Skip to content

Commit 47a5e96

Browse files
danny-aviladanny-avila
authored
🧠 feat: Memories + Documentation Guidelines (#322)
* feat: memories update * docs: Add LibreChat documentation rules and configuration update guidelines * docs: Update Node.js version requirements across documentation - Revised Node.js prerequisites to specify v20.19.0+ (or ^22.12.0 or >= 23.0.0) in README.md, get_started.mdx, npm.mdx, docker_linux.mdx, and nginx.mdx for clarity and compatibility with openid-client v6. * docs: Add DEBUG_OPENID_REQUESTS environment variable for enhanced OpenID debugging - Introduced a new environment variable, DEBUG_OPENID_REQUESTS, to enable detailed logging of OpenID request headers for better troubleshooting. - Updated documentation to include troubleshooting steps for OpenID Connect, emphasizing the use of the new logging feature. * docs: Update changelog dates for versions v1.2.6 and v1.2.7 * docs: Enhance memory configuration documentation - Updated the memory configuration section to clarify the default value for the personalize option. - Changed the provider name from "openai" to "openAI" for consistency. - Added notes regarding the provider field and valid model parameters. - Improved examples for memory agent configuration.
1 parent 6b471cf commit 47a5e96

File tree

18 files changed

+614
-9
lines changed

18 files changed

+614
-9
lines changed

‎.cursor/rules/librechat-documentation.mdc

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: true
5+
---
6+
# LibreChat Documentation Rules
7+
8+
## Config Version Updates
9+
10+
When updating the LibreChat config version (e.g., from v1.2.6 to v1.2.7), follow these steps:
11+
12+
### 1. Create Changelog Files
13+
14+
#### Main Changelog File
15+
Create: `pages/changelog/config_v{VERSION}.mdx`
16+
17+
Template:
18+
```mdx
19+
---
20+
date: YYYY/MM/DD
21+
title: ⚙️ Config v{VERSION}
22+
---
23+
24+
import { ChangelogHeader } from '@/components/changelog/ChangelogHeader'
25+
import Content from '@/components/changelog/content/config_v{VERSION}.mdx'
26+
27+
<ChangelogHeader />
28+
29+
---
30+
31+
<Content />
32+
```
33+
34+
#### Content File
35+
Create: `components/changelog/content/config_v{VERSION}.mdx`
36+
37+
Format:
38+
- Use bullet points starting with `-`
39+
- Group related changes together
40+
- Include links to detailed documentation using `[Feature Name](/docs/configuration/librechat_yaml/object_structure/{feature})`
41+
- Describe what was added/changed and its purpose
42+
- Keep descriptions concise but informative
43+
44+
Example:
45+
```mdx
46+
- Added `memory` configuration to control memory functionality for conversations
47+
- Configure memory persistence and personalization settings
48+
- Set token limits and message window sizes for memory context
49+
- Configure agents for memory processing with provider-specific settings
50+
- Supports both predefined agents (by ID) and custom agent configurations
51+
- See [Memory Configuration](/docs/configuration/librechat_yaml/object_structure/memory) for details
52+
```
53+
54+
### 2. Create Object Structure Documentation
55+
56+
For new root-level configurations, create: `pages/docs/configuration/librechat_yaml/object_structure/{feature}.mdx`
57+
58+
Structure:
59+
1. **Title**: `# {Feature} Configuration`
60+
2. **Overview**: Brief description of the feature
61+
3. **Example**: Complete YAML example showing all options
62+
4. **Field Documentation**: Use `<OptionTable>` components for each field
63+
5. **Subsections**: For complex nested objects
64+
6. **Notes**: Important considerations at the end
65+
66+
### 3. Update Navigation
67+
68+
Add the new feature to: `pages/docs/configuration/librechat_yaml/object_structure/_meta.ts`
69+
70+
Insert alphabetically or logically within the structure:
71+
```ts
72+
export default {
73+
config: 'Root Settings',
74+
file_config: 'File Config',
75+
interface: 'Interface (UI)',
76+
// ... other entries
77+
memory: 'Memory', // Add new entry
78+
// ... remaining entries
79+
}
80+
```
81+
82+
### 4. Update Main Config Documentation
83+
84+
In `pages/docs/configuration/librechat_yaml/object_structure/config.mdx`:
85+
86+
1. Update the version example:
87+
```yaml
88+
['version', 'String', 'Specifies the version of the configuration file.', 'version: 1.2.7' ],
89+
```
90+
91+
2. Add the new configuration section (insert alphabetically or logically):
92+
```mdx
93+
## memory
94+
95+
**Key:**
96+
<OptionTable
97+
options={[
98+
['memory', 'Object', 'Brief description of the feature.', ''],
99+
]}
100+
/>
101+
102+
**Subkeys:**
103+
<OptionTable
104+
options={[
105+
['field1', 'Type', 'Description', ''],
106+
['field2', 'Type', 'Description', ''],
107+
// ... other fields
108+
]}
109+
/>
110+
111+
see: [Memory Object Structure](/docs/configuration/librechat_yaml/object_structure/memory)
112+
```
113+
114+
## Documentation Standards
115+
116+
### OptionTable Usage
117+
```mdx
118+
<OptionTable
119+
options={[
120+
['fieldName', 'Type', 'Description of what the field does.', 'example: value'],
121+
]}
122+
/>
123+
```
124+
125+
### YAML Examples
126+
- Use `filename` attribute for code blocks: ` ```yaml filename="memory" `
127+
- Show realistic, working examples
128+
- Include comments only when necessary for clarity
129+
130+
### Field Descriptions
131+
- Be precise about default values
132+
- Explain the impact of different settings
133+
- Note any relationships between fields
134+
- Mention when fields are required vs optional
135+
136+
### Special Considerations
137+
- For boolean fields that give users control, clarify WHO gets the control (admin vs end-user)
138+
- For fields that replace default behavior, explicitly state this
139+
- For union types, show examples of each variant
140+
- For nested objects, create subsections with their own OptionTables
141+
142+
## Version Numbering
143+
- Config versions follow semantic versioning: v{MAJOR}.{MINOR}.{PATCH}
144+
- Adding new root-level configurations typically warrants a minor version bump
145+
- Breaking changes require a major version bump
146+
- Bug fixes or minor adjustments use patch versions

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Based on [Nextra](https://nextra.site/)
44

55
## Local Development
66

7-
Pre-requisites: Node.js 18+, pnpm 9+
7+
Pre-requisites: Node.js v20.19.0+ (or ^22.12.0 or >= 23.0.0), pnpm 9+
88

99
1. Optional: Create env based on [.env.template](./.env.template)
1010
2. Run `pnpm i` to install the dependencies.

‎components/changelog/content/config_v1.2.7.mdx

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
- Added `memory` configuration to control memory functionality for conversations
2+
- Configure memory persistence and personalization settings
3+
- Set token limits and message window sizes for memory context
4+
- Configure agents for memory processing with provider-specific settings
5+
- Supports both predefined agents (by ID) and custom agent configurations
6+
- See [Memory Configuration](/docs/configuration/librechat_yaml/object_structure/memory) for details
7+
8+
- Added memory-related capabilities to conversation processing
9+
- Enables conversation memory and personalization features
10+
- Configurable token limits and context window management
11+
- Integration with agent-based memory processing
12+
- Defaults to personalization enabled with a 5-message window size

‎pages/changelog/config_v1.2.6.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
date: 2025/5/7
2+
date: 2025/5/8
33
title: ⚙️ Config v1.2.6
44
---
55

‎pages/changelog/config_v1.2.7.mdx

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
date: 2025/6/9
3+
title: ⚙️ Config v1.2.7
4+
---
5+
6+
import { ChangelogHeader } from '@/components/changelog/ChangelogHeader'
7+
import Content from '@/components/changelog/content/config_v1.2.7.mdx'
8+
9+
<ChangelogHeader />
10+
11+
---
12+
13+
<Content />

‎pages/docs/configuration/authentication/OAuth2-OIDC/index.mdx

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,14 @@ This section will cover how to configure OAuth2 and OpenID Connect with LibreCha
2727
- [AWS Cognito](/docs/configuration/authentication/OAuth2-OIDC/aws)
2828
- [Azure Entra/AD](/docs/configuration/authentication/OAuth2-OIDC/azure)
2929
- [Keycloak](/docs/configuration/authentication/OAuth2-OIDC/keycloak)
30-
- [Re-use OpenID Tokens for Login Session](/docs/configuration/authentication/OAuth2-OIDC/token-reuse)
30+
- [Re-use OpenID Tokens for Login Session](/docs/configuration/authentication/OAuth2-OIDC/token-reuse)
31+
32+
## Troubleshooting OpenID Connect
33+
34+
If you encounter issues with OpenID Connect authentication:
35+
36+
1. **Enable Header Debug Logging**: Set `DEBUG_OPENID_REQUESTS=true` in your environment variables to log request headers in addition to URLs (with sensitive data masked). Note: Request URLs are always logged at debug level
37+
2. **Check Redirect URIs**: Ensure your callback URL matches exactly between your provider and LibreChat configuration
38+
3. **Verify Scopes**: Make sure all required scopes are properly configured
39+
4. **Review Provider Logs**: Check your identity provider's logs for authentication errors
40+
5. **Validate Tokens**: Ensure your provider is issuing valid tokens with the expected claims

‎pages/docs/configuration/authentication/OAuth2-OIDC/token-reuse.mdx

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,4 +100,5 @@ If you encounter issues with token reuse:
100100
2. Check that admin consent has been granted
101101
3. Ensure the API permissions are correctly set up
102102
4. Verify the token cache is working as expected
103-
5. Check the application logs for any authentication errors
103+
5. Check the application logs for any authentication errors
104+
6. Enable detailed OpenID request header logging by setting `DEBUG_OPENID_REQUESTS=true` in your environment variables to see request headers in addition to URLs (with sensitive data masked)

‎pages/docs/configuration/dotenv.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1012,6 +1012,7 @@ For more information:
10121012
['OPENID_IMAGE_URL', 'string', 'The URL of the OpenID login button image.','OPENID_IMAGE_URL='],
10131013
['OPENID_USE_END_SESSION_ENDPOINT', 'string', 'Whether to use the Issuer End Session Endpoint as a Logout Redirect','OPENID_USE_END_SESSION_ENDPOINT=TRUE'],
10141014
['OPENID_AUTO_REDIRECT', 'boolean', 'Whether to automatically redirect to the OpenID provider.','OPENID_AUTO_REDIRECT=true'],
1015+
['DEBUG_OPENID_REQUESTS', 'boolean', 'Enable detailed logging of OpenID request headers. When disabled (default), only request URLs are logged at debug level. When enabled, request headers are also logged (with sensitive data masked) for deeper debugging of authentication issues.','DEBUG_OPENID_REQUESTS=false'],
10151016
]}
10161017
/>
10171018

‎pages/docs/configuration/librechat_yaml/object_structure/_meta.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ export default {
66
model_specs: 'Model Specs',
77
registration: 'Registration',
88
balance: 'Balance',
9+
memory: 'Memory',
910
agents: 'Agents',
1011
mcp_servers: 'MCP Servers',
1112
aws_bedrock: 'AWS Bedrock',

‎pages/docs/configuration/librechat_yaml/object_structure/config.mdx

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
<OptionTable
99
options={[
10-
['version', 'String', 'Specifies the version of the configuration file.', 'version: 1.0.8' ],
10+
['version', 'String', 'Specifies the version of the configuration file.', 'version: 1.2.7' ],
1111
]}
1212
/>
1313

@@ -258,6 +258,29 @@ see also:
258258
- [alloweddomains](/docs/configuration/librechat_yaml/object_structure/registration#alloweddomains),
259259
- [Registration Object Structure](/docs/configuration/librechat_yaml/object_structure/registration)
260260
261+
## memory
262+
263+
**Key:**
264+
<OptionTable
265+
options={[
266+
['memory', 'Object', 'Configures conversation memory and personalization features for the application.', ''],
267+
]}
268+
/>
269+
270+
**Subkeys:**
271+
<OptionTable
272+
options={[
273+
['disabled', 'Boolean', 'Disables memory functionality when set to true.', ''],
274+
['validKeys', 'Array of Strings', 'Specifies which keys are valid for memory storage.', ''],
275+
['tokenLimit', 'Number', 'Sets the maximum number of tokens for memory storage and processing.', ''],
276+
['personalize', 'Boolean', 'Enables or disables personalization features.', ''],
277+
['messageWindowSize', 'Number', 'Specifies the number of recent messages to include in memory context.', ''],
278+
['agent', 'Object | Union', 'Configures the agent responsible for memory processing.', ''],
279+
]}
280+
/>
281+
282+
see: [Memory Object Structure](/docs/configuration/librechat_yaml/object_structure/memory)
283+
261284
## actions
262285
263286
**Key:**

0 commit comments

Comments
 (0)