Quickstart · Why · Benchmarks · Query Engine · Install · API · Paper

---

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.

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?

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

---

---

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.

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	<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. Validated across providers with 21 cross-provider 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?"

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

Python (recommended):

pip install agentic-brain

Note: The Python SDK requires the amem Rust binary. Install it via cargo install agentic-memory below, or see INSTALL.md for alternatives.

With LLM providers:

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 (required for Python SDK):

cargo install agentic-memory

One-command auto-install (connects all AI tools on your machine):

pip install amem-installer
amem-install install --auto

Detects Claude Code, Cursor, Windsurf, Continue, Ollama -- configures them all to share one brain. Details ->

---

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

---

How It Works

AgenticMemory stores knowledge as a typed cognitive event graph in a custom binary format.

Nodes are cognitive events -- six types:

Type	What	Example
Fact	Something learned	"User is a senior Rust developer"
Decision	Choice + reasoning	"Chose PostgreSQL -- team has 5 years experience"
Inference	Synthesized knowledge	"User is likely a systems architect"
Correction	Updated information	"User now works at DataFlow (was TechCorp)"
Skill	Learned preference	"Use analogies when explaining concurrency"
Episode	Session summary	"Discussed migration strategy, chose blue-green"

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.

File format details

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

v0.2 adds BM25 term index (tag 0x05) and document lengths (tag 0x06) to the index block, plus feature flags in the header. Fully backward compatible -- v0.1 readers skip unknown tags. v0.2 readers handle files with or without BM25 indexes via automatic slow-path fallback (77x slower but correct).

Full format specification ->

---

Validation

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

Suite	Tests
Rust core engine	179	13 criterion benchmarks
Python SDK	104	8 test modules, query expansion coverage
Terminal agent	97	6 validation protocols
Cross-provider	21	Claude <-> GPT <-> Ollama
Auto-installer	39	Sandboxed config tests
Total	440	All passing

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

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

---

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

---

_{Built by Agentic Revolution -- The agent infrastructure company.}