给AI编码Agent装上大脑：开源持久记忆系统Engram完全入门
给AI编码Agent装上大脑：开源持久记忆系统Engram完全入门
AI编码Agent每次会话结束就「失忆」？Engram 是一款开源的 AI Agent 持久记忆系统：一个 Go 编写的单二进制，内置 SQLite + FTS5 全文搜索，通过 MCP 协议接入 Claude Code、Codex、Cursor 等任意编码Agent，让决策、Bug 修复、架构约定跨会话永久留存，无需 Node.js、Python 或 Docker。
为什么AI编码Agent需要「持久记忆」？
如果你用过 AI 编码助手，一定遇到过这些场景：
- 上周刚让 Agent 修完的 N+1 查询问题，这周又让你重新排查一遍
- 项目里的命名约定、架构选型，换个会话就要从头解释
- 长对话被压缩（compaction）后，Agent 直接「断片」
Engram 的定位很清晰：给 Agent 装上一颗大脑。 它把「会话中产生的知识」沉淀成结构化的持久记忆：
| 特性 | 说明 |
|---|---|
| 🧠 持久存储 | 本地 SQLite 单文件（~/.engram/engram.db），零外部依赖 |
| 🔍 全文检索 | FTS5 索引，Agent 可按关键词找回历史知识 |
| 🔌 Agent 无关 | 通过 MCP 接入 Claude Code、OpenCode、Gemini CLI、Codex、VS Code Copilot、Cursor、Windsurf 等 |
| 🪶 轻量部署 | 单个 Go 二进制，纯 Go 实现的 SQLite，无 CGO |
| ☁️ 本地优先 | 本地库是权威数据源，Git 同步 / 云端复制均为可选项 |
💡 核心设计哲学：Engram 信任 Agent 自己判断什么值得记——它不是原始对话的流水账，而是精选过的「项目大脑」。
Engram 如何工作：Agent 主动存，本地永久留
整个记忆流程只有四步：
- Agent 完成一件有意义的事（修 Bug、架构决策、发现新规律）
- Agent 主动调用
mem_save工具，写入结构化摘要（What / Why / Where / Learned） - Engram 将其持久化到 SQLite，并自动建立 FTS5 全文索引
- 下次会话开始时，Agent 通过
mem_search/mem_context检索，自动恢复上下文
Agent 在完成关键工作后主动调用 mem_save——结构化、可检索、零噪音
为了节省 Token，Engram 采用三层渐进式检索：先用 mem_search 拿到精简结果（每条约 100 tokens）→ 需要上下文时用 mem_timeline 查看该记忆前后的会话脉络 → 最后用 mem_get_observation 读取完整内容。一次不倾倒全部记忆，而是按需深入。
快速上手：三条命令装好 Engram
1️⃣ 最快安装方法：一行命令安装
macOS / Linux（Homebrew）：
brew install gentleman-programming/tap/engram
源码构建（需要 Go 1.24+）：
git clone https://gitcode.com/gh_mirrors/engra/engram
cd engram
go install ./cmd/engram
其他平台：直接从官方 Releases 页面下载对应平台的预编译二进制（支持 macOS / Linux / Windows 的 x86_64 与 ARM64），解压后放入 PATH 即可。完整的安装方式与 Windows 配置路径见 docs/INSTALLATION.md。
2️⃣ 一条命令接入你的编码Agent
engram setup <agent> 会自动写好 MCP 集成配置和记忆协议，之后重启你的 Agent 即可：
| 你的Agent | 安装命令 |
|---|---|
| OpenCode | engram setup opencode |
| Codex | engram setup codex |
| Gemini CLI | engram setup gemini-cli |
| Cursor | engram setup cursor |
| VS Code (Copilot) | engram setup vscode-copilot |
| Windsurf / Kiro / Qwen / Kilo | engram setup windsurf 等 |
| Claude Code | 通过 Claude 插件市场安装 engram 插件 |
| 其他 MCP Agent | 直接配置 engram mcp（stdio 传输） |
各 Agent 的详细配置见 docs/AGENT-SETUP.md，Claude Code 插件脚本位于 plugin/claude-code/。
3️⃣ 心法：装好就忘掉它
官方 docs/intended-usage.md 里有一条黄金法则：
Engram 是基础设施。像一个好数据库——配置一次，然后忘记它的存在。 如果你工作的时候还在想 engram，说明哪里出了问题；它应该是无感知的。
日常使用：命令行、终端UI与记忆搜索
CLI 常用命令一览：
| 命令 | 用途 |
|---|---|
engram tui |
打开交互式终端 UI |
engram search <关键词> |
全文搜索记忆 |
engram save <标题> <内容> |
手动存一条记忆 |
engram context [项目] |
查看历史会话的近期上下文 |
engram stats |
记忆统计 |
engram doctor |
只读诊断：项目检测、存储健康 |
终端 UI（TUI）是浏览记忆的最佳入口。 运行 engram tui，主面板显示会话数、观察数、提示数与项目数：
近期观察列表按时间倒序展示所有记忆，一眼看到最近存了什么：
按 / 进入全文搜索，命中结果按类型（architecture、discovery 等）高亮显示：
按 Enter 深入查看单条记忆的完整内容与来源会话：
快捷键很简单：j/k 上下移动、Enter 进入详情、/ 搜索、c 复制内容、Esc 返回。主题采用 Catppuccin Mocha 配色。
跨会话记忆如何流转：会话摘要与主题记忆
Engram 的记忆生命周期设计让知识能「越用越新」：
🔁 会话交接：会话结束时，Agent 会写一份 mem_session_summary（目标、发现、已完成、下一步、相关文件）；下次会话自动注入上一段的上下文，对话被压缩后也能快速恢复。
🏷️ 主题记忆（topic_key）：对持续演进的知识点（如 architecture/auth-model），使用稳定的主题键后，mem_save 会变成「原地更新」而非新增——同一个决策始终是一条记忆，修订次数 +1，不会出现互相打架的多条重复条目。
🧹 记忆卫生：精确去重（窗口内相同内容只记一次）、软删除（默认保留可审计）、生命周期复审（mem_review 列出过期待审记忆）。
完整机制见 docs/ARCHITECTURE.md，核心存储实现在 internal/store/store.go。
本地优先，云端可选：记忆同步与团队共享
| 需求 | 方案 |
|---|---|
| 单机使用 | 默认即可，SQLite 文件就是全部 |
| 多机/团队共享（Git） | engram sync 导出压缩记忆块到 .engram/，随仓库分发 |
| 云端复制 + 浏览器看板 | engram cloud serve（可选 Engram Cloud） |
云端是可选的按项目订阅的复制层：本地 SQLite 始终是权威数据源，云端只负责复制与可视化（Postgres + HTMX 仪表盘）。团队使用约定见 docs/TEAM-USAGE.md，云端部署指南见 docs/engram-cloud/README.md，同步与自动同步逻辑位于 internal/cloud/。
关键文档与源码导读
| 资料 | 路径 |
|---|---|
| 完整技术参考（CLI / API / MCP 工具） | DOCS.md |
| 安装与平台支持 | docs/INSTALLATION.md |
| 架构与会话生命周期 | docs/ARCHITECTURE.md |
| 心智模型与代码地图 | docs/codebase/mental-model.md |
| MCP 记忆工具实现（23 个 mem_* 工具） | internal/mcp/mcp.go |
| HTTP API 服务（默认端口 7437） | internal/server/ |
| Bubbletea 终端 UI | internal/tui/ |
| 插件（OpenCode / Claude Code / Pi） | plugin/ |
总结：把「失忆」彻底交给基础设施
Engram 用最朴素的技术组合（Go 单二进制 + SQLite + FTS5）解决了一个高频痛点：AI 编码Agent跨会话记忆丢失。三条命令装好、一条命令接入 Agent，之后它在后台默默工作——Agent 该存时存、该查时查，而你的项目知识第一次真正「留了下来」。🧠