# Remem Memory

> Claude Code 和 Codex 的自动记忆系统。

语言： [English](README.md) | **简体中文**

`remem` 是 Claude Code 和 Codex 的持久记忆系统。它是一个 Rust 单二进制程序，会在 Claude Code 和 Codex 会话间自动捕获、提炼并注入项目上下文，包括决策、模式、偏好和经验。你不用在每次新会话里重复解释项目。

[![CI](https://github.com/majiayu000/remem/actions/workflows/ci.yml/badge.svg)](https://github.com/majiayu000/remem/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

![Remem Memory terminal demo](assets/remem-demo.gif)

## 核心问题

- **会话失忆**：每次新开 Claude Code 或 Codex 会话都要从零解释。
- **上下文丢失**：Bug 修复原因、设计取舍会在会话结束后消失。
- **偏好重复**：同样的编码偏好要反复强调。
- **缺少连续性**：跨会话推进功能时恢复成本高。

## remem 的解决方式

| 没有 remem | 使用 remem |
|---|---|
| “我们用 FTS5 trigram tokenizer...” 每次都说 | 自动从记忆注入 |
| “非测试代码不要 `expect()`” 反复提醒 | 偏好会优先展示 |
| “上次我们决定了什么...” 需要手动回溯 | 决策历史可追踪 |
| 会话结束就丢失修复背景 | 根因与修复被持续保留 |

## 安装

```bash
# 方式 1：Homebrew
brew install majiayu000/tap/remem

# 方式 2：快速安装（GitHub Release 预编译二进制，并自动配置 hooks）
curl -fsSL https://raw.githubusercontent.com/majiayu000/remem/main/install.sh | sh

# 固定版本、指定安装目录，或只安装二进制不改 hooks/MCP
REMEM_VERSION=v0.5.42 curl -fsSL https://raw.githubusercontent.com/majiayu000/remem/main/install.sh | sh
REMEM_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/majiayu000/remem/main/install.sh | sh
REMEM_NO_CONFIG=1 curl -fsSL https://raw.githubusercontent.com/majiayu000/remem/main/install.sh | sh

# 方式 3：手动下载 GitHub Release
curl -LO https://github.com/majiayu000/remem/releases/latest/download/remem-darwin-arm64.tar.gz
tar xzf remem-darwin-arm64.tar.gz
mv remem ~/.local/bin/
codesign -s - -f ~/.local/bin/remem  # macOS ARM 必须签名

# 方式 4：Cargo 安装
cargo install remem-ai --bin remem

# 方式 5：源码构建
git clone https://github.com/majiayu000/remem.git
cd remem
cargo build --release
cp target/release/remem ~/.local/bin/
codesign -s - -f ~/.local/bin/remem  # macOS ARM 必须签名

# 如果使用 Cargo 或源码安装，配置检测到的 Claude Code/Codex hooks + MCP
remem install

# 可选：明确指定安装目标
remem install --target codex    # auto | claude | codex | all
remem install --dry-run         # 预览配置改动
```

安装后重启对应的 AI 编程工具。

PATH 上建议只保留一个 canonical `remem` 命令。Standalone 和源码安装通常放在
`~/.local/bin/remem`；Windows standalone 安装建议放在
`%USERPROFILE%\.local\bin\remem.exe`。如果使用 Homebrew 或 Cargo 这类包管理器，
后续也通过同一个渠道升级，避免 PATH 前后同时残留第二份手动安装的二进制。
`remem doctor` 和 `remem install --dry-run` 会在检测到多个 `remem` 可执行文件时警告。

### 更新已有安装

手动替换二进制后，需要重新执行 `remem install`，让已有 Claude Code 和
Codex hook 命令刷新到当前 host-aware 配置：

```bash
cargo build --release
cp target/release/remem ~/.local/bin/
codesign -s - -f ~/.local/bin/remem  # macOS ARM 必须签名
remem install --target all
```

验证已安装 hooks 是否包含 host-specific context 命令：

```bash
jq -r '.hooks.SessionStart[]?.hooks[]?.command' ~/.claude/settings.json
jq -r '.hooks.SessionStart[]?.hooks[]?.command' ~/.codex/hooks.json
```

期望看到 host-only command；模型、executor、上下文策略都在
`~/.remem/config.toml`：

```text
/Users/you/.local/bin/remem context --host claude-code
/Users/you/.local/bin/remem context --host codex-cli
```

## 在 Codex 中使用

只配置 Codex：

```bash
remem install --target codex
remem doctor
remem status
```

`remem install --target codex` 会配置三类 Codex 集成：

- 在 `~/.codex/config.toml` 中启用 `[features].hooks = true`
- 在 `~/.codex/config.toml` 中注册 `remem` MCP server
- 在 `~/.codex/hooks.json` 中写入 Codex hook 命令
- 创建或更新 `~/.remem/config.toml` memory-AI profiles

重启 Codex 后，remem 会在 session start 自动注入相关项目记忆，并在 stop
时后台总结本次会话。Codex 也可以调用 `remem mcp` 暴露的 MCP 工具，包括
`search`、`get_observations`、`save_memory`、`workstreams` 和 `timeline`。

默认 Codex 集成刻意保持低噪音：用 `SessionStart` 注入上下文，用 `Stop`
做后台总结。Codex 通过 `[memory_ai.hosts."codex-cli"].context_gate = "strict"`
启用 strict duplicate-injection gate，所以同一 session 里中途重复触发的
`SessionStart` 会在首次注入后保持静默；默认不安装高频 Bash observe hook。

## 发布渠道

当前已发布：

- Homebrew：`brew install majiayu000/tap/remem`
- GitHub Releases：macOS/Linux 的 x64/arm64 预编译二进制
- crates.io：`cargo install remem-ai --bin remem`
- npm：`npm install -g @majiayu000/remem`
- 源码构建：`cargo build --release`

适合继续扩展的渠道：

- apt/yum packages：等 Linux 的安装路径和服务管理方案稳定后再做

## 工作机制

`remem` 使用 host-specific hook 策略自动运行：

```
Claude Code 正常工作流
        |
        |- SessionStart      -> 注入记忆与偏好
        |- UserPromptSubmit  -> 注册会话、刷新旧队列
        |- PostToolUse       -> 捕获工具操作（入队，<1ms）
        '- Stop              -> 后台总结（返回约 6ms）

Codex 正常工作流
        |
        |- SessionStart      -> 注入记忆与偏好
        '- Stop              -> 使用 Codex CLI 后台总结
```

Codex 默认不再安装高频 `PostToolUse(Bash)` observe hook。Shell-heavy 会话必须等 coalesced capture 管线接管后再开启逐命令捕获，否则 Bash 输出会制造无界 backlog。旧 hook 即使残留，也会被默认忽略；只有显式设置 `REMEM_ENABLE_CODEX_BASH_OBSERVE=1` 才会重新开启。

capture 管线从 append-only ledger 开始：`captured_events` 保存原始 hook/session evidence，`event_blobs` 承接大 payload，`extraction_tasks` 按 host/project/session 合并后台提炼任务，避免每个工具调用都生成一个 LLM job。长期记忆仍然是这条管线 promotion 后的结果，不是 raw event 本身。

## 检索架构

`remem` 使用受 [Hindsight](https://github.com/vectorize-io/hindsight) 启发的 4 通道 RRF 融合检索：

```
Query: "database encryption"
        |
   +----+------------------------------------+
   |            4 个并行通道                 |
   +-----------------------------------------+
   | 1. FTS5 (BM25)   trigram + OR           |
   | 2. Entity Index  1600+ 实体             |
   | 3. Temporal      "yesterday"/"last week" |
   | 4. LIKE fallback 短 token 回退          |
   +-------------+---------------------------+
                 |
        RRF score = sum(1 / (60 + rank_i))
                 |
              输出融合后的 Top-K
```

增强能力：

- 实体图扩展（2-hop 多跳检索）
- 项目级隔离检索（避免跨项目污染）
- CJK 分词支持
- 中英文同义词扩展
- 标题加权 BM25（`bm25(fts, 10.0, 1.0)`）
- 基于内容哈希的 `topic_key` 去重
- MCP 工具中的多步检索引导

## 基准概览

### LoCoMo（仅作信息参考）

完整 [LoCoMo](https://github.com/snap-research/locomo) 基准（10 个会话，对抗类跳过后共 1540 QA）：

这个快照只是历史脚注，不作为 CI 或发布门禁。确定性门禁使用 golden
retrieval eval；LoCoMo 仅保留给人工信息参考，因为该基准的方法论已有争议。

| 配置 | Overall | Single-hop | Multi-hop | Temporal | Open-domain | Ingest | Model |
|---|---:|---:|---:|---:|---:|---|---|
| **v1（公平对比）** | **56.8%** | 67.1% | 39.0% | 53.9% | 28.1% | per-turn | gpt-5.4 |
| **v2（优化）** | **62.7%** | 72.3% | 61.3% | 40.5% | 56.2% | session_summary | gpt-5.4 |

### 内部评测（1777 条真实记忆）

| 指标 | 数值 |
|---|---:|
| MRR | 0.858 |
| Hit Rate@5 | 1.000 |
| Dedup rate | 1.0% |
| Project leak | 0% |
| Self-retrieval | 100% |

### 本地端到端 QA 评测

```bash
python3 eval/local/run_local_eval.py --db ~/.remem/remem.db --n 20
```

| 指标 | 分数 |
|---|---:|
| Overall | **85.0%** |
| Decision | 77.8% |
| Discovery | 87.5% |
| Preference | 100% |
| Source in top-20 | 90.0% |

需要显式传入 `--db`，并在项目根目录 `.env` 中配置 `OPENAI_API_KEY`（可选 `OPENAI_BASE_URL`、`OPENAI_MODEL`）。

## Token 使用量与费用统计

remem 会为自己的后台提炼、总结、压缩、promotion 调用写入 AI usage
账本。CLI 可以查看每日、每周 token 使用量和估算费用：

```bash
remem usage --days 14 --weeks 8
remem usage --project /path/to/project --days 30 --weeks 12
```

报表包含调用次数、input/cache/output/reasoning token、total token、估算
美元费用，以及统计精度说明。usage row 会标记来源：

- `anthropic_usage`：Anthropic Messages API 返回的 provider usage
- `codex_log`：从当前 `codex exec --json` 的 `turn.completed.usage`
  事件解析出的精确 token count
- `text_estimate`：拿不到真实 usage 时，用 prompt/response 文本长度估算

费用是估算，不是账单。历史数据可能是文本估算，也可能从旧的无精确模型记录
重估过。

## Memory AI 配置

Memory AI 执行策略配置在 `~/.remem/config.toml`（可用 `REMEM_CONFIG`
覆盖路径）。hooks 只传 `--host`；config 负责把每个 host 映射到一个 profile，
统一用于 summarize、flush/extract、compress 和 dream。

```bash
remem config path
remem config show
remem config set memory_ai.profiles.codex.model gpt-5.4-mini
```

日常切模型推荐用更高层的 `remem model` 命令：

```bash
remem model current
remem model list
remem model use cheap
remem model use balanced --dry-run
remem model use gpt-5.2 --reasoning medium
remem model use haiku --host claude-code
remem model test
remem model test --live
remem model rollback
```

`remem model test` 默认只校验配置，不产生 AI 调用成本；只有加 `--live`
才会实际调用模型。`remem model use` 写入配置前会保存 rollback 备份。内置
preset 主要面向 Codex；Claude Code profile 建议直接传明确模型名。

默认 Codex profile：

```toml
[memory_ai.hosts."codex-cli"]
memory_profile = "codex"
context_gate = "strict"
context_color = true
capture_adapter = "codex-cli"

[memory_ai.profiles.codex]
executor = "codex-cli"
model = "gpt-5.4-mini"
reasoning_effort = "low"
path = "codex"
```

## 常用命令

```bash
remem install
remem uninstall
remem doctor
remem search "query"
remem search "query" --branch main --type decision --multi-hop --offset 10
remem show <id>
remem eval
remem eval-local
remem backfill-entities
remem encrypt
remem api --port 5567
remem status
remem config show
remem config set memory_ai.profiles.codex.model gpt-5.4-mini
remem model current
remem model list
remem model use balanced --dry-run
remem model use gpt-5.2 --reasoning medium
remem model use haiku --host claude-code
remem model test [--live]
remem model rollback
remem usage --days 14 --weeks 8
remem pending list-failed
remem pending retry-failed --dry-run
remem pending purge-failed --dry-run --older-than-days 7
remem review list
remem review approve <id>
remem review discard <id>
remem review edit <id> --text "updated memory"
remem preferences list
remem preferences add "text"
remem preferences remove 42
remem context --cwd .
remem cleanup --dry-run --json
remem cleanup
remem dream [--project X] [--profile NAME] [--dry-run]
remem install --target codex
remem mcp
remem sync-memory --cwd .
```

## REST API

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

直接使用库 API 构建 router 的调用方，应在 `remem::api::build_router(...)`
之前调用 `remem::api::ensure_api_token()`。

| Endpoint | Method | 说明 |
|---|---|---|
| `/api/v1/search?query=&project=&type=&limit=&offset=&branch=&multi_hop=` | GET | 检索记忆 |
| `/api/v1/memory?id=` | GET | 获取单条记忆 |
| `/api/v1/memories` | POST | 保存记忆 |
| `/api/v1/status` | GET | 系统状态 |

## 安全性

- SQLCipher 静态加密（`remem encrypt`）
- 数据目录权限（`0700`）
- 密钥文件权限（`0600`）
- REST API 仅绑定本机（`127.0.0.1`），并要求
  `Authorization: Bearer $(cat ~/.remem/.api-token)`
- API token 文件权限（`0600`）

## 架构文档

详细设计见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。

## 卸载

```bash
remem uninstall
rm -rf ~/.remem
```

## License

MIT
