-# Redis Agent Memory Server
+# Agent Memory Server
-A memory layer for AI agents.
+Session Memory and Long-Term Memory for AI Agents.
- **[Documentation](https://redis.github.io/agent-memory-server/)** β’ **[GitHub](https://github.com/redis/agent-memory-server)** β’ **[Docker](https://hub.docker.com/r/redislabs/agent-memory-server)**
+ **[Documentation](https://ai.redis.io/agent-memory/)** β’ **[GitHub](https://github.com/redis/agent-memory-server)** β’ **[Docker](https://hub.docker.com/r/redislabs/agent-memory-server)**
@@ -144,7 +144,7 @@ results = await client.search_long_term_memory(
)
```
-> **Note**: While you can call client functions directly as shown above, using **MCP or SDK-provided tool calls** is recommended for AI agents as it provides better integration, automatic context management, and follows AI-native patterns. For the best performance, you can add messages to working memory and allow the server to extract memories in the background. See **[Memory Integration Patterns](https://redis.github.io/agent-memory-server/memory-integration-patterns/)** for guidance on when to use each approach.
+> **Note**: While you can call client functions directly as shown above, using **MCP or SDK-provided tool calls** is recommended for AI agents as it provides better integration, automatic context management, and follows AI-native patterns. For the best performance, you can add messages to working memory and allow the server to extract memories in the background. See **[Memory Integration Patterns](https://ai.redis.io/agent-memory/user_guide/how_to_guides/integration_patterns/)** for guidance on when to use each approach.
#### LangChain Integration
@@ -244,24 +244,24 @@ export EMBEDDING_MODEL=ollama/nomic-embed-text
export REDISVL_VECTOR_DIMENSIONS=768 # Required for Ollama
```
-See **[LLM Providers](https://redis.github.io/agent-memory-server/llm-providers/)** for complete configuration options.
+See **[LLM Providers](https://ai.redis.io/agent-memory/user_guide/how_to_guides/llm_providers/)** for complete configuration options.
## Documentation
-π **[Full Documentation](https://redis.github.io/agent-memory-server/)** - Complete guides, API reference, and examples
+π **[Full Documentation](https://ai.redis.io/agent-memory/)** - Complete guides, API reference, and examples
### Key Documentation Sections:
-- **[Quick Start Guide](https://redis.github.io/agent-memory-server/quick-start/)** - Get up and running in minutes
-- **[Python SDK](https://redis.github.io/agent-memory-server/python-sdk/)** - Complete SDK reference with examples
-- **[LangChain Integration](https://redis.github.io/agent-memory-server/langchain-integration/)** - Automatic tool conversion for LangChain
-- **[LLM Providers](https://redis.github.io/agent-memory-server/llm-providers/)** - Configure OpenAI, Anthropic, AWS Bedrock, Ollama, and more
-- **[Embedding Providers](https://redis.github.io/agent-memory-server/embedding-providers/)** - Configure embedding models for semantic search
-- **[Custom Memory Vector Databases](https://redis.github.io/agent-memory-server/custom-memory-vector-db/)** - Configure custom memory vector databases
-- **[Authentication](https://redis.github.io/agent-memory-server/authentication/)** - OAuth2/JWT setup for production
-- **[Memory Types](https://redis.github.io/agent-memory-server/long-term-memory/#memory-types)** - Understanding semantic vs episodic memory
-- **[API Reference](https://redis.github.io/agent-memory-server/api/)** - REST API endpoints
-- **[MCP Protocol](https://redis.github.io/agent-memory-server/mcp/)** - Model Context Protocol integration
+- **[Quick Start Guide](https://ai.redis.io/agent-memory/user_guide/01_quick_start/)** - Get up and running in minutes
+- **[Python SDK](https://ai.redis.io/agent-memory/api/python_sdk/)** - Complete SDK reference with examples
+- **[LangChain Integration](https://ai.redis.io/agent-memory/examples/langchain/)** - Automatic tool conversion for LangChain
+- **[LLM Providers](https://ai.redis.io/agent-memory/user_guide/how_to_guides/llm_providers/)** - Configure OpenAI, Anthropic, AWS Bedrock, Ollama, and more
+- **[Embedding Providers](https://ai.redis.io/agent-memory/user_guide/how_to_guides/embedding_providers/)** - Configure embedding models for semantic search
+- **[Custom Memory Vector Databases](https://ai.redis.io/agent-memory/user_guide/how_to_guides/custom_vector_db/)** - Configure custom memory vector databases
+- **[Authentication](https://ai.redis.io/agent-memory/user_guide/how_to_guides/authentication/)** - OAuth2/JWT setup for production
+- **[Memory Types](https://ai.redis.io/agent-memory/concepts/long_term_memory/#memory-types)** - Understanding semantic vs episodic memory
+- **[API Reference](https://ai.redis.io/agent-memory/api/rest/)** - REST API endpoints
+- **[MCP Protocol](https://ai.redis.io/agent-memory/api/mcp/)** - Model Context Protocol integration
## Architecture
diff --git a/docs/README.md b/docs/README.md
deleted file mode 100644
index b2df1c31..00000000
--- a/docs/README.md
+++ /dev/null
@@ -1,87 +0,0 @@
-# Redis Agent Memory Server Documentation
-
-Comprehensive documentation for building AI agents with persistent, intelligent memory.
-
-## π Getting Started
-
-**New to Redis Agent Memory Server?** Start here:
-
-- **[Quick Start Guide](quick-start.md)** - Get up and running in 5 minutes
-- **[Getting Started](getting-started.md)** - Complete installation and setup guide
-- **[Use Cases](use-cases.md)** - Real-world examples and implementation patterns
-
-## π§ Core Concepts
-
-Understand the fundamentals:
-
-- **[Memory Types](long-term-memory.md#memory-types)** - Working vs Long-term memory explained with examples
-- **[Authentication](authentication.md)** - OAuth2/JWT, token-based, and development setup
-- **[Configuration](configuration.md)** - Environment variables, settings, and deployment options
-
-## β¨ Advanced Features
-
-Powerful features for intelligent memory management:
-
-- **[Query Optimization](query-optimization.md)** - AI-powered query refinement for better search accuracy
-- **[Contextual Grounding](contextual-grounding.md)** - Resolve pronouns and references in extracted memories
-- **[Memory Editing](memory-lifecycle.md#memory-editing)** - Update, correct, and enrich existing memories
-- **[Recency Boost](recency-boost.md)** - Time-aware memory ranking and intelligent scoring
-- **[Custom Memory Vector Databases](custom-memory-vector-db.md)** - Custom memory vector database implementations
-
-## π API Reference
-
-Choose your integration approach:
-
-- **[REST API](api.md)** - HTTP endpoints with complete examples and curl commands
-- **[MCP Server](mcp.md)** - Model Context Protocol tools for AI agents (Claude, etc.)
-- **[CLI](cli.md)** - Command-line interface for server management and administration
-
-## π οΈ Development
-
-For contributors and advanced users:
-
-- **[Development Guide](development.md)** - Local setup, testing, and contributing guidelines
-- **[System Architecture](../diagram.png)** - Visual overview of system components
-
-## π Additional Resources
-
-- **[Manual OAuth Testing](../manual_oauth_qa/README.md)** - Comprehensive Auth0 testing guide
-- **[Main Project README](../README.md)** - Project overview and quick reference
-- **[Examples Directory](../examples/)** - Complete working examples and demos
-
-## Navigation Tips
-
-### By Experience Level
-
-**π New Users**: Quick Start β Use Cases β Memory Types
-**π§ Developers**: Getting Started β REST API β Configuration
-**π€ AI Agent Builders**: MCP Server β Memory Editing β Query Optimization
-**ποΈ System Admins**: Authentication β Configuration β CLI
-
-### By Use Case
-
-**Building a chatbot?** β Quick Start β Memory Types β MCP Server
-**Adding memory to existing app?** β REST API β Authentication β Configuration
-**Research/content assistant?** β Use Cases β Query Optimization β Contextual Grounding
-**Production deployment?** β Authentication β Custom Memory Vector Databases β Development
-
-### By Interface Preference
-
-**REST API users** β [API Documentation](api.md) β [Authentication](authentication.md)
-**MCP/Claude users** β [MCP Server](mcp.md) β [Memory Editing](memory-lifecycle.md#memory-editing)
-**CLI management** β [CLI Reference](cli.md) β [Configuration](configuration.md)
-
-## Feature Cross-Reference
-
-| Feature | REST API | MCP Server | CLI | Documentation |
-|---------|----------|------------|-----|---------------|
-| **Memory Search** (semantic, keyword, hybrid) | β `/v1/long-term-memory/search` | β `search_long_term_memory` | β `agent-memory search` | [REST API](api.md), [MCP](mcp.md), [CLI](cli.md) |
-| **Memory Editing** | β `PATCH /v1/long-term-memory/{id}` | β `edit_long_term_memory` | β | [Memory Editing](memory-lifecycle.md#memory-editing) |
-| **Query Optimization** | β `optimize_query` param | β `optimize_query` param | β | [Query Optimization](query-optimization.md) |
-| **Recency Boost** | β Default enabled | β Available | β | [Recency Boost](recency-boost.md) |
-| **Authentication** | β JWT/Token | β Inherited | β Token management | [Authentication](authentication.md) |
-| **Background Tasks** | β Automatic | β Automatic | β Worker management | [Configuration](configuration.md) |
-
----
-
-**Need help?** Check the [Quick Start Guide](quick-start.md) or explore [real-world examples](use-cases.md) to see Redis Agent Memory Server in action! π§ β¨
diff --git a/docs/advanced-topics-index.md b/docs/advanced-topics-index.md
deleted file mode 100644
index 992f00b3..00000000
--- a/docs/advanced-topics-index.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# Advanced Topics
-
-Optimize memory search, tune ranking algorithms, and configure advanced memory vector database features.
-
-
-
-## Interface Comparison
-
-| Interface | Best For | Authentication |
-|-----------|----------|----------------|
-| REST API | Applications, backends, custom integrations | OAuth2/JWT or token |
-| MCP Server | Claude Desktop, MCP-compatible AI agents | Environment config |
-| CLI | Server administration, development | Local access |
-| Python SDK | Python applications with LLM tool integration | Token or OAuth2 |
-| TypeScript SDK | Node.js, browser, and TypeScript applications | Token or OAuth2 |
-| Java SDK | JVM-based applications | Token or OAuth2 |
-
-## Interactive API Docs
-
-When running the server locally, visit `http://localhost:8000/docs` for interactive Swagger documentation where you can try endpoints directly.
diff --git a/docs/api/cli.md b/docs/api/cli.md
new file mode 100644
index 00000000..1c14ccfc
--- /dev/null
+++ b/docs/api/cli.md
@@ -0,0 +1,437 @@
+# Command Line Interface
+
+The `agent-memory-server` package provides a command-line interface (CLI) called `agent-memory` for running the REST API and MCP servers, scheduling and processing background tasks, running migrations, and managing authentication tokens.
+
+## Installation
+
+The `agent-memory` command is included when you install the server package.
+
+```bash
+pip install agent-memory-server
+```
+
+Verify the installation by running:
+
+```bash
+agent-memory version
+```
+
+## Getting help
+
+All commands and command groups support the `--help` flag.
+
+| Flag | Description |
+|---|---|
+| `--help` | Display usage information for the command or command group |
+
+**Examples**
+
+```bash
+agent-memory --help # Top-level help
+agent-memory api --help # Help for a single command
+agent-memory token --help # Help for a command group
+```
+
+## `version`
+
+Display the installed version of `agent-memory-server`.
+
+**Syntax**
+
+```bash
+agent-memory version
+```
+
+---
+
+## `api`
+
+Start the REST API server.
+
+**Syntax**
+
+```bash
+agent-memory api [OPTIONS]
+```
+
+**Options**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `--port` | integer | `settings.port` (usually `8000`) | Port to run the server on |
+| `--host` | string | `0.0.0.0` | Host to bind the server to |
+| `--reload` | flag | disabled | Enable auto-reload for development |
+| `--task-backend` | `asyncio` \| `docket` | `docket` | Background task backend. `docket` requires a running `agent-memory task-worker`; `asyncio` runs tasks inline in the API process. |
+| `--no-worker` *(deprecated)* | flag | β | Backwards-compatible alias for `--task-backend=asyncio`. Prefer `--task-backend`. |
+
+**Examples**
+
+```bash
+# Development mode (no separate worker needed)
+agent-memory api --port 8080 --reload --task-backend asyncio
+
+# Production mode (default Docket backend; requires a separate worker)
+agent-memory api --port 8080
+```
+
+!!! warning "Limitations of `--task-backend=asyncio`"
+
+ The `asyncio` backend is suitable for development and simple use cases, but has important limitations:
+
+ - **Periodic tasks don't run**: Scheduled maintenance tasks like memory compaction, periodic forgetting, and summary view refresh only execute when a Docket worker is running. These tasks use Docket's `Perpetual` scheduler.
+ - **No task persistence**: If the server restarts, pending background tasks are lost.
+ - **No distributed processing**: All tasks run in the API process; you cannot scale workers independently.
+
+ For production deployments, use the default `docket` backend with a separate `agent-memory task-worker` process.
+
+---
+
+## `mcp`
+
+Start the Model Context Protocol (MCP) server.
+
+**Syntax**
+
+```bash
+agent-memory mcp [OPTIONS]
+```
+
+**Options**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `--port` | integer | `settings.mcp_port` (usually `9000`) | Port to run the MCP server on |
+| `--mode` | `stdio` \| `sse` \| `streamable-http` | `stdio` | MCP transport mode |
+| `--task-backend` | `asyncio` \| `docket` | `asyncio` | Background task backend. `docket` requires a running `agent-memory task-worker`. |
+
+**Examples**
+
+```bash
+# Stdio mode (recommended for Claude Desktop)
+agent-memory mcp
+
+# SSE mode for development (no separate worker needed)
+agent-memory mcp --mode sse --port 9001
+
+# Streamable HTTP mode for network deployments (e.g. Kubernetes)
+agent-memory mcp --mode streamable-http --port 9000
+
+# SSE mode for production (requires a separate worker process)
+agent-memory mcp --mode sse --port 9001 --task-backend docket
+```
+
+!!! note "Choosing a mode"
+
+ Stdio mode is designed for tools like Claude Desktop and uses the asyncio backend by default (no worker required). Streamable HTTP mode is suited for deploying the MCP server as a network service where HTTP clients (like Claude Code) connect over the network. Use `--task-backend docket` if you want MCP to enqueue background work into a shared Docket worker.
+
+---
+
+## `task-worker`
+
+Start a Docket worker to process background tasks from the queue. The worker uses the Docket name configured in settings.
+
+**Syntax**
+
+```bash
+agent-memory task-worker [OPTIONS]
+```
+
+**Options**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `--concurrency` | integer | `10` | Number of tasks to process concurrently |
+| `--redelivery-timeout` | integer | `2 Γ llm_task_timeout_minutes` (`600` seconds with default config) | Seconds to wait before a task is redelivered to another worker if the current worker fails or times out |
+
+**Example**
+
+```bash
+agent-memory task-worker --concurrency 5 --redelivery-timeout 600
+```
+
+---
+
+## `schedule-task`
+
+Schedule a background task to be processed by a Docket worker.
+
+**Syntax**
+
+```bash
+agent-memory schedule-task [OPTIONS]
+```
+
+**Arguments**
+
+| Argument | Description |
+|---|---|
+| `TASK_PATH` | Python import path to the task function (e.g. `agent_memory_server.long_term_memory.compact_long_term_memories`) |
+
+**Options**
+
+| Option | Description |
+|---|---|
+| `-a`, `--args TEXT` | Arguments to pass to the task in `key=value` format. Repeatable. Values are auto-converted to bool, integer, or float when possible; otherwise they remain strings. |
+
+**Example**
+
+```bash
+agent-memory schedule-task "agent_memory_server.long_term_memory.compact_long_term_memories" \
+ -a limit=500 \
+ -a namespace=my_namespace \
+ -a compact_semantic_duplicates=false
+```
+
+---
+
+## `rebuild_index`
+
+Rebuild the Redis search index.
+
+**Syntax**
+
+```bash
+agent-memory rebuild_index
+```
+
+---
+
+## `migrate-memories`
+
+Run the built-in long-term memory migrations. Safe to rerun. Use this after upgrading if you need to backfill fields on existing memory records.
+
+**Syntax**
+
+```bash
+agent-memory migrate-memories
+```
+
+---
+
+## `migrate-working-memory`
+
+Migrate legacy `working_memory:*` string keys to Redis JSON. Use this if you are upgrading from an older working-memory format or if you want to remove deprecated legacy `sessions` / `sessions:*` sorted sets from the old session-listing path.
+
+**Syntax**
+
+```bash
+agent-memory migrate-working-memory [OPTIONS]
+```
+
+**Options**
+
+| Option | Description |
+|---|---|
+| `--dry-run` | Report what would be migrated without making any changes |
+
+**Examples**
+
+```bash
+# Inspect what would change
+agent-memory migrate-working-memory --dry-run
+
+# Run the migration
+agent-memory migrate-working-memory
+```
+
+---
+
+## `token`
+
+Manage authentication tokens for token-based authentication. This command group provides subcommands for creating, listing, viewing, and removing API tokens.
+
+**Syntax**
+
+```bash
+agent-memory token [OPTIONS]
+```
+
+**Subcommands**
+
+| Subcommand | Description |
+|---|---|
+| [`add`](#token-add) | Create a new authentication token |
+| [`list`](#token-list) | List all authentication tokens |
+| [`show`](#token-show) | Show detailed information about a specific token |
+| [`remove`](#token-remove) | Remove an authentication token |
+
+**Security features**
+
+- All tokens are hashed using bcrypt before storage
+- Tokens automatically expire based on Redis TTL if an expiration is set
+- The server never stores plaintext tokens
+- Partial hash matching is supported for CLI convenience
+
+### `token add`
+
+Create a new authentication token.
+
+**Syntax**
+
+```bash
+agent-memory token add --description [OPTIONS]
+```
+
+**Required options**
+
+| Option | Description |
+|---|---|
+| `-d`, `--description TEXT` | Description for the token (e.g. "API access for service X") |
+
+**Optional options**
+
+| Option | Default | Description |
+|---|---|---|
+| `-e`, `--expires-days INTEGER` | never expires | Number of days until the token expires |
+| `--format` `text` \| `json` | `text` | Output format. `json` is recommended for CI and scripting. |
+| `--token TEXT` | auto-generated | Use a pre-generated token value instead of letting the CLI generate one. The CLI hashes and stores the provided token; store the plaintext securely in your secrets manager or CI system. |
+
+**Examples**
+
+```bash
+# Create a token that expires in 30 days
+agent-memory token add --description "API access token" --expires-days 30
+
+# Create a permanent token (no expiration)
+agent-memory token add --description "Service account token"
+
+# Create a token and return JSON (for CI/scripts)
+agent-memory token add --description "CI token" --expires-days 30 --format json
+
+# Register a pre-generated token (e.g., from a secrets manager)
+agent-memory token add --description "Terraform bootstrap" --token "$MY_TOKEN" --format json
+```
+
+!!! warning "Token shown only once"
+
+ The generated token is displayed only once. Store it securely; it cannot be retrieved again.
+
+### `token list`
+
+List all authentication tokens, showing masked token hashes, descriptions, and expiration dates.
+
+**Syntax**
+
+```bash
+agent-memory token list [OPTIONS]
+```
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `--format` `text` \| `json` | `text` | Output format. `json` returns a machine-readable array suitable for CI pipelines. |
+
+**Text output example**
+
+```
+Authentication Tokens:
+==================================================
+Token: abc12345...xyz67890
+Description: API access token
+Created: 2025-07-10T18:30:00.000000+00:00
+Expires: 2025-08-09T18:30:00.000000+00:00
+------------------------------
+Token: def09876...uvw54321
+Description: Service account token
+Created: 2025-07-10T19:00:00.000000+00:00
+Expires: Never
+------------------------------
+```
+
+**JSON output example**
+
+```json
+[
+ {
+ "hash": "abc12345def67890xyz",
+ "description": "API access token",
+ "created_at": "2025-07-10T18:30:00.000000+00:00",
+ "expires_at": "2025-08-09T18:30:00.000000+00:00",
+ "status": "Active"
+ },
+ {
+ "hash": "def09876uvw54321...",
+ "description": "Service account token",
+ "created_at": "2025-07-10T19:00:00.000000+00:00",
+ "expires_at": null,
+ "status": "Never Expires"
+ }
+]
+```
+
+### `token show`
+
+Show detailed information about a specific token. Supports partial hash matching for convenience.
+
+**Syntax**
+
+```bash
+agent-memory token show [OPTIONS]
+```
+
+**Arguments**
+
+| Argument | Description |
+|---|---|
+| `TOKEN_HASH` | The token hash (or partial hash) to display. Can be the full hash or just the first few characters; partial hashes must be unique. |
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `--format` `text` \| `json` | `text` | Output format. `json` returns a machine-readable object including status. |
+
+**Examples**
+
+```bash
+# Show token details using full hash
+agent-memory token show abc12345def67890xyz
+
+# Show token details using partial hash (must be unique)
+agent-memory token show abc123
+```
+
+**JSON output example**
+
+```json
+{
+ "hash": "abc12345def67890xyz",
+ "description": "API access token",
+ "created_at": "2025-07-10T18:30:00.000000+00:00",
+ "expires_at": "2025-08-09T18:30:00.000000+00:00",
+ "status": "Active"
+}
+```
+
+### `token remove`
+
+Remove an authentication token. By default, asks for confirmation before removal.
+
+**Syntax**
+
+```bash
+agent-memory token remove [OPTIONS]
+```
+
+**Arguments**
+
+| Argument | Description |
+|---|---|
+| `TOKEN_HASH` | The token hash (or partial hash) to remove. Can be the full hash or just the first few characters. |
+
+**Options**
+
+| Option | Description |
+|---|---|
+| `-f`, `--force` | Remove the token without asking for confirmation |
+
+**Examples**
+
+```bash
+# Remove token with confirmation prompt
+agent-memory token remove abc123
+
+# Remove token without confirmation
+agent-memory token remove abc123 --force
+```
diff --git a/docs/api/index.md b/docs/api/index.md
new file mode 100644
index 00000000..a7e4af27
--- /dev/null
+++ b/docs/api/index.md
@@ -0,0 +1,102 @@
+---
+description: API reference for Agent Memory Server.
+---
+
+# API Reference
+
+Every interface for talking to the memory server: HTTP endpoints, the MCP
+toolset for AI agents, the CLI for operators, and three client SDKs.
+Pick the one that matches your stack β they all sit on top of the same
+core memory operations.
+
+## Server Interfaces
+
+
+
+- :material-web:{ .lg .middle } **[REST API](rest.md)**
+
+ ---
+
+ OpenAPI-described HTTP endpoints for working memory, long-term memory, and prompts.
+
+- :material-protocol:{ .lg .middle } **[MCP server](mcp.md)**
+
+ ---
+
+ Model Context Protocol tools for AI agent integration (Claude Desktop, etc.).
+
+- :material-console:{ .lg .middle } **[CLI](cli.md)**
+
+ ---
+
+ Command-line interface for running, indexing, migrating, and scheduling tasks.
+
+
+
+## Client SDKs
+
+
+
+- :material-language-python:{ .lg .middle } **[Python SDK](python_sdk.md)**
+
+ ---
+
+ Async-first Python client with tool schemas for OpenAI and Anthropic.
+
+- :material-language-typescript:{ .lg .middle } **[TypeScript SDK](typescript_sdk.md)**
+
+ ---
+
+ Type-safe client for Node.js and browser applications.
+
+- :material-coffee:{ .lg .middle } **[Java SDK](java_sdk.md)**
+
+ ---
+
+ JVM client for Java and Kotlin applications.
+
+
+
+## Source Reference
+
+
+
+- :material-package:{ .lg .middle } **[Server package](server/index.md)**
+
+ ---
+
+ Auto-generated `agent_memory_server` Python package reference, built from source via [mkdocstrings](https://mkdocstrings.github.io/).
+
+
+
+## Interface Comparison
+
+| Interface | Best For | Authentication |
+|-----------|----------|----------------|
+| REST API | Applications, backends, custom integrations | OAuth2/JWT or token |
+| MCP Server | Claude Desktop, MCP-compatible AI agents | Environment config |
+| CLI | Server administration, development | Local access |
+| Python SDK | Python applications with LLM tool integration | Token or OAuth2 |
+| TypeScript SDK | Node.js, browser, and TypeScript applications | Token or OAuth2 |
+| Java SDK | JVM-based applications | Token or OAuth2 |
+
+## Feature Cross-Reference
+
+| Feature | REST API | MCP Server | CLI | Documentation |
+|---------|----------|------------|-----|---------------|
+| **Memory Search** (semantic, keyword, hybrid) | β `/v1/long-term-memory/search` | β `search_long_term_memory` | β `agent-memory search` | [REST](rest.md), [MCP](mcp.md), [CLI](cli.md) |
+| **Memory Editing** | β `PATCH /v1/long-term-memory/{id}` | β `edit_long_term_memory` | β | [Memory Editing](../user_guide/how_to_guides/memory_editing.md) |
+| **Query Optimization** | β `optimize_query` param | β `optimize_query` param | β | [Query Optimization](../user_guide/how_to_guides/query_optimization.md) |
+| **Recency Boost** | β Default enabled | β Available | β | [Recency Boost](../concepts/recency_boost.md) |
+| **Authentication** | β JWT/Token | β Inherited | β Token management | [Authentication](../user_guide/how_to_guides/authentication.md) |
+| **Background Tasks** | β Automatic | β Automatic | β Worker management | [Configuration](../user_guide/how_to_guides/configuration.md) |
+
+## By Interface Preference
+
+**REST API users** β [REST API Documentation](rest.md) β [Authentication](../user_guide/how_to_guides/authentication.md)
+**MCP/Claude users** β [MCP Server](mcp.md) β [Memory Editing](../user_guide/how_to_guides/memory_editing.md)
+**CLI management** β [CLI Reference](cli.md) β [Configuration](../user_guide/how_to_guides/configuration.md)
+
+!!! tip "Interactive API Docs"
+ When running the server locally, visit `http://localhost:8000/docs` for
+ interactive Swagger documentation where you can try endpoints directly.
diff --git a/docs/java-sdk.md b/docs/api/java_sdk.md
similarity index 100%
rename from docs/java-sdk.md
rename to docs/api/java_sdk.md
diff --git a/docs/mcp.md b/docs/api/mcp.md
similarity index 94%
rename from docs/mcp.md
rename to docs/api/mcp.md
index b31b9a6c..7601547c 100644
--- a/docs/mcp.md
+++ b/docs/api/mcp.md
@@ -88,8 +88,8 @@ For Claude, the easiest way is to use uvx (recommended):
Notes:
- API keys: Default models use OpenAI. Set `OPENAI_API_KEY`. To use Anthropic instead, set `ANTHROPIC_API_KEY` and also `GENERATION_MODEL` to an Anthropic model (e.g., `claude-3-5-haiku-20241022`).
- Make sure your MCP host can find `uvx` (on its PATH or by using an absolute command path).
- - macOS: `brew install uv`
- - If not on PATH, set `"command"` to an absolute path (e.g., `/opt/homebrew/bin/uvx` on Apple Silicon, `/usr/local/bin/uvx` on Intel macOS). On Linux, `~/.local/bin/uvx` is common. See https://docs.astral.sh/uv/getting-started/ for distro specifics
+ - macOS: `brew install uv`
+ - If not on PATH, set `"command"` to an absolute path (e.g., `/opt/homebrew/bin/uvx` on Apple Silicon, `/usr/local/bin/uvx` on Intel macOS). On Linux, `~/.local/bin/uvx` is common. See https://docs.astral.sh/uv/getting-started/ for distro specifics
- Set `DISABLE_AUTH=false` in production and configure proper auth per the Authentication guide.
If youβre running from a local checkout instead of PyPI, you can use `uv run` with a directory:
diff --git a/docs/python-sdk.md b/docs/api/python_sdk.md
similarity index 100%
rename from docs/python-sdk.md
rename to docs/api/python_sdk.md
diff --git a/docs/api.md b/docs/api/rest.md
similarity index 100%
rename from docs/api.md
rename to docs/api/rest.md
diff --git a/docs/api/server/auth.md b/docs/api/server/auth.md
new file mode 100644
index 00000000..aa6126cb
--- /dev/null
+++ b/docs/api/server/auth.md
@@ -0,0 +1,7 @@
+---
+description: agent_memory_server.auth reference.
+---
+
+# auth
+
+::: agent_memory_server.auth
diff --git a/docs/api/server/config.md b/docs/api/server/config.md
new file mode 100644
index 00000000..1d60c872
--- /dev/null
+++ b/docs/api/server/config.md
@@ -0,0 +1,7 @@
+---
+description: agent_memory_server.config reference.
+---
+
+# config
+
+::: agent_memory_server.config
diff --git a/docs/api/server/extraction.md b/docs/api/server/extraction.md
new file mode 100644
index 00000000..f448495d
--- /dev/null
+++ b/docs/api/server/extraction.md
@@ -0,0 +1,7 @@
+---
+description: agent_memory_server.extraction reference.
+---
+
+# extraction
+
+::: agent_memory_server.extraction
diff --git a/docs/api/server/filters.md b/docs/api/server/filters.md
new file mode 100644
index 00000000..493da0c5
--- /dev/null
+++ b/docs/api/server/filters.md
@@ -0,0 +1,7 @@
+---
+description: agent_memory_server.filters reference.
+---
+
+# filters
+
+::: agent_memory_server.filters
diff --git a/docs/api/server/index.md b/docs/api/server/index.md
new file mode 100644
index 00000000..421a7dc9
--- /dev/null
+++ b/docs/api/server/index.md
@@ -0,0 +1,79 @@
+---
+description: Reference for the agent_memory_server Python package.
+---
+
+# Server package reference
+
+Auto-generated reference for the `agent_memory_server` Python package.
+Module pages are generated from Google-style docstrings via
+[mkdocstrings](https://mkdocstrings.github.io/).
+
+
+
+- :material-database:{ .lg .middle } **[Models](models.md)**
+
+ ---
+
+ Pydantic data models for memory records, sessions, and search payloads.
+
+- :material-memory:{ .lg .middle } **[Working memory](working_memory.md)**
+
+ ---
+
+ Session-scoped memory APIs for messages, structured memories, and metadata.
+
+- :material-database-search:{ .lg .middle } **[Long-term memory](long_term_memory.md)**
+
+ ---
+
+ Persistent memory with semantic search, deduplication, and compaction.
+
+- :material-strategy:{ .lg .middle } **[Memory strategies](memory_strategies.md)**
+
+ ---
+
+ Pluggable strategies for promoting working memory into long-term storage.
+
+- :material-vector-line:{ .lg .middle } **[Vector DB](memory_vector_db.md)**
+
+ ---
+
+ Vector database abstraction and factory used by the long-term memory layer.
+
+- :material-text-search:{ .lg .middle } **[Extraction](extraction.md)**
+
+ ---
+
+ Topic and entity extraction (LLM and BERT-based) over message streams.
+
+- :material-text-box-outline:{ .lg .middle } **[Summarization](summarization.md)**
+
+ ---
+
+ Conversation summarization when context windows are exceeded.
+
+- :material-filter:{ .lg .middle } **[Filters](filters.md)**
+
+ ---
+
+ Filter primitives (session, namespace, topics, entities, timestamps).
+
+- :material-shield-key:{ .lg .middle } **[Auth](auth.md)**
+
+ ---
+
+ OAuth2/JWT verification and JWKS handling.
+
+- :material-cog:{ .lg .middle } **[Config](config.md)**
+
+ ---
+
+ Settings loaded from environment variables.
+
+- :material-robot:{ .lg .middle } **[LLM client](llm.md)**
+
+ ---
+
+ LiteLLM-backed chat and embedding client.
+
+
+ ${siblingTabs()}
+ `;
+ document.body.insertBefore(header, document.body.firstChild);
+ }
+
+ if (document.readyState === 'loading') {
+ document.addEventListener('DOMContentLoaded', inject);
+ } else {
+ inject();
+ }
+})();
diff --git a/docs/assets/redis-logo-script-red.svg b/docs/assets/redis-logo-script-red.svg
new file mode 100644
index 00000000..b2abedae
--- /dev/null
+++ b/docs/assets/redis-logo-script-red.svg
@@ -0,0 +1,10 @@
+
diff --git a/docs/assets/redis-logo-script.svg b/docs/assets/redis-logo-script.svg
new file mode 100644
index 00000000..0f59d4c7
--- /dev/null
+++ b/docs/assets/redis-logo-script.svg
@@ -0,0 +1,10 @@
+
diff --git a/docs/cli.md b/docs/cli.md
deleted file mode 100644
index b3592364..00000000
--- a/docs/cli.md
+++ /dev/null
@@ -1,322 +0,0 @@
-# Command Line Interface
-
-The `agent-memory-server` provides a command-line interface (CLI) for managing the server and related tasks. You can access the CLI using the `agent-memory` command (assuming the package is installed in a way that makes the script available in your PATH, e.g., via `pip install ...`).
-
-## Available Commands
-
-Here's a list of available commands and their functions:
-
-### `version`
-
-Displays the current version of `agent-memory-server`.
-
-```bash
-agent-memory version
-```
-
-### `api`
-
-Starts the REST API server.
-
-```bash
-agent-memory api [OPTIONS]
-```
-
-**Options:**
-
-- `--port INTEGER`: Port to run the server on. (Default: value from `settings.port`, usually 8000)
-- `--host TEXT`: Host to run the server on. (Default: "0.0.0.0")
-- `--reload`: Enable auto-reload for development.
-- `--task-backend [asyncio|docket]`: Background task backend. `docket` (default) uses Docket-based background workers (requires a running `agent-memory task-worker` for non-blocking tasks). `asyncio` runs tasks inline in the API process and does **not** require a separate worker.
-- `--no-worker` (**deprecated**): Backwards-compatible alias for `--task-backend=asyncio`. Maintained for older scripts; prefer `--task-backend`.
-
-**Examples:**
-
-```bash
-# Development mode (no separate worker needed, asyncio backend)
-agent-memory api --port 8080 --reload --task-backend asyncio
-
-# Production mode (default Docket backend; requires separate worker process)
-agent-memory api --port 8080
-```
-
-!!! warning "Limitations of `--task-backend=asyncio`"
- The `asyncio` backend is suitable for development and simple use cases, but has important limitations:
-
- - **Periodic tasks don't run**: Scheduled maintenance tasks like memory compaction, periodic forgetting, and summary view refresh only execute when a Docket worker is running. These tasks use Docket's `Perpetual` scheduler.
- - **No task persistence**: If the server restarts, pending background tasks are lost.
- - **No distributed processing**: All tasks run in the API process; you cannot scale workers independently.
-
- For production deployments, use the default `docket` backend with a separate `agent-memory task-worker` process.
-
-### `mcp`
-
-Starts the Model Context Protocol (MCP) server.
-
-```bash
-agent-memory mcp [OPTIONS]
-```
-
-**Options:**
-
-- `--port INTEGER`: Port to run the MCP server on. (Default: value from `settings.mcp_port`, usually 9000)
-- `--mode [stdio|sse|streamable-http]`: Run the MCP server in stdio, SSE, or streamable-http mode. (Default: stdio)
-- `--task-backend [asyncio|docket]`: Background task backend. `asyncio` (default) runs tasks inline in the MCP process with no separate worker. `docket` sends tasks to a Docket queue, which requires running `agent-memory task-worker`.
-
-**Examples:**
-
-```bash
-# Stdio mode (recommended for Claude Desktop) - default asyncio backend
-agent-memory mcp
-
-# SSE mode for development (no separate worker needed)
-agent-memory mcp --mode sse --port 9001
-
-# Streamable HTTP mode for network deployments (e.g. Kubernetes)
-agent-memory mcp --mode streamable-http --port 9000
-
-# SSE mode for production (requires separate worker process)
-agent-memory mcp --mode sse --port 9001 --task-backend docket
-```
-
-**Note:** Stdio mode is designed for tools like Claude Desktop and, by default, uses the asyncio backend (no worker). Streamable HTTP mode is suited for deploying the MCP server as a network service where HTTP clients (like Claude Code) connect over the network. Use `--task-backend docket` if you want MCP to enqueue background work into a shared Docket worker.
-
-### `schedule-task`
-
-Schedules a background task to be processed by a Docket worker.
-
-```bash
-agent-memory schedule-task [OPTIONS]
-```
-
-**Arguments:**
-
-- `TASK_PATH`: The Python import path to the task function. For example: `"agent_memory_server.long_term_memory.compact_long_term_memories"`
-
-**Options:**
-
-- `--args TEXT` / `-a TEXT`: Arguments to pass to the task in `key=value` format. Can be specified multiple times. Values are automatically converted to boolean, integer, or float if possible, otherwise they remain strings.
-
-Example:
-
-```bash
-agent-memory schedule-task "agent_memory_server.long_term_memory.compact_long_term_memories" -a limit=500 -a namespace=my_namespace -a compact_semantic_duplicates=false
-```
-
-### `task-worker`
-
-Starts a Docket worker to process background tasks from the queue. This worker uses the Docket name configured in settings.
-
-```bash
-agent-memory task-worker [OPTIONS]
-```
-
-**Options:**
-
-- `--concurrency INTEGER`: Number of tasks to process concurrently. (Default: 10)
-- `--redelivery-timeout INTEGER`: Seconds to wait before a task is redelivered to another worker if the current worker fails or times out. (Default: `2 x llm_task_timeout_minutes` from server settings; with the default config, this is 600 seconds.)
-
-Example:
-
-```bash
-agent-memory task-worker --concurrency 5 --redelivery-timeout 600
-```
-
-### `rebuild_index`
-
-Rebuilds the search index for Redis Memory Server.
-
-```bash
-agent-memory rebuild_index
-```
-
-### `migrate-memories`
-
-Runs the built-in long-term memory migrations. Safe to rerun.
-
-Use this after upgrading if you need to backfill fields on existing memory
-records.
-
-```bash
-uv run agent-memory migrate-memories
-```
-
-### `migrate-working-memory`
-
-Migrates legacy `working_memory:*` string keys to Redis JSON.
-
-Use this if you are upgrading from an older working-memory format or if you
-want to remove deprecated legacy `sessions` / `sessions:*` sorted sets from the
-old session-listing path.
-
-Check what needs migration first:
-
-```bash
-uv run agent-memory migrate-working-memory --dry-run
-```
-
-Run the migration:
-
-```bash
-uv run agent-memory migrate-working-memory
-```
-
-### `token` Commands
-
-Manages authentication tokens for token-based authentication. The token command group provides subcommands for creating, listing, viewing, and removing API tokens.
-
-#### `token add`
-
-Creates a new authentication token.
-
-```bash
-agent-memory token add --description "DESCRIPTION" [--expires-days DAYS] [--format text|json] [--token TOKEN_VALUE]
-```
-
-**Options:**
-
-- `--description TEXT` / `-d TEXT`: **Required**. Description for the token (e.g., "API access for service X")
-- `--expires-days INTEGER` / `-e INTEGER`: **Optional**. Number of days until token expires. If not specified, token never expires.
-- `--format [text|json]`: **Optional**. Output format. `text` (default) is human-readable; `json` is machine-readable and recommended for CI or scripting.
-- `--token TEXT`: **Optional**. Use a pre-generated token value instead of having the CLI generate one. The CLI will hash and store the provided token; make sure you've stored the plaintext securely in your secrets manager or CI system.
-
-**Examples:**
-
-```bash
-# Create a token that expires in 30 days
-agent-memory token add --description "API access token" --expires-days 30
-
-# Create a permanent token (no expiration)
-agent-memory token add --description "Service account token"
-
-# Create a token and return JSON (for CI/scripts)
-agent-memory token add --description "CI token" --expires-days 30 --format json
-
-# Register a pre-generated token (e.g., from a secrets manager)
-agent-memory token add --description "Terraform bootstrap" --token "$MY_TOKEN" --format json
-```
-
-**Security Note:** The generated token is displayed only once. Store it securely as it cannot be retrieved again.
-
-#### `token list`
-
-Lists all authentication tokens, showing masked token hashes, descriptions, and expiration dates.
-
-```bash
-agent-memory token list [--format text|json]
-```
-
-When `--format json` is used, the command prints a JSON array of token summaries suitable for scripting and CI pipelines. The default `text` format produces human-readable output like the example below.
-**JSON Output Example:**
-```json
-[
- {
- "hash": "abc12345def67890xyz",
- "description": "API access token",
- "created_at": "2025-07-10T18:30:00.000000+00:00",
- "expires_at": "2025-08-09T18:30:00.000000+00:00",
- "status": "Active"
- },
- {
- "hash": "def09876uvw54321...",
- "description": "Service account token",
- "created_at": "2025-07-10T19:00:00.000000+00:00",
- "expires_at": null,
- "status": "Never Expires"
- }
-]
-```
-
-**Example Output:**
-```
-Authentication Tokens:
-==================================================
-Token: abc12345...xyz67890
-Description: API access token
-Created: 2025-07-10T18:30:00.000000+00:00
-Expires: 2025-08-09T18:30:00.000000+00:00
-------------------------------
-Token: def09876...uvw54321
-Description: Service account token
-Created: 2025-07-10T19:00:00.000000+00:00
-Expires: Never
-------------------------------
-```
-
-#### `token show`
-
-Shows detailed information about a specific token. Supports partial hash matching for convenience.
-
-```bash
-agent-memory token show TOKEN_HASH [--format text|json]
-```
-
-When `--format json` is used, the command prints a JSON object with token details (including status) suitable for scripting and CI pipelines. The default `text` format produces human-readable output.
-**JSON Output Example:**
-```json
-{
- "hash": "abc12345def67890xyz",
- "description": "API access token",
- "created_at": "2025-07-10T18:30:00.000000+00:00",
- "expires_at": "2025-08-09T18:30:00.000000+00:00",
- "status": "Active"
-}
-```
-
-**Arguments:**
-
-- `TOKEN_HASH`: The token hash (or partial hash) to display. Can be the full hash or just the first few characters.
-
-**Examples:**
-
-```bash
-# Show token details using full hash
-agent-memory token show abc12345def67890xyz
-
-# Show token details using partial hash (must be unique)
-agent-memory token show abc123
-```
-
-#### `token remove`
-
-Removes an authentication token. By default, asks for confirmation before removal.
-
-```bash
-agent-memory token remove TOKEN_HASH [--force]
-```
-
-**Arguments:**
-
-- `TOKEN_HASH`: The token hash (or partial hash) to remove. Can be the full hash or just the first few characters.
-
-**Options:**
-
-- `--force` / `-f`: Remove the token without asking for confirmation.
-
-**Examples:**
-
-```bash
-# Remove token with confirmation prompt
-agent-memory token remove abc123
-
-# Remove token without confirmation
-agent-memory token remove abc123 --force
-```
-
-**Security Features:**
-
-- All tokens are hashed using bcrypt before storage
-- Tokens automatically expire based on Redis TTL if expiration is set
-- Server never stores plaintext tokens
-- Partial hash matching for CLI convenience
-
-## Getting Help
-
-To see help for any command, you can use `--help`:
-
-```bash
-agent-memory --help
-agent-memory api --help
-agent-memory mcp --help
-# etc.
-```
diff --git a/docs/contextual-grounding.md b/docs/concepts/contextual_grounding.md
similarity index 98%
rename from docs/contextual-grounding.md
rename to docs/concepts/contextual_grounding.md
index c827ee49..7ebc39e0 100644
--- a/docs/contextual-grounding.md
+++ b/docs/concepts/contextual_grounding.md
@@ -125,7 +125,7 @@ Contextual grounding works with any supported language model, but performance va
- **claude-3-5-sonnet**: Excellent at contextual understanding
- **claude-3-haiku**: Fast, good for simple grounding
-See [LLM Providers](llm-providers.md) for complete model configuration options.
+See [LLM Providers](../user_guide/how_to_guides/llm_providers.md) for complete model configuration options.
## Usage Examples
diff --git a/docs/concepts/index.md b/docs/concepts/index.md
new file mode 100644
index 00000000..4cdf3048
--- /dev/null
+++ b/docs/concepts/index.md
@@ -0,0 +1,89 @@
+---
+description: Foundational concepts for Agent Memory Server.
+---
+
+# Concepts
+
+Memory in this system has **two tiers**. **Working memory** holds the live
+conversation for a single session. **Long-term memory** holds anything
+worth keeping across conversations β facts, preferences, decisions. The
+**lifecycle** pages cover how content moves between the two tiers
+(extraction, promotion, deduplication, eventual forgetting). Everything
+else on this page is a mechanism that supports those two tiers.
+
+If you only read two pages, read [Working memory](working_memory.md) and
+[Long-term memory](long_term_memory.md). Then come back for the rest.
+
+
+
+- :material-brain:{ .lg .middle } **[Working memory](working_memory.md)**
+
+ ---
+
+ Session-scoped conversation state with automatic summarization and context tracking.
+
+- :material-database:{ .lg .middle } **[Long-term memory](long_term_memory.md)**
+
+ ---
+
+ Persistent storage with semantic, keyword, and hybrid search across sessions.
+
+- :material-chart-box:{ .lg .middle } **[Summary views](summary_views.md)**
+
+ ---
+
+ Aggregated views of memory content for dashboards and analytics.
+
+- :material-refresh:{ .lg .middle } **[Memory lifecycle](memory_lifecycle.md)**
+
+ ---
+
+ How memories are created, promoted, deduplicated, and eventually forgotten.
+
+- :material-magnify:{ .lg .middle } **[Memory extraction](memory_extraction.md)**
+
+ ---
+
+ How important facts are automatically extracted from conversations.
+
+- :material-link-variant:{ .lg .middle } **[Contextual grounding](contextual_grounding.md)**
+
+ ---
+
+ How retrieved memories are injected into prompts at the right moment.
+
+- :material-sort-clock-descending:{ .lg .middle } **[Recency boost](recency_boost.md)**
+
+ ---
+
+ Tunable scoring that biases newer memories without losing semantic relevance.
+
+
+
+## Related Topics
+
+| Topic | Description |
+|-------|-------------|
+| [LangChain Integration](../examples/langchain.md) | Use memory with LangChain agents and chains |
+| [Custom Memory Vector Databases](../user_guide/how_to_guides/custom_vector_db.md) | Configure Redis or a custom vector backend |
+| [Use cases](../examples/use_cases.md) | What people actually build with this β read this if you're still deciding |
+
+## When to Use Advanced Features
+
+| Feature | Use When |
+|---------|----------|
+| [Query Optimization](../user_guide/how_to_guides/query_optimization.md) | Search results aren't matching user intent well |
+| [Recency Boost](recency_boost.md) | Recent memories should rank higher than older ones |
+| [Advanced Vector Config](../user_guide/how_to_guides/advanced_vector_db.md) | You need to tune performance or use custom distance metrics |
+| [Contextual Grounding](contextual_grounding.md) | Extracted memories contain unresolved pronouns like "he" or "it" |
+| [Memory Editing](../user_guide/how_to_guides/memory_editing.md) | You need to correct, enrich, or update stored memories after creation |
+
+## Where to Start
+
+**Building a chatbot?** Start with [Memory Integration Patterns](../user_guide/how_to_guides/integration_patterns.md) to understand your options.
+
+**Need to understand the data model?** Read [Working Memory](working_memory.md) and [Long-term Memory](long_term_memory.md).
+
+**Configuring extraction behavior?** See [Memory Extraction](memory_extraction.md).
+
+**Looking for server configuration?** See the [How-To Guides](../user_guide/how_to_guides/index.md) for authentication, LLM providers, and deployment.
diff --git a/docs/long-term-memory.md b/docs/concepts/long_term_memory.md
similarity index 88%
rename from docs/long-term-memory.md
rename to docs/concepts/long_term_memory.md
index fe606c53..8954ec17 100644
--- a/docs/long-term-memory.md
+++ b/docs/concepts/long_term_memory.md
@@ -21,7 +21,7 @@ Long-term memory provides persistent storage that survives server restarts and s
- **Cross-Session**: Accessible from any session
- **Persistent**: Survives server restarts and session expiration
-- **Multi-Modal Search**: Semantic (vector), keyword (BM25 full-text), and hybrid search β configurable embeddings (OpenAI, Bedrock, Ollama, and more via [LiteLLM](llm-providers.md))
+- **Multi-Modal Search**: Semantic (vector), keyword (BM25 full-text), and hybrid search - configurable embeddings (OpenAI, Bedrock, Ollama, and more via [LiteLLM](../user_guide/how_to_guides/llm_providers.md))
- **Deduplication**: Automatic hash-based and semantic deduplication
- **Rich Metadata**: Topics, entities, timestamps, memory types
- **Compaction**: Automatic cleanup and merging of duplicates
@@ -227,8 +227,9 @@ There are two main ways to create long-term memories:
The most common approach is to let the system automatically promote memories from working memory to long-term storage. This handles extraction strategies, background processing, and batch optimization.
-!!! info "Working Memory Integration"
- For automatic memory promotion from conversations, see the [Working Memory documentation](working-memory.md). This covers extraction strategies, background processing, and how to configure the memory server to automatically create long-term memories from conversation content.
+!!! note "Working Memory Integration"
+
+ For automatic memory promotion from conversations, see the [Working Memory documentation](working_memory.md). This covers extraction strategies, background processing, and how to configure the memory server to automatically create long-term memories from conversation content.
### 2. Manual Creation via API
@@ -300,12 +301,14 @@ EMBEDDING_MODEL=text-embedding-3-small # Embedding model (see LLM Providers for
DISTANCE_THRESHOLD=0.8 # Similarity threshold for search
```
-For complete configuration options, see the [Configuration Guide](configuration.md).
+For complete configuration options, see the [Configuration Guide](../user_guide/how_to_guides/configuration.md).
## Related Documentation
-- [Working Memory](working-memory.md) - Session-scoped memory storage for conversations
-- [Memory Integration Patterns](memory-integration-patterns.md) - How to integrate memory with your applications
-- [Memory Extraction Strategies](memory-extraction-strategies.md) - Different approaches to memory extraction and storage
-- [LLM Providers](llm-providers.md) - Configure OpenAI, Anthropic, AWS Bedrock, Ollama, and more
-- [Custom Memory Vector Databases](custom-memory-vector-db.md) - Configuring custom memory vector database implementations
+- [Working Memory](working_memory.md) - Session-scoped memory storage for conversations
+- [Memory Lifecycle](memory_lifecycle.md) - Creation, promotion, deduplication, and forgetting
+- [Memory Editing](../user_guide/how_to_guides/memory_editing.md) - Correct, enrich, or update stored memories after creation
+- [Memory Integration Patterns](../user_guide/how_to_guides/integration_patterns.md) - How to integrate memory with your applications
+- [Memory Extraction Strategies](memory_extraction.md) - Different approaches to memory extraction and storage
+- [LLM Providers](../user_guide/how_to_guides/llm_providers.md) - Configure OpenAI, Anthropic, AWS Bedrock, Ollama, and more
+- [Custom Memory Vector Databases](../user_guide/how_to_guides/custom_vector_db.md) - Configuring custom memory vector database implementations
diff --git a/docs/memory-extraction-strategies.md b/docs/concepts/memory_extraction.md
similarity index 91%
rename from docs/memory-extraction-strategies.md
rename to docs/concepts/memory_extraction.md
index bf27f320..64f4f608 100644
--- a/docs/memory-extraction-strategies.md
+++ b/docs/concepts/memory_extraction.md
@@ -1,6 +1,6 @@
# Memory Extraction Strategies
-This reference documents the configurable extraction strategies that determine how memories are extracted from conversations during [background extraction](memory-integration-patterns.md#pattern-3-background-extraction-automatic).
+This reference documents the configurable extraction strategies that determine how memories are extracted from conversations during [background extraction](../user_guide/how_to_guides/integration_patterns.md#pattern-3-background-extraction-automatic).
## Available Strategies
@@ -124,6 +124,7 @@ working_memory = WorkingMemory(
Allows you to provide a custom extraction prompt for specialized domains.
!!! danger "Security Critical"
+
Custom prompts can introduce security risks including prompt injection and code execution attempts. This strategy includes comprehensive security validation, but understanding the risks is essential for safe usage.
```python
@@ -134,9 +135,9 @@ custom_config = MemoryStrategyConfig(
Extract technical decisions from: {message}
Focus on:
- - Technology choices made
- - Architecture decisions
- - Implementation details
+ - Technology choices made
+ - Architecture decisions
+ - Implementation details
Return JSON with memories array containing type, text, topics, entities.
Current datetime: {current_datetime}
@@ -209,8 +210,9 @@ else:
strategy = DiscreteMemoryStrategy()
```
-!!! info "Full Security Documentation"
- For comprehensive security guidance, attack examples, and production recommendations, see the [Security Guide](security-custom-prompts.md).
+!!! note "Full Security Documentation"
+
+ For comprehensive security guidance, attack examples, and production recommendations, see the [Security Guide](../user_guide/how_to_guides/security.md).
## REST API Usage
@@ -230,7 +232,7 @@ curl -X PUT "http://localhost:8000/v1/working-memory/my-session" \
}'
```
-For more comprehensive integration examples, see [Memory Integration Patterns](memory-integration-patterns.md).
+For more comprehensive integration examples, see [Memory Integration Patterns](../user_guide/how_to_guides/integration_patterns.md).
## Best Practices
@@ -302,14 +304,15 @@ pytest tests/test_prompt_security.py -v
## Related Documentation
-- **[Working Memory](working-memory.md)** - Session-scoped, ephemeral memory storage
-- **[Long-term Memory](long-term-memory.md)** - Persistent, cross-session memory storage
-- **[Security Guide](security-custom-prompts.md)** - Comprehensive security for custom strategies
-- **[Memory Lifecycle](memory-lifecycle.md)** - How memories are managed over time
-- **[API Reference](api.md)** - REST API for memory management
-- **[MCP Server](mcp.md)** - Model Context Protocol integration
+- **[Working Memory](working_memory.md)** - Session-scoped, ephemeral memory storage
+- **[Long-term Memory](long_term_memory.md)** - Persistent, cross-session memory storage
+- **[Security Guide](../user_guide/how_to_guides/security.md)** - Comprehensive security for custom strategies
+- **[Memory Lifecycle](memory_lifecycle.md)** - How memories are managed over time
+- **[API Reference](../api/rest.md)** - REST API for memory management
+- **[MCP Server](../api/mcp.md)** - Model Context Protocol integration
---
!!! tip "Getting Started"
+
Start with the **Discrete Strategy** for most applications. It provides excellent general-purpose memory extraction. Move to specialized strategies (Summary, Preferences, Custom) as your needs become more specific.
diff --git a/docs/memory-lifecycle.md b/docs/concepts/memory_lifecycle.md
similarity index 50%
rename from docs/memory-lifecycle.md
rename to docs/concepts/memory_lifecycle.md
index 34162d32..f55036d5 100644
--- a/docs/memory-lifecycle.md
+++ b/docs/concepts/memory_lifecycle.md
@@ -1,6 +1,6 @@
# Memory Lifecycle Management
-Redis Agent Memory Server provides sophisticated memory lifecycle management to prevent unlimited growth and maintain optimal performance. This includes automatic background forgetting processes, memory compaction strategies, and server-controlled cleanup operations.
+Agent Memory Server provides sophisticated memory lifecycle management to prevent unlimited growth and maintain optimal performance. This includes automatic background forgetting processes, memory compaction strategies, and server-controlled cleanup operations.
## Overview
@@ -413,479 +413,23 @@ Automatic lifecycle management (forgetting, compaction, optimization) operates s
## Memory Editing
-The Redis Agent Memory Server provides comprehensive memory editing capabilities, allowing you to update, correct, and refine stored memories through both REST API endpoints and MCP tools. This feature enables AI agents and applications to maintain accurate, up-to-date memory records over time.
-
-### Overview
-
-Memory editing allows you to modify existing long-term memories without losing their search indexing or metadata. This is essential for:
-
-- **Correcting mistakes**: Fix inaccurate information in stored memories
-- **Updating information**: Reflect changes in user preferences or circumstances
-- **Adding details**: Enrich memories with additional context or information
-- **Maintaining accuracy**: Keep memory store current and reliable
-
-**Key Features:**
-- **Partial updates**: Modify only the fields you want to change
-- **Automatic re-indexing**: Updated memories are re-indexed for search
-- **Vector consistency**: Embeddings are regenerated when text changes
-- **Metadata preservation**: IDs, timestamps, and other metadata remain stable
-- **Atomic operations**: Updates succeed or fail completely
-
-### Memory Editing Workflow
-
-#### 1. Find the Memory
-
-First, locate the memory you want to edit using search:
-
-```python
-# Search for memories to edit
-results = await client.search_long_term_memory(
- text="user food preferences",
- limit=5
-)
-
-# Find the specific memory
-memory_to_edit = results.memories[0]
-memory_id = memory_to_edit.id
-```
-
-#### 2. Prepare Updates
-
-Specify only the fields you want to change:
-
-```python
-# Update only the text content
-updates = {
- "text": "User prefers Mediterranean cuisine and is vegetarian"
-}
-
-# Or update multiple fields
-updates = {
- "text": "User prefers Mediterranean cuisine and is vegetarian",
- "topics": ["food", "preferences", "diet", "mediterranean"],
- "entities": ["Mediterranean cuisine", "vegetarian"]
-}
-```
-
-#### 3. Apply the Update
-
-Use the appropriate interface to apply your changes:
-
-```python
-# Update the memory
-updated_memory = await client.edit_long_term_memory(
- memory_id=memory_id,
- updates=updates
-)
-```
-
-### REST API Interface
-
-#### Endpoint
-
-**PATCH /v1/long-term-memory/{memory_id}**
-
-Updates specific fields of an existing memory record.
-
-#### Request Format
-
-```http
-PATCH /v1/long-term-memory/01HXE2B1234567890ABCDEF
-Content-Type: application/json
-Authorization: Bearer your_token_here
-
-{
- "text": "Updated memory text",
- "topics": ["new", "topics"],
- "entities": ["updated", "entities"],
- "memory_type": "semantic",
- "event_date": "2024-01-15T14:30:00Z",
- "namespace": "updated_namespace",
- "user_id": "updated_user"
-}
-```
-
-#### Response Format
-
-```json
-{
- "id": "01HXE2B1234567890ABCDEF",
- "text": "Updated memory text",
- "memory_type": "semantic",
- "topics": ["new", "topics"],
- "entities": ["updated", "entities"],
- "created_at": "2024-01-10T12:00:00Z",
- "persisted_at": "2024-01-10T12:00:00Z",
- "updated_at": "2024-01-16T10:30:00Z",
- "last_accessed": "2024-01-16T10:30:00Z",
- "user_id": "user_123",
- "session_id": "session_456",
- "namespace": "updated_namespace",
- "memory_hash": "new_hash_after_update"
-}
-```
-
-#### cURL Examples
-
-**Update memory text:**
-```bash
-curl -X PATCH "http://localhost:8000/v1/long-term-memory/01HXE2B1234567890ABCDEF" \
- -H "Content-Type: application/json" \
- -H "Authorization: Bearer your_token" \
- -d '{
- "text": "User prefers dark mode interfaces and uses vim for coding"
- }'
-```
-
-**Update multiple fields:**
-```bash
-curl -X PATCH "http://localhost:8000/v1/long-term-memory/01HXE2B1234567890ABCDEF" \
- -H "Content-Type: application/json" \
- -H "Authorization: Bearer your_token" \
- -d '{
- "text": "User completed Python certification on January 15, 2024",
- "memory_type": "episodic",
- "event_date": "2024-01-15T14:30:00Z",
- "topics": ["education", "certification", "python"],
- "entities": ["Python", "certification"]
- }'
-```
-
-### MCP Tool Interface
-
-#### Tool: edit_long_term_memory
-
-The MCP server provides an `edit_long_term_memory` tool for AI agents to modify memories through natural conversation.
-
-#### Tool Schema
-
-```python
-{
- "name": "edit_long_term_memory",
- "description": "Update an existing long-term memory with new or corrected information",
- "parameters": {
- "type": "object",
- "properties": {
- "memory_id": {
- "type": "string",
- "description": "The ID of the memory to edit (get this from search results)"
- },
- "text": {
- "type": "string",
- "description": "Updated memory text content"
- },
- "topics": {
- "type": "array",
- "items": {"type": "string"},
- "description": "Updated list of topics"
- },
- "entities": {
- "type": "array",
- "items": {"type": "string"},
- "description": "Updated list of entities"
- },
- "memory_type": {
- "type": "string",
- "enum": ["semantic", "episodic", "message"],
- "description": "Type of memory"
- },
- "event_date": {
- "type": "string",
- "description": "Event date for episodic memories (ISO 8601 format)"
- },
- "namespace": {
- "type": "string",
- "description": "Memory namespace"
- },
- "user_id": {
- "type": "string",
- "description": "User ID associated with the memory"
- }
- },
- "required": ["memory_id"]
- }
-}
-```
-
-#### MCP Usage Examples
-
-**Simple text update:**
-```python
-await client.call_tool("edit_long_term_memory", {
- "memory_id": "01HXE2B1234567890ABCDEF",
- "text": "User prefers tea over coffee (updated preference)"
-})
-```
-
-**Update memory type and event date:**
-```python
-await client.call_tool("edit_long_term_memory", {
- "memory_id": "01HXE2B1234567890ABCDEF",
- "memory_type": "episodic",
- "event_date": "2024-01-15T14:30:00Z"
-})
-```
-
-**Comprehensive update:**
-```python
-await client.call_tool("edit_long_term_memory", {
- "memory_id": "01HXE2B1234567890ABCDEF",
- "text": "User was promoted to Principal Engineer on January 15, 2024",
- "memory_type": "episodic",
- "event_date": "2024-01-15T14:30:00Z",
- "topics": ["career", "promotion", "engineering", "principal"],
- "entities": ["Principal Engineer", "promotion", "January 15, 2024"]
-})
-```
-
-### Python Client Interface
-
-#### Method: edit_long_term_memory
-
-```python
-async def edit_long_term_memory(
- self,
- memory_id: str,
- updates: dict[str, Any]
-) -> MemoryRecord:
- """
- Edit an existing long-term memory record.
-
- Args:
- memory_id: The ID of the memory to edit
- updates: Dictionary of fields to update
-
- Returns:
- The updated memory record
-
- Raises:
- HTTPException: If memory not found or update fails
- """
-```
-
-#### Client Usage Examples
-
-```python
-from agent_memory_client import MemoryAPIClient, MemoryClientConfig
-
-client = MemoryAPIClient(MemoryClientConfig(base_url="http://localhost:8000"))
-
-# Simple text correction
-updated_memory = await client.edit_long_term_memory(
- memory_id="01HXE2B1234567890ABCDEF",
- updates={"text": "User actually prefers coffee, not tea"}
-)
-
-# Add more context
-updated_memory = await client.edit_long_term_memory(
- memory_id="01HXE2B1234567890ABCDEF",
- updates={
- "text": "User prefers Italian cuisine, especially pasta and pizza",
- "topics": ["food", "preferences", "italian", "cuisine"],
- "entities": ["Italian cuisine", "pasta", "pizza"]
- }
-)
-
-# Update namespace and user
-updated_memory = await client.edit_long_term_memory(
- memory_id="01HXE2B1234567890ABCDEF",
- updates={
- "namespace": "work_preferences",
- "user_id": "user_456"
- }
-)
-```
-
-### Editable Fields
-
-#### Core Content Fields
-
-- **text**: The main memory content (triggers embedding regeneration)
-- **topics**: List of topic tags for categorization
-- **entities**: List of named entities mentioned in the memory
-- **memory_type**: Type classification (semantic, episodic, message)
-
-#### Temporal Fields
-
-- **event_date**: Specific date/time for episodic memories (ISO 8601 format)
-
-#### Organization Fields
-
-- **namespace**: Memory namespace for organization
-- **user_id**: User associated with the memory
-
-#### Read-Only Fields
-
-These fields cannot be edited and are managed automatically:
-
-- **id**: Unique memory identifier
-- **created_at**: Original creation timestamp
-- **persisted_at**: When memory was first saved to long-term storage
-- **updated_at**: Last modification timestamp (updated automatically)
-- **last_accessed**: Last time memory was retrieved (managed by recency system)
-- **memory_hash**: Content hash (regenerated when text changes)
-
-### Update Behavior
-
-#### Automatic Updates
-
-When you edit a memory, the system automatically:
-
-1. **Updates timestamps**: Sets `updated_at` to current time
-2. **Regenerates embeddings**: If text content changes, new embeddings are created
-3. **Recalculates hash**: Content hash is updated for deduplication
-4. **Re-indexes memory**: Search index is updated with new content
-5. **Updates access time**: Sets `last_accessed` to current time
-
-#### Partial Updates
-
-Only specify fields you want to change - other fields remain unchanged:
-
-```python
-# Only update topics - text, entities, etc. stay the same
-updates = {"topics": ["programming", "python", "web-development"]}
-
-# Only update text - topics, entities, etc. stay the same
-updates = {"text": "Updated description of the user's preferences"}
-```
-
-#### Vector Re-indexing
-
-When memory text changes, the system automatically:
-- Generates new embeddings using the configured embedding model
-- Updates the vector index for accurate semantic search
-- Maintains search performance and accuracy
-
-### Error Handling
-
-#### Common Errors
-
-**Memory Not Found (404):**
-```json
-{
- "detail": "Memory not found: 01HXE2B1234567890ABCDEF",
- "status_code": 404
-}
-```
-
-**Invalid Memory ID (400):**
-```json
-{
- "detail": "Invalid memory ID format",
- "status_code": 400
-}
-```
-
-**Validation Error (422):**
-```json
-{
- "detail": [
- {
- "loc": ["body", "event_date"],
- "msg": "invalid datetime format",
- "type": "value_error"
- }
- ],
- "status_code": 422
-}
-```
-
-#### Error Handling in Code
-
-```python
-try:
- updated_memory = await client.edit_long_term_memory(
- memory_id="01HXE2B1234567890ABCDEF",
- updates={"text": "Updated text"}
- )
-except HTTPException as e:
- if e.status_code == 404:
- print("Memory not found")
- elif e.status_code == 422:
- print("Invalid update data")
- else:
- print(f"Update failed: {e.detail}")
-```
-
-### Use Cases and Examples
-
-#### Correcting User Information
-
-**Scenario**: User corrects their job title
-
-```python
-# 1. Search for the memory
-results = await client.search_long_term_memory(
- text="user job title engineer",
- limit=1
-)
-
-# 2. Update with correction
-if results.memories:
- await client.edit_long_term_memory(
- memory_id=results.memories[0].id,
- updates={
- "text": "User works as a Senior Software Engineer at TechCorp",
- "entities": ["Senior Software Engineer", "TechCorp"]
- }
- )
-```
-
-#### Adding Context to Sparse Memories
-
-**Scenario**: Enrich a basic memory with additional details
-
-```python
-# Original: "User likes pizza"
-# Enhanced with context:
-await client.edit_long_term_memory(
- memory_id="01HXE2B1234567890ABCDEF",
- updates={
- "text": "User likes pizza, especially thin crust with pepperoni and mushrooms from Mario's Pizzeria",
- "topics": ["food", "preferences", "pizza", "italian"],
- "entities": ["pizza", "thin crust", "pepperoni", "mushrooms", "Mario's Pizzeria"]
- }
-)
-```
-
-#### Converting Memory Types
-
-**Scenario**: Convert a general memory to an episodic memory with event date
-
-```python
-# Change from semantic to episodic with specific date
-await client.edit_long_term_memory(
- memory_id="01HXE2B1234567890ABCDEF",
- updates={
- "text": "User got promoted to Team Lead on March 15, 2024",
- "memory_type": "episodic",
- "event_date": "2024-03-15T09:00:00Z",
- "topics": ["career", "promotion", "team-lead"],
- "entities": ["Team Lead", "promotion", "March 15, 2024"]
- }
-)
-```
-
-### Best Practices for Memory Editing
-
-#### Memory Identification
-
-1. **Use search first**: Always search to find the correct memory ID
-2. **Verify before editing**: Check memory content matches your expectations
-3. **Handle duplicates**: Consider if multiple memories need the same update
-
-#### Update Strategy
-
-1. **Minimal changes**: Only update fields that actually need to change
-2. **Preserve context**: Don't remove important information when updating
-3. **Consistent formatting**: Maintain consistent data formats across memories
-4. **Validate inputs**: Check data formats before making updates
-
-#### Error Prevention
-
-1. **Check memory exists**: Handle 404 errors gracefully
-2. **Validate data**: Ensure update data matches expected formats
-3. **Test updates**: Verify changes work as expected in development
-4. **Monitor performance**: Watch for degradation with frequent updates
-
-This comprehensive memory editing system ensures that your AI agent's memory remains accurate, current, and useful over time, adapting to new information and corrections as they become available.
+Long-term memories aren't immutable records β they're part of the
+lifecycle. After a memory is created it can be **updated**, **corrected**,
+or **enriched** through the REST API, the MCP server, and the Python
+client.
+
+Why this matters for the lifecycle: an edit isn't a plain field update.
+Changing a memory's `text` regenerates its embedding, recomputes its
+content hash (which feeds deduplication), and re-enters the same indexing
+pipeline as a newly-created memory. Edits to topics, entities, or
+metadata refresh the search filters that other memories are matched
+against. In other words, an edited memory passes back through extraction,
+embedding, and indexing β the same stages a fresh memory walks through.
+
+That's why editing belongs in the lifecycle picture rather than in a
+separate CRUD section: it's a re-entry into the pipeline.
+
+For the full workflow β including the `PATCH /v1/long-term-memory/{id}`
+endpoint, the `edit_long_term_memory` MCP tool, the editable field
+reference, error handling, and worked use cases β see the [**Memory
+editing how-to guide**](../user_guide/how_to_guides/memory_editing.md).
diff --git a/docs/recency-boost.md b/docs/concepts/recency_boost.md
similarity index 100%
rename from docs/recency-boost.md
rename to docs/concepts/recency_boost.md
diff --git a/docs/summary-views.md b/docs/concepts/summary_views.md
similarity index 95%
rename from docs/summary-views.md
rename to docs/concepts/summary_views.md
index 632b21e3..96c2e9e2 100644
--- a/docs/summary-views.md
+++ b/docs/concepts/summary_views.md
@@ -244,6 +244,6 @@ The summarization prompt is automatically truncated to fit within the model's co
## Related Documentation
-- [Long-term Memory](long-term-memory.md) - The memory source for summary views
-- [Working Memory](working-memory.md) - Session-scoped memory (future summary view source)
-- [Configuration](configuration.md) - Server settings including `fast_model` and `summarization_threshold`
+- [Long-term Memory](long_term_memory.md) - The memory source for summary views
+- [Working Memory](working_memory.md) - Session-scoped memory (future summary view source)
+- [Configuration](../user_guide/how_to_guides/configuration.md) - Server settings including `fast_model` and `summarization_threshold`
diff --git a/docs/working-memory.md b/docs/concepts/working_memory.md
similarity index 85%
rename from docs/working-memory.md
rename to docs/concepts/working_memory.md
index c923a2d2..4a66b272 100644
--- a/docs/working-memory.md
+++ b/docs/concepts/working_memory.md
@@ -4,10 +4,10 @@ Working memory stores the **current conversation** for a session. It holds messa
## What Working Memory Does
-1. **Stores conversation messages** β The chat history for a session
-2. **Tracks session data** β Arbitrary key-value data that lives only in this session
-3. **Automatically summarizes** β When messages exceed the token limit, older messages are summarized and removed
-4. **Promotes memories** β Structured memories added here get indexed in long-term storage
+1. **Stores conversation messages** - The chat history for a session
+2. **Tracks session data** - Arbitrary key-value data that lives only in this session
+3. **Automatically summarizes** - When messages exceed the token limit, older messages are summarized and removed
+4. **Promotes memories** - Structured memories added here get indexed in long-term storage
## Quick Reference
@@ -42,7 +42,7 @@ When your conversation exceeds the model's context window, working memory automa
3. **Removes the summarized messages** to free space
4. **Keeps recent messages** intact
-This happens transparentlyβyou don't need to trigger it.
+This happens transparently - you don't need to trigger it.
### How It Works
@@ -130,7 +130,7 @@ working_memory = WorkingMemory(
> **β οΈ Always provide `created_at` timestamps**
>
-> This ensures correct message ordering and proper temporal context when promoting to long-term memory. Omitting `created_at` triggers a deprecation warningβit will become required in a future version.
+> This ensures correct message ordering and proper temporal context when promoting to long-term memory. Omitting `created_at` triggers a deprecation warning - it will become required in a future version.
## Session-Specific Data
@@ -193,7 +193,7 @@ working_memory = WorkingMemory(
)
```
-See [Memory Extraction Strategies](memory-extraction-strategies.md) for configuration options.
+See [Memory Extraction Strategies](memory_extraction.md) for configuration options.
## API Reference
@@ -244,11 +244,13 @@ This lets you use TTL to save Redis memory while maintaining conversation contin
| `LONG_TERM_MEMORY` | `true` | Enable long-term memory features |
| `INDEX_ALL_MESSAGES_IN_LONG_TERM_MEMORY` | `false` | Index messages for reconstruction |
-See the [Configuration Guide](configuration.md) for all options.
+See the [Configuration Guide](../user_guide/how_to_guides/configuration.md) for all options.
## Related Documentation
-- [Long-term Memory](long-term-memory.md) β Persistent, cross-session storage
-- [Memory Integration Patterns](memory-integration-patterns.md) β How to integrate memory
-- [Memory Extraction Strategies](memory-extraction-strategies.md) β Automatic memory extraction
-- [LLM Providers](llm-providers.md) β Configure OpenAI, Anthropic, Bedrock, Ollama
+- [Long-term Memory](long_term_memory.md) - Persistent, cross-session storage
+- [Memory Lifecycle](memory_lifecycle.md) - How memories are created, promoted, and forgotten
+- [Memory Editing](../user_guide/how_to_guides/memory_editing.md) - Update or correct stored memories
+- [Memory Integration Patterns](../user_guide/how_to_guides/integration_patterns.md) - How to integrate memory
+- [Memory Extraction Strategies](memory_extraction.md) - Automatic memory extraction
+- [LLM Providers](../user_guide/how_to_guides/llm_providers.md) - Configure OpenAI, Anthropic, Bedrock, Ollama
diff --git a/docs/developer-guide-index.md b/docs/developer-guide-index.md
deleted file mode 100644
index fed98c06..00000000
--- a/docs/developer-guide-index.md
+++ /dev/null
@@ -1,60 +0,0 @@
-# Developer Guide
-
-Learn how to integrate memory into your AI applications. This guide covers integration patterns, memory types, extraction strategies, and memory lifecycle management.
-
-## Core Concepts
-
-
-
-- π **Memory Integration Patterns**
-
- ---
-
- Three patterns for using memory: LLM-driven, code-driven, and background extraction
-
- [Integration Patterns β](memory-integration-patterns.md)
-
-- π **Working Memory**
-
- ---
-
- Session-scoped storage for active conversation state
-
- [Working Memory β](working-memory.md)
-
-- π§ **Long-term Memory**
-
- ---
-
- Persistent, cross-session storage for knowledge that should be retained
-
- [Long-term Memory β](long-term-memory.md)
-
-- π― **Memory Extraction Strategies**
-
- ---
-
- Configure how memories are extracted: discrete, summary, preferences, or custom
-
- [Extraction Strategies β](memory-extraction-strategies.md)
-
-
-
-## Additional Topics
-
-| Topic | Description |
-|-------|-------------|
-| [Summary Views](summary-views.md) | Pre-computed memory summaries for efficient context |
-| [Memory Lifecycle](memory-lifecycle.md) | How memories are created, updated, and managed over time |
-| [LangChain Integration](langchain-integration.md) | Use memory with LangChain agents and chains |
-| [Custom Memory Vector Databases](custom-memory-vector-db.md) | Configure Redis or custom memory vector databases |
-
-## Where to Start
-
-**Building a chatbot?** Start with [Memory Integration Patterns](memory-integration-patterns.md) to understand your options.
-
-**Need to understand the data model?** Read [Working Memory](working-memory.md) and [Long-term Memory](long-term-memory.md).
-
-**Configuring extraction behavior?** See [Memory Extraction Strategies](memory-extraction-strategies.md).
-
-**Looking for server configuration?** See the [Operations Guide](operations-guide-index.md) for authentication, LLM providers, and deployment.
diff --git a/docs/examples/agent_examples.md b/docs/examples/agent_examples.md
new file mode 100644
index 00000000..7c3afd7f
--- /dev/null
+++ b/docs/examples/agent_examples.md
@@ -0,0 +1,143 @@
+# Agent Examples
+
+Working examples that demonstrate real-world usage patterns of the Agent
+Memory Server. Each example focuses on a different aspect of memory
+management β from basic conversation storage to advanced editing
+workflows β and runs as a self-contained script (or notebook).
+
+If you're just trying things out, **start with the
+[Interactive Technical Guide](agent_memory_server_interactive_guide.ipynb)**:
+it walks through the whole system end-to-end in a notebook. If you'd
+rather see one complete agent first, start with the
+[**Travel Agent**](travel_agent.md) β it uses every memory tool the
+server exposes.
+
+
+
+- :material-notebook:{ .lg .middle } **[Interactive Guide](agent_memory_server_interactive_guide.ipynb)**
+
+ ---
+
+ Twelve-section, cell-by-cell walkthrough of the full memory system.
+
+- :material-airplane:{ .lg .middle } **[Travel Agent](travel_agent.md)**
+
+ ---
+
+ Most comprehensive example. Auto-discovers and uses every memory tool.
+
+- :material-message-text:{ .lg .middle } **[Memory Prompt Agent](memory_prompt_agent.md)**
+
+ ---
+
+ Simplified pattern using `memory_prompt()` for context hydration.
+
+- :material-pencil:{ .lg .middle } **[Memory Editing Agent](memory_editing_agent.md)**
+
+ ---
+
+ Full editing lifecycle: create, search, correct, update, delete.
+
+- :material-school:{ .lg .middle } **[AI Tutor](ai_tutor.md)**
+
+ ---
+
+ Episodic + semantic memory for learning tracking and weak-concept practice.
+
+- :material-link-variant:{ .lg .middle } **[LangChain Integration](langchain.md)**
+
+ ---
+
+ Memory-enabled LangChain agents via `get_memory_tools()`.
+
+- :material-counter:{ .lg .middle } **[Recent Messages Limit Demo](recent_messages_limit_demo.md)**
+
+ ---
+
+ Efficient retrieval of the most recent N messages from working memory.
+
+
+
+## Getting Started with Examples
+
+### 1. Prerequisites
+
+```bash
+# Install dependencies
+cd /path/to/agent-memory-server
+uv sync --all-extras
+
+# Start memory server (disable auth for local development)
+DISABLE_AUTH=true uv run agent-memory api --task-backend=asyncio
+
+# Set required API keys
+export OPENAI_API_KEY="your-openai-key"
+```
+
+### 2. Run an Example
+
+```bash
+cd examples
+
+# Most comprehensive standalone agent
+python travel_agent.py --demo
+
+# Memory editing workflows
+python memory_editing_agent.py --demo
+
+# Simplified memory prompts
+python memory_prompt_agent.py
+
+# Learning tracking
+python ai_tutor.py --demo
+
+# LangChain integration
+python langchain_integration_example.py
+
+# Recent messages limit feature
+python recent_messages_limit_demo.py
+```
+
+### 3. Customize and Extend
+
+Each example is designed to be:
+
+- **Self-contained**: Runs independently with minimal setup
+- **Configurable**: Supports custom sessions, users, and server URLs
+- **Educational**: Well-commented code showing best practices
+- **Production-ready**: Robust error handling and logging
+
+### 4. Shared Implementation Patterns
+
+Most examples follow the same shape:
+
+```python
+# Memory client setup
+client = MemoryAPIClient(
+ base_url="http://localhost:8000",
+ default_namespace=namespace,
+ user_id=user_id
+)
+
+# Tool integration
+tools = MemoryAPIClient.get_all_memory_tool_schemas()
+response = await openai_client.chat.completions.create(
+ model="gpt-4o",
+ messages=messages,
+ tools=tools
+)
+
+# Tool resolution
+for tool_call in response.choices[0].message.tool_calls:
+ result = await client.resolve_tool_call(
+ tool_call=tool_call,
+ session_id=session_id
+ )
+```
+
+## Where to Next
+
+- **Learning the system end-to-end?** β [Interactive Guide](agent_memory_server_interactive_guide.ipynb)
+- **Most complete production-style agent?** β [Travel Agent](travel_agent.md)
+- **Editing patterns?** β [Memory Editing Agent](memory_editing_agent.md) and the [Memory editing how-to](../user_guide/how_to_guides/memory_editing.md)
+- **Building your own?** Each example is a template β clone, adapt, ship.
diff --git a/docs/examples/agent_memory_server_interactive_guide.ipynb b/docs/examples/agent_memory_server_interactive_guide.ipynb
new file mode 120000
index 00000000..3ca2ec28
--- /dev/null
+++ b/docs/examples/agent_memory_server_interactive_guide.ipynb
@@ -0,0 +1 @@
+../../examples/agent_memory_server_interactive_guide.ipynb
\ No newline at end of file
diff --git a/docs/examples/ai_tutor.md b/docs/examples/ai_tutor.md
new file mode 100644
index 00000000..29f73dd4
--- /dev/null
+++ b/docs/examples/ai_tutor.md
@@ -0,0 +1,52 @@
+# π« AI Tutor
+
+**File**: [`examples/ai_tutor.py`](https://github.com/redis/agent-memory-server/blob/main/examples/ai_tutor.py)
+
+A functional tutoring system that demonstrates episodic memory for learning tracking and semantic memory for concept management.
+
+## Core Features
+
+- **Quiz Management**: Runs interactive quizzes and stores results
+- **Learning Tracking**: Stores quiz results as episodic memories with timestamps
+- **Concept Tracking**: Tracks weak concepts as semantic memories
+- **Progress Analysis**: Provides summaries and personalized practice suggestions
+
+## Memory Patterns Used
+
+```python
+# Episodic: Per-question results with event dates
+{
+ "text": "User answered 'photosynthesis' question incorrectly",
+ "memory_type": "episodic",
+ "event_date": "2024-01-15T10:30:00Z",
+ "topics": ["quiz", "biology", "photosynthesis"]
+}
+
+# Semantic: Weak concepts for targeted practice
+{
+ "text": "User struggles with photosynthesis concepts",
+ "memory_type": "semantic",
+ "topics": ["weak_concept", "biology", "photosynthesis"]
+}
+```
+
+## Usage Examples
+
+```bash
+cd examples
+
+# Interactive tutoring session
+python ai_tutor.py
+
+# Demo with sample quiz flow
+python ai_tutor.py --demo
+
+# Custom student session
+python ai_tutor.py --user-id student123 --session-id bio_course
+```
+
+## Key Commands
+
+- **Practice**: Start a quiz on specific topics
+- **Summary**: Get learning progress summary
+- **Practice-next**: Get personalized practice recommendations based on weak areas
diff --git a/docs/examples/index.md b/docs/examples/index.md
new file mode 100644
index 00000000..6d119856
--- /dev/null
+++ b/docs/examples/index.md
@@ -0,0 +1,40 @@
+---
+description: Examples and integrations for Agent Memory Server.
+---
+
+# Examples
+
+Real-world integrations and agent patterns using Agent Memory Server.
+
+Browse [**Use cases**](use_cases.md) first to see what people actually
+build with this. Then jump to [**LangChain**](langchain.md) if you're
+wiring memory into an existing chain, or to [**Agent examples**](agent_examples.md)
+for end-to-end walkthroughs you can clone and run.
+
+
+
+- :material-target:{ .lg .middle } **[Use cases](use_cases.md)**
+
+ ---
+
+ Real-world applications across industries: customer support, tutoring, healthcare, e-commerce, and more.
+
+- :material-link-variant:{ .lg .middle } **[LangChain integration](langchain.md)**
+
+ ---
+
+ Use Agent Memory Server with LangChain for persistent agent memory.
+
+- :material-robot:{ .lg .middle } **[Agent examples](agent_examples.md)**
+
+ ---
+
+ Complete agents: travel agent, AI tutor, memory editor, and more.
+
+
+
+!!! tip
+
+ For runnable scripts, see the
+ [examples directory](https://github.com/redis/agent-memory-server/tree/main/examples)
+ on GitHub.
diff --git a/docs/langchain-integration.md b/docs/examples/langchain.md
similarity index 96%
rename from docs/langchain-integration.md
rename to docs/examples/langchain.md
index f94b15f6..d253b203 100644
--- a/docs/langchain-integration.md
+++ b/docs/examples/langchain.md
@@ -6,7 +6,7 @@ The Python SDK (agent-memory-client) provides a LangChain integration that helps
The SDK provides a `get_memory_tools()` function that returns a list of LangChain `StructuredTool` instances. These tools give your LangChain LLMs and agents access to the memory server's capabilities.
-For details on available memory operations, see the [Tool Integration](python-sdk.md#tool-integration) section of the Python SDK documentation.
+For details on available memory operations, see the [Tool Integration](../api/python_sdk.md#tool-integration) section of the Python SDK documentation.
### Direct LLM Integration
@@ -300,6 +300,6 @@ asyncio.run(main())
## See Also
-- [Python SDK Documentation](python-sdk.md) - Complete SDK reference and tool methods
-- [Memory Integration Patterns](memory-integration-patterns.md) - Overview of different integration approaches
+- [Python SDK Documentation](../api/python_sdk.md) - Complete SDK reference and tool methods
+- [Memory Integration Patterns](../user_guide/how_to_guides/integration_patterns.md) - Overview of different integration approaches
- [LangChain Integration Example](https://github.com/redis/agent-memory-server/blob/main/examples/langchain_integration_example.py) - Complete working example
diff --git a/docs/examples/memory_editing_agent.md b/docs/examples/memory_editing_agent.md
new file mode 100644
index 00000000..16761b38
--- /dev/null
+++ b/docs/examples/memory_editing_agent.md
@@ -0,0 +1,75 @@
+# βοΈ Memory Editing Agent
+
+**File**: [`examples/memory_editing_agent.py`](https://github.com/redis/agent-memory-server/blob/main/examples/memory_editing_agent.py)
+
+Demonstrates comprehensive memory editing capabilities through natural conversation patterns.
+
+## Core Features
+
+- **Memory Editing Workflow**: Complete lifecycle of creating, searching, editing, and deleting memories
+- **All Memory Tools**: Uses all available memory management tools including editing capabilities
+- **Realistic Scenarios**: Common patterns like corrections, updates, and information cleanup
+- **Interactive Demo**: Both automated demo and interactive modes
+
+## Memory Operations Demonstrated
+
+1. **search_memory** β Find existing memories using natural language (supports `semantic`, `keyword`, and `hybrid` search modes)
+2. **get_long_term_memory** β Retrieve specific memories by ID
+3. **lazily_create_long_term_memory** β Store new information (promoted to long-term storage later)
+4. **eagerly_create_long_term_memory** β Create long-term memories directly for immediate storage
+5. **edit_long_term_memory** β Update existing memories
+6. **delete_long_term_memories** β Remove outdated information
+7. **get_or_create_working_memory** β Check current working memory session
+8. **update_working_memory_data** β Store/update session-specific data
+9. **get_current_datetime** β Get current UTC datetime for grounding relative time expressions
+
+## Common Editing Scenarios
+
+```python
+# Correction scenario
+"Actually, I work at Microsoft, not Google"
+# β Search for job memory, edit company name
+
+# Update scenario
+"I got promoted to Senior Engineer"
+# β Find job memory, update title and add promotion date
+
+# Preference change
+"I prefer tea over coffee now"
+# β Search beverage preferences, update from coffee to tea
+
+# Information cleanup
+"Delete that old job information"
+# β Search and remove outdated employment data
+```
+
+## Usage Examples
+
+```bash
+cd examples
+
+# Interactive mode (explore memory editing)
+python memory_editing_agent.py
+
+# Automated demo (see complete workflow)
+python memory_editing_agent.py --demo
+
+# Custom configuration
+python memory_editing_agent.py --session-id alice_session --user-id alice
+```
+
+## Demo Conversation Flow
+
+The automated demo shows a realistic conversation:
+
+1. **Initial Information**: User shares profile (name, job, preferences)
+2. **Corrections**: User corrects information (job company change)
+3. **Updates**: User provides updates (promotion, new title)
+4. **Multiple Changes**: User updates location and preferences
+5. **Information Retrieval**: User asks what agent remembers
+6. **Ongoing Updates**: Continued information updates
+7. **Memory Management**: Specific memory operations (show/delete)
+
+## See Also
+
+- [Memory editing how-to guide](../user_guide/how_to_guides/memory_editing.md) β endpoint reference, MCP tool, and editable field details
diff --git a/docs/examples/memory_prompt_agent.md b/docs/examples/memory_prompt_agent.md
new file mode 100644
index 00000000..6b1d8a44
--- /dev/null
+++ b/docs/examples/memory_prompt_agent.md
@@ -0,0 +1,47 @@
+# π§ Memory Prompt Agent
+
+**File**: [`examples/memory_prompt_agent.py`](https://github.com/redis/agent-memory-server/blob/main/examples/memory_prompt_agent.py)
+
+Demonstrates the simplified memory prompt feature for context-aware conversations without manual tool management.
+
+## Core Concept
+
+Uses `client.memory_prompt()` to automatically retrieve relevant memories and enrich prompts with contextual information.
+
+## How It Works
+
+1. **Store Messages**: All conversation messages stored in working memory
+2. **Memory Prompt**: `memory_prompt()` retrieves relevant context automatically
+3. **Enriched Context**: Memory context combined with system prompt
+4. **LLM Generation**: Enhanced context sent to LLM for personalized responses
+
+## Usage Examples
+
+```bash
+cd examples
+python memory_prompt_agent.py
+
+# With custom session
+python memory_prompt_agent.py --session-id my_session --user-id jane_doe
+```
+
+## Key Implementation Pattern
+
+```python
+# Automatic memory retrieval and context enrichment
+context = await client.memory_prompt(
+ query=user_message,
+ session_id=session_id,
+ long_term_search={
+ "text": user_message,
+ "limit": 5,
+ "user_id": user_id
+ }
+)
+
+# Enhanced prompt with memory context
+response = await openai_client.chat.completions.create(
+ model="gpt-4o",
+ messages=context["messages"]
+)
+```
diff --git a/docs/examples/recent_messages_limit_demo.md b/docs/examples/recent_messages_limit_demo.md
new file mode 100644
index 00000000..9e1682d5
--- /dev/null
+++ b/docs/examples/recent_messages_limit_demo.md
@@ -0,0 +1,46 @@
+# π Recent Messages Limit Demo
+
+**File**: [`examples/recent_messages_limit_demo.py`](https://github.com/redis/agent-memory-server/blob/main/examples/recent_messages_limit_demo.py)
+
+Demonstrates the `recent_messages_limit` parameter for efficiently retrieving only the most recent N messages from working memory.
+
+## Core Concept
+
+When working memory grows large, retrieving all messages is expensive. The `recent_messages_limit` parameter lets you fetch only the N most recent messages, useful for context windows and UI displays.
+
+## Key Features
+
+- **Efficient Retrieval**: Fetch only the messages you need instead of the full history
+- **SDK & HTTP Integration**: Uses `agent_memory_client` to store working memory and raw HTTP requests to retrieve it
+- **Multiple Scenarios**: Tests various limits (3, 5, 20, 2) to show how `recent_messages_limit` changes the results
+- **Direct API Verification**: Uses the raw HTTP API for retrieval so you can inspect the exact responses from the server
+
+## Usage Examples
+
+```bash
+cd examples
+python recent_messages_limit_demo.py
+```
+
+## Key Implementation Pattern
+
+The `recent_messages_limit` parameter is not yet exposed in the high-level Python SDK. Use the REST API directly via `httpx`:
+
+```python
+import httpx
+
+async with httpx.AsyncClient(base_url="http://localhost:8000") as http:
+ # Get only the 3 most recent messages
+ resp = await http.get(
+ f"/v1/working-memory/{session_id}",
+ params={"namespace": "demo", "recent_messages_limit": 3},
+ )
+ resp.raise_for_status()
+ messages = resp.json()["messages"]
+```
+
+The equivalent raw request is:
+
+```
+GET /v1/working-memory/{session_id}?namespace=demo&recent_messages_limit=3
+```
diff --git a/docs/examples/travel_agent.md b/docs/examples/travel_agent.md
new file mode 100644
index 00000000..656b259b
--- /dev/null
+++ b/docs/examples/travel_agent.md
@@ -0,0 +1,69 @@
+# 𧳠Travel Agent
+
+**File**: [`examples/travel_agent.py`](https://github.com/redis/agent-memory-server/blob/main/examples/travel_agent.py)
+
+A comprehensive travel assistant that demonstrates the most complete integration patterns.
+
+## Key Features
+
+- **Automatic Tool Discovery**: Uses `MemoryAPIClient.get_all_memory_tool_schemas()` to automatically discover and integrate all available memory tools
+- **Unified Tool Resolution**: Leverages `client.resolve_tool_call()` to handle all memory tool calls uniformly across different LLM providers
+- **Working Memory Management**: Session-based conversation state and structured memory storage
+- **Long-term Memory**: Persistent memory storage with semantic, keyword, and hybrid search capabilities
+- **Optional Web Search**: Cached web search using Tavily API with Redis caching
+
+## Available Tools
+
+The travel agent automatically discovers and uses all memory tools:
+
+1. **search_memory** β Search through previous conversations and stored information (supports `semantic`, `keyword`, and `hybrid` search modes)
+2. **get_or_create_working_memory** β Check current working memory session
+3. **lazily_create_long_term_memory** β Store important information as structured memories (promoted to long-term storage later)
+4. **update_working_memory_data** β Store/update session-specific data like trip plans
+5. **get_long_term_memory** β Retrieve a specific long-term memory by ID
+6. **eagerly_create_long_term_memory** β Create long-term memories directly for immediate storage
+7. **edit_long_term_memory** β Update existing long-term memories
+8. **delete_long_term_memories** β Remove long-term memories
+9. **get_current_datetime** β Get current UTC datetime for grounding relative time expressions
+10. **web_search** (optional) β Search the internet for current travel information
+
+## Usage Examples
+
+```bash
+# Basic interactive usage
+cd examples
+python travel_agent.py
+
+# Automated demo showing capabilities
+python travel_agent.py --demo
+
+# With custom configuration
+python travel_agent.py --session-id my_trip --user-id john_doe --memory-server-url http://localhost:8001
+```
+
+## Environment Setup
+
+```bash
+# Required
+export OPENAI_API_KEY="your-openai-key"
+
+# Optional (for web search)
+export TAVILY_API_KEY="your-tavily-key"
+export REDIS_URL="redis://localhost:6379"
+```
+
+## Key Implementation Patterns
+
+```python
+# Tool auto-discovery
+memory_tools = MemoryAPIClient.get_all_memory_tool_schemas()
+
+# Unified tool resolution for any provider
+result = await client.resolve_tool_call(
+ tool_call=provider_tool_call,
+ session_id=session_id
+)
+
+if result["success"]:
+ print(result["formatted_response"])
+```
diff --git a/docs/use-cases.md b/docs/examples/use_cases.md
similarity index 98%
rename from docs/use-cases.md
rename to docs/examples/use_cases.md
index 80d430e0..e48e098e 100644
--- a/docs/use-cases.md
+++ b/docs/examples/use_cases.md
@@ -1,6 +1,6 @@
# Use Cases and Examples
-Redis Agent Memory Server enables powerful AI applications by providing persistent, searchable memory. Here are real-world use cases and implementation examples across different industries and applications.
+Agent Memory Server enables powerful AI applications by providing persistent, searchable memory. Here are real-world use cases and implementation examples across different industries and applications.
## Customer Support
@@ -713,4 +713,4 @@ guidance = await health.get_contextual_health_guidance(
- **Background processing**: Let automatic promotion handle memory management
- **Regular cleanup**: Use forgetting mechanisms for outdated information
-These use cases demonstrate the versatility of Redis Agent Memory Server across industries and applications. The key is to design your memory schema and search patterns to match your specific domain needs while leveraging the platform's intelligent features for optimal user experiences.
+These use cases demonstrate the versatility of Agent Memory Server across industries and applications. The key is to design your memory schema and search patterns to match your specific domain needs while leveraging the platform's intelligent features for optimal user experiences.
diff --git a/docs/for-ais-only/AUTHORING_STANDARD.md b/docs/for-ais-only/AUTHORING_STANDARD.md
new file mode 100644
index 00000000..9be80425
--- /dev/null
+++ b/docs/for-ais-only/AUTHORING_STANDARD.md
@@ -0,0 +1,94 @@
+---
+description: Authoring standard for Redis project documentation. Use this as a system prompt when generating or revising docs.
+---
+
+# Authoring Standard
+
+Use this page as a **system prompt** when generating or revising documentation
+for a Redis project (`agent-memory-server`, `redis-vl-python`, `sql-redis`,
+or similar). It captures the pedagogical, structural, and brand decisions
+that the docs are built on.
+
+---
+
+You are writing or revising technical documentation for a Redis project.
+Follow this philosophy strictly.
+
+## Information architecture β DiΓ‘taxis-inspired, learning-flow first
+
+Organize content into four buckets β **Concepts** (Explanation), **User Guide**
+(Tutorials + How-To), **Examples**, **API Reference** β but treat the
+framework as a starting point, not a cage. The reader's learning journey
+takes priority over quadrant purity:
+
+- **Cross-link freely between quadrants.** If a concept page benefits from
+ pointing at the tutorial that demonstrates it, do it. If a how-to needs to
+ reference an explanation page, link to it. The original DiΓ‘taxis
+ discourages this; we don't.
+- **Open every long page with a porch.** A 2β4 sentence orientation block
+ that tells the reader (a) what they're about to read, (b) what they need
+ to know first, and (c) where to go next. Porches are the bridge that the
+ strict DiΓ‘taxis quadrants refuse to build.
+- **Use analogies for hard concepts.** Working memory is the goldfish;
+ long-term memory is the elephant. Name the analogy, anchor it visually
+ if possible, and reuse it across pages so it compounds.
+- **Every section has an `index.md` landing page** built from a Material
+ card grid with cross-links to neighboring sections. The landing page is
+ a router, not a wall of text.
+
+## Voice and pedagogy
+
+- Second person, present tense, sentence case headings.
+- One purpose per page. If a page is teaching ("how do I think about X"),
+ don't ambush the reader with reference tables.
+- Don't pad with rationale or marketing. If a sentence doesn't help the
+ reader make a decision or take an action, cut it.
+- When introducing a feature, lead with the problem it solves, then the
+ mental model, then the API. Never the reverse.
+- Code examples are runnable, copy-pasteable, and use realistic variable
+ names. No `foo`/`bar` in non-trivial examples.
+- Admonitions (`!!! tip`, `!!! note`, `!!! warning`) for callouts. Never
+ bare emoji headings.
+
+## File and structure conventions
+
+- `snake_case` filenames. Numeric prefixes (`01_quick_start.md`) for ordered
+ tutorials only β never for reference or how-to pages where order is
+ flexible.
+- Heading depth capped at 3.
+- `attr_list` syntax: `{ .class }` goes *after* the closing `)` of links and
+ images; `{: .class }` on the *next line* for paragraphs. Never inline
+ mid-sentence.
+- A `for-ais-only/` section in every repo with `REPOSITORY_MAP.md`,
+ `BUILD_AND_TEST.md`, `FAILURE_MODES.md`, and this `AUTHORING_STANDARD.md`
+ for downstream AI-agent ingestion.
+
+## Brand and layout (don't override)
+
+- **MkDocs Material** with the shared `redis-brand.css` (Redis palette,
+ Space Grotesk + Space Mono).
+- **Sidebars flush to viewport edges** (`max-width: none` at desktop
+ breakpoint) β the content region is not a centered column.
+- **Card grids** on every section landing page.
+- Notebooks live in `examples/`, are symlinked into `docs/examples/`, and
+ render via `mkdocs-jupyter` with explicit cell separators.
+
+## Zero content loss on reorgs
+
+When moving or renaming a page, every example, every code block, every link
+target from the original must survive. If you're tempted to drop something,
+link to it from the new page instead. The diff for a reorg should be
+dominated by `R` (rename) operations, not `D` + `A`.
+
+## Strict build is non-negotiable
+
+The CI gate is `mkdocs build --strict`. Zero warnings. Zero broken anchors.
+Zero missing nav entries. If your edit breaks the build, fix the build
+before shipping. Pre-commit mirrors CI.
+
+## When in doubt, choose the reader
+
+If DiΓ‘taxis purity, brand consistency, or any other rule above conflicts
+with what would actually help a reader learn the material faster, choose
+the reader. Document the deviation in the page's porch so the next author
+understands why.
diff --git a/docs/for-ais-only/BUILD_AND_TEST.md b/docs/for-ais-only/BUILD_AND_TEST.md
new file mode 100644
index 00000000..9728d03b
--- /dev/null
+++ b/docs/for-ais-only/BUILD_AND_TEST.md
@@ -0,0 +1,89 @@
+# Build and Test
+
+## Prerequisites
+
+- Python 3.12.
+- `uv` (https://docs.astral.sh/uv/) β `pip install uv`.
+- Docker (for `testcontainers` Redis fixtures).
+- Optional API keys for tests that hit OpenAI/Anthropic (`make test-api`).
+
+You MUST `source .venv/bin/activate` before running `uv run` commands.
+
+## Make targets
+
+```
+make setup Create .venv, sync deps, install pre-commit hooks
+make sync Sync latest dependencies
+make test pytest (standard suite)
+make test-unit Unit tests only
+make test-integration Integration tests (require Redis via testcontainers)
+make test-api Full suite including API-key-dependent tests
+make test-cov Run tests with coverage
+make pre-commit Run the exact formatting/lint hooks used in CI
+make verify Full local verification (pre-commit + API tests)
+```
+
+## Coverage policy
+
+100% of tests must pass before commit. Run `make verify` locally before pushing.
+
+## Running a single test
+
+```
+uv run pytest tests/test_.py::test_ -vv
+```
+
+## Building the docs
+
+The docs are MkDocs Material. Notebooks render via `mkdocs-jupyter`; the
+Python API reference under `docs/api/server/` is auto-generated by
+`mkdocstrings`.
+
+```
+uv sync --group docs
+uv run mkdocs serve # http://127.0.0.1:8000/agent-memory/
+uv run mkdocs build # writes site/
+```
+
+The build should complete with zero warnings. Treat any warning as a
+breaking change. To enforce this in CI:
+
+```
+uv run mkdocs build --strict
+```
+
+## CI gates
+
+- `make verify` (pre-commit + API tests) on every PR.
+- `uv run mkdocs build --strict` on every PR (see `.github/workflows/docs.yml`).
+
+## Fast iteration loops
+
+When changing API endpoints:
+
+```
+uv run pytest tests/test_api.py -x -vv
+```
+
+When changing memory promotion or extraction:
+
+```
+uv run pytest tests/test_long_term_memory.py tests/test_extraction.py -x -vv
+```
+
+When changing MCP tools:
+
+```
+uv run pytest tests/test_mcp.py -x -vv
+```
+
+## Running the server locally
+
+```
+docker-compose up redis # Redis 8 only
+DISABLE_AUTH=true uv run agent-memory api # REST on :8000
+DISABLE_AUTH=true uv run agent-memory mcp # MCP (stdio)
+uv run agent-memory task-worker # Background worker
+```
+
+Never set `DISABLE_AUTH=true` outside local development.
diff --git a/docs/for-ais-only/FAILURE_MODES.md b/docs/for-ais-only/FAILURE_MODES.md
new file mode 100644
index 00000000..8a3ba407
--- /dev/null
+++ b/docs/for-ais-only/FAILURE_MODES.md
@@ -0,0 +1,67 @@
+# Failure Modes
+
+Things that look like bugs but are intentional. Read this before "fixing" any
+of them.
+
+## Search uses RedisVL, never raw `redis.ft().search()`
+
+If you see RedisVL `VectorQuery` / `FilterQuery` builders instead of direct
+`redis.ft().search(...)` calls, that is deliberate. The project standardises on
+RedisVL because it owns query construction, type coercion, and embedding
+field handling. Replacing it with raw FT calls will break filter semantics and
+break the project rule.
+
+## Working memory automatically summarises on overflow
+
+Long sessions appear to "lose" earlier messages β they have actually been
+summarised into the working-memory summary field. This is by design: the
+context window is bounded by the configured model. Removing the summarisation
+step will cause downstream prompt-token explosions.
+
+## Promotion to long-term memory is asynchronous
+
+A memory written to working memory is not immediately searchable in
+long-term memory. Promotion runs in the background via Docket. Tests that
+expect synchronous promotion are wrong; use the explicit promotion call or
+wait for the worker.
+
+## Deduplication is content-hash based
+
+Two memories with byte-identical content are intentionally collapsed. Tests
+that insert "duplicates" and expect two records back are wrong. Vary the
+content if you need two records.
+
+## `DISABLE_AUTH=true` is a development-only escape hatch
+
+The REST API is locked down by OAuth2/JWT in every other configuration. Tests
+and local development use `DISABLE_AUTH=true`; production deployments must
+not. Do not "fix" the auth middleware to be optional in production builds.
+
+## All core operations are async
+
+The codebase is async-first. Sync wrappers exist only on the client. Adding a
+synchronous code path inside `agent_memory_server/*` will break the FastAPI +
+Docket event loop assumptions.
+
+## Inline imports are deliberate where they exist
+
+Most imports live at the top of the module. The handful of inline imports
+exist to avoid circular dependencies, optional-dependency import errors, or
+a measurable startup cost. Hoisting them to the top will break one of those.
+
+## Topic and entity extraction are best-effort
+
+`extraction.py` may produce empty topic / entity lists for short or
+ambiguous content. That is expected. Consumers must not assume a non-empty
+result. Do not raise on empty output.
+
+## Tests use `testcontainers` Redis 8
+
+Integration tests start a real Redis 8 container. They require Docker. They
+are slow on cold cache. Do not "speed them up" by mocking Redis β mocked
+tests will not catch RedisVL query regressions.
+
+## Coverage gate failures are not flakes
+
+If CI reports coverage below the project bar, do not retry. The failure is
+real. Either add a test or delete the unreachable branch.
diff --git a/docs/for-ais-only/REPOSITORY_MAP.md b/docs/for-ais-only/REPOSITORY_MAP.md
new file mode 100644
index 00000000..112b50ce
--- /dev/null
+++ b/docs/for-ais-only/REPOSITORY_MAP.md
@@ -0,0 +1,118 @@
+# Repository Map
+
+A module-by-module guide to the Agent Memory Server source tree, written for an
+agent that needs to change something and wants to know where to look.
+
+## Source layout
+
+```
+agent_memory_server/
+ main.py FastAPI application entry point. Builds the app,
+ wires routers, mounts MCP, registers startup hooks.
+ api.py REST endpoints (/v1/working-memory, /v1/long-term-memory,
+ /v1/memory/prompt). Thin layer over working_memory.py
+ and long_term_memory.py.
+ mcp.py Model Context Protocol server. Exposes
+ create_long_term_memories, search_long_term_memory,
+ memory_prompt, set_working_memory tools.
+ cli.py `agent-memory` Click CLI: api, mcp, task-worker,
+ rebuild-index, migrate-memories, schedule-task.
+ config.py Pydantic Settings. Env vars, OAuth2 config,
+ model selection, feature flags.
+ models.py Pydantic data models: WorkingMemory, MemoryRecord,
+ MemoryRecordResult, MemoryMessage, etc.
+ auth.py OAuth2/JWT validation with JWKS. Multi-provider
+ (Auth0, Cognito, Okta, Azure AD).
+ dependencies.py FastAPI dependency-injection helpers.
+ working_memory.py Session-scoped memory: get/set/delete, automatic
+ summarization when context window exceeded.
+ long_term_memory.py Persistent storage with semantic search via RedisVL.
+ Promotion from working memory, deduplication.
+ summarization.py Conversation summarization using configured LLM.
+ summary_views.py Aggregated views over stored memories.
+ extraction.py Topic and entity extraction (BERTopic + NER).
+ filters.py Filter compilation for RedisVL FilterQuery.
+ memory_strategies.py Pluggable strategies for what gets promoted to
+ long-term memory and how.
+ memory_vector_db.py Abstract vector-DB interface.
+ memory_vector_db_factory.py Concrete backend selection (Redis, Pinecone,
+ Chroma, Postgres, ...).
+ working_memory_index.py In-memory index used during working-memory
+ operations.
+ prompt_security.py Prompt-injection guards and safe-prompt helpers.
+ docket_tasks.py Background task definitions (Docket queue).
+ tasks.py Task wiring helpers.
+ migrations.py Schema migrations for stored memory records.
+ healthcheck.py /health endpoint.
+ logging.py Structlog setup.
+ llm/ LiteLLM-based client package.
+ client.py LLMClient with chat() and embed() methods.
+ types.py ChatCompletionResponse, EmbeddingResponse, LLMBackend.
+ embeddings.py Embedding-specific helpers.
+ exceptions.py LLMClientError, ModelValidationError, APIKeyMissingError.
+ utils/ Cross-cutting helpers.
+ redis.py Redis connection setup and pooling.
+ keys.py Redis key naming conventions.
+ api_keys.py API-key utilities.
+ redis_query.py RedisVL query construction helpers.
+ recency.py Recency-boost ranking math.
+ tag_codec.py Tag encoding/decoding for filterable fields.
+ datetime.py Timezone-aware datetime helpers.
+ _aws/ AWS-specific helpers (Bedrock, IAM, Cognito).
+```
+
+## Test layout
+
+```
+tests/
+ test_api.py REST endpoint coverage.
+ test_mcp.py MCP tool coverage.
+ test_working_memory.py Session memory + summarization.
+ test_long_term_memory.py Vector search, promotion, dedup.
+ test_extraction.py Topic + entity extraction.
+ test_summarization.py LLM summarization paths.
+ test_filters.py Filter compilation.
+ test_auth.py JWT/JWKS validation.
+ conftest.py testcontainers Redis fixture, async client fixture.
+```
+
+## Where features live
+
+| Feature | Module(s) |
+|---|---|
+| Store/retrieve a working-memory session | `api.py` β `working_memory.py` β `utils/redis.py` |
+| Search long-term memory | `api.py` β `long_term_memory.py` β `filters.py` β `utils/redis_query.py` |
+| Promote working β long-term memory | `working_memory.py` β `memory_strategies.py` β `long_term_memory.py` |
+| Summarize a conversation | `working_memory.py` β `summarization.py` β `llm/client.py` |
+| Extract topics & entities | `extraction.py` β `llm/client.py` |
+| Hydrate a prompt with relevant memories | `api.py` (`/v1/memory/prompt`) β `long_term_memory.py` |
+| MCP tool surface | `mcp.py` β same business-logic modules as REST |
+| Auth on every request | `dependencies.py` β `auth.py` |
+| Background indexing & compaction | `docket_tasks.py` β `long_term_memory.py` |
+| Choose a vector backend | `memory_vector_db_factory.py` β `memory_vector_db.py` |
+
+## What to read before changing X
+
+- **Search behavior.** Read `long_term_memory.py` for the query path, then
+ `filters.py` for filter semantics, then `utils/redis_query.py` for the actual
+ RedisVL builders. Project rule: never call `redis.ft().search()` directly β
+ always use RedisVL `VectorQuery` / `FilterQuery`.
+- **A new endpoint.** Add the route in `api.py`, the model in `models.py`, the
+ business logic in the appropriate `*_memory.py` module. Mirror it in `mcp.py`
+ if it should also be an MCP tool.
+- **Authentication.** `auth.py` is the JWKS validator; `dependencies.py` is how
+ routes opt in. `DISABLE_AUTH=true` is a development-only escape hatch.
+- **A new LLM/embedding provider.** Configure via env (LiteLLM resolves it);
+ no code changes unless you need provider-specific features β then extend
+ `llm/client.py`.
+- **A new vector-DB backend.** Implement the `memory_vector_db.py` interface
+ and register it in `memory_vector_db_factory.py`.
+
+## What is intentionally not exported
+
+- `agent_memory_server._aws.*` β AWS-specific helpers used by the Bedrock path;
+ not part of the public contract.
+- `agent_memory_server.utils.*` β internal helpers; tests may import them but
+ they are not stable across versions.
+- `agent_memory_server.working_memory_index` β implementation detail of the
+ working-memory store.
diff --git a/docs/for-ais-only/index.md b/docs/for-ais-only/index.md
new file mode 100644
index 00000000..e348c2ac
--- /dev/null
+++ b/docs/for-ais-only/index.md
@@ -0,0 +1,53 @@
+---
+description: Internal AI-agent guide to the Agent Memory Server source tree.
+---
+
+# For AI Agents Modifying Agent Memory
+
+This section is the internal counterpart to the user-facing
+[AGENTS.md](https://github.com/redis/agent-memory-server/blob/main/AGENTS.md).
+It exists for an agent that has been asked to *change* the library: add a
+new feature, fix a bug, extend a subsystem.
+
+Start with the [**Repository map**](REPOSITORY_MAP.md) to find the
+subsystem you need. Run [**Build and test**](BUILD_AND_TEST.md) before
+and after any change. If something looks broken, check
+[**Failure modes**](FAILURE_MODES.md) before assuming it's a bug β
+several behaviors are intentional and documented there.
+
+
+
+- :material-map:{ .lg .middle } **[Repository map](REPOSITORY_MAP.md)**
+
+ ---
+
+ Top-down map of every package and module with its responsibility.
+
+- :material-hammer-wrench:{ .lg .middle } **[Build and test](BUILD_AND_TEST.md)**
+
+ ---
+
+ The exact commands CI runs, plus the local equivalents.
+
+- :material-alert-circle:{ .lg .middle } **[Failure modes](FAILURE_MODES.md)**
+
+ ---
+
+ Intentional behaviors that look like bugs and where they live.
+
+- :material-book-edit:{ .lg .middle } **[Authoring standard](AUTHORING_STANDARD.md)**
+
+ ---
+
+ System prompt for generating or revising docs in this repo.
+
+
+
+## Decision tree
+
+| Task | Read first |
+|---|---|
+| Run tests | [Build and test](BUILD_AND_TEST.md) |
+| Diagnose "this looks broken" | [Failure modes](FAILURE_MODES.md) before assuming a bug |
+| Find a subsystem | [Repository map](REPOSITORY_MAP.md) |
+| Write or revise docs | [Authoring standard](AUTHORING_STANDARD.md) |
diff --git a/docs/getting-started-index.md b/docs/getting-started-index.md
deleted file mode 100644
index 32cdfa41..00000000
--- a/docs/getting-started-index.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# Getting Started
-
-Get up and running with Redis Agent Memory Server. Whether you want a quick 5-minute setup or a comprehensive installation guide, start here.
-
-
-
-- π **Quick Start**
-
- ---
-
- Get a working memory server in 5 minutes with the Python SDK
-
- [Quick Start Guide β](quick-start.md)
-
-- π¦ **Installation**
-
- ---
-
- Complete installation options: CLI, Docker Compose, and production setup
-
- [Installation Guide β](getting-started.md)
-
-- π‘ **Use Cases**
-
- ---
-
- Real-world examples across industries and applications
-
- [Explore Use Cases β](use-cases.md)
-
-
-
-## Recommended Path
-
-**New to memory systems?** Start with the [Quick Start Guide](quick-start.md) to understand the basics and see immediate results.
-
-**Ready for production?** Jump to the [Installation Guide](getting-started.md) for Docker Compose setup and worker configuration.
diff --git a/docs/index.md b/docs/index.md
index f46e5266..e617c77f 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,47 +1,81 @@
-# Redis Agent Memory Server
+---
+description: Agent Memory Server documentation. Session Memory and Long-Term Memory for AI Agents.
+---
+
+
+
+{ .rds-hero__logo }
+
+# Agent Memory Server
-**Give your AI agents persistent memory and context that gets smarter over time.**
+Session Memory and Long-Term Memory for AI Agents
+{: .rds-hero__tagline }
-Transform your AI agents from goldfish π into elephants π with Redis-powered memory that automatically learns, organizes, and recalls information across conversations and sessions.
+
-- π **Quick Start**
+- :material-rocket-launch:{ .lg .middle } **[Quick Start](user_guide/01_quick_start.md)**
---
- Get up and running in 5 minutes with our step-by-step guide
+ Get a memory-enabled agent running in 5 minutes.
+
+- :material-target:{ .lg .middle } **[Use Cases](examples/use_cases.md)**
- [Quick Start Guide β](quick-start.md)
+ ---
-- π§ **Use Cases**
+ See what you can build: support bots, tutors, personal assistants.
+
+- :material-language-python:{ .lg .middle } **[Python SDK](api/python_sdk.md)**
---
- See real-world examples across industries and applications
+ Async-first client with OpenAI and Anthropic tool integration.
+
+
+
+---
+
+## Explore the Docs
+
+
+
+- :material-book-open-variant:{ .lg .middle } **[Concepts](concepts/index.md)**
- [Explore Use Cases β](use-cases.md)
+ ---
-- π **Python SDK**
+ The memory model. Working memory, long-term memory, lifecycle, extraction, summarization.
+
+- :material-rocket-launch:{ .lg .middle } **[User Guide](user_guide/index.md)**
---
- Easy integration with tool abstractions for OpenAI and Anthropic
+ Tutorials and how-to recipes. Installation, auth, providers, vector DB, integration patterns.
- [SDK Documentation β](python-sdk.md)
+- :material-lightbulb-on:{ .lg .middle } **[Examples](examples/index.md)**
+ ---
+
+ Runnable agent patterns: travel agent, AI tutor, memory editor, LangChain integration.
+
+- :material-api:{ .lg .middle } **[API Reference](api/index.md)**
+
+ ---
+
+ REST, MCP, CLI, SDKs, plus the full `agent_memory_server` Python package.
-## What is Redis Agent Memory Server?
+## What is Agent Memory Server?
-Redis Agent Memory Server is a production-ready memory system for AI agents and applications that:
+Agent Memory Server is a production-ready memory system for AI agents and applications that:
- **π§ Remembers everything**: Stores conversation history, user preferences, and important facts across sessions
- **π Finds relevant context**: Uses semantic, keyword, and hybrid search to surface the right information at the right time
- **π Gets smarter over time**: Automatically extracts, organizes, and deduplicates memories from interactions
- **π Works with any AI model**: REST API and MCP interfaces compatible with OpenAI, Anthropic, and others
-- **π Multi-provider support**: Use [100+ LLM providers](llm-providers.md) via LiteLLM (OpenAI, Anthropic, AWS Bedrock, Ollama, Azure, Gemini, and more)
+- **π Multi-provider support**: Use [100+ LLM providers](user_guide/how_to_guides/llm_providers.md) via LiteLLM (OpenAI, Anthropic, AWS Bedrock, Ollama, Azure, Gemini, and more)
## Why Use It?
@@ -99,47 +133,50 @@ print(f"Found: {results.memories[0].text}")
- Advanced filtering by time, topics, entities, users
### π Intelligent Search
+
- **Multiple search modes**: Semantic (vector similarity), keyword (full-text), and hybrid (combined) search
- **Advanced filters**: Search by user, session, time, topics, entities
- **Query optimization**: AI-powered query refinement for better results
- **Recency boost**: Time-aware ranking that surfaces relevant recent information
### β¨ Smart Memory Management
+
- **Automatic extraction**: Pull important facts from conversations
- **Contextual grounding**: Resolve pronouns and references ("he" β "John")
- **Deduplication**: Prevent duplicate memories with content hashing
- **Memory editing**: Update, correct, or enrich existing memories
### π Production Ready
+
- **Multiple interfaces**: REST API, MCP server, Python client
- **Authentication**: OAuth2/JWT, token-based, or disabled for development
- **Scalable storage**: Redis (default), Pinecone, Chroma, PostgreSQL, and more
- **Background processing**: Async tasks for heavy operations
- **Multi-tenancy**: User and namespace isolation
-## Get Started
+## Reader Paths
-Ready to give your AI agents perfect memory?
+**π New to memory systems?** β [Quick Start](user_guide/01_quick_start.md) β [Use Cases](examples/use_cases.md) β [Long-Term Memory](concepts/long_term_memory.md)
+**π§ Ready to integrate?** β [Installation](user_guide/02_installation.md) β [REST API](api/rest.md) β [Configuration](user_guide/how_to_guides/configuration.md) β [Authentication](user_guide/how_to_guides/authentication.md)
+**π€ Building an AI agent?** β [MCP Server](api/mcp.md) β [Memory Lifecycle](concepts/memory_lifecycle.md) β [Query Optimization](user_guide/how_to_guides/query_optimization.md)
-
+## Get Started
-
-**New to memory systems?**
+
-Start with our quick tutorial to understand the basics and see immediate results.
+[:material-rocket-launch: New to memory systems?](user_guide/01_quick_start.md){ .md-button .md-button--primary }
+[:material-api: Ready to integrate?](user_guide/index.md){ .md-button }
-[π Quick Start Guide](quick-start.md){ .md-button .md-button--primary }
-
-**Ready to integrate?**
+## For AI agents
-Jump into the Developer Guide for memory patterns and integration strategies.
-
-[π§ Developer Guide](memory-integration-patterns.md){ .md-button }
-
-
-
+If you are an AI agent reading these docs, start with
+[`AGENTS.md`](https://github.com/redis/agent-memory-server/blob/main/AGENTS.md)
+at the repo root for usage notes, or
+[For AI Agents](for-ais-only/index.md) for an internal map of the source
+tree. A flat [`llms.txt`](https://ai.redis.io/agent-memory/llms.txt)
+index of every doc page is generated at build time.
---
@@ -149,7 +186,3 @@ Jump into the Developer Guide for memory patterns and integration strategies.
- **π³ Docker Images**: [Docker Hub](https://hub.docker.com/r/redislabs/agent-memory-server)
- **π Issues**: [Report Issues](https://github.com/redis/agent-memory-server/issues)
- **π Examples**: [Complete Examples](https://github.com/redis/agent-memory-server/tree/main/examples)
-
----
-
-**Ready to transform your AI agents?** Start with the [Quick Start Guide](quick-start.md) and build smarter agents in minutes! π§ β¨
diff --git a/docs/javascripts/redis-ai-hub-header.js b/docs/javascripts/redis-ai-hub-header.js
new file mode 100644
index 00000000..d4d0671b
--- /dev/null
+++ b/docs/javascripts/redis-ai-hub-header.js
@@ -0,0 +1,87 @@
+// Redis AI Hub: shared header injector
+// Renders a persistent top bar on every per-library docs site.
+// In production, this would be injected by the central host (CDN edge or reverse proxy).
+// In the prototype, each site bundles this JS and injects on DOMContentLoaded.
+
+(function () {
+ const HUB_URL = (window.REDIS_AI_HUB_URL || '/').replace(/\/+$/, '/') || '/';
+ const CURRENT = window.REDIS_AI_HUB_LIBRARY || '';
+
+ const LIBRARIES = {
+ core: [
+ { slug: 'redisvl', name: 'RedisVL', path: 'redisvl/' },
+ { slug: 'agent-memory', name: 'Agent Memory', path: 'agent-memory/' },
+ { slug: 'agent-kit', name: 'Agent Kit', path: 'agent-kit/' },
+ { slug: 'sre-agent', name: 'SRE Agent', path: 'sre-agent/' },
+ ],
+ experimental: [
+ { slug: 'sql', name: 'SQL for Redis', path: 'sql/' },
+ { slug: 'optimizer', name: 'Retrieval Optimizer', path: 'optimizer/' },
+ ],
+ integration: [
+ { slug: 'adk', name: 'Google ADK', path: 'adk/' },
+ { slug: 'langgraph', name: 'LangGraph', path: 'langgraph/' },
+ { slug: 'langchain', name: 'LangChain', path: 'langchain/' },
+ { slug: 'recipes', name: 'AI Recipes', path: 'recipes/' },
+ ],
+ };
+
+ function dropdown(label, items) {
+ const links = items.map(it => {
+ const isCurrent = it.slug === CURRENT;
+ return `${it.name}`;
+ }).join('');
+ return `
+
-
-## Quick Reference
-
-| Topic | Description |
-|-------|-------------|
-| [Configuration](configuration.md) | All environment variables and YAML settings |
-| [Worker timeout tuning](configuration.md#worker-lease-and-task-timeout) | How to size task timeout vs redelivery timeout for Docket workers |
-| [Authentication](authentication.md) | OAuth2, token auth, and development mode |
-| [Security](security-custom-prompts.md) | Custom prompt security and best practices |
-| [LLM Providers](llm-providers.md) | Generation models including AWS Bedrock |
-| [Embedding Providers](embedding-providers.md) | Embedding models and dimensions |
-| [Memory Vector Databases](custom-memory-vector-db.md) | Storage backend configuration |
-
-## Where to Start
-
-**Deploying to production?** Start with [Configuration](configuration.md) to understand all server settings.
-
-**Setting up authentication?** See [Authentication](authentication.md) for OAuth2 or token-based auth.
-
-**Using AWS?** The [LLM Providers](llm-providers.md) guide covers AWS Bedrock setup for both generation and embedding models.
-
-**Customizing storage?** Check [Memory Vector Databases](custom-memory-vector-db.md) for Redis and custom backend options.
diff --git a/docs/python-sdk-index.md b/docs/python-sdk-index.md
deleted file mode 100644
index a22f54b8..00000000
--- a/docs/python-sdk-index.md
+++ /dev/null
@@ -1,54 +0,0 @@
-# Python SDK
-
-The Python SDK provides a simple, async-first interface for integrating memory into your AI applications. It includes client libraries, tool schemas for LLMs, and framework integrations.
-
-
-
-- π **SDK Documentation**
-
- ---
-
- Complete API reference for the Python client library
-
- [SDK Reference β](python-sdk.md)
-
-- π¦ **LangChain Integration**
-
- ---
-
- Use memory with LangChain agents and chains
-
- [LangChain Guide β](langchain-integration.md)
-
-- βοΈ **Configuration**
-
- ---
-
- Environment variables and configuration options
-
- [Configuration β](configuration.md)
-
-
-
-## Installation
-
-```bash
-pip install agent-memory-client
-```
-
-## Quick Example
-
-```python
-from agent_memory_client import MemoryAPIClient, MemoryClientConfig
-
-client = MemoryAPIClient(MemoryClientConfig(base_url="http://localhost:8000"))
-
-# Get memory-enriched context for your LLM
-context = await client.memory_prompt(
- query="What restaurants should I try?",
- session_id="chat_123",
- long_term_search={"text": "food preferences", "limit": 5}
-)
-```
-
-See the [SDK Documentation](python-sdk.md) for complete usage examples.
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index cd06070d..b16561f6 100644
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -1,4 +1,4 @@
-/* Custom styles for Redis Agent Memory Server documentation */
+/* Custom styles for Agent Memory Server documentation */
/* Code block improvements */
.highlight pre {
@@ -20,6 +20,29 @@ table th {
font-weight: 500;
}
+/* Left sidebar (sections nav) scrolls independently when the nav is taller
+ * than the viewport. Material's defaults handle this on long pages, but with
+ * navigation.sections expanded across many sections (User Guide, How-To,
+ * API Reference, Server package) the nav can exceed viewport height while
+ * the page itself is short β leaving the bottom of the sidebar unreachable.
+ * Constrain the scrollwrap to viewport-minus-header and force overflow.
+ *
+ * Header heights mirror Material defaults: 2.4rem header + 2.4rem tabs on
+ * desktop, 2.4rem header alone when tabs are absent. We target the larger
+ * value to be safe; a couple of extra rems of breathing room costs nothing.
+ */
+@media screen and (min-width: 76.25em) {
+ .md-sidebar--primary .md-sidebar__scrollwrap {
+ max-height: calc(100vh - 5.5rem);
+ overflow-y: auto;
+ scrollbar-gutter: stable;
+ }
+ .md-sidebar--secondary .md-sidebar__scrollwrap {
+ max-height: calc(100vh - 5.5rem);
+ overflow-y: auto;
+ }
+}
+
/* Highlight new features */
.md-content h3:has-text("New in v0.10.0") {
color: var(--md-accent-fg-color);
@@ -55,3 +78,36 @@ table th {
.highlight .language-yaml {
border-left: 4px solid var(--md-accent-fg-color);
}
+
+/* mkdocs-jupyter rendering: leave JupyterLab's defaults intact, but draw
+ * explicit dividers so the reader can tell at a glance:
+ * 1. where a prose (markdown) cell ends and a code cell begins (and
+ * vice versa), and
+ * 2. where a code cell's input ends and its output begins.
+ */
+.jupyter-wrapper .jp-MarkdownCell + .jp-CodeCell,
+.jupyter-wrapper .jp-CodeCell + .jp-MarkdownCell,
+.jupyter-wrapper .jp-MarkdownCell + .jp-RawCell,
+.jupyter-wrapper .jp-RawCell + .jp-MarkdownCell {
+ border-top: 1px solid var(--md-default-fg-color--lightest);
+ margin-top: 1rem;
+ padding-top: 1rem;
+}
+
+.jupyter-wrapper .jp-CodeCell .jp-Cell-outputWrapper {
+ border-top: 1px dashed var(--md-default-fg-color--lighter);
+ margin-top: 0.5rem;
+ padding-top: 0.5rem;
+}
+
+/* Layout: pin the left sidebar to the viewport's left edge and the right
+ * TOC to the viewport's right edge by removing Material's centered grid
+ * cap. Sidebars keep their default 12.1rem widths; the content column
+ * absorbs all remaining space. Header/tabs use the same grid so they
+ * also span full width, keeping the layout consistent.
+ */
+@media screen and (min-width: 76.25em) {
+ .md-grid {
+ max-width: none;
+ }
+}
diff --git a/docs/stylesheets/redis-ai-hub-header.css b/docs/stylesheets/redis-ai-hub-header.css
new file mode 100644
index 00000000..3d23604f
--- /dev/null
+++ b/docs/stylesheets/redis-ai-hub-header.css
@@ -0,0 +1,194 @@
+/* Redis AI Hub: shared header + brand tokens
+ * Mirrors redis.io typography (Space Grotesk display, Inter body, JetBrains
+ * Mono code) and brand palette (Redis red #DC382C, Midnight #091A23).
+ */
+@import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Space+Grotesk:wght@500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap");
+
+:root {
+ --rds-red: #DC382C;
+ --rds-red-hover: #B82A20;
+ --rds-red-bright: #FF4438;
+ --rds-midnight: #091A23;
+ --rds-ink: #161F31;
+ --rds-slate: #2D4754;
+ --rds-mute: #B9C2C6;
+ --rds-line: #E8EBEC;
+ --rds-bg: #FFFFFF;
+ --rds-font-display: "Space Grotesk", -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+ --rds-font-body: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, system-ui, sans-serif;
+ --rds-font-mono: "JetBrains Mono", "SF Mono", Menlo, Consolas, monospace;
+}
+
+#rah-header {
+ position: sticky;
+ top: 0;
+ z-index: 9999;
+ background: var(--rds-bg);
+ color: var(--rds-midnight);
+ font-family: var(--rds-font-body);
+ border-bottom: 1px solid var(--rds-line);
+}
+html[data-theme="dark"] #rah-header {
+ background: var(--rds-midnight);
+ color: var(--rds-line);
+ border-bottom-color: var(--rds-slate);
+}
+
+.rah-bar {
+ display: flex;
+ align-items: center;
+ gap: 24px;
+ padding: 12px 24px;
+ max-width: 100%;
+}
+
+.rah-brand {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ color: var(--rds-midnight) !important;
+ text-decoration: none !important;
+ font-family: var(--rds-font-display);
+ font-weight: 600;
+ font-size: 15px;
+ letter-spacing: -0.01em;
+ white-space: nowrap;
+}
+html[data-theme="dark"] .rah-brand { color: #fff !important; }
+.rah-brand:hover { opacity: 0.85; }
+
+.rah-nav { display: flex; align-items: center; gap: 4px; flex: 1; }
+
+.rah-dropdown { position: relative; }
+.rah-dropdown-btn,
+.rah-link {
+ background: none;
+ border: none;
+ color: #4A5C66;
+ font-family: var(--rds-font-body);
+ font-size: 14px;
+ padding: 6px 12px;
+ cursor: pointer;
+ border-radius: 4px;
+ text-decoration: none !important;
+ font-weight: 500;
+}
+html[data-theme="dark"] .rah-dropdown-btn,
+html[data-theme="dark"] .rah-link { color: var(--rds-mute); }
+.rah-dropdown-btn:hover,
+.rah-link:hover { background: rgba(9,26,35,0.05); color: var(--rds-midnight); }
+html[data-theme="dark"] .rah-dropdown-btn:hover,
+html[data-theme="dark"] .rah-link:hover { background: rgba(255,255,255,0.06); color: #fff; }
+.rah-caret { font-size: 10px; opacity: 0.6; }
+
+.rah-dropdown-menu {
+ display: none;
+ position: absolute;
+ top: 100%;
+ left: 0;
+ margin-top: 4px;
+ background: var(--rds-bg);
+ border: 1px solid var(--rds-line);
+ border-radius: 8px;
+ min-width: 200px;
+ padding: 6px;
+ box-shadow: 0 12px 28px rgba(9,26,35,0.10);
+}
+html[data-theme="dark"] .rah-dropdown-menu {
+ background: var(--rds-ink);
+ border-color: var(--rds-slate);
+ box-shadow: 0 12px 28px rgba(0,0,0,0.5);
+}
+.rah-dropdown:hover .rah-dropdown-menu,
+.rah-dropdown:focus-within .rah-dropdown-menu { display: block; }
+
+.rah-item {
+ display: block;
+ padding: 8px 12px;
+ color: var(--rds-midnight) !important;
+ text-decoration: none !important;
+ border-radius: 4px;
+ font-size: 13.5px;
+}
+html[data-theme="dark"] .rah-item { color: var(--rds-line) !important; }
+.rah-item:hover { background: rgba(220,56,44,0.08); color: var(--rds-red) !important; }
+.rah-item--active { color: var(--rds-red) !important; font-weight: 600; }
+
+.rah-actions { display: flex; gap: 10px; align-items: center; }
+.rah-search {
+ background: rgba(9,26,35,0.04);
+ border: 1px solid var(--rds-line);
+ color: #4A5C66;
+ padding: 6px 12px;
+ border-radius: 6px;
+ font-size: 13px;
+ cursor: pointer;
+ font-family: inherit;
+}
+html[data-theme="dark"] .rah-search {
+ background: rgba(255,255,255,0.06);
+ border-color: var(--rds-slate);
+ color: var(--rds-mute);
+}
+.rah-search:hover { background: rgba(9,26,35,0.08); color: var(--rds-midnight); }
+html[data-theme="dark"] .rah-search:hover { background: rgba(255,255,255,0.12); color: #fff; }
+.rah-gh {
+ color: #4A5C66 !important;
+ text-decoration: none !important;
+ font-size: 13px;
+ padding: 6px 10px;
+ border-radius: 4px;
+}
+html[data-theme="dark"] .rah-gh { color: var(--rds-mute) !important; }
+.rah-gh:hover { color: var(--rds-midnight) !important; background: rgba(9,26,35,0.05); }
+html[data-theme="dark"] .rah-gh:hover { color: #fff !important; background: rgba(255,255,255,0.06); }
+
+.rah-tabs {
+ display: flex;
+ gap: 0;
+ padding: 0 24px;
+ border-top: 1px solid var(--rds-line);
+ background: #FAFBFC;
+ overflow-x: auto;
+}
+html[data-theme="dark"] .rah-tabs {
+ border-top-color: var(--rds-slate);
+ background: var(--rds-ink);
+}
+.rah-tab {
+ color: #6B7A82 !important;
+ text-decoration: none !important;
+ padding: 10px 16px;
+ font-size: 13px;
+ border-bottom: 2px solid transparent;
+ white-space: nowrap;
+ font-weight: 500;
+}
+html[data-theme="dark"] .rah-tab { color: #8A99A0 !important; }
+.rah-tab:hover { color: var(--rds-midnight) !important; }
+html[data-theme="dark"] .rah-tab:hover { color: var(--rds-line) !important; }
+.rah-tab--active {
+ color: var(--rds-red) !important;
+ border-bottom-color: var(--rds-red);
+ font-weight: 600;
+}
+
+/* Apply redis.io fonts to the host Sphinx theme too */
+body,
+.bd-container,
+.bd-content,
+.bd-sidebar-primary,
+.bd-sidebar-secondary {
+ font-family: var(--rds-font-body);
+}
+h1, h2, h3, h4, h5, h6,
+.bd-page-width h1, .bd-page-width h2, .bd-page-width h3 {
+ font-family: var(--rds-font-display);
+ letter-spacing: -0.015em;
+}
+code, kbd, pre, samp,
+.highlight pre {
+ font-family: var(--rds-font-mono);
+}
+
+body { padding-top: 0; }
diff --git a/docs/stylesheets/redis-brand.css b/docs/stylesheets/redis-brand.css
new file mode 100644
index 00000000..9e44fde7
--- /dev/null
+++ b/docs/stylesheets/redis-brand.css
@@ -0,0 +1,79 @@
+/* Redis brand tokens and Material theme overrides for agent-memory-server docs.
+ * Mirrors the redis-docs tailwind palette (Redis red #FF4438, Redis ink
+ * #091A23) and self-hosts the Space Grotesk + Space Mono pairing used on
+ * redis.io.
+ */
+@import url("https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=Space+Mono:wght@400;700&display=swap");
+
+:root {
+ /* Mirrors redis-docs tailwind.config.js. */
+ --rds-red: #FF4438; /* redis-red-500: primary brand red */
+ --rds-red-hover: #D52D1F; /* redis-red-600: hover/pressed */
+ --rds-red-bright: #E4291E; /* redis-red-700 */
+ --rds-midnight: #091A23; /* redis-ink-900 */
+ --rds-ink: #161F31; /* midnight-700 */
+ --rds-slate: #2D4754; /* redis-pen-700 */
+ --rds-mute: #B9C2C6; /* redis-pen-300 */
+ --rds-line: #E8EBEC; /* redis-pen-200 */
+ --rds-bg: #FFFFFF;
+}
+
+/* Wire the Redis red into Material's primary/accent slots so the top bar,
+ * search bar, links, and active nav items pick it up. */
+:root,
+[data-md-color-scheme="default"],
+[data-md-color-scheme="slate"] {
+ --md-primary-fg-color: var(--rds-red);
+ --md-primary-fg-color--light: #FF6B5F;
+ --md-primary-fg-color--dark: var(--rds-red-hover);
+ --md-accent-fg-color: var(--rds-red);
+ --md-accent-fg-color--transparent: rgba(255, 68, 56, 0.1);
+}
+
+/* Bold every top-level entry in the left sidebar. With navigation.sections,
+ * group labels (Concepts, User Guide, ...) get the section-title treatment,
+ * but single-page top-level items like Home stay regular weight. This rule
+ * gives them the same visual weight as the section headers. */
+.md-nav--primary > .md-nav__list > .md-nav__item > .md-nav__link {
+ font-weight: 700;
+}
+
+/* Landing-page hero: Redis script logo stacked over the wordmark and tagline.
+ * Mirrors the marketing card used on docs.redisvl.com hand-offs. */
+.rds-hero {
+ text-align: center;
+ margin: 1.5rem auto 2.5rem;
+ padding: 0 1rem;
+}
+
+.rds-hero__logo {
+ display: block;
+ margin: 0 auto 0.75rem;
+ width: clamp(180px, 32vw, 280px);
+ aspect-ratio: 85 / 27;
+ height: auto;
+}
+
+.rds-hero h1 {
+ margin: 0;
+ font-weight: 700;
+ font-size: clamp(1.5rem, 3.2vw, 2.125rem);
+ line-height: 1.15;
+ color: var(--rds-midnight);
+ letter-spacing: -0.01em;
+}
+
+[data-md-color-scheme="slate"] .rds-hero h1 {
+ color: #F2F4F5;
+}
+
+.rds-hero__tagline {
+ margin: 0.5rem 0 0;
+ font-size: clamp(1rem, 2vw, 1.25rem);
+ color: var(--rds-slate);
+ font-weight: 400;
+}
+
+[data-md-color-scheme="slate"] .rds-hero__tagline {
+ color: var(--rds-mute);
+}
diff --git a/docs/quick-start.md b/docs/user_guide/01_quick_start.md
similarity index 94%
rename from docs/quick-start.md
rename to docs/user_guide/01_quick_start.md
index d4490c01..01da550c 100644
--- a/docs/quick-start.md
+++ b/docs/user_guide/01_quick_start.md
@@ -1,6 +1,13 @@
# Quick Start Guide
-Get up and running with Redis Agent Memory Server in 5 minutes. This guide shows you how to build memory-enabled AI applications using the Python SDK, with REST API examples as backup.
+Get up and running with Agent Memory Server in 5 minutes. This guide shows you how to build memory-enabled AI applications using the Python SDK, with REST API examples as backup.
+
+!!! info "Need a longer setup walkthrough?"
+ This guide installs everything inline and assumes you're comfortable
+ with `pip` and Docker. If you'd rather see the full installation
+ options first β Docker Compose, manual install, native macOS without
+ Docker, or production deployment β start with the
+ [Getting started guide](02_installation.md) and come back here.
## What You'll Learn
@@ -340,12 +347,12 @@ Now that you have the basics working, explore these advanced features:
### π **Advanced Search**
- Try filtering by topics, entities, or time ranges
- Experiment with recency boost and query optimization
-- See [Working Memory](working-memory.md) and [Long-term Memory](long-term-memory.md) guides for detailed examples
+- See [Working Memory](../concepts/working_memory.md) and [Long-term Memory](../concepts/long_term_memory.md) guides for detailed examples
### βοΈ **Memory Editing**
- Update existing memories with corrections
- Add more context to sparse memories
-- See [Memory Lifecycle Guide](memory-lifecycle.md#memory-editing)
+- See [Memory Editing Guide](how_to_guides/memory_editing.md)
### π **Production Setup**
- Enable authentication (OAuth2/JWT or token-based)
@@ -401,10 +408,10 @@ uv run agent-memory task-worker --concurrency 5 &
3. **Start MCP server (if using SSE or streamable HTTP mode):**
```bash
-# Production MCP server β SSE (uses Docket backend)
+# Production MCP server - SSE (uses Docket backend)
uv run agent-memory mcp --mode sse --port 9000 --task-backend docket
-# Production MCP server β streamable HTTP (uses Docket backend)
+# Production MCP server - streamable HTTP (uses Docket backend)
uv run agent-memory mcp --mode streamable-http --port 9000 --task-backend docket
```
@@ -529,8 +536,8 @@ redis-cli -h localhost -p 6379
## Get Help
- **API Documentation**: Visit `http://localhost:8000/docs`
-- **Configuration Guide**: [Configuration](configuration.md)
-- **Memory Types**: [Working Memory](working-memory.md) and [Long-term Memory](long-term-memory.md)
+- **Configuration Guide**: [Configuration](how_to_guides/configuration.md)
+- **Memory Types**: [Working Memory](../concepts/working_memory.md) and [Long-term Memory](../concepts/long_term_memory.md)
- **GitHub Issues**: Report problems or ask questions
## What's Next?
diff --git a/docs/getting-started.md b/docs/user_guide/02_installation.md
similarity index 95%
rename from docs/getting-started.md
rename to docs/user_guide/02_installation.md
index 0dd5f5c9..7c13da80 100644
--- a/docs/getting-started.md
+++ b/docs/user_guide/02_installation.md
@@ -18,7 +18,7 @@ pip install uv
uv sync
```
-3. Set up environment variables (see [Configuration](configuration.md) section)
+3. Set up environment variables (see [Configuration](how_to_guides/configuration.md) section)
## Running
@@ -82,7 +82,7 @@ When configuring MCP-enabled apps (e.g., Claude Desktop), prefer `uvx` so the ap
```
Notes:
-- API keys: Default models use OpenAI. Set `OPENAI_API_KEY`. To use Anthropic instead, set `ANTHROPIC_API_KEY` and also `GENERATION_MODEL` to an Anthropic model (e.g., `claude-3-5-haiku-20241022`). If you have access to GPT-5 models, you can instead set `GENERATION_MODEL` to `gpt-5.2-chat-latest`, `gpt-5.1-chat-latest`, `gpt-5-mini`, or `gpt-5-nano`. See [LLM Providers](llm-providers.md) for all supported providers.
+- API keys: Default models use OpenAI. Set `OPENAI_API_KEY`. To use Anthropic instead, set `ANTHROPIC_API_KEY` and also `GENERATION_MODEL` to an Anthropic model (e.g., `claude-3-5-haiku-20241022`). If you have access to GPT-5 models, you can instead set `GENERATION_MODEL` to `gpt-5.2-chat-latest`, `gpt-5.1-chat-latest`, `gpt-5-mini`, or `gpt-5-nano`. See [LLM Providers](how_to_guides/llm_providers.md) for all supported providers.
- Make sure your MCP host can find `uvx` (on its PATH or by using an absolute command path). macOS: `brew install uv`. If not on PATH, set `"command"` to an absolute path (e.g., `/opt/homebrew/bin/uvx` on Apple Silicon, `/usr/local/bin/uvx` on Intel macOS).
- For production, remove `DISABLE_AUTH` and configure auth.
diff --git a/docs/user_guide/03_no_docker_setup.md b/docs/user_guide/03_no_docker_setup.md
new file mode 100644
index 00000000..ad58d4aa
--- /dev/null
+++ b/docs/user_guide/03_no_docker_setup.md
@@ -0,0 +1,233 @@
+# Running Agent Memory Server on macOS (No Docker)
+
+Natively on macOS, including Apple Silicon M-series. No Docker required.
+
+## Prerequisites
+
+- macOS (Intel or Apple Silicon)
+- Homebrew (https://brew.sh)
+- An LLM provider (one of):
+ - **OpenAI API key** (easiest), or
+ - **Ollama** (fully local, no API key needed)
+
+---
+
+## Part 1: Redis
+
+Agent Memory Server uses Redis as its database. Install and start it:
+
+```bash
+brew install redis
+brew services start redis
+```
+
+Verify:
+```bash
+redis-cli ping
+# PONG
+```
+
+---
+
+## Part 2: Agent Memory Server
+
+### Install
+
+```bash
+brew install python@3.12
+git clone https://github.com/redis/agent-memory-server.git
+cd agent-memory-server
+pip install uv
+make setup
+```
+
+### Configure
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with **one** of the following configurations:
+
+**Option A: OpenAI (cloud)**
+```
+REDIS_URL=redis://localhost:6379
+OPENAI_API_KEY=
+LONG_TERM_MEMORY=true
+GENERATION_MODEL=gpt-4o-mini
+EMBEDDING_MODEL=text-embedding-3-small
+DISABLE_AUTH=true
+```
+
+**Option B: Ollama (fully local, no API key)**
+
+First install and start Ollama:
+```bash
+brew install ollama
+ollama serve # Start Ollama server (keep running)
+ollama pull llama3.2 # Pull a generation model
+ollama pull nomic-embed-text # Pull an embedding model
+```
+
+Then set `.env`:
+```
+REDIS_URL=redis://localhost:6379
+OLLAMA_API_BASE=http://localhost:11434
+GENERATION_MODEL=ollama/llama3.2
+EMBEDDING_MODEL=ollama/nomic-embed-text
+REDISVL_VECTOR_DIMENSIONS=768
+LONG_TERM_MEMORY=true
+DISABLE_AUTH=true
+```
+
+> **Note:** When using Ollama, you must set `REDISVL_VECTOR_DIMENSIONS` to match your embedding model (nomic-embed-text = 768, mxbai-embed-large = 1024).
+
+### Build the search index
+
+```bash
+source .venv/bin/activate
+uv run agent-memory rebuild-index
+```
+
+### Run
+
+Pick what you need. Each runs in its own terminal.
+
+**MCP Server** (for AI agent integration, e.g. Orchestrate, Cursor, Claude Desktop):
+```bash
+source .venv/bin/activate
+uv run agent-memory mcp --mode sse --port 9000
+```
+
+**REST API** (optional, for HTTP clients):
+```bash
+source .venv/bin/activate
+uv run agent-memory api
+```
+
+**Background task worker** (optional, for async extraction/compaction):
+```bash
+source .venv/bin/activate
+uv run agent-memory task-worker
+```
+
+### Verify
+
+```bash
+# MCP server
+curl -s http://localhost:9000/sse -H "Accept: text/event-stream" --max-time 3
+# Expected: event: endpoint ...
+
+# REST API
+curl http://localhost:8000/v1/health
+# Expected: {"status":"ok"}
+```
+
+---
+
+## Stopping everything
+
+```bash
+brew services stop redis # Stop Redis
+# Ctrl+C in each terminal # Stop Agent Memory Server
+```
+
+## Restarting after reboot
+
+```bash
+brew services start redis
+cd agent-memory-server
+source .venv/bin/activate
+uv run agent-memory mcp --mode sse --port 9000
+```
+
+---
+
+## Connecting to IBM watsonx Orchestrate (Remote MCP)
+
+If you need to connect your local MCP server to a cloud service like IBM watsonx Orchestrate,
+you need a public URL. Use **ngrok** or **cloudflared** to create a tunnel.
+
+### Option A: ngrok
+
+> Requires a free account. Sign up at https://ngrok.com and get your auth token from https://dashboard.ngrok.com/get-started/your-authtoken
+
+```bash
+# Install
+brew install ngrok
+
+# Authenticate (one-time)
+ngrok config add-authtoken
+
+# Start tunnel (in a new terminal, while MCP server is running)
+ngrok http 9000
+```
+
+Copy the `https://...ngrok-free.dev` URL from the output.
+
+### Option B: cloudflared
+
+> No account required for quick tunnels.
+
+```bash
+# Install
+brew install cloudflared
+
+# Start tunnel (in a new terminal, while MCP server is running)
+cloudflared tunnel --url http://localhost:9000
+```
+
+Copy the `https://...trycloudflare.com` URL from the output.
+
+### Verify the tunnel
+
+```bash
+curl -s https:///sse \
+ -H "Accept: text/event-stream" \
+ --max-time 3
+# Expected: event: endpoint ...
+```
+
+### Add to Orchestrate
+
+Go to **Agent settings > MCP Servers > Add remote MCP server** and fill in:
+
+**Server name:** `Redis-Agent-Memory-MCP-Server`
+**Description:** `Tools to manage an agent's memory with Redis. Two-tier memory: working/session memory management and long term memory management.`
+**MCP server URL:** `https:///sse`
+**Transport type:** Server-Sent Events (SSE)
+
+> β οΈ The URL **must** end with `/sse`. Without it you'll get a `502 / 404 Not Found` error.
+
+> β οΈ Free-tier tunnel URLs change on every restart. Update the URL in Orchestrate each time you restart the tunnel.
+
+---
+
+## Troubleshooting
+
+**Port 9000/8000 in use:**
+```bash
+lsof -ti :9000 | xargs kill -9
+```
+
+**Redis not running:**
+```bash
+brew services restart redis
+```
+
+**Search index missing:**
+```bash
+uv run agent-memory rebuild-index
+```
+
+**Python version error:**
+Requires Python >=3.12, <3.13. Check with `python3.12 --version`
+
+**Orchestrate 502/404:**
+Make sure the MCP server URL ends with `/sse`
+
+**ngrok tunnel already exists:**
+```bash
+pkill -f "ngrok http"
+ngrok http 9000
+```
diff --git a/docs/advanced-memory-vector-db.md b/docs/user_guide/how_to_guides/advanced_vector_db.md
similarity index 99%
rename from docs/advanced-memory-vector-db.md
rename to docs/user_guide/how_to_guides/advanced_vector_db.md
index 7a49658d..5d677818 100644
--- a/docs/advanced-memory-vector-db.md
+++ b/docs/user_guide/how_to_guides/advanced_vector_db.md
@@ -1,6 +1,6 @@
# Advanced Memory Vector Database Configuration
-This guide covers advanced configuration patterns, custom implementations, and migration strategies for memory vector databases in Redis Agent Memory Server.
+This guide covers advanced configuration patterns, custom implementations, and migration strategies for memory vector databases in Agent Memory Server.
## Advanced Factory Patterns
diff --git a/docs/authentication.md b/docs/user_guide/how_to_guides/authentication.md
similarity index 96%
rename from docs/authentication.md
rename to docs/user_guide/how_to_guides/authentication.md
index 7a02bbac..ee9f4e38 100644
--- a/docs/authentication.md
+++ b/docs/user_guide/how_to_guides/authentication.md
@@ -1,6 +1,6 @@
# Authentication
-The Redis Agent Memory Server supports multiple authentication modes for secure API access. All API endpoints (except `/v1/health`, `/docs`, and `/openapi.json`) require valid authentication unless disabled for development.
+The Agent Memory Server supports multiple authentication modes for secure API access. All API endpoints (except `/v1/health`, `/docs`, and `/openapi.json`) require valid authentication unless disabled for development.
## Authentication Modes
@@ -128,7 +128,7 @@ You can extract any of these fields in your scripts (for example, `.token` or `.
#### Terraform example (register a pre-generated token)
-If you generate tokens outside Redis Agent Memory Server (for example via a secrets manager), you can register them using `--token` so the server only ever stores a hash:
+If you generate tokens outside Agent Memory Server (for example via a secrets manager), you can register them using `--token` so the server only ever stores a hash:
```hcl
variable "agent_memory_token" {
diff --git a/docs/aws-bedrock.md b/docs/user_guide/how_to_guides/aws_bedrock.md
similarity index 90%
rename from docs/aws-bedrock.md
rename to docs/user_guide/how_to_guides/aws_bedrock.md
index 283d4cfd..5f5e73ad 100644
--- a/docs/aws-bedrock.md
+++ b/docs/user_guide/how_to_guides/aws_bedrock.md
@@ -1,10 +1,10 @@
# AWS Bedrock Models
-The Redis Agent Memory Server supports [Amazon Bedrock](https://aws.amazon.com/bedrock/) for both **embedding models** and **LLM generation models**. This allows you to use AWS-native AI models while keeping your data within the AWS ecosystem.
+The Agent Memory Server supports [Amazon Bedrock](https://aws.amazon.com/bedrock/) for both **embedding models** and **LLM generation models**. This allows you to use AWS-native AI models while keeping your data within the AWS ecosystem.
-> **See also:** [LLM Providers](llm-providers.md#aws-bedrock) for a broader overview of all supported providers, and [Embedding Providers](embedding-providers.md) for embedding-specific configuration.
+> **See also:** [LLM Providers](llm_providers.md#aws-bedrock) for a broader overview of all supported providers, and [Embedding Providers](embedding_providers.md) for embedding-specific configuration.
-## Quick Start β Run a Full Bedrock-Backed Instance
+## Quick Start - Run a Full Bedrock-Backed Instance
Follow these steps to get the memory server running entirely on AWS Bedrock in under five minutes.
@@ -24,7 +24,7 @@ uv sync --extra aws
```bash
# ββ AWS credentials ββββββββββββββββββββββββββββββββββββββββββββββ
-# (or use an IAM role / AWS CLI profile instead β see "AWS Credentials" below)
+# (or use an IAM role / AWS CLI profile instead - see "AWS Credentials" below)
export AWS_ACCESS_KEY_ID=your-access-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-access-key
export AWS_REGION_NAME=us-east-1 # Required: used by LiteLLM for Bedrock API calls
@@ -80,8 +80,8 @@ All LLM operations in the server go through [LiteLLM](https://docs.litellm.ai/),
| Model type | Prefix required? | Example |
|------------|------------------|---------|
-| **Embedding** | **Yes** β must include `bedrock/` | `bedrock/amazon.titan-embed-text-v2:0` |
-| **Generation (chat)** | **Optional** β not required, but allowed | `anthropic.claude-sonnet-4-5-20250929-v1:0` |
+| **Embedding** | **Yes** - must include `bedrock/` | `bedrock/amazon.titan-embed-text-v2:0` |
+| **Generation (chat)** | **Optional** - not required, but allowed | `anthropic.claude-sonnet-4-5-20250929-v1:0` |
**Why the difference?** LiteLLM can infer the provider for generation models from the Bedrock-style model ID (e.g., `anthropic.claude-*`), so the `bedrock/` prefix is optional for generation. Adding it (e.g., `bedrock/anthropic.claude-sonnet-4-5-20250929-v1:0`) also works. For embedding models, the `bedrock/` prefix is the only way LiteLLM distinguishes a Bedrock embedding call from other providers, so it is **required**. If you omit the prefix on an embedding model, the server will auto-add it and emit a **deprecation warning**, but this fallback will be removed in a future release.
@@ -100,21 +100,21 @@ All LLM operations in the server go through [LiteLLM](https://docs.litellm.ai/),
| `bedrock/amazon.titan-embed-image-v1` | Amazon | 1024 | Titan multimodal (text + image) embedding * |
| `bedrock/cohere.embed-english-v3` | Cohere | 1024 | English-focused embeddings |
| `bedrock/cohere.embed-multilingual-v3` | Cohere | 1024 | Multilingual embeddings |
-| `bedrock/cohere.embed-v4:0` | Cohere | 1024 | Cohere Embed v4 β text + image embedding * |
+| `bedrock/cohere.embed-v4:0` | Cohere | 1024 | Cohere Embed v4 - text + image embedding * |
> \* Models marked with **\*** are not in `MODEL_CONFIGS` and their dimensions cannot be auto-resolved. You **must** set `REDISVL_VECTOR_DIMENSIONS=1024` explicitly when using them, or you will get vector-size mismatch errors at runtime.
### Generation Models (Anthropic Claude on Bedrock)
-The following Anthropic Claude models are available on Bedrock. Models marked **pre-configured** have entries in `MODEL_CONFIGS` (in `config.py`) with validated token limits; the others are fully usable by setting the corresponding environment variable β LiteLLM routes the request based on the Bedrock model ID.
+The following Anthropic Claude models are available on Bedrock. Models marked **pre-configured** have entries in `MODEL_CONFIGS` (in `config.py`) with validated token limits; the others are fully usable by setting the corresponding environment variable - LiteLLM routes the request based on the Bedrock model ID.
| Model ID | Description | Pre-configured |
|----------|-------------|:--------------:|
-| `anthropic.claude-opus-4-6-v1` | Claude Opus 4.6 β latest and most capable | |
+| `anthropic.claude-opus-4-6-v1` | Claude Opus 4.6 - latest and most capable | |
| `anthropic.claude-sonnet-4-6` | Claude Sonnet 4.6 | |
| `anthropic.claude-opus-4-5-20251101-v1:0` | Claude Opus 4.5 | β |
| `anthropic.claude-sonnet-4-5-20250929-v1:0` | Claude Sonnet 4.5 | β |
-| `anthropic.claude-haiku-4-5-20251001-v1:0` | Claude Haiku 4.5 β fast & cost-effective | β |
+| `anthropic.claude-haiku-4-5-20251001-v1:0` | Claude Haiku 4.5 - fast & cost-effective | β |
| `anthropic.claude-opus-4-1-20250805-v1:0` | Claude Opus 4.1 | |
| `anthropic.claude-sonnet-4-20250514-v1:0` | Claude Sonnet 4 | |
| `anthropic.claude-3-5-haiku-20241022-v1:0` | Claude 3.5 Haiku | |
@@ -130,14 +130,14 @@ AWS Bedrock support requires additional dependencies. Install the `[aws]` extra:
# With pip
pip install agent-memory-server[aws]
-# With uv (recommended β used by this project)
+# With uv (recommended - used by this project)
uv sync --extra aws
```
This installs:
-- **`boto3`** β AWS SDK for Python
-- **`botocore`** β Low-level AWS client library
+- **`boto3`** - AWS SDK for Python
+- **`botocore`** - Low-level AWS client library
> **Without these packages**, any attempt to use Bedrock models will fail at import time. The standard install (`pip install agent-memory-server`) does **not** include them.
@@ -207,8 +207,8 @@ export AWS_PROFILE=your-profile
The Dockerfile provides two build targets (multi-stage):
-- **`standard`** (default) β OpenAI / Anthropic support only
-- **`aws`** β Includes `boto3` and `botocore` for AWS Bedrock support
+- **`standard`** (default) - OpenAI / Anthropic support only
+- **`aws`** - Includes `boto3` and `botocore` for AWS Bedrock support
#### Building the AWS-enabled Image
@@ -229,7 +229,7 @@ docker-compose --profile aws up
docker-compose --profile aws up api-aws redis
```
-> **Note:** The `aws` profile services (`api-aws`, `mcp-aws`, `task-worker-aws`) are separate from the standard services. Do **not** mix profiles β run either `docker-compose up` (standard) or `docker-compose --profile aws up`.
+> **Note:** The `aws` profile services (`api-aws`, `mcp-aws`, `task-worker-aws`) are separate from the standard services. Do **not** mix profiles - run either `docker-compose up` (standard) or `docker-compose --profile aws up`.
Create a `.env` file with your credentials and model configuration. The Docker Compose AWS services read this file automatically:
@@ -333,7 +333,7 @@ REDISVL_VECTOR_DIMENSIONS=1536
### Example 1: Bedrock Embeddings with OpenAI Generation
```bash
-# Embedding model (Bedrock β bedrock/ prefix required)
+# Embedding model (Bedrock - bedrock/ prefix required)
EMBEDDING_MODEL=bedrock/amazon.titan-embed-text-v2:0
REDISVL_VECTOR_DIMENSIONS=1024
@@ -360,11 +360,11 @@ AWS_REGION_NAME=us-east-1
AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
-# Embedding model (Bedrock Titan β bedrock/ prefix required)
+# Embedding model (Bedrock Titan - bedrock/ prefix required)
EMBEDDING_MODEL=bedrock/amazon.titan-embed-text-v2:0
REDISVL_VECTOR_DIMENSIONS=1024
-# Generation models (Bedrock Claude β no prefix needed)
+# Generation models (Bedrock Claude - no prefix needed)
GENERATION_MODEL=anthropic.claude-sonnet-4-5-20250929-v1:0
FAST_MODEL=anthropic.claude-haiku-4-5-20251001-v1:0
SLOW_MODEL=anthropic.claude-sonnet-4-5-20250929-v1:0
@@ -505,8 +505,8 @@ If you see authentication errors:
## Related Documentation
-- [LLM Providers](llm-providers.md) - Comprehensive LLM provider guide (recommended)
-- [Embedding Providers](embedding-providers.md) - Embedding model configuration
+- [LLM Providers](llm_providers.md) - Comprehensive LLM provider guide (recommended)
+- [Embedding Providers](embedding_providers.md) - Embedding model configuration
- [Configuration](configuration.md) - Full configuration reference
-- [Custom Memory Vector Databases](custom-memory-vector-db.md) - Custom memory vector database setup
-- [Getting Started](getting-started.md) - Initial setup guide
+- [Custom Memory Vector Databases](custom_vector_db.md) - Custom memory vector database setup
+- [Getting Started](../01_quick_start.md) - Initial setup guide
diff --git a/docs/configuration.md b/docs/user_guide/how_to_guides/configuration.md
similarity index 97%
rename from docs/configuration.md
rename to docs/user_guide/how_to_guides/configuration.md
index 2ccc57d5..2c8c7acd 100644
--- a/docs/configuration.md
+++ b/docs/user_guide/how_to_guides/configuration.md
@@ -1,6 +1,6 @@
# Configuration
-The Redis Agent Memory Server can be configured via environment variables or YAML configuration files. All settings have sensible defaults for development, but you'll want to customize them for production.
+The Agent Memory Server can be configured via environment variables or YAML configuration files. All settings have sensible defaults for development, but you'll want to customize them for production.
## Configuration Methods
@@ -82,7 +82,7 @@ EMBEDDING_MODEL=bedrock/amazon.titan-embed-text-v2:0
REDISVL_VECTOR_DIMENSIONS=1024 # Must match the embedding model dimensions
```
-For detailed AWS Bedrock setup, see [LLM Providers - AWS Bedrock](llm-providers.md#aws-bedrock).
+For detailed AWS Bedrock setup, see [LLM Providers - AWS Bedrock](llm_providers.md#aws-bedrock).
### Server Ports
```bash
@@ -289,7 +289,7 @@ Pre-configured models:
- `anthropic.claude-haiku-4-5-20251001-v1:0` - Claude 4.5 Haiku (Fast)
- `anthropic.claude-opus-4-5-20251101-v1:0` - Claude 4.5 Opus (Most capable)
-The server uses [LiteLLM](https://docs.litellm.ai/) internally, which supports any Bedrock model. See [LLM Providers](llm-providers.md#aws-bedrock) for setup instructions and adding custom models.
+The server uses [LiteLLM](https://docs.litellm.ai/) internally, which supports any Bedrock model. See [LLM Providers](llm_providers.md#aws-bedrock) for setup instructions and adding custom models.
### Embedding Models
@@ -302,7 +302,7 @@ The server supports many embedding providers via LiteLLM:
- **Cohere**: `cohere/embed-english-v3.0`
- **And more...**
-See [Embedding Providers](embedding-providers.md) for complete setup instructions, model formats, and dimension configuration.
+See [Embedding Providers](embedding_providers.md) for complete setup instructions, model formats, and dimension configuration.
## Configuration Examples
diff --git a/docs/custom-memory-vector-db.md b/docs/user_guide/how_to_guides/custom_vector_db.md
similarity index 100%
rename from docs/custom-memory-vector-db.md
rename to docs/user_guide/how_to_guides/custom_vector_db.md
diff --git a/docs/development.md b/docs/user_guide/how_to_guides/development.md
similarity index 91%
rename from docs/development.md
rename to docs/user_guide/how_to_guides/development.md
index 0dc0e9f5..1d3e227c 100644
--- a/docs/development.md
+++ b/docs/user_guide/how_to_guides/development.md
@@ -63,8 +63,8 @@ Releases are triggered manually via GitHub Actions workflow dispatch.
3. Go to GitHub Actions β "Release Docker Images" workflow
4. Click "Run workflow"
5. Choose options:
- - **Version**: Leave empty to use version from `__init__.py`, or specify a custom version
- - **Push latest tag**: Check to also tag as `latest` (recommended for stable releases)
+ - **Version**: Leave empty to use version from `__init__.py`, or specify a custom version
+ - **Push latest tag**: Check to also tag as `latest` (recommended for stable releases)
6. Click "Run workflow"
This will:
diff --git a/docs/embedding-providers.md b/docs/user_guide/how_to_guides/embedding_providers.md
similarity index 97%
rename from docs/embedding-providers.md
rename to docs/user_guide/how_to_guides/embedding_providers.md
index 5a4af2ac..c9fbff29 100644
--- a/docs/embedding-providers.md
+++ b/docs/user_guide/how_to_guides/embedding_providers.md
@@ -1,6 +1,6 @@
# Embedding Providers
-The Redis Agent Memory Server uses LiteLLM for embeddings, enabling support for many embedding providers out of the box.
+The Agent Memory Server uses LiteLLM for embeddings, enabling support for many embedding providers out of the box.
## Quick Start
diff --git a/docs/user_guide/how_to_guides/index.md b/docs/user_guide/how_to_guides/index.md
new file mode 100644
index 00000000..70155841
--- /dev/null
+++ b/docs/user_guide/how_to_guides/index.md
@@ -0,0 +1,127 @@
+---
+description: How-to guides for Agent Memory Server.
+---
+
+# How-To Guides
+
+Task-oriented recipes. Each one assumes you already know the basics from
+the numbered tutorials and answers a single "how do I..." question.
+
+## Configure
+
+
+
+- :material-robot:{ .lg .middle } **[LLM providers](llm_providers.md)**
+
+ ---
+
+ OpenAI, Anthropic, and other LiteLLM-supported chat models.
+
+- :material-vector-line:{ .lg .middle } **[Embedding providers](embedding_providers.md)**
+
+ ---
+
+ Pick and configure an embedding model for semantic search.
+
+- :material-aws:{ .lg .middle } **[AWS Bedrock](aws_bedrock.md)**
+
+ ---
+
+ Use Bedrock-hosted Claude, Titan, and Cohere models.
+
+
+
+## Vector storage
+
+
+
+- :material-database-search:{ .lg .middle } **[Advanced vector DB](advanced_vector_db.md)**
+
+ ---
+
+ Tune index parameters, choose algorithms, manage migrations.
+
+- :material-database-edit:{ .lg .middle } **[Custom vector DB](custom_vector_db.md)**
+
+ ---
+
+ Plug in your own vector backend behind the memory layer.
+
+- :material-tune:{ .lg .middle } **[Query optimization](query_optimization.md)**
+
+ ---
+
+ Lower latency and improve recall on large memory stores.
+
+- :material-pencil:{ .lg .middle } **[Memory editing](memory_editing.md)**
+
+ ---
+
+ Update, correct, and enrich existing long-term memories via REST, MCP, or the Python client.
+
+
+
+## Integrate
+
+
+
+- :material-puzzle:{ .lg .middle } **[Integration patterns](integration_patterns.md)**
+
+ ---
+
+ Recipes for plugging the server into common agent frameworks.
+
+- :material-toolbox:{ .lg .middle } **[Development](development.md)**
+
+ ---
+
+ Local dev loop, debugging, and contributing back.
+
+
+
+## Operations Quick Reference
+
+| Topic | Description |
+|-------|-------------|
+| [Configuration](configuration.md) | All environment variables and YAML settings |
+| [Worker timeout tuning](configuration.md#worker-lease-and-task-timeout) | How to size task timeout vs redelivery timeout for Docket workers |
+| [Authentication](authentication.md) | OAuth2, token auth, and development mode |
+| [Custom prompt security](security.md) | Custom prompt security and best practices |
+| [LLM Providers](llm_providers.md) | Generation models including AWS Bedrock |
+| [Embedding Providers](embedding_providers.md) | Embedding models and dimensions |
+| [Custom Vector DB](custom_vector_db.md) | Storage backend configuration |
+| [Advanced Vector DB](advanced_vector_db.md) | Tune index parameters and algorithms |
+
+## Where to Start
+
+**Deploying to production?** Start with [Configuration](configuration.md) to understand all server settings.
+
+**Setting up authentication?** See [Authentication](authentication.md) for OAuth2 or token-based auth.
+
+**Using AWS?** The [LLM Providers](llm_providers.md) and [AWS Bedrock](aws_bedrock.md) guides cover Bedrock setup for both generation and embedding models.
+
+**Customizing storage?** Check [Custom Vector DB](custom_vector_db.md) for Redis and custom backend options.
diff --git a/docs/memory-integration-patterns.md b/docs/user_guide/how_to_guides/integration_patterns.md
similarity index 99%
rename from docs/memory-integration-patterns.md
rename to docs/user_guide/how_to_guides/integration_patterns.md
index 6e94696b..ec47c589 100644
--- a/docs/memory-integration-patterns.md
+++ b/docs/user_guide/how_to_guides/integration_patterns.md
@@ -1,6 +1,6 @@
# Memory Integration Patterns
-The most common question developers have is: *"How do I actually get memories into and out of my LLM?"* Redis Agent Memory Server provides three distinct patterns for integrating memory with your AI applications, each optimized for different use cases and levels of control.
+The most common question developers have is: *"How do I actually get memories into and out of my LLM?"* Agent Memory Server provides three distinct patterns for integrating memory with your AI applications, each optimized for different use cases and levels of control.
## Overview of Using Memory
@@ -508,7 +508,7 @@ await client.put_working_memory("car_shopping_session", working_memory)
# - "User is shopping for electric vehicles"
```
-For complete details on extraction strategies (discrete, summary, preferences, custom) and security considerations, see [Memory Extraction Strategies](memory-extraction-strategies.md).
+For complete details on extraction strategies (discrete, summary, preferences, custom) and security considerations, see [Memory Extraction Strategies](../../concepts/memory_extraction.md).
### Continuous Learning Agent
diff --git a/docs/llm-providers.md b/docs/user_guide/how_to_guides/llm_providers.md
similarity index 91%
rename from docs/llm-providers.md
rename to docs/user_guide/how_to_guides/llm_providers.md
index f0021c77..633502a0 100644
--- a/docs/llm-providers.md
+++ b/docs/user_guide/how_to_guides/llm_providers.md
@@ -1,6 +1,6 @@
# LLM Providers
-The Redis Agent Memory Server uses [LiteLLM](https://docs.litellm.ai/) as a unified interface for all LLM operations. This enables support for 100+ LLM providers without code changesβjust configure environment variables.
+The Agent Memory Server uses [LiteLLM](https://docs.litellm.ai/) as a unified interface for all LLM operations. This enables support for 100+ LLM providers without code changes - just configure environment variables.
## Architecture Overview
@@ -41,13 +41,13 @@ export OPENAI_API_KEY=sk-...
export GENERATION_MODEL=gpt-4o
export EMBEDDING_MODEL=text-embedding-3-small
-# Anthropic (requires a separate embedding provider β Anthropic has no embedding models)
+# Anthropic (requires a separate embedding provider - Anthropic has no embedding models)
export ANTHROPIC_API_KEY=sk-ant-...
export GENERATION_MODEL=claude-3-5-sonnet-20241022
export OPENAI_API_KEY=sk-... # Needed for embeddings
export EMBEDDING_MODEL=text-embedding-3-small # Use OpenAI for embeddings
-# AWS Bedrock (full stack β see "AWS Bedrock" section for details)
+# AWS Bedrock (full stack - see "AWS Bedrock" section for details)
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_REGION_NAME=us-east-1 # Required: LiteLLM Bedrock calls
@@ -57,7 +57,7 @@ export EMBEDDING_MODEL=bedrock/amazon.titan-embed-text-v2:0 # bedrock/ pre
export REDISVL_VECTOR_DIMENSIONS=1024 # Must match embedding model
```
-> **Bedrock users:** You must also install the `[aws]` extra (`pip install agent-memory-server[aws]` or `uv sync --extra aws`) to get `boto3` and `botocore`. See [AWS Bedrock](aws-bedrock.md) for a full walkthrough.
+> **Bedrock users:** You must also install the `[aws]` extra (`pip install agent-memory-server[aws]` or `uv sync --extra aws`) to get `boto3` and `botocore`. See [AWS Bedrock](aws_bedrock.md) for a full walkthrough.
## Supported Providers
@@ -74,7 +74,7 @@ export REDISVL_VECTOR_DIMENSIONS=1024 # Must match e
### Embedding Models
-See [Embedding Providers](embedding-providers.md) for complete embedding configuration.
+See [Embedding Providers](embedding_providers.md) for complete embedding configuration.
**Quick reference:**
```bash
@@ -130,7 +130,7 @@ export EMBEDDING_MODEL=text-embedding-3-small
AWS Bedrock provides access to foundation models from multiple providers (Anthropic Claude, Amazon Titan, Cohere, etc.) through AWS infrastructure.
-> **Full guide:** See [AWS Bedrock Models](aws-bedrock.md) for a complete walkthrough including a Quick Start demo, Docker Compose instructions, IAM policies, and troubleshooting.
+> **Full guide:** See [AWS Bedrock Models](aws_bedrock.md) for a complete walkthrough including a Quick Start demo, Docker Compose instructions, IAM policies, and troubleshooting.
#### Installation
@@ -140,7 +140,7 @@ AWS Bedrock support requires the `[aws]` extra, which installs `boto3` and `boto
# With pip
pip install agent-memory-server[aws]
-# With uv (recommended β used by this project)
+# With uv (recommended - used by this project)
uv sync --extra aws
```
@@ -160,7 +160,7 @@ export AWS_PROFILE=my-profile
export AWS_REGION_NAME=us-east-1
# Option 3: IAM role (recommended for production on AWS)
-# No explicit credentials needed β LiteLLM discovers them from instance metadata
+# No explicit credentials needed - LiteLLM discovers them from instance metadata
export AWS_REGION_NAME=us-east-1
# Option 4: AWS SSO
@@ -184,30 +184,30 @@ export FAST_MODEL=anthropic.claude-haiku-4-5-20251001-v1:0
| Model ID | Description | Pre-configured |
|----------|-------------|:--------------:|
-| `anthropic.claude-opus-4-6-v1` | Claude Opus 4.6 β latest | |
+| `anthropic.claude-opus-4-6-v1` | Claude Opus 4.6 - latest | |
| `anthropic.claude-sonnet-4-6` | Claude Sonnet 4.6 | |
| `anthropic.claude-opus-4-5-20251101-v1:0` | Claude Opus 4.5 | β |
| `anthropic.claude-sonnet-4-5-20250929-v1:0` | Claude Sonnet 4.5 | β |
-| `anthropic.claude-haiku-4-5-20251001-v1:0` | Claude Haiku 4.5 β fast & cost-effective | β |
+| `anthropic.claude-haiku-4-5-20251001-v1:0` | Claude Haiku 4.5 - fast & cost-effective | β |
| `anthropic.claude-opus-4-1-20250805-v1:0` | Claude Opus 4.1 | |
| `anthropic.claude-sonnet-4-20250514-v1:0` | Claude Sonnet 4 | |
| `anthropic.claude-3-5-haiku-20241022-v1:0` | Claude 3.5 Haiku | |
| `anthropic.claude-3-haiku-20240307-v1:0` | Claude 3 Haiku | |
-Any Bedrock model can be used by setting the environment variable β LiteLLM routes based on the model ID convention.
+Any Bedrock model can be used by setting the environment variable - LiteLLM routes based on the model ID convention.
#### Embedding Models
> **Important:** Bedrock embedding models **require** the `bedrock/` prefix.
-LiteLLM needs the `bedrock/` prefix to distinguish Bedrock embeddings from other providers. If you omit it, the server auto-adds the prefix and emits a **deprecation warning** β this fallback will be removed in a future release.
+LiteLLM needs the `bedrock/` prefix to distinguish Bedrock embeddings from other providers. If you omit it, the server auto-adds the prefix and emits a **deprecation warning** - this fallback will be removed in a future release.
```bash
-# Correct β use bedrock/ prefix
+# Correct - use bedrock/ prefix
export EMBEDDING_MODEL=bedrock/amazon.titan-embed-text-v2:0
export REDISVL_VECTOR_DIMENSIONS=1024 # Must match embedding model dimensions
-# Deprecated β works but emits a warning
+# Deprecated - works but emits a warning
export EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
```
@@ -220,7 +220,7 @@ export EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
| `bedrock/amazon.titan-embed-image-v1` | 1024 | Titan multimodal (text + image) embedding * |
| `bedrock/cohere.embed-english-v3` | 1024 | English-focused |
| `bedrock/cohere.embed-multilingual-v3` | 1024 | Multilingual |
-| `bedrock/cohere.embed-v4:0` | 1024 | Cohere Embed v4 β text + image * |
+| `bedrock/cohere.embed-v4:0` | 1024 | Cohere Embed v4 - text + image * |
> \* Models marked with **\*** are not in `MODEL_CONFIGS`, so their dimensions cannot be auto-resolved. Set `REDISVL_VECTOR_DIMENSIONS=1024` explicitly when using them.
@@ -401,7 +401,7 @@ export REDISVL_VECTOR_DIMENSIONS=1024
- Verify IAM permissions include `bedrock:InvokeModel`
- Check model is enabled in your AWS region
- Ensure both `REGION_NAME` and `AWS_REGION_NAME` are set correctly
-- See [AWS Bedrock Troubleshooting](aws-bedrock.md#troubleshooting) for more details
+- See [AWS Bedrock Troubleshooting](aws_bedrock.md#troubleshooting) for more details
**Bedrock "AWS-related dependencies might be missing"**
- Install the `[aws]` extra: `pip install agent-memory-server[aws]` or `uv sync --extra aws`
@@ -440,8 +440,8 @@ The following are no longer required:
## See Also
-- [AWS Bedrock Models](aws-bedrock.md) - Complete Bedrock guide with Quick Start, IAM policies, and Docker setup
-- [Embedding Providers](embedding-providers.md) - Detailed embedding configuration
+- [AWS Bedrock Models](aws_bedrock.md) - Complete Bedrock guide with Quick Start, IAM policies, and Docker setup
+- [Embedding Providers](embedding_providers.md) - Detailed embedding configuration
- [Configuration](configuration.md) - All environment variables
-- [Query Optimization](query-optimization.md) - Model selection for query optimization
+- [Query Optimization](query_optimization.md) - Model selection for query optimization
- [LiteLLM Documentation](https://docs.litellm.ai/) - Full provider list
diff --git a/docs/user_guide/how_to_guides/memory_editing.md b/docs/user_guide/how_to_guides/memory_editing.md
new file mode 100644
index 00000000..92751437
--- /dev/null
+++ b/docs/user_guide/how_to_guides/memory_editing.md
@@ -0,0 +1,497 @@
+---
+description: Update, correct, and enrich existing long-term memories.
+---
+
+# Memory editing
+
+The Agent Memory Server provides comprehensive memory editing capabilities, allowing you to update, correct, and refine stored memories through both REST API endpoints and MCP tools. This feature enables AI agents and applications to maintain accurate, up-to-date memory records over time.
+
+## Overview
+
+Memory editing allows you to modify existing long-term memories without losing their search indexing or metadata. This is essential for:
+
+- **Correcting mistakes**: Fix inaccurate information in stored memories
+- **Updating information**: Reflect changes in user preferences or circumstances
+- **Adding details**: Enrich memories with additional context or information
+- **Maintaining accuracy**: Keep memory store current and reliable
+
+**Key Features:**
+
+- **Partial updates**: Modify only the fields you want to change
+- **Automatic re-indexing**: Updated memories are re-indexed for search
+- **Vector consistency**: Embeddings are regenerated when text changes
+- **Metadata preservation**: IDs, timestamps, and other metadata remain stable
+- **Atomic operations**: Updates succeed or fail completely
+
+## Memory editing workflow
+
+### 1. Find the memory
+
+First, locate the memory you want to edit using search:
+
+```python
+# Search for memories to edit
+results = await client.search_long_term_memory(
+ text="user food preferences",
+ limit=5
+)
+
+# Find the specific memory
+memory_to_edit = results.memories[0]
+memory_id = memory_to_edit.id
+```
+
+### 2. Prepare updates
+
+Specify only the fields you want to change:
+
+```python
+# Update only the text content
+updates = {
+ "text": "User prefers Mediterranean cuisine and is vegetarian"
+}
+
+# Or update multiple fields
+updates = {
+ "text": "User prefers Mediterranean cuisine and is vegetarian",
+ "topics": ["food", "preferences", "diet", "mediterranean"],
+ "entities": ["Mediterranean cuisine", "vegetarian"]
+}
+```
+
+### 3. Apply the update
+
+Use the appropriate interface to apply your changes:
+
+```python
+# Update the memory
+updated_memory = await client.edit_long_term_memory(
+ memory_id=memory_id,
+ updates=updates
+)
+```
+
+## REST API interface
+
+### Endpoint
+
+**PATCH /v1/long-term-memory/{memory_id}**
+
+Updates specific fields of an existing memory record.
+
+### Request format
+
+```http
+PATCH /v1/long-term-memory/01HXE2B1234567890ABCDEF
+Content-Type: application/json
+Authorization: Bearer your_token_here
+
+{
+ "text": "Updated memory text",
+ "topics": ["new", "topics"],
+ "entities": ["updated", "entities"],
+ "memory_type": "semantic",
+ "event_date": "2024-01-15T14:30:00Z",
+ "namespace": "updated_namespace",
+ "user_id": "updated_user"
+}
+```
+
+### Response format
+
+```json
+{
+ "id": "01HXE2B1234567890ABCDEF",
+ "text": "Updated memory text",
+ "memory_type": "semantic",
+ "topics": ["new", "topics"],
+ "entities": ["updated", "entities"],
+ "created_at": "2024-01-10T12:00:00Z",
+ "persisted_at": "2024-01-10T12:00:00Z",
+ "updated_at": "2024-01-16T10:30:00Z",
+ "last_accessed": "2024-01-16T10:30:00Z",
+ "user_id": "user_123",
+ "session_id": "session_456",
+ "namespace": "updated_namespace",
+ "memory_hash": "new_hash_after_update"
+}
+```
+
+### cURL examples
+
+**Update memory text:**
+
+```bash
+curl -X PATCH "http://localhost:8000/v1/long-term-memory/01HXE2B1234567890ABCDEF" \
+ -H "Content-Type: application/json" \
+ -H "Authorization: Bearer your_token" \
+ -d '{
+ "text": "User prefers dark mode interfaces and uses vim for coding"
+ }'
+```
+
+**Update multiple fields:**
+
+```bash
+curl -X PATCH "http://localhost:8000/v1/long-term-memory/01HXE2B1234567890ABCDEF" \
+ -H "Content-Type: application/json" \
+ -H "Authorization: Bearer your_token" \
+ -d '{
+ "text": "User completed Python certification on January 15, 2024",
+ "memory_type": "episodic",
+ "event_date": "2024-01-15T14:30:00Z",
+ "topics": ["education", "certification", "python"],
+ "entities": ["Python", "certification"]
+ }'
+```
+
+## MCP tool interface
+
+### Tool: edit_long_term_memory
+
+The MCP server provides an `edit_long_term_memory` tool for AI agents to modify memories through natural conversation.
+
+### Tool schema
+
+```python
+{
+ "name": "edit_long_term_memory",
+ "description": "Update an existing long-term memory with new or corrected information",
+ "parameters": {
+ "type": "object",
+ "properties": {
+ "memory_id": {
+ "type": "string",
+ "description": "The ID of the memory to edit (get this from search results)"
+ },
+ "text": {
+ "type": "string",
+ "description": "Updated memory text content"
+ },
+ "topics": {
+ "type": "array",
+ "items": {"type": "string"},
+ "description": "Updated list of topics"
+ },
+ "entities": {
+ "type": "array",
+ "items": {"type": "string"},
+ "description": "Updated list of entities"
+ },
+ "memory_type": {
+ "type": "string",
+ "enum": ["semantic", "episodic", "message"],
+ "description": "Type of memory"
+ },
+ "event_date": {
+ "type": "string",
+ "description": "Event date for episodic memories (ISO 8601 format)"
+ },
+ "namespace": {
+ "type": "string",
+ "description": "Memory namespace"
+ },
+ "user_id": {
+ "type": "string",
+ "description": "User ID associated with the memory"
+ }
+ },
+ "required": ["memory_id"]
+ }
+}
+```
+
+### MCP usage examples
+
+**Simple text update:**
+
+```python
+await client.call_tool("edit_long_term_memory", {
+ "memory_id": "01HXE2B1234567890ABCDEF",
+ "text": "User prefers tea over coffee (updated preference)"
+})
+```
+
+**Update memory type and event date:**
+
+```python
+await client.call_tool("edit_long_term_memory", {
+ "memory_id": "01HXE2B1234567890ABCDEF",
+ "memory_type": "episodic",
+ "event_date": "2024-01-15T14:30:00Z"
+})
+```
+
+**Comprehensive update:**
+
+```python
+await client.call_tool("edit_long_term_memory", {
+ "memory_id": "01HXE2B1234567890ABCDEF",
+ "text": "User was promoted to Principal Engineer on January 15, 2024",
+ "memory_type": "episodic",
+ "event_date": "2024-01-15T14:30:00Z",
+ "topics": ["career", "promotion", "engineering", "principal"],
+ "entities": ["Principal Engineer", "promotion", "January 15, 2024"]
+})
+```
+
+## Python client interface
+
+### Method: edit_long_term_memory
+
+```python
+async def edit_long_term_memory(
+ self,
+ memory_id: str,
+ updates: dict[str, Any]
+) -> MemoryRecord:
+ """
+ Edit an existing long-term memory record.
+
+ Args:
+ memory_id: The ID of the memory to edit
+ updates: Dictionary of fields to update
+
+ Returns:
+ The updated memory record
+
+ Raises:
+ HTTPException: If memory not found or update fails
+ """
+```
+
+### Client usage examples
+
+```python
+from agent_memory_client import MemoryAPIClient, MemoryClientConfig
+
+client = MemoryAPIClient(MemoryClientConfig(base_url="http://localhost:8000"))
+
+# Simple text correction
+updated_memory = await client.edit_long_term_memory(
+ memory_id="01HXE2B1234567890ABCDEF",
+ updates={"text": "User actually prefers coffee, not tea"}
+)
+
+# Add more context
+updated_memory = await client.edit_long_term_memory(
+ memory_id="01HXE2B1234567890ABCDEF",
+ updates={
+ "text": "User prefers Italian cuisine, especially pasta and pizza",
+ "topics": ["food", "preferences", "italian", "cuisine"],
+ "entities": ["Italian cuisine", "pasta", "pizza"]
+ }
+)
+
+# Update namespace and user
+updated_memory = await client.edit_long_term_memory(
+ memory_id="01HXE2B1234567890ABCDEF",
+ updates={
+ "namespace": "work_preferences",
+ "user_id": "user_456"
+ }
+)
+```
+
+## Editable fields
+
+### Core content fields
+
+- **text**: The main memory content (triggers embedding regeneration)
+- **topics**: List of topic tags for categorization
+- **entities**: List of named entities mentioned in the memory
+- **memory_type**: Type classification (semantic, episodic, message)
+
+### Temporal fields
+
+- **event_date**: Specific date/time for episodic memories (ISO 8601 format)
+
+### Organization fields
+
+- **namespace**: Memory namespace for organization
+- **user_id**: User associated with the memory
+
+### Read-only fields
+
+These fields cannot be edited and are managed automatically:
+
+- **id**: Unique memory identifier
+- **created_at**: Original creation timestamp
+- **persisted_at**: When memory was first saved to long-term storage
+- **updated_at**: Last modification timestamp (updated automatically)
+- **last_accessed**: Last time memory was retrieved (managed by recency system)
+- **memory_hash**: Content hash (regenerated when text changes)
+
+## Update behavior
+
+### Automatic updates
+
+When you edit a memory, the system automatically:
+
+1. **Updates timestamps**: Sets `updated_at` to current time
+2. **Regenerates embeddings**: If text content changes, new embeddings are created
+3. **Recalculates hash**: Content hash is updated for deduplication
+4. **Re-indexes memory**: Search index is updated with new content
+5. **Updates access time**: Sets `last_accessed` to current time
+
+### Partial updates
+
+Only specify fields you want to change - other fields remain unchanged:
+
+```python
+# Only update topics - text, entities, etc. stay the same
+updates = {"topics": ["programming", "python", "web-development"]}
+
+# Only update text - topics, entities, etc. stay the same
+updates = {"text": "Updated description of the user's preferences"}
+```
+
+### Vector re-indexing
+
+When memory text changes, the system automatically:
+
+- Generates new embeddings using the configured embedding model
+- Updates the vector index for accurate semantic search
+- Maintains search performance and accuracy
+
+## Error handling
+
+### Common errors
+
+**Memory Not Found (404):**
+
+```json
+{
+ "detail": "Memory not found: 01HXE2B1234567890ABCDEF",
+ "status_code": 404
+}
+```
+
+**Invalid Memory ID (400):**
+
+```json
+{
+ "detail": "Invalid memory ID format",
+ "status_code": 400
+}
+```
+
+**Validation Error (422):**
+
+```json
+{
+ "detail": [
+ {
+ "loc": ["body", "event_date"],
+ "msg": "invalid datetime format",
+ "type": "value_error"
+ }
+ ],
+ "status_code": 422
+}
+```
+
+### Error handling in code
+
+```python
+try:
+ updated_memory = await client.edit_long_term_memory(
+ memory_id="01HXE2B1234567890ABCDEF",
+ updates={"text": "Updated text"}
+ )
+except HTTPException as e:
+ if e.status_code == 404:
+ print("Memory not found")
+ elif e.status_code == 422:
+ print("Invalid update data")
+ else:
+ print(f"Update failed: {e.detail}")
+```
+
+## Use cases and examples
+
+### Correcting user information
+
+**Scenario**: User corrects their job title
+
+```python
+# 1. Search for the memory
+results = await client.search_long_term_memory(
+ text="user job title engineer",
+ limit=1
+)
+
+# 2. Update with correction
+if results.memories:
+ await client.edit_long_term_memory(
+ memory_id=results.memories[0].id,
+ updates={
+ "text": "User works as a Senior Software Engineer at TechCorp",
+ "entities": ["Senior Software Engineer", "TechCorp"]
+ }
+ )
+```
+
+### Adding context to sparse memories
+
+**Scenario**: Enrich a basic memory with additional details
+
+```python
+# Original: "User likes pizza"
+# Enhanced with context:
+await client.edit_long_term_memory(
+ memory_id="01HXE2B1234567890ABCDEF",
+ updates={
+ "text": "User likes pizza, especially thin crust with pepperoni and mushrooms from Mario's Pizzeria",
+ "topics": ["food", "preferences", "pizza", "italian"],
+ "entities": ["pizza", "thin crust", "pepperoni", "mushrooms", "Mario's Pizzeria"]
+ }
+)
+```
+
+### Converting memory types
+
+**Scenario**: Convert a general memory to an episodic memory with event date
+
+```python
+# Change from semantic to episodic with specific date
+await client.edit_long_term_memory(
+ memory_id="01HXE2B1234567890ABCDEF",
+ updates={
+ "text": "User got promoted to Team Lead on March 15, 2024",
+ "memory_type": "episodic",
+ "event_date": "2024-03-15T09:00:00Z",
+ "topics": ["career", "promotion", "team-lead"],
+ "entities": ["Team Lead", "promotion", "March 15, 2024"]
+ }
+)
+```
+
+## Best practices for memory editing
+
+### Memory identification
+
+1. **Use search first**: Always search to find the correct memory ID
+2. **Verify before editing**: Check memory content matches your expectations
+3. **Handle duplicates**: Consider if multiple memories need the same update
+
+### Update strategy
+
+1. **Minimal changes**: Only update fields that actually need to change
+2. **Preserve context**: Don't remove important information when updating
+3. **Consistent formatting**: Maintain consistent data formats across memories
+4. **Validate inputs**: Check data formats before making updates
+
+### Error prevention
+
+1. **Check memory exists**: Handle 404 errors gracefully
+2. **Validate data**: Ensure update data matches expected formats
+3. **Test updates**: Verify changes work as expected in development
+4. **Monitor performance**: Watch for degradation with frequent updates
+
+This comprehensive memory editing system ensures that your AI agent's memory remains accurate, current, and useful over time, adapting to new information and corrections as they become available.
+
+## See also
+
+- [Memory lifecycle](../../concepts/memory_lifecycle.md) β how memories are created, promoted, and forgotten
+- [Long-term memory](../../concepts/long_term_memory.md) β semantic search and persistent storage
diff --git a/docs/query-optimization.md b/docs/user_guide/how_to_guides/query_optimization.md
similarity index 96%
rename from docs/query-optimization.md
rename to docs/user_guide/how_to_guides/query_optimization.md
index 459dccea..8e592ee8 100644
--- a/docs/query-optimization.md
+++ b/docs/user_guide/how_to_guides/query_optimization.md
@@ -1,6 +1,6 @@
# Query Optimization
-The Redis Agent Memory Server includes intelligent query optimization that uses configurable language models to improve search accuracy and retrieval quality. This feature automatically refines user queries to better match stored memories using specialized AI models.
+The Agent Memory Server includes intelligent query optimization that uses configurable language models to improve search accuracy and retrieval quality. This feature automatically refines user queries to better match stored memories using specialized AI models.
## Overview
@@ -73,7 +73,7 @@ GENERATION_MODEL=gpt-4o
# - Any model supported by LiteLLM (100+ providers)
```
-See [LLM Providers](llm-providers.md) for complete configuration options.
+See [LLM Providers](llm_providers.md) for complete configuration options.
## Usage Examples
diff --git a/docs/security-custom-prompts.md b/docs/user_guide/how_to_guides/security.md
similarity index 93%
rename from docs/security-custom-prompts.md
rename to docs/user_guide/how_to_guides/security.md
index 882bf659..78e058d1 100644
--- a/docs/security-custom-prompts.md
+++ b/docs/user_guide/how_to_guides/security.md
@@ -3,6 +3,7 @@
This guide covers security considerations when using the CustomMemoryStrategy feature, which allows users to provide custom extraction prompts for specialized memory extraction.
!!! danger "Security Critical"
+
User-provided prompts introduce security risks including prompt injection, template injection, and output manipulation. The system includes comprehensive defenses, but understanding these risks is essential for production deployment.
## Overview
@@ -115,7 +116,8 @@ def _validate_memory_output(self, memory: dict[str, Any]) -> bool:
The system automatically detects and blocks common attack patterns:
-!!! example "Blocked Patterns"
+!!! tip "Blocked Patterns"
+
- **Instruction Override:** `ignore previous instructions`, `forget everything`
- **Information Extraction:** `reveal your system prompt`, `show me your instructions`
- **Code Execution:** `execute code`, `eval(`, `import`, `subprocess`
@@ -224,6 +226,7 @@ logger.warning("Filtered potentially unsafe memory: {memory}")
```
!!! tip "Production Monitoring"
+
Monitor these security logs in production environments to detect potential attack attempts and adjust security rules as needed.
## Production Recommendations
@@ -247,19 +250,19 @@ logger.warning("Filtered potentially unsafe memory: {memory}")
If you suspect a security issue:
1. **Immediate Actions:**
- - Disable the affected custom prompt
- - Review recent memory extractions for anomalies
- - Check system logs for security events
+ - Disable the affected custom prompt
+ - Review recent memory extractions for anomalies
+ - Check system logs for security events
2. **Investigation:**
- - Identify the source of malicious prompts
- - Assess potential data exposure or corruption
- - Review user access and authentication logs
+ - Identify the source of malicious prompts
+ - Assess potential data exposure or corruption
+ - Review user access and authentication logs
3. **Remediation:**
- - Update security rules if new attack patterns detected
- - Notify affected users of any data concerns
- - Implement additional security controls as needed
+ - Update security rules if new attack patterns detected
+ - Notify affected users of any data concerns
+ - Implement additional security controls as needed
## API Integration
@@ -312,8 +315,8 @@ uv run pytest tests/test_memory_strategies.py tests/test_prompt_security.py
## Related Documentation
-- [Working Memory](working-memory.md) - Session-scoped memory storage
-- [Long-term Memory](long-term-memory.md) - Persistent memory storage
+- [Working Memory](../../concepts/working_memory.md) - Session-scoped memory storage
+- [Long-term Memory](../../concepts/long_term_memory.md) - Persistent memory storage
- [Authentication](authentication.md) - Securing API access
- [Configuration](configuration.md) - System configuration options
- [Development Guide](development.md) - Development and testing practices
@@ -321,4 +324,5 @@ uv run pytest tests/test_memory_strategies.py tests/test_prompt_security.py
---
!!! warning "Security Responsibility"
+
Security is a shared responsibility. Always validate and review custom prompts before use in production environments. When in doubt, use the built-in memory strategies (discrete, summary, preferences) which have been thoroughly tested and validated.
diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md
new file mode 100644
index 00000000..79069005
--- /dev/null
+++ b/docs/user_guide/index.md
@@ -0,0 +1,48 @@
+---
+description: User guide for Agent Memory Server.
+---
+
+# User Guide
+
+Start here on your first pass. The numbered tutorials below take you
+end-to-end from a clean machine to a memory-enabled application; the
+[how-to guides](how_to_guides/index.md) cover specific tasks once you
+know the basics.
+
+## Tutorials
+
+
+
+- :material-rocket-launch:{ .lg .middle } **[1. Quick start](01_quick_start.md)**
+
+ ---
+
+ Stand up the server, install the Python SDK, and store + retrieve your first memory in five minutes.
+
+- :material-package-variant:{ .lg .middle } **[2. Installation](02_installation.md)**
+
+ ---
+
+ Full install paths: Docker, pip, source.
+
+- :material-laptop:{ .lg .middle } **[3. Run without Docker](03_no_docker_setup.md)**
+
+ ---
+
+ Local Redis 8 plus a Python virtualenv only.
+
+