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

______________________________________________________________________

每个AI代理都有健忘症。

克劳德忘了你上次的谈话。GPT不知道你上周做了什么决定。你的副驾驶不记得三个月前的架构讨论了。 每个会话都从零开始。

目前的修复不起作用。矢量数据库失去了所有的结构——你得到的是“相似的文本”，永远不会 *“我为什么做出这个决定？”*Markdown文件速度较慢，并且在缩放时会中断。键值存储是扁平的——没有关系，没有推理链。提供程序内存锁定到一个供应商。

代理记忆 将代理的知识存储为单个二进制文件中的可导航图。不要“搜索你的旧对话”。你的经纪人有一个 大脑 --事实、决策、推理链、更正和技能——所有这些都是相互关联的，都可以在微秒内查询。

已解决的问题（请先阅读）

• 问题： 每次聊天都会重新开始，之前的决定也会消失。\

解决了的： 持久的 .amem 内存能够经受重启、模型切换和会话之间的长时间间隔。

• 问题： 向量搜索返回“相似文本”，但不是真正的推理轨迹。\

解决了的： 图遍历、因果路径和决策沿袭都是一级查询。

• 问题： 更正会掩盖真相，抹去历史。\

解决了的： 替代链通过可审计的变化历史来保存新旧信念。

• 问题： 内存质量会随着时间的推移而悄然下降。\

解决了的： 质量、漂移、间隙和修订工具使内存在运行时保持可靠。

• 问题： 长期记忆变得太重，无法随身携带。\

解决了的： 紧凑的单文件存储，具有实用的多年寿命和备份便携性。

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?

操作可靠性命令（CLI）：

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

六条线。十六种查询类型。一个文件包含所有内容。适用于Claude、GPT、Ollama或您接下来切换到的任何LLM。

______________________________________________________________________

V3：不朽建筑

v0.4.1中的新功能 --永不消逝的记忆。

V3添加了一个完整的仅追加、内容寻址的存储层，带有BLAKE3完整性链。你的代理的内存现在是加密防篡改的，多客户端的，设计寿命为20年。

核心能力

• 不朽日志 --仅使用BLAKE3完整性链进行存储。从不删除。从不修改。
• 五个指标 --时间、语义、因果、实体和程序。立即找到任何东西。
• 分层存储 --热->暖->冷->冷冻。20年内存，约500MB。
• 影子写手 --自动同步到Claude、Cursor、Windsurf和Cody。零配置。
• 智能检索 --多指标融合代币预算。完美的上下文组装。
• 崩溃恢复 --带CRC32校验和的WAL。什么都能活下来。
• MCP硬化 --内容长度框架限制为8 MiB，JSON-RPC 2.0验证，无无声回退。

多客户端支持

V3架构

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

五个指数

分层存储

Comparison with existing systems

______________________________________________________________________

为什么代理记忆

记忆是一个图形，而不是一个搜索索引。 当你想起 *为什么* 你做出了一个决定，你遍历了一个链：决定\ The five novel queries -- what makes them different

信念修正 --反事实传播。注入一个假设的事实，向前追踪每一个因果关系，报告哪些是无效的。只读——除非你这么说，否则一切都不会改变。只有通过键入因果边+置信度得分才有可能。

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(...), ...]

类比推理 --子图模式匹配。用相同的推理查找过去的情况 *结构* 即使域完全不同。单体到微服务的迁移与之前的Flask到FastAPI的迁移相匹配——形状相同，内容不同。

整合 --大脑维护。重复几乎相同的事实，发现不相关的矛盾，促进对事实的稳定推断。默认情况下为干运行。在任何突变之前自动备份。

漂移检测 --信念轨迹跟踪。显示关于主题的知识是如何逐会话发展的，计算稳定性得分，并确定活动修订的领域。

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

______________________________________________________________________

安装

一个衬垫 （桌面配置文件，向后兼容）：

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

下载预构建 agentic-memory-mcp 二进制到 ~/.local/bin/ 并将MCP服务器合并到您的Claude Desktop和Claude Code配置中。内存默认为 ~/.brain.amem。需要 curl 和 jq. 如果发布工件不可用，安装程序会自动回退到 cargo install --git 源代码安装。

环境概况 （每个环境一个命令）：

# 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

服务器身份验证和工件同步

对于云/服务器运行时：

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

所有MCP客户端必须发送 Authorization: Bearer . 如果 .amem/.acb/.avis 文件在另一台机器上，请先将它们同步到服务器。

Detailed install options

开发包 （要求 amem Rust二进制文件——请参见 安装.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库：

cargo add agentic-memory

部署模型

• 默认情况下为独立： AgentMemory可独立安装和操作。与AgentVision或AgentCodebase的集成是可选的，从来不是必需的。
• 默认情况下的自主操作： 运行时维护使用基于安全配置文件的默认值，包括备份、睡眠周期维护、迁移保护和健康分类账快照。

______________________________________________________________________

MCP服务器

任何兼容MCP的客户端都可以即时访问持久图形内存。 这 agentic-memory-mcp crate公开了整个AgentMemory引擎 模型上下文协议 （JSON-RPC 2.0通过标准输入）。

cargo install agentic-memory-mcp

配置Claude桌面

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

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

零配置：默认为 ~/.brain.amem.用覆盖 "args": ["--memory", "/path/to/brain.amem", "serve"].

内存模式 --控制克劳德的储蓄力度：

配置VS代码/光标

增添 .vscode/settings.json:

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

LLM能得到什么

一旦连接，LLM可以存储事实、遍历推理链、纠正信念、运行因果影响分析并保持会话连续性——所有这些都有相同的支持 .amem 二进制图。 完整的MCP文档->

______________________________________________________________________

快速入门

带内存的完整代理--5行

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

直接使用大脑——不需要LLM

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?

相同的大脑，不同的LLM

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

______________________________________________________________________

常见工作流

1. 调试决策 --当你需要了解代理人为什么做出选择时：

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

1. 验证信念货币 --在对存储的知识采取行动之前：

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

1. 审核内存运行状况 --定期维护以保持大脑的可靠性：

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

   amem quality my_agent.amem   # CLI equivalent

1. 跨会话连续性 --从过去的工作背景开始新的会议：

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

______________________________________________________________________

运作原理

Agent Memory将知识存储为 类型化认知事件图 以自定义二进制格式。节点代表认知事件（事实、决策、推理、纠正、技能、事件）。边编码因果关系、信念修正和时间排序。查询引擎支持图中的16种导航类型。

为了提高性能和安全性，核心运行时是用Rust编写的。所有州都住在一个便携式 .amem 二进制文件——没有外部数据库，没有托管向量服务。MCP服务器通过JSON-RPC stdio公开了完整的引擎。

______________________________________________________________________

详细的认知图：

节点 是认知事件——六种类型：

边缘 是关系——七种类型： caused_by . supports . contradicts . supersedes . related_to . part_of . temporal_next

查询 --涵盖检索、图算法和五种新型认知操作的十六种类型 不存在于任何其他系统中.

二进制 .amem 文件 使用固定大小的记录（O（1）访问）、LZ4压缩内容、内存映射I/O、内联特征向量和BM25倒排索引。没有解析开销。没有外部服务。即时访问。

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将BM25术语索引（标签0x05）和文档长度（标签0x06）添加到索引块，以及标头中的特征标志。完全向后兼容——v0.1读卡器跳过未知标签。v0.2读卡器通过自动慢路径回退（慢77倍，但正确）处理有或没有BM25索引的文件。

完整格式规范->

______________________________________________________________________

验证

这不是原型。它的测试超出了大多数生产系统的要求。

跨提供者测试证明：事实、决策、更正、技能和推理链在Claude、GPT-4o和Ollama之间完美地传递（包括小到1B参数的模型）。跨版本测试证明：v0.1文件在v0.2中加载，v0.2文件在v0.1中加载（未知索引被优雅地跳过）。

三篇研究论文：

• 论文一：AgentMemory格式+v0.1（7页，7图，6表）
• 论文二：查询扩展——9种新的查询类型（10页，9幅图，6个表，真实的Criterion数据）
• 论文三：MCP服务器——通过模型上下文协议实现通用LLM访问

______________________________________________________________________

存储库结构

这是一个Cargo工作区monorepo，包含核心库、MCP服务器和集成桥测试。

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

运行测试

# 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服务器快速启动

cargo install agentic-memory-mcp

配置Claude桌面(~/Library/Application Support/Claude/claude_desktop_config.json):

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

______________________________________________________________________

路线图：下一个--远程服务器支持

下一个版本计划为远程部署添加HTTP/SSE传输。跟踪进度 #1.

计划的CLI形状（当前版本中不可用）：

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

______________________________________________________________________

.amem文件

你经纪人的记忆。一个文件。永远属于你。

| | | |-|-| |大小|~1-2GB，20年后使用| |格式|二进制图形，可移植| |适用于|克劳德、GPT、Llama、任何型号|

两个目的：

1. 保留：20年的对话、决策、偏好
2. 富集：加载到任何模型中——突然间它就知道你了

模型是商品。你的namem就是价值。

v0.3：接地和工作区

接地：没有记忆证据，代理人不能声称“你说了X”。

工作区：同时跨多个.amem文件进行查询。

______________________________________________________________________

从V2迁移

V3完全向后兼容。你的V2 .amem 文件继续工作。

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

# No migration command needed -- it just works

______________________________________________________________________

哲学

“硬盘在写入时并不决定什么是重要的。它存储所有内容，并允许您稍后查询。内存也应该这样做。”

AgentMemory V3基于三个原则构建：

1. 捕捉一切 --写入时不要过滤。每一个象征都很重要。
2. 指数智能 --针对任何查询模式的五个专门索引。
3. 零摩擦 --一个安装命令。永远工作。没有配置。

结果：AI代理永远不会忘记，永远不会失去上下文，并且可以从任何会话中回忆起任何时刻。

______________________________________________________________________

项目统计

______________________________________________________________________

贡献

看 贡献.md.最快的帮助方式：

1. 试试看 和 文件问题
2. 添加LLM提供程序 --为新后端编写集成
3. 写一个例子 --展示一个真实的用例
4. 改进文档 --每一个澄清都有助于某人

______________________________________________________________________

隐私与安全

• 所有数据都保留在本地 .amem 默认情况下，没有遥测，没有云同步。
• AMEM_AUTO_CAPTURE_REDACT=true 在存储之前从提示和工具上下文中删除PII。
• AMEM_AUTO_CAPTURE_MODE 控制捕获的内容： safe （默认）， full，或 off.
• 存储预算政策通过20年预测和自动汇总来防止无限增长。
• 服务器模式要求显式 AGENTIC_TOKEN 承载身份验证的环境变量。

______________________________________________________________________

Built by Agentra Labs