agentic-memory

Immortal cognitive memory for AI agents.

Every letter captured. Every context preserved. Nothing lost. Ever.

V3 Architecture · Quickstart · Problems Solved · How It Works · Why · MCP Tools · Benchmarks · Query Engine · Install · API · Papers

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

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

Tiered Storage

V3 MCP Tools

AgenticMemory V3 exposes 13 MCP tools for AI agents:

Capture Tools

Retrieval Tools

Search Tools

Stats Tools

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:

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.

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.

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

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

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

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.

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

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

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.

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:

Configure VS Code / Cursor

Add to .vscode/settings.json:

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

What the LLM gets

Once connected, the LLM can store facts, traverse reasoning chains, correct beliefs, run causal impact analysis, and maintain session continuity -- all backed by the same .amem binary graph. Full MCP docs ->

Quickstart

Full agent with memory -- 5 lines

from agentic_memory import Brain, MemoryAgent
from agentic_memory.integrations import AnthropicProvider

brain = Brain("my_agent.amem")
agent = MemoryAgent(brain=brain, provider=AnthropicProvider(), verbose=True)

# Session 1
agent.chat("My name is Marcus. I'm building a Rust compiler.", session=1)

# Session 2 -- the agent remembers
response = agent.chat("What am I working on?", session=2)
# -> "You're building a Rust compiler, Marcus."

Use the brain directly -- no LLM needed

from agentic_memory import Brain

brain = Brain("my_agent.amem")

# Build knowledge
fact = brain.add_fact("User lives in Toronto", session=1, confidence=0.95)
dec = brain.add_decision("Chose PostgreSQL -- team knows it well", session=2)
brain.link(dec, fact, "caused_by")

# Correct without erasing
brain.add_correction("User moved to Vancouver", session=5, supersedes=fact)

# Navigate
brain.traverse(dec, edges=["caused_by"])     # Why this decision?
brain.resolve(fact)                          # -> "User moved to Vancouver"
brain.impact(fact)                           # What depends on this?

# Search (v0.2)
brain.search("PostgreSQL")                   # Hybrid BM25 + vector
brain.search_text("Vancouver")              # Exact term match (1.58 ms @ 100K)

# Reason about your own reasoning (v0.2)
brain.revise("Team switched to MySQL")       # What breaks?
brain.gaps()                                 # Where am I guessing?
brain.centrality()                           # What are my core beliefs?
brain.drift("database choice")              # How has this evolved?
brain.analogy(node_id=42)                   # Similar past patterns
brain.consolidate(dry_run=True)             # Dedup, find contradictions
brain.shortest_path(src=42, dst=99)         # How are these connected?

Same brain, different LLMs

from agentic_memory import Brain, MemoryAgent
from agentic_memory.integrations import AnthropicProvider, OpenAIProvider

brain = Brain("shared_brain.amem")

# Monday: Claude learns
MemoryAgent(brain, AnthropicProvider()).chat(
    "I decided to use Kubernetes for deployment", session=10
)

# Tuesday: GPT remembers everything Claude learned
response = MemoryAgent(brain, OpenAIProvider()).chat(
    "What's our deployment strategy?", session=11
)
# -> "You decided to use Kubernetes for deployment."

Common Workflows

1. Debug a decision -- When you need to understand why an agent made a choice:

   brain.traverse(decision_id, edges=["caused_by"])   # Walk the reasoning chain
   brain.impact(decision_id)                           # See downstream effects
   

2. Verify belief currency -- Before acting on stored knowledge:

   current = brain.resolve(old_fact_id)   # Follow supersedes chains to the latest version
   

3. Audit memory health -- Periodic maintenance to keep your brain reliable:

   report = brain.gaps()       # Find low-confidence nodes, stale evidence, unsupported decisions
   # report.health_score -> 0.73
   

   amem quality my_agent.amem   # CLI equivalent
   

4. Cross-session continuity -- Starting a new session with context from past work:

   results = brain.search("current task description")   # Hybrid BM25 + vector retrieves relevant past experience
   

How It Works

AgenticMemory stores knowledge as a typed cognitive event graph in a custom binary format. Nodes represent cognitive events (facts, decisions, inferences, corrections, skills, episodes). Edges encode causal relationships, belief revision, and temporal ordering. The query engine supports 16 navigation types across the graph.

The core runtime is written in Rust for performance and safety. All state lives in a portable .amem binary file -- no external databases, no managed vector services. The MCP server exposes the full engine over JSON-RPC stdio.

The cognitive graph in detail:

Nodes are cognitive events -- six types:

Edges are relationships -- seven types: caused_by . supports . contradicts . supersedes . related_to . part_of . temporal_next

Queries -- sixteen types spanning retrieval, graph algorithms, and five novel cognitive operations that don't exist in any other system.

The binary .amem file uses fixed-size records (O(1) access), LZ4-compressed content, memory-mapped I/O, inline feature vectors, and a BM25 inverted index. No parsing overhead. No external services. Instant access.

+-------------------------------------+
|  HEADER           64 bytes          |  Magic . version . dimension . counts . feature flags
+-------------------------------------+
|  NODE TABLE       fixed-size rows   |  type . session . confidence . timestamp . offset
+-------------------------------------+
|  EDGE TABLE       fixed-size rows   |  source . target . type . weight
+-------------------------------------+
|  CONTENT BLOCK    LZ4 compressed    |  UTF-8 text for each node
+-------------------------------------+
|  FEATURE VECTORS  128-dim f32       |  Embedding vectors for similarity
+-------------------------------------+
|  INDEXES                            |  type . session . temporal . cluster . BM25 term . doc lengths
+-------------------------------------+

Validation

This isn't a prototype. It's tested beyond what most production systems require.

Cross-provider tests prove: facts, decisions, corrections, skills, and reasoning chains transfer perfectly between Claude, GPT-4o, and Ollama (including models as small as 1B parameters). Cross-version tests prove: v0.1 files load in v0.2, v0.2 files load in v0.1 (unknown indexes gracefully skipped).

Three research papers:

• Paper I: AgenticMemory format + v0.1 (7 pages, 7 figures, 6 tables)
• Paper II: Query Expansion -- 9 new query types (10 pages, 9 figures, 6 tables, real Criterion data)
• Paper III: MCP Server -- universal LLM access via Model Context Protocol

Repository Structure

This is a Cargo workspace monorepo containing the core library, MCP server, and integration bridge tests.

agentic-memory/
├── Cargo.toml                    # Workspace root
├── crates/
│   ├── agentic-memory/           # Core library (crates.io: agentic-memory v0.3.2)
│   ├── agentic-memory-cli/       # CLI (crates.io: agentic-memory-cli v0.3.2)
│   ├── agentic-memory-mcp/       # MCP server (crates.io: agentic-memory-mcp v0.3.2)
│   └── agentic-memory-ffi/       # FFI bindings (crates.io: agentic-memory-ffi v0.3.2)
├── tests/bridge/                 # Integration tests (core ↔ MCP)
├── python/                       # Python SDK (PyPI: agentic-brain)
├── agent/                        # Terminal test agent
├── installer/                    # Auto-installer (PyPI: amem-installer)
├── examples/                     # Python + Rust usage examples
├── paper/                        # Research papers (I, II, III)
└── docs/                         # Quickstart, API ref, concepts, benchmarks

Running Tests

# All workspace tests (unit + integration + bridge)
cargo test --workspace

# Bridge integration tests only
cargo test -p agentic-memory-bridge-tests

# Stress tests
cargo test -p agentic-memory-bridge-tests --test bridge_stress

MCP Server Quick Start

cargo install agentic-memory-mcp

Configure Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Roadmap: Next — Remote Server Support

The next release is planned to add HTTP/SSE transport for remote deployments. Track progress in #1.

Planned CLI shape (not available in current release):

agentic-memory-mcp serve-http --memory /data/brain.amem --port 8080 --token "<token>"
agentic-memory-mcp serve-http --multi-tenant --data-dir /data/users --port 8080 --token "<token>"

The .amem File

Your agent's memory. One file. Forever yours.

Two purposes:

1. Retention: 20 years of conversations, decisions, preferences
2. Enrichment: Load into ANY model — suddenly it knows you

The model is commodity. Your .amem is value.

v0.3: Grounding & Workspaces

Grounding: Agent cannot claim "you said X" without memory evidence.

Workspaces: Query across multiple .amem files simultaneously.

Migration from V2

V3 is fully backward compatible. Your V2 .amem files continue to work.

# V3 is enabled via feature flag in 0.4.0+
cargo build --features v3

# No migration command needed -- it just works

Philosophy

"A hard drive doesn't decide what's important at write time. It stores everything and lets you query later. Memory should do the same."

AgenticMemory V3 is built on three principles:

1. Capture everything -- Don't filter at write time. Every token matters.
2. Index smart -- Five specialized indexes for any query pattern.
3. Zero friction -- One install command. Works forever. No configuration.

The result: AI agents that never forget, never lose context, and can recall any moment from any session.

Project Stats

Contributing

See CONTRIBUTING.md. The fastest ways to help:

1. Try it and file issues
2. Add an LLM provider -- write an integration for a new backend
3. Write an example -- show a real use case
4. Improve docs -- every clarification helps someone

Privacy and Security

• All data stays local in .amem files -- no telemetry, no cloud sync by default.
• AMEM_AUTO_CAPTURE_REDACT=true strips PII from prompt and tool context before storage.
• AMEM_AUTO_CAPTURE_MODE controls what gets captured: safe (default), full, or off.
• Storage budget policy prevents unbounded growth with 20-year projection and auto-rollup.
• Server mode requires an explicit AGENTIC_TOKEN environment variable for bearer auth.

_{Built by Agentra Labs}