agent-memory 教程：给 AI Agent 装上跨会话的长期记忆

📌 项目地址：github.com/tigerless-labs/agent-memory | 星数：1,320+ | 协议：MIT | 语言：Python 3.12+ | 支持：Claude Code · Codex CLI · 任意可执行shell命令的Agent · MCP

📋 项目简介

Agent 关掉会话就忘掉一切——这是所有编码 Agent 的通病。你在 Claude Code 里教它的项目约定，换到 Codex 里全归零；上周让它记住的架构决策，这周它重新问你。agent-memory（tigerless-labs，2026 年 9 月开源，两周 1,300+ 星）给出的答案是把它当运行时问题而不是提示词问题来解决：Markdown 文件是唯一事实源，SQLite 索引只是随时可删的缓存，Claude Code、Codex CLI 和任何能跑 shell 命令的 Agent 共享同一个记忆库，全程零 API key。同赛道产品化的记忆系统可对比Claude-Mem深度评测；想给 Agent 配一整套云端运行环境的见AgentVerse-OS个人云OS教程。

🏗️ 两条路线合一：检索引擎 + 文件系统

README 对行业的判断很精辟：Agent 记忆长出了两条路线——一条造检索引擎（embedding、知识图谱、排序管线），找得准但给 Agent 的是无法检查的黑盒块；另一条直接给 Agent 文件系统（Markdown 可以 ls 和 grep），可读可迁移但不排序，目录一大就崩。agent-memory 是两者合一：检索引擎索引的是一个 Agent 也能直接读的文件系统。关系以链接形式存在记忆文件内部，本地索引负责排序，每个命中都解析为磁盘上完整的 Markdown 文件——召回既有图谱和向量搜索的精度，又保留 Agent 可直接遍历的普通目录，而且读路径上没有任何模型调用或网络请求。

🔍 按路径召回，按层级阅读

最大胆的设计：召回不往上下文里塞文本。它返回一个 L0 列表——每项一行摘要、文件路径、锚点、分数——Agent 再按需打开：

mem recall "why files instead of a database"   # L0 列表，默认 8 条
mem read <name> --level outline               # 只要标题；或摘要级/全文级
mem context "why files instead of a database"  # 召回+阅读一次搞定

mem setup --host claude-code                  # 或 --host codex
mem sleep --reason host                       # 睡眠整理
mem proposals                                 # 查看待决策提案
mem decide <id> --accept                      # 人工确认后才生效

这个设计直击 RAG 的痛点：把整段检索结果贴进上下文，既浪费 token 又稀释注意力；返回路径让 Agent 自己决定读多深——扫一眼标题就够的任务绝不读全文。想进一步压 Agent 的 token 消耗，可搭配SoL-Pi效率扩展教程（NVIDIA 出品）使用。

💤 睡眠时整理：会写梦境报告的 Manage 层

记忆不只是存，还有整理和遗忘。agent-memory 引入独立的睡眠时（sleep-time）Manage 层：mem sleep 触发整合，T0 级变更直接应用，T1 级只写入提案账本；mem proposals 列出等待决策的项，mem decide 人工确认。安全护栏是硬的：Manage 层不能在无人值守状态下删除任何东西，所有删除走提案确认；它借用你指定的宿主 CLI 做推理，每次整理写一份"梦境报告"。写入侧也不依赖 Agent"记得去记"——写在会话边界（SessionStart 注入、Stop/SessionEnd 蒸馏、PreCompact 驱散）自动触发。

🔌 接入方式

索引坏了不慌：rm -rf ~/agent-memory-store/.index && mem rebuild 一键重建——因为 Markdown 才是事实源。开发侧自带 pytest/ruff/mypy 全套检查。MIT 协议，适合直接进生产。