跨端记忆库 ys118/harnmem

HarnMem

HarnMem logo

跨 harness 的智能体记忆，存放在普通文件里。

HarnMem = harness + memory（harn 在苏格兰语里也有「脑子」的意思）。
一个用户，一台机器，一份记忆库 —— 你用的每个编码智能体都能共享。

HarnMem 是给编码智能体用的可移植记忆系统。记忆以普通 Markdown 文件的形式存放在 ~/.harnmem/ 下，由本地确定性引擎检索，再往每个 harness 会话里注入一小份字节稳定的热索引。同一份记忆库，每个适配器和命令行都能读，所以在某个 harness 里写下的记忆，换个 harness 也能用 —— 不需要服务器，不需要向量数据库，不需要嵌入模型，引擎也没有任何运行时依赖。

- 包： @harnmem/core（引擎）、@harnmem/cli（harnmem 命令）、pi-harnmem（pi 扩展，已收录进 pi.dev 包画廊）、dsh-harnmem（DSH 插件）、claude-harnmem（Claude Code 插件）、codex-harnmem（Codex 命令行插件）、opencode-harnmem（opencode v2 插件）、grok-harnmem（Grok 命令行插件）、cursor-harnmem（Cursor 桌面插件）、hermes-harnmem（Hermes Agent 记忆服务商，通过 Hermes 自带的插件管理器安装）和 omp-harnmem（oh-my-pi 扩展插件）—— 除 hermes-harnmem 外全部发布在 npm 上，hermes-harnmem 则通过 Hermes 自带的插件管理器安装（见上文）。安装命令行用 npm install -g @harnmem/cli；opencode 适配器需要 opencode 2.x，已在 2.1.4 二进制上端到端验证（注入、原生工具、逐轮日志）；Grok 适配器已在 1.0.70 二进制上验证（MCP initialize.instructions 注入、六个工具、会话结束提取）；Cursor 适配器已在 Cursor 3.27.22 上验证（首条提示词注入、插件 MCP 工具、会话结束日志）；Hermes 适配器已在 Hermes Agent 0.22.5 上验证（预取注入、五个原生工具、分离式会话结束提取）；omp 适配器已在 oh-my-pi 18.14.1 上验证（字节稳定的系统提示词注入、五个工具、/memory、会话结束日志）。
- 协议： MIT。
- 状态： v0.7.3 —— 引擎、命令行/迁移工具，以及全部八个发布在 npm 上的适配器（pi、DeepSeek Harness、Claude Code、Codex、opencode、Grok、Cursor、omp）均已发布并通过端到端测试；Hermes 适配器（hermes-harnmem）同样已实现、通过端到端验证，并通过 Hermes 插件管理器安装。0.7.3 版本修复了一个静默数据丢失核心 bug（用未知 project id 写入时，会创建后续会话都无法解析的分片，#42），并重新升版 engine-embedding 适配器；同时发布 pi-harnmem 0.4.6，在 pi.dev package gallery 中附上预览图，并为宿主包提供文档推荐的 "" peer 范围；0.7.2 交付了 omp 和 Hermes 适配器以及 UTF-8 BOM 配置修复，此前还有 0.7.0 的 Grok 和 Cursor 适配器，以及 0.6.2 的七包审计波次（21 个确认问题修复了 17 个，结构性剩余项在路线图中记为 N18-N20）。Codex 适配器还覆盖命令行 TUI 信任流程和 Codex Desktop，并从 ~/.codex/sessions 回填会话，直到 Codex 提供 SessionEnd 钩子。

为什么还要另一个记忆插件？

| 方案 | 在本用例下的局限 |
| mem0 / Zep / Letta / OpenViking | 需要服务、向量数据库或 Docker；安装和运维都很重 |
| pi-memory | 在 pi 内有效，但不与其他 harness 共享，也没有生命周期治理 |
| dsh-auto-memory | 仅限 DSH；能跨会话，但不能跨 harness |
| harness 内置记忆（如 ZCode） | 绑定单一 harness；存储布局无法复用 |
| 把所有东西都塞进 AGENTS.md | 没有检索，没有治理；越写越吵，直到模型直接忽略 |

HarnMem 的赌注：真相源是文件系统，检索在本地进程内完成，生命周期决策可解释、可回滚。

特性

- 天生跨 harness。 存储和数据模型与 harness 无关；适配器很薄。同一份存储由 pi、DeepSeek Harness、Claude Code、Codex、opencode、Grok、Cursor、Hermes 和 omp 适配器共享，也由不依赖任何 harness 的命令行共享。
- 文件原生 SSOT。 一条记忆一个 Markdown 文件，带 YAML frontmatter。索引和摘要是派生出来的，可重建；索引损坏只付出一次重建代价，绝不丢数据。
- 零运行时依赖。 @harnmem/core 和 @harnmem/cli 只用 Node.js 内置模块。没有原生模块，没有下载，没有后台守护进程。
- 不靠 embedding 也能精确召回。 支持 CJK 的分词（字符二元组）、BM25F 字段加权、实体/标签/时间过滤、两跳链接扩散，以及一个可解释的分数，融合词法相关性、重要性、置信度、新近度、使用情况、置顶、链接和过期程度。
- 记忆越老越好用。 只追加写入，配合双时间 supersede 保留历史；机械去重/合并让存储保持精简；基于价值的留存把条目从 active -> archived -> trashed 迁移；trash/ + 恢复和只追加的 state/audit.jsonl 让一切可审计。
- 对 KV 缓存友好的注入。 注入块只在会话开始、压缩、记忆写入和跨天时重建，且轮次之间字节一致，所以提示词缓存持续命中。
- 词汇表随你的语料成长。 内置的同义词表通用是有意为之；harnmem synonyms suggest 读取你自己的记忆，向模型询问可互换的术语——共现扫描永远找不到这些词（中文行话通常不共享字符），再拿每个词组对照语料库校验，把审核过的建议写入本地 -suggested 表。保留之前，synonyms check 会报告排名增益。
- 实测，而非断言。 确定性评估框架覆盖 12 个场景套件，带硬性功能门槛和建议性性能门槛；消融实验显示哪些检索信号真正重要。
- 安全迁移。 为 DSH、pi、ZCode、Claude Code 和 Markdown 目录树提供导入器（外加宽松的 JSON/JSONL/stdin 契约），默认 dry-run，备份源数据，记录台账，校验源完整性，支持按次回滚。不确定手上有什么？harnmem import auto 探测已知存储并打印计划。

快速开始

要求：Node.js 22.15+ 和 pnpm 10（corepack enable）。

安装

CLI (works with every harness, no adapter needed)
npm install -g @harnmem/cli

pi extension
pi install npm:pi-harnmem

DSH plugin
dsh plugin --profile desktop add dsh-harnmem

Claude Code plugin (the repo root is a Claude Code marketplace)
claude plugin marketplace add ys118/harnmem
claude plugin install harnmem@harnmem-marketplace

Codex CLI plugin (the repo root is also a Codex marketplace)
codex plugin marketplace add ys118/harnmem
codex plugin add harnmem@harnmem-marketplace

opencode v2 plugin (requires opencode 2.x)
opencode plugin add opencode-harnmem

Grok CLI plugin (the repo root is also a Grok marketplace)
grok plugin marketplace add ys118/harnmem
grok plugin install grok-harnmem --trust

Cursor desktop: copy the plugin into ~/.cursor/plugins/local, merge the
user-level hooks, then run Developer: Reload Window
npx cursor-harnmem

Hermes Agent memory provider (requires Hermes v0.22.5+ and Node 22.15+ on PATH)
hermes plugins install ys118/harnmem/packages/hermes-harnmem --enable
hermes memory setup

oh-my-pi plugin (requires omp 18.14.1+)
omp plugin install omp-harnmem

所有适配器读写同一个 ~/.harnmem/ 存储，所以装多个适配器共享同一份记忆。每次安装都完全在本地运行，不会向外发送任何数据。

Grok CLI 还会自动发现为 Claude Code 安装的插件。因此如果装了 claude-harnmem，Grok 会看到两个插件声明同一个 harnmem MCP 服务器；它只保留一个，显式启用的 grok-harnmem 胜出（它的 [plugins] enabled 条目由 grok plugin install 写入），于是会话拿到六个 Grok 工具和注入的索引。要彻底卸载自动加载的 Claude 副本（一个 SessionEnd 钩子而不是两个），在 ~/.grok/config.toml 的 [plugins] 下加 disabled = ["harnmem"]；没装 Claude 插件时这个条目无害。详情见 docs/design/11-grok-adapter.md。

从源码构建

bash
corepack enable
pnpm install
pnpm -r build
pnpm test # every package's test suite (node --test)

pi 适配器 bash

Try it without installing: load the built extension in a one-shot pi session.

pi -e ./packages/pi-harnmem/dist/index.js -p "Remember: I prefer pnpm over npm."

From a checkout: install the local path instead of npm:pi-harnmem.

pi install ./packages/pi-harnmem

扩展会在每轮对话开始前注入热索引，注册记忆工具（harnmem_write、harnmem_search、harnmem_read、harnmem_forget、harnmem_status —— 名称跟随 toolPrefix 设置，默认的 harnmem_ 前缀让 pi-memory 能同时加载，后者占用裸的 memory_ 名称），添加 /memory，并在会话结束时执行一次有界提取。配置放在 ~/.harnmem/config.json（或 $HARNMEM_HOME/config.json）。

DSH 适配器 bash

From a checkout (instead of the published package in Install above):

pnpm --filter dsh-harnmem build
dsh plugin --profile desktop add ./packages/dsh-harnmem

插件以 cordis 插件形式挂载：通过 systemPrompt.section 注入同一份热索引（字节稳定，并带同步冷启动兜底），注册五个以 harnmem_ 为前缀的工具（harnmem_write、harnmem_search、harnmem_read、harnmem_forget、harnmem_status；裸的 memory_* 名称属于 dsh-auto-memory，两个插件都安装时 DSH 会保留它），让子代理会话保持只读，并通过宿主 LLM 服务在会话结束时执行一次有界提取。生命周期与提取决策写入 ~/.harnmem/logs/dsh.jsonl（log: "on" 是试用默认值），每次提取结果都以 kind:"extract" 事件写入 ~/.harnmem/state/audit.jsonl。它要求 DSH 0.2.x，自身从不打开网络连接。在 DSH web GUI 上，插件还会注册一个只读的 Memory 面板（概览、记忆列表、详情、索引与注入预览）。

Claude Code 适配器

通过上面的 marketplace 命令安装（要求 Claude Code 2.1.x，已在 2.1.310 上验证）。插件会：

- 通过 SessionStart 钩子注入热索引 —— 轮次之间字节稳定，空存储注入零字节，输出在 Claude 的 10,000 字符 additionalContext 上限内确定性截断；
- 通过内置的零依赖 stdio MCP 服务器暴露五个记忆工具（harnmem_search、harnmem_read、harnmem_write、harnmem_forget、harnmem_status；工具输出会被裁剪到远低于客户端 25k token 上限）；
- 添加 /harnmem:memory 斜杠命令，用于手动搜索/读取/写入/遗忘/查看状态；
- 在分离的子进程中执行会话结束提取（上游不遵守插件钩子的超时声明，所以钩子必须立即返回）；
- 让子代理会话保持只读（在 2.1.310 上 Task 子代理不触发会话钩子；这些防护是向前兼容的安全网）。
@harnmem/core 已内置到插件包中，因此安装后的插件目录是自包含的。如果要在本地检出上开发，执行 claude plugin marketplace add D:\projects\harnmem（或对应的 POSIX 路径）会直接读取仓库，代码改动在下一个会话生效。

Codex 适配器

通过上面的 marketplace 命令安装（需要 codex 0.164/0.165 alpha 引擎；已在 Windows 上验证）。插件会：

- 通过 SessionStart 的 mcp_tool 钩子注入热索引——工具输出会作为开发者消息落地，在轮次之间字节稳定，存储为空时不注入任何内容；
- 通过内置的零依赖 stdio MCP 服务器暴露五个记忆工具和两个内部钩子目标（共 7 个工具）；
- 附带一个技能，教模型何时搜索、何时写入；
- 每次会话启动时回填：~/.codex/sessions 下比持久游标更新的 rollout 只记录一次，因此即使会话关闭时没有抽取，也仍会被捕获。Codex 目前还不支持 SessionEnd 钩子——钩子已声明，但当前引擎会跳过；
- 遵守一次性的 TUI 信任流程（「Hooks need review」）；Codex Desktop 在 config.toml 中沿用同一份持久化信任状态。

配置见包 README，完整验证记录见探测记录。

Hermes 适配器

通过 Hermes 自带的插件管理器安装（需要 Hermes Agent v0.22.5+；PATH 中必须有 Node.js 22.15+，因为插件通过一个小型 Node 桥接驱动引擎）。适配器是一个 Python MemoryProvider 插件：

- 在每次模型调用前通过 prefetch() 注入快照——在 Python 中缓存，只在会话切换、跨天、记忆写入或压缩时重建，因此连续轮次注入的字节完全相同；
- 把 harnmem_write/search/read/forget/status 暴露为 Hermes 原生工具；
- 在每个真实会话边界，于分离的子进程中抽取一次，因此关闭 Hermes 永远不会等待抽取；
- 对子代理会话和 cron 会话，以及设置了 read_only 时，以只读方式运行；
- 通过 hermes memory setup 配置（10 个字段），通过 hermes harnmem status 报告状态。

安装、配置和故障排查见包 README，接缝映射见设计文档。

命令行 bash
node packages/cli/dist/main.js --help
node packages/cli/dist/main.js stats
node packages/cli/dist/main.js search "deployment rule" --limit 5
node packages/cli/dist/main.js write --type feedback \
--title "Never force-push main" \
--content "Why: shared repo. How to apply: open a PR." --importance 7

Migrate legacy memories: dry-run by default, then --apply

node packages/cli/dist/main.js import auto # probe known stores (DSH/pi/ZCode/Claude Code)
node packages/cli/dist/main.js import dsh
node packages/cli/dist/main.js import md --path ./notes --apply # any Markdown tree
node packages/cli/dist/main.js import json --path export.json # any JSON/JSONL export

Grow the local synonym table from your own memories (nothing is auto-applied)
node packages/cli/dist/main.js synonyms list
node packages/cli/dist/main.js synonyms suggest --llm-url http://127.0.0.1:11434/v1 --llm-model qwen3:8b
node packages/cli/dist/main.js synonyms check

评测

node evals/gen/generate.mjs # generate deterministic corpora
node evals/gen/generate.mjs --check # prove a second generation is byte-identical
pnpm eval # all suites
pnpm eval:gate # hard gates (perf gates are advisory)

架构

flowchart LR
subgraph Harnesses
PI[pi extension]
DSH[DSH plugin]
CC[Claude Code plugin]
CX[Codex plugin]
OP[opencode plugin]
GK[Grok plugin]
HE[Hermes plugin]
end
CLI[harnmem CLI + migration]
CORE["@harnmem/corestore · retrieval · writing · lifecycle · extraction"]
PI --> CORE
DSH --> CORE
CC --> CORE
CX --> CORE
OP --> CORE
GK --> CORE
HE --> CORE
CLI --> CORE
CORE --> STD[(~/.harnmem plain files)]
CORE --> IDX[(rebuildable BM25F index)]

一次会话的流程是这样：

1. 会话开始 / 恢复： 适配器调用 ensureContext()；core 在 token 预算内返回一份热索引（置顶条目、高价值条目、近期条目、摘要行）。适配器把它注入系统提示词一次，之后保持字节稳定，直到它失效。
2. 会话进行中： 模型用记忆工具（或命令行）写入、搜索、读取、遗忘和查看记忆。写入会去重并限定范围；冲突的事实会取代旧事实，而不是覆盖历史。
3. 会话结束： 适配器把对话记录摘要发给一次有界的 LLM 调用，然后写入提取出的记忆（与现有存储去重，带置信度阈值和幂等游标）。
4. 会话之间： 整合会合并近似重复项，按价值/时间淘汰陈旧条目，并（可选）写入主题摘要。

一条记忆长什么样

schema: 1
id: mem_01J8Z6Q0K4T9B2M7R5X3C8V1ND
type: feedback
category: workflow
scope: project
project: my-app-4f2a91c3d0
title: Never force-push main
description: Shared repository requires PRs; force-push rewrites others' history.
importance: 7
confidence: 0.9
pinned: false
status: active
created: 1760918400000
updated: 1760918400000
tags: [git, workflow]
links: []
supersedes: []

Why: main is shared; rewriting history disrupts other contributors.
How to apply: push feature branches and open a pull request.

类型有 user、feedback、project 和 reference。记录只追加：修正后的事实会新建一条记录，并把旧记录标记为 status: superseded，同时设置 valid_to，这样「上个月我相信的是什么？」依然答得出来。

数据布局

默认 ~/.harnmem/（Windows：C:\Users\<you>\.harnmem\）：

~/.harnmem/
├── config.json # optional user config (budgets, weights, governance)
├── VERSION # store layout version
├── memories/ # SSOT: one .md file per memory
│ ├── user/ # global, cross-project scope
│ └── projects/<projectId>/
├── digests/ # optional topic digests produced by consolidation
├── prompts/ # prompt assets deployed on first run (editable)
├── data/ # synonym tables, one file per language, deployed on first run (editable)
├── projects.json # project identity registry (git remote/path -> id)
├── index/ # derived indexes; safe to delete, rebuilt on demand
├── sessions/ # raw session journals used as extraction input
├── state/ # sequence numbers, audit log, cursors, usage overlay
├── trash/ # soft-deleted entries (30-day grace, restorable)
└── logs/ # adapter logs, e.g. logs/pi.jsonl

schema 与迁移映射见 docs/design/02-data-model.md。

检索与排序

检索刻意做成纯本地、可解释：

- 分词器：英文单词 + 汉字二元组（查询时避开边界单字噪声）；
- BM25F 作用于标题/描述/标签/实体/正文，各字段带权重；
- 打分混合：词法相关性、重要性、置信度、时间新鲜度（0.995^hours）、使用频次、置顶、两跳链接扩散，以及陈旧度惩罚；
- MMR 多样化，外加注入用的 token 预算；
- 最佳词法证据太弱时弃权（避免注入无关上下文）。

公式与标定见 docs/design/03-retrieval.md。

评测结果

harness 是确定性的（不用 LLM，不联网），跑一遍约一分钟；下面的数字来自纳入版本管理的 eval-report.md：

| 指标 | 结果 |
| 套件 / 查询 / 文档 | 12（S1-S12）/ 565 / 27,510 |
| Macro Recall@10 | 1.000 |
| MRR | 0.891 |
| nDCG@10 | 0.911 |
| 跨语言（zh <-> en）召回差距 | 0.000 |
| 功能门禁 | 全部通过 |
| 参考性性能项 | 10k 导入约 12 s；热搜索 p95 约 16 ms；索引约为规范存储的 2.9 倍 |

参考性性能项如实记录，没有藏起来：导入是一次性迁移成本，超大存储的索引体积与延迟目标已列入路线图。细节、各套件数字、消融实验与门禁定义见 docs/design/05-evaluation.md 和 evals/README.md。

Harness 支持

| Harness | 状态 | 备注 |
| pi 1.3.0+ | 支持 | 扩展，带注入、工具、/memory、会话结束抽取；已在 1.3.0 上端到端验证，peer 范围接受 1.4.x |
| DeepSeek Harness 0.2.1 | 支持（0.2.x） | Cordis 插件（dsh-harnmem）；已用一次性配置档和本地 mock 端点对桌面运行时验证 |
| CLI（任意 harness） | 支持 | harnmem 命令读写同一存储 |
| Claude Code 2.1.x | 支持 | claude-harnmem 插件（SessionStart 钩子 + stdio MCP + /harnmem:memory）；已对 2.1.310 端到端验证；harnmem import claude 可迁移已有存储 |
| Codex CLI 0.164/0.165 alpha | 支持（Windows） | codex-harnmem 插件（SessionStart mcp_tool 钩子 → 开发者消息注入 + stdio MCP + 技能 + rollout 回填）；已在 CLI、TUI 信任流程和 Codex Desktop 上端到端验证；Codex 发布 SessionEnd 钩子之前，抽取靠回填 |
| opencode 2.1.4 | 支持（2.x） | opencode-harnmem 插件（字节稳定的 session.hook("context") 快照 + 五个原生工具 + 逐轮日志；子会话只读）；已在 2.1.4 二进制上端到端验证 |
| Grok CLI 1.0.70 | 支持（1.0.x） | grok-harnmem 插件（记忆索引走 MCP initialize.instructions —— Grok 的 SessionStart 只观察；六个工具 + /grok-harnmem:memory + 从 chat_history.jsonl 做 SessionEnd 抽取；插件 id harnmem 会遮蔽自动加载的 claude-harnmem，因此只跑一个 MCP 服务器和一个抽取器）；已在 1.0.70 二进制上端到端验证 |
| Hermes Agent 0.22.5 | 支持（PATH 上有 Node 22.15+） | hermes-harnmem Python MemoryProvider 插件 + 内置引擎的 Node 桥（逐轮 prefetch 注入，配 Python 侧快照缓存；五个原生工具；分离的会话结束抽取；子代理/cron 会话只读）；已在临时 HERMES_HOME 上端到端验证（注入、召回、工具写入、hermes plugins validate 无告警） |
| oh-my-pi 18.14.1 | 支持（18.x） | omp-harnmem 扩展插件（字节稳定的 before_agent_start 系统提示词注入 + 五个记忆工具 + /memory 命令；退出/切换记日志，子代理只读）；已在 18.14.1 二进制上端到端验证 |
| 其他 harness | 欢迎 | 见适配器契约和 CONTRIBUTING.md |

文档

先从文档索引看起。重点：

- 用户指南
- FAQ
- 设计概览
- 数据模型
- 检索
- 写入生命周期
- 评估
- 适配器契约
- 迁移接入
- Hermes 适配器
- 适配器编写指南
- 智能体工作流契约

路线图

当前状态（核实过的数字、正在跑的试用、已知问题）和排好序的后续步骤，见 docs/ROADMAP.md。

- Codex 适配器 —— 已作为 codex-harnmem 发布；见它的 README，以及探测记录 docs/research/codex-plugin.md。
- Grok 适配器 —— 已作为 grok-harnmem 发布；见它的 README、docs/design/11-grok-adapter.md 和探测记录 docs/research/grok-plugin.md。
- Cursor 适配器 —— 已作为 cursor-harnmem 发布；见它的 README、docs/design/12-cursor-adapter.md 和探测记录 docs/research/cursor-plugin.md。
- Hermes 适配器 —— 已实现为 hermes-harnmem，将在下个版本发布（通过 Hermes 插件管理器安装，不走 npm）；见它的 README、docs/design/13-hermes-adapter.md 和研究笔记 docs/research/hermes-plugin.md。
- omp 适配器 —— 已作为 omp-harnmem 发布；见它的 README 和研究记录 docs/research/omp-plugin.md。
- 持久化索引并增量更新，让大型存储预热更快；缩小索引体积。
- 在 Linux/macOS/Windows 上验证 npm 安装，并为每次发布附上 provenance。
- 加固多个 harness 共用一个 home 时的并发写入。
- 为有歧义的召回加一个可选的 reranker 或 LLM 选择器，默认关闭（基础使用永远不需要）。

安全与隐私

HarnMem 本地优先：没有遥测，没有后台服务，引擎从不打开网络连接。命令行默认也离线；唯一的外呼是可选启用的 harnmem synonyms suggest --llm-url 桥接，只有你传入端点时才会运行。记忆内容本身就很敏感——备份 ~/.harnmem/，别把它放进版本控制，报告漏洞前先读 SECURITY.md。存储层做了符号链接/路径包含检查、体积上限、敏感值脱敏、软删除和审计日志；细节见设计文档。

贡献

欢迎贡献。先读 CONTRIBUTING.md，遵守 Code of Conduct，提 pull request 前跑一遍 pnpm test 和 pnpm eval:gate。注意贡献门槛：新贡献者提的 issue 和 pull request 默认自动关闭，维护者用 lgtmi（issue）或 lgtm （issue 和 pull request）批准后重新打开。合并 master 只能走 PR，且需要 owner 批准。如果你在用 AI 编程智能体，让它读 AGENTS.md：每项改动都走 worktree 分支和 pull request，智能体绝不推送到 master。欢迎在 Discussions 提问、提想法。安全问题请走 SECURITY.md 里的私密流程。

License

MIT © HarnMem contributors