跨智能体会话记忆 vshulcz/deja-vu

你的编码智能体不再重复调试你已经修好的问题。

Claude Code、Codex、Cursor、OpenClaw、Gemini CLI、OpenCode、Hermes 以及另外 36 个智能体，早已把每个会话存到磁盘。
deja 在本地为这些内容建索引，再通过 MCP 和钩子把相关的历史交还给智能体——不用 LLM，只有一个 Go 二进制文件。

官网与交互式搜索 · 浏览器在线演示 · 文档 · 基准测试 · 对比 · 集成到你的工具

curl -fsSL https://raw.githubusercontent.com/vshulcz/deja-vu/main/install.sh | sh
deja install --auto

macOS 和 Linux · Windows、Homebrew、npm 和插件市场 · 或者不安装，先看看磁盘上已经有什么：npx @vshulcz/deja-vu sources · 在浏览器里试用 →

召回97.2% R@5，LongMemEval-S 上MemPalace 公布 96.6%，agentmemory 95.2% Tokentoken 用量只有 agentmemory 的一半在这台机器已经解决过的任务上索引时间13.6 s 索引 19,195 个会话七个工具里的第二名要 72 s

每个驱动、语料和评分规则都在这个仓库里：正面交锋 · 全部基准测试运行

自己搜一搜

不带参数运行 deja，会打开一个终端搜索界面，覆盖每个智能体的历史记录——先列出你未提交改动背后的会话，再列出当前项目的近期工作。

- 导航： ↑↓ 选中会话，↵ 在匹配处打开，/ 在会话内搜索，] 在轮次之间跳转，^s 切换按日期/相关度排序（deja search --sort date）。
- 筛选： 按智能体（codex:）、时间（today、yesterday、week、month）或项目（in:<project>）。
- 恢复或交接： r 在原生智能体里重新打开会话；o 在另一个智能体里继续它，带上目标、决定和未完成的工作。
- 找回已删除的对话： tab 在本项目、所有项目和 Deleted（智能体清除过、但 deja 仍保留的会话）之间切换；R 恢复一个，D 删除（deja delete <id>），? 列出所有按键。

更喜欢浏览器？deja view 把存储导出成一个本地 HTML 文件——会话、召回审计记录和提升的笔记都在里面（[试试在线演示）。设置 DEJA_TUI=0（或运行 deja brief），deja 会打印纯文本摘要。

亮点

- 第一天就全量启动。 全部四十三种智能体过去几个月的记录立刻可搜——在 Codex 里修过的 bug，Claude Code、Cursor 或 OpenCode 都能回想起来。
- 通过钩子和 MCP 自动召回。 在会话开始时、编辑文件或运行命令之前、命令失败时，把此前的会话呈现出来。
- 扛得住压缩。 实测 43 次压缩，摘要保留了 77% 的决策和 0.2% 的命令；其余部分由 deja 交还（原理）。
- 索引代码改动，不只是聊天。 跟踪打开的文件、带退出码的命令，以及精确的 Edit 片段（deja blame <file>:<line>、deja restore <path>）。
- 跟踪决策生命周期与过期状态。 deja promote <id> --state rejected 标记被回退的做法，之后命中时会提示当初为何放弃（--state accepted 撤销标记）；会话触碰过的文件此后有变动，命中结果也会报告。
- 默认本地、默认私密。 零 LLM 调用，无需云账号，索引时自动脱敏凭据（隐私）。

你自己的成果，打包呈现

deja stats --card 在终端里画出你这一年的智能体活动，或写出 SVG 供 GitHub 个人主页使用（在浏览器里转成 PNG）。

安装

install.sh 把 deja 二进制放进 ~/.local/bin，deja install --auto 把 MCP 召回和钩子接入每个检测到的智能体，并建立初始索引（约 10 秒）。

在任何已接入的智能体里开个新会话，它已经知道你在这个仓库里解决过什么——或者直接问它（have we dealt with jwt refresh rotation before?）。

Homebrew、Windows（Scoop / winget）、npm、插件市场，以及仅二进制安装

brew install deja-vu、go install github.com/vshulcz/deja-vu/cmd/deja@latest，或 npx @vshulcz/deja-vu "query"，什么都不装就能试用。把 MCP 服务器当作
包接收的桌面应用，可以打开最新发布里的 .mcpb；它自带二进制。

Codex CLI、opencode、Claude Code、Qwen 和 OpenClaw 也能直接从各自的市场或注册表安装插件包（见自带安装包的运行环境， Cursor 另见 cursor-plugin/）。Copilot CLI 也安装市场包，不过它只取其中的技能——钩子和 MCP 请用 deja install copilot-auto：

codex plugin marketplace add https://github.com/vshulcz/deja-vu && codex plugin add deja-vu@deja-vu
opencode plugin opencode-deja
claude plugin marketplace add vshulcz/deja-vu && claude plugin install deja-vu@deja-vu

在 Windows 上，安装脚本会以 unsupported OS 退出——它是 shell 脚本。改用 Scoop（每个 Scoop 安装都自带的主 bucket 里就有），或者用 winget（Windows 自带）： powershell scoop install deja-vu winget install vshulcz.deja-vu

也可以从最新发布下载 deja-vu_<version>_windows_amd64.zip，把 deja.exe 放进 PATH，比如 %USERPROFILE%\.local\bin。

只装二进制文件就能完整搜索：索引、搜索、show、ctx、blame、--json 和脱敏都不需要别的东西。deja install 负责把 MCP 接进你的智能体，并打开会话启动时的回忆——值得装，但可选。只装二进制时，deja doctor 会把每个 MCP 目标报成 config missing，智能体已安装的地方则报 not-wired，这正是该配置的预期表现。deja warmup 还会在 ~/.agents/skills/deja-search/SKILL.md 留一个技能，教智能体命令行约定——deja recall、ctx、blame、怎么读回忆页、怎么要下一页——这样它不用 MCP 也知道历史可搜索。仓库里的副本在 skills/deja-search/SKILL.md。

deja install --all 等于 --auto 去掉会话启动时的回忆：智能体自己决定调用时才从记忆里回答，而不是每个会话一开始就带着它。智能体配置指南讲了每个 harness 支持什么、aider 的只读上下文文件，以及 Windows 的 cmd /c deja mcp 包装。

每个智能体自己的指导文件里会写入什么安装时，还会为检测到的 harness 写入用户级指引：Claude Code、Codex、opencode、Gemini CLI、Antigravity、Qwen、Kimi Code、pi、Senpi、Copilot、VS Code Copilot Chat、Goose、OpenClaw、Hermes、Roo Code、omp、Amp、prime-agent、DeepSeek Harness、Continue、Crush、CodeBuddy Code、WorkBuddy、Zed、TRAE CLI、TRAE IDE、Muse Code、CodeWhale、ZCode 和 Junie，各自写入自己的指引文件（或写入配置的 XDG_CONFIG_HOME 下）。重新运行会重写 deja 的技能或标记块，不改动周围的用户内容。用 deja install --all --no-guidance 可以跳过这一步；Grok Build 和 Devin CLI 拿到的是 ~/.agents/skills 里的共享技能，它们读的就是这个位置；旁边写出的 ~/.grok/GROK.md 是给共用该目录的另一个社区命令行用的，与它们无关。Cursor 没有用户级指令文件，所以拿到的是 ~/.agents/skills 里的共享技能——这是 Cursor 读取技能的四个位置之一——只在内容看起来相关时才读，而不是每个会话都读。Kilo Code、gajae-code、Kimchi、Command Code、Cherry Studio 和 Reasonix 拿到技能，MiniMax Code 在插件包内拿到技能，Kiro 拿到技能和一个 steering 文件，都来自各自的安装目标。

隐私

索引和搜索都在本地进行。只有这些操作会用到网络：deja update、deja sync ssh、deja doctor 里的版本检查、deja embed 访问你配置的端点（以及语义 sidecar 建好之后，每次搜索都会把查询发到该端点），还有交互式命令每天一次查看最新版本。这次查看不发送任何会话数据；DEJA_OFFLINE=1 可以关掉它，把 DEJA_NO_UPDATE_NOTICE 设为任意值也能关掉，后者还会隐藏新版本首次运行时打印的提示。

建立索引时会剥离凭据：云服务商和服务商密钥、token 和 JWT、PEM 块、URL 里的密码或正文里写明的密码。每处都替换成 [redacted:<kind>]，周围的文字仍然可以搜索。源转录文件里仍然保留着它们（有一台机器在 42 个会话里有 84 处）：deja secrets 会列出这些会话，但不打印具体值；deja secrets --scrub 会重写它能处理的部分，并把原文件留在旁边。

deja forget 会丢弃会话，重建索引后也不会恢复。~/.config/deja/exclude 每行跳过一个项目，或者用 harness:opencode 跳过整个存储。数据流向以及脱敏无法覆盖的情况，见安全模型。

命令行

在终端里直接运行 deja 会打开搜索界面。带上查询词，或者运行下面任意命令，它会打印结果后退出： text
$ 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 需要 SameSite=Lax

查询历史

| 命令 | 作用 |
| deja <query> | 搜索全部历史。多个词之间是 AND 关系，带引号的短语要求文本连续；查询没有精确匹配时，会再尝试词形变化和相近拼写，子串就是这样命中它所在的词（code 能找到 opencode）。--sort date 按最新匹配优先列出。 |
| deja | 在终端里打开上面的全屏搜索。deja brief 改为打印文字摘要：今天的会话、deja 提供过什么、最近的工作，以及一条可以试试的搜索。 |
| deja wip | 这个目录里上一次会话在做什么：任务是什么、定下了什么、正在改哪些文件、最后一条命令，以及它是否失败——全部从对话记录推导，不靠谁记得写下的笔记。 |
| deja blame <path>[:line] | 哪些会话讨论过某个文件、决定了什么、为什么。带上行号时：最后一次改动它的提交，以及写下那一行或写下被该提交替换掉的文本的会话。--attribution 只打印行号答案，加 --json 输出 JSON，--git-note 把它记录到 refs/notes/deja。 |
| deja files <topic> | 反方向查：围绕某个主题的工作实际碰过哪些文件。 |
| deja how <tool> | 这台机器实际怎么跑某个东西，带真实参数，依据是智能体以前的运行记录。 |
| deja fix <error> | 同一个错误以前出现时，这台机器在它没再复发的情况下接着跑了什么。绝不会是合并、强制推送或删除。 |
| deja friction | 命中三个及以上独立会话的错误，并列出对应的 harness。 |

裸查询的第一个词至少有四个字符，且与某个命令名只差一次编辑时，deja 会在 stderr 上点出那个命令，然后照常搜索。deja search <query> 跳过这个提示。

使用搜到的内容，以及在机器之间搬运

使用搜到的内容

| 命令 | 作用 |
| deja ctx <query> | 最佳匹配的 Markdown 摘要，附带它改过的代码，可直接管道送进提示词。 |
| deja recall <words> | MCP recall 工具交给智能体的那一页：约 4 KB，本项目优先（DEJA_RECALL_GLOBAL=1 让所有项目排名相同）。适合通过 shell 调用 deja 的技能和脚本。 |
| deja resume <id> | 在会话原生的 harness 里重新打开搜到的会话。--app 在 ChatGPT 桌面应用里打开 Codex 会话。 |
| deja restore <path> | 交回智能体替换掉的一段内容，来源是它那次编辑记录的 old_string。绝不覆盖原文。 |
| deja promote <id> | 把会话提炼成一条精选笔记，带出处、标签和生命周期状态。笔记的优先级高于原始对话记录。 |
| deja share <id> | 给同事的脱敏会话摘要，密钥已清理干净。 |

搬运与检查

| 命令 | 作用 |
| deja sync export/import/ssh | 在机器之间搬运记忆。带水印、只追加、幂等。 |
| deja view | 把全部记忆导出成一个本地 HTML 文件（在线演示）。不需要服务器，文件始终留在本机。 |
| deja stats | 你的智能体工作年度总结。--card 在终端里画出来，--card <file>.svg 为某个配置档写一份，--html 生成可浏览的时间线。 |
| deja secrets [--scrub] | 哪些会话的源转录里带有凭据，以及是哪一类。从不打印具体值。--scrub 重写能改的那些，原文件保留在旁边。 |
| deja rules [sync] | 把常驻规则放在 ~/.config/deja/rules.md；sync 把它们作为标记块复制进每个已安装智能体的全局规则文件。 |
| deja rules candidates [--json] [--limit n] [--since 90d] | 你纠正智能体的那些轮次，跨所有工具，按会话编号。让智能体给出规则建议，它会分组；你选定之前不写入任何内容。 |
| deja doctor [--deep] | 自诊断；加上 --deep，对照源文件校验索引。 |
| deja mcp | stdio MCP 服务器，也就是 deja install 接入的那个。 |

完整参考：命令和 JSON 输出。

MCP 工具

服务器只暴露一个工具 deja，带一个 mode 参数；deja install 负责接入。一个工具每轮消耗 477 个 token 的定义，而 day zero 里实测的七个服务器中最大的那个要 8,283 个。六个旧工具名（recall、recall_context、blame、fix、how、remember）仍然可用。deja mcp --context-search 是另一个服务器，只有一个 context_search 工具，面向 Qwen Code 的 External Context MCP Profile v1（Qwen 页面）。

参数与返回结构

| 工具 | 参数 | 返回 |
| deja | mode、q、harness?、project?、limit? | 取决于下面的 mode。 |

q 承载 mode 要查询的内容。下面各 mode 的专用参数名仍然接受；它们不再声明，因为无论是否调用工具，schema 每轮都会被读取。

| Mode | q 是 | 还读取 | 返回 |
| recall | 1-3 个精确词：文件路径、错误字符串、标志或标识符 | harness?、limit?、offset? | 密集的匹配片段，上限 4KB。 |
| context | 与 recall 相同 | harness? | 最佳匹配会话的 Markdown 摘要，附带它改过的代码。 |
| blame | 文件路径 | harness?、project?、since?、limit?、all? | 讨论过某文件的会话。 |
| fix | 失败输出，原样传入 | limit? | 本机此前遇到同一错误后运行或改动了什么。 |
| how | 工具或目标，例如 go test | project?、limit? | 真实调用方式，来自智能体在本机的实际运行。 |
| orient | 不需要参数——它会主动询问项目情况 | project?、limit? | 过往会话在此运行过的命令，以及它们操作过的文件。 |
| remember | 一条持久事实或决策 | project?、tags? | 存下一条持久决策，供以后召回。 |
| handoff | 会话 id 或 harness 名称；留空则取此处最新的会话 | harness? | 另一个会话的目标、常驻指令、最新结论、已通过的检查以及停在哪里，用来接着做。 |

支持的 harness

aider · Amp · Antigravity · Claude Code · Cline · Codex CLI · Copilot CLI · VS Code Copilot Chat · Cursor · DeepSeek Harness · Gemini CLI · Goose · Grok Build · Hermes · Kimi Code · omp (Oh My Pi) · OpenClaw · opencode · Continue · Crush · pi · prime-agent (PrimeIntellect) · Qwen Code · Cherry Studio · Senpi · gajae-code · Kimchi Coding · Command Code · ZCode · Kiro · Kilo Code · Roo Code · Zed · Devin CLI · CodeWhale · Junie · JetBrains AI Assistant · Windsurf / Devin Desktop · CodeBuddy Code · Reasonix · TRAE CLI · Muse Code · MiniMax Code。

各自支持什么

| Harness | MCP 召回 | 自动召回 | 技能 | 命令 | 恢复 | 交接 | 依赖 |
| aider | ⚠ | ✅ | ✕ | ⚠ | ✕ | ✅ | deja aider |
| Amp | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 0.0.1774963753 起的 threads 在 ampcode.com 上实时可用；deja 读取其插件写出的那些，以及更早的本地记录 |
| Antigravity | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| Claude Code | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| Cline | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| Codex CLI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| Copilot CLI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| VS Code Copilot Chat | ✅ | ✅ | ✅ | ✅ | ✕ | ✅ | — |
| Cursor | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | sqlite3（IDE 聊天、CLI 工具输出） |
| DeepSeek Harness | ✅ | ✅ | ✅ | ✅ | ✕ | ✅ | zstd |
| Gemini CLI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| Goose | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | deja goose |
| Grok Build | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | sqlite3（grok-dev 存储） |
| Hermes | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | sqlite3 |
| Kimi Code | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| omp (Oh My Pi) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| OpenClaw | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | sqlite3（2026.8+ 存储）；.zst 归档与压缩事件需要 zstd（2026.9.9+） |
| opencode | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | sqlite3 |
| Continue | ✅ | ⚠ | ✅ | ✅ | ✅ | ✅ | — |
| Crush | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | sqlite3 |
| pi | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| prime-agent (PrimeIntellect) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| Qwen Code | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| Cherry Studio | ✅ | ✅ | ✅ | ✕ | ✕ | 粘贴 | 在 Settings -> MCP 里导入一次服务器；为智能体启用技能 |
| Senpi | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 无 |
| gajae-code | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 无 |
| Kimchi Coding | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 无 |
| Command Code | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 无 |
| ZCode | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 命令行数据库需要 sqlite3 |
| Kiro | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 命令行数据库需要 sqlite3 |
| Kilo Code | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 命令行存储需要 sqlite3 |
| Roo Code | ✅ | ✕ | ✅ | ✅ | ✅ | 粘贴 | roo 命令行（编辑器任务会在编辑器里重新打开） |
| Zed | ✅ | ✕ | ✅ | ✅ | ✕ | 粘贴 | sqlite3 + zstd |
| Devin CLI | ✅ | ✅ | ✅ | ✕ | ✅ | ✅ | sqlite3 |
| CodeWhale | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 无 |
| Junie | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 无 |
| JetBrains AI Assistant | ✅ | ⚠ | ⚠ | ⚠ | ✕ | 粘贴 | 无 |
| Windsurf / Devin Desktop | ✅ | ⚠ | ✅ | ✅ | ✕ | 粘贴 | 无 |
| CodeBuddy Code | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 无 |
| Reasonix | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 1.x 会话需要 zstd |
| TRAE CLI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 无 |
| Muse Code | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 无 |
| MiniMax Code | ✅ | ✅ | ✅ | ✕ | ✅ | ✅ | deja resume 和 deja handoff --to mcode --exec 需要 MiniMax Code 命令行（mcode）；会话工作区需要 sqlite3 |

✅ 可用 · — 可行，尚未实现 · ✕ 该 harness 没有这种机制 · ⚠ 取决于 harness 本身 · ? 未调查

TRAE IDE 只做接线，不读取：它的聊天记录存在加密数据库里。deja install trae-ide 会加上 MCP 服务器和技能，trae-ide-auto 会加上钩子；钩子需要你在 Settings > Hooks 里打开， TRAE IDE 才会运行。

自定义存储位置走 DEJA__ROOT 变量，各智能体自己的迁移变量同样生效。
session format registry 逐个 harness 记录了实测路径、记录结构和角色映射，并用合成样例保证这些描述与解析器保持一致。

自带安装包的 harness

deja install --auto 会像处理其他 harness 一样，给下面每一个都接好线，这仍然是最省事的做法。它们在自己的生态里也各有安装包，适合习惯在扩展市场安装、而不是从命令行安装的人：

| Harness | 包 | 安装 |
| opencode | npm opencode-deja | opencode plugin opencode-deja |
| DeepSeek Harness | npm dsh-deja | dsh plugin --profile web add dsh-deja |
| Zed | deja-context-server | Zed → Extensions → deja |
| Kimi Code | 插件 deja | /plugins install https://github.com/vshulcz/deja-vu |
| Codex CLI | 插件 deja-vu | codex plugin marketplace add https://github.com/vshulcz/deja-vu 然后 codex plugin add deja-vu@deja-vu |
| Grok Build | 插件 deja | grok plugin marketplace add vshulcz/deja-vu 然后 grok plugin install deja |
| OpenClaw | ClawHub 和 npm @vshulcz/openclaw-deja | openclaw plugins install clawhub:@vshulcz/openclaw-deja |
| pi（以及 omp） | npm @vshulcz/pi-deja | pi install npm:@vshulcz/pi-deja |
| Hermes | 记忆服务商 deja-memory，位于 Hermes 插件目录 | hermes plugins install deja-memory，或从 GitHub 安装：hermes plugins install vshulcz/deja-vu/extensions/hermes |
| Magpie | npm 包 @vshulcz/magpie-deja | magpie plugin add @vshulcz/magpie-deja |
| CC Switch | 一键导入 MCP 与技能仓库（ccswitch://） | 把 MCP 添加到 CC Switch · 切换指南 |

两条路径单独用都行，一起用也不会翻倍：每个包读的都是 deja install 已经写好的内容，用的也是你已有的 deja。

在 Spec Kit 项目里，装个扩展就能加上 /speckit.deja-vu.recall。实现功能之前，它会去翻历史会话，找这个功能的相关记录：

specify extension add deja-vu --from https://github.com/vshulcz/deja-vu/releases/latest/download/deja-spec-kit.zip

同样的搜索也做成了技能，任何能加载 SKILL.md 的智能体都能用：

npx skills add https://github.com/vshulcz/deja-vu --skill deja-search # skills CLI: Claude Code, Cursor, Goose, Copilot…
openclaw skills install @vshulcz/deja-search # ClawHub
hermes skills install vshulcz/deja-vu/skills/deja-search # Hermes

这个技能调用的是上面安装步骤里的 deja 二进制，自身并不打包一份。

语义召回（可选）

用 DEJA_EMBED_URL 把 deja embed 指向本地 Ollama、LM Studio 或 OpenAI 兼容端点，换个说法查询也照样命中。没有可用的运行时，词法搜索和 MCP 召回照常工作。OpenAI Platform 用标准密钥即可：

export OPENAI_API_KEY='sk-...'
export DEJA_EMBED_URL='https://api.openai.com/v1/embeddings'
export DEJA_EMBED_MODEL='text-embedding-3-small'
deja embed

本地运行时、其他端点，以及向量要花多少

不设 DEJA_EMBED_URL 时，deja 会探测 localhost:11434 和 localhost:1234，所以机器上已经在跑 Ollama 或 LM Studio 的话，不用问就能直接用上。DEJA_EMBED_OFF=1 或 DEJA_EMBED_URL=off 会关掉这个探测——但另外配置了 DEJA_EMBED_URL 时，仍以它为准。

要用另一个需要认证的 OpenAI 兼容端点，就显式设置 DEJA_EMBED_KEY：

export DEJA_EMBED_URL='https://example.com/v1/embeddings'
export DEJA_EMBED_MODEL='embedding-model'
export DEJA_EMBED_KEY='...'
deja embed

DEJA_EMBED_KEY 优先。OPENAI_API_KEY 只在 URL 是 HTTPS 的 api.openai.com 时自动使用，绝不会隐式发给本地或第三方端点。

用指令前缀训练的模型，比如多语言 E5 系列，查询和文档两侧都要加前缀。DEJA_EMBED_QUERY_PREFIX 会加在每个搜索查询前面，每个被索引的文本前面都要加 DEJA_EMBED_PASSAGE_PREFIX；两者默认都为空：

export DEJA_EMBED_MODEL='multilingual-e5-small'
export DEJA_EMBED_QUERY_PREFIX='query: '
export DEJA_EMBED_PASSAGE_PREFIX='passage: '
deja embed

passage 前缀是 sidecar 模型名的一部分，所以改动它会把所有内容重新嵌入一遍；搜索会忽略用其他模型或前缀生成的向量（只会提示一次）。

sidecar 与索引放在一起，文件名是 .vectors.bin，不在 index.db 里面。对 1,024 维模型来说，Float32 向量每 1k 条消息大约占 4 MB。远程端点收到的是脱敏后的索引文本，截断到约 2k 字符，但绝不会收到原始源文件。用 Ollama 或 LM Studio 时，嵌入留在本地，不需要 key。

实测

查询只需毫秒级；在 LongMemEval-S 上 hit@1 达到 88.9%（470 题清洗集），全部 500 题上 hit@1 为 88.2%；在 LoCoMo 检索上 hit@1 为 71.9%。在一台机器已经解决过的任务上，token 少了 58%：每组跑十一次，接入后是 53,558，什么都没接是 126,222；后来换了一版构建、两组交替跑，分别是 52,815 和 103,443。两套检索测试工具都随本仓库发布，几分钟就能在公开数据集上跑完：基准测试 ·一个任务的开销。

其余由 deja bench 测量：

deja bench recall # ranking floor: 100 queries, half Russian, CI fails if recall drops
deja bench context # 30 seeded task chains plus five negative controls
deja bench block # does the answer survive into what deja hands over
deja bench prompt # what the per-prompt hook fires on, and what it fires on wrongly

deja bench ingest # what an update costs: unchanged, a turn, a new transcript, a rename, a rewrite
deja bench read # what it costs to read a database-backed store, and what one long value does to it

What the in-repo benches measure, and lookup cost on a real store

bench block asks the question the others cannot: with the right session in
hand, does the block carry what that session settled. Eight sessions discuss each
subject and one of them settles it, in the middle of its own transcript rather
than at the end — so the baseline arm, the newest turns of the top hit, scores zero and an arm above zero had to choose.

| Arm | Carries the answer | Median tokens |
| deja-block (session-start block) | 1.00 | 665 |
| deja-digest (context digest) | 1.00 | 1656 |
| newest-turn (baseline) | 0.00 | 289 |
| cold | 0.00 | 0 |

The context experiment compares deja-recall against full-history, naive grep and cold
context. With the default seed:

| Arm | Median tokens | Median coverage | Negative-control tokens |
| deja-recall | 1,096 | 1.00 | 0 |
| full-history | 80,547 | 1.00 | 78,145 |
| naive-grep | 273,238 | 1.00 | 0 |
| cold | 0 | 0.00 | 0 |

Same fact coverage as grepping the raw logs for about 250x fewer tokens, and about 70x
fewer than replaying the matched sessions in full, while injecting nothing on the chains
where no prior fact is relevant. The corpus generator and the relevance labels are
ordinary reviewed Go. Audit what "relevant" means before trusting any figure, ours
included.

Measured on a real store of 2,419 sessions and 179k messages, 1.9 GB of
transcripts:

| Measurement | Result |
| Lookup, in process | 0.7–0.8 ms median (deja bench recall, 100 queries, half of them Russian), ~15 ms on the LongMemEval-S haystacks |
| deja <query>, end to end | ~0.2 s median on that store: process start, the freshness check over every store, ranking, printing |
| Freshness check alone | ~50 ms when nothing changed |
| Index size | 200 MB, ~10% of corpus |

The same store has since grown to 2,754 sessions, 358k messages and 5.7 GB.
A cold full build over it takes 71 s and writes a 232 MB index — 4% of the corpus, because the share falls as transcripts repeat themselves — and the end-to-end median is unchanged at 0.25 s. Since 0.23.2 records are compressed from 256 bytes, which takes a 19k-session index from 277 to 185 MB.

The index is incremental. When a session file grows, only that file is re-read. When one is
rewritten, its new records are appended and the old ones zeroed in place. On a
40,000-session store a pass over 20 rewritten transcripts takes 1.7 s and peaks under 1 GB,
and a search for a word most sessions hold takes about a second.

How it works

Local inverted index in ~/.cache/deja: parse the JSONL and SQLite stores, redact
credentials, write an append-only records.bin plus token buckets, and track per-file state in
manifest.gob so repeat runs only ingest what changed. The MCP server, stats, share and
sync all read that one index. Details in docs/ARCHITECTURE.md.

FAQ

How is this different from the other memory tools?

| | deja | Memory platforms(Mem0, Letta, memU) | Session search(cass) |
| Knows work from before you installed it | yes | no | yes |
| Capture step | none, the transcripts are the memory | the agent or your code writes facts | none |
| Needs an LLM or embedding key | no | yes | optional |
| Recalls without being asked | at session start and before a tool runs | no | no |

engram is the strongest of the
record-forward tools and worth your time if that model fits you; it still starts empty and
knows only what an agent chose to save. The
full comparison covers 15 of them.

Will it slow my agent down?

A recall is a lexical lookup against a local index:
0.7–0.8 ms median, and nothing waits on a model. A hook adds the process start and a
freshness check over your stores on top of that: about 0.2 s end to end on a 1.9 GB
store. On an index of 19k sessions the per-prompt hook takes 107 ms at the median,
and a recall through deja mcp 85 ms.

Where is Claude Code session history stored, and can I search it?

Under ~/.claude/projects, one JSONL file per session; Codex keeps ~/.codex/sessions, Cursor a
SQLite state.vscdb. deja reads them all in place: bare deja opens a screen to search
and read them, deja search does it from a script, deja last lists the recent
sessions of every agent, and deja view opens the whole history as one local page. Paths
for each agent: where sessions are stored.

My Claude Code session history disappeared. Is it gone?

Claude Code deletes transcripts older than 30 days (cleanupPeriodDays in ~/.claude/settings.json), and claude --resume lists
only what is left. A session deja indexed before the cleanup stays searchable after the
file is gone, and the weekly note at session start says how many it kept, with an id
deja resume <id> --write-back puts back. Details: session files on disk.

Can I stop it reindexing on its own, or index for search only?

Yes. DEJA_NO_AUTO_INDEX=1 or "auto_index": false in ~/.config/deja/policy.json stops every automatic update; search, MCP recall and hooks answer from the last finished index.

DEJA_SEARCH_ONLY=1 or "search_only": true in ~/.config/deja/policy.json skips mining fixes, commands and co-occurrence (~20% of a build's CPU). The DEJA_INDEX_ switches that keep commands, tool output, paths and edits out of the index are in the commands guide.

One project is spread over several checkouts. Can recall treat them as one?

List the trees in ~/.config/deja/projects, one <path> = <name> per line:

~/work/monorepo = work
~/work/worktrees = work

Every directory under a listed path is then that project, for indexing, the hooks and recall alike; the longest matching path wins. Run deja index --rebuild to re-file existing transcripts under the new name. The exclude file still wins over project aliases.

How do I wipe everything?

deja uninstall --all
rm -rf ~/.cache/deja ~/.local/share/deja ~/.config/deja

The index is under ~/.cache/deja, your remember and promote notes in
~/.local/share/deja, and the rules, exclude list, project aliases and hook launcher in
~/.config/deja (or under XDG_DATA_HOME and XDG_CONFIG_HOME when set; on
Windows the notes are in %AppData%\deja).

Guides

- Context & recovery: Does your agent remember previous conversations? · The agent lost the context you had · The context window is full · What compaction drops · Why agents forget between sessions
- Resuming & finding: Resuming yesterday's session · Finding the session where you solved it · The agent repeats a mistake you already fixed · Switching agents
- Session files & cleanup: Session files on disk · Where each agent keeps its history · Recovering a deleted Claude Code session · Claude Code: No conversation found with session ID · Codex resume session · Deleting old Claude Code sessions
- Comparisons & operations: What each memory tool knows the day you install it · Memory plugins compared · What memory costs · Auditing an agent · Exporting a conversation · Across machines

Per-harness setup guides (Claude Code, Codex, Cursor, OpenClaw, Hermes…)

Claude Code · Codex · Cursor · Windsurf · opencode · DeepSeek Harness · Kimi Code · Zed · Grok Build · Gemini CLI · Qwen Code · OpenClaw · Goose · Cline · pi · Hermes · Copilot CLI · Copilot Chat · aider · Amp · Antigravity · Continue · Crush · Roo Code · Kilo Code · Kiro · Cherry Studio · Oh My Pi · prime-agent · Senpi · Kimchi · Command Code · ZCode · gjc · CodeWhale · Reasonix · TRAE CLI

Contributing

make build test lint, then CONTRIBUTING.md. Adding a harness starts in
the parser registry. Priorities and non-goals are in
ROADMAP.md. Good first issues are labeled.

Support

Bugs and questions go to issues.
Anything you think is exploitable goes through the private advisory link in
SECURITY.md instead. What deja reads, what it never sends
anywhere, and how to exclude a project or forget a session is under
Privacy.

License

MIT © Vladislav Shulcz