Engram - 让 AI 编码助手拥有持久记忆

notes › tutorial
, , ,

engram /ˈen.ɡræm/ — 神经科学: 大脑中记忆的物理痕迹。

你的 AI 编码助手在会话结束后会忘记一切。Engram 给了它一个”大脑”。

为什么需要 AI Agent 记忆系统？

如果你经常使用 Claude Code、OpenCode、Cursor 等 AI 编码助手，你一定遇到过这个问题：

  • 每次新会话，AI 都要从零开始了解项目
  • 上次修复的 bug、做的架构决策，AI 完全不记得
  • 重复解释相同的代码上下文，浪费时间和 token

Engram 解决了这个问题 —— 它让 AI 助手能够跨会话保存和检索记忆。

Engram 是什么？

Engram 是一个 Agent 无关 的持久化记忆系统：

  • 📦 单一二进制文件 - 无需 Node.js、Python、Docker
  • 🔍 SQLite + FTS5 - 本地存储，全文搜索
  • 🔌 MCP 协议 - 兼容所有支持 MCP 的 AI 助手
  • 🖥️ 多种接口 - CLI、HTTP API、MCP Server、TUI
1
2
3
4
5
Agent (Claude Code / OpenCode / Gemini CLI / Codex / VS Code / Cursor ...)
    ↓ MCP stdio
Engram (单一 Go 二进制文件)
    ↓
SQLite + FTS5 (~/.engram/engram.db)

核心特性

1. Agent 无关设计

支持所有 MCP 兼容的 AI 助手：

Agent 一键安装命令
Claude Code claude plugin install engram
OpenCode engram setup opencode
Gemini CLI engram setup gemini-cli
Codex engram setup codex
VS Code code --add-mcp '{"name":"engram","command":"engram","args":["mcp"]}'
Cursor / Windsurf 手动 JSON 配置

2. 结构化记忆保存

不是无脑记录所有工具调用，而是让 AI 主动保存有价值的记忆：

1
2
3
4
1. AI 完成重要工作（bugfix、架构决策等）
2. AI 调用 mem_save → title, type, What/Why/Where/Learned
3. Engram 持久化到 SQLite，FTS5 索引
4. 下次会话：AI 搜索记忆，获取相关上下文

3. 渐进式信息检索

Token 高效的记忆检索 —— 不要一股脑全倒出来，按需深入：

1
2
3
1. mem_search "auth middleware"     → 紧凑结果 + ID（~100 tokens）
2. mem_timeline observation_id=42  → 该会话前后的时间线
3. mem_get_observation id=42       → 完整未截断内容

4. Git 同步

跨机器同步记忆，使用压缩块 —— 无合并冲突，无巨大文件：

1
2
3
engram sync                    # 导出新记忆为压缩块
git add .engram/ && git commit -m "sync engram memories"
engram sync --import           # 在另一台机器导入

安装

macOS / Linux (Homebrew)

1
brew install gentleman-programming/tap/engram

Windows

从 Releases 下载 engram-windows-amd64.exe

从源码安装

1
2
3
git clone https://github.com/Gentleman-Programming/engram
cd engram
go build -o engram ./cmd/engram

MCP 工具一览

工具 用途
mem_save 保存结构化观察（决策、bugfix、模式等）
mem_update 按 ID 更新现有观察
mem_delete 删除观察（默认软删除，可选硬删除）
mem_suggest_topic_key 为演化主题建议稳定的 topic_key
mem_search 全文搜索所有记忆
mem_session_summary 保存会话结束摘要
mem_context 获取之前会话的最近上下文
mem_timeline 特定观察周围的 chronological 上下文
mem_get_observation 按 ID 获取完整内容
mem_save_prompt 保存用户提示
mem_stats 记忆系统统计
mem_session_start 注册会话开始
mem_session_end 标记会话完成

会话生命周期

1
2
3
4
5
会话开始 → AI 工作 → AI 主动保存记忆
                        ↓
会话结束 → AI 写入会话摘要（Goal/Discoveries/Accomplished/Files）
                        ↓
下次会话开始 → 之前的会话上下文自动注入

记忆保存最佳实践

何时保存

AI 应该在以下情况主动调用 mem_save：

  • ✅ Bug 修复完成 - 记录问题根因和解决方案
  • ✅ 架构决策 - 记录设计权衡和选择原因
  • ✅ 发现非显而易见的问题 - 记录坑点和边界情况
  • ✅ 配置变更 - 记录环境设置
  • ✅ 建立模式/约定 - 记录命名、结构、惯例

记忆格式

使用结构化格式确保记忆高质量：

1
2
3
4
**What**: [做了什么，一句话]
**Why**: [原因，用户请求或问题驱动]
**Where**: [影响的文件/路径]
**Learned**: [学到的坑点、边界情况（如有）]

示例：

1
2
3
4
5
6
7
title: "Fixed N+1 query in UserList"
type: bugfix
content:
  **What**: Wrapped getUserIds() in batch query instead of per-user DB call
  **Why**: Page load was 15s for 100 users due to N+1 queries
  **Where**: src/services/UserList.ts — fetchUserDetails()
  **Learned**: Always check for loops containing async DB calls

终端 UI

1
engram tui

启动交互式终端界面：

  • 导航: j/k vim 键，Enter 深入，/ 搜索，Esc 返回
  • 主题: Catppuccin Mocha
  • 功能: 浏览记忆、搜索、时间线视图

CLI 参考

命令 描述
engram setup [agent] 安装 Agent 集成
engram serve [port] 启动 HTTP API（默认 7437）
engram mcp 启动 MCP server（stdio）
engram tui 启动终端 UI
engram search <query> 搜索记忆
engram save <title> <msg> 保存记忆
engram timeline <obs_id> 时间线上下文
engram context [project] 最近会话上下文
engram stats 记忆统计
engram export [file] 导出为 JSON
engram import <file> 从 JSON 导入
engram sync Git 同步导出
engram version 显示版本

与其他方案对比

特性 Engram claude-mem
Agent 支持 所有 MCP 兼容 Agent 仅 Claude Code
依赖 零依赖（单一二进制） Node.js
存储 SQLite + FTS5 JSON 文件
搜索 全文搜索 关键词匹配
同步 Git 压缩块 手动复制
UI 内置 TUI 无

总结

Engram 解决了 AI 编码助手的”失忆”问题：

  1. 持久化 - 会话结束，记忆不丢失
  2. 可检索 - FTS5 全文搜索，快速找到相关记忆
  3. 跨 Agent - 一套记忆，多种 AI 助手共享
  4. 零依赖 - 单一二进制文件，安装即用
  5. 可控 - AI 主动保存，不是无脑记录

如果你经常使用 AI 编码助手，Engram 绝对值得尝试。

📌 项目地址: https://github.com/Gentleman-Programming/engram