lore

📖 Lore

为你使用的每个 AI Agent 提供共享、完整保真的会话历史。

任何 Agent。任何会话。任何轮次。随时可用。

你今天早上在 Claude Code 中运行的会话，Openclaw 今天下午就能调取。 Cursor 上周梳理过的调试讨论串，Hermes 也能像亲历现场一样读取。Lore 为你所有的编码 Agent 提供一份共享记忆：跨越所有工具和会话，永不过期。

这正是大多数“Agent 记忆”工具所遗漏的部分。其他工具只会为一个 Agent 在一个应用中记住内容。Lore 则让你所有 Agent 曾经进行过的每个会话，都能随时被其他任何 Agent 搜索。Codex 搞清楚的事，Claude Code 也知道。你周二解决的问题，周五只需搜索一下就能找到，无论你当时使用的是哪个 Agent。

而且，它能在上下文压缩后继续保留。当上下文窗口填满并被压缩时，工作并没有消失，而是仍然保存在磁盘上。Lore 只需让你能再次访问这些内容，并在你的 Agent 工作之处提供完整搜索。数据在本地、私密，永远归你所有。

https://github.com/user-attachments/assets/b5c0f077-47da-4502-bf78-2ce08abf034f

灵感来自 RLM

v0.2.0 版本发布

此版本将 Lore 从旧对话记录的搜索框，升级为一套轻量级工作流基础设施，帮助 Agent 继续完成实际工作：

• 支持 Schema 5 写入。 当前安装版本现在可以再次读取和写入实时存储。lore status --json 会同时报告 schemaVersion 和 supportedSchemaVersion，因此在同步、索引或推送写入失败之前，就能发现过期的全局安装。
• 新鲜度检查。 在 Agent 根据不完整的记忆撰写摘要或交接内容之前，lore status 会告知它源或项目时间窗口是否已就绪、缺失、过期或可能尚未同步。
• 实时同步已检测到的来源。 lore sync <source> 会增量索引已检测到的活动对话记录树。它支持 codex（~/.codex/sessions，并将归档会话作为兼容性回退）和 claude-code （~/.claude/projects），无需 Agent 记住原始路径。
• 工作流技能。 npm 包现在除基础 lore 技能外，还包含 lore-recall、lore-brief、 lore-handoff 和 lore-dev-verification。其中包括参考资料、示例、评估规范、验证器和已提交的测试报告。
• 软件包冒烟测试证明。 npm run package:smoke 会构建、打包、解包并验证实际 tarball，从而一并检查 README、帮助文本、技能文件夹、可执行权限和软件包元数据。

已经安装？在测试任何 Schema 或同步行为之前，请先刷新全局命令：

npm install -g @jordanhindo/lore@latest
lore help
lore status --json

如果你的 shell 缓存了旧路径，请打开新终端，或运行 hash -r，然后重试 lore help。

✨ 为什么你会需要它

• 🔀 一份记忆，适用于每个 Agent。 Claude Code、Codex、openclaw、Cursor 和 Hermes 的历史记录都会存入同一个存储（与它们各自的 /. 存储相互独立），任何 MCP 客户端都能读取。一个 Agent 中的会话，其他 Agent 都能立即读取。Codex 搞清楚的事， Claude Code 也知道。
• 🧠 它不会随着上下文窗口消失。 压缩不再意味着失忆。 上周的推理过程，只需搜索一下就能找到。
• 🔍 懂代码的搜索。 getUserById、foo.bar.ts 和 trust-metadata 都能作为完整词条被找到，不会被拆得支离破碎。
• 🔒 默认在本地运行。 所有内容都保存在你机器上的 ~/.lore/lore.db。绝不向外发送数据。

🚀 快速开始（将此内容粘贴到你的 Agent 中）

Lore 会自行完成设置。将下面的说明粘贴到任意编码 Agent 中。它会安装 Lore、为你自己的历史记录建立索引，并在宣告完成前验证搜索功能正常。默认情况下无需服务端，也不需要注册 MCP。

Set up Lore (full-fidelity session memory) for yourself. Install it with
`npm install -g @jordanhindo/lore@latest`, then run `lore setup` to index my
history and self-verify. Prove it by running `lore search` for a word from
a past session and showing me a hit. The MCP server is optional: only
register it (`lore serve`) if you specifically want MCP tool calls instead
of the CLI; if you do, tell me the reload step I have to do.

Agent 遵循的确定性操作指南位于 AGENT-ONBOARD.md，其中将 MCP 注册作为 可选步骤。更喜欢使用技能？运行 npx skills add jordanhindo/lore （见下文）即可安装会自动完成初始设置的 lore 技能；下次你让它回忆某些内容时，它会完成以上所有操作。

🛠️ 自行安装

推荐：安装技能。它会完成其余设置。

npx skills add jordanhindo/lore

这会将捆绑的 lore 技能安装到你的 Agent 中（~/.claude/skills/）。该技能会自动完成初始设置：下次你让 Agent“记住”／“回忆”某些内容，或“设置 lore”时，它会读取自身的 references/setup/index.md， 安装 lore CLI，为你的历史记录建立索引，并验证搜索功能正常。无需 MCP 服务。一条命令即可安装全部内容。

或者直接安装 CLI：

npm install -g @jordanhindo/lore@latest   # puts the `lore` command on your PATH

需要 Node 22+。安装就这么简单。接下来由 lore setup 完成后续操作。如果 npm install 因 better-sqlite3 报错，或之后找不到 lore，请参阅 故障排除 一节，其中也包含 Windows 的解决方法。

升级全局 CLI

全局 lore 命令只是一个 npm 二进制文件垫片。如果你运行的是旧版软件包，请先更新，再使用 lore sync、lore index 或 lore push：

npm install -g @jordanhindo/lore@latest
lore help
lore status --json

如果 lore status --json 显示存储的 schemaVersion 高于 supportedSchemaVersion，说明你的命令仍然过时。重新安装软件包， 必要时打开新的 shell，然后重新运行 lore status --json。

从源代码安装

克隆项目适用于贡献者，或用于编写新适配器（需要源代码树）：

git clone https://github.com/jordanhindo/lore && cd lore
npm install
npm run build
npm link        # optional: puts `lore` on your PATH

📥 回填你的历史记录

lore setup 是最快的方式。它会检测你机器上的各个运行环境， 为每个环境建立索引，检查搜索功能是否正常，并打印如何将 Lore 接入你的 MCP 客户端。

lore setup

想要更精细地控制？将转录目录传给 lore index。对于 Claude Code，该目录是 ~/.claude/projects：

lore index ~/.claude/projects              # primary transcripts
lore index ~/.claude/projects --subagents  # include subagent transcripts
lore index ~/.claude/projects --no-redact  # keep credentials verbatim (see Privacy)

其他运行环境可通过 --source 接入。Codex、openclaw、Cursor 和 Hermes 均已内置支持：

lore index ~/.codex/sessions --source codex
lore index ~/.openclaw/sessions --source openclaw
lore index ~/.cursor --source cursor     # reads Cursor's SQLite state store
lore index ~/.hermes --source hermes     # reads Hermes's SQLite state store

Cursor 和 Hermes 将历史记录存储在 SQLite 数据库中，而不是 JSONL 文件中；将目录传给 lore index，适配器便会直接读取存储数据。 当前抽样的 Cursor 数据行包含 toolResults 字段，但其中只有空数组，因此 Cursor 适配器只为文本建立索引，不会伪造工具调用。

需要时可重新运行以上任一命令。未更改的文件会被跳过，因此重复运行的开销很小。

有些运行环境会写入转录树，而不是发出与 Lore 兼容的钩子负载。如需手动追补当前活动会话，请使用增量同步命令：

lore sync codex
lore sync claude-code
lore sync hermes

codex sync 会增量索引 ~/.codex/sessions，仅在兼容性回退时使用 ~/.codex/archived_sessions。claude-code sync 会增量索引 ~/.claude/projects，包括子 Agent 转录。hermes sync 会增量索引 ~/.hermes。

对于 cron、launchd、Task Scheduler 或任何无人值守的定时任务，请使用捆绑的、受锁保护的包装器，而不要直接运行 lore sync，以免多个源任务同时写入 ~/.lore/lore.db：

./scripts/lore-sync-once.sh codex
./scripts/lore-sync-once.sh claude-code
./scripts/lore-sync-once.sh hermes

💻 从 CLI 回忆，无需服务端

使用 Lore 不需要 MCP 服务。lore 命令会直接打开 SQLite 存储，因此只要有 shell，搜索、回读、导航和写入都能在无需服务端的情况下正常工作。下方的 MCP 服务只是读取同一存储的另一种方式；这里的所有操作都不依赖它。

整个流程始终不变：逐步深入，绝不倾倒。 一个会话可能包含数百万个令牌，因此绝不能将整个会话分页载入上下文。先广泛搜索，再使用返回的真实 ID（绝不自行编造），然后充分利用这些 ID：

lore search "fts tokenizer" --relevant     # → hits, each leading with a message + session id
lore get <message-id> --full               # read that one message in full
lore context <message-id>                  # 5 before / 5 after, anchor flagged
lore session <session-id> --around <message-id>   # jump to that spot, read forward

其他命令也让流程更加完整：lore status（新鲜度／健康状况）、 lore sessions（近期对话）、lore timeline（按日／小时查看活动） 以及 lore push（通过 stdin 中的 JSON 批次添加实时会话）。为其中任何命令添加 --json，即可获得机器可读的封装。 MCP 工具接受的所有搜索筛选条件在这里也都适用（--project、--source、 --session、--branch、--agent、--skill、--tool、--role、--model、 --since、--until、--limit）。

在请求最新简报或交接信息前，请先检查新鲜度：

lore status --json --source codex --project "$PWD"

schemaVersion 和 supportedSchemaVersion 会告诉你此版本能否写入存储。只读搜索仍可能适用于更新的兼容存储，但只有已安装版本支持该存储架构时，同步／索引／推送才会运行。在源码检出目录中，请先运行 npm run build，再使用全局 lore shim。对于 npm 安装，请运行 npm install -g @jordanhindo/lore@latest，然后再次检查 lore status --json。

CLI ⇄ MCP 的一致性经过验证，而非仅仅声称。 每个 lore … --json 封装都与对应 MCP 工具的响应逐字节相同；这一点由一致性测试套件验证，该套件会让两条路径针对同一共享 fixture 存储运行。因此，CLI 可以忠实替代服务端：

任务	CLI	MCP 工具	--json 封装
关键词搜索	lore search	search_memory	{ count, hits }
融合近期性的搜索	lore search --relevant	find_relevant	{ count, hits }
单条消息	lore get	get_message	详情对象 / { error, message_id }
相邻消息	lore context	get_context	{ messages }
会话分页	lore session	get_session	{ messages, nextCursor }
会话列表	lore sessions	list_sessions	{ count, sessions }
活动情况	lore timeline	timeline	{ buckets }
状态／新鲜度	lore status	status	状态封装
写入	lore push	push	结果 / { error, detail }

随附的 lore skill（skills/lore/）会教会 Agent 如何完成整个流程：何时搜索、使用哪个 ID，以及如何逐步深入而非倾倒内容。它能自举：其 references/setup/index.md 涵盖了如何先将历史记录编入索引（安装、为 harness 建立索引／回填、编写适配器或推送），因此只需运行一次 npx skills add jordanhindo/lore 即可安装全部内容。

Agent 工作流技能

低层级的 skills/lore/ 技能会教 Agent 如何安装 Lore、为转录内容建立索引、搜索记忆、深入查看消息 ID，以及在运行环境支持时使用 MCP 服务。工作流包构建在这一基础之上：

• lore:recall 对应 skills/lore-recall/。它会规划有界检索、检查 lore status --json、标注时效性、深入查看上下文窗口，并生成附有引用的证据包，而不是转储转录内容。
• lore:brief 对应 skills/lore-brief/。它默认涵盖滚动的最近 24 小时，总结已完成和未完成的工作，并提出后续技能、作业、问题、修复、任务、记忆卡片或 Wiki 更新建议，但不会执行这些操作。
• lore:handoff 对应 skills/lore-handoff/。它会创建精简的续接包，其中包含已验证、待处理、过时和有风险的部分、产物、共享提案对象、记忆卡片候选项、矛盾候选项以及后续操作。
• lore:dev-verification 对应 skills/lore-dev-verification/。它是 Lore 仓库变更的项目专属验证关卡，涵盖 CLI/MCP 一致性、存储兼容性、适配器保真度、隐私和破坏性记忆操作行为、软件包冒烟测试，以及工作流技能评估证明。

这些是可安装的技能包，而不是单文件提示词片段。每项工作流技能都包含 SKILL.md、参考资料、示例、评估规范、结构确定时使用的验证脚本，以及 evals/test-report.md。只有当测试报告证明评估/审查流程已运行且技能包验证器通过后，工作流技能才算完整。

此版本没有通用插件封装。未来的插件或许可以打包 lore:recall、lore:brief 和 lore:handoff 等名称，但目前发布的内容是 skills/ 软件包目录树，以及 lore CLI/MCP 基础层。工作流技能可以提出操作建议；除非用户明确要求执行下一步，否则不得创建作业、编辑提示词、更新 Wiki 页面、创建任务、修改代码或运行破坏性记忆操作。

更改此软件包的任何部分时，也要同步更新对应内容：CLI 帮助、README、AGENT-ONBOARD.md、skills/lore、工作流技能文档、验证器、示例、评估报告和软件包冒烟测试应一并更新。

打包验证位于：

npm run package:smoke

该冒烟测试会构建 CLI、保留 dist/cli/lore.js 的可执行权限、验证软件包试运行元数据、打包实际的 tarball、从打包后的目录树中读取工作流技能文件夹、检查测试报告标题内容非空，并验证打包后的 CLI 帮助能够在依赖项齐全时运行。

🔌 将其提供给客户端

lore serve 会通过 stdio 启动 MCP 服务。让任意 MCP 客户端连接到它即可。

Claude Code（添加到 ~/.claude/settings.json）：

{
  "mcpServers": {
    "lore": { "command": "lore", "args": ["serve"] }
  }
}

Cursor / Cline 等客户端：在客户端的 MCP 配置中添加一个 stdio 服务条目，并使用相同的 command / args 格式。

你的 Agent 能做什么

工具	功能说明
status	存储健康状况、新鲜度、架构版本，以及按来源／项目范围统计的数量。
search_memory	在所有对话记录中进行关键词搜索，按 bm25 排序，并支持筛选。
find_relevant	与 search_memory 类似，但会综合相关性和时间新近度。
get_message	按 ID 获取一条消息（full=true 会返回未经省略的文本）。
get_context	获取锚点消息前后的邻近消息窗口。
get_session	将一个逻辑会话折叠为分页时间线。
list_sessions	会话汇总信息（数量、首次／最近活动时间），支持筛选。
timeline	按天或小时分桶统计一段时间内的活动。
push	写入一个经过规范化的实时 JSON 批次，与 CLI lore push 的格式一致。

每个搜索工具都接受相同的维度筛选条件：project、branch、 source、agent、skill、tool、role、model、since、until、limit。

搜索结果包含什么

你的 Agent 使用查询（以及任意筛选条件）调用 search_memory，即可获得匹配数量和按相关性排序的结果列表。每条结果都包含匹配文本和完整来源信息，因此 Agent 可以知道记忆_来自何处_，并通过 get_message 获取其余内容：

// search_memory({ query: "fts tokenizer", source: "claude-code", limit: 2 })
{
  "count": 2,
  "hits": [
    {
      "messageId": "9f3c…a71b",          // synthetic, stable across re-index
      "sessionId": "0c1d2e3f-…",
      "sourceFileId": "claude-code:…",
      "source": "claude-code",            // harness namespace the hit came from
      "role": "assistant",
      "timestamp": "2026-06-05T18:22:41.103Z",
      "project": "/Users/you/lore",
      "branch": "main",
      "model": "claude-opus-4",
      "agent": null,
      "score": 11.27,                       // higher is a better match (bm25)
      "text": "Switched the FTS5 tokenizer to unicode61 with tokenchars '_-.' so getUserById and foo.bar.ts stay whole…",
      "textTruncated": false
    }
    // …one more hit
  ]
}

长消息会以省略形式返回，并附带标记，告知 Agent 如何通过 get_message(message_id, full=true) 获取完整文本，这样一份超长对话记录就不会撑爆上下文窗口。

🪄 熬过上下文压缩

上下文压缩时，记忆最为重要，因此要在新会话内容从活动上下文中消失前及时捕获。具体挂钩方式因运行环境而异： Claude Code 可在存在挂钩负载时，从 PreCompact / SessionEnd 调用 lore hook；如果只需要刷新对话记录目录，则可手动运行 lore sync claude-code 追赶更新。计时器应调用 scripts/lore-sync-once.sh claude-code，确保对共享存储的写入经过锁定。Codex 应使用其通知包装器，或由计时器调用 scripts/lore-sync-once.sh codex，因为它写入的是会话目录，而非 transcript_path 挂钩负载。

技能设置参考文档中包含确切的操作步骤： skills/lore/references/setup/claude-code-hooks.md、 skills/lore/references/setup/codex-hooks.md， 以及 skills/lore/references/setup/other-harness-hooks.md。

🧩 使用你自己的运行环境

列表中没有你的 Agent？lore sample <transcript-dir> 可以概述其磁盘上的格式。它能识别 JSONL、SQLite 数据库（通过文件头读取，绝不加载数据库）和完整文件形式的 JSON，让你在编写任何内容前了解未知运行环境的数据结构。内置 lore 技能的 references/setup/index.md（skills/lore/references/setup/index.md）会指导 Agent 从“已安装”到“我的会话可供搜索”，包括编写并验证新的适配器，或在运行环境完全不保留文件时使用实时 push 路径。 push 仅处理数据：它会在入口处验证每条记录，绝不会接收或执行代码。

🔒 隐私

• 存储位于本地（~/.lore/lore.db），在任何仓库之外，并且 *.db 已加入 gitignore。使用 LORE_DB 移动它。
• 默认会脱敏凭据。 在写入任何内容之前，都会对消息文本和工具负载运行 保守的清理器（OpenAI / GitHub / AWS / Slack 密钥、Bearer 令牌、PEM 私钥块）。其他内容均按原样保留。这是你自己的记忆。请将清理器视为安全网，而非保证。
• 如果确实希望凭据也按原样存储，可在 lore index / lore hook / lore setup 中使用 --no-redact 选择退出。
• 删除你不想保留的记忆。 lore forget 删除某个会话或项目（指定时间点）；lore exclude 删除某个项目，并禁止今后从中采集内容。两者都会显示精确范围预览，只有添加 --confirm 后才会执行，并且都会写入墓碑，防止重新索引时恢复数据。完整的预览后确认流程请参阅 lore 技能。

🧬 底层工作原理

• 一个共享存储，多个运行环境。 每个运行环境都写入自己的 source 命名空间（claude-code、codex、openclaw、cursor、hermes）。任何 MCP 客户端都可以读取所有运行环境的历史记录。
• 三个 ID。 source_file_id 表示一个物理对话记录文件（摄取和恢复水位标记的单位）。session_id 表示一个逻辑会话，由主文件及其子 Agent 文件共享。每条消息都会获得一个合成的 message_id = hash(source_file_id + uuid + seq)，因为原始 uuid 会冲突。
• 从设计上支持增量处理。 每个文件都有一个水位标记，用于跳过未更改的文件、仅追加新增内容，并对已重写的文件进行完整重新索引。对数千份对话记录重新运行回填时，只会处理发生更改的内容。
• 感知代码的搜索。 FTS5 分词器会保留标识符和路径的完整形式，因此你实际搜索的内容都能被检索到。

⚙️ 环境变量

变量	默认值	含义
LORE_DB	~/.lore/lore.db	存储位置。
LORE_LOG_LEVEL	info	debug / info / warn / error。

👷 开发

npm run check   # typecheck + lint + format + test
npm run test:watch

许可证：MIT。