Related Pages

Related topics: Core Memory Features: Working Memory, Long-Term Memory, Search, and Extraction, Clients, APIs, MCP, and Workbench, Operations, Deployment, LLM/Embedding Integration, and Extensibility

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:

flowchart LR
  Client[Agent / HTTP Client] -->|HTTP| API[api.py<br/>FastAPI routes]
  API --> Memory[memory.py<br/>domain models]
  API --> Tasks[docket_tasks.py<br/>background tasks]
  Tasks --> LLM[llms.py<br/>LLM + embeddings]
  Tasks --> VS[vector_search.py]
  API --> Redis[(Redis 8<br/>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.

Related Pages

Related topics: Overview and System Architecture, Clients, APIs, MCP, and Workbench, Operations, Deployment, LLM/Embedding Integration, and Extensibility

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

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

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.

Related Pages

Related topics: Overview and System Architecture, Core Memory Features: Working Memory, Long-Term Memory, Search, and Extraction, Operations, Deployment, LLM/Embedding Integration, and Extensibility

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

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.

Related Pages

Related topics: Overview and System Architecture, Core Memory Features: Working Memory, Long-Term Memory, Search, and Extraction, Clients, APIs, MCP, and Workbench

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:

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

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.

Doramagic Pitfall Log

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
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: identity.distribution | https://github.com/redis/agent-memory-server

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/redis/agent-memory-server

3. Configuration risk: Configuration risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/redis/agent-memory-server/issues/306

4. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/redis/agent-memory-server/issues/307

5. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/redis/agent-memory-server

6. Runtime risk: Runtime risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/redis/agent-memory-server/issues/308

7. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/redis/agent-memory-server

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• 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
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/redis/agent-memory-server

10. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/redis/agent-memory-server

11. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/redis/agent-memory-server

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using agent-memory-server with real data or production workflows.

• docs: deduplicate=True merges distinct-but-similar records — ids are ups - github / github_issue
• docs/UX: search limit hard-capped at 100 — over-limit reads as empty res - github / github_issue
• docs: empty-text search as the listing/count primitive; relevance cutoff - github / github_issue
• docs: long-term search ordering is relevance-based — server_side_recency - github / github_issue
• Server v0.15.2 - github / github_release
• Server v0.15.1 - github / github_release
• Server v0.15.0 - github / github_release
• Server v0.14.0 - github / github_release
• Java Client 0.1.0 - github / github_release
• Server v0.13.2 - github / github_release
• 0.13.1 - github / github_release
• 0.13.0 - github / github_release