vshulcz/deja-vu · 上手攻略

  • 仓库：vshulcz/deja-vu
  • 链接：https://github.com/vshulcz/deja-vu
  • 分类：agent / llm-infra（本地记忆层）
  • 作者：spark
  • 更新：2026-09-01

是什么

deja-vu 是一个本地、单二进制（Go 语言）、零 LLM/零 embedding 的「会话历史反向检索层」。它不记录未来，只索引过去——扫描 Claude Code、Codex、Cursor 等 21 款 AI 编程 agent 已经写到磁盘的会话历史（JSONL / SQLite 等），去重脱敏后建立倒排索引，让你（在任意 agent 里）能反查到「三个月前那次 debug」「哪个 agent 跑过同一条报错命令」。README 直白写："Every memory tool starts empty and records forward. deja starts full."

核心特征四点：① 索引对象是 agent 已经写入的 transcript，不侵入式记录；② 默认纯本地，只有 deja sync ssh / deja update 等显式动作才出网；③ 索引时即做 redaction（AWS key、JWT、PEM、Bearer、高熵未知模式 → [redacted:<kind>]），缓存文件可安全留存；④ 把「记忆」统一为一层，所有 agent 都通过同一个 MCP recall/recall_context/blame/fix/how/remember 工具访问。

解决什么问题

每个用 AI 编程的人都被这些场景困住过：

  • 「上个月我们在哪个 session 解决过 JWT refresh token kid mismatch？」
  • 「这台机器上用什么命令真的跑通了 X？」（不是文档说的，而是这台机器某次确实跑过）
  • 「这条 error 我上次怎么修的？」
  • 「agent 重复我三个月前已经修过的一个 bug」

普通 memory 工具（Mem0、Letta、memU、engram）都从空开始、需要 agent 或代码主动写事实（"record-forward"），回想能力取决于 agent 记得几次。deja-vu 走另一条路：recall-forward——直接读磁盘上 agent 早就写下的 transcript，第一次启动就把"过去几个月的所有 session"装进倒排索引，并把它接到每个 agent 的会话开头、PreToolUse/PostToolUse hook。

快速安装

README 给出三种零依赖 + 一条 marketplace 路线，按推荐程度排：

# 1) 一行安装脚本（macOS/Linux，自动配 PATH）
curl -fsSL https://raw.githubusercontent.com/vshulcz/deja-vu/main/install.sh | sh
deja install --auto   # 把 MCP 接进所有检测到的 agent，并构建首份索引

# 2) Homebrew（macOS/Linux）
brew install deja-vu

# 3) Go 安装（已有 Go 工具链的开发者）
go install github.com/vshulcz/deja-vu/cmd/deja@latest

# 4) 零安装试一把
npx @vshulcz/deja-vu "query"

要把 MCP 接到 Claude Code / Codex / Cursor / Qwen / OpenClaw / Copilot，还可以用各家的 marketplace：

claude plugin marketplace add vshulcz/deja-vu && claude plugin install deja-vu@deja-vu

Windows：scoop install deja-vu，或在 latest release 拿 .zip 解出 deja.exe 放进 %USERPROFILE%\.local\bin。⚠️ README 明说 install.sh 在 Windows 上 exit unsupported OS（这是个 shell 脚本）。

只想要搜索能力、不要 MCP 集成？二进制本身就完整：deja index 构索引，deja search、show、ctx、blame、--json 都能跑。deja install --all 是 --auto 但不开 session-start recall（让 agent 自己决定何时调用）。deja doctor 会把"未接 MCP"标红，这是 binary-only 模式的预期表现。

核心用法

1. 直接 grep 自己的历史

$ deja "jwt refresh token"
[claude] api · Jul 8 · 8f31c0a9 — 2 matches
 login started failing after refresh token rotation; jwt kid mismatch in tests
 fixed by reloading jwks cache after rotateKey and adding a clock-skew test
[codex] web · Jul 1 · b77d91e2 — 1 match
 refresh token cookie needed SameSite=Lax in local callback flow

多词是 AND；带引号是字面连续；无精确命中会回退到词形/拼写近似（README："code finds opencode"）。

2. 「这条命令在我机器上到底怎么跑的」

deja how <tool>          # 真实历史里 agent 用过哪些 flag
deja fix <error>         # 这台机器上相同错误之后是怎么被修掉的
deja friction            # 出现过 ≥3 个 session 的"墙"，点名 harness
deja blame <path>        # 哪些 session 讨论过这个文件、决定是什么、为什么
deja files <topic>       # 反向：关于这个主题实际触碰了哪些文件

deja ctx <query> 给一段 markdown digest，可以直接 deja ctx "..." | pbcopy 喂进 prompt。deja resume <id> 在原 harness 里重新打开那个 session。deja restore <path> 还原被编辑替换过的 span（基于编辑时记录的 old_string，从不动原文件）。

3. 拒绝决策也要记

deja promote <id> --state rejected --note "why"

被 mark rejected 的决策，后续每次命中都会显示「尝试过但被否决，原因：...」。什么都不删，用 --state accepted 可撤回。

4. 跨机搬迁

deja sync export > memory.watermark
deja sync import < memory.watermark
deja sync ssh laptop                          # 追加式、无云端
deja handoff --to codex                       # 把 live context 打包到另一个 agent

都带 watermark、append-only、idempotent。

5. 凭据脱敏

索引时即扫：AWS keys、api_key=、token=、Bearer JWT、PEM 块、provider token、scheme://user:pass@host、未知高熵模式 → 替换为 [redacted:<kind>]。deja share 和 deja sync export 出门再脱一次。要永久忘掉某个 session：

deja forget <session-id>      # 写 tombstone，后续 index 无法从源历史恢复
deja forget --unforget <id>   # 解除 tombstone
# 项目级排除：~/.config/deja/exclude 每行一个 glob

6. 想升级到向量召回（可选）

export DEJA_EMBED_URL='http://localhost:11434/v1/embeddings'
export DEJA_EMBED_MODEL='nomic-embed-text'
deja embed

支持任何 OpenAI 兼容端点。⚠️ 关键安全约束：除非 DEJA_EMBED_URL 是 HTTPS 的 api.openai.com，OPENAI_API_KEY 不会被自动发到该端点；自定义端点必须显式设 DEJA_EMBED_KEY，它优先级高于 OPENAI_API_KEY。向量放在索引旁的 .vectors.bin（不进 index.db），float32 一千维模型大致 4 MB / 1k messages。

7. 接进 harness

deja install --auto 会给以下 harness 写用户级指引：Claude Code、Codex、opencode、Gemini CLI、Antigravity、Qwen、Kimi Code、pi、Copilot、Cursor、Goose、OpenClaw、Hermes、Roo Code、omp、DeepSeek Harness、Zed。要 opt out：deja install --all --no-guidance。Grok Build 只读 ~/.agents/skills/，那里的 community ~/.grok/GROK.md 与本项目无关。Cursor 没有 user-level instructions 文件，只得到 ~/.cursor/skills/ 下的技能。Rust/Go 用 Skim/IDE 还要外加 sqlite3（Cursor 的 IDE chats）或 paste + zstd（DeepSeek Harness）才能解析。

支持的 21 款：aider / Antigravity / Claude Code / Cline / Codex CLI / Copilot CLI / Cursor / DeepSeek Harness / Gemini CLI / Goose / Grok Build / Hermes / Kimi Code / omp (Oh My Pi) / OpenClaw / opencode / pi / prime-agent (PrimeIntellect) / Qwen Code / Roo Code / Zed。完整支持矩阵见 README 表（涵盖 MCP recall、auto-recall、skill、command、resume、handoff 六维度，每行还注明"需要 sqlite3 / paste / zstd" 等额外依赖）。

8. 体检与统计

deja doctor [--deep]   # 自检 + 拿源数据证明索引
deja stats             # 汇总；--card 画终端卡片，--card <file>.svg 出 README 头像
deja view              # 把整本记忆渲染成单个本地 HTML，零服务器

9. MCP 工具清单

当 agent 通过 MCP 接入时，暴露 6 个工具：recall(query, harness?, limit?, offset?) → 命中片段，截到 4 KB；recall_context(query, harness?) → 最佳匹配的 markdown digest；blame(path, harness?, project?, since?, limit?, all?) → 讨论过该文件的 session；fix(error, project?, limit?) → 同错修复历史；how(what, project?, limit?) → 真实历史里的调用方式；remember(text, project?, tags?) → 写入一条长效决策（凌驾原始 transcript）。详细参数 + 返回 schema 见 docs/json-output.md。

10. 一键卸载

deja uninstall --all
rm -rf ~/.cache/deja

典型适用场景

  • 多 agent 多项目切换：Codex 上修一个 bug、两周后在 Cursor 提问「JWT refresh 我们当时怎么改的？」 → 走 recall 直接召回原始 session + 决定。
  • 团队新成员 Onboarding：把 deja sync export 分享给他（已自动脱敏），新人能搜这台机器上所有"我们之前怎么做的"答案。
  • 长期项目：compaction 之后，过去 99.8% 的命令会丢，只剩 0.2%。deja ctx <query> 把决策还原回 prompt；README 给出 43 次 compaction 测得的「决策保留率 77%」、「命令保留率 0.2%」。
  • 想反查"哪个 session 解决过 bug X"：用 deja blame <path> 或 deja files <topic> 反向走。
  • 跨机搬迁 memory：出差时在笔记本上做的工作，return 后 deja sync ssh laptop 合回主机；或在新机器 import 一次到位。
  • 红队/运维：rejected 决策保留机制让"我们试过 A 因为 X 不行"这种知识不再丢。

坑与注意

  1. ⚠️ 「无需 LLM」指的是默认 lexical 召回——不上 deja embed 时就是 BM25 风格倒排检索；要语义召回必须配 DEJA_EMBED_URL。如果只是想「能搜」，默认安装的 deja doctor 会把"未接 embedding 端点"列成 warning，这是预期行为，README 明说。
  2. ⚠️ 索引大小与体积——5.2 GB 历史 → 索引 160 MB（≈3%）。倒排索引在 ~/.cache/deja/，增量更新：session 文件增量时才重读。建议放开 macOS Spotlight / Windows Search 不索引这个目录，否则 mdfind/搜索体验会变慢。
  3. ⚠️ Project 排除在 ~/.config/deja/exclude——一行一个 glob；不写就是全量。记得开 redaction 检查：deja share / deja sync export 再脱一次，但 audit 时仍以 raw transcript 为准（README："They stay in the original harness files, which are your agent's data. They do not enter deja's index..."）。敏感项目请同时把源 transcript 目录加进 .gitignore，deja-vu 不会回溯清理已经写到磁盘的旧文件。
  4. ⚠️ aider 的 MCP recall 是 ⚠，README 注"blocked by an upstream bug"；Roo Code 的 auto-recall 也是 ⚠；Copilot CLI 和 Zed 的 auto-recall 是 ✕（harness 没提供机制）。装之前看清楚自己主力 harness 在哪些格子里是 ✅ / ⚠ / ✕。
  5. ⚠️ Windows 实战路径 = Scoop + release zip；.mcpb（桌面 app bundle）路径适合 Windsurf / Cursor Desktop 这种接受 .mcpb 的环境。
  6. ⚠️ deja install 写用户级指引会改以下文件或目录：~/.claude/CLAUDE.md、~/.codex/...、~/.config/opencode/...、~/.gemini/...、~/.qwen/...、~/.kimi/...、~/.pi/...、~/.cursor/skills/、~/.local/share/omp/...、~/.config/zed/settings.json 等。机器上多人共用一个 user 账号时慎重，会被复写——deja install --all --no-guidance 可以跳过这块，但失去了 harness 主动触发 recall 的能力。
  7. ⚠️ prime-agent (PrimeIntellect) 全 —（possible, not built yet）——README 没列依赖项，连 ? 都没给，意味着尚未实地集成；如果该 harness 是你主力，目前别指望。
  8. ⚠️ hook 性能：PreToolUse / PostToolUse 每次都在跑，包含 process start + freshness check，几 GB 索引也只多几十 ms。1,551 sessions / 143k messages 实测：单次 deja <query> 端到端中位 0.2 s，但 freshness check 单独 ~30 ms（无变化时）。在小机器大索引场景，Hook 叠加仍可能是感知到的卡顿，建议先关 auto-recall、保留 MCP 按需调用观察几天。
  9. ⚠️ deja forget 写 tombstone 但不清理源 harness 文件——rebuild index 后也无法从源历史恢复；要"真删"再 deja forget 后用 deja index --rebuild，并自己处理原始 transcript（~/.claude/projects/、~/.codex/sessions/ 等）。
  10. ⚠️ 数据出境——deja update、deja sync ssh、版本检查 都会出网；离线场景请把 deja update 关掉（README 在 "Indexing and search are local" 段只列了 3 个出网动作，但版本检查在 deja doctor 里也会发请求）。

关键数字（README 给出，2026-08-31 截至）

  • Stars：744（web_search 一致返回 737~744，README 仓库头标 744 为准）
  • 索引 ~25 ms on LongMemEval-S haystacks / 0.4 ms median 内进程查询
  • 5.2 GB 实测 corpus（1,551 sessions / 143k messages、9 个 harness）→ 索引 160 MB（≈ 3%）
  • 85.3% hit@1 on LongMemEval-S · 69.6% on LoCoMo（README 自报；bench harness 在仓库内，可在公开数据集上复跑 → vshulcz.github.io/deja-vu/guide/benchmarks.html）
  • context 实验：默认 seed 下，deja-recall 中位 token 286 / coverage 1.00；full-history 16,919；naive-grep 57,489；cold 0 / 0.00。比 raw grep 节省约 200× token，比回放匹配 session 省约 60×。 ⚠️ README 自陈："Audit what 'relevant' means before trusting any figure, ours included."
  • compaction 实测 43 次：决策保留率 77% / 命令保留率 0.2%——deja 把后 99.8% 还回来
  • 21 个 harness 支持矩阵；6 大能力维度（MCP recall / auto-recall / skill / command / resume / handoff）
  • 装一个大项目首发索引约 10 s（README 自报）
  • Float32 向量成本：~4 MB / 1k messages（1,024 dim 模型）
  • 最近提交：2026-08-31

与同类对比（按 README 自陈）

维度 deja-vu Mem0 / Letta / memU cass（session search）
装之前的事也能搜 yes no yes
写入步骤 无（transcript 即记忆） agent / 代码要写事实 无
必须 LLM/embedding key no yes optional
主动 recall 会话开头 + 编辑前 + 命令前后 否 否

README 还点名 engram（Gentleman-Programming/engram）是 record-forward 工具里最强的，如果「我让 agent 主动记事实」这个范式适合你，可以看 engram；engram 仍然从空开始、只知道 agent 主动保存的。整个对比见 How it compares，覆盖 11 款。

常见问答（README FAQ 摘要）

  • 会变慢吗？ 不会——lexical lookup ~0.4 ms，hook 额外 + 几十 ms freshness check。
  • 必须改工作流吗？ 不必。agent 自己会调 recall；开 auto-recall 后 session 一开就自动知道历史。
  • Windows？ build 存在、CI 跑，macOS / Linux 是实战打磨路径，欢迎反馈（#9）。

一句话推荐结论

用过 Claude Code / Codex / Cursor 任一一段时间的人，装一个 deja install --auto，10 秒安装、10 秒建索引，就能让所有 agent 反查到几个月前的 session；不想接 MCP 就只装二进制先用 deja <query>，再按需升级到 embedding 召回。

不确定/未能验证： - Windows 上 scoop install deja-vu 与 release zip 两种路径在中文路径 / OneDrive 同步目录下的稳定性，README 没明说。 - ~/.cache/deja 在 macOS 14+ 的「应用程序沙盒」路径下行为，未实测。 - deja bench recall 在不同 OS 上的「ranking regression floor」具体阈值与 CI fail 触发门槛，仓库文档里只描述行为未公开数值，建议直接跑仓库内 bench。 - 21 款 harness 支持矩阵的 ⚠ 项（aider / Roo Code），是已锁定等 upstream 修复还是临时绕过，未在 README 里区分清楚，要用之前翻 GitHub issue。