# agent-memory-mcp

**Give your agents memory. Give them direction. Open the context window.**

The context window is the most expensive real estate in AI development. Most teams fill it with the same documents, the same re-derived dependencies, the same facts the agent already knew from last session. The window bloats. The cost compounds. The agent still starts from scratch.

`agent-memory-mcp` solves the other half of the problem.

Not retrieval — traversal. Your agent doesn't search for what looks similar. It walks declared relationships: what came before, what depends on what, what decision caused what outcome. Persistent across sessions. Zero external services. One config entry.

Combined with a sealed knowledge appliance ([ckg-mcp](https://pypi.org/project/ckg-mcp/)), your agent has both layers of what a production system needs: memory for what it *did*, and structured knowledge for what's *true*. That's not a wider context window — that's a smarter one.

[![PyPI](https://img.shields.io/pypi/v/agent-memory-mcp)](https://pypi.org/project/agent-memory-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

![agent-memory-mcp architecture](assets/graph.svg)

> ⭐ **If this saves you tokens, star it** — it's how other developers find it.

---

## The problem

Most teams give their agents a document dump and call it knowledge. Most agents start every session with no sense of where they've been. The result:

- Re-explaining your stack, your preferences, your constraints — every session
- Re-discovering which tool worked and which didn't
- Re-fetching context the agent already built last time
- Burning tokens on what the agent already knew
- No memory of decisions made, no record of what was tried and failed

This isn't a model problem. It's a memory architecture problem — and it compounds with every agent call you pay for.

---

## Install

```bash
# Run directly — no install needed
uvx --from agentmem-mcp agent-memory

# Or install
pip install agentmem-mcp
```

---

## MCP config

### Claude Desktop

```json
{
  "mcpServers": {
    "agent-memory": {
      "command": "uvx",
      "args": ["--from", "agentmem-mcp", "agent-memory"]
    }
  }
}
```

### Cursor / Windsurf / NVIDIA AgentIQ

Same config — drop it in your `mcp_servers.json`. Any MCP-compatible client works.

Memories persist to `~/.agent-memory/memories.db` — SQLite, no external services, no API keys.

---

## Tools

| Tool | What it does |
|---|---|
| `remember(content, category, tags)` | Store a memory. Auto-links to related existing memories. |
| `recall(query, limit)` | Search by keyword. Returns matches with their graph connections. |
| `get_related(memory_id, depth)` | Traverse the graph outward 1–3 hops from a memory. |
| `link_memories(source, target, relationship)` | Declare a typed edge between two memories. |
| `list_memories(category, limit)` | Browse by category: fact, tool, decision, preference, context… |
| `forget(memory_id)` | Delete a memory and all its edges. |

**Categories:** `fact` · `tool` · `preference` · `context` · `relationship` · `task` · `decision`

**Edge types:** `DEPENDS_ON` · `SUPPORTS` · `CONTRADICTS` · `PRECEDES` · `CAUSES` · `RELATES_TO`

---

## Usage patterns

### 1. Cross-session continuity

The agent picks up where it left off — no re-introduction needed.

```
Session 1:
  remember("User prefers FastAPI over Flask", "preference", ["python", "api"])
  remember("Project uses Postgres 15 on Supabase", "fact", ["database"])
  remember("Avoid Alembic — use raw migrations", "preference", ["database"])

Session 2:
  recall("database preferences")
  → Returns Postgres fact + Alembic preference with RELATES_TO edge between them
```

### 2. Dependency chain memory

The agent stores what it discovered about your stack — so it doesn't re-discover it.

```
remember("TensorRT requires CUDA 11.8+", "fact", ["tensorrt", "cuda"])
remember("CUDA 11.8 install requires gcc 9+", "fact", ["cuda", "build"])
link_memories(tensorrt_id, cuda_id, "DEPENDS_ON")
link_memories(cuda_id, gcc_id, "DEPENDS_ON")

→ get_related(tensorrt_id, depth=3) returns the full dependency chain
```

### 3. Decision trail

The agent remembers why it made a choice — not just what it chose.

```
remember("Chose ChromaDB over Pinecone: latency and no API key requirement", "decision", ["vector-db"])
remember("Pinecone rejected: requires API key in CI environment", "context", ["vector-db", "ci"])
link_memories(decision_id, context_id, "CAUSES")

→ Three months later: recall("vector db decision") surfaces both with the causal link
```

### 4. Tool performance learning

The agent tracks what worked — and what didn't.

```
remember("exa_search returns better results than web_search for technical docs", "tool", ["search"])
remember("brave_search rate-limited after 10 calls/min in production", "tool", ["search", "production"])

→ Before next search: recall("search tools") returns ranked performance memories
```

### 5. Multi-step task tracking

The agent tracks where a long-running task is — even across sessions.

```
remember("Migration step 1/4 complete: users table done", "task", ["migration", "postgres"])
remember("Step 2/4 blocked: foreign key constraint on orders table", "task", ["migration", "blocker"])
link_memories(step1_id, step2_id, "PRECEDES")

→ Next session: recall("migration status") returns the full chain with the blocker flagged
```

### 6. Pair with a sealed knowledge appliance (CKG)

Memory tells the agent what it **did**. Knowledge tells it what's **true**.

```
# Memory: agent remembers what it tried
remember("NIM deployment failed on t3.medium: insufficient VRAM", "fact", ["nim", "aws"])

# Knowledge: CKG tells it the dependency chain it should have known
query_ckg("NIM", "nvidia-nim", depth=3)
→ NIM → TensorRT-LLM → GPU Memory ≥24GB → A10G minimum
```

The agent now has both: its own experience (memory) and the declared domain rules (knowledge).

See [ckg-mcp](https://pypi.org/project/ckg-mcp/) — 97 domains of sealed knowledge appliances, or build your own at [graphifymd.com/pro/](https://graphifymd.com/pro/).

---

## Context compression and optimization

This is the underlying problem agent-memory-mcp solves — not just "memory."

**The standard approach:** inject raw documents into the context window. 2,982 tokens to answer one question about your stack. Every call. Every session.

**The graph approach:** traverse declared relationships. 269 tokens for the same answer — the exact chain, nothing more.

That's **11× context compression**. Not by summarizing or chunking. By replacing document retrieval with graph traversal. You don't inject a manual — you walk a map.

Context optimization means the agent gets *exactly* what it needs to reason:
- Not "here are 40 pages about CUDA" — but "NIM → TensorRT → CUDA 11.8+ → Hopper SM90"
- Not "here are your last 200 conversation turns" — but the 3 decisions that led to this moment
- Not similarity guesses — declared edges the agent itself wrote

The result: smaller prompts, faster responses, lower cost, and an agent that reasons rather than retrieves.

---

## Why graph, not vector?

Vector similarity finds *related* content. Graph traversal finds *declared* connections.

| | Vector | Graph |
|---|---|---|
| How it works | Embedding similarity | Declared typed edges |
| Best for | Fuzzy recall, semantic search | Reasoning chains, dependency traversal |
| Answer to "what came before X?" | Approximation | Exact traversal |
| Can be wrong? | Yes — guesses | No — only returns declared edges |

`agent-memory-mcp` auto-links new memories to related existing ones on write (via keyword overlap), then lets you declare precise typed edges when the relationship matters.

**The graph doesn't guess. It traverses.**

---

## Benchmark

Memory quality benchmarked against [KRB Benchmark v0.6.2](https://github.com/Yarmoluk/ckg-benchmark/blob/main/paper/main.pdf):

| System | F1 | Tokens/query |
|---|---|---|
| **CKG graph traversal** | **0.471** | **269** |
| RAG (vector retrieval) | 0.123 | 2,982 |
| GraphRAG | 0.120 | — |

~4× F1 · 11× fewer tokens · auditable by design

---

## Pair it with domain knowledge

agent-memory-mcp handles what your agent **experiences**. [ckg-mcp](https://pypi.org/project/ckg-mcp/) handles what your agent **knows**.

```bash
pip install ckg-mcp
```

97 domains ready to query: NVIDIA AI stack, financial regulations, healthcare standards, manufacturing safety, legal frameworks, and more. Free tier included.

**[→ Browse domains and pricing at graphifymd.com/pro/](https://graphifymd.com/pro/)**

---

## Partners and integrations

We're looking for:

- **MCP client integrations** — if you're building an agent runtime that supports MCP, we'd like to be in your default toolchain
- **Domain experts** — if you have proprietary knowledge that would be more useful as a traversable graph than a document corpus, let's talk
- **Enterprise pilots** — regulated industries (finance, healthcare, manufacturing, legal) where agents need auditable, declared knowledge rather than probabilistic retrieval
- **Researchers** — working on agent memory, knowledge representation, or MCP tooling

Reach out: [graphifymd.com](https://graphifymd.com) · [daniel.yarmoluk@gmail.com](mailto:daniel.yarmoluk@gmail.com)

---

## Related

- **[ckg-mcp](https://pypi.org/project/ckg-mcp/)** — 97 sealed knowledge appliances via MCP
- **[ckg-nvidia-ai](https://github.com/Yarmoluk/ckg-nvidia-ai)** — 20 NVIDIA AI domain graphs, 998 nodes, free
- **[KRB Benchmark](https://huggingface.co/datasets/danyarm/ckg-benchmark)** — open benchmark dataset
- **[graphifymd.com/pro/](https://graphifymd.com/pro/)** — Context-as-a-Service: build or subscribe to sealed knowledge appliances

---

## License

MIT — built by [Graphify.md](https://graphifymd.com). Patent pending.