agentic-memory MCP server

---

Every AI agent has amnesia.

Claude forgets your last conversation. GPT doesn't know what you decided last week. Your copilot can't recall the architecture discussions from three months ago. Every session starts from zero.

The current fixes don't work. Vector databases lose all structure -- you get "similar text," never "why did I decide this?". Markdown files are slow and break at scale. Key-value stores are flat -- no relationships, no reasoning chains. Provider memory is locked to one vendor.

AgenticMemory stores your agent's knowledge as a navigable graph in a single binary file. Not "search your old conversations." Your agent has a brain -- facts, decisions, reasoning chains, corrections, and skills -- all connected, all queryable in microseconds.

Problems Solved (Read This First)

• Problem: every chat starts over and previous decisions disappear.
  Solved: persistent .amem memory survives restarts, model switches, and long gaps between sessions.
• Problem: vector search returns "similar text" but not true reasoning trails.
  Solved: graph traversal, causal paths, and decision lineage are first-class queries.
• Problem: corrections overwrite truth and erase history.
  Solved: supersession chains preserve old and new beliefs with auditable change history.
• Problem: memory quality degrades silently over time.
  Solved: quality, drift, gap, and revision tooling keep memory reliable at runtime.
• Problem: long-term memory becomes too heavy to keep portable.
  Solved: compact single-file storage with practical multi-year lifespan and backup portability.

from agentic_memory import Brain

brain = Brain("my_agent.amem")

# Your agent learns
brain.add_fact("User is a senior Rust developer", session=1, confidence=0.95)
brain.add_decision("Recommended tokio for async -- team has no Go experience", session=1)

# Session 47 -- months later, different LLM, same brain:
results  = brain.search("async runtime")          # Hybrid BM25 + vector search
chain    = brain.traverse(decision_id)             # Why did I decide this?
current  = brain.resolve(old_fact_id)              # What's the latest version?
report   = brain.revise("Team now knows Go")       # If this is true, what breaks?
gaps     = brain.gaps()                            # Where am I guessing?
timeline = brain.drift("programming languages")    # How has this belief changed?

Operational reliability commands (CLI):

amem quality my_agent.amem
amem runtime-sync my_agent.amem --workspace . --write-episode

Six lines. Sixteen query types. One file holds everything. Works with Claude, GPT, Ollama, or any LLM you switch to next.

---

V3: Immortal Architecture

New in v0.4.1 -- Memory that never dies.

V3 adds a complete append-only, content-addressed storage layer with BLAKE3 integrity chains. Your agent's memory is now cryptographically tamper-proof, multi-client, and designed to last 20 years.

Core Capabilities

• Immortal Log -- Append-only storage with BLAKE3 integrity chains. Never deletes. Never modifies.
• Five Indexes -- Temporal, semantic, causal, entity, and procedural. Find anything instantly.
• Tiered Storage -- Hot -> Warm -> Cold -> Frozen. 20 years of memory in ~500MB.
• Ghost Writer -- Auto-syncs to Claude, Cursor, Windsurf, and Cody. Zero configuration.
• Smart Retrieval -- Multi-index fusion with token budgeting. Perfect context assembly.
• Crash Recovery -- WAL with CRC32 checksums. Survives anything.
• MCP Hardening -- Content-Length framing with 8 MiB limit, JSON-RPC 2.0 validation, no silent fallbacks.

Multi-Client Support

Client	Auto-Sync Location	Status
Claude Code	~/.claude/memory/V3_CONTEXT.md	Full support
Cursor	~/.cursor/memory/agentic-memory.md	Full support
Windsurf	~/.windsurf/memory/agentic-memory.md	Full support
Cody	~/.sourcegraph/cody/memory/agentic-memory.md	Full support

V3 Architecture

+-------------------------------------------------------------+
|                     YOUR AI AGENT                           |
|           (Claude, Cursor, Windsurf, Cody)                  |
+----------------------------+--------------------------------+
                             |
                  +----------v----------+
                  |      MCP LAYER      |
                  |   Tools + Resources |
                  +----------+----------+
                             |
+----------------------------v--------------------------------+
|                        V3 ENGINE                            |
+--------------+--------------+--------------+----------------+
| Immortal Log | 5 Indexes    |Tiered Storage| Ghost Writer   |
| (append-only)| (T/S/C/E/P)  | (H/W/C/F)   | (multi-client) |
+--------------+--------------+--------------+----------------+
                             |
                  +----------v----------+
                  |     .amem FILE      |
                  |    (your memory)    |
                  +---------------------+

The Five Indexes

Index	Purpose	Query Type
Temporal	Find by time	"What happened yesterday?"
Semantic	Find by meaning	"Everything about contracts"
Causal	Find decision chains	"Why did we choose Rust?"
Entity	Find by file/person	"All changes to main.rs"
Procedural	Find workflows	"Steps to deploy"

Tiered Storage

Tier	Age	Access Time	Storage
Hot	< 24 hours	< 1ms	Memory
Warm	< 30 days	< 10ms	Disk
Cold	< 1 year	< 100ms	Compressed
Frozen	Forever	< 1s	Archive

---

V3 MCP Tools

AgenticMemory V3 exposes 13 MCP tools for AI agents:

Capture Tools

Tool	Description
memory_capture_message	Capture user/assistant messages
memory_capture_tool	Capture tool calls with input/output
memory_capture_file	Capture file operations
memory_capture_decision	Capture decisions with reasoning
memory_capture_boundary	Capture session boundaries (compaction, etc.)

Retrieval Tools

Tool	Description
memory_retrieve	Smart context assembly with token budgeting
memory_resurrect	Restore full state at any timestamp
memory_v3_session_resume	Load context for session continuation

Search Tools

Tool	Description
memory_search_temporal	Search by time range
memory_search_semantic	Search by meaning/text
memory_search_entity	Search by file/person/entity

Stats Tools

Tool	Description
memory_v3_stats	Storage and index statistics
memory_verify_integrity	Cryptographic integrity verification

MCP Resources

memory://v3/session/context   -- Full session context
memory://v3/session/decisions -- Recent decisions
memory://v3/session/files     -- Files modified
memory://v3/session/errors    -- Errors resolved
memory://v3/session/activity  -- Recent activity
memory://v3/stats             -- Storage statistics

---

Benchmarks

Rust core. Memory-mapped I/O. Zero-copy access. Real numbers from Criterion statistical benchmarks:

Operation	Time	Scale
Add node	276 ns	10K graph
Add edge	1.2 ms	10K graph
Traverse depth-5	3.4 ms	100K nodes
Similarity search (top 10)	9.0 ms	100K nodes
BM25 text search (fast path)	1.58 ms	100K nodes
BM25 text search (slow path)	122 ms	100K nodes
Hybrid search (BM25 + vector)	10.83 ms	100K nodes
PageRank convergence	34.3 ms	100K nodes
Bidirectional BFS shortest path	104 us	100K nodes
Belief revision (cascade)	53.4 ms	100K nodes
Drift detection	68.4 ms	100K nodes
Read 10K nodes from file	3.7 ms	--
mmap node access	370 ns	100K nodes

All v0.2 query benchmarks measured with Criterion (100 samples) on Apple M4 Pro, 64 GB, Rust 1.90.0 --release. Computationally intensive queries (gap detection 297s, analogical 229s, consolidation 43.6s at 100K) are designed for periodic/offline execution and complete in <3s at 10K nodes.

Capacity: A year of daily use produces a ~24 MB file. A decade fits in ~240 MB. A lifetime of memory fits in under 1 GB.

	Vector DB	Markdown Files	Key-Value Store	AgenticMemory
Storage / 10K events	~500 MB	~200 MB	~50 MB	~8 MB
Query latency (p99)	~50 ms	~200 ms	~30 ms	<1 ms
Relationship tracking	None	None	None	7 typed edges
Query types	1 (similarity)	1 (keyword)	1 (key lookup)	16
Portability	Vendor-locked	File-based	API-locked	Single file
External dependencies	Cloud service	Embedding API	Cloud service	None
Reconstruct reasoning	No	No	No	Yes
Self-correction history	No	No	Partial	Yes
"What breaks if X changes?"	No	No	No	Yes
"Where am I guessing?"	No	No	No	Yes

---

Why AgenticMemory

Memory is a graph, not a search index. When you remember why you made a decision, you traverse a chain: decision <- caused by <- these facts <- inferred from <- observations. That's graph navigation. Vector similarity search can never reconstruct this.

One file. Truly portable. Your entire memory is a single .amem file. Copy it. Back it up. Version control it. No cloud service, no API keys, no vendor lock-in.

Any LLM, any time. Start with Claude today. Switch to GPT tomorrow. Move to a local model next year. Same brain file. Cross-provider validation report with 21 interoperability tests.

Self-correcting. Corrections don't delete -- they SUPERSEDE. The old fact, the new fact, and the correction chain are all preserved. brain.resolve(old_id) always returns the current truth.

Sixteen query types. Not just search. Traversal, pattern matching, temporal comparison, causal impact, similarity, BM25 text search, hybrid search, graph centrality, shortest path, belief revision, reasoning gap detection, analogical reasoning, consolidation, drift detection, context extraction, and resolve. Five of these don't exist anywhere else.

---

The Query Engine

Sixteen ways to navigate a cognitive graph. Seven are foundational. Four are established algorithms adapted for cognitive graphs. Five are genuinely novel -- they don't exist in any other system.

#	Query	What it answers
1	Traversal	"Why did I decide this?" -- walk reasoning chains
2	Pattern	"Show me all low-confidence decisions from last week"
3	Temporal	"What changed between session 5 and session 20?"
4	Impact	"What depends on this fact?"
5	Similarity	"What else do I know about this topic?"
6	Context	"Give me everything around this node"
7	Resolve	"What's the current truth after corrections?"
8	BM25 Search	"Find memories containing these exact terms" (1.58 ms @ 100K)
9	Hybrid Search	BM25 + vector fusion via RRF (10.83 ms @ 100K)
10	Centrality	"What are my foundational beliefs?" -- PageRank (34.3 ms @ 100K)
11	Shortest Path	"How are these two ideas connected?" -- BFS in 104 us
12	Belief Revision	"If I learn X, what breaks?" -- counterfactual cascade
13	Reasoning Gaps	"Where am I guessing?" -- 5 gap categories
14	Analogical	"I've solved something like this before" -- structural fingerprints
15	Consolidation	"Clean up: dedup, link contradictions, promote inferences"
16	Drift Detection	"How has my understanding of this topic evolved?"

Belief Revision -- Counterfactual propagation. Inject a hypothetical fact, trace every causal edge forward, report what gets invalidated. Read-only -- nothing changes until you say so. Only possible because of typed causal edges + confidence scores.

report = brain.revise("Team now knows Go")
# report.contradicted -> ["Team has no Go experience"]
# report.invalidated_decisions -> ["Chose Rust because no Go"]
# report.total_affected -> 5 nodes

Reasoning Gaps -- Structural health audit. Finds decisions with no recorded justification, inferences built on a single fragile fact, high-impact nodes with low confidence, and correction chains that keep changing.

report = brain.gaps()
# report.health_score -> 0.73
# report.gaps -> [UnjustifiedDecision(...), SingleSourceInference(...), ...]

Analogical Reasoning -- Subgraph pattern matching. Finds past situations with the same reasoning structure even if the domain is completely different. A monolith-to-microservices migration matches a previous Flask-to-FastAPI migration -- same shape, different content.

Consolidation -- Brain maintenance. Deduplicates near-identical facts, detects unlinked contradictions, promotes stable inferences to facts. Dry-run by default. Automatic backup before any mutation.

Drift Detection -- Belief trajectory tracking. Shows how knowledge about a topic evolved session by session, computes stability scores, and identifies areas of active revision.

report = brain.drift("preferred language")
# Timeline: Python (session 1) -> Rust (session 15) -> exploring Zig (session 30)
# report.stability -> 0.3 (low -- keeps changing)

---

Install

One-liner (desktop profile, backwards-compatible):

curl -fsSL https://agentralabs.tech/install/memory | bash

Downloads a pre-built agentic-memory-mcp binary to ~/.local/bin/ and merges the MCP server into your Claude Desktop and Claude Code configs. Memory defaults to ~/.brain.amem. Requires curl and jq. If release artifacts are not available, the installer automatically falls back to cargo install --git source install.

Environment profiles (one command per environment):

# Desktop MCP clients (auto-merge Claude Desktop + Claude Code when detected)
curl -fsSL https://agentralabs.tech/install/memory/desktop | bash

# Terminal-only (no desktop config writes)
curl -fsSL https://agentralabs.tech/install/memory/terminal | bash

# Remote/server hosts (no desktop config writes)
curl -fsSL https://agentralabs.tech/install/memory/server | bash

Channel	Command	Result
GitHub installer (official)	curl -fsSL https://agentralabs.tech/install/memory | bash	Installs release binaries when available, otherwise source fallback; merges MCP config
GitHub installer (desktop profile)	curl -fsSL https://agentralabs.tech/install/memory/desktop | bash	Explicit desktop profile behavior
GitHub installer (terminal profile)	curl -fsSL https://agentralabs.tech/install/memory/terminal | bash	Installs binaries only; no desktop config writes
GitHub installer (server profile)	curl -fsSL https://agentralabs.tech/install/memory/server | bash	Installs binaries only; server-safe behavior
crates.io paired crates (official)	cargo install agentic-memory-cli agentic-memory-mcp	Installs amem and agentic-memory-mcp
PyPI (SDK + installer)	pip install agentic-brain / pip install amem-installer	Python SDK and auto-connector tools
npm (wasm)	npm install @agenticamem/memory	WASM-based memory SDK for Node.js and browser

Server auth and artifact sync

For cloud/server runtime:

export AGENTIC_TOKEN="$(openssl rand -hex 32)"

All MCP clients must send Authorization: Bearer <same-token>. If .amem/.acb/.avis files are on another machine, sync them to the server first.

Goal	Command
Just give me memory	Run the one-liner above
Python developer	pip install agentic-brain
Rust developer	cargo install agentic-memory-cli agentic-memory-mcp
Connect all AI tools	pip install amem-installer && amem-install install --auto

Python SDK (requires amem Rust binary -- see INSTALL.md):

pip install agentic-brain
pip install agentic-brain[anthropic]   # Claude
pip install agentic-brain[openai]      # GPT
pip install agentic-brain[ollama]      # Local models
pip install agentic-brain[all]         # Everything

Rust CLI + MCP:

cargo install agentic-memory-cli       # CLI (amem)
cargo install agentic-memory-mcp       # MCP server

Rust library:

cargo add agentic-memory

Deployment Model

• Standalone by default: AgenticMemory is independently installable and operable. Integration with AgenticVision or AgenticCodebase is optional, never required.
• Autonomic operations by default: runtime maintenance uses safe profile-based defaults with backup, sleep-cycle upkeep, migration safeguards, and health-ledger snapshots.

Area	Default behavior	Controls
Autonomic profile	Local-first conservative posture	`AMEM_AUTONOMIC_PROFILE=desktop
Sleep-cycle maintenance	Decay refresh, tier balancing, completed-session auto-archive	AMEM_SLEEP_CYCLE_SECS, AMEM_SLEEP_IDLE_SECS
Backup + retention	Rolling backups with bounded retention	AMEM_AUTO_BACKUP_SECS, AMEM_AUTO_BACKUP_RETENTION, AMEM_AUTO_BACKUP_DIR
Storage migration	Policy-gated with checkpointed auto-safe path	`AMEM_STORAGE_MIGRATION_POLICY=auto-safe
Storage budget policy	20-year projection + auto-rollup when budget pressure appears	`AMEM_STORAGE_BUDGET_MODE=auto-rollup
Prompt + feedback auto-capture	Captures MCP prompt/tool context into .amem with privacy controls	`AMEM_AUTO_CAPTURE_MODE=safe
Maintenance throttling	SLA-aware under sustained mutation load	AMEM_SLA_MAX_MUTATIONS_PER_MIN
Health ledger	Periodic operational snapshots (default: ~/.agentra/health-ledger)	AMEM_HEALTH_LEDGER_DIR, AGENTRA_HEALTH_LEDGER_DIR, AMEM_HEALTH_LEDGER_EMIT_SECS

---

MCP Server

Any MCP-compatible client gets instant access to persistent graph memory. The agentic-memory-mcp crate exposes the full AgenticMemory engine over the Model Context Protocol (JSON-RPC 2.0 over stdio).

cargo install agentic-memory-mcp

Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agentic-memory": {
      "command": "agentic-memory-mcp",
      "args": ["serve"]
    }
  }
}

Zero-config: defaults to ~/.brain.amem. Override with "args": ["--memory", "/path/to/brain.amem", "serve"].

Memory modes — control how aggressively Claude saves:

Mode	Behavior	Config
smart (default)	Auto-saves facts, decisions, preferences	["serve"]
minimal	Only saves when you say "remember"	["serve", "--mode", "minimal"]
full	Saves everything, creates session summaries	["serve", "--mode", "full"]

Configure VS Code / Cursor

Add to .vscode/settings.json:

{
  "mcp.servers": {
    "agentic-memory": {
      "command": "agentic-memory-mcp",
      "args": ["serve"]
    }
  }
}