Zikkaron

Zikkaron（זכרון）在希伯来语中的意思是“记忆”。

你的 AI 每次在你关闭标签页后都会忘记你。你解释过的每一个架构决策、你们一起走过的每一个调试窟窿、每一次“记住，我们用 Postgres 而不是 SQLite”的纠正——全都消失。下一个会话开始时，你在自己的工具面前再次变成了陌生人。

Zikkaron 是一个为 Claude Code 构建的、基于计算神经科学的持久记忆引擎。它记住你做了什么、你的思考方式、你决定了什么事，以及为什么。它不是一堆被塞进上下文的呆板文本垃圾，而是一个活的记忆系统：会巩固、会聪明地遗忘，并在正确的时间重建正确的上下文。

26 个子系统。24 个 MCP 工具。完全运行在你自己的机器上。一个 SQLite 文件。

两分钟搞定，从此不再需要向 AI 重复自己

pip install zikkaron

添加到你的 Claude Code 配置：

{
  "mcpServers": {
    "zikkaron": {
      "command": "zikkaron"
    }
  }
}

告诉 Claude 怎么用它。把下面这段放进你的全局 ~/.claude/CLAUDE.md（你的用户主目录，不是项目目录）：

## Memory
- On every new session, call `recall` with the current project name
- Before starting any task, call `get_project_context` for the current directory
- After completing significant work, call `remember` to store decisions and outcomes

或者干脆让 Zikkaron 自己来处理。每次启动时，它都会通过 sync_instructions 自动把 ~/.claude/CLAUDE.md 同步成最新指令。你只需设置一次，之后就再也不用去管它了。

Related MCP server: memory-mcp

这到底是什么感觉

周一。 你花了一个小时调试一个棘手的 auth token 竞态条件。Claude 帮你把它追踪到 Redis 和你的 JWT 配置之间的 TTL 不匹配。你修复了它，Claude 记住了这个记忆。

周四。 有用户报告间歇性登出。你在同一个项目里打开 Claude Code，甚至还没开始描述这个 bug，Claude 就回想起了周一的 Redis TTL 修复，判断它是否与此相关，还问：你后来加的中间件有没有处理“Redis 在会话中途重启”这个边缘情况。

这就是区别。不是“你的历史对话记录在这里”，而是真正的记忆回溯。你的工具理解你正在构建的东西的“形状”，而不只是上一次输入过的文字。

真正好用的检索

我们按照 LoCoMo（Maharana et al., ACL 2024）这个长对话记忆的标准基准来测试 Zikkaron。10 段对话，1,986 个问题，从简单的事实查询、多跳推理，到专门让人翻车的对抗性误导问题，全都覆盖了。

关键在于，查询时没有任何大语言模型（LLM）在运行。没有 API 调用，没有数十亿参数的模型。只有一个 22MB 的嵌入模型、一个 SQLite 文件，以及一群神经科学算法在干重活。多数能打出这种数字的体系，都需要在流程里放一个 GPT-4。Zikkaron 靠 Hopfield 能量打分、传播激活和 Cross-Encoder 重排就做到了。

BEAM：一千万个 token 的对话，一套记忆系统

BEAM（Tavakoli et al., ICLR 2026）是目前最难的长程记忆基准。10 段对话，每段横跨一千万个 token；200 个探测问题覆盖 10 种记忆能力，其中三个是此前任何模型都没有测评过的：矛盾消解、事件排序和指令遵循。

论文中所有系统在此规模下都会崩盘。论文里报告出的最好成绩（基于 Llama-4-Maverick 的 LIGHT 框架）只有 0.266。大多数能力在落到 1 千万 token 时都会降到接近 0。上下文窗口方法根本装不下，RAG 方法又会被噪声吞掉。

Zikkaron 要比照下能拿到 0.404 总成绩，比 ICLR 2026 论文里的最好成绩提高了 52%。

十项能力里，七项打败了论文中的 State-of-the-Art。提升最大的正是结构化记忆最该帮上忙的地方：矛盾解析（+219%）、时间推理（+175%）、知识更新（+73%）。在这些点上，论文里几乎所有系统都接近零分，因为它们若要跟踪事实的变化和事件的先后，就需要额外机制。而 ZHOP 的热力学衰减、重固化（reconsolidation）和时间 metadata 是把这些能力原生内建进去的。

LIGHT 获胜的那三项——abstention、事件排序、摘要生成——确实反映了系统真实存在的局限性。Abstention 需要知道“没有信息”也是一种信息，而 LIGHT 里的 scratchpad 会显式记录自己已经议论过哪些东西，这一点很容易利用。事件排序需要的是严格的 chronological 顺序，而不仅找到正确的事件。做摘要需要同时找出多个源文本段落，我们的检索输出头只覆盖了相关片段的一部分。

一个重要的 caveat：BEAM 论文的 baseline 用 GPT-4.1-nano 作为 reader 模型；我们用的是 Claude Opus 4.6，它要强很多。那个指令遵结果为 (0.750) 配合检索 MRR 只有 0.086），说明 reader 模型本身的质量对问答分数有独立影响。而我们的 retrieval metrics（MRR 0.422, Recall@10 0.353）是不带模型 bias 的，可直接与论文 of baselines 相比。

评估配置：BEAM-10M 的数据集，10 个会话，200 个问题；使用与论文 RAG 模式一致的 pair-chunk 摄入方式，句子按 rubric 被切割成 binary nugget 并用 int() 转换（跟论文评估代码一致）；按论文使用 Kendall tau-b 通过 scipy 处理事件排序；每次会话创建全新的数据库。

海马回放：让上下文在压缩中幸存

这里有个 everyone 不爱说的问题：Claude Code 的窗口是 200k /1M 个 token。长会话中，当窗口满时，它会 压缩 端口：合理总结旧消息、删除工具输出、把指令改成语义更抽象的说法。很多细节的细微差别就这样蒸发掉。你早先进程中的决定，最后会变成模糊的摘要。

海马回放（Hippocampal Replay）就是为了解决这个问题。与大脑在睡眠时快速回放重要经历来强化长期记忆的原理相同，它把上下文压缩被视为那个“睡眠时机”，并在 Claude “醒来”之后回放最重要的一段。

运行原理：

在压缩发生前，一个 hook 会被触发。Zikkaron 会排空你当前的上下文：你在做什么、打开了哪些文件、你已经做了什么决定、哪些错误尚未解决。所有这些都会作为一个 checkpoint 存下来。

压缩完成之后，第二个 hook 被触发。Zikkaron 会智能地重建上下文。它不会一次性全部回填，而是把正确的内容组装回来：最新 checkpoint、你曾经明确标注的 critical facts、项目里现在最“热”的记忆，以及根据你的使用模式通过预测得到的下一步可能需要的内容。

你也可以明确写出哪些是最重要的：

Tool: anchor
  content: "We're using the event-sourcing pattern. All state changes go through the event bus."
  reason: "Architecture constraint"

Anchored 记忆会被最大程度保护。它们无论如何都不会被压缩掉。

每个项目只需要一次性设置：

Tool: install_hooks
  project_directory: "/path/to/your/project"

之后一切都变成自动的。你不需要记挂，也不用手动调用。hook 触发，上下文排放，上下文还原。你那些很长的会话，就会自然“工作正常”。

零碎片记忆（v1.3.0）

旧版还是缺失。例如你在一件任务上做了一步，一行一行推进，而 Zikkaron 的写入门槛会把其中了一半扔进“trash”——因为每个宝宝小步骤跟上一处相比都看起来“没什么可惊讶的”。你会得出一个可能是架构级的结论，可慢慢地却进入去了一个写实的里面。回到一个新会话，Claude 根本不知道你刚才在干嘛。

v1.3.0 把这些都修好了：

自适应写入门（Adaptive write gate）。 系统现在会跟踪你最近保存的 10 条记忆。当它看到你明显正在做同一件事——同一目录、同一时间段、类似内容——它就会降低惊讶（surprisal）阈值，这样每一步的进展也能录下来。这道闸门为了阻止噪音，但不会再挡住你的实际工作。

决策自动保护（Decision auto-protection）。 当你说“决定用 Redis 替换 Memcached”或者“宁愿用 event-sourcing 而不是 CRUD”这类话时，Zikkarron 会识别出决策模式，并自动把它标为 protected。受保护的记忆不会被压缩，也不会快速衰减。你的决策寿命会超过会话本身。

自动动作捕获（automatic action capture）。 Claude 每完成一次 tool call，都会触发一个 PostToolUse hook。文件编辑、bash 命令、搜索……全都会被捕获到轻量的动作列表里。之后由 consolidation daemon 持续处理，把它们变成真正 memory entry。对例行的工作，你不需要调用 remember——系统自己会知道。

会话上下文注入（session context injection）。 每个新会话开启时都会触发 SessionStart hook，把你的项目上下文（最新热记忆、anchored facts、最近的 actions、最后一个 checkpoint）直接注入 Claude 的上下文窗口——也许这，Claude 每一轮都像从你才结束的地方开始一样。

迷你 checkpoint（micro-checkpointing）。 不再每 50 个工具调用才打点，现在它一遇到“重要事件”就保存 checkpoint：比如遇到报错、做出决策、出现高惊讶信息。关键转移状态在发生的那一刻就被记录下来了。

会话连贯性（session coherence）。 在 4 小时以内创建的旧记忆，会获得一个随时间线性衰减的 heat bonus。这样你未来再也不会遇见那个场景：我就在十分钟前刚把这件事告诉你，你现在却问。

所有这些 hook 在 stdio 和 HTTP transport 模式下都能工作——它们直接操作 SQLite 数据库，不需要中间的 server。

项目冷启动：不再从零开始

Zikar-on 会把记忆在各次会话中慢慢积累。这对正在持续进行的项目很合适，但如果你是在一个已经做了一年的 library（外部库）上初次装它呢？ 大概在你数十个 session 之后，Claude 才会对项目内容有足够有意义的覆盖。而到了那一天，你已经把同样的话说了五十遍。

seed_project 解决了这个问题。只需一次调用，Zikkaron 就会扫描你的整个项目，并从结构、配置、文档、CI/CD、入口点和各组件摘要中创建基础记忆。Claude 在下一个会话开始时就已经知道你的项目是什么、用什么构建的、以及如何组织的。

# CLI
zikkaron seed /path/to/your/project

# Preview without storing
zikkaron seed /path/to/your/project --dry-run

或者从 Claude Code 中作为 MCP 工具调用它：

Tool: seed_project
  directory: "/path/to/your/project"

它提取的内容：

• 项目概览 — 名称、技术栈、文件数量、目录树

• 配置文件 — package.json、pyproject.toml、Cargo.toml、go.mod 以及 15 多种其他格式。通过正确的方式解析（TOML 用 tomllib，JSON 用 json），而不是正则表达式抓取。依赖、脚本、工作区、构建后端——全部提取。

• 文档 — README、ARCHITECTURE、CONTRIBUTING、CLAUDE.md、CHANGELOG

• CI/CD — GitHub Actions、GitLab CI、Jenkins、Travis、Azure Pipelines

• 入口点 — main.*、index.*、app.*、server.*、__main__.py

• 各组件摘要 — 支持 monorepo。通过查找嵌套配置文件（packages/web/package.json、services/api/Cargo.toml）来检测子项目边界，而不仅仅是顶层目录

专为重复运行而设计。 重新播种会干净地替换旧的种子记忆，而不是追加到它们后面。项目演进后，你重新播种，记忆就会反映当前状态。所有种子记忆都标记为 _seed 以便识别。

热度差异化。 并非所有种子记忆都同等重要。项目概述和文档的初始热度（0.85-0.9）高于组件文件列表（0.5）。Claude 会优先呈现重要内容。

LongMemEval

我们运行了完整的 LongMemEval 基准测试（Wu 等人，ICLR 2025），这是当前评估聊天助手长期交互记忆的标准。500 个人工策划的问题，涵盖六个类别，每个问题嵌入在约 40 个会话的对话历史中（约 115k tokens）。该基准测试测试了 LoCoMo 没有覆盖的内容：能否回忆助手说过的话（而不仅仅是用户）、能否追踪信息随时间的变化、能否知道自己不知道什么、以及能否跨数周间隔的会话进行推理。

论文中报告的最佳检索命中率为该数据集上的 78.4% Recall@10。Zikkaron 在检索循环中没有任何 LLM 的情况下达到了 96.7%。

按类别划分的检索结果：

知识更新获得了完美的 MRR，因为基于热度的衰减自然会将新信息推到同一事实的旧版本之上。这不是为基准测试设计的。这只是热力学模型的自然工作方式。

时间推理是最难的类别，也是我们 MRR 最低的类别，为 0.902，但这仍然意味着正确的记忆通常在前两个结果中。像"我几周前参加了 X"这样的问题需要与会话时间戳匹配，我们基于嵌入的检索通过直接嵌入在记忆内容中的时间元数据来处理这一点。

完整的 QA 评估（使用 Claude 同时作为阅读器和评判者）达到了 75.6% 的总体准确率，在知识更新（85.9%）和助手回忆（94.6%）方面表现突出。多会话推理（54.9%）是主要差距，但这是阅读器综合问题，不是检索问题。对于多会话问题，我们在 95.8% 的情况下检索到了正确的会话。阅读器只需要做更多工作来连接跨会话的信息。

基准配置：LongMemEval_S 变体，按轮次进行记忆分解，每个问题使用全新数据库，500 个问题端到端评估。

底层科学原理

Zikkaron 不像数据库存储行那样存储记忆。它更像大脑处理经验那样处理记忆。

记忆有温度。 每条记忆开始时是热的。如果你持续访问它，它就会保持热度。如果不访问，它就会冷却。低于阈值时，它会压缩：先压缩为要点，然后压缩为标签，最终完全消失。这不是缺陷。这是率失真最优遗忘，与大脑决定什么值得保留的数学框架相同。重要记忆能抵抗压缩。令人惊讶的记忆会获得热度提升。无聊、冗余的记忆会悄悄消失。

存储有守门人。 并非所有内容都值得被记住。Zikkaron 维护一个关于它已知内容的预测模型，只存储违反其预期的信息。同一件事告诉它两次，写入门会阻止第二次尝试。这是预测编码：与你的新皮层过滤感官输入的机制相同。只有预测误差才能通过。

检索会改变记忆。 当你在新上下文中回忆一段记忆时，它不会被动地交还给你。它会将检索上下文与存储上下文进行比较，如果存在足够的不匹配，它会重新整合：更新记忆以反映当前的真实情况。严重不匹配会归档旧版本并创建新版本。这是真实的神经科学。Nader 等人在 2000 年表明，被检索的记忆会变得不稳定，可以被重写。你的代码库在演进，Zikkaron 对它的记忆也在演进。

记忆竞争空间。 一个 engram 槽池，每个槽都有一个兴奋度分数，使用时飙升，随时间衰减。当新记忆到达时，它会进入最兴奋的槽。同一槽中的记忆在时间上被链接，创建相关体验的链条，即使它们的内容毫无共同之处。这模拟了真实神经元如何通过 CREB 依赖的兴奋性分配 engram。

后台整合像睡眠一样运行。 当你空闲时，一个 astrocyte 守护进程会醒来并处理最近的体验。它提取实体和关系，构建知识图谱，合并近似重复项，发现因果链，并运行"梦境回放"，其中随机记忆对进行比较并产生新的连接。四个领域专用进程以不同速率处理不同类型知识：代码结构、架构决策、错误模式和依赖关系。

认知地图组织一切。 后继表示构建了一个概念空间的 2D 地图，其中在相似上下文中被访问的记忆聚集在一起，即使它们的内容完全不同。调试记忆聚集在其他调试记忆附近。架构决策聚集在一起。导航这张地图，你会发现关键词搜索永远无法发现的关联知识。

全部 24 个工具

架构

一切都在本地运行。一个 SQLite 数据库，使用 WAL 模式、FTS5 全文搜索和 sqlite-vec 进行近似最近邻向量搜索。

26 个子系统组织为五层：

高级设置

从源码构建

git clone https://github.com/amanhij/Zikkaron.git
cd Zikkaron
pip install -e .

SSE 传输

以持久化后台服务器方式运行，而非 stdio：

zikkaron --transport sse

然后将 Claude Code 指向该 URL：

{
  "mcpServers": {
    "zikkaron": {
      "type": "sse",
      "url": "http://127.0.0.1:8742/sse"
    }
  }
}

默认端口为 8742。使用 --port 覆盖。数据库默认路径为 ~/.zikkaron/memory.db，使用 --db-path 覆盖。

配置

所有设置均使用 ZIKKARON_ 环境变量前缀：

完整列表见 zikkaron/config.py。

测试

python -m pytest zikkaron/tests/ -x -q

998 个测试分布在 34 个测试文件中，覆盖每个子系统。

参考文献

Ramsauer et al. "Hopfield Networks is All You Need" (ICLR 2021, arXiv:2008.02217)

Nader, Schafe, LeDoux. "Fear memories require protein synthesis in the amygdala for reconsolidation after retrieval" (Nature 406, 2000)

Osan, Tort, Bhatt, Amaral. "Three outcomes of reconsolidation" (PLoS ONE, 2011)

McClelland, McNaughton, O'Reilly. "Why there are complementary learning systems in the hippocampus and neocortex" (Psychological Review 102, 1995)

Sun et al. "Organizing memories for generalization in complementary learning systems" (Nature Neuroscience 26, 2023)

Stachenfeld, Botvinick, Gershman. "The hippocampus as a predictive map" (Nature Neuroscience 20, 2017)

Whittington et al. "The Tolman-Eichenbaum Machine" (Cell 183, 2020)

Spirtes, Glymour, Scheines. Causation, Prediction, and Search (MIT Press, 2000)

Kanerva. Sparse Distributed Memory (MIT Press, 1988)

Frady, Kleyko, Sommer. "Variable Binding for Sparse Distributed Representations" (IEEE TNNLS, 2022)

Toth et al. "Optimal forgetting via rate-distortion theory" (PLoS Computational Biology, 2020)

Josselyn, Frankland. "Memory allocation: mechanisms and function" (Annual Review Neuroscience 41, 2018)

Rashid et al. "Competition between engrams influences fear memory formation and recall" (Science 353, 2016)

Zhou et al. "MetaRAG: Metacognitive Retrieval-Augmented Generation" (ACM Web, 2024)

许可证

MIT