Agentic Memory

[](https://opencrater.to)

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

| 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 |

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 Comparison with existing systems

| | 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 | **

---

Why AgenticMemory

Memory is a graph, not a search index. When you remember why you made a decision, you traverse a chain: decision

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?" |

The five novel queries -- what makes them different

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 . 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 |

Detailed install options

Python SDK (requires amem Rust binary -- see [INSTALL.md](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|cloud|aggressive | | 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,

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: agentralabs
• Source: agentralabs/agentic-memory
• License: MIT
• Homepage: https://crates.io/crates/agentic-memory

Install and usage instructions live in the source repository linked above.