iai-memory：把每轮会话逐字存到本机，并按轮注入上下文的个人记忆引擎
仓库：CodeAbra/iai-personal-memory-engine
PyPI：iai-pme
English | 中文
iai-memory 是给 AI 编码工作流用的个人记忆引擎。它逐字保存每轮对话，并在每一轮把合适的历史上下文喂给 agent——事实变化时连同旧措辞一起保留。
PyPI 包 iai-pme，MIT 协议，Python 3.11 | 3.12，macOS | Linux 已支持，Windows beta，兼容 MCP。指标：Rescue@10 1.000，LongMemEval R@5 0.962，historical-verbatim 1.000，静态加密 AES-256-GCM。
它是什么
AI agent 在会话结束的瞬间就忘掉一切，iai-memory 在本机补上这一层。打开 hooks 后，它会逐字记录会话双方的内容，并在每条消息上把历史里相关的部分喂给 agent——不只是会话开始时注入一次。不需要维护记忆文件，也不需要说「记住这个」。
事实发生变化时，旧记录不会被覆盖。新版本被写入并链接回它所替代的内容，两边都能调出来。出现自相矛盾时，recall 会展示冲突，而不是悄悄把一个过期答案当作事实递出去。
它是围绕「你 + 一个 agent」设计的记忆，不是面向多租户应用的记忆 API，也不是某家数据库的封装。你说过的话只逐字存一次，永不重写。存储、检索、图、Dashboard，全部跑在本机。
记忆风格是按字面（literal）设计的：保留原始措辞而不是抹平成释义；保留精确线索；让稀有的事件保持稀有，而不是被平均掉。
快速开始
Claude Code
python3.12 -m pip install -U iai-pme
然后在 Claude Code 内执行：
/plugin marketplace add CodeAbra/iai-personal-memory-engine
/plugin install iai-memory@iai-pme
重启会话后验证：
iai --version
iai-mcp daemon status
iai-mcp doctor
Python 3.11 同样支持。
macOS / Linux：一体化源码安装
curl -fsSL https://raw.githubusercontent.com/CodeAbra/iai-personal-memory-engine/main/scripts/bootstrap.sh | bash
该脚本会构建 Rust 引擎和 TypeScript wrapper，安装后台服务与 hooks，注册 Claude Code，并跑一次健康检查。依赖 Git、Python 3.11/3.12、Node.js 18+ 和 Rust。想先看步骤、不改动环境：
curl -fsSL https://raw.githubusercontent.com/CodeAbra/iai-personal-memory-engine/main/scripts/bootstrap.sh | bash -s -- --dry-run
其他宿主
python3.12 -m pip install -U iai-pme
iai-mcp crypto init
iai-mcp daemon install
iai-mcp capture-hooks install --target codex
把 codex 换成 cursor、antigravity、hermes、openclaw 或 all 即可。MCP 工具可用于任何 MCP-over-stdio 客户端；自动采集和上下文注入依赖宿主本身暴露的 hooks。详见技术参考 docs/REFERENCE.md。
新建的 store 默认使用 native engine 格式；已有 store 在升级时保持原有格式。要把旧的 legacy SQLite store 迁到 native engine，运行 iai-mcp migrate-to-lilli——iai-mcp doctor 会打印确切命令，完整流程在技术参考里。
安装之后发生了什么
| 事件 | 动作 |
|---|---|
| Prompt | 新回合以文件 IO 追加进 session buffer；采集路径上不需要 embedding 或引擎 RPC |
| Session end | 剩余的 transcript 内容被滚动进入 ingestion；hook 失败不会阻塞宿主 |
| Session start | 一段有界的 memory prefix 作为宿主上下文暴露；store 为空或引擎不可用时输出为空 |
| Later turns | 受支持的宿主会收到一个小的 foresight 或 delta pack，带 age 和 revision 标记 |
| Idle time | 采集内容被 embedding、去重、加密、写入、聚类、consolidation、reinforce、decay |
后台进程在 CLI 里叫 daemon。它休眠或暂时不可用时，MCP wrapper 和 iai 仍可直接读取本地 store。
工作原理
记忆模型
| 层 | 内容 |
|---|---|
| Episodic | 带时间戳、写入一次（write-once）的发言片段 |
| Semantic | 在 idle consolidation 中从相关 episode 归纳出的摘要 |
| Procedural | 随时间学到的十个有界行为参数 |
不同的超维度表征让字面细节、语义结构和行为倾向不会塌缩到同一个向量面上。
本地、无 LLM 的 recall 路径同时使用语义相似度、图证据、recency、temporal validity 和词汇证据。memory_recall 返回 hits 和 anti_hits；memory_contradict 会关闭旧记录的 validity interval，创建新记录，并把两者链接起来。
空闲时，引擎对相关 episode 分组、归纳 semantic memory、强化有用的路径、衰减弱的未复核边。可选的 REM 步骤可能通过用户已有的 Claude 订阅调用 claude -p，上限为每日配额的 1%。不需要 Anthropic API key。
一方组件
| 组件 | 角色 |
|---|---|
| Hippo | 加密记录、向量索引和图，统一在一个本地 store |
| MOSAIC | Leiden 系社区检测，社区身份稳定 |
| Lilli HD | 超维度基底与结构性 recall |
| Native engine | Rust embedder 与图内核 |
Dashboard 与 CLI
iai brain
本地 dashboard 可以检索 store、浏览图的邻域与矛盾、pin 或 fade 记忆、ingest 文件、控制后台引擎，并根据你自己的 store 给出 token 用量估算。
iai recall · temporal-recall · search · ask · capture · teach · upload
iai watch · brain · status · last
iai upload 接受文档、Office 文件、电子书、源码、配置文件和目录。完整格式与行政命令见 docs/REFERENCE.md。
Benchmarks
所有 harness 都在 bench/ 里；方法与复现命令见 BENCHMARKS.md。
| Benchmark | 结果 |
|---|---|
| Rescue@10 after contradiction | 1.000 |
| Historical-verbatim hit@10 | 1.000 |
| LongMemEval-S R@5，产品 embedder | 0.962 |
| LongMemEval-S R@10，产品 embedder | 0.978 |
Historical-verbatim 检索的 flat-cosine baseline 约为 0.71。用匹配的 all-MiniLM-L6-v2 embedder 时，iai-memory 与 mempalace v3.3.6 的 R@5 都是 0.966，R@10 都是 0.978；此处不主张胜负。
在作者的 store 上，自动注入的 memory pack 平均约 350 tokens，而它所替代的 agent-search 往返约 2,850 tokens：在那一份实测负载上约省 88%。这不适用于显式 memory_recall，后者的默认响应预算是 1,500 tokens。
MCP 工具
memory_recall memory_temporal_recall
memory_recall_structural memory_search
memory_capture memory_contradict
memory_reinforce memory_consolidate
profile_get_set topology
schema_list events_query
episodes_recent curiosity_pending
十四个工具覆盖线索、时间、结构和词法 recall；capture 与修正；强化与 consolidation；行为 profile 控制；以及 store 内省。
兼容性
| 宿主 | Ambient 行为 |
|---|---|
| Claude Code | 会话开始 recall、逐轮更新、回合采集、会话采集 |
| Codex CLI | 通过 Codex hooks 的完整集成 |
| Cursor | 会话开始 recall 与采集；无逐轮文本注入 |
| Antigravity | 每次调用时 recall，无损 transcript 采集 |
| Hermes 0.5.0+ | 模型调用前 recall，并从其 message store 采集 |
| OpenClaw | 按请求使用 MCP 工具；无 ambient shell hooks |
| Gemini CLI 及其他 MCP 宿主 | 提供 MCP 工具；除上表所列外不附带宿主专属 hooks |
| Claude Desktop | 提供 MCP 工具；普通 Chat 不暴露 Claude Code 式的 ambient hooks |
隐私与限制
- 记录静态加密，AES-256-GCM。store 与密钥都在
~/.iai-mcp/下；备份时请一起备份。 - macOS 与 Linux 使用 Unix socket。Windows 使用临时 loopback 端口加每用户 token。
- 没有 iai-memory 账号、遥测管道、托管 dashboard，也没有跨机器同步。
- 可选的 iai-memory 网络活动只有 REM 的
claude -p步骤和每日一次 PyPI 版本检查。设置IAI_MCP_VERSION_CHECK=0可关闭版本检查。 - store 拒绝混用不兼容的 embedding 世代；更换 embedder 需要显式迁移。
- 大约前十个会话内 recall 通常一般；质量与延迟取决于语料规模、语言、embedder 和历史数据。
- 默认 store 以英语优先。非英语原始记录需要显式
raw:标签，并搭配多语言或自定义 embedder。 - Windows 支持为 beta。Ambient 行为随宿主 hook 支持程度而变化。
- 项目为个人维护，不提供企业级 SLA。
健康检查与更新：
iai-mcp doctor # 38 checks
iai-mcp daemon status
iai-mcp self-update
关于名字
IAI — Independent Autistic Intelligence，描述的是这套记忆设计。
- Independent： 引擎、store、embedding、dashboard 都在本地运行。
- Autistic： 字面保存、精确线索、持续聚焦，稀有事件以稀有的形式保留，而不是被平滑成一个典型摘要。这是对运行设计的描述，不是诊断，也不是随手打的比方。
- Intelligence： 取系统含义——一个观察、适应、自我重组并长期维持可行的过程。
「Personal memory engine」描述的是范围：一个人的记忆，在一台机器上，供他已经在用的助手使用。
文档
- docs/REFERENCE.md — 技术与运维参考
BENCHMARKS.md— 方法与复现命令docs/EMBEDDERS.md— provider、语言与迁移CHANGELOG.md— 发布历史
License
MIT。