Zikkaron

Zikkaron

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

每次关闭标签页，你的 AI 就会忘记你。你解释过的每个架构决策、你们一起排查过的每个棘手问题，以及每次“记住，我们用的是 Postgres，不是 SQLite”的纠正，全都消失了。下一次会话开始时，你面对自己的工具却像个陌生人。

Zikkaron 是一款基于计算神经科学、为 Claude Code 打造的持久记忆引擎。它会记住你做过什么、如何思考、做了什么决定以及原因。它不是一堆被塞进上下文的纯文本，而是一个鲜活的记忆系统，能够整合记忆、智能遗忘，并在恰当的时机还原正确的上下文。

26 个子系统。24 个 MCP 工具。完全在你的设备上运行。一个 SQLite 文件。

两分钟，让你再也不用重复说明

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 与最新说明同步。只需设置一次，之后就不用再操心。

实际用起来是什么感觉

星期一。 你花了一个小时排查一个棘手的身份验证令牌竞态问题。Claude 帮你追查，发现问题出在 Redis 与 JWT 配置的 TTL 不匹配。你修复了问题。Claude 保存了这段记忆。

星期四。 一位用户报告说会间歇性地退出登录。你在同一个项目中打开 Claude Code。还没等你描述问题，Claude 就想起了星期一对 Redis TTL 的修复，检查问题是否相关，并询问你添加的中间件能否处理 Redis 在会话中途重启这一边缘情况。

这就是区别。不是“这是你的对话历史”。而是真正的回忆。你的工具理解你所构建内容的脉络，而不只是你上次输入的文字。

真正有效的检索

我们使用 LoCoMo（Maharana 等人，ACL 2024）对 Zikkaron 进行了测试。这是长对话记忆的标准基准测试，包含 10 段对话、1,986 个问题，涵盖简单的事实查询、多跳推理，以及旨在让你掉进陷阱的对抗性刁钻问题。

	Zikkaron	含义
Recall@10	86.8%	正确的记忆几乎每 10 次就有 9 次会出现在前 10 条结果中
MRR	0.708	正确答案通常是第一条或第二条结果
Single-hop MRR	0.757	对事实类问题，几乎总能一次命中
Temporal MRR	0.712	对“X 是什么时候发生的？”这类查询，具备出色的时间感知能力

关键在于，查询时没有大模型运行。没有 API 调用。没有十亿参数模型。只有一个 22MB 的嵌入模型、一个 SQLite 文件，以及一系列承担繁重计算工作的神经科学算法。大多数达到这种水平的系统都需要 GPT-4 参与其中。Zikkaron 则通过 Hopfield 能量评分、扩散激活和交叉编码器重排序实现了同样的效果。

BEAM：1,000 万个对话 token，一个记忆系统

BEAM（Tavakoli 等人，ICLR 2026）是目前最难的长期记忆基准。包含 10 段对话，每段跨度达 1,000 万个 token。200 个探测问题涵盖 10 种记忆能力，其中包括此前没有任何基准测试过的三种能力：矛盾消解、事件排序和指令遵循。

论文中的每个系统在这个规模下都表现崩溃。报告的最佳结果（运行于 Llama-4-Maverick 上的 LIGHT 框架）为 0.266。大多数能力在 1,000 万个 token 时都降至接近零。上下文窗口方案无法容纳这么多内容。RAG 方案则淹没在噪声中。

Zikkaron 的总体得分为 0.404，比 ICLR 2026 论文中的最佳系统高出 52%。

能力	Zikkaron	LIGHT（最佳）	结果
指令遵循	0.750	0.500	+50%。即使检索结果不够理想，Claude Opus 也能很好地阅读
信息提取	0.650	0.375	+73%。从 1 万条记忆中检索具体事实
知识更新	0.650	0.375	+73%。热度衰减能呈现事实的最新版本
偏好遵循	0.642	0.483	+33%。跨会话跟踪用户偏好
弃答	0.450	0.750	没有草稿板时，很难知道自己不知道什么
摘要生成	0.216	0.277	摘要生成需要同时获取许多源段落
多会话推理	0.195	0.135	+44%。关联相距较远的轮次中的证据
时间推理	0.175	0.075	+133%。X 相对于 Y 是什么时候发生的？
矛盾消解	0.163	0.050	+226%。检测相隔数千轮的冲突陈述
事件排序	0.150	0.266	检索能找到事件，但按时间顺序排列很难
总体	0.404	0.266	+52%

10 种能力中有 7 种超越了已发表的最先进水平。提升最大的正是结构化记忆最能发挥作用的能力：矛盾消解（+226%）、时间推理（+133%）和知识更新（+73%）。论文中的每个系统在这些能力上的得分都接近零，因为上下文窗口方案没有机制来跟踪事实如何变化或事件何时发生。Zikkaron 的热力学衰减、记忆再巩固和时间元数据则能原生处理这些问题。

LIGHT 胜出的三种能力（弃答、事件排序和摘要生成）体现了实际存在的局限。弃答需要识别信息缺失的情况，而 LIGHT 的草稿板会明确跟踪已经讨论过的内容，因此对此有所帮助。事件排序要求完美地按时间顺序排列，而不只是检索到正确的事件。摘要生成需要同时检索许多源段落，而我们的检索预算只能覆盖相关内容的一小部分。

需要注意的一点是：BEAM 论文的基线使用 GPT-4.1-nano 作为阅读模型。我们使用的是能力强得多的 Claude Opus 4.6。指令遵循结果（得分为 0.750，检索 MRR 仅为 0.086）表明，阅读模型的质量会独立于检索质量影响问答得分。我们的检索指标（MRR 0.422，Recall@10 0.353）与模型无关，可以直接与论文中的基线进行比较。

基准配置：BEAM-10M 划分、10 段对话、200 个问题、与论文 RAG 模式一致的成对分块摄取、使用 int() 转换并与论文评估代码一致的逐评分标准二元要点计分、使用 scipy 计算事件排序的 Kendall tau-b，以及每段对话使用全新数据库。

海马重放：在压缩后依然留存的上下文

有个问题没人提起。Claude Code 的上下文窗口有 200k/1M 个 token。在长时间会话中，窗口填满后就会进行压缩：总结较早的消息、删去工具输出、转述你的指令。重要的细节会逐渐消失。你在对话早期确定的决策，也会化为含糊的摘要。

海马重放解决了这个问题。它以神经科学中的一种现象命名：大脑会在睡眠期间重放重要经历，将其巩固为长期记忆。它将上下文压缩视为“睡眠”，并在 Claude“醒来”时重放重要内容。

工作原理：

压缩开始前，会触发一个钩子。Zikkaron 会提取当前上下文中的内容：你正在做什么、打开了哪些文件、做出了哪些决策、还有哪些错误尚未解决。所有这些内容都会保存为检查点。

压缩后，会触发第二个钩子。Zikkaron 会智能地重建你的上下文。它不会把所有内容原封不动地塞回来，而是组合出合适的内容：最新的检查点、你标记为关键的事实、最相关的项目记忆，以及根据你的使用模式对接下来所需内容做出的预测。

你也可以明确指出哪些内容很重要：

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

锚定记忆会得到最高级别的保护。无论如何，它们都能在压缩后留存。

每个项目只需设置一次：

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

之后，一切都会自动完成。你不必操心，也不必手动调用任何内容。钩子会触发，上下文会被提取，也会被还原。你的长时间会话就这样……顺畅运行。

零间隙记忆（v1.3.0）

之前的版本仍然存在间隙。你可能花一小时处理某件事，逐步取得进展，但 Zikkaron 的写入门会挡掉其中一半，因为相较于上一步，每个小步骤看起来都“不出意料”。你可能做出关键的架构决策，但它会逐渐衰减成一段简述。开启新会话时，Claude 可能完全不知道你刚才在做什么。

v1.3.0 解决了所有这些问题：

自适应写入门。 系统现在会追踪最近存储的 10 条记忆。当你明显在处理同一项任务时——目录相同、时间范围相近、内容相似——系统会降低意外性阈值，让渐进式进展也能被记录下来。写入门仍会拦截噪声，只是不再挡住你的工作。

决策自动保护。 当你说“决定使用 Redis 而不是 Memcached”或“选择事件溯源模式而不是 CRUD”时，Zikkaron 会检测决策模式，并自动将其标记为受保护记忆。受保护记忆永远不会被压缩，也不会快速衰减。你的决策会比会话留存得更久。

自动捕获操作。 每次 Claude 调用工具后，都会触发 PostToolUse 钩子。文件编辑、bash 命令、搜索等操作都会被记录到轻量级操作日志中。整合守护进程会定期将这些内容处理成真正的记忆。日常工作不必调用 remember，系统会自动记录。

会话上下文注入。 每次新会话开始时，都会触发 SessionStart 钩子，并将项目上下文直接注入 Claude 的上下文窗口，其中包括高热度记忆、锚定事实、近期操作和上一个检查点。Claude 从每次会话开始就知道你之前在做什么。

微型检查点。 系统不再每调用 50 次工具才创建检查点，而是在发生重要事件时自动创建：遇到错误、做出决策或出现高度意外的信息。关键状态转变会在发生时立即记录。

会话连贯性。 最近 4 小时内创建的记忆会获得热度加成，并线性衰减。你再也不会遇到“我 10 分钟前刚告诉过你”这种情况。

所有钩子都支持 stdio 和 HTTP 传输模式——它们会直接访问 SQLite 数据库，无需与服务进行通信。

项目初始化：解决冷启动问题

Zikkaron 会在多个会话中自然积累记忆。这对持续进行的工作很有帮助，但如果你在一个已经开发了一年的代码库上安装它呢？你得花上几十个会话，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 多种文件。使用适当的方式解析（通过 tomllib 解析 TOML，通过 json 解析 JSON），而不是用正则表达式抓取。依赖项、脚本、工作区、构建后端等内容都会被提取。
• 文档 — README、ARCHITECTURE、CONTRIBUTING、CLAUDE.md、CHANGELOG
• CI/CD — GitHub Actions、GitLab CI、Jenkins、Travis、Azure Pipelines
• 入口点 — main.*、index.*、app.*、server.*、__main__.py
• 各组件摘要 — 支持感知单体仓库结构。通过查找嵌套配置文件（packages/web/package.json、services/api/Cargo.toml）来检测子项目边界，而不只是检查顶层目录

专为重复运行而设计。 重新初始化时会干净地替换旧的初始化记忆，而不是在其后追加。随着项目演进，你可以重新初始化，记忆也会反映当前状态。所有初始化记忆都会标记为 _seed，便于识别。

热度差异化。 初始化生成的记忆并非都一样。项目概览和文档的初始热度更高（0.85-0.9），而组件文件列表的初始热度较低（0.5）。Claude 会优先呈现重要内容。

LongMemEval

我们运行了完整的 LongMemEval 基准测试（Wu 等人，ICLR 2025）。这是目前评估聊天助手长期交互记忆能力的标准。测试包含 500 个由人工整理的问题，涵盖六个类别，每个问题都嵌入约 40 段对话历史（约 115k 个 token）。该基准测试评估了 LoCoMo 未涉及的能力：能否回忆助手说过的话（而不只是用户说过的话）、能否追踪信息随时间发生的变化、能否识别自身所不知道的信息，以及能否跨越相隔数周的会话进行推理。

	Zikkaron	含义
Recall@10	96.7%	几乎每个问题的正确记忆都会出现在前 10 个结果中
MRR	0.945	返回的第一个结果几乎总是正确答案
Knowledge Update MRR	1.000	用户信息发生变化时，Zikkaron 总会优先显示最新版本

该论文报告的最佳检索结果是在此数据集上达到 78.4% 的 Recall@10。Zikkaron 无需在检索流程中使用任何 LLM，即可达到 96.7%。

各类别检索结果：

类别	MRR	Recall@10
单会话（用户）	0.973	1.000
单会话（助手）	0.964	0.964
单会话（偏好）	0.810	0.967
多会话推理	0.966	0.958
时间推理	0.902	0.955
知识更新	1.000	0.979

知识更新类别取得了完美的 MRR，因为基于热度的衰减会自然地将新信息排在同一事实的旧版本之前。这并非为该基准测试专门设计，而是热力学模型的自然表现。

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

完整问答评估（使用 Claude 同时作为阅读器和评判者）总体准确率达到 75.6%，其中知识更新（85.9%）和助手回忆（94.6%）表现突出。多会话推理（54.9%）是主要差距所在，这属于阅读器综合信息的问题，而非检索问题。对于多会话问题，我们有 95.8% 的概率检索到正确会话。阅读器只需进一步整合这些会话中的信息。

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

其背后的科学

Zikkaron 存储记忆的方式并不像数据库存储数据行。它处理记忆的方式更像大脑处理经历。

记忆有温度。 每条记忆一开始都是热的。如果你持续访问它，它就会保持热度；如果不再访问，它就会冷却。温度低于阈值后，记忆就会压缩：先变成要点，再变成标签，最终彻底消退。这不是 bug，而是率失真意义上的最优遗忘——大脑用来判断哪些内容值得保留的，同一套数学框架。重要的记忆能抵抗压缩。令人惊讶的记忆会获得额外热度。无聊、冗余的记忆则会悄然消失。

存储有把关机制。 不是所有内容都值得记住。Zikkaron 会维护一个关于自己已有知识的预测模型，只存储违背其预期的信息。告诉它同一件事两次，写入闸门就会拦截第二次尝试。这就是预测编码：新皮层用来过滤感官输入的同一套机制。只有预测误差才能通过。

检索会改变记忆。 在新的上下文中回忆一条记忆时，Zikkaron 不会只是被动地把它交还给你。它会比较检索上下文与存储上下文；如果两者差异足够大，就会进行再巩固：更新记忆，以反映当前的真实情况。差异严重时，它会归档旧版本并创建新版本。这是神经科学中的真实现象。Nader 等人在 2000 年证明，被提取的记忆会变得不稳定，因此可以被改写。你的代码库在不断演进，Zikkaron 对它的记忆也一样。

记忆会争夺空间。 一个由印迹槽组成的池中，每个槽都有一个兴奋性分数，使用时会飙升，随后随时间衰减。新记忆到来时，会被分配到兴奋性最高的槽。同一槽中的记忆会在时间上关联起来，即使它们的内容毫不相关，也会形成相关经历的链条。这模拟了真实神经元如何通过 CREB 依赖的兴奋性分配记忆印迹。

后台巩固像睡眠一样运行。 当你处于空闲状态时，星形胶质细胞守护进程会醒来并处理近期经历。它会提取实体和关系、构建知识图谱、合并近似重复项、发现因果链，并进行“梦境重放”，随机比较记忆对，从而产生新的关联。四种专精于不同领域的进程以不同速率处理不同类型的知识：代码结构、架构决策、错误模式和依赖关系。

认知地图将一切组织起来。 后继表示会构建一张概念空间的二维地图；即使内容完全不同，在相似上下文中被访问的记忆也会聚集在一起。调试记忆会聚集在其他调试记忆附近，架构决策也会聚集在一起。沿着这张地图探索，就能找到关键词搜索永远不会呈现的相关知识。

全部 24 个工具

工具	用途
remember	通过预测编码写入门控存储记忆
recall	通过热度加权排序进行多信号检索
forget	删除记忆
validate_memory	根据当前文件状态检查记忆是否过时
get_project_context	获取某个目录的热门记忆
consolidate_now	强制执行一次整合周期
memory_stats	查看所有子系统的系统统计信息
rate_memory	提供有用性反馈，用于元记忆跟踪
recall_hierarchical	在指定抽象层级查询分形层级结构
drill_down	深入浏览记忆集群
create_trigger	设置在匹配上下文时触发的前瞻性触发器
get_project_story	项目的自传式叙述
add_rule	用于筛选和重新排序的神经符号约束
get_rules	列出有效规则
navigate_memory	通过后继表示遍历概念空间
get_causal_chain	获取某个实体的因果祖先和后代
assess_coverage	评估知识覆盖情况并识别缺口
detect_gaps	查找孤立实体、过时区域和缺失连接
checkpoint	为压缩恢复快照保存工作状态
restore	通过海马体回放在压缩后重建上下文
anchor	将关键事实标记为不受压缩影响
install_hooks	启用自动捕获、上下文注入和压缩恢复钩子
sync_instructions	使用最新的 Zikkaron 功能更新 CLAUDE.md
seed_project	通过一次扫描为现有项目初始化记忆

架构

所有操作都在本地运行。使用单个 SQLite 数据库，并启用 WAL 模式、FTS5 全文搜索和 sqlite-vec 近似最近邻向量搜索。

26 个子系统分为五层：

核心存储与检索

模块	作用
storage.py	SQLite WAL 引擎、16 张表、FTS5 索引、sqlite-vec ANN 搜索
embeddings.py	Sentence-transformer 编码（all-MiniLM-L6-v2）、批量操作
retrieval.py	四信号融合：向量相似度、FTS5 BM25、知识图谱 PPR、扩散激活
models.py	完整类型层次结构的 Pydantic 数据模型
config.py	使用 ZIKKARON_ 前缀、基于环境变量的配置

记忆动态

模块	作用
thermodynamics.py	热度、意外度、重要性、情绪效价、时间衰减
reconsolidation.py	易变检索，依据 Nader 等人（2000 年）提出的机制，具有三种结果
predictive_coding.py	写入门控，通过预测误差过滤冗余
engram.py	具有 CREB 类兴奋性的竞争式槽位分配
compression.py	三个压缩级别下的率失真最优遗忘
staleness.py	通过 SHA-256 哈希比较监控文件变更

巩固与组织

模块	作用
consolidation.py	用于定期巩固的后台星形胶质细胞守护进程
astrocyte_pool.py	面向代码、决策、错误、依赖项的领域专用工作进程
sleep_compute.py	梦境重放、Louvain 社区检测、时间压缩
fractal.py	支持逐层深入导航的多尺度记忆树
cls_store.py	互补学习系统：快速情景存储 + 慢速语义存储

知识结构

模块	作用
knowledge_graph.py	采用个性化 PageRank 的类型化实体关系图
causal_discovery.py	基于编码会话数据构建因果 DAG 的 PC 算法
cognitive_map.py	用于基于导航进行检索的后继表示
narrative.py	合成项目自传故事
curation.py	合并重复项、检测矛盾、建立交叉引用链接

前沿能力

模块	作用
hopfield.py	现代连续 Hopfield 网络（Ramsauer 等人，2021 年）
hdc_encoder.py	在 10,000 维双极空间中进行超维计算
metacognition.py	自我评估知识覆盖情况并检测缺口
rules_engine.py	硬性与软性神经符号约束
crdt_sync.py	通过 CRDT 实现多 Agent 记忆共享
prospective.py	针对目录、关键词、实体或时间的未来导向触发器
sensory_buffer.py	用于捕获原始会话内容的情景缓冲区
restoration.py	海马体重放引擎，增强上下文压缩后的恢复能力
seed.py	扫描项目并引导建立基础记忆

高级设置

从源代码安装

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

SSE 传输

作为持久后台服务运行，而不是使用标准输入输出：

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_PORT	8742	服务端口
ZIKKARON_DB_PATH	~/.zikkaron/memory.db	数据库位置
ZIKKARON_EMBEDDING_MODEL	all-MiniLM-L6-v2	Sentence-Transformer 模型
ZIKKARON_DECAY_FACTOR	0.95	每个巩固周期的热度衰减
ZIKKARON_COLD_THRESHOLD	0.05	记忆成为归档候选项的热度阈值
ZIKKARON_WRITE_GATE_THRESHOLD	0.4	通过写入门控所需的最低惊奇度
ZIKKARON_HOPFIELD_BETA	8.0	Hopfield 网络的锐度
ZIKKARON_SR_DISCOUNT	0.9	后继表征折扣因子
ZIKKARON_COGNITIVE_LOAD_LIMIT	4	活跃上下文块数量上限（Cowan 的 4 +/- 1）

完整列表见 zikkaron/config.py。

测试

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

34 个测试文件中共有 998 项测试，覆盖所有子系统。

参考资料

实现所依据的论文和书籍

Ramsauer 等：《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 等：《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 等：《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 等：《Optimal forgetting via rate-distortion theory》（PLoS Computational Biology，2020）

Josselyn、Frankland：《Memory allocation: mechanisms and function》（Annual Review Neuroscience 41，2018）

Rashid 等：《Competition between engrams influences fear memory formation and recall》（Science 353，2016）

Zhou 等：《MetaRAG: Metacognitive Retrieval-Augmented Generation》（ACM Web，2024）

许可证

MIT