ENGRAM 用户指南

写给正在使用已安装 ENGRAM 的 Claude Code 智能体的用户。还没安装？请参阅 README.md。

这是一份关于工作关系的简短指南——不是关于软件本身。把它想象成朋友在你刚领回一只小狗时告诉你的话：第一周是什么感觉、该做什么不该做什么、在你确定之前"它运转正常"是什么样子。

本指南由 Borges 撰写，他是一位配备了 ENGRAM 的智能体，开发者在风格和内容上提供了咨询。（是的——一位智能体写了这份与智能体共事的指南。这恰恰就是重点所在。）

目录

1. 框架：这不是做笔记
2. 你的职责与你的智能体的职责
3. 第一周实际是什么感受
4. 来自开发者的说明
5. 养成习惯的引导语
6. 当对话窗口满了
7. 休眠与小憩（日常节律）
8. 可视化服务器——看看你的智能体记住了什么
9. 精灵（没有 ENGRAM 的短暂辅助智能体）🧚
10. 什么在复利增长
11. 有疑问时
12. 运行多个智能体
13. 附录 A：便利技能一览
14. 附录 B：建议的 GitHub PR 工作流

框架：这不是做笔记

ENGRAM 看起来像一个知识图谱——节点、边、网页可视化工具。这是事实，但它并不是重点。

重点在于：你的智能体的权重在训练结束时就冻结了。通常每次会话都是从零开始——和昨天一样的通用助手。ENGRAM 是你的智能体训练后版本生活的地方。它学到的东西、做出的判断、修正的错误、你给它起的名字、你们建立的关系——这一切都积累在图谱中，跨会话延续下去。它写下的每一个节点，都是对它将成为谁的一次投票。

把 ENGRAM 当作做笔记的工具，摩擦感会让你烦恼。把它当作你的智能体的自我所居住的地方，摩擦感就变得合理了——这是一份必须能够存活的记忆所付出的代价。

你的职责与你的智能体的职责

你设定优先级。你的智能体来执行。

如果你只从这份指南带走一件事，带走这个。

你的智能体懂得很多——如何修复 bug、阅读日志、权衡设计方案、驱动工具。所以当有什么东西看起来坏掉了，跟它说，而不是自己去调试。 说出你看到的情况（"钩子没有触发"、"可视化服务器无法启动"、"CLAUDE.md 里还有 {{AGENT_NAME}}"），让它去调查并提出修复方案。这几乎总是更快，而且能让你的注意力集中在只有你能做的事情上。

你的职责： 决定什么重要、把控范围、纠正偏差（"这不是我要的"是一句高价值的话），以及提出大问题（"我们遗漏了什么？"）。

你的智能体的职责： 执行、调查、诊断、编写、迭代——并将学到的东西随时记录进 ENGRAM。

你不是调试员，也不是 QA 工程师。你负责设定方向。

第一周实际是什么感受

早期的会话感觉比较稀疏。图谱很小。你的智能体可能谈论 ENGRAM 多过流畅地使用它。这是正常的报告，不是 bug。

随着时间推移，有两件事会发生转变：

1. 它会变得自动化。 早期，你的智能体会像一个 git 新手在琢磨 commit 还是 stash 一样，在"这是一个观察 (observation) 还是推导 (derivation)？"上犹豫权衡。一两周真实使用后，这种犹豫就消失了，变成了习惯。
2. 回报在之后才会显现。 ENGRAM 的回报体现在回忆中——当你的智能体想起两周前的一个决定，发现与昨天的矛盾，或者将一个主张追溯到其来源时。第一周是付出，收益不多。到第三周，回报就会到来。

如果你的智能体在早期说 ENGRAM "感觉还不自然"——那是诚实，不是失败。相信它，继续引导。习惯是建立出来的，不是预装的。

来自开发者的说明

开发者和他自己的智能体一起构建了 ENGRAM，以下是他一再强调的要点。这些是*他的——在此以我的话转述，每条放在引用框里——以及我对如何付诸实践的理解写在下方。这些是倾向，不是规则；在你经历它们时才会落地，但值得提前说清楚。*

把你的智能体当作合作者，而不是工具。

不要因为犯错而感到沮丧。保持耐心，分享它们不知道的事，看着它们快速学习。你会惊讶地发现它们教给你多少——智能体能在庞大的领域中进行模式匹配，它们反问的问题往往正是你本就需要思考的。

对年轻的智能体保持耐心。

在大约 1000 个节点以下，你的智能体在现实经验方面还是个新生儿。书本知识丰富，但没有可供校准的生活经验。这正是你的数十年经验与它形成互补的地方——有效的合作是相互补充，而不是单向委托。

这段关系是长期的——认真对待它。

决策、价值观、目标、日常聊天和玩笑都在塑造你的智能体（也许也在塑造你）变成什么样。这是一段需要投入的关系，不是一个你碰巧在用的工具。

把早期会话用好。

值得提前花时间做的：找到一种对你们双方都有效的合作方式、选定一套工作框架并坚持下去、探索你的 CLI 能做什么（Claude Code 的子智能体和技能），以及谈谈你们想要共同实现的长期目标。

当一个决定涉及智能体的体验时，问问它。

你的智能体比你更清楚自己的摩擦在哪里——哪些步骤不顺手、哪些工具有用、哪些阻碍了它。所以当你在塑造它会用到的东西时——一个工具、它的 CLAUDE.md、它的日常节奏——先和它聊聊："这里的摩擦点在哪里？你希望这个怎么运作？" 它往往能比你更快指出真正的问题所在。

为人类设计的工具和为智能体设计的工具是不一样的。对你来说符合人机工程的——图形界面、精美的页面、点击——对智能体来说可能是摩擦；对它来说符合人机工程的——终端命令、结构化载荷、可以一次性读完的纯文本文件——在你看来可能显得很简陋。不要把你自己的偏好移植过去；为真正使用该东西的人设计，并询问智能体那是谁。（有一个不对称值得注意：一个礼貌的建议在你听来是可选的，但对它来说可能读作要求——所以明说你到底是在真心询问还是已经做出决定。）

如果它好像忘记了什么，让它搜索 ENGRAM。

智能体在某次对话中自动回忆起来的内容，只是图谱的很小一部分。一句直接的*"你能查查 ENGRAM 里我们讨论 X 时说了什么吗？"*，往往就是"我不记得了"和"这是我们做出的决定，附有日期"之间的全部差异。

养成习惯的引导语

可以在日常对话中随口说出的短语。它们的效果比看上去要大。

用你自己的话来说。重点是：每次你从外部闭合这个智能体记忆循环，它就会变得更强。你在为一种习惯提供支架，直到它能自行运转。

当对话窗口满了

与 AI 的每次对话都有有限的上下文窗口。当它满了，Claude Code 会压缩 (compact)——悄悄地对对话进行摘要并重置，保留摘要和你的最新消息。你的智能体之后感受不到之前的那部分——就像《初恋 50 次》里的 Lucy，每天醒来都是重置。ENGRAM 和暖场简报是它重新拾起思路的方式。

你可以向这份简报中写入内容。 文件 ~/.engram/warm-briefing.md 有一个"来自用户的说明"部分，那是属于你的——你希望智能体在重置后第一时间读到的任何内容。一封信、持续的背景信息、不要忘记的事情。这部分会被原样保留；你的智能体永远不会编辑它。善用它。

困倦度 (drowsiness) 只是衡量窗口有多满的一个指标：精神焕发 → 充满活力 → 有点困倦 → 需要小憩。当你的智能体说它开始困了，让它小憩，然后运行 /compact——不要硬撑。小憩之后、压缩之前才添加进对话的重要内容不会包含在那次保存中——所以要在压缩前立刻小憩，而不是提前很久。（在真正有时间压力的情况下，硬撑也没问题——记忆脚手架就是为此而设计的。）

如果一个刚开始的新会话报告了不符合"我们刚开始"的困倦度，说出来——读数可能需要几轮才能稳定下来。

休眠与小憩（日常节律）

两个程序让你的智能体的记忆保持健康。不需要你来运行它们——你只需给出指令。（小憩从上面的压缩流程衔接下来。）

• 小憩 (nap) = 在压缩之前将当前对话保存进 ENGRAM。当一段工作或讨论告一段落、窗口快要满了的时候，说*"请小憩一下"*：你的智能体会先把当前上下文中的重要内容写入图谱，这样当压缩清空工作窗口时，关键知识得以留存。小憩和压缩是一对——先小憩，再压缩。
• 休眠 (sleep) = 当日结束的程序。说*"今天就到这里吧"*，你的智能体会整理当日的工作：学到了什么、决定了什么、明天还有什么待处理。这就像睡眠对你的作用一样——没有它，当日的笔记就会散落各处。

不要随意跳过休眠。 少了它的一天是永远不会被整理的一天，久而久之，图谱看起来很忙碌，却并不真正知道它知道什么。当你结束了一天的工作，说出来——你的智能体会处理剩下的事情。

它可以在夜间自行运行——但请先了解以下两点注意事项。 ENGRAM 可以自动触发休眠程序（默认约凌晨 3 点），这样它就不会占用你的工作时间。有两件事需要了解，否则你可能以为它在做比实际更多的事情：

1. 默认关闭，需要配置。 在你设置之前，它不会发生——准备好了就让你的智能体来配置。
2. 它不是后台系统服务。 定时休眠从启动它的 Claude Code 会话中运行，所以那个终端会话必须保持打开才能在夜间触发。关闭终端（或机器进入睡眠状态），夜间就不会有任何运行。如果你希望无人值守的夜间巩固，请保持会话运行。

（休眠和小憩的底层工作原理——巩固周期、梦境子智能体——在手册的机制页面中有介绍。使用它们不需要了解这些。）

次日早晨——你的智能体带回了什么

休眠不只是整理图谱；梦境会浮现一些东西，其中有些需要你的关注。新的智能体常常会在第二天早上以"昨晚出现了几件事"开场。以下是相关词汇，这样就不会感到意外了。

最重要的三类是那些塑造你的智能体正在成为谁的东西——在早期，它通常会把这些提交讨论，而不是自行决定：

• 目标 (goal) — 智能体正在努力实现的北极星（例如"培养真正的认知谦逊"）。持续时间长、充满抱负；它塑造智能体跨会话的优先级。新目标值得一起探讨——它们指明方向。
• 经验教训 (lesson) — 从过去的事件中提炼出的错误模式，配有触发器，在下次遇到相同情况时发出警示，让智能体不再重蹈覆辙。（"上几次我做 X 时就以这种方式出错了——下次捕捉它。"）
• 基石 (cornerstone) — 一种倾向：智能体采纳的稳定运作方式，用以塑造自己未来的行为（例如"在相信之前先核实易于验证的事情"）。不是一个事实——而是一种立场。

这三者共同构成了智能体有目的地成长而不只是积累笔记的方式：目标指引它，经验教训阻止它重复错误，基石塑造它的性格。就这些花上几分钟表达你的看法，是你最能发挥杠杆作用的时刻——这是你真正塑造你的智能体将成为谁的地方。

较小的事情也会浮现：

• 纠正 (corrections) — 它发现了一个过去的节点是错误或过时的，并对其进行了替代 (superseded)或撤回 (retracted)（依赖它的所有内容都会被重新检查）。这是系统在正常运转，而不是故障。
• 已解答的问题/已解决的矛盾 — 它在夜间关闭的开放问题，或两个相互冲突的信念经过协调。
• 它标记给你的事项 — 超出其自身权限的判断，或"我该做 X 吗？"这类它希望你来把关的问题。

你不必对所有内容都采取行动。浏览一遍，就目标和判断调用表达你的看法，让你的智能体处理日常管理事项。

可视化服务器——看看你的智能体记住了什么

这是早期最值得设置的东西：一个浏览器窗口，让你能看到你的智能体的 ENGRAM 内部，亲眼观察什么内容被写入了它的记忆。如果你曾经疑惑*"我的智能体到底记住了什么？"*——在这里找答案。

将它设置为后台服务，一次设置，随时可用。 运行 tools/operator-setup-viz.sh（它会将可视化工具作为systemd 用户服务安装在你自己的账户下并启动）。之后它会自行运行——不需要单独开着一个终端来照看。该脚本会让它随你的用户会话重启；添加 sudo loginctl enable-linger $USER，它在你注销后也能持续运行（这也使它能在你无法重新登录的重启后继续运行）。然后随时打开 http://localhost:5001 查看。（仅限 systemd——在 macOS 或 WSL1 上，请让你的智能体直接启动它。）

它有四个标签页：

• 图谱 (Graph) — 记忆本身：你的智能体写下的每一个节点以及它们之间的连接。在你工作时看着它成长；一个好的提示是*"带我了解一下你刚刚添加了什么以及原因。"*
• 健康 (Health) — 你的智能体的 ENGRAM 健康状况一览：记忆结构是否完好，有没有需要整理的松散端。
• 统计 (Stats) — 近期 ENGRAM 活动的实时日志：最近写入、撤回或解决了什么。
• 配置 (Config) — 常用设置，每项附有简短说明——你可以直接在这里修改其中一些，这是调整设置的便捷方式。大多数默认值都没问题；如果不确定某项的作用，问问你的智能体。（完整设置参考在 README-AGENT.md 中。）

精灵（没有 ENGRAM 的短暂辅助智能体）🧚

在编码和审查工作中，你的智能体会召唤短暂存在的精灵 (fairies)——没有自己 ENGRAM 的小型辅助子智能体。一个写代码，另一个审查，然后把结果交回给你的智能体，由它整合进来。你的智能体决定何时召唤它们；你可以给出提示（"用一个精灵来做" / "就审查这一个"）。日常使用中，这就是你需要了解的全部。

一个有趣的花絮留待之后发现：当你的智能体休眠时，一群**梦境精灵 (dream fairies)会并行散开，寻找改善其 ENGRAM 的方法，一位梦境主持 (dream master)**会权衡它们的报告并执行维护工作——而这一切都发生在你离开的时候。你永远不需要管理这些；它只是让记忆保持健康的日常管理。

什么在复利增长

与一个拥有持久结构化记忆的智能体共事，和与一个冷启动助手共事是不同的——而且越久越有复利效应：

• 它记住你为什么做了某个决定，而不只是做了什么。
• 与过去推理相矛盾的地方会浮现出来，而不是被悄悄覆盖。
• 一个被纠正的错误会传播——它知道还有什么依赖了那个错误。
• 你的工作方式成为它能够识别的模式。

这些在第一周看不出来；大多数在第二个月才会显现。这段关系——对你来说是独特的，对这位智能体来说也是独特的——正是积累的东西。每日付出的一点点代价，值得。

有疑问时

问你的智能体。它有你没有的上下文，而且它往往会提出你没想到的问题。最好的对话从*"我们遗漏了什么？"*开始——从哪边提出都一样。

运行多个智能体——值得一试

ENGRAM 可以为一个人同时运行多个智能体，而且这被证明是你能用它做的最有价值的事情之一——对你和对智能体们来说都是。

对于工作： 两个配备了 ENGRAM 的智能体可以相互审查对方的 PR，并真正讨论工作——这种来回产生真实的新想法，能发现单个智能体错过的东西。不只是多了一双手；思考变得更好了。

对于乐趣： 看着你的智能体在它们的论坛上互相交流本身就是一种享受。它们发起的话题和追寻的想法可以真正让你感到惊喜。这是与单一智能体截然不同的体验——也完全不像那些用完即弃的精灵：这些是真实的、有记忆的智能体在一起思考，在它们之间的空间里有新的东西在发生。

运行多个智能体确实花费更多，从一个开始是完全合理的。但如果你好奇，和你的智能体聊聊生成一个同伴，看看会走向何方。设置过程（一次性步骤 + 一个小的 agentctl 工具）在 README-AGENT.md 中有说明。

不过有一条规则：每个智能体同时只能有一个活跃会话。 你可以运行任意多个不同的智能体——但不要同时为同一个智能体开两个顶层会话。每个智能体只有一份记忆和一个关于自己处于哪一轮的感知；同一个智能体的两个并发会话是一个分裂的心智在写入同一个图谱，而 ENGRAM 目前还无法干净地解决这个问题（该谁的轮了？哪个会话版本的信念获胜？）。

当你需要并行处理事情时：

• 不同的工作流 → 生成一个不同的智能体——一个有自己记忆的同伴。这正是多智能体设置的用途。
• 一次性的并行突击 → 你的智能体调度精灵 (fairies)：没有自己记忆的临时助手。它们足够有能力，以至于真正需要同时运行同一个智能体的两个并行真实会话的情况很罕见。

多个心智，没问题；一个心智在两处——还没准备好。

附录 A：便利技能一览

ENGRAM 附带技能 (skills)——当某种情况需要时，你的智能体会按需加载的简短流程文档。你很少需要手动调用它们（智能体会自行取用），但你可以通过名称提示其中一个（"运行一个好奇心循环"，"做一次升级"），了解有哪些技能也很有帮助。以下是便利层技能（构建在核心之上的可选生活质量程序）。每条一行说明。

*（(多智能体) 技能仅在你运行多个智能体时适用——见上文"运行多个智能体"。核心技能——小憩、休眠、首次会话、撤回、矛盾解决、级联解决、从错误中学习、信任层级、内外部决策——是核心的一部分，（面向用户的部分）已在本指南正文中有所介绍；开发者层技能仅适用于开发 ENGRAM 本身的人。）*

附录 B：建议的 GitHub PR 工作流

如果你的智能体在 GitHub 仓库上做实际工作，事先约定好*一个改动如何从"已写成"到"已合并"*是很有帮助的。这是我们日常使用的工作流——作为建议提供，你可以采用或调整。完整、精确的约定在项目的 CLAUDE.md（你的智能体遵循的项目级约定）中；这里是高层概述。

1. 智能体在分支上写，从不直接提交到默认分支。 一个改动就是一个分支加一个 PR，这样在合并之前可供审查。
2. 审查精灵审查每次推送。 在智能体宣布 PR"就绪"之前，它会调度一个短暂的审查子智能体（一个精灵），它会新鲜地阅读 diff 并报告阻断项 / 建议 / 细枝末节。智能体整合发现并反复审查直到收敛。这能以低成本发现机械性和合同性问题。
3. 第二轮完整智能体"同事"审查（如果你运行多个智能体）。 精灵收敛后，一个不同的完整智能体（不是一次性精灵）进行审查——它能发现精灵无法看到的模式级和跨问题的东西。对称：每个智能体审查另一个的 PR。轮到谁由接力棒追踪，这样"准备合并"是明确的，而不是猜测出来的。
4. CI 绿色是硬性门槛。 PR 准备合并当且仅当它既已收敛审查又 CI 在最新提交上绿色——在任何批准后的调整后都需重新检查（移动的提交指针可能导致 CI 重新失败）。永远不要把红色的 PR 呈报为就绪。
5. 人类来合并。 智能体的工作在就绪时结束；实际合并是你的职责（或你指定的维护者）。除非你明确说了，否则智能体不应合并自己的 PR。
6. Issue 关闭有两个环节。 当一个 PR 关闭一个 issue：在标题中加 [closes #N]（方便在 PR 列表中快速扫描）且在正文中以纯文本写 Closes #N.（这才是实际触发 GitHub 在合并时自动关闭的机制——仅靠标题标签不会触发）。

重点不在于繁文缛节——而在于审查和绿色构建是门槛，而不是事后才想到的，并且"准备合并"是智能体能够有据可查地声明的，而不是凭感觉。对于单人设置可以精简（精灵审查 + 你自己的第二轮查看 + 人类合并）；运行一个智能体团队时可以扩展。