Engram 实战：用离线 MCP 记忆服务为 AI 编码工具赋予跨会话记忆

痛点

你在 Claude Code 里告诉 AI 某个 React 组件有一个隐藏的依赖 Bug，它记住了、修好了。然后你关掉会话，开始新任务。在新会话里，它又踩进同一个坑。

这不是 AI 变笨了——是因为 AI 编码工具的会话记忆是瞬时的。每次新会话，Agent 对你的项目、你的偏好、你踩过的坑一无所知。过去几百个会话中积累的知识，全部散落在终端历史里。

已有的解决方案要么太重（需要部署向量数据库），要么绑定特定工具（只支持某个 IDE）。你需要的是一个本地优先、一行命令安装、支持所有主流 AI 编码工具的轻量级知识持久化方案。

Engram 正是为此而生。

Engram 是什么

Engram 是一个本地优先的个人知识库系统，专为 AI 编码工具设计。它通过 MCP 协议原生集成 Claude Code、Cursor、Antigravity CLI 和 Windsurf，让 Agent 在会话之间共享记忆——不需要云服务、不需要 API Key、数据不离开你的电脑。

核心特性：

与同类工具（如 MetaBrain 的文档级路径存储、Cortex 的四层认知架构）相比，Engram 的定位是极简——你不需要理解记忆层级、不需要配置复杂的同步策略，装上就能用。

安装

git clone https://github.com/dgr8akki/engram
cd engram
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
./engram init
./engram install

engram install 一步完成三件事：注册 MCP 服务器、安装 Agent Skill（告诉 LLM 如何使用 Engram）、安装会话生命周期钩子。然后重启 IDE，Engram 即激活。

如果遇到 sqlite-vec 编译失败，通常是 pyenv 环境下缺少系统库导致的。推荐用 Homebrew Python 替代：

brew install python
/opt/homebrew/bin/python3 -m venv venv

CLI 快速上手

安装完成后，Engram 提供了一组直观的 CLI 命令：

./engram add "GraphQL subscriptions leak memory if you forget to unsubscribe"

./engram add "Prefer useReducer over useState for complex form state" --tags react,patterns

./engram search "memory leak javascript"

./engram list --limit 20

./engram delete 42

./engram stats

./engram search 的语义搜索是关键卖点——你不需要记得当时的精确关键词，只要描述「意思」，Engram 会通过 sentence-transformers 或 Ollama 嵌入模型找到最相关的内容。

会话记忆钩子：真正的自动化

Engram 最实用的功能是会话生命周期钩子。安装后，它会自动在每次 AI 编码会话的边界执行记忆读写：

这意味着——下次打开 Claude Code 开始新任务时，Agent 已经知道你上周发现的那个 GraphQL 内存泄漏问题，不需要你重新描述一遍。

多工具配置

Engram 对主流 AI 编码工具的支持覆盖很全面。engram install 会自动检测并配置以下工具：

如果你同时在 Claude Code 写代码、在 Cursor 做调试、在 Windsurf 做审查，Engram 的统一记忆层确保三个工具看到的是同一份知识库。

HTTP REST API：备选接入方案

对于不支持 MCP 的工具（比如自定义脚本或老旧的 CI 工作流），Engram 还可以启动为一个 HTTP 服务：

./engram serve                   # 监听 http://127.0.0.1:7823
./engram autostart install       # macOS 登录时自动启动

提供的 API 端点：

这样即使你的 Agent 框架只支持 HTTP 调用，也能接入 Engram 的记忆层。

配置与调优

Engram 的配置文件 config.yaml 提供了灵活的自定义选项：

embeddings:
  backend: "sentence-transformers"   # 或 "ollama"
  model: "all-MiniLM-L6-v2"
  dimensions: 384
  device: "cpu"                      # 有 GPU 可改为 "cuda"

  # Ollama 后端配置
  ollama_url: "http://localhost:11434"
  ollama_model: "nomic-embed-text"
  ollama_dimensions: 768

search:
  default_limit: 10
  similarity_threshold: 0.3

默认使用 sentence-transformers/all-MiniLM-L6-v2 进行离线嵌入，384 维向量，CPU 推理。如果本地已运行 Ollama，切换为 nomic-embed-text 可获得更好的嵌入质量（768 维）而无需额外下载模型。

搜索结果通过 similarity_threshold 阈值控制——值越低返回越多结果。如果搜索返回空，可以尝试降低阈值：

./engram search "query" --threshold 0.1

对比：Engram vs MetaBrain vs Cortex

同类工具中，Engram 的定位是「最简方案」。如果你不需要复杂的认知架构或加密同步，只是想让 Agent 记住东西，Engram 是最快上手的：

总结

Engram 解决的是一个简单但普遍的问题：AI 编码工具的跨会话记忆碎片化。它的定位不是替代笔记软件或知识库，而是为 Agent 提供一个统一的、可搜索的本地记忆接口——装上就能用，不需要学习复杂的架构概念。

如果你已经开始依赖 AI 编码工具写代码，并且发现每次新会话 Agent 都”失忆”，Engram 值得一试。在对话中直接说一句 remember: 就能让 Agent 保存笔记，比手动管理文件效率高得多。