关于 Engram
Engram 是本地运行的 AI 长期记忆 MCP 服务,面向开发者、研究者和笔记使用者保存并检索原始文字。它无需 LLM 或 API 密钥,支持语义、全文与时间线索检索,并保留记忆变更历史。
主要功能
- 01本地保存原始笔记与对话
- 02结合语义、全文和时间检索
- 03修正记忆并保留变更历史
- 04为 Claude Code 自动回忆与保存
- 05提供 31 个记忆管理工具
- 06可选启用秘密信息脱敏
适用场景
- 01跨会话查找项目决策及其原因
- 02搜索笔记、文档和代码资料
- 03为个人 Agent 提供本地记忆
- 04更新过时记录并追溯旧证据
MCP 相关
Engram 可连接支持 MCP 的应用,并提供 31 个用于回忆、搜索、保存和修正记忆的工具。也可通过本地 Web API 提供相同工具。
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
工具
本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。
详细介绍
Engram
聊天结束后,你的 AI 会忘记一切。Engram 能帮它记住。 免费、私密、运行在你自己的电脑上,并会逐字保留你写下的所有内容。
问题
周一,你花了一小时和 Claude 一起查明登录系统为何会泄漏内存,并决定更换库。到了周五,你打开一个新聊天,问道:“我们为什么又弃用 Passport 了?”
它完全不知道。对话已经消失,推理过程也不复存在。
你告诉 AI 的任何事情都会如此:你姐姐的生日、你已经修复的错误、某项设置如此配置的原因。每次新聊天都从零开始。
Engram 是一种能在聊天结束后留存的记忆。 它会保存你的笔记、文件和对话;之后你提出问题时,即使措辞完全不同,它也能找到相关内容。
看看它如何运作
先输入两条普通笔记:
notes/decisions.md We switched from Passport to Lucia on March 3 because
Passport sessions kept leaking memory under load.
notes/personal.md My sister Maya's birthday is June 14. She loves anything
with sunflowers.
engram mine notes --wing life
几天后,用你自己的话提问。这些问题与笔记中的句子毫无重合:
$ engram search "why did we change the auth library"
1 life/notes We switched from Passport to Lucia on March 3 because
Passport sessions kept leaking memory under load.
$ engram search "gift idea for Maya"
1 life/notes My sister Maya's birthday is June 14. She loves anything
with sunflowers.
将它接入 Claude 后,这一切都会自动完成:Claude 需要时会在 Engram 中查找信息,Engram 也会自动保存你的 Claude Code 会话。
两分钟上手
你需要 Python 3.9 或更新版本(推荐使用 3.11 到 3.14)。运行 python3 --version 检查。
1. 安装
pip install engram-chateau
PyPI 上的包名是
engram-chateau,但你输入的命令只有engram。(另一个无关的软件包已经占用了engram这个名称。)
2. 添加要记住的内容
engram mine ~/Documents/notes --wing notes # any folder of notes, docs or code
首次运行时会下载一个小型语言模型(约 80 MB),让 Engram 能理解含义。之后,所有功能都可以离线使用。
3. 向它提问
engram search "what did I decide about the database"
这样就可以体验了。
将它接入你的 AI 应用
Engram 适用于任何支持 MCP 的应用。MCP 是 AI 应用接入工具的标准方式。只需一条命令即可添加:
engram connect cursor # or: claude-desktop, windsurf, vscode, gemini, codex, zed, lm-studio
engram connect all # every supported app on this computer
engram connect # list them, with ✓ next to the ones you have
它会将 Engram 添加到该应用的设置中(保留其他所有内容,并创建 .bak 备份),并告诉你如何重启应用。你可以随时再次运行;第二次运行时不会做任何更改。
| 应用 | 写入的设置 |
|---|---|
| Claude Desktop | claude_desktop_config.json |
| Cursor | ~/.cursor/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| VS Code(Copilot Agent 模式) | 你的用户级 mcp.json |
| Gemini CLI | ~/.gemini/settings.json |
| Codex CLI | ~/.codex/config.toml |
| Zed、LM Studio | 打印可供粘贴的配置片段 |
之后,每个应用都会获得 31 个 engram_* 工具:回想、搜索、记住、纠正过时的记忆、将结论与其证据关联、解释记忆内容的由来、查看某个主题的历史、查看包含人物和事实的知识图谱等。连接时,Engram 还会告诉 AI 如何使用这些工具:回答依赖过往工作的内容前先检查记忆、保存决策,以及通过纠正而非反驳来处理问题。(应用会自行决定是否将这些指引传给模型;目前大多数应用都会。)你可以问:“记住,我们在这个仓库里使用制表符”、“关于身份验证,我们之前决定了什么?”,或 “我们改用 PostgreSQL 了,更新一下。”
Claude Code 的功能最丰富:无需你主动要求,它也能使用记忆。
engram connect claude-code # prints the one-line `claude mcp add` command
engram install-hooks --apply # then restart Claude Code
install-hooks 会向 ~/.claude/settings.json 添加三个 Claude Code hooks(保留现有设置,并创建备份):
- 自动召回。 每次你向 Claude 发送消息时,Engram 都会先搜索你的记忆。如果找到明显相关的内容,Claude 在回答前会收到一条简短提示,其中最多包含 3 条记忆:优先显示当前版本(并说明它们取代了什么以及原因),过时的记忆则会标注出来。你在一个全新的聊天中问 “我们为什么弃用了 Passport?”,Claude 就已经知道答案。如果没有相关内容,就不会添加任何内容;同一条记忆不会在一个会话中重复出现,预热后大约只需一秒(电脑启动后发送的第一条消息可能需要几秒钟,因为它需要加载)。
- 了解项目。 记忆按你正在处理的项目(git 仓库或文件夹名称)归档,召回时会优先显示该项目的记忆;只有在匹配度非常高时,其他项目的笔记才会出现。
- 自动保存。 Claude 编辑的每个文件都会保存。
- 压缩前保存。 Claude Code 压缩对话前,会先保存对话。
使用 engram recall "your message" 预览自动召回会提供给 Claude 的内容。运行 engram install-hooks(不带 --apply)可查看设置,而不应用设置;也可以添加 --no-recall 跳过自动召回。
其他 MCP 应用: 将其指向命令 engram-mcp(或 python -m engram.mcp_server)。Engram 也已列入官方 MCP 注册表,名称为 io.github.TushaeBXN/engram。
不支持 MCP 的应用(Open WebUI、n8n、自编脚本)可以通过一个小型本地 Web API 使用 Engram:
engram serve # http://127.0.0.1:7742, the same tools and rules as MCP
将应用指向 http://127.0.0.1:7742/openapi.json;其中描述了每个工具。也可以直接调用:
curl -s localhost:7742/v1/tools/engram_recall -H 'Content-Type: application/json' \
-d '{"message": "why did we drop Passport?"}'
记忆是私密的,因此默认采用严格设置。它仅监听 localhost,并会拒绝看起来来自网页或经过代理的请求。若要从另一台机器访问,请使用 engram serve --host 0.0.0.0:此时始终需要令牌(首次使用时创建于 ~/.engram/server/token,不会打印出来),并通过 Authorization: Bearer <token> 发送。即使在 localhost 上,engram serve --token 也要求提供令牌。它绝不会发送 CORS 标头,因此网页无法与之通信。
教任何编码 Agent 使用它。 skills/engram/SKILL.md 是现成的 Agent 技能:说明何时召回、保存和更正,以及如何解释结论。使用 npx skills add TushaeBXN/engram 安装(或复制该文件)。
更喜欢使用 uv、pipx 或引导式安装?
uv tool install engram-chateau # or: pipx install engram-chateau
engram init ~/myproject # guided setup: your AI's identity, a default wing, then saves the project
两种方式都会将 engram 和 engram-mcp 添加到 PATH,而不会修改系统 Python。
适用人群
🧑💻 使用 Claude Code 的开发者。 Engram 会在后台保存 Claude 操作过的文件及其背后的对话。几个月后,问一句 “重试次数上限为什么是 7?”,就能找回实际讨论内容,而不是得到猜测。
🤖 构建 AI 伴侣或 Agent 的人。 为你的机器人赋予专属记忆:它对你的了解、日记,以及关于人物和事实的知识图谱(“Kai 从 6 月起在 Orion 工作。”)。只需几行 Python,就能让这一切完全离线运行。Engram 最初正是为此而生:作为一款个人伴侣应用的记忆系统。
📚 作家、研究人员和笔记记录者。 将其指向笔记文件夹、Obsidian 库,或 Notion、Linear 导出的内容,就能按含义搜索其中所有内容:“我之前关于定价层级的那个想法”。
Engram 有何不同
- 🔒 它只属于你。 所有内容都保存在你电脑上的一个文件夹中(
~/.engram/)。无需账号、云服务或 API 密钥,也不会跟踪你。 - 📝 它会保留你的原话。 大多数 AI 记忆工具会让大模型把对话改写成简短的“事实”,再丢弃原文。Engram 会保存原始文本,并在需要时重新找到它。摘要不会遗漏任何内容。
- 🧠 它能理解你的意思。 当你询问“更换身份验证库”时,它能找到 “我们从 Passport 换成了 Lucia”。它也能匹配精确名称和数字(
INV-20931),还能理解时间:“两周前”“六月”“5 月 8 日”。 - 💸 它免费运行。 保存或搜索都不需要大模型,因此没有按消息计费,也不会受到速率限制。
- 🎯 它准确。 在两项标准的 AI 记忆测试中,它的表现超过了已发布的最佳免大模型结果(下方的数据)。
- 📖 你可以阅读全部代码。 大约 10,000 行纯 Python,采用 MIT 许可证。如果你想确切了解数据会如何处理,尽可查看。
- 🔄 它知道信息何时已过时。 决策变更时,新记忆会标记为替代旧记忆。搜索会优先给出当前答案,并在下方保留旧答案作为历史记录,注明变更时间和原因。
- 🔑 它可以帮你隐藏机密。 启用
redact_secrets后,API 密钥、令牌和密码会在写入磁盘前被清空。
工作原理
Engram 像整理一栋大房子那样整理记忆:每个人或项目对应一个 翼,每个主题对应一间 房间,每种记忆对应一条 走廊,里面则有存放原始文本的 抽屉。
Wing – a person or project ("myapp", "life")
└── Room – a topic ("auth-migration")
└── Hall – the kind of memory (facts, events, discoveries, preferences, advice)
└── Drawer – your original text, word for word
你无需管理这些内容;Engram 会在保存时自动整理。搜索时,它会综合权衡多种线索:
| 线索 | 作用 |
|---|---|
| 含义 | 查找含义相同但用词不同的文本 |
| 精确用词 | 全文索引可以捕捉到含义搜索会漏掉的名称、数字和生僻词 |
| 时间 | “我两周前买了什么?” 或 “六月发生了什么?” 会优先匹配对应时段的记忆 |
| 随口一提的内容 | 留意你随口提到的事情(“我最近睡得不好”),以便之后的问题能找到它们 |
| 近期程度 | 稍微偏向较新的记忆;固定的记忆永不过时 |
| 重排序器 (可选) | 由小型本地模型重新审阅排名前 20 的结果,并将最佳结果排在第一位 |
在会话开始时,Engram 还可以向 AI 提供一则简短的“唤醒”提示(说明它是谁及关键事实:先列固定的记忆,再列最新的记忆;默认约 120 个令牌),让它不至于从零开始。
信息变更时
三月时,你记录应用会将所有内容存储在 SQLite 中。到了四月,你将其迁移到 PostgreSQL。此时,大多数记忆工具会保留两条相互矛盾的记录,并返回与问题最匹配的一条。
在 Engram 中,你(或 Claude,或你的 Agent)只需记录一次变更:
engram correct file-05aa607a "We migrated the app from SQLite to PostgreSQL on April 9" --reason "SQLite locked under concurrent writes"
此后,搜索会优先显示当前答案,并将旧答案清楚标记后保留在下方:
$ engram search "which database does the app use"
1 c6e0b7b4 [current, replaces file-05aa607a] We migrated the app from SQLite to PostgreSQL on April 9…
2 file-05aa607a [outdated → c6e0b7b4] Decision: the app stores everything in SQLite because…
engram history file-05aa607a 会显示完整经过:记录了什么、由什么替代、何时替代以及原因。内容永远不会被悄悄删除。旧证据仍可搜索;如果更正有误,还可以使用 engram supersede <id> --undo 撤销。
Engram 绝不会自行判定一条记录与另一条记录相互矛盾。判断何为事实,应由使用者负责。Claude 保存记忆时,Engram 会指出可能需要更新的现有记忆,由 Claude 作出决定。
为什么会这样?
记忆可以说明它的依据和来源,因此结论不会脱离证据而独立存在:
engram source 903294e5 primary --ref "U.S. Const. art. I, § 2" # where a memory came from
engram link c9422f65 based_on 903294e5 --reason "constitutional text"
engram link c9422f65 derived_from 2da14213 # also: contradicts, supersedes
来源包括 user(你说的内容)、primary(原始文档、法律、裁决或数据集)、secondary(报道或分析)、tool(搜索或程序结果)和 inference(AI 自己的结论)。推断会始终标记为推断。
engram why <id> 会解释任意一条记忆:它的来源和日期、它是记录还是推断、背后的证据、这些证据后来是否已更正或受到质疑、早期版本及其证据;使用 --query 时,还会说明搜索为何将其排在该位置:
$ engram why c9422f65
c9422f65-… amy/views 2026-10-20
My view: population apportionment is the baseline; the 2025 map changes the state's representation.
Source: AI inference. Type: an inference.
Evidence
based_on 903294e5 2026-10-20 primary source, U.S. Const. art. I, § 2
Article I, Section 2: Representatives shall be apportioned among the several States…
derived_from 2da14213 2026-10-20 secondary source OUTDATED → 914e0cb2
Report: the legislature adopted a new map in 2025.
Needs review
• evidence 2da14213 was corrected (current version: 914e0cb2); check whether this still holds
engram check 会列出记忆中所有这类情况:证据已更正或受到质疑的结论、没有证据的推断、尚未解决的冲突,以及指向已删除记忆的链接。它不会修改任何内容。修订立场时,旧立场会保留其原有证据,因此你始终可以查看先前观点的依据,以及支持新观点的内容。
备份。 engram export backup.json.gz 会将每条记忆、更正、知识图谱事实和日记放入一个文件中。engram import backup.json.gz 会在另一台电脑上恢复这些内容,并先检查整个文件:如果有任何错误,就不会修改任何内容。格式见 docs/backup-format.md。
效果如何?
研究人员使用两个公开基准测试 AI 记忆。每个基准都会向系统提供很长的聊天记录,并提出答案隐藏在其中某处的问题。评分依据是系统找到正确对话的频率。
| 基准(默认设置,不使用 LLM) | Engram |
|---|---|
| LongMemEval:500 个问题,正确对话位于前 5 条结果中 | 98.8% |
| LoCoMo:1,986 个问题,答案所在的会话位于前 10 条结果中 | 92.1% |
简单来说:向 Engram 提出 500 个关于数月聊天记录的问题,其中有 494 个问题的正确对话会出现在前 5 条结果中。它使用可在笔记本电脑上运行的小型模型实现这一点,无需 LLM,也无需 API。这些测试衡量的是能否找到正确的对话,并不衡量修正内容、证据链接或回忆笔记能否提高 AI 的准确性;benchmarks/trust_eval.py 会检查这些方面,结果列在下方。
它能让记忆值得信赖吗? 这些测试没有涵盖修正内容、交给模型的笔记或崩溃情况,因此 benchmarks/trust_eval.py 会检查这些方面。在当前版本中,针对其自身(由作者编写、刻意保持小规模)的场景,结果如下:
| 结果 | |
|---|---|
| 事实发生变化后,当前版本排在最前 | 20 个问题中有 20 个(其中 20 个问题里有 4 个没有修正记录) |
| 自动回忆笔记的大小与粘贴所有记忆相比 | 92 个 token,vs. 5,134 个 |
| 自动回忆笔记包含答案 | 20 个中有 17 个(普通前 5 条搜索:20 个中有 19 个) |
| 没有存储相关内容时,自动回忆会提示 | 0 次(共 20 次) |
| 40 次强制崩溃后留下的半写入记忆文件 | 0 个(修复此问题前,1.10.1 之前的版本为 10 个) |
| 6 个写入者并行操作时丢失的修正内容或链接 | 0 个(共 240 个) |
自动回忆以放弃部分答案为代价,换来保持沉默和简短笔记;完整表格、测试未涵盖的内容,以及如何自行运行测试,均见此处。这里没有任何结果能证明它从端到端提高了 AI 的准确性;这方面尚未经过测试。
细则
- 它使用小型本地嵌入模型(all-MiniLM-L6-v2)。Engram 会为助手和你的回复都建立索引。
- 这些数字并非来自留出数据集。 Engram 的增强项是固定的通用规则,并非针对每个问题调优;但我们通过观察 LongMemEval 和 LoCoMo 各版本的得分来决定采用哪些规则(每个步骤都记录在 BENCHMARKS.md 中),因此部分得分是针对这两个测试集拟合的。
- 仅使用原始语义搜索,不使用任何增强项时,LongMemEval 的 R@5 得分为 96.8%。 增强项大约能提高 2 个百分点。
- LongMemEval 中每个问题占 0.2 分,因此细微差异可能只相当于一两个问题。
- 使用 LLM 重排器(需要 API 密钥)可以进一步提高得分。Engram 出于设计考量不提供此功能。
- 所有内容都可以在此仓库中复现。各类问题的完整结果、早期版本和准确命令均见 benchmarks/BENCHMARKS.md。
你应该使用 Engram 吗?
有不少优秀的记忆工具。以下是一份诚实的指南。
| 如果你想要…… | 使用 |
|---|---|
| 为 Claude Code 或 Claude Desktop 提供私密、免费的记忆功能,并且开箱即用 | Engram |
| 为自己的 AI 应用、陪伴型应用或 Agent 提供记忆库,支持离线使用且无需按调用付费 | Engram |
| 阅读并信任所有会接触你数据的代码 | Engram |
| 为多用户云端产品提供记忆功能,并配备仪表板和 API | 使用 Mem0、Zep 或 Supermemory 等托管服务(通常需要账户、API 密钥和 LLM) |
| 只需几条长期规则(“使用制表符”、“我的名字是……”) | Claude 内置记忆或 CLAUDE.md 文件 |
在自己的应用中使用
from engram.agents import AgentDiary
from engram.backends import get_backend
from engram.chateau import Chateau
from engram.knowledge_graph import KnowledgeGraph
from engram.searcher import Searcher
memory = Chateau() # your memory folder (~/.engram/chateau)
searcher = Searcher(get_backend("chromadb"), memory)
for hit in searcher.search("what music does Maya like", n=5):
print(hit["text"], hit["final_score"])
AgentDiary("my-assistant").write("Helped plan the week") # an agent's diary
KnowledgeGraph().add(subject="Maya", predicate="likes", obj="jazz") # facts about people and things
这些调用由 tests/test_public_api.py 固定,因此基于它们构建的应用在各个版本中都能正常运行。要使用完整的默认搜索(包括精确词语索引),请使用 engram.backends.backend_from_config(engram.config.load_config()) 构建后端。
日常命令
# Save things
engram mine ~/project --wing myapp # a folder of files
engram mine ~/Downloads/claude-export --mode convos --wing myapp # a Claude, ChatGPT or Slack export
engram watch ~/project --wing myapp # keep saving as files change
# Find things
engram search "auth decisions" --wing myapp
engram answer "What did we decide about the database?" # a written answer (needs Ollama)
engram replay --room auth-migration # a topic's history, in order
# Fix and keep things
engram correct <id> "the new, correct version" # replace an outdated memory (old one kept as history)
engram history <id> # what replaced what, when and why
engram why <id> # where it came from, what it rests on, what changed
engram forget <id> # delete a memory for good (shows what changes; add --yes)
engram export backup.json.gz # back up everything to one file
engram import backup.json.gz # restore it (checked first; safe to repeat)
# Look after it
engram status # what's in your memory
engram wake-up # the short start-of-session note
engram audit --fix # health check and safe fixes
ID 是 engram search 结果第一列中的短代码。
完整命令参考
设置
engram init <dir> # guided setup
engram serve [--host H] [--port P] [--token] # local web API for apps without MCP (OpenAPI at /openapi.json)
engram reindex [--wing W] # rebuild the search index (after changing the embedding model)
engram connect <app> # add Engram to Cursor, VS Code, Gemini CLI, Codex… (no app: list)
engram install-hooks --apply # Claude Code hooks: auto-recall, auto-save, save before compacting
engram recall "a message" # preview what auto-recall would give Claude
engram setup-reranker # download the reranker model (90 MB) and turn it on
engram setup-reranker --disable # turn the reranker off
保存
engram mine <dir> # project files
engram mine <dir> --mode convos # conversation exports (Claude, ChatGPT, Slack, Claude Code)
engram mine <dir> --wing myapp --room auth # choose the wing and room
engram mine <dir> --since 2026-01-01 # skip older files
engram mine <dir> --plugin obsidian # also: notion, linear
engram watch <dir> --wing myapp # auto-save on change
engram split <dir> [--dry-run] # split concatenated transcripts
engram remember-type "Prefer SQLite for local dev" preference --wing myapp
engram remember-type --list # the 13 memory types
搜索
engram search "query" [--wing W] [--room R] [--results 20]
engram search "query" --no-decay # ignore recency
engram search "query" --no-hybrid # meaning only
engram search "query" --rerank / --no-rerank # force the reranker on or off for one search
engram answer "question" [--wing W] [--model llama3.2] [--chunks 8]
上下文、历史记录和图谱
engram wake-up [--wing W] [--rebuild]
engram replay --room R [--wing W] [--type decision] [--since 2026-06-01] [--min-confidence 0.8]
engram kg query "Kai" [--all]
engram kg add "Kai" works_on "Orion" --from 2025-06-01
engram kg invalidate "Kai" works_on "Orion" --ended 2026-03-01
engram kg timeline "auth-migration"
engram graph [--wing W] [--output file.png] # needs: pip install "engram-chateau[viz]"
更正
engram correct <id> "new text" [--reason "why"] # save a correction that replaces <id>
engram supersede <old-id> <new-id> [--reason R] # mark an existing memory as replacing another
engram supersede <old-id> --undo # make <old-id> current again
engram history <id> # status and full replacement history
engram correct <id> "text" --source primary --ref "cite" --based-on <evidence-id>
删除
engram forget <id> # show what deleting it would change
engram forget <id> --yes # delete it, its search entries and every link to it
遗忘功能适用于本不该保存的内容。它替换的记忆会重新成为当前记忆,依赖该记忆的内容会失去相应证据(engram check 会列出所有因此变得无依据的内容),而更早的导出仍会包含它。若要更改记忆而不丢失其历史记录,请改用 engram correct。
证据和解释
engram link <id> based_on <evidence-id> [--reason R] # <evidence-id> supports <id>
engram link <id> derived_from <other-id> # <id> was inferred from <other-id>
engram link <id> contradicts <other-id> # conflict, undecided
engram link <id> supersedes <old-id> # <id> replaces <old-id>
engram link <id> based_on <evidence-id> --undo # remove a link
engram source <id> user|primary|secondary|tool|inference [--ref "citation or URL"]
engram why <id> [--query "the question"] [--json] # explain a memory
engram check [--json] # what needs review; changes nothing
备份
engram export <file>[.gz] # back up everything to one file
engram import <file> [--dry-run] [--overwrite] # restore; the whole file is checked first
维护
engram status
engram audit [--fix]
engram conflicts # resolve contradicting knowledge-graph facts
engram compress [--wing W] [--room R] # rebuild short summaries (ES)
engram provenance <drawer-id> [--history]
engram provenance --summary
engram ui # local notes app at http://127.0.0.1:7741
设置
所有功能开箱即用。如果想调整设置,可在 ~/.engram/config.json 中进行配置。所有键均为可选,默认值是经过基准测试的配置。
| 设置 | 默认值 | 作用 |
|---|---|---|
redact_secrets | false | 保存任何内容之前,将 API 密钥、令牌和密码替换为空白([REDACTED:…]) |
reranker | false | 本地重排器;使用 engram setup-reranker 启用。关闭时不会额外下载任何内容 |
recall | true | 在 Claude Code 中自动召回(需要 engram install-hooks);设为 false 可关闭 |
recall_max / recall_min_relevance | 3 / 0.30 | 每条消息最多召回的记忆数量,以及记忆必须达到的匹配程度(0 到 1) |
recall_preference_min_relevance | 0.20 | 已保存偏好的匹配门槛;该值较低,因为询问某项选择的请求很少会重复使用偏好中的措辞 |
recall_exclude_wings | ["library"] | 自动召回时永不显示的翼区 |
recall_other_min_relevance | 0.55 | 其他项目的记忆必须达到的匹配程度才会显示 |
projects | {} | 将文件夹映射到翼区,适用于文件夹名不符合预期的情况,例如 {"~/code/app": "billing"} |
keyword_search | true | 与语义搜索并行使用精确词语索引(SQLite,无需下载);首次运行时根据现有记忆创建索引 |
embedding_api_url / embedding_api_model | 未设置 | 使用你运行的嵌入服务(LM Studio、Ollama、llama.cpp、vLLM:任何支持 /v1/embeddings 的服务),代替内置英语模型,例如用于其他语言。设置后运行一次 engram reindex。由于记忆文本会发送给该服务,因此除非 embedding_api_allow_remote 为 true,否则服务必须运行在本机或你的网络中 |
vector_backend | chromadb | 搜索引擎:chromadb、faiss 或 sqlitevec(无需编译组件) |
hybrid_weight | 0.3 | 提升包含相同精确词语的结果;设为 0 可关闭 |
temporal_weight | 0.4 | 提升接近问题所提时间的记忆;设为 0 可关闭 |
preference_summaries | true | 为随口提及的偏好和顾虑建立简短摘要索引 |
l1_budget_tokens | 120 | 唤醒笔记中关键事实部分的长度 |
rerank_top | 20 | 重排器重新排序的顶部结果数量 |
decay_factor / decay_max_days | 0.005 / 90 | 对较新记忆的加权程度,以及加权持续时间 |
chateau_path | ~/.engram/chateau | 记忆的存储位置 |
ENGRAM_VECTOR_BACKEND=sqlitevec engram … 可在单次运行中切换后端。嵌入服务可与默认的 chromadb 后端配合使用;每个服务和模型都有各自的索引,因此切换回来无需重新建立索引,也不会更改记忆。~/.engram/identity.txt 保存每份唤醒笔记开头的简短身份信息。
故障排除
- 安装后提示
engram: command not found。 pip 将它安装到了不在 PATH 中的位置。请使用python3 -m pip install --user engram-chateau,或使用uv tool install engram-chateau/pipx install engram-chateau安装,这些工具会为你处理 PATH。 - 提示
pip: command not found。 请尝试pip3或python3 -m pip。在uv虚拟环境中,请使用uv pip install …。 - 迁移到新电脑。 在旧电脑上运行
engram export backup.json.gz,在新电脑上安装 Engram,然后运行engram import backup.json.gz。导入时会重建搜索索引。 - Claude 中没有显示 engram 工具。 添加服务后,请重启 Claude Code 或 Claude Desktop。如果应用找不到
engram-mcp,请提供which engram-mcp返回的完整路径。 - 提示“ChromaDB failed to load”。 ChromaDB 的编译组件与你的 Python 版本不匹配。请尝试
pip install --force-reinstall --no-cache-dir chromadb,或设置"vector_backend": "sqlitevec",它不需要编译组件。然后再次运行engram mine,因为每个后端都会保留各自的索引。 - Python 3.15 或更高版本。 ChromaDB 目前无法在这些版本上安装,因此 Engram 会回退到
sqlitevec,它按词匹配而非按含义匹配。要进行基于含义的搜索,请使用 Python 3.11 到 3.14。 - 从 GitHub 更新后提示“No such command”。 请在 Engram 文件夹中运行
git pull origin main,然后运行pip install -e .(或uv pip install -e .)。 - 搜索结果的 Relevance 列显示
<0.001。 重排器没有找到真正能回答该问题的内容;请尝试提出更具体的问题。
内部机制:简写、记忆层、Web 界面、代码映射
Engram 简写(ES)
一种紧凑的文本格式,任何大模型都能直接读取,无需解码器。它仅用于 Engram 加载到模型中的短上下文;你的抽屉始终保留原始文本。ES 会去掉填充词,使散文内容缩短约 1.6 倍,代码缩短约 1.1 倍。
from engram.shorthand import compress
compress("The authentication module is a critical component that has a dependency on the database.")
# → "auth module=★★ component +dep on db."
记忆层
| 层 | 内容 | 大小 | 加载时机 |
|---|---|---|---|
| L0 | 身份:AI 是谁 | ~50 个 token | 始终 |
| L1 | 关键事实,以简写形式呈现 | 最多 120 个 token(l1_budget_tokens) | 始终 |
| L2 | 当前主题的记忆 | 按需 | 提及该主题时 |
| L3 | 完整搜索 | 按需 | 被要求时 |
Web 界面
engram ui 会在 http://127.0.0.1:7741 打开一个本地笔记应用,包含关联笔记图谱、标签、置顶笔记、每日日志和 Markdown 编辑功能。目前,笔记保存在你的浏览器中,且尚未显示 ~/.engram/ 中的记忆;要查看这些记忆,请使用 engram search 或 MCP 工具。
| 文件 | 功能 |
|---|---|
engram/chateau.py | 磁盘上的翼、房间、大厅和抽屉 |
engram/searcher.py | 搜索:含义、关键词、时间、近期程度、重排 |
engram/keyword_index.py | 将精确词语索引(SQLite FTS5)与含义搜索合并 |
engram/indexing.py | 将长文本拆分为索引所需的文本块 |
engram/temporal.py | 理解“两个星期前”“六月”“5 月 8 日”等时间表达 |
engram/preferences.py | 从消息中识别偏好和顾虑 |
engram/redact.py | 可选的机密信息脱敏 |
engram/reranker.py | 可选的本地重排器(ONNX) |
engram/miner.py、engram/convo_miner.py | 保存文件和对话 |
engram/lineage.py | 修正:哪些记忆是当前的、哪些已被替代,以及原因 |
engram/relations.py | 证据链接、来源、engram why 和 engram check |
engram/server.py | engram serve:本地 Web API 及其请求检查 |
engram/validate.py | 根据各工具的架构检查工具参数(MCP 和 Web) |
engram/embedding.py | 用可选的嵌入服务替代内置模型 |
engram/backup.py | engram export / engram import |
engram/recall.py | Claude Code 的自动回忆钩子 |
engram/mcp_server.py | MCP 服务(31 个工具),以 engram-mcp 运行 |
engram/connect.py | engram connect:将 Engram 添加到 AI 应用的设置中 |
engram/layers.py、engram/shorthand.py | 唤醒便笺和 ES 速记 |
engram/knowledge_graph.py、engram/agents.py | 知识图谱和 Agent 日记 |
engram/backends/ | ChromaDB(默认)、FAISS、sqlite-vec |
engram/plugins/ | Obsidian、Notion、Linear 导入器 |
engram/hooks/ | Claude Code 保存和压缩前钩子 |
benchmarks/ | LongMemEval 和 LoCoMo 运行器 |
要求
- Python 3.9 或更高版本。 推荐使用 3.11 至 3.14,以支持基于含义的搜索。
- 自动安装: ChromaDB、typer、rich、watchdog、questionary、pyyaml 和 requests。
- 可选附加项:
engram-chateau[faiss]、[sqlitevec]、[viz](图形)或[all]。 - 可选: 使用 Ollama 运行
engram answer。
互联网使用情况: 除两项一次性下载外,不使用互联网。嵌入模型(约 80 MB)会在首次保存或搜索时下载。可选的重排器(90 MB)仅在运行 engram setup-reranker 时下载。你的记忆永远不会离开你的设备。
贡献
欢迎提交错误报告、想法和拉取请求。
git clone https://github.com/TushaeBXN/engram && cd engram
pip install -e ".[dev]"
pytest
发布(维护者)
Engram 通过 .github/workflows/publish.yml 发布到 PyPI,包名为 engram-chateau,并使用 PyPI 可信发布(不存储令牌;所有者为 TushaeBXN,仓库为 engram,工作流为 publish.yml,环境为 pypi)。
- 更新
pyproject.toml中的version和engram/__init__.py中的__version__,并在CHANGELOG.md中添加条目。 - 合并到
main。 - 合并后创建一个新的 GitHub 发布版本,标签设为
v<version>,保留点号(例如v1.5.1,而不是v1.51),并以main为目标分支。工作流会检查标签是否与版本一致、运行测试、构建并上传。
致谢和许可证
Engram 的设计(翼、房间、大厅、抽屉和时间知识图谱)受到其他开源记忆系统的启发。部分检索思路(精确词语索引和日期理解)改编自 Hindsight。
MIT © 2026 Tushae Thomas
如果 Engram 帮你记住了重要的事情,点个 ⭐ 能帮助更多人找到它。
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。