Shared, persistent memory for a team of AI agents, over MCP. One SQLite file per project, hybrid search (keyword + local multilingual embeddings), safe for many agent processes at once. No API keys, no external services, no LLM calls.
claude mcp add agent-memory -s project -- npx -y agent-memory-storeAgents start every session from zero, and agents working in parallel don't
know what the others decided. agent-memory-store gives them one place to
search before acting and write what others will need — decisions with
their rationale, outputs and where they live, discoveries — plus a small
versioned key/value state for coordination (phase, owner, run id).
What makes it suitable for a team:
- Multilingual retrieval — a question in Portuguese finds a memory written in
English and vice versa; exact identifiers (
PAG-4821,orders.v1, paths) still match by keyword. - Many agents, one file — WAL, busy timeouts and compare-and-set versions; tested with concurrent processes, no lost writes.
- Update, don't duplicate — write with an
idto update in place; every write reports likely duplicates. - Safe by default — natural-language queries can't break search, expired memories disappear immediately, credentials are refused on write.
- Measured, not claimed — every number below comes from scripts in
benchmarks/that run the same code as the server.
Requires Node.js ≥ 22.16. The first start downloads the embedding model
(~310 MB) to ~/.cache/agent-memory-store/models; until it is ready,
search runs in keyword mode.
# shared by everyone who opens this repo (writes .mcp.json)
claude mcp add agent-memory -s project -- npx -y agent-memory-storeor in .mcp.json:
{
"mcpServers": {
"agent-memory": {
"command": "npx",
"args": ["-y", "agent-memory-store"],
"env": { "AGENT_MEMORY_AGENT": "backend-agent" }
}
}
}{
"mcp": {
"agent-memory": {
"type": "local",
"command": ["npx", "-y", "agent-memory-store"],
"enabled": true
}
}
}{
"mcpServers": {
"agent-memory": { "command": "npx", "args": ["-y", "agent-memory-store"] }
}
}The store lives in .agent-memory-store/store.db under the directory the
client starts the server from — one store per project. Add
.agent-memory-store/ to .gitignore. To share one store across repositories,
set AGENT_STORE_PATH to an absolute path.
The server sends a short usage protocol to the client automatically (MCP
server instructions). For multi-agent pipelines, add
skills/SKILL.md as a skill or paste this into
CLAUDE.md / AGENTS.md:
## Memory
- Before a task: `search_context` for prior decisions, conventions and outputs (any language).
- After a decision, output or discovery others need: `write_context` with a specific topic,
the content with its rationale, and 1–4 lowercase tags.
- Always pass your role as `agent` (e.g. `backend-agent`) on writes, same id every session.
- To change a memory, pass its `id` to `write_context`. Merge reported duplicates.
- Shared mutable values (phase, owner, run id): `get_state` / `set_state` with `expected_version`.
- Never store secrets — store where they live.| Tool | Purpose |
|---|---|
search_context |
Hybrid search. Filters: tags, agent, since/until. Returns snippets with score, similarity, version. |
write_context |
Create, or update in place with id. Optional expected_version (compare-and-set), ttl_days, importance. Reports likely duplicates. |
read_context |
Full text of one memory. |
list_context |
Newest first, metadata only, with total and paging. |
delete_context |
Delete one memory. |
get_state / set_state |
Versioned JSON values for coordination; expected_version: 0 = claim if unset. |
Full parameters, response formats and behavior: docs/DOCUMENTATION.md.
agent A ─┐ ┌─ FTS5 BM25 (topic 3× · tags 2× · content) ─┐
agent B ─┼─ MCP stdio servers ──┤ ├─ score fusion ─ results
agent C ─┘ (one per agent) └─ local embeddings → in-memory vector index ─┘
│
└── .agent-memory-store/store.db (SQLite, WAL, shared)
- Keyword: SQLite FTS5, accent-insensitive (
decisao=Decisão); every query term is quoted, so punctuation and operators can't cause syntax errors. - Semantic:
Snowflake/snowflake-arctic-embed-m-v2.0(multilingual, ONNX 8-bit, CPU) and exact cosine search over an in-memory index that each process keeps in sync with the file. - Fusion: weighted sum of per-query normalized scores, 70% semantic / 30% keyword — chosen on held-out queries, see Results. Importance and recency only break near-ties.
One command, one process, ~30 s, < 1 GB RAM:
npm run benchMeasured on an Apple M2 (8 GB), Node 25.6. Raw outputs:
benchmarks/results/. Every benchmark runs the same
MemoryStore code as the MCP server; quality numbers are identical across
runs, and the metric code is unit-tested against hand-computed values.
150 hand-written memories from a fictional product team (55% PT-BR, 45% EN),
120 queries: 35 cross-lingual, 35 paraphrases, 15 exact identifiers, 12
knowledge updates, 10 filtered, 13 multi-memory
(benchmarks/golden/dataset.json).
Synthetic and small: a regression test for the intended use, not a leaderboard.
Model (AGENT_MEMORY_MODEL) |
Hit@1 | Recall@5 | MRR | Search p50 | Write p50 | RAM / process |
|---|---|---|---|---|---|---|
none (keyword only) |
50.8% | 70.0% | 0.587 | 0.7 ms | 0.1 ms | 64 MB |
minilm-l6-en (0.0.x model) |
55.0% | 70.0% | 0.610 | 2.6 ms | 3.2 ms | 271 MB |
granite-97m-multilingual |
66.7% | 88.3% | 0.770 | 4.5 ms | 5.8 ms | 453 MB |
arctic-embed-m-v2 (default) |
74.2% | 95.8% | 0.836 | 8.6 ms | 13.9 ms | 628 MB |
embeddinggemma-300m |
74.2% | 96.7% | 0.841 | 57.9 ms | 94.1 ms | 1372 MB |
Hybrid mode. Search and write latency with 2,000 memories in an on-disk store
(write includes embedding and the duplicate check; reads are < 0.1 ms).
On Linux x64 (GitHub Actions) the default model scores 75.0% / 96.7% / 0.843
(int8 kernels differ slightly between ARM and x86), searches in 12.8 ms and
uses about 1.3 GB RAM per process — plan memory accordingly, or use
granite-97m-multilingual / none on small Linux machines.
Official retrieval protocol: session granularity, user turns only, abstention
and no-evidence questions excluded (n = 419 of 500, cleaned release),
metrics from the official eval_utils.py.
| Mode | R_any@5 | R_all@5 | R_any@10 | R_all@10 | NDCG@10 |
|---|---|---|---|---|---|
| keyword (BM25) | 95.5% | 84.2% | 96.4% | 89.3% | 0.882 |
LongMemEval indexes raw chat logs, not curated memories, and embedding its
~16K long sessions takes about an hour and several GB of RAM on a laptop, so
the hybrid run is optional: npm run bench:longmemeval (--sample 100 for a
stratified subset). The keyword run takes seconds:
node benchmarks/longmemeval.js --model none.
- Model —
arctic-embed-m-v2matches the best quality (EmbeddingGemma) within 0.005 MRR at 7× lower latency and half the RAM, is Apache-2.0, and separates near-duplicates well enough for the write-time duplicate warning. The 0.0.x model (all-MiniLM-L6-v2, English-only) fails cross-lingual queries: Recall@5 70.0% vs 95.8%. - Fusion — equal-weight reciprocal rank fusion (0.0.x) scored below
semantic-only search on the golden set, because keyword hits dilute
cross-lingual and paraphrase queries. A grid over method × weight was run on
the odd-numbered queries only; the chosen setting (convex combination, 0.7
semantic) was then confirmed on the even half (
npm run bench:tune-fusion). It keeps keyword strength for exact identifiers. - Duplicate warning — the similarity threshold per model is set for a ~5% false-positive rate on the golden set's superseded/superseding pairs.
Existing stores migrate automatically on first start (content, tags, timestamps and state are kept; vectors are recomputed in the background). Tool names are unchanged; new optional parameters only. Fixed along the way:
- searches containing
? ' . - / ,orAND/OR/NOTfailed with FTS5 syntax errors; min_scorewas ignored; expired memories were returned until restart;- updating meant delete + write;
INSERT OR REPLACEleft orphan index rows; - concurrent processes could fail with
SQLITE_BUSY; - the previously published "92.1% Recall@5" came from a copy of the search code that differed from production, a non-standard recall metric and a competitor table mixing different metrics; it is replaced by the reproducible results above.
| Variable | Default | |
|---|---|---|
AGENT_STORE_PATH |
./.agent-memory-store |
Store directory. |
AGENT_MEMORY_AGENT |
global |
Default agent id recorded on writes from this process. |
AGENT_MEMORY_MODEL |
arctic-embed-m-v2 |
Or granite-97m-multilingual (lighter), embeddinggemma-300m, minilm-l6-en, none (keyword only, ~64 MB RAM). All agents sharing a store must use the same model. |
AGENT_MEMORY_CACHE |
~/.cache/agent-memory-store/models |
Model cache. |
- Each agent process loads its own model copy (~630 MB on macOS ARM, ~1.3 GB
on Linux x64 with the default). With
many agents on a small machine, use
granite-97m-multilingual(~450 MB) ornone(~64 MB, keyword only). - Exact vector search is linear: fine up to ~100K memories per store.
- Only the first ~2000 characters of a memory are embedded; keyword search covers all of it. Prefer focused memories.
- Secret detection is pattern-based, not a DLP system. There is no access
control: whoever can read
store.dbcan read every memory.
npm install
npm test # unit, end-to-end over stdio, multi-process — no model download
AMS_MODEL_TESTS=1 npm test # + end-to-end with the real model
npm run bench # quality + speed, ~30 s
npm run bench:longmemeval # optional, heavy (see above)See CONTRIBUTING.md. Programmatic use (import { MemoryStore } from "agent-memory-store") is documented in docs/DOCUMENTATION.md.
MIT — see LICENSE.