🧠 feat: Memories + Documentation Guidelines

.cursor/rules/librechat-documentation.mdc

@@ -0,0 +1,146 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# LibreChat Documentation Rules
+
+## Config Version Updates
+
+When updating the LibreChat config version (e.g., from v1.2.6 to v1.2.7), follow these steps:
+
+### 1. Create Changelog Files
+
+#### Main Changelog File
+Create: `pages/changelog/config_v{VERSION}.mdx`
+
+Template:
+```mdx
+---
+date: YYYY/MM/DD
+title: ⚙️ Config v{VERSION}
+---
+
+import { ChangelogHeader } from '@/components/changelog/ChangelogHeader'
+import Content from '@/components/changelog/content/config_v{VERSION}.mdx'
+
+<ChangelogHeader />
+
+---
+
+<Content />
+```
+
+#### Content File
+Create: `components/changelog/content/config_v{VERSION}.mdx`
+
+Format:
+- Use bullet points starting with `-`
+- Group related changes together
+- Include links to detailed documentation using `[Feature Name](/docs/configuration/librechat_yaml/object_structure/{feature})`
+- Describe what was added/changed and its purpose
+- Keep descriptions concise but informative
+
+Example:
+```mdx
+- Added `memory` configuration to control memory functionality for conversations
+  - Configure memory persistence and personalization settings
+  - Set token limits and message window sizes for memory context
+  - Configure agents for memory processing with provider-specific settings
+  - Supports both predefined agents (by ID) and custom agent configurations
+  - See [Memory Configuration](/docs/configuration/librechat_yaml/object_structure/memory) for details
+```
+
+### 2. Create Object Structure Documentation
+
+For new root-level configurations, create: `pages/docs/configuration/librechat_yaml/object_structure/{feature}.mdx`
+
+Structure:
+1. **Title**: `# {Feature} Configuration`
+2. **Overview**: Brief description of the feature
+3. **Example**: Complete YAML example showing all options
+4. **Field Documentation**: Use `<OptionTable>` components for each field
+5. **Subsections**: For complex nested objects
+6. **Notes**: Important considerations at the end
+
+### 3. Update Navigation
+
+Add the new feature to: `pages/docs/configuration/librechat_yaml/object_structure/_meta.ts`
+
+Insert alphabetically or logically within the structure:
+```ts
+export default {
+  config: 'Root Settings',
+  file_config: 'File Config',
+  interface: 'Interface (UI)',
+  // ... other entries
+  memory: 'Memory',  // Add new entry
+  // ... remaining entries
+}
+```
+
+### 4. Update Main Config Documentation
+
+In `pages/docs/configuration/librechat_yaml/object_structure/config.mdx`:
+
+1. Update the version example:
+   ```yaml
+   ['version', 'String', 'Specifies the version of the configuration file.', 'version: 1.2.7' ],
+   ```
+
+2. Add the new configuration section (insert alphabetically or logically):
+   ```mdx
+   ## memory
+
+   **Key:**
+   <OptionTable
+     options={[
+       ['memory', 'Object', 'Brief description of the feature.', ''],
+     ]}
+   />
+
+   **Subkeys:**
+   <OptionTable
+     options={[
+       ['field1', 'Type', 'Description', ''],
+       ['field2', 'Type', 'Description', ''],
+       // ... other fields
+     ]}
+   />
+
+   see: [Memory Object Structure](/docs/configuration/librechat_yaml/object_structure/memory)
+   ```
+
+## Documentation Standards
+
+### OptionTable Usage
+```mdx
+<OptionTable
+  options={[
+    ['fieldName', 'Type', 'Description of what the field does.', 'example: value'],
+  ]}
+/>
+```
+
+### YAML Examples
+- Use `filename` attribute for code blocks: ` ```yaml filename="memory" `
+- Show realistic, working examples
+- Include comments only when necessary for clarity
+
+### Field Descriptions
+- Be precise about default values
+- Explain the impact of different settings
+- Note any relationships between fields
+- Mention when fields are required vs optional
+
+### Special Considerations
+- For boolean fields that give users control, clarify WHO gets the control (admin vs end-user)
+- For fields that replace default behavior, explicitly state this
+- For union types, show examples of each variant
+- For nested objects, create subsections with their own OptionTables
+
+## Version Numbering
+- Config versions follow semantic versioning: v{MAJOR}.{MINOR}.{PATCH}
+- Adding new root-level configurations typically warrants a minor version bump
+- Breaking changes require a major version bump
+- Bug fixes or minor adjustments use patch versions 

README.md

@@ -4,7 +4,7 @@ Based on [Nextra](https://nextra.site/)
 
 ## Local Development
 
-Pre-requisites: Node.js 18+, pnpm 9+
+Pre-requisites: Node.js v20.19.0+ (or ^22.12.0 or >= 23.0.0), pnpm 9+
 
 1. Optional: Create env based on [.env.template](./.env.template)
 2. Run `pnpm i` to install the dependencies.

components/changelog/content/config_v1.2.7.mdx

@@ -0,0 +1,12 @@
+- Added `memory` configuration to control memory functionality for conversations
+  - Configure memory persistence and personalization settings
+  - Set token limits and message window sizes for memory context
+  - Configure agents for memory processing with provider-specific settings
+  - Supports both predefined agents (by ID) and custom agent configurations
+  - See [Memory Configuration](/docs/configuration/librechat_yaml/object_structure/memory) for details
+
+- Added memory-related capabilities to conversation processing
+  - Enables conversation memory and personalization features
+  - Configurable token limits and context window management
+  - Integration with agent-based memory processing
+  - Defaults to personalization enabled with a 5-message window size 

pages/changelog/config_v1.2.6.mdx

@@ -1,5 +1,5 @@
 ---
-date: 2025/5/7
+date: 2025/5/8
 title: ⚙️ Config v1.2.6
 ---
 

pages/changelog/config_v1.2.7.mdx

@@ -0,0 +1,13 @@
+---
+date: 2025/6/9
+title: ⚙️ Config v1.2.7
+---
+
+import { ChangelogHeader } from '@/components/changelog/ChangelogHeader'
+import Content from '@/components/changelog/content/config_v1.2.7.mdx'
+
+<ChangelogHeader />
+
+---
+
+<Content /> 

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

@@ -27,4 +27,14 @@ This section will cover how to configure OAuth2 and OpenID Connect with LibreCha
   - [AWS Cognito](/docs/configuration/authentication/OAuth2-OIDC/aws)
   - [Azure Entra/AD](/docs/configuration/authentication/OAuth2-OIDC/azure)
   - [Keycloak](/docs/configuration/authentication/OAuth2-OIDC/keycloak)
-  - [Re-use OpenID Tokens for Login Session](/docs/configuration/authentication/OAuth2-OIDC/token-reuse)
+  - [Re-use OpenID Tokens for Login Session](/docs/configuration/authentication/OAuth2-OIDC/token-reuse)
+
+## Troubleshooting OpenID Connect
+
+If you encounter issues with OpenID Connect authentication:
+
+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
+2. **Check Redirect URIs**: Ensure your callback URL matches exactly between your provider and LibreChat configuration
+3. **Verify Scopes**: Make sure all required scopes are properly configured
+4. **Review Provider Logs**: Check your identity provider's logs for authentication errors
+5. **Validate Tokens**: Ensure your provider is issuing valid tokens with the expected claims

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

@@ -100,4 +100,5 @@ If you encounter issues with token reuse:
 2. Check that admin consent has been granted
 3. Ensure the API permissions are correctly set up
 4. Verify the token cache is working as expected
-5. Check the application logs for any authentication errors 
+5. Check the application logs for any authentication errors
+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

@@ -1012,6 +1012,7 @@ For more information:
     ['OPENID_IMAGE_URL', 'string', 'The URL of the OpenID login button image.','OPENID_IMAGE_URL='],
     ['OPENID_USE_END_SESSION_ENDPOINT', 'string', 'Whether to use the Issuer End Session Endpoint as a Logout Redirect','OPENID_USE_END_SESSION_ENDPOINT=TRUE'],
     ['OPENID_AUTO_REDIRECT', 'boolean', 'Whether to automatically redirect to the OpenID provider.','OPENID_AUTO_REDIRECT=true'],
+    ['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'],
   ]}
 />
 

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

@@ -6,6 +6,7 @@ export default {
   model_specs: 'Model Specs',
   registration: 'Registration',
   balance: 'Balance',
+  memory: 'Memory',
   agents: 'Agents',
   mcp_servers: 'MCP Servers',
   aws_bedrock: 'AWS Bedrock',

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

@@ -7,7 +7,7 @@
 
 <OptionTable
   options={[
-    ['version', 'String', 'Specifies the version of the configuration file.', 'version: 1.0.8' ],
+    ['version', 'String', 'Specifies the version of the configuration file.', 'version: 1.2.7' ],
   ]}
 />
 
@@ -258,6 +258,29 @@ see also:
 - [alloweddomains](/docs/configuration/librechat_yaml/object_structure/registration#alloweddomains),
 - [Registration Object Structure](/docs/configuration/librechat_yaml/object_structure/registration)
 
+## memory
+
+**Key:**
+<OptionTable
+  options={[
+    ['memory', 'Object', 'Configures conversation memory and personalization features for the application.', ''],
+  ]}
+/>
+
+**Subkeys:**
+<OptionTable
+  options={[
+    ['disabled', 'Boolean', 'Disables memory functionality when set to true.', ''],
+    ['validKeys', 'Array of Strings', 'Specifies which keys are valid for memory storage.', ''],
+    ['tokenLimit', 'Number', 'Sets the maximum number of tokens for memory storage and processing.', ''],
+    ['personalize', 'Boolean', 'Enables or disables personalization features.', ''],
+    ['messageWindowSize', 'Number', 'Specifies the number of recent messages to include in memory context.', ''],
+    ['agent', 'Object | Union', 'Configures the agent responsible for memory processing.', ''],
+  ]}
+/>
+
+see: [Memory Object Structure](/docs/configuration/librechat_yaml/object_structure/memory)
+
 ## actions
 
 **Key:**