# https://github.com/redis/agent-memory-server Project Manual Generated at: 2026-07-22 05:34:57 UTC ## Table of Contents - [Overview and System Architecture](#page-1) - [Core Memory Features: Working Memory, Long-Term Memory, Search, and Extraction](#page-2) - [Clients, APIs, MCP, and Workbench](#page-3) - [Operations, Deployment, LLM/Embedding Integration, and Extensibility](#page-4) ## Overview and System Architecture ### Related Pages Related topics: [Core Memory Features: Working Memory, Long-Term Memory, Search, and Extraction](#page-2), [Clients, APIs, MCP, and Workbench](#page-3), [Operations, Deployment, LLM/Embedding Integration, and Extensibility](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/redis/agent-memory-server/blob/main/README.md) - [V0/README.md](https://github.com/redis/agent-memory-server/blob/main/V0/README.md) - [V0/agent_memory_server/main.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent_memory_server/main.py) - [V0/agent_memory_server/api.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent_memory_server/api.py) - [V0/agent_memory_server/docket_tasks.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent_memory_server/docket_tasks.py) - [V0/agent_memory_server/config.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent_memory_server/config.py) - [V0/agent_memory_server/memory.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent_memory_server/memory.py) - [V0/agent_memory_server/llms.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent_memory_server/llms.py) - [V0/agent_memory_server/vector_search.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent_memory_server/vector_search.py)
# Overview and System Architecture ## Purpose and Scope Agent Memory Server (AMS) is a Redis-backed service that provides persistent, queryable memory for AI agents. It exposes a FastAPI HTTP API plus an optional CLI for managing two distinct memory tiers: short-lived **working memory** tied to a conversation session, and **long-term memory** that is extracted, embedded, and indexed for semantic retrieval. The server is designed to be embedded into an agent runtime (e.g., LangChain, LlamaIndex, or custom clients) so that user state, conversation history, and learned facts survive across sessions. The project ships as a PyPI package, a standard Docker image that requires an external Redis 8 instance, and a standalone Docker image with Redis embedded. Source: [README.md:1-80](). ## Core Architecture Components The server is built around a small set of cooperating modules: | Module | Responsibility | |---|---| | `main.py` | FastAPI application factory, middleware, lifespan, Docket worker registration | | `api.py` | HTTP route definitions for memory CRUD, search, and session management | | `memory.py` | Domain models (`WorkingMemory`, `MemoryRecord`, `MemoryMessage`) and serialization | | `docket_tasks.py` | Background tasks: memory structure extraction, deduplication, summarization, embedding | | `vector_search.py` | Vector index abstraction (Redis-based, with a LangChain adapter under discussion) | | `llms.py` | LLM provider wrappers (OpenAI, Anthropic, Bedrock) and embedding clients | | `config.py` | Environment-driven configuration, Redis connection, feature flags | ```mermaid flowchart LR Client[Agent / HTTP Client] -->|HTTP| API[api.py
FastAPI routes] API --> Memory[memory.py
domain models] API --> Tasks[docket_tasks.py
background tasks] Tasks --> LLM[llms.py
LLM + embeddings] Tasks --> VS[vector_search.py] API --> Redis[(Redis 8
KV + Vector + Search)] VS --> Redis Tasks --> Redis ``` The FastAPI app defined in `main.py` mounts routers from `api.py`, initializes the Redis connection on startup, and registers a Docket worker that consumes queued tasks. Source: [V0/agent_memory_server/main.py:1-120](). API routes accept Pydantic models from `memory.py` and translate them into Redis reads/writes plus queued background work. Source: [V0/agent_memory_server/api.py:1-200](). ## Memory Model Working memory is a per-session container holding ordered messages plus structured memory entries. `PUT /v1/working-memory/{session_id}` appends messages and may trigger summarization, structure extraction, and embedding asynchronously. Source: [V0/agent_memory_server/api.py:150-260](). Long-term memory is stored as `MemoryRecord` objects with vector embeddings, topic/entity metadata, and a namespace used for filtering. The `search_long_term_memory` endpoint accepts structured filters, recency weighting, and a `limit` parameter. Source: [V0/agent_memory_server/memory.py:1-180](). Community-reported behaviors that materially shape client integration: - The search `limit` parameter is hard-capped at 100; values above that fail with a Pydantic validation error rather than being clamped, which can read as an empty result from the client side. Source: [Issue #308](). - An empty `text` argument turns `search_long_term_memory` into a namespace listing primitive, returning up to `limit` records, but a relevance threshold means very weak matches may be omitted, so it is not a true enumerator. Source: [Issue #307](). - Results are relevance-ordered; even with `RecencyConfig(recency_weight=1.0, server_side_recency=True)` the `server_side_recency` contract is not honored consistently. Source: [Issue #306](). - `GET /v1/working-memory/{session_id}` historically returned an empty `WorkingMemory` with `new_session: true` for unknown sessions; this deprecated behavior is slated for removal. Source: [Issue #136](). - Working-memory summarization runs whenever messages are present and cannot be cleanly disabled today. Source: [Issue #193](). ## Background Processing with Docket Long-running or LLM-dependent work is deferred to a Docket worker rather than blocking the request thread. After a write to working memory, the API enqueues tasks such as memory-structure extraction, semantic deduplication, and embedding generation. Per-task timeouts were introduced in v0.13.2 to prevent LLM calls from hanging the queue. Source: [V0/agent_memory_server/docket_tasks.py:1-220](). The summarization feature itself was disabled by default in v0.15.0, reflecting community feedback that it was hard to control and rarely wanted. Source: [Release v0.15.0](); see also [Issue #193](). ## Configuration, LLMs, and Storage `config.py` reads environment variables to configure Redis connection strings, the embedding model, the LLM provider, feature flags (summarization enabled, extraction debounce TTL), and Docket worker concurrency. The LLM layer currently wraps OpenAI, Anthropic, and Bedrock via separate client classes; community discussion [#105]() proposes unifying these behind a single LiteLLM-backed client to remove the hand-maintained `MODEL_NAME_MAP`. Source: [V0/agent_memory_server/llms.py:1-160](). Vector search is implemented natively against Redis vector indexes. A LangChain adapter exists but is considered limiting because not all vector backends support the same metadata-filter semantics, and there is an open proposal to deprecate the adapter in favor of the internal interface. Source: [Issue #139](); see also [V0/agent_memory_server/vector_search.py:1-140](). The recommended deployment target is Redis 8 (`redis:8`), which bundles the modules AMS needs; several examples in the repository still reference Redis Stack images and are tracked for migration. Source: [Issue #287](). ## Versioning and Releases The server is released independently of its clients. As of the latest tag, Server v0.15.2 ships via PyPI and Docker (`redislabs/agent-memory-server:0.15.2`, standalone image also available). Companion clients include a Java client (v0.1.0, JVM 21) and a JavaScript client (v0.3.1) released from the same monorepo. Source: [Release Server v0.15.2](); [Release Java Client 0.1.0](). --- ## Core Memory Features: Working Memory, Long-Term Memory, Search, and Extraction ### Related Pages Related topics: [Overview and System Architecture](#page-1), [Clients, APIs, MCP, and Workbench](#page-3), [Operations, Deployment, LLM/Embedding Integration, and Extensibility](#page-4)
Related Source Files The following source files were used to generate this page: - [V0/agent_memory_server/working_memory.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent_memory_server/working_memory.py) - [V0/agent_memory_server/working_memory_index.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent_memory_server/working_memory_index.py) - [V0/agent_memory_server/long_term_memory.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent_memory_server/long_term_memory.py) - [V0/agent_memory_server/memory_strategies.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent_memory_server/memory_strategies.py) - [V0/agent_memory_server/extraction.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent_memory_server/extraction.py) - [V0/agent_memory_server/summarization.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent_memory_server/summarization.py)
# Core Memory Features: Working Memory, Long-Term Memory, Search, and Extraction The Agent Memory Server (AMS) provides a two-tier memory model for AI agents: a fast, session-scoped **Working Memory** for active conversation state, and a durable, semantically searchable **Long-Term Memory** for facts, preferences, and distilled knowledge. The bridge between them is an **extraction pipeline** that periodically promotes important information from working memory into long-term storage using LLM-driven analysis. ## Architecture and Data Flow ```mermaid flowchart LR A[Client / Agent] -->|PUT messages| B(Working Memory) B -->|debounced trigger| C{Extraction Pipeline} C -->|LLM topic/entity analysis| D[Memory Records] D -->|embeddings + HSET| E[(Redis: long-term store)] A -->|search_long_term_memory| F[Search Router] F -->|vector + filters| E F -->|relevance-ordered| A B -->|optional summary| G[Summarization] G -->|condensed context| B ``` Working memory is the short-lived, per-session scratchpad. Long-term memory is the persistent, queryable knowledge base. Search is the read-side access pattern over long-term memory. Extraction is the write-side promotion path. ## Working Memory Working memory holds the live conversation for a single session: ordered `messages`, optional structured `context`, optional long-term memory pointers, and a `long_term_memory_semantic_relations` map. The canonical operations are exposed in `working_memory.py`: - `get_working_memory(session_id)` — fetch the current session state, including lazy hydration of long-term memory pointers. - `set_working_memory(session_id, working_memory)` — write messages/context, kick off extraction, and optionally trigger summarization. - `delete_working_memory(session_id)` — remove session state. - `list_sessions(...)` and `list_working_memory(...)` — enumeration endpoints used by the CLI and workbench. Source: [V0/agent_memory_server/working_memory.py:1-120]() Sessions are stored in Redis sorted sets and JSON blobs. `working_memory_index.py` maintains secondary indexes (by user, by namespace, by recency) so that `list_sessions` can return results without scanning every key. Source: [V0/agent_memory_server/working_memory_index.py:1-80]() ### Known UX behavior - `GET /v1/working-memory/{session_id}` historically returned an empty `WorkingMemory` with `new_session: true` for missing sessions. This deprecated behavior is tracked in #136 and slated for removal. Source: [V0/agent_memory_server/working_memory.py:60-95]() - Summarization was disabled by default in v0.15.0 (PR #226) but cannot yet be cleanly turned off at runtime — see issue #193. ## Long-Term Memory and Search Long-term memory records are flat, queryable items with fields like `id`, `text`, `topics`, `entities`, `namespace`, `user_id`, `memory_type`, `created_at`, and `last_accessed_at`. Storage and indexing are abstracted through a `MemoryStrategy` interface, with the default Redis-backed implementation provided by `memory_strategies.py`. Source: [V0/agent_memory_server/memory_strategies.py:1-150]() The `search_long_term_memory` API is the primary read path. It supports: - **Text query**: semantic vector search over `text`. An empty `text=""` is interpreted as a pure listing primitive (no vector scoring) — see issue #307. - **Structured filters**: `namespace`, `user_id`, `topics`, `entities`, `memory_type` using Redis-style `eq/in` operators. - **Recency config**: `RecencyConfig(recency_weight, server_side_recency)` exists but, per issue #306, server-side recency ordering is not reliably applied; results are effectively relevance-ordered. - **Pagination**: `limit` (hard-capped at 100 via Pydantic validation) and `offset`. Exceeding the cap fails validation rather than clamping — issue #308. Source: [V0/agent_memory_server/long_term_memory.py:1-200]() ### Common parameters | Parameter | Type | Behavior | |---|---|---| | `text` | `str` | Semantic query text. Empty string → list-only mode | | `namespace` | `Filter` | `{"eq": "ns1"}` or `{"in": [...]}` | | `limit` | `int` | 1–100; over-limit raises Pydantic error | | `offset` | `int` | Standard pagination | | `recency` | `RecencyConfig` | Client hint; server-side ordering is unreliable | ## Extraction and Summarization The extraction pipeline is the write-side mechanism that turns ephemeral working-memory messages into durable long-term records. Flow in `extraction.py`: 1. After `set_working_memory`, a debounced background task (Docket) fires once the session has been quiet for the configured TTL. Source: [V0/agent_memory_server/extraction.py:1-100]() 2. The task calls an LLM (via the unified `LLMClient`) to extract **topics** and **entities** from the new messages, and to identify discrete memory records worth persisting. Topic/entity extraction defaults to LLM-driven since v0.12.7. 3. Each candidate is embedded (default OpenAI, with a LiteLLM wrapper added in v0.12.7), deduplicated semantically, and `HSET` into the long-term store. The HSET path is guarded against missing sessions per v0.15.0 fixes (PR by @Piotr1215). Source: [V0/agent_memory_server/extraction.py:100-260]() 4. Embedding failures on empty text were fixed in 0.13.1 (PR #134). Summarization is a separate, optional pass that condenses older working-memory messages into a rolling summary to keep token counts bounded. It is currently **disabled by default** as of v0.15.0 and has no clean runtime toggle (issue #193). Source: [V0/agent_memory_server/summarization.py:1-80]() ## Operational Notes and Known Footguns - **Search limit ceiling**: Always pass `limit ≤ 100`; otherwise the request fails before reaching the strategy. Issue #308. - **Listing via empty text**: Use `search_long_term_memory(text="", namespace={"eq": ns}, limit=100)` for enumeration; relevance scoring is skipped, but the relevance *cutoff* still applies, which can drop low-scored items — see issue #307. - **Ordering contract**: Do not rely on `RecencyConfig` for recency ordering; sort client-side using `created_at`/`last_accessed_at` until #306 is resolved. - **Session 404 vs empty**: Expect `GET` to start returning 404 for missing sessions once #136 lands. - **Summarization off**: Default behavior in 0.15.0+; no flag to re-enable per-session is exposed yet. --- ## Clients, APIs, MCP, and Workbench ### Related Pages Related topics: [Overview and System Architecture](#page-1), [Core Memory Features: Working Memory, Long-Term Memory, Search, and Extraction](#page-2), [Operations, Deployment, LLM/Embedding Integration, and Extensibility](#page-4)
Related Source Files The following source files were used to generate this page: - [V0/agent_memory_server/mcp.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent_memory_server/mcp.py) - [V0/agent_memory_server/cli.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent_memory_server/cli.py) - [V0/agent_memory_server/auth.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent_memory_server/auth.py) - [V0/agent-memory-client/agent_memory_client/client.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent-memory-client/agent_memory_client/client.py) - [V0/agent-memory-client/agent_memory_client/models.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent-memory-client/agent_memory_client/models.py) - [V0/agent-memory-client/agent_memory_client/filters.py](https://github.com/redis/agent-memory-server/blob/main/V0/agent-memory-client/agent_memory_client/filters.py) - [V0/agent-memory-server/README.md](https://github.com/redis/agent-memory-server/blob/main/V0/agent-memory-server/README.md)
# Clients, APIs, MCP, and Workbench The agent-memory-server (AMS) exposes its memory capabilities through several complementary surfaces: a FastAPI HTTP API, a Python client SDK, a JavaScript/TypeScript client, a Java client, an MCP (Model Context Protocol) server, a CLI, and the Workbench UI. Together they let applications, agents, and operators interact with short-term (working), long-term, and episodic memory without coupling to internal storage details. ## REST API and Python Client The server's HTTP API is the canonical interface. Endpoints cover working-memory CRUD per session, long-term-memory search, episodic-memory queries, summary views, and system health. Authentication is applied centrally through `auth.py`, which gates requests using a configurable token or integration before they reach the route handlers. Source: [V0/agent_memory_server/auth.py:1-120]() The Python client in `agent-memory-client` mirrors the API in a typed, ergonomic form. `client.py` exposes methods such as `get_working_memory`, `set_working_memory`, `search_long_term_memory`, `delete_long_term_memory`, and accessors for episodic memory and topics, each returning Pydantic models declared in `models.py`. Source: [V0/agent-memory-client/agent_memory_client/client.py:1-160]() Request and response shapes — `WorkingMemory`, `MemoryRecord`, `SearchRequest`, `RecencyConfig`, and namespace/user/session filter inputs — are defined in `models.py`, giving clients strong validation and IDE support. Source: [V0/agent-memory-client/agent_memory_client/models.py:1-200]() Filter helpers in `filters.py` translate Python keyword arguments into the structured predicate objects the API expects (equality, IN, range, and text predicates for namespace, topics, entities, and timestamps). Source: [V0/agent-memory-client/agent_memory_client/filters.py:1-160]() A few contract points that surface frequently in client usage: - The `limit` parameter for `search_long_term_memory` is hard-capped at 100; values above this fail Pydantic validation rather than being clamped, so callers receive an empty/error response and may interpret it as "no results." Source: community discussion #308 - An empty `text` argument combined with namespace/session filters acts as an enumeration primitive for listing records, but the relevance cutoff makes purely semantic queries non-enumerating. Source: community discussion #307 - Result ordering for `search_long_term_memory` is relevance-based, and `RecencyConfig.server_side_recency` does not guarantee recency-first ordering in current releases. Source: community discussion #306 These behaviors are part of the live contract clients must handle, even when undocumented. ## MCP Server `mcp.py` registers an MCP-compatible server that exposes AMS operations as tools callable by MCP-aware agents (for example, Claude-based or OpenAI-based assistants that negotiate the Model Context Protocol). Each tool wraps an underlying API call — `search_long_term_memory`, `get_working_memory`, `set_working_memory`, episodic reads — so agent runtimes can read and write memory without bespoke HTTP plumbing. Source: [V0/agent_memory_server/mcp.py:1-200]() This surface inherits the same auth and request validation as the HTTP API, and reuses the Pydantic models from `models.py`, so type guarantees are preserved across protocols. The MCP layer is the recommended integration for agent frameworks that already speak MCP, while the Python client remains the preferred path for service-to-service code. ## CLI `cli.py` provides operator-facing commands that wrap the same API surface. As of v0.14.0 it includes `search` and `delete` commands for long-term memory, plus session-scoped helpers for working memory, enabling shell-driven inspection, scripted cleanup, and quick troubleshooting without writing Python. Source: [V0/agent_memory_server/cli.py:1-200]() Output formatting uses the same `MemoryRecord` / `WorkingMemory` models, keeping human-readable output consistent with what clients receive programmatically. ## Workbench UI and Other Clients The AMS Workbench, introduced alongside v0.14.0, is a web UI for browsing sessions, inspecting long-term records, and triggering searches against a running server. It reads the same API the Python client does, so anything visible in Workbench is also reachable programmatically. Additional first-party clients include the JavaScript/TypeScript client (referenced in v0.13.2 fixes for `getWorkingMemory` options) and the Java client (released as Java Client 0.1.0, JVM 21). Both reuse the API contract documented in the server's OpenAPI schema, and both rely on the same auth, filter, and model definitions. Source: [V0/agent-memory-server/README.md:1-160]() ## Surface Comparison | Surface | Best for | Talks to | |---|---|---| | HTTP API / Python client | Service code, SDKs | FastAPI routes | | MCP server | MCP-aware agents | Same endpoints, MCP framing | | CLI | Ops, scripting | HTTP API | | Workbench UI | Browsing, debugging | HTTP API | | JS / Java clients | Polyglot apps | HTTP API | Choose the Python client or HTTP API for application integration, MCP for agent tool use, the CLI for operations, and the Workbench for human inspection. All four share the same auth, models, and filter semantics, so behavior — including the documented caveats above — applies uniformly. --- ## Operations, Deployment, LLM/Embedding Integration, and Extensibility ### Related Pages Related topics: [Overview and System Architecture](#page-1), [Core Memory Features: Working Memory, Long-Term Memory, Search, and Extraction](#page-2), [Clients, APIs, MCP, and Workbench](#page-3)
Related Source Files The following source files were used to generate this page: - [agent_memory_server/config.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/config.py) - [agent_memory_server/dependencies.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/dependencies.py) - [agent_memory_server/llm/client.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/llm/client.py) - [agent_memory_server/embeddings.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/embeddings.py) - [agent_memory_server/memory_vector_db.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/memory_vector_db.py) - [agent_memory_server/memory_vector_db_factory.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/memory_vector_db_factory.py) - [agent_memory_server/migrations.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/migrations.py) - [agent_memory_server/cli.py](https://github.com/redis/agent-memory-server/blob/main/agent_memory_server/cli.py) - [Dockerfile](https://github.com/redis/agent-memory-server/blob/main/Dockerfile)
# Operations, Deployment, LLM/Embedding Integration, and Extensibility ## Overview Agent Memory Server (AMS) is delivered as a Python package plus container images and is designed to be wired into existing Redis 8 deployments. Beyond the HTTP API surface, four concerns define how the server is run, scaled, and extended in production: 1. **Configuration** — Pydantic-based settings that control Redis connection, LLM provider, embeddings, summarization, extraction, and search behavior. 2. **Deployment** — PyPI distribution and two Docker image flavors (standard and standalone with embedded Redis). 3. **LLM and embedding integration** — provider wrappers and a LiteLLM-based embeddings path that AMS uses for memory extraction, topic/entity extraction, and vector generation. 4. **Extensibility** — a vector-store adapter factory and a migration runner that lets operators swap backends and evolve the data model. This page ties these four concerns together so operators and integrators can deploy AMS confidently and extend it without forking. ## Configuration Runtime configuration is loaded through `agent_memory_server/config.py`, which uses `pydantic-settings` to bind environment variables to typed settings models. The configuration object is exposed via FastAPI dependency injection so that routes, background tasks, and CLI commands share a single source of truth. Source: [agent_memory_server/config.py:1-80]() Key configurable areas include: - **Redis connection** — host, port, and optional TLS/auth for the underlying vector store and message store. - **LLM provider selection** — model name and credentials for the provider wrapper selected in `agent_memory_server/llm/client.py`. - **Embeddings** — model identifier and provider-specific options consumed by `agent_memory_server/embeddings.py`. - **Summarization and extraction** — token thresholds, debounce TTLs, and feature toggles. The summarization feature can be disabled (release v0.15.0). Source: [agent_memory_server/config.py:120-180]() - **Working-memory limits** — `max_messages`, `max_tokens`, and recency/search knobs used by long-term search. Community issue #193 highlights a current operational gap: there is no clean configuration switch to disable working-memory summarization on `PUT /v1/working-memory/{session_id}`, even though the feature itself is gated. Source: [Issue #193]() ## Deployment AMS ships three deployment surfaces, all reflected in the latest v0.15.2 release: | Surface | Command | Notes | | --- | --- | --- | | PyPI | `pip install agent-memory-server==0.15.2` | Library + server entrypoint | | Docker (standard) | `docker pull redislabs/agent-memory-server:0.15.2` | Requires an external Redis 8 instance | | Docker (standalone) | `docker pull redislabs/agent-memory-server:0.15.2-standalone` | Bundles an embedded Redis, suitable for local/dev | The `Dockerfile` produces the standard image; the standalone variant layers an embedded Redis so that a single container can boot end-to-end. Source: [Dockerfile:1-60]() Community issue #287 tracks migrating user-facing examples from Redis Stack images to Redis 8 (`redis:8`), since Redis 8 now ships the modules AMS depends on. Operators should plan to update compose files and `docker run` examples accordingly. Source: [Issue #287]() A CLI surface (`agent_memory_server/cli.py`) — added in v0.14.0 — provides operational commands such as `search` and `delete`, useful for back-office reconciliation and ad-hoc admin work. Source: [agent_memory_server/cli.py:1-40]() ```mermaid flowchart LR Client[Client / Workbench] --> API[FastAPI App] API --> Settings[config.py Settings] Settings --> LLM[llm/client.py] Settings --> EMB[embeddings.py] Settings --> VDB[memory_vector_db.py] VDB --> Factory[memory_vector_db_factory.py] Factory --> Redis[(Redis 8 / Vector Store)] API --> Migrations[migrations.py] ``` ## LLM and Embedding Integration LLM access is centralized in `agent_memory_server/llm/client.py`. The module historically exposed provider-specific wrappers (`OpenAIClientWrapper`, `AnthropicClientWrapper`, `BedrockClientWrapper`) and a `MODEL_NAME_MAP` used to detect the right wrapper from a model string. Source: [agent_memory_server/llm/client.py:1-120]() This design has known operational pain points captured in community issue #105: duplicated wrapper logic, manual provider detection, and inconsistent error handling across providers. The proposal is to unify everything behind a single `LLMClient` built on LiteLLM, so that adding a new provider is a configuration change rather than a code change. Source: [Issue #105]() Embeddings are loaded through `agent_memory_server/embeddings.py`. A LiteLLM-based embeddings wrapper was added in v0.12.7 and is now the recommended path because it shares LiteLLM's provider coverage with the LLM layer. Source: [agent_memory_server/embeddings.py:1-90]() Both layers are used by AMS for memory structure extraction, topic/entity extraction, summarization, and vector generation during indexing and long-term search. ## Extensibility: Vector Stores and Migrations AMS abstracts the vector store behind `agent_memory_server/memory_vector_db.py`, an interface that captures the operations the rest of the application relies on (upsert, vector + filter search, delete, count). Concrete backends are selected through `agent_memory_server/memory_vector_db_factory.py`, which reads the configured backend name and returns the right implementation. Source: [agent_memory_server/memory_vector_db_factory.py:1-60]() Community issue #139 proposes deprecating the LangChain-based vector search adapter: vector stores do not guarantee a common metadata-filter shape, and pinning to LangChain limits which backends can be plugged in. The recommended path is to build against the AMS interface directly, while still allowing alternative implementations. Source: [Issue #139]() Schema and index changes are handled by `agent_memory_server/migrations.py`, which is invoked at startup (and via the CLI) to bring the connected Redis instance to the expected version. Because long-term search has subtle ordering and limit semantics — `limit` is hard-capped at 100 with a Pydantic validation error on overflow (Issue #308), empty-text search acts as a listing/count primitive (Issue #307), and results are relevance-ordered with a still-unclear `server_side_recency` contract (Issue #306) — migrations are the right place to evolve index options without breaking clients. Sources: [agent_memory_server/migrations.py:1-80](), [Issue #308](), [Issue #307](), [Issue #306]() ## Putting It Together A typical production rollout reads configuration from the environment, connects to an external Redis 8 instance, and resolves LLM and embedding providers through the unified client layer. Operators who need a new vector backend implement the interface and register it with the factory; operators who need schema changes add a migration. Summarization and extraction features are gated through settings, with the current gap on per-request summarization opt-out tracked separately. This separation keeps the HTTP API stable while allowing the system underneath to evolve. --- --- ## Pitfall Log Project: redis/agent-memory-server Summary: Found 11 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: runtime_trace - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Repro command: `docker run -p 8000:8000 -e REDIS_URL=redis://your-redis:6379 -e OPENAI_API_KEY=your-key redislabs/agent-memory-server:latest agent-memory api` - Evidence: identity.distribution | https://github.com/redis/agent-memory-server ## 2. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/redis/agent-memory-server ## 3. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/redis/agent-memory-server/issues/306 ## 4. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a capability evidence risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/redis/agent-memory-server/issues/307 ## 5. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/redis/agent-memory-server ## 6. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/redis/agent-memory-server/issues/308 ## 7. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/redis/agent-memory-server ## 8. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/redis/agent-memory-server ## 9. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/redis/agent-memory-server ## 10. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/redis/agent-memory-server ## 11. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/redis/agent-memory-server