A-MEM: Self-evolving memory for coding agents
mcp-name: io.github.DiaaAj/a-mem-mcp
A-MEM is a self-evolving memory system for coding agents. Unlike simple vector stores, A-MEM automatically organizes knowledge into a Zettelkasten-style graph with dynamic relationships. Memories don't just get stored—they evolve and connect over time.
Currently tested with Claude Code. Support for other MCP-compatible agents is planned.
Quick Start
Install
pip install a-mem
Add to Claude Code
claude mcp add a-mem -s user -- a-mem-mcp \
-e LLM_BACKEND=openai \
-e LLM_MODEL=gpt-4o-mini \
-e OPENAI_API_KEY=sk-...
That's it! A session-start hook installs automatically to remind Claude to use memory.
Note: Memory is stored per-project in
./chroma_db. For global memory across all projects, see Memory Scope.
Uninstall
a-mem-uninstall-hook # Remove hooks first
pip uninstall a-mem
How It Works
t=0 t=1 t=2
◉───◉ ◉───◉
◉ │ ╱ │ ╲
◉ ◉──┼──◉
│
◉
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━▶
self-evolving memory
- Add a memory → A-MEM extracts keywords, context, and tags via LLM
- Find neighbors → Searches for semantically similar existing memories
- Evolve → Decides whether to link, strengthen connections, or update related memories
- Store → Persists to ChromaDB with full metadata and relationships
The result: a knowledge graph that grows smarter over time, not just bigger.
Features
Self-Evolving Memory Memories aren't static. When you add new knowledge, A-MEM automatically finds related memories and strengthens connections, updates context, and evolves tags.
Semantic + Structural Search Combines vector similarity with graph traversal. Find memories by meaning, then explore their connections.
Peek and Drill
Start with breadth-first search to capture relevant memories via lightweight metadata (id, context, keywords, tags). Then drill depth-first into specific memories with read_memory_note for full content. This minimizes token usage while maximizing recall.
MCP Tools
A-MEM exposes 8 tools to your coding agent:
| Tool | Description |
|---|---|
add_memory_note |
Store new knowledge (async, returns immediately) |
search_memories |
Semantic search across all memories |
search_memories_agentic |
Search + follow graph connections |
search_memories_by_time |
Search within a time range |
read_memory_note |
Get full details (supports bulk reads) |
update_memory_note |
Modify existing memory |
delete_memory_note |
Remove a memory |
check_task_status |
Check async task completion |
Example Usage
# The agent calls these automatically, but here's what happens:
# Store a memory (returns task_id immediately)
add_memory_note(content="Auth uses JWT in httpOnly cookies, validated by AuthMiddleware")
# Search later
search_memories(query="authentication flow", k=5)
# Deep search with connections
search_memories_agentic(query="security", k=5)
Advanced Configuration
JSON Config
For more control, edit ~/.claude/settings.json (global) or .claude/settings.local.json (project):
{
"mcpServers": {
"a-mem": {
"command": "a-mem-mcp",
"env": {
"LLM_BACKEND": "openai",
"LLM_MODEL": "gpt-4o-mini",
"OPENAI_API_KEY": "sk-..."
}
}
}
}
Environment Variables
| Variable | Description | Default |
|---|---|---|
LLM_BACKEND |
openai, ollama, sglang, openrouter |
openai |
LLM_MODEL |
Model name | gpt-4o-mini |
OPENAI_API_KEY |
OpenAI API key | — |
EMBEDDING_MODEL |
Sentence transformer model | all-MiniLM-L6-v2 |
CHROMA_DB_PATH |
Storage directory | ./chroma_db |
EVO_THRESHOLD |
Evolution trigger threshold | 100 |
Memory Scope
- Project-specific (default): Each project gets isolated memory in
./chroma_db - Global: Share across projects by setting
CHROMA_DB_PATH=~/.local/share/a-mem/chroma_db
Alternative Backends
Ollama (local, free)
claude mcp add a-mem -s user -- a-mem-mcp \
-e LLM_BACKEND=ollama \
-e LLM_MODEL=llama2
OpenRouter (100+ models)
claude mcp add a-mem -s user -- a-mem-mcp \
-e LLM_BACKEND=openrouter \
-e LLM_MODEL=anthropic/claude-3.5-sonnet \
-e OPENROUTER_API_KEY=sk-or-...
Hook Management (Claude Code)
The session-start hook reminds Claude to use memory tools. It installs automatically with Claude Code, but you can manage it manually:
a-mem-install-hook # Install/reinstall hook
a-mem-uninstall-hook # Remove hook completely
Python API
Use A-MEM directly in Python (works with any agent or application):
from agentic_memory.memory_system import AgenticMemorySystem
memory = AgenticMemorySystem(
llm_backend="openai",
llm_model="gpt-4o-mini"
)
# Add (auto-generates keywords, tags, context)
memory_id = memory.add_note("FastAPI app uses dependency injection for DB sessions")
# Search
results = memory.search("database patterns", k=5)
# Read full details
note = memory.read(memory_id)
print(note.keywords, note.tags, note.links)
Research
A-MEM implements concepts from the paper:
A-MEM: Agentic Memory for LLM Agents Xu et al., 2025 arXiv:2502.12110
Metadata
Release files for a-mem 0.2.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| a_mem-0.2.6.tar.gz | 58.0 kB | Without provenance | Details for a_mem-0.2.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| a_mem-0.2.6-py3-none-any.whl | Python 3 | none | any | Details for a_mem-0.2.6-py3-none-any.whl |
Total release size: 118.0 kB
Release files / a_mem-0.2.6.tar.gz
| Download URL | a_mem-0.2.6.tar.gz |
|---|---|
| Size | 58.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
242921f897003f955137c261b7f30342de76491870b17587d343601c08c07fdf
|
|
BLAKE2b-256 checksum How to use checksums |
8aa7aea9d5542af3b4c95fc292d7febb7deb0c461399a65d302bdb4599c4827c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / a_mem-0.2.6-py3-none-any.whl
| Download URL | a_mem-0.2.6-py3-none-any.whl |
|---|---|
| Size | 60.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a92cf0efd7ddb5d6ae6cd6ff0e964436e9113355e5ef53c1294ab6f6fafdcdc1
|
|
BLAKE2b-256 checksum How to use checksums |
4b7240cacd1c3fba2bbcb3617a1f170ff188586a8faf16f90e564a3dea71d9bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Security for a-mem 0.2.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.