realMemory

面向 LLM 代理的持久记忆层，支持持续学习：一个本地 “海马体”式记忆，无需重新索引即可写入，通过痕迹动态遗忘， 并在“睡眠”期间将情节整合为语义。

状态：v0.4 — 所有进程共享单一 SQLite 存储，全局/项目 记忆作用域，混合 FTS5 搜索，阈值已在真实文本上校准。

核心思想

LLM 保持冻结（“皮层”）。realMemory 是一个独立可变的模块 （“海马体”）：

• 新颖性门控写入：已知事实被强化，相关事实被关联， 全新事实分配新的痕迹。改写永远不会堆积。

• 共享 + 按项目记忆：每个痕迹都带有作用域（global 或 项目名称）；回忆会看到当前项目加上 global，绝不混用上下文。

• 基于痕迹动态的遗忘：每个痕迹的保留度指数衰减， 强化延长其寿命，得到充分强化的情节会提升为语义痕迹（慢衰减）。 遗忘曲线是突触的属性，而不是定时任务。

• 免费的联想图：一起被回忆的内容会通过可塑性 （类似 STDP 的规则）绑定 —— 多跳遍历来自使用统计， 而不是来自 LLM 实体抽取。

• 混合检索：精确标记搜索（FTS5）补充嵌入 —— 错误 ID、包名和代码即使在余弦相似度较低时也能被找到。

• 睡眠：离线整合提交资格痕迹，衰减/剪除弱连接 并提升状态。所有状态都存在于一个 SQLite 数据库中： MCP 服务器和钩子可以并发运行而不丢失数据。

Related MCP server: Cortex

快速开始

pip install -e ".[dev]"
pytest                # full core test suite
python -m realmemory.eval.bench_recall --facts 1500 --queries 200   # synthetic
python -m realmemory.eval.bench_real                                # real-text (fastembed)

from realmemory import Hippocampus, MemoryConfig

hippo = Hippocampus.open("./rm_data", config=MemoryConfig.dev())
hippo.remember("The project uses PostgreSQL 16 with alembic migrations",
               scope="myproject")            # a project-scoped fact
hippo.remember("The user prefers concise answers") # global by default

packet = hippo.recall("which database does the project use?", scope="myproject")
for item in packet.items:
    print(f"[{item.confidence:.2f}] ({item.source}) {item.text}")
if packet.abstained:
    print("no trustworthy memories")     # abstention instead of hallucination

hippo.consolidate()   # "sleep": commit traces, decay weak links

本地嵌入器

默认情况下，核心使用确定性的 HashingEmbedder（无需模型）。 生产级的本地语义嵌入器是 fastembed（ONNX Runtime，CPU）：

pip install 'realmemory[local]'

• 模型：paraphrase-multilingual-MiniLM-L12-v2，维度=384，俄语+英语。

• 模型缓存：~/.cache/realmemory/fastembed（约 240 MB），只下载一次。

• 实测负载：约 580 MB 进程内存；CPU 上每个文本约 65–75 毫秒； 一次完整回忆约 77 毫秒。对代理不可见。

• 不对称性已处理：事实用 embed() 编码，查询用 embed_query() 编码。

• 门控阈值按模型各向异性校准：阈值配置位于 FastEmbedProvider.recommended_thresholds，在服务器启动时应用， 源自真实文本基准（见下文）。

接入 ZCode / Claude Code（MCP）

在客户端配置中注册用户作用域的 stdio 服务器：

"realmemory": {
  "type": "stdio",
  "command": "/path/to/venv/Scripts/python.exe",
  "args": ["-m", "realmemory.api.mcp_server",
           "--path", "/path/to/rm_data",
           "--embedder", "local"]
}

代理工具（以认知动作命名）：recall(query,k,project) · memorize(text,kind,related_ids,project) · reflect(memory_ids,reward) · revise(old_id,new_text) · introspect() · dream_log()。

共享 + 按项目记忆：每个痕迹都带有作用域标签 —— global （偏好、身份）或项目名称。项目会自动检测 （REALMEMORY_PROJECT → ZCODE_PROJECT_DIR → 包含 .git 的当前目录）； 也可以通过 project 参数或 --project 显式传入。 recall 搜索当前项目 + global；其他项目永远不会泄漏进来。

不同大脑之间完全命名空间隔离可通过 Hippocampus.open(path, namespace=...) / --namespace 实现。

数据库存储一个嵌入器标记（db_meta），并拒绝使用不同的 嵌入器打开 —— 新旧向量不能按余弦进行比较。

自动化：让代理真正使用它

默认安装三种机制：

1. 技能 / 指令，描述何时回忆 / 记忆 / 反思， 加载到每个会话上下文中。

2. SessionStart 钩子 → python -m realmemory.hook_cli brief — 注入 简短记忆状态：当前项目 + global 的语义事实和持久情节痕迹， 约 600 字符预算。

3. Stop 钩子 → python -m realmemory.hook_cli sleep — 每次回答后 进行整合；由数据库状态限流（自上次睡眠以来无变化则跳过）。 约需 0.3 秒，不加载嵌入器模型。

钩子和 MCP 服务器可以安全地同时运行：所有状态都在 SQLite 中， 并发“睡眠”由事务串行化。

运维

• 备份：每次“睡眠”前，数据库会被复制到 <store>/backups/（一致的 sqlite 备份 API），保留最近 10 份 （backups_keep；0 表示禁用）。任何模式迁移都会先自动创建安全副本。

• 模式版本记录在 db_meta.schema_version 中。

• 钩子失败不会被忽略：失败的钩子会打印到会话的 stderr，并在日志中留下 hook_error 事件，可在报告中看到。

• 学习纪律：报告显示 reflect/recall —— 低于约 0.1 时 代理很少给回忆的记忆打分，衰减和提升会盲目运行。

• 项目路由可通过一次调用验证 —— introspect 显示当前 检测到的项目。

可观测性（“记忆如何随时间表现”）

每个事件都会附加到数据库内的日志中：写入、回忆 （延迟、弃权、置信度）、反馈、带有完整指标的整合。 随时可查看完整报告：

python -m realmemory.report --path ./rm_data [--json report.json]

显示：按类型/作用域/状态的记忆增长、新颖性门控决策历史、 弃权比例和 p50/p95 回忆延迟、什么被强化、哪些 情节在消退、睡眠期间的保留动态、钩子失败。

阶段 0 结果（真实运行）

合成基准（bench_recall，哈希嵌入器，维度=2048）：

真实文本基准（bench_real，fastembed MiniLM 维度=384，103 条 RU/EN 事实， 89 条查询 —— 改写、精确标记、噪声）：

来自合成基准的教训：它在真实文本上得分 1.000，而默认阈值 几乎把所有内容合并成几个大块 —— 校准现在 源自基准分布，并位于嵌入器配置文件中。 同一个真实文本基准包含一个朴素的全扫描余弦基线： 管道在精确标记上明显胜出（1.000 对 0.800），在 改写上持平，目前弃权不如纯阈值积极 —— 参见 docs/ARCHITECTURE.md §7.2。 规模扫描（10k–50k 痕迹），并诚实报告了合成数据上 30k 处的回忆质量悬崖：§7.3。

细节和负面的 Hamming-SDM 结果见 docs/ARCHITECTURE.md 第 3 节和第 7 节。

测试：122 项通过。

架构

简而言之：L1 — SDRVotingIndex，对 SDR 单元的倒排索引进行指针投票 （容量 + 候选），L2 — 基于相同单元的组装网络 （关联、补全、多跳），再加上精确嵌入重排、 新颖性门控、衰减策略和离线整合器（“睡眠”）。

模块接口在 docs/CONTRACTS.md 中固定； 研究背景和来源在 docs/RESEARCH.md 中。

项目结构

src/realmemory/
├── encoding/     # embedders, SDR encoding
├── core/         # L1 SDRVotingIndex, L2 AssemblyNetwork, plasticity
├── policies/     # novelty gate, trace decay/promotion
├── store/        # SQLite storage (traces, edges, eligibility, events)
├── api/          # MCP server
└── eval/         # benchmarks

许可证

MIT