diff --git a/README.md b/README.md index efbb06cf..8abbb21d 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,191 @@ -# Redis Agent Memory +# Agent Memory Server -[Redis Agent Memory](https://redis.io/agent-memory/) is Redis's managed memory layer for AI agents: a persistent store that lets an agent recall facts, events, and preferences across sessions, without stuffing every token of history back into the prompt. It is part of [Redis Iris](https://redis.io/iris/), Redis's real-time context engine for agents. +> **For new agent memory projects on Redis, use [Redis Agent Memory](https://redis.io/agent-memory/) in [Redis Iris](https://redis.io/iris/).** It is the supported, maintained product. It runs as a managed service on Redis Cloud or self-managed on your own Kubernetes cluster. +> +> This repository holds the original open source Agent Memory Server (in [`V0/`](./V0/)), the research that shaped Redis Agent Memory. Agent Memory Server is deprecated and is not the supported production path. -[Redis Agent Memory docs](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/) · [Benchmark harness](./agent-memory-benchmark/) · [Benchmark write-up](https://redis.github.io/redis-ai-research-public/longmemeval-agent-memory/) +## Start with Redis Agent Memory -## Getting started +Redis Agent Memory is a memory service for AI agents. It keeps the active conversation in session memory and extracts durable facts, preferences and events into long-term memory in the background, so a later session can recall them without replaying the whole history into the prompt. It works with any agent framework or LLM provider. -- Product overview: [Redis Iris](https://redis.io/iris/) -- Agent Memory overview: [Redis Agent Memory docs](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/) -- Redis Cloud service guide: [Redis Agent Memory on Redis Cloud](https://redis.io/docs/latest/operate/rc/context-engine/agent-memory/) +1. Create an Agent Memory store: + + - Redis Cloud: [Create an Agent Memory service](https://redis.io/docs/latest/operate/iris/agent-memory/create-service/). + - Self-managed: [Deploy Agent Memory on Kubernetes](https://redis.io/docs/latest/operate/iris/agent-memory/self-managed/). -On Redis Cloud: + -1. [Create a database](https://redis.io/docs/latest/operate/rc/databases/create-database/). -2. [Create an Agent Memory service](https://redis.io/docs/latest/operate/rc/context-engine/agent-memory/create-service/). -3. Use the [Python SDK](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/python-sdk-quickstart/), [TypeScript SDK](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/typescript-sdk-quickstart/), or [REST API](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/rest-api-quickstart/) from your app. -4. Manage the service with the [Redis Cloud guide](https://redis.io/docs/latest/operate/rc/context-engine/agent-memory/). +2. Install the Redis Iris Python package, which includes the `iris` CLI: -Implementation details: [API and SDK examples](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/) and the [API reference](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/api-reference/). +```sh +pip install 'redis-iris>=1.0.0' +``` + +3. Set `IRIS_AGENT_MEMORY_URL`, `IRIS_AGENT_MEMORY_STORE_ID` and `IRIS_AGENT_MEMORY_API_KEY` from your store, then record a conversation and recall what Agent Memory extracted: + +```py +import time +from redis_iris.agent_memory import AgentMemory + +memory = AgentMemory.from_env() + +conversation = memory.conversation(owner="quickstart-user", session_id="travel-planning") +conversation.user("I am visiting Tokyo and Kyoto next month. I am vegetarian and prefer spicy food.") + +question = "What dietary requirements and food preferences does the user have?" +for _ in range(30): # extraction runs in the background + known = memory.recall(question, owner="quickstart-user") + if known: + break + time.sleep(10) +print(known.as_prompt()) +``` + +Next steps: + +- [Quickstart](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/quickstart/) in Python, the `iris` CLI or cURL +- [Developer guide](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/developer-guide/) +- [MCP](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/mcp/) for agents that search and curate memory through the store's MCP endpoint +- [API reference](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/api-reference/) + +## What is in this repository + +| Path | What it is | Status | +| :---- | :---- | :---- | +| [`V0/`](./V0/) | Agent Memory Server, the original open source memory server: Python, FastAPI, RedisVL and LiteLLM, with a REST API, Python client, CLI and MCP server | Deprecated. Preserved for study. | +| [`agent-memory-benchmark/`](./agent-memory-benchmark/) | A LongMemEval harness that runs against the Redis Agent Memory REST API and other memory providers | | -## How it works +## How Agent Memory Server relates to Redis Agent Memory -Redis Agent Memory uses a two-tier model. Session memory keeps active conversation state close at hand, with configurable TTL. Long-term memory stores extracted facts from past sessions as text plus vector embeddings for later retrieval. +Redis built Agent Memory Server first to test an idea: give agents a fast session memory and a durable long-term memory in Redis, and let a background process decide what moves from one to the other. That work validated the model that Redis Agent Memory is built on. -As new events land in session memory, Redis Agent Memory extracts what matters and promotes it to long-term memory in the background. Memory can accumulate without slowing the live agent loop. +What carried over: -Keeping full conversation history in the prompt does not scale. Context windows are bounded, long prompts are slow and expensive, and accuracy degrades as prompts grow. Agent memory lets an agent stay fast and cheap on every turn while still recalling what happened weeks ago. +- Two tiers: session (working) memory for the active conversation and long-term memory for durable facts, preferences and summaries. +- Background extraction from session data into long-term memory, so the agent loop stays fast. +- Retrieval with Redis vector search plus metadata filters. +- APIs to write, search, update and delete memory. -## Validated independently +What is different: -We ran a best-effort LongMemEval comparison across a sweep of memory systems, on a shared answer model and judge, to put those systems on more equal footing (Wu et al., ICLR 2025). Some vendors publish higher scores than we report. We were not able to reproduce those numbers under this protocol. +- Redis Agent Memory is a new implementation, not a hosted copy of this server. Redis rebuilt it as a product service with its own API, data model, SDKs and runtime. +- It adds what this server left to the operator: store provisioning, store-scoped API keys and access control, managed background workers, retention settings, and supported Cloud and Kubernetes deployment. +- It adds features this server does not have, including [custom memory types](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/long-term-memory/#custom-memory-types), [sensitive-data exclusions](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/developer-guide/#exclude-sensitive-data-from-automatic-extraction), [namespaces](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/namespaces/), [Summary Views](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/summary-views/) and [MemoryETL](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/memory-etl/) for building memory from documents. -A separate research configuration that combined two retrieval strategies (Instruct extraction and Remis) reached **86.5%** task-averaged accuracy in our evaluation, at about $0.07 per session. Remis is **not** in Redis Agent Memory in Iris yet, and that configuration is **not** what this public harness runs. Do not treat 86.5% as a Redis Cloud product score. +The two are not drop-in compatible. Moving an application from Agent Memory Server to Redis Agent Memory means changing endpoints, credentials, store IDs, and request and response models. [Migrate to Redis Agent Memory](https://redis.io/docs/latest/integrate/google-adk/agent-memory-server/#migrate-to-redis-agent-memory) in the Google ADK docs walks through the change for ADK apps. Switching does not copy existing memories, so plan for long-term memory to repopulate. -The public harness in [`agent-memory-benchmark/`](./agent-memory-benchmark/) evaluates the shipping Redis Agent Memory REST API and other adapters. It is an audit surface, not a timeless ranking. A result is evidence about a specific provider version, split, models, retrieval settings, artifacts, and run date. +## Which one to use -```bash +Use **Redis Agent Memory** when you are building something new, when you want Redis to run the service, or when you need supported security, isolation and lifecycle controls. That covers almost every case. + +Use **Agent Memory Server (V0)** when you want to read a working reference implementation of agent memory, study the extraction and retrieval approaches Redis tried first, or keep an existing deployment running while you migrate. You own everything if you run it: Redis, LLM access, authentication, workers, scaling, upgrades and backups. + +## Benchmarks + +[`agent-memory-benchmark/`](./agent-memory-benchmark/) runs LongMemEval (Wu et al., ICLR 2025\) against the Redis Agent Memory REST API and other memory providers on a shared answer model. Setup and provider recipes are in [`agent-memory-benchmark/README.md`](./agent-memory-benchmark/README.md). The full write-up is the [Agent Memory benchmark report](https://redis.io/resources/agent-memory-benchmark-report/). + +## Agent Memory Server (V0) quick start + +These instructions run the original server. They are kept accurate for existing users and for study. Full docs are in [`V0/docs/`](./V0/docs/index.md) and [`V0/README.md`](./V0/README.md). + +Requirements: Docker, or Python with [uv](https://docs.astral.sh/uv/), and an OpenAI API key (or another provider configured through LiteLLM). + +### Run with Docker + +Images: [`redislabs/agent-memory-server`](https://hub.docker.com/r/redislabs/agent-memory-server) on Docker Hub and [`ghcr.io/redis/agent-memory-server`](https://github.com/redis/agent-memory-server/pkgs/container/agent-memory-server). The last release is 0.15.2. + +```sh git clone https://github.com/redis/agent-memory-server.git -cd agent-memory-server/agent-memory-benchmark +cd agent-memory-server/V0 + +# Development: API and Redis, background tasks run in process +docker compose up api redis + +# Production-like: API, background worker, Redis and MCP server +docker compose up api task-worker redis mcp ``` -Setup, protocol, and provider recipes: [`agent-memory-benchmark/README.md`](./agent-memory-benchmark/README.md). +The image defaults to the Docket task backend, which needs a separate `agent-memory task-worker` process. For a single container, pass `--task-backend=asyncio`: -## V0 — the open-source research foundation +```sh +docker run -p 8000:8000 \ + -e REDIS_URL=redis://your-redis:6379 \ + -e OPENAI_API_KEY=your-key \ + redislabs/agent-memory-server:0.15.2 \ + agent-memory api --host 0.0.0.0 --port 8000 --task-backend=asyncio +``` -[`V0/`](./V0/) is the original Redis Agent Memory Server. It informed the Iris product. We keep it here as an open research artifact, not as the supported production distribution. Start at [`V0/README.md`](./V0/README.md). +### Run from source -## Citing this work +```sh +cd V0 +pip install uv +uv sync --all-extras +docker compose up redis +uv run agent-memory api --task-backend=asyncio +``` + +| Command | Use | +| :---- | :---- | +| `uv run agent-memory api --task-backend=asyncio` | Local development, one process | +| `uv run agent-memory api` | API server with Docket; also run `task-worker` | +| `uv run agent-memory task-worker --concurrency 10` | Background worker for Docket tasks | +| `uv run agent-memory mcp` | MCP server over stdio, for desktop MCP clients | +| `uv run agent-memory mcp --mode sse --port 9000` | MCP server over SSE | + +### Python client + +```sh +pip install agent-memory-client +``` + +```py +from agent_memory_client import MemoryAPIClient, MemoryClientConfig + +client = MemoryAPIClient(MemoryClientConfig(base_url="http://localhost:8000")) -Redis Applied AI Research, "How Redis Agent Memory Stacks Up: Benchmarking Memory Systems for AI Agents on LongMemEval," 2026. +await client.create_long_term_memory([ + {"text": "User prefers morning meetings", "user_id": "user123", "memory_type": "preference"} +]) + +results = await client.search_long_term_memory( + text="What time does the user like meetings?", + user_id="user123", +) +``` + +For agents, adding messages to working memory and letting the server extract memories in the background usually works better than writing memories by hand. See [Memory integration patterns](./V0/docs/memory-integration-patterns.md). The client also converts its tools for LangChain: [LangChain integration](./V0/docs/langchain-integration.md). + +### MCP configuration + +```json +{ + "mcpServers": { + "memory": { + "command": "uvx", + "args": ["--from", "agent-memory-server", "agent-memory", "mcp"], + "env": { + "DISABLE_AUTH": "true", + "REDIS_URL": "redis://localhost:6379", + "OPENAI_API_KEY": "" + } + } + } +} +``` + +Remove `DISABLE_AUTH` and set up [authentication](./V0/docs/authentication.md) before you expose the server to anyone else. + +## Maintenance and contributing + +Agent Memory Server is deprecated. + +For questions about Redis Agent Memory, use the [Redis Agent Memory docs](https://redis.io/docs/latest/develop/ai/context-engine/agent-memory/). + +## Citing this work -Also see [Building and evaluating long-term conversational memory](https://redis.github.io/redis-ai-research-public/longmemeval-agent-memory/). +Redis Applied AI Research, "How Redis Agent Memory Stacks Up: Benchmarking Memory Systems for AI Agents on LongMemEval," 2026\. ## License -Apache License 2.0 (Redis, Inc.). See [`LICENSE`](./LICENSE). +Apache License 2.0, Copyright Redis, Inc. See [`LICENSE`](./LICENSE).