ClawMem如何为AI编程代理提供本地持久化记忆？（附开源架构解析）

专为 Claude Code、OpenClaw、Hermes 及 AI 代理设计的本地记忆系统。 集检索增强搜索、钩子（hooks）和 MCP 服务器于一体，完全本地化运行。无需 API 密钥，无云端依赖。

ClawMem：为 AI 编码代理提供本地持久化记忆。 集检索增强搜索、钩子（hooks）和 MCP 服务器于一体，完全本地化运行。无需 API 密钥，无云端依赖。

ClawMem 融合了多项前沿研究，构建了一个真正可用的检索增强记忆层。其混合架构结合了源自 QMD 的多信号检索（BM25 + 向量搜索 + 倒数排序融合 + 查询扩展 + 交叉编码器重排序）、受 SAME 启发的复合评分（近期衰减、置信度、内容类型半衰期、协同激活强化）、MAGMA 风格的多图遍历意图分类（语义、时序和因果波束搜索），以及 A-MEM 式的自演进记忆笔记（为文档添加关键词、标签和条目间的因果链接）。从 Engram 借鉴的模式提取功能，则增加了去重窗口、基于频率的持久性评分和时序导航。

ClawMem fuses recent research into a retrieval-augmented memory layer that agents actually use. The hybrid architecture combines QMD-derived multi-signal retrieval (BM25 + vector search + reciprocal rank fusion + query expansion + cross-encoder reranking), SAME-inspired composite scoring (recency decay, confidence, content-type half-lives, co-activation reinforcement), MAGMA-style intent classification with multi-graph traversal (semantic, temporal, and causal beam search), and A-MEM self-evolving memory notes that enrich documents with keywords, tags, and causal links between entries. Pattern extraction from Engram adds deduplication windows, frequency-based durability scoring, and temporal navigation.

可通过 Claude Code 钩子、MCP 服务器（兼容任何 MCP 客户端）、原生 OpenClaw 插件或 Hermes Agent 的 MemoryProvider 插件进行集成。所有路径都写入同一个本地 SQLite 保险库。在 Claude Code 会话中捕获的决策，当 OpenClaw 或 Hermes 代理接手同一项目时，会立即显现。

Integrates via Claude Code hooks, an MCP server (works with any MCP-compatible client), a native OpenClaw plugin, or a Hermes Agent MemoryProvider plugin. All paths write to the same local SQLite vault. A decision captured during a Claude Code session shows up immediately when an OpenClaw or Hermes agent picks up the same project.

基于 Bun 的 TypeScript 实现。MIT 许可证。

TypeScript on Bun. MIT License.

核心功能

ClawMem 将您的 Markdown 笔记、项目文档和研究资料转化为 AI 编码代理的持久记忆。它能自动执行以下操作：

ClawMem turns your markdown notes, project docs, and research dumps into persistent memory for AI coding agents. It automatically:

• 在每次提示时提供相关上下文（上下文浮现钩子）

  Surfaces relevant context on every prompt (context-surfacing hook)

• 引导会话启动：包含您的个人资料、最近的交接记录、近期决策和过时笔记

  Bootstraps sessions with your profile, latest handoff, recent decisions, and stale notes

• 从会话记录中捕获决策、偏好、里程碑和问题：使用本地 GGUF 观察者模型

  Captures decisions, preferences, milestones, and problems from session transcripts using a local GGUF observer model

• 导入对话导出文件：支持 Claude Code、ChatGPT、Claude.ai、Slack 和纯文本，通过 clawmem mine 命令，并可选择在导入后使用 LLM 进行事实提取（--synthesize），从纯文本对话转储中提取结构化的决策/偏好/里程碑/问题以及跨事实链接（v0.7.2）

  Imports conversation exports from Claude Code, ChatGPT, Claude.ai, Slack, and plain text via clawmem mine, with optional post-import LLM fact extraction (--synthesize) that pulls structured decisions / preferences / milestones / problems and cross-fact links out of otherwise full-text conversation dumps (v0.7.2)

• 生成交接记录：在会话结束时生成，以便下一个会话能接着您离开的地方继续

  Generates handoffs at session end so the next session can pick up where you left off

• 学习重要内容：通过反馈循环提升被引用的笔记，衰减未使用的笔记

  Learns what matters via a feedback loop that boosts referenced notes and decays unused ones

• 防范提示词注入：在浮现的内容中防范提示词注入攻击

  Guards against prompt injection in surfaced content

• 分类查询意图（WHY / WHEN / ENTITY / WHAT）：以加权不同的搜索策略

  Classifies query intent (WHY / WHEN / ENTITY / WHAT) to weight search strategies

• 遍历多图（语义、时序、因果）：通过自适应波束搜索

  Traverses multi-graphs (semantic, temporal, causal) via adaptive beam search

• 演进记忆元数据：随着新文档创建或完善连接关系

  Evolves memory metadata as new documents create or refine connections

• 推断事实间的因果关系：从会话观察中提取的事实之间

  Infers causal relationships between facts extracted from session observations

• 检测矛盾：在新旧决策之间，自动衰减被取代的决策（在合并工作器中增加了额外的合并时矛盾门，阻止跨观察的矛盾在落地前发生，v0.7.1）

  Detects contradictions between new and prior decisions, auto-decaying superseded ones (with an additional merge-time contradiction gate in the consolidation worker that blocks cross-observation contradictions before they land, v0.7.1)

• 防范跨实体合并：在合并期间，基于名称感知的双阈值合并安全机制，在合并相似观察前比较实体锚点，防止“Alice 决定 X”合并到“Bob 决定 X”中（v0.7.1）

  Guards against cross-entity merges during consolidation — name-aware dual-threshold merge safety compares entity anchors before merging similar observations, preventing "Alice decided X" from merging into "Bob decided X" (v0.7.1)

• 防止衍生见解中的上下文污染：第三阶段演绎合成流水线在写入跨会话演绎观察之前，通过反污染包装器（确定性实体污染检查 + LLM 验证器 + 去重）验证每个草稿（v0.7.1）

  Prevents context bleed in derived insights — the Phase 3 deductive synthesis pipeline validates every draft against an anti-contamination wrapper (deterministic entity contamination check + LLM validator + dedupe) before writing cross-session deductive observations (v0.7.1)

• 将浮现的事实框定为背景知识：context-surfacing 将注入的内容包装在 <instruction> + <facts> + <relationships> 块中，告诉模型将这些事实视为已知，并直接在提示中暴露浮现文档之间的记忆图边（v0.7.1）

  Frames surfaced facts as background knowledge — context-surfacing wraps injected content in <instruction> + <facts> + <relationships> blocks, telling the model to treat facts as already-known and exposing memory-graph edges between surfaced docs directly in-prompt (v0.7.1)

• 将知识图谱事实作为结构化三元组注入：当用户的提示中提到保险库已知的实体时，context-surfacing 通过三路径仅提示提取器（规范 ID、专有名词、小写 n-gram）解析它们，查询 SPO 图获取当前状态三元组，并将一个原始 subject predicate object 行的 <vault-facts> 块附加到 <vault-context> 中 — 在 speed 模式下关闭，在 balanced 模式下为 200 个 token，在 deep 模式下为 250 个 token，在三元组边界处截断（v0.9.0）

  Injects knowledge-graph facts as structured triples — when the user's prompt mentions entities already known to the vault, context-surfacing resolves them via a three-path prompt-only extractor (canonical IDs, proper nouns, lowercased n-grams), queries the SPO graph for current-state triples, and appends a <vault-facts> block of raw subject predicate object lines to <vault-context> — off for speed, 200 tokens on balanced, 250 on deep, token-truncated at the triple boundary (v0.9.0)

• 会话范围的焦点主题增强：clawmem focus set "<topic>" --session-id <id> 写入一个仅针对该会话的焦点文件，引导查询扩展、重排序、块选择、片段提取以及后复合评分的主题增强（匹配项 1.4 倍提升 / 非匹配项 0.75 倍降级） — 仅限会话隔离，故障开放，从不写入 SQLite 或生命周期列（v0.9.0）

  Session-scoped focus topic boost — clawmem focus set "<topic>" --session-id <id> writes a per-session focus file that steers query expansion, reranking, chunk selection, snippet extraction, and post-composite-score topic boosting (1.4× match / 0.75× demote) for that session only — session-isolated, fail-open, never writes to SQLite or lifecycle columns (v0.9.0)

• 评估文档质量：使用结构、关键词和元数据丰富度信号

  Scores document quality using structure, keywords, and metadata richness signals

• 提升协同访问的文档：经常一起浮现的笔记会获得检索强化

  Boosts co-accessed documents — notes frequently surfaced together get retrieval reinforcement

• 分解复杂查询：将复杂查询分解为类型化的检索子句（BM25/向量/图），以处理多主题问题

  Decomposes complex queries into typed retrieval clauses (BM25/vector/graph) for multi-topic questions

• 自动清理过时的嵌入向量：在嵌入运行前，自动清理已删除/更改文档的孤儿向量

  Cleans stale embeddings automatically before embed runs, removing orphans from deleted/changed documents

• 事务安全的索引：索引中途崩溃不会留下任何部分状态（原子提交与回滚）

  Transaction-safe indexing — crash mid-index leaves zero partial state (atomic commit with rollback)

• 钩子生成观察的去重：在 30 分钟窗口内使用规范化内容哈希，防止重复钩子输出导致记忆膨胀

  Deduplicates hook-generated observations within a 30-minute window using normalized content hashing, preventing memory bloat from repeated hook output

• 在文档周围进行时序邻域导航：通过 timeline 工具 — 从搜索到按时间顺序的上下文再到完整内容的渐进式披露

  Navigates temporal neighborhoods around any document via the timeline tool — progressive disclosure from search to chronological context to full content

• 提升频繁修订的记忆：修订次数较多的文档在复合评分中获得持久性信号（上限为 10%）

  Boosts frequently-revised memories — documents with higher revision counts get a durability signal in composite scoring (capped at 10%)

• 支持置顶/暂停生命周期管理：用于持久性提升和临时抑制

  Supports pin/snooze lifecycle for persistent boosts and temporary suppression

• 管理文档生命周期：策略驱动的归档扫描，支持恢复功能

  Manages document lifecycle — policy-driven archival sweeps with restore capability

• 自动路由查询：通过 memory_retrieve — 分类意图并分派到最优的搜索后端

  Auto-routes queries via memory_retrieve — classifies intent and dispatches to the optimal search backend

• 同步项目问题：从 Beads 问题跟踪器同步到可搜索的记忆中

  Syncs project issues from Beads issue trackers into searchable memory

• 运行静默窗口重度维护通道：第二个合并工作器，默认关闭，通过 CLAWMEM_HEAVY_LANE=true 启用，仅在可配置的小时窗口内以更长的间隔运行。由 context_usage 查询速率控制，因此它从不与交互式会话竞争 CPU/GPU 资源，仅通过数据库支持的 worker_leases 进行范围限定，默认优先处理陈旧任务，可选择意外性选择器，并在 maintenance_runs 中记录每次尝试以供操作员查看（v0.8.0）

  Runs a quiet-window heavy maintenance lane — a second consolidation worker, off by default behind CLAWMEM_HEAVY_LANE=true, that runs on a longer interval only inside a configurable hour window. Gated by context_usage query-rate so it never competes for CPU/GPU with interactive sessions, scoped exclusively via DB-backed worker_leases, stale-first by default with an optional surprisal selector, and journals every attempt in maintenance_runs for operator visibility (v0.8.0)

完全本地运行，无需 API 密钥和云服务。通过 Claude Code 钩子和 MCP 工具、原生 OpenClaw 插件或 Hermes Agent 的 MemoryProvider 插件集成。所有模式共享同一个保险库，实现跨运行时记忆。兼容任何 MCP 客户端。

Runs fully local with no API keys and no cloud services. Integrates via Claude Code hooks and MCP tools, as a native OpenClaw plugin, or as a Hermes Agent MemoryProvider plugin. All modes share the same vault for cross-runtime memory. Works with any MCP-compatible client.

完整版本历史记录在 RELEASE_NOTES.md 中。现有保险库的升级说明在 docs/guides/upgrading.md 中。

Full version history is in RELEASE_NOTES.md. Upgrade instructions for existing vaults are in docs/guides/upgrading.md.

架构

安装指南

平台支持

Platform	Status	Notes
Linux	Full support	Primary target. systemd services for watcher + embed timer.
macOS	Full support	Homebrew SQLite handled automatically. GPU via Metal (llama.cpp).
Windows (WSL2)	Full support	Recommended for Windows users. Install Bun + ClawMem inside WSL2.
Windows (native)	Not recommended	Bun and sqlite-vec work, but bin/clawmem wrapper is bash, hooks expect bash commands, and systemd services have no equivalent. Use WSL2 instead.

先决条件

必需：

Required:

• Bun v1.0+ — ClawMem 的运行时。在 Linux 上，通过 curl -fsSL https://bun.sh/install | bash 安装（不要用 snap — snap 版 Bun 无法读取 stdin，这会破坏钩子）。

  Bun v1.0+ — runtime for ClawMem. On Linux, install via curl -fsSL https://bun.sh/install | bash (not snap — snap Bun cannot read stdin, which breaks hooks).

• SQLite with FTS5 — Bun 已包含。在 macOS 上，安装 brew install sqlite 以获得扩展加载支持（Cl

常见问题（FAQ）

ClawMem 如何实现完全本地化运行，无需云端依赖？

ClawMem 基于 Bun 的 TypeScript 实现，所有数据存储在本地 SQLite 保险库中，无需 API 密钥或云服务，确保隐私和离线可用性。

ClawMem 支持哪些 AI 编程代理集成？

支持 Claude Code 钩子、MCP 服务器（兼容任何 MCP 客户端）、原生 OpenClaw 插件和 Hermes Agent 的 MemoryProvider 插件，所有路径写入同一本地保险库。

ClawMem 的核心功能如何帮助 AI 代理提升编码效率？

它自动提供相关上下文、捕获决策和偏好、生成会话交接记录，并通过自演进记忆笔记维护跨会话知识图，使代理能持续学习项目历史。