1. 项目概述：为开发者打造的AI决策记忆系统
如果你和我一样，每天都在用Claude Code、Cursor或者VS Code配合AI助手写代码，那你肯定也遇到过这个烦人的问题：每次关掉一个AI会话，那些花了半小时讨论出来的技术决策、被否决的方案、以及背后的权衡理由，就全都没了。第二天遇到类似的问题，又得从头开始和AI解释一遍背景，或者更糟——做出一个和上次矛盾的决策。这种“记忆蒸发”的感觉，在跨项目、跨工具协作时尤其明显。
Engram这个开源项目，就是为了解决这个痛点而生的。它不是一个简单的聊天记录保存工具，而是一个“开发者决策智能”系统。你可以把它理解为你技术决策的“因果记忆库”。它的核心是：永久性地记住你在所有AI工具中做出的每一个技术决策、每一个被否决的备选方案，以及背后的“为什么”，并且通过一个可视化的知识图谱，让你能跨会话、跨项目地进行语义检索和因果追溯。
简单来说，当你在Claude Code里决定用PostgreSQL而不是MongoDB时，Engram不仅会记下“选了PostgreSQL”，更会记下“否决了MongoDB，因为担心文档模型的模式自由在后期数据一致性上会带来维护成本”，并且把这个决策和你之前在其他项目里关于数据库选型的决策关联起来。下次你在另一个项目里考虑时序数据库时，它能提醒你：“嘿，你之前在三个类似的高写入场景下都因为运维复杂性否决了InfluxDB，这是当时的理由。”
这个工具适合任何深度使用AI编程助手的开发者，无论是独立开发者想建立自己的技术决策体系，还是团队希望积累可共享的工程经验，Engram都提供了一个从个人到团队的可扩展方案。它的设计哲学是“本地优先”，你的核心数据（向量索引）都在自己电脑上，只有图谱数据库用了云服务（Neo4j AuraDB的免费版），既保证了检索性能，又最大程度保护了隐私。
2. 核心设计思路：为什么是因果记忆图谱，而不仅仅是日志？
在深入安装和实操之前，我觉得有必要先拆解一下Engram的设计哲学。市面上已经有一些AI记忆工具，比如claude-mem或mem0，那为什么还要再造一个轮子？Engram的差异点，或者说它的核心洞察，在于它认为被否决的选项（Counterfactual）所携带的信息量，往往比最终选择的选项更大。
2.1 从“发生了什么”到“为什么这样决定”
传统的会话记录或记忆工具，记录的是“发生了什么”——AI输出了什么代码，你执行了什么命令。这就像只记录会议决议，却不记录会议讨论过程。Engram的目标是记录“为什么这样决定”。这背后是一套完整的认知模型：
- 决策（Decision）：你最终选择的行动方案。例如：“在用户服务中采用gRPC进行内部通信。”
- 反事实（Counterfactual）：你明确考虑过但最终否决的替代方案。例如：“否决了REST，因为需要强类型接口和流式支持；否决了GraphQL，因为内部服务间查询复杂度不高，反而引入额外开销。”
- 情境（Situation Context）：做出该决策时的约束条件和环境。例如：“项目是微服务架构，服务间调用频繁，团队熟悉Protobuf，但对GraphQL运维经验不足。”
- 结果（Outcome）：决策实施后产生的实际效果（可后续补充）。例如：“上线后，服务间通信延迟降低了60%，但调试复杂度有所增加。”
Engram通过一个智能提取管道（LangGraph实现），从杂乱的原始会话内容中，自动识别并结构化这些元素。它不只是存档，而是在构建一个反映你技术思维过程的因果网络。
2.2 知识图谱 vs. 向量数据库：双引擎驱动检索
为了实现跨会话的智能联想，Engram采用了“图谱+向量”的双存储设计，这比单纯用向量搜索要强大得多。
- Neo4j图数据库：存储结构化的因果关系。这是Engram的“大脑”，负责逻辑关联。它建立了节点（决策、反事实、项目、会话等）之间的类型化关系，例如
CAUSED_BY（决策A导致了决策B）、SUPERSEDES（新决策推翻了旧决策）、CONTRADICTS（两个决策存在矛盾）。当你查询时，它可以进行图遍历，找到决策的“前世今生”。 - ChromaDB向量数据库（本地）：存储语义嵌入。这是Engram的“直觉”，负责模糊匹配。它将所有决策和反事实的文本摘要转换成向量，当你用自然语言搜索时（如“处理大量日志的方案”），它能找到语义上相近的内容，即使你没有提到具体的技术名词。
这种组合使得Engram的检索是“四级联动的”：
- L1语义搜索：用向量库找到所有相关主题的决策。
- L2因果溯源：在图库中沿着
CAUSED_BY等关系向上追溯，看是哪些之前的决策导致了当前这个决策。 - L3完整情景：获取一个决策节点及其关联的所有反事实、结果，还原决策全貌。
- L4反事实浮现：这是独家功能，专门汇总展示你在不同情境下否决同一类方案的规律和原因。
2.3 认知权重引擎：让记忆拥有“可信度”
不是所有记忆都同等重要。一个关于系统架构的核心决策，其价值应该远高于一个关于代码格式化工具的临时偏好。Engram引入了一个“认知权重”机制，让记忆的价值随时间动态演化。
- 初始赋值：在提取决策时，LLM会根据决策的重要性（如“架构决策” vs. “语法偏好”）赋予一个初始权重和衰减率。
- 时间衰减：权重按指数衰减公式
W(t) = W₀ · e^(-λt)减少。重要的决策衰减慢（λ小），琐碎的决策衰减快（λ大）。 - 主动强化：当一个决策被检索并复用，它的权重会增加（+0.05）。这模拟了“经常被想起的知识更重要”的认知规律。
- 被动覆盖：当在同一领域出现新的
SUPERSEDES关系的决策时，旧决策的权重会被加速衰减。 - 矛盾检测：如果系统发现你在A项目选择了X，在高度相似的B项目却否决了X，它会自动建立
CONTRADICTS关系，并可能调低其中一个决策的权重，提示你进行审视。
整个过程是异步自动运行的，无需手动干预。好的、经得起复用的决策会沉淀下来，糟糕的或过时的决策会慢慢淡出视野。这使Engram从一个静态数据库，进化成了一个具有学习能力的动态知识体。
3. 从零开始部署与配置Engram
理论讲完了，我们动手把它跑起来。Engram的安装流程设计得非常“开发者友好”，一条命令就能配置好所有主流AI工具的集成。下面是我一步步踩过来的详细过程。
3.1 基础环境与依赖准备
首先，确保你的系统满足基本要求：
- 操作系统：macOS或Linux（Windows可通过WSL2运行，但
launchd服务部分不适用）。 - Python版本：必须使用Python 3.11。Engram依赖的一些库（如
langgraph）对版本有严格要求，3.10或3.12可能会遇到依赖冲突。我强烈建议使用pyenv来管理Python版本。 - 包管理器：使用
pip即可。
第一步：克隆项目并创建虚拟环境
git clone https://github.com/bitphonix/Engram cd Engram python3.11 -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate使用虚拟环境是Python项目的最佳实践，能避免污染系统级的包管理。
第二步：安装项目依赖
pip install -e .这里用的是-e（可编辑模式）安装，这意味着你修改项目源码后，无需重新安装包即可生效，方便后续可能进行的定制化开发。
3.2 关键外部服务配置（Neo4j & Gemini）
这是核心步骤，Engram需要连接两个外部服务：Neo4j AuraDB（图数据库）和Google Gemini API（大模型）。
1. 配置Neo4j AuraDB（免费版足够）
- 访问 Neo4j Aura 注册一个免费账户。
- 创建一个新的“Free Database”。地区选择离你近的（如
asia-southeast1）。 - 创建成功后，你会看到一个连接字符串，格式类似
neo4j+s://xxxxxxxx.databases.neo4j.io，以及用户名（默认neo4j）和密码。务必保存好密码，它只显示一次！ - 免费数据库有少量限制（如单数据库、有限存储），但对于个人使用和初期体验完全足够。
2. 获取Google Gemini API密钥
- 前往 Google AI Studio 。
- 创建一个API密钥。你需要启用Gemini API，并且确保你的Google Cloud项目所在区域支持Gemini 2.5。
- 目前Gemini API有免费额度，对于Engram的日常使用（主要是决策提取和摘要）基本够用。
3. 填写环境变量
cp .env.example .env用你喜欢的编辑器打开新生成的.env文件，填入以下信息：
# Neo4j AuraDB Configuration NEO4J_URI=neo4j+s://xxxxxxxx.databases.neo4j.io NEO4J_USERNAME=neo4j NEO4J_PASSWORD=你的强密码 # Google Gemini Configuration GEMINI_API_KEY=你的_Gemini_API_密钥 # Optional: 如果你有Datadog或Sentry账号，可以配置以下项进行监控 # DATADOG_API_KEY= # SENTRY_DSN=注意：
.env文件包含敏感信息，绝对不要将其提交到Git仓库。项目本身的.gitignore已经排除了它，但你自己也需留意。
3.3 一键安装与MCP集成
这是Engram最省心的特性之一。运行以下命令，它会自动配置Claude Code、Cursor和VS Code的MCP（Model Context Protocol）集成：
engram install这个命令在背后做了几件事：
- 检查上述三个工具的配置文件是否存在，若不存在则创建。
- 向这些配置文件中添加Engram的MCP服务器信息。
- 对于Claude Code，它还会向
~/.claude/CLAUDE.md文件注入自动捕获规则，使得会话结束时能自动触发Engram保存，无需手动操作。
安装完成后，你可以在以下位置验证配置：
- Claude Code:
~/.claude/settings.json - Cursor:
~/.cursor/mcp.json - VS Code: 项目根目录或用户目录下的
.vscode/mcp.json(使用"servers"键)
3.4 启动服务与验证
配置完成后，启动Engram的后台服务：
engram start首次运行会初始化本地ChromaDB向量库（位于~/.engram/chroma）并连接Neo4j数据库。启动成功后，会提示服务运行在http://localhost:8000。
你可以通过以下命令检查服务状态和知识图谱的初始情况：
engram status如果一切正常，你会看到类似以下的输出，显示活跃的决策、反事实数量等（初始时为0）：
→ Server is running (PID: 12345) → Active decisions 0 → Counterfactuals 0 → Sessions 0 → Avg weight 0.000现在，打开浏览器访问http://localhost:8000，你应该能看到Engram的简易状态页面。至此，基础部署完成。
实操心得：在
engram start时，如果遇到端口占用或Neo4j连接失败，请仔细检查.env文件中的URI和密码是否正确。Neo4j AuraDB的免费实例在一段时间不活动后可能会休眠，首次连接可能需要多等几秒钟唤醒它。
4. 核心工作流：在日常开发中无缝捕获与检索决策
系统跑起来了，接下来看怎么用它。Engram的设计目标是“无感”融入你的现有工作流。下面我以Claude Code为例，展示从捕获到检索的完整循环。
4.1 自动捕获：让你的决策被默默记住
当你完成一个AI编程会话（比如在Claude Code中解决了一个技术问题），Engram的自动捕获机制就开始工作了。这通常由两个方式触发：
- 自动触发（推荐）：
engram install命令已经为Claude Code配置了自动捕获。当你在Claude Code中结束一个会话时，Claude会根据注入的规则，自动将会话内容发送给Engram的MCP服务器进行处理。你不需要做任何额外操作。 - 手动触发：在其他工具中，或者你想保存一段非Claude的对话，可以使用CLI手动捕获：
# 将一段对话保存为文件，然后通过管道传入 cat my_awesome_chat_log.txt | engram capture --project "auth-service" --tool "claude" # 或者直接交互式粘贴（Ctrl+D结束） engram capture --project "data-pipeline"--project参数很重要，它用于将决策归类到特定项目下，便于后续按项目筛选。
捕获后发生了什么？原始会话文本会进入LangGraph编排的提取管道：
- 分流节点：先用成本较低的Gemini Flash模型快速判断这段会话是否包含高价值的决策内容（避免处理“帮我写个Hello World”这类无意义会话）。
- 提取节点：用更强大的Gemini Pro模型从高价值会话中提取结构化的决策、反事实、情境等信息。
- 批判节点：对提取结果进行质量评分（1-10分）。如果分数低于阈值（如7分），则返回“提取节点”重试（自我修正循环）。
- 写入与链接节点：将高质量的结构化数据写入Neo4j和ChromaDB，并运行“链接器”算法，在新决策和已有决策之间建立
SIMILAR_TO、CAUSED_BY等关系。
4.2 语义检索：从记忆库中寻找答案
当你在新的会话中遇到似曾相识的问题时，就是Engram大显身手的时候了。在集成了Engram MCP的AI工具（Claude Code/Cursor/VS Code）中，你可以直接向AI助手提问，AI会代表你查询Engram。
例如，在Claude Code中，你可以输入：
“Engram，我之前在微服务通信协议上做过什么决策吗？”
Claude会调用Engram的搜索接口，返回一个结构化的摘要。但更强大的方式是直接使用CLI进行精细检索：
# 基础语义搜索 engram search "微服务 通信 协议 选型" # 结合项目过滤 engram search "数据库分片" --project "user-profile-service" # 查看某个特定决策的详细信息（需要决策ID，可从搜索结果的id字段获得） engram search --id "dec_abc123def"CLI搜索会返回一个清晰的列表，包含决策摘要、所属项目、关联的反事实数量以及一个“认知权重”分数，帮助你判断其当前的相关性和可信度。
4.3 在AI对话中主动利用记忆
除了被动检索，你可以在设计提示词时主动引用Engram的记忆。例如，当你开始一个新的关于“缓存策略”的会话时，可以先让AI去查询相关历史：
“在开始讨论之前，请先查询一下我的Engram记忆库，看看我在过去的项目里关于‘Redis缓存键设计’和‘缓存穿透解决方案’都做过哪些决策，把主要的结论和理由总结给我。”
这样，AI助手就能在了解你历史决策偏好的基础上，提供更具连续性和个性化的建议，而不是每次都从零开始。这极大地提升了AI作为“长期思考伙伴”的价值。
注意事项：Engram的检索是基于语义的，所以尽量使用描述性的自然语言进行搜索，而不是精确的关键词。例如，搜索“如何处理高并发下的订单创建”比搜索“订单 并发”效果更好。另外，在项目初期决策较少时，检索结果可能不多，随着持续使用，这个知识库的价值会呈指数级增长。
5. 深入解析：知识图谱模型与高级功能
要真正玩转Engram，需要理解其底层的数据模型。这不仅能帮你更好地组织信息，也能在出问题时进行排查。
5.1 数据模型详解：六类节点与十四种关系
Engram的知识图谱由六种核心节点类型构成，它们通过十四种预定义的关系相互连接，形成了一个丰富的因果网络。
| 节点类型 | 核心字段 | 说明 |
|---|---|---|
| SESSION | id,tool,project_id,started_at | 记录一次AI会话的元数据。是决策产生的源头。 |
| PROJECT | id,name,description | 项目容器。用于归类和过滤决策。 |
| DECISION | id,summary,chosen,reasoning,confidence,epistemic_weight | 核心节点。记录最终选择、理由、信心和动态权重。 |
| COUNTERFACTUAL | id,rejected_option,rejection_reason,rejection_concern | 价值核心。记录被否决的方案、否决原因及具体担忧。 |
| OUTCOME | id,description,quality_score,observed_at | 决策实施后的结果反馈。用于强化或否定决策权重。 |
| CONCEPT | id,name,type(e.g.,technology,pattern,principle) | 概念标签。如“PostgreSQL”、“微服务”、“最终一致性”。用于分类和关联。 |
节点之间的关系定义了知识的流动和逻辑：
| 关系类型 | 起点 → 终点 | 含义 |
|---|---|---|
PRODUCED | SESSION → DECISION | 会话产生了决策。 |
BELONGS_TO | SESSION → PROJECT | 会话属于某个项目。 |
REJECTED | DECISION → COUNTERFACTUAL | 决策否决了某个反事实选项。 |
LED_TO | DECISION → OUTCOME | 决策导致了某个结果。 |
CAUSED_BY | DECISION → DECISION | 决策B是由决策A导致的（因果链）。 |
SUPERSEDES | DECISION → DECISION | 决策B取代了决策A（更新）。 |
CONTRADICTS | DECISION → DECISION | 决策B与决策A矛盾。 |
SIMILAR_TO | DECISION → DECISION | 决策B与决策A在语义上相似。 |
INVOLVES | DECISION/CONTERFACTUAL → CONCEPT | 决策或反事实涉及某个技术概念。 |
REINFORCED | OUTCOME → DECISION | （成功）结果强化了原决策的权重。 |
INVALIDATED | OUTCOME → DECISION | （失败）结果削弱了原决策的权重。 |
这个模型的美妙之处在于，它用图结构天然地表达了技术决策之间的复杂依赖、演进和冲突关系。例如，一个“选用Kafka作为消息队列”的决策，可能CAUSED_BY一个“系统需要解耦异步通信”的决策，同时它可能CONTRADICTS更早一个“使用RabbitMQ”的决策，并且INVOLVES“事件驱动架构”这个概念。
5.2 认知权重引擎的运作细节
权重引擎是让知识图谱“活”起来的关键。它是一个在后台运行的异步进程。
- 衰减计算：权重衰减不是线性的，而是指数衰减。公式
W(t) = W₀ · e^(-λt)中，λ（衰减率）在决策被提取时由LLM根据决策领域设定。例如：架构决策：λ = 0.01，半衰期很长，记忆持久。库版本选择：λ = 0.05，衰减较快。代码风格偏好：λ = 0.30，衰减非常快，琐碎记忆很快被遗忘。
- 强化机制：每当一个决策通过检索被“想起”并应用到新情境中，它的权重会增加一个固定值（如+0.05）。这模拟了“实践是检验真理的唯一标准”。
- 矛盾处理：当链接器发现两个决策存在
CONTRADICTS关系时，它会触发一个审查流程，可能会调低两个决策的权重，并在界面上给出提示，让你这个“用户”来做最终裁决。这体现了系统的人机协同理念——系统发现矛盾，人类解决矛盾。
5.3 本地优先架构与数据安全
Engram在数据安全上做了精心设计：
- 向量数据完全本地：所有文本的嵌入向量都存储在
~/.engram/chroma目录下，使用本地ChromaDB。这意味着你最敏感的会话内容语义，永远不会离开你的机器。 - 图谱数据云端（但可加密）：Neo4j AuraDB是托管的，但你可以选择AuraDB的企业版或自建Neo4j实例来获得完全控制。Neo4j本身支持传输加密和静态加密。
- 失败队列：如果网络中断或Gemini API调用失败，提取任务会被放入
~/.engram/queue/目录下的本地队列，等待网络恢复后重试，确保数据不丢失。 - 内容去重：系统会对原始会话内容计算SHA-256哈希值。完全相同的会话不会被重复处理，节省资源。
这种“敏感数据本地化，关系数据可托管”的混合架构，在隐私、性能和成本之间取得了很好的平衡。
6. 常见问题排查与实战技巧
在实际使用中，你可能会遇到一些问题。下面是我在深度使用过程中总结的常见坑点和解决方案。
6.1 安装与配置问题
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
engram install失败，提示找不到Claude/Cursor配置目录。 | 对应的AI工具未曾运行过，或安装在了非标准路径。 | 先手动启动一次Claude Code或Cursor，生成配置文件。对于非标准安装，可以手动创建对应的JSON配置文件。 |
engram start失败，报Neo4j连接错误。 | 1..env文件配置错误。2. Neo4j AuraDB实例处于休眠状态。 3. 网络问题（如代理）。 | 1. 仔细检查NEO4J_URI、USERNAME、PASSWORD，确保无空格和换行。2. 等待1-2分钟，或登录Aura控制台手动唤醒实例。 3. 检查网络连接，如有代理需在Python中配置。 |
| MCP集成后，AI工具内无法调用Engram。 | 1. MCP服务器未运行。 2. AI工具未正确加载MCP配置。 3. 端口冲突。 | 1. 运行engram status确认服务已启动。2. 重启AI工具（Claude Code/Cursor）。 3. 检查8000端口是否被占用，可在 .env中通过PORT变量修改。 |
| Gemini API调用频繁报错或超时。 | 1. API密钥无效或未启用。 2. 达到免费额度限制。 3. 区域不支持Gemini 2.5。 | 1. 在Google AI Studio检查密钥状态。 2. 查看Gemini API使用情况。 3. 确保Google Cloud项目位于支持的区域（如 us-central1）。 |
6.2 使用与性能优化
- 捕获似乎没有生效：首先检查
engram status，确保服务在运行。然后查看Engram的日志，通常位于~/.engram/logs/或通过journalctl（macOS）查看服务日志。最常见的原因是Gemini API调用失败，任务被放入了重试队列。可以运行engram retry手动重试队列中的任务。 - 搜索返回结果不相关：Engram的语义搜索质量取决于提取的摘要质量和向量模型。确保你的会话内容包含清晰的决策讨论。你也可以尝试在搜索时使用更具体、更完整的句子来描述问题，而不是零散的关键词。
- 知识图谱变得杂乱：随着决策增多，可能会出现大量琐碎的、低权重的决策干扰搜索。这是认知权重引擎设计要解决的问题。你可以定期使用CLI命令查看低权重决策，并考虑手动删除（
engram delete <id>）。未来版本可能会增加自动归档功能。 - 性能考虑：本地ChromaDB在处理成千上万个向量时依然很快。Neo4j AuraDB免费版有操作频率限制，如果出现限流，可以考虑升级到付费计划，或者将
EPHEMERAL_WEIGHT_UPDATE间隔调大（在配置中），减少实时权重更新的频率。
6.3 高级技巧与定制化
- 项目命名规范：为
--project参数建立一个清晰的命名规范，例如team-project-service（团队-项目-服务）。这能极大提升后期按项目筛选和管理的效率。 - 主动补充结果（Outcome）：决策的长期价值需要反馈来强化。当你一个决策实施一段时间后（比如上线运行了一个月），可以通过CLI或未来API，手动为该决策添加一个
OUTCOME节点，描述实际效果并打分。这能显著提升该决策在未来检索中的权重和可信度。 - 利用概念（Concept）标签：系统会自动提取决策中涉及的技术概念（如
PostgreSQL,Docker），但你也可以在决策描述中有意识地使用一些统一的关键词，帮助系统建立更准确的INVOLVES关系，形成更好的知识分类。 - 本地LLM降级：如果你非常关注隐私和成本，可以修改Engram的代码，将“分流节点”使用的Gemini Flash模型替换为本地运行的小模型（如通过Ollama运行的Llama 3.2）。虽然提取质量可能略有下降，但可以实现完全离线的运行。
Engram作为一个开源项目，其架构是模块化的。如果你对LangGraph、Neo4j或MCP协议本身感兴趣，完全可以将其作为学习这些技术的绝佳样板。它的代码结构清晰，提供了从AI交互、图数据处理到后台服务的完整实现参考。
