remem

remem：为 Claude Code 和 OpenAI Codex 提供本地优先的记忆

不必在每次新的编码 Agent 会话中重新解释你的项目。

语言：English | 简体中文

remem 会在 Claude Code 和 OpenAI Codex CLI 会话中自动捕获、提炼、搜索和注入工程记忆。决策、修复错误的原因、项目模式和偏好会通过钩子、MCP、CLI 和本地主机 REST API 保持可用。

新的 Claude Code 会话会通过带有记忆引用的内容，回忆起此前的根本原因、提交记录和待处理 TODO，无需重新解释。

remem 能为你做什么

• 自动捕获会话，并在后台通过大模型进行提炼。
• 使用一个本地存储，在 Claude Code 和 Codex 中召回项目范围内的记忆。
• 可搜索的决策、错误修复、架构说明、偏好和原始会话证据。
• 来源归属、过时标记、抑制、审核队列和注入审计。
• 新安装默认使用带 SQLCipher 加密的 SQLite。
• 通过一个 Rust 运行时提供 MCP、CLI 和经过身份验证的本地主机 REST 访问。

remem 优先保证记忆质量。自动捕获是主要途径；当需要立即记录某项决策时，可通过手动调用 save_memory 进行补充。

五分钟内完成安装

Homebrew

brew install majiayu000/tap/remem
"$(brew --prefix remem)/bin/remem" install --target codex

Claude Code 使用 --target claude。--target all 会配置所有已知宿主，包括支持其 v1 渲染器的 Cursor。

独立安装程序

curl -fsSL https://raw.githubusercontent.com/majiayu000/remem/main/install.sh | env REMEM_NO_CONFIG=1 sh
~/.local/bin/remem install --target codex

npm 或 Cargo

npm install -g @remem-ai/remem
# or
cargo install remem-ai --bin remem

remem install --target codex

Codex 的安装、检测、doctor、卸载、转录扫描和默认原生记忆导入都会遵循 CODEX_HOME；默认值为 ~/.codex。运行这些命令前，将其设为绝对路径即可选择其他 Codex 配置文件。空值或相对路径覆盖值会在安装写入任何内容前明确报错。无关的配置文件会保持原样。

GitHub Releases：提供 macOS 和 Linux 的 x64/arm64 预编译二进制文件，并公布校验和。请在 PATH 中使用一个规范的 remem 可执行文件；如果钩子和终端解析到不同副本，remem doctor 会发出警告。

有关特定发布渠道的升级、平台限制、PATH 漂移和手动安装说明，请参阅安装与升级指南。更全面的文档指南汇集了插件和运维资料。

验证安装

重启所选编码 Agent，然后运行：

remem doctor
remem status
remem search "last decision"

健康的 Claude Code 或 Codex 安装会在 SessionStart 时注入相关项目记忆，并在 Stop 时将持久会话提炼任务加入队列。Codex 还会使用 UserPromptSubmit 捕获每条提示词，并展示精简的可选记忆候选项。remem doctor 会检查架构、加密密钥、数据库、钩子、MCP 注册、工作进程和常见安装路径漂移。 其诊断不会创建数据目录，也不会写入或轮换日志文件；发现的问题和 stderr 警告仍会显示，同时还会检查现有日志的健康状况。

仓库贡献者可以通过隔离的可执行文件冒烟测试 fixture验证重复的 SessionStart 抑制。

如需聚焦且只读地查看当前记忆的实际情况：

remem doctor truth --cwd .

为什么没有记住某些内容？

使用一份只读报告，跟踪捕获、提取、审核、当前有效性和最近记录的上下文运行：

remem doctor memory "original phrase" --cwd .
remem doctor memory --host codex-cli --source-root local \
  --project PROJECT_KEY --session-id SESSION_ID --json

从 remem raw sessions --json 复制准确的选择器。使用 --injection-run-id RUN_ID 检查特定目标上下文的注入。源会话和目标上下文运行 彼此独立。每个证据源最多显示 20 行；省略的证据会明确标记。终端输出会显示 保留的来源／状态数量，以及每个来源的 3 个样例；--json 包含 所有保留的证据。未找到匹配项或 单项审计结果为未知，并不能证明捕获失败，也不能据此猜测丢弃 原因。查询发现会结合原始搜索与存储文本的字面匹配； 改写表述找不到证据时，请尝试原始措辞或准确的会话。请参阅诊断契约。

Remem 帮助 Agent 延续工作；Refine 帮助人们检查和重用 知识；agent-sessions 用于解析原生来源格式。Refine 使用 Remem 现有的会话引用、 内容指纹和提交／会话关联，而不是再收集一份转录副本。

宿主支持

能力	Claude Code	Codex CLI	Cursor v1
MCP 记忆工具	支持	支持	支持 macOS/Linux
SessionStart 注入	支持	支持	不支持
自动会话记忆	支持	支持，基于 Stop 且低噪声	v1 安装程序未启用
工具事件捕获	已安装钩子	默认不安装高频 Bash 钩子	存在运行时命令；未安装钩子
已编译命令规则强制执行	可选：对 Bash 发出警告／阻止	不支持	不支持
Windows	支持	支持	不支持

Cursor 的 v1 安装程序仅注册 MCP。已验证的 observe 和 summarize 运行时命令确实存在，但 remem install --target cursor 不会 安装自动捕获钩子或 SessionStart 注入。

仓库还包含一个 Codex 插件封装。有关本地插件运行时和 显式启用钩子的说明，请参阅 plugins/remem/README.md。

为什么要将 remem 与内置记忆结合使用

内置的 MEMORY.md、CLAUDE.md 和 Agent 指令文件非常适合记录 少量应始终可见的稳定事实。remem 则用于记录那些过于庞大、动态或证据密集， 难以手动维护的工程历史。

需求	内置文件	remem
稳定的项目规则	出色	支持
不断变化的上下文	手写指令；Claude Code 自动记忆也会写入笔记	由钩子驱动的会话捕获和后台提炼
搜索较早的决策依据	受加载文本限制	精选搜索和原始搜索
分支、时间和过时状态处理	手动	内置
来源溯源和注入审计	Git 历史	基于数据库的审计
审核、抑制和生命周期治理	手动编辑	一等命令

Claude Code 自动记忆 已会自动保存 笔记。两者的区别在于记忆范围，以及证据、检索和生命周期控制，而不只是自动持久化。

两者结合使用。将简洁的规则保存在原生文件中，让 remem 留存大量长期积累的决策、 失败案例、证据和不断变化的项目状态。

更广泛的生态对比见有日期标注的 记忆工具调查。

工作原理

Claude Code / Codex hooks
          |
          v
append-only captured_events ledger
          |
          v
coalesced background extraction and session rollup
          |
          v
governed candidates -> curated memories + workstreams + raw archive
          |
          v
FTS, entity, temporal, vector, graph, and optional local rerank retrieval
          |
          v
budgeted, source-attributed SessionStart context

钩子会在完成持久化捕获或排入队列后迅速返回。后台工作进程负责提取、候选内容治理、 压缩、检索增强和生命周期清理。MCP、CLI、REST 和 SessionStart 共用同一 本地存储和治理模型，但会应用特定于各自界面的资格策略。 显式搜索是检查和恢复界面，因此可能返回带有 legacy_unverified 标签的记忆； 默认情况下，SessionStart 和 CurrentTruth 会排除这些记录，并记录排除原因。 对于格式错误的生成式提取响应，系统会使用现有的有界退避策略重试，同时保留相同的源证据。无效的已存储证据仍需修复；如果模型尝试次数耗尽，系统会保留原始捕获内容和重放范围供检查，而不是接受不完整的输出。

观测提取和会话汇总会将大量积压拆分为有界的事件块。每次模型调用都会将系统指令、提示词格式化内容和证据一并纳入预算；处理进度只会推进到已处理的事件块。每个事件的提示词内容即使被截断，原始证据仍可用。精确恢复会保留原始范围，并在明确选择的配置文件和单一总超时时间内，恢复已验证成功的事件块。已存在的关联后续任务会从各自的原始边界和检查点恢复；主任务完成不会掩盖后续任务失败。归档的精确恢复会原子性地声明现有任务组，禁止新增后续任务；若尝试失败，则会再次归档未完成的成员。

Worker 会持久化公平的队列顺序和阶段／项目声明顺序，因此在繁忙项目中继续捕获内容时，仍能为下游提取和持久化任务留出空间，并支持一次性 Worker 重启。现有的一次性 Worker 准入预算仍然适用。

生成的记忆在通过来源支持性、机密信息、指令模式、范围和生命周期检查之前，都会被视为不可信。存在风险的内容会被丢弃或转交审核，并附上可诊断的原因。完整且有用户支持的安全禁令、研究活动和明确作为分析对象引用的内容，可以用英文或中文进入人工审核；它们绝不会自动提升。机密值、有害指令和缺乏支持的外部文本仍会被排除。

自动提升的摘要决策和发现，在捕获的本地证据、当前摘要门槛和精确激活回执仍有效时，可以按其原始摘要置信度进入当前上下文。外部内容以及缺失或已变更的证明仍会进入审核，或被排除。新的可信证据可以重新评估内容相同且仍待审核的内容：remem 会保留原始快照，并将其关联到新的候选项。重复证据、人工审核决定、隔离和抑制状态都会保留。已过期的运行状态需要新的证据才能续期。

如需了解模块归属和当前数据流，请阅读 docs/ARCHITECTURE.md。

实验性的 MCP context_bundle 工具会向显式调用方提供带版本控制和预算限制的编译器。实验性的 remem context-plan 命令会输出针对特定请求的检索计划。这些选择性启用的接口由 Context Bundle 和 retrieval-router 合约跟踪。

默认的 Codex 集成保持低干扰：SessionStart 提供稳定的上下文，UserPromptSubmit 提供精简的候选索引，Stop 则将摘要任务加入后台队列。提示词候选项包含 ID、标题、状态、检索原因、估算读取成本和详情查询提示，但不包含记忆正文。它们只是可选线索，Codex 可以忽略、打开或进一步搜索。第一个提示词还可能收到最多两个连续性锚点，因此像 continue 这样的提示词不必依赖词汇重合。现有的混合 RRF 会为记忆候选项排序；不会由最终置信度阈值来决定模型判断的相关性。自动提取会要求生成简短且具体的候选标题，不带多余的项目名称前缀；已存储的标题则保持不变。 对于你自己的 Codex 侧边栏，可以选择采用 MMDD｜TYPE｜Topic 这一重命名规范，例如 0903｜FIX｜FTS5 tokenizer mismatch。如果使用单独的、由宿主支持的重命名工作流，请先预览拟定名称，再批量应用。这只是宿主侧边栏的整理方式：Remem 不会重命名宿主对话，也不会将这些名称导入为意图覆盖项。Remem 的结构化会话／工作流字段仍具有权威性，宿主标题不会更改记忆类型或工作流身份。请参阅会话意图约定和实现史诗 #1065。

会话／工作流标签更正需先通过经过身份验证的 POST /api/v1/session-intent/preview 进行预览，再通过 POST /api/v1/session-intent/apply 明确确认。在拟议主题和原因中，每个敏感选项或 Bearer 前缀及其值都必须位于同一逻辑行。例如，curl --oauth2-bearer\nexample-value 会被拒绝，并返回 HTTP 400 错误 session_intent_cross_line_sensitive_argument；请将选项和值放在同一行后重试。拒绝请求不会创建预览令牌或审计条目，也不会更改标签。同一行中的敏感值会在预览前进行脱敏处理。

日常工作流

检索和检查

remem search "database encryption"
remem search "deployment decision" --branch main --explain
remem show <memory-id>
remem why <memory-id>
remem current <state-key>

remem search 会保持终端整洁：正常使用时，每次查询的 [INFO] [search-perf] 诊断信息会写入日志文件，而不是 stderr。调试时，设置 REMEM_DEBUG=1 可将这些信息同时输出到 stderr。

Git worktree 的项目别名

当 worktree 拥有自己的项目键时，先预览指向主检出目录的别名， 然后检查路径和 Git 证明，再应用别名：

remem project alias add /path/to/worktree --canonical /path/to/main \
  --actor you --reason "same project"
remem project alias add /path/to/worktree --canonical /path/to/main \
  --actor you --reason "same project" --apply
remem project alias list
remem search "decision" --project /path/to/main
remem project alias revoke /path/to/worktree \
  --actor you --reason "worktree retired" --apply

主检出目录必须已通过常规 remem 捕获创建项目行。 该别名会保留历史行中记录的路径，同时让 CLI 和 MCP 项目搜索也包含 worktree 的记忆。除非指定 --apply， 否则 add 和 revoke 只会预览，不会写入数据库。撤销别名会将 worktree 从主项目的搜索范围中移除；list 会报告有效别名及其 最近一次激活时的操作者和原因。

Agent 可以使用 MCP search 获取精简结果，再使用 get_observations 查看 所选详情。只有在整理后的记忆中找不到确切的转录证据时，才使用原始回忆：

remem raw search "exact phrase" --since 2026-06-01 --json

读取确切转录前，先列出完整的、绑定主机的会话：

remem raw sessions --latest 20 --json
remem raw messages --host codex-cli --source-root local \
  --project "/path/to/project" --session-id SESSION_ID --json
remem ingest-sessions --root codex-cli:archive=/path/to/sessions --json

默认转录扫描会使用 $CLAUDE_CONFIG_DIR/projects 和 $CODEX_HOME/sessions，若不可用则回退到 ~/.claude 和 ~/.codex。 显式指定空覆盖值会报错。显式指定的覆盖目录必须存在且可读；只有不存在的推断默认目录会被跳过。仍支持显式指定 --root 目录；批量扫描会排除其下级 subagents 目录。 Codex 会话模式使用原生来源证据：IDE 表示交互式会话，显式的 exec 即使来源方为 Desktop，也表示无人值守；子 Agent 证据优先。这些是来源标签，并不能证明是谁发起了运行。检查原始分类证据后，已保存的模式只升级一次；真正的来源冲突仍会导致批次失败。此更新会添加架构版本 v093：升级前请保留数据库备份；旧版二进制文件无法打开升级后的架构。原始消息标识和游标会保留。

将某条 raw sessions 摘要中的 host、source_root、project 和 session_id 原样复制到 raw messages。现有脚本必须添加必需的 --host 选择器，并将 --root LABEL=PATH 替换为 --root HOST:LABEL=PATH；raw reconcile 也使用相同的根目录格式。如果部分归档行无法符合绑定主机的会话约定，JSON 信封会报告 excluded_legacy_rows、excluded_legacy_sessions 和 excluded_legacy_identities。每个列出的会话还会附带可为空的新增字段 mmdd、session_intent、session_topic、display_label 和 session_intent_source。mmdd 根据 Asia/Shanghai 时区中的会话创建时间戳推导；只有在意图和主题均已知时，才会提供完整的 {MMDD}｜{INTENT}｜{topic} 标签。Stop 摘要可以将这些字段的来源设为 summary 并填入字段；未知、空、过长或已脱敏的值会被弃用，而不会阻止摘要的其余部分处理。自动生成的 Stop 汇总会在后续轮次中保留手动标签覆盖，包括显式清除的标签。列表仍会返回健康会话；--latest N 只会用健康会话填满该数量上限，不会让尚未解决的行占用名额。使用跳过的标识（已知时包括 source_root、project、session_id 和 host）检查或修复这些行。对于被跳过的选择器，精确的 raw messages 查询会继续 fail-closed。除非摄取操作确实能认领被跳过的行，否则不要重新摄取；许多旧行没有可信的主机来源信息。 HOST 为 claude-code 或 codex-cli，LABEL 会成为持久化的 source_root。游标快照证据要求手动配置并验证 remem summarize --host cursor Stop 集成；文件系统 --root 摄取和对账会明确拒绝 cursor。

审查与治理

remem review list
remem review approve <candidate-id>
remem memory suppress memory:<id> --reason "no longer relevant"
remem govern --action stale --dry-run --json <id>

根据风险，变更型治理命令会提供预览、明确确认或审查边界。请运行 remem <command> --help 查看当前约定，不要依赖复制来的命令清单。

MCP 工具与该存储共用数据，但遵循更严格的通信协议约定。权威 MCP 约定见 GH981，其中包括 #1061 的变更和范围边界：

• save_memory：已知调用主机时，请传入 host。省略主机时会记录为 unknown，绝不会推断为 codex-cli。
• govern_memory：先运行 dry-run，预览该治理事务中的 ID 和当前版本。非 dry-run 变更必须为每个 ID 提供 expected_versions、设置 confirm_destructive=true，并明确说明原因。
• recall_user_context：请提供 project 或 cwd。服务不会根据自身进程的工作目录推断此范围。

本地 Remem 应用会显示会话／工作流标签或明确表示无法判断。可按意图和 Asia/Shanghai 中的创建日期筛选会话。操作人员可通过批量操作更正标签，并查看更正前／后的预览、进行明确确认和审计；工作流身份和主机对话标题保持稳定。

配置记忆 AI 和检索

remem config show
remem model current
remem model use balanced --dry-run
remem embedding status
remem embedding download --model multilingual-e5-small
remem embedding backfill --limit 1000

除非选择 remem 专用 API 密钥，否则 auto 嵌入模式会保持本地运行。经验证的本地模型为可选项；带标签的特征哈希回退方案仍然可用。第二阶段本地重排器也为可选项，在完成配置前处于禁用状态。

向量索引会将每个模型和工件修订版保存在各自的向量空间中。在选择最近邻之前，会先应用项目、分支、类型和生命周期筛选条件。自动上下文使用与搜索相同的向量执行器，因此随着项目增长，旧记忆仍可通过相似度匹配。派生索引重建期间，本地精确扫描可确保召回率；大型存储可能需要更长时间，直到相应配置文件的索引就绪。

详情请参阅当前配置路由、本地嵌入约定，以及 remem config、remem embedding 或 remem reranker 的帮助信息。

remem usage 会报告每次已分派的记忆 AI 尝试，包括失败的尝试。观测到的零值、部分值、缺失值、无效值和文本估算令牌数会分别处理。报告的 USD 金额仅包含已知定价部分；覆盖率计数会显示未知费率或缺少计数器详情是否导致数据不完整。没有提供方计数器的失败尝试不会获得猜测的令牌估算值。历史用量仍会标记为未经验证，而不会被悄然重新分类。

在数据库之外共享或编辑记忆

remem sync-memory --cwd .
remem export --markdown --output ./remem-memory
remem export --pack .remem-pack

Markdown 镜像可供人工编辑。项目记忆包是确定性导出内容，可提交到 git，并支持考虑来源信息的导入与隔离处理。请参阅记忆用量指南和项目记忆包约定。

证据与基准测试

已检入的公开套件将记忆系统能力证据与编码 Agent 结果证据分开。使用以下命令在本地验证：

cargo run -- bench verify --root eval/public --json-out /tmp/remem-bench-verify.json

验证器会在 --root 的父目录旁解析 claims/registry.json，因此外部套件应将 public/ 和 claims/ 作为同级目录，并且不受调用者当前工作目录的影响。

公开对抗性 SQLite 快照上限为 64 MiB，并且必须是规范的 VACUUM 映像；验证器读取的工件目标也必须解析到声明的公开根目录内。

当前公开报告不支持公开基准测试声明，并有意标记为 directional_only_no_public_claim。历史上的隔离编码基线是有用的工程证据，但其预加载记忆条件与当前的 SessionStart 检索路径不可比较。

复现命令、工件架构、声明边界和当前门槛位于：

• eval/README.md
• eval/public/README.md
• eval/coding-bench/README.md

README 声明有意排除未封存且没有已检入报告的本地指标。

安全与隐私

• 全新安装会创建 SQLCipher 加密数据库和私钥文件。
• 数据目录和密钥采用严格的逐用户权限。
• REST API 绑定到 127.0.0.1，并要求提供 bearer token。
• 钩子捕获的事件预览会在持久化前进行脱敏。
• MCP 和 CLI 工作流列表会投影脱敏文本：类似凭据的赋值、简短的内联密钥和敏感命令选项会在返回字段（以及 CLI --json 信封的 project）中替换为 [REDACTED]，而普通文件系统项目路径仍可读。存储的工作流行会保留其规范值，以便进行匹配和范围检查，因此当存在密钥时，查询输出可能与数据库内容不同。
• 记忆候选项和注入内容会通过密钥与投毒防护。
• remem doctor 会报告加密、明文残留、架构和审计故障，但不会打印记忆负载。

有关报告和安全政策，请阅读 SECURITY.md。SQLite 调优 和记忆投毒防护的操作契约保存在首页之外。

REST API

remem api --port 5567
TOKEN=$(cat ~/.remem/.api-token)
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:5567/api/v1/health
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:5567/api/v1/capabilities

客户端应通过 /api/v1/capabilities 进行功能检测。当前端点和兼容性契约维护在 docs/specs/SPEC-web-api.md 中。

文档

使用 docs/README.md 作为安装、配置、记忆生命周期、检索、治理、API、插件、运维、架构和基准测试资料的导航页。

最常用的入口包括：

• 架构与数据流
• 记忆使用指南
• 记忆生命周期
• Codex 插件
• REST API 契约
• 当前规范索引
• 变更日志
• 贡献指南

卸载

预览并移除主机钩子和 MCP 注册，但不删除记忆：

remem uninstall --dry-run
remem uninstall

加密数据库仍保留在配置的 REMEM_DATA_DIR 中。如果要删除数据，请在手动删除该目录前先备份。常规文件删除会移除 remem 的本地数据，但无法保证从文件系统快照、备份或底层存储介质中安全擦除。

许可证

MIT