mcpField
E
Engram

Engram

本地服务
github.com/TushaeBXN记忆与知识11 周前更新

关于 Engram

Engram 是本地运行的 AI 长期记忆 MCP 服务,面向开发者、研究者和笔记使用者保存并检索原始文字。它无需 LLM 或 API 密钥,支持语义、全文与时间线索检索,并保留记忆变更历史。

主要功能

  1. 01本地保存原始笔记与对话
  2. 02结合语义、全文和时间检索
  3. 03修正记忆并保留变更历史
  4. 04为 Claude Code 自动回忆与保存
  5. 05提供 31 个记忆管理工具
  6. 06可选启用秘密信息脱敏

适用场景

  1. 01跨会话查找项目决策及其原因
  2. 02搜索笔记、文档和代码资料
  3. 03为个人 Agent 提供本地记忆
  4. 04更新过时记录并追溯旧证据

MCP 相关

Engram 可连接支持 MCP 的应用,并提供 31 个用于回忆、搜索、保存和修正记忆的工具。也可通过本地 Web API 提供相同工具。

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
"mcpServers": {
"tushaebxn-engram": {
"command": "uvx",
"args": [
"engram-chateau"
]
}
}
}
启动命令uvx engram-chateau

本地服务需要在你的电脑上安装运行环境(如 Node.js 18+)。各客户端的配置文件位置不同,请参考客户端文档。

安装包
pypiengram-chateau1.10.5

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。

详细介绍

Engram

engram update image

聊天结束后,你的 AI 会忘记一切。Engram 能帮它记住。 免费、私密、运行在你自己的电脑上,并会逐字保留你写下的所有内容。

MIT License Python 3.9+ PyPI CI


问题

周一,你花了一小时和 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 Desktopclaude_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_secretsfalse保存任何内容之前,将 API 密钥、令牌和密码替换为空白([REDACTED:…])
rerankerfalse本地重排器;使用 engram setup-reranker 启用。关闭时不会额外下载任何内容
recalltrue在 Claude Code 中自动召回(需要 engram install-hooks);设为 false 可关闭
recall_max / recall_min_relevance3 / 0.30每条消息最多召回的记忆数量,以及记忆必须达到的匹配程度(0 到 1)
recall_preference_min_relevance0.20已保存偏好的匹配门槛;该值较低,因为询问某项选择的请求很少会重复使用偏好中的措辞
recall_exclude_wings["library"]自动召回时永不显示的翼区
recall_other_min_relevance0.55其他项目的记忆必须达到的匹配程度才会显示
projects{}将文件夹映射到翼区,适用于文件夹名不符合预期的情况,例如 {"~/code/app": "billing"}
keyword_searchtrue与语义搜索并行使用精确词语索引(SQLite,无需下载);首次运行时根据现有记忆创建索引
embedding_api_url / embedding_api_model未设置使用你运行的嵌入服务(LM Studio、Ollama、llama.cpp、vLLM:任何支持 /v1/embeddings 的服务),代替内置英语模型,例如用于其他语言。设置后运行一次 engram reindex。由于记忆文本会发送给该服务,因此除非 embedding_api_allow_remote 为 true,否则服务必须运行在本机或你的网络中
vector_backendchromadb搜索引擎:chromadb、faiss 或 sqlitevec(无需编译组件)
hybrid_weight0.3提升包含相同精确词语的结果;设为 0 可关闭
temporal_weight0.4提升接近问题所提时间的记忆;设为 0 可关闭
preference_summariestrue为随口提及的偏好和顾虑建立简短摘要索引
l1_budget_tokens120唤醒笔记中关键事实部分的长度
rerank_top20重排器重新排序的顶部结果数量
decay_factor / decay_max_days0.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 笔记界面 ### 代码结构
文件功能
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.pyengram serve:本地 Web API 及其请求检查
engram/validate.py根据各工具的架构检查工具参数(MCP 和 Web)
engram/embedding.py用可选的嵌入服务替代内置模型
engram/backup.pyengram export / engram import
engram/recall.pyClaude Code 的自动回忆钩子
engram/mcp_server.pyMCP 服务(31 个工具),以 engram-mcp 运行
engram/connect.pyengram 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)。

  1. 更新 pyproject.toml 中的 version 和 engram/__init__.py 中的 __version__,并在 CHANGELOG.md 中添加条目。
  2. 合并到 main。
  3. 合并后创建一个新的 GitHub 发布版本,标签设为 v<version>,保留点号(例如 v1.5.1,而不是 v1.51),并以 main 为目标分支。工作流会检查标签是否与版本一致、运行测试、构建并上传。

致谢和许可证

Engram 的设计(翼、房间、大厅、抽屉和时间知识图谱)受到其他开源记忆系统的启发。部分检索思路(精确词语索引和日期理解)改编自 Hindsight。

MIT © 2026 Tushae Thomas

如果 Engram 帮你记住了重要的事情,点个 ⭐ 能帮助更多人找到它。

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。