给 AI 编程工具装上「记忆硬盘」：deja-vu 让 Agent 不再健忘

场景切入：那个 Bug 又回来了

周一的下午，你正信心满满地在 Claude Code 里实现一个新的 API 网关模块。一切都很顺利——直到某个接口开始返回 401 认证错误。你花了整整两小时翻遍了文档，终于在一个深夜里用 Codex 解决了这个问题：在测试环境里，refresh token 的轮换周期没有同步更新到 JWK 缓存里，你加了一行 jwkCache.reload()，加了一个时钟偏差的容错测试。

那是两周前的事了。现在是新的周一，你在用 Codex 开发另一个功能——同一个模块，同一个错误。

这大概是每个 AI 编程工具重度用户都经历过的尴尬时刻。 调试经验在会话结束的瞬间就「丢失」了，下一次对话形同陌路。你积累了几个月的 API 踩坑记录、架构决策、参数配置心得，在每一个新会话里都像从未存在过。你只能靠脑子记，或者把重要的结论手动粘贴到提示词里。

deja-vu 正是来解决这个问题的。

背景：为什么 AI Agent 需要记忆工具

AI 编程工具（Claude Code、Codex、opencode、Cline、Cursor 等）的设计哲学是「无状态」——每次会话从零开始，不会主动去查找你之前在别的工具里解决过什么问题。这在理论上简化了设计，但在实际工作中造成了大量重复劳动。

现有的解决方案有几类：

第一类是记录向前的记忆工具（如 Engram、Mem0、Letta）：需要在每次对话结束后主动调用 mem_save API 才能保存记忆。这依赖开发者的配合，而且只能记住「被显式保存」的内容，遗漏了大量的隐性知识——比如调试过程中尝试过的错误路径、失败的原因、最终解决方案的上下文。

第二类是向量数据库方案（如 cass）：通过 embedding 模型把所有会话向量化存储，支持语义检索。但这需要额外的服务运行（Python 运行时、向量数据库、embedding 模型），安装和运维成本高，且 embedding 服务通常需要网络调用，数据隐私难以保证。

deja-vu 选择了一条截然不同的路：零依赖、零 LLM、零 API key、回溯式全文索引。 它不需要你改变任何使用习惯，不需要任何安装配置，直接把你的 Agent 历史文件夹里已经存在的会话文件全部索引。安装之后立刻就能用，而且从第一天起就「满血」——它能索引你安装之前数月积累的历史记录。## 核心功能：从搜索到自动注入

deja-vu 的功能可以分为三个层次，从最基础的搜索到最高级的自动上下文注入。

第一层：快速搜索

deja "jwt refresh token rotation"
# [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

背后是本地倒排索引（BM25 + 混合排序）。在 3.3 GB 历史数据上，搜索延迟约 12ms，索引文件大小仅占原文的 2.4%。支持按时间范围过滤、按 Agent 类型过滤、按项目过滤，正则表达式搜索。

第二层：MCP Recall——让 Agent 自主查找记忆

通过 MCP 协议，deja recall 和 deja recall_context 工具可以被任何 MCP 客户端调用。Claude Code 在遇到 JWT 认证问题时，可以直接调用 MCP recall 工具，Agent 回答「两周前你在 Codex 里解决了这个问题，原因是 JWK 缓存没有同步」，而不是重新走一遍两小时的调试流程。

更强大的 deja blame <path> 可以反向查询：某个文件被哪些会话修改过，改了什么、为什么改。

第三层：Auto-recall——会话启动时自动注入相关记忆

通过 deja install --auto，deja-vu 会在支持的 Agent（Claude Code、Codex、opencode 等）上注册 SessionStart Hook。Agent 每次启动时，自动把与当前项目相关的记忆摘要注入上下文，完全无需人工干预。

Claude Code 还额外支持 PreCompact Hook：在上下文压缩之前，把当前会话转录内容提前写入索引，确保长期知识不会因为上下文窗口限制而丢失。## 技术架构：Go + 本地倒排索引

deja-vu 的架构非常清晰，核心组件只有三个：

解析器注册表（Source Parsers）：deja-vu 支持 16 种 Agent 的会话文件格式，每种格式都有对应的解析器把原始文件转换成统一的内部记录格式。支持的格式包括 JSONL（Claude Code、Codex）、SQLite（opencode、Cursor IDE 聊天）、JSON（Gemini CLI）、自定义格式（Cline、Cursor CLI）以及各 Agent 的元数据文件。解析器注册在 docs/registry/README.md 中维护，每个解析器都有对应的合成测试用例确保格式变化能被及时发现。

本地倒排索引引擎（Index Engine）：索引结构为 records.bin（原始记录二进制存储）+ token 分桶倒排索引 + manifest.gob（增量更新元数据）。凭证清洗（API Key、JWT、私钥等高敏感信息替换为 [redacted:xxx]）在写入索引前完成，支持 12 种凭证模式，覆盖 AWS/GitHub/npm 等主流服务。索引支持增量更新——会话文件有增量写入时，只重新读取和索引变动的部分。

可选向量语义层（Semantic Sidecar）：通过 deja embed 接入本地 Ollama/LM Studio embedding 端点，生成固定宽度 float32 向量写入 .vectors.bin 文件。混合排序策略：词法 BM25 top-64 结果经向量重排，最终分数 = 0.5×归一化词法分 + 0.5×余弦相似度。

CLI 层通过 cobra/urish/cli 提供子命令，deja mcp 输出 MCP stdio 协议，所有功能（搜索、分享、同步）都基于同一套索引读写。## 隐私设计：本地优先，数据最小化

deja-vu 在隐私方面的设计颇为用心。索引和搜索完全本地运行，网络仅在两个场景中出现：

• deja update：检查 GitHub 是否有新版本
• deja sync ssh：通过系统 SSH/SCP 传输脱敏后的 JSONL 批次

同步传输的内容会经过二次脱敏——即使源文件有遗漏，系统在导出时也会重新扫描一遍凭证模式。导入是幂等的（基于时间戳水印），支持增量追加，不会产生重复记录。

不想被记住的会话有多种排除方式：全局排除规则（~/.config/deja/exclude）、环境变量排除（DEJA_EXCLUDE_PROJECTS）、单个命令排除（deja index --exclude）。而一旦你想彻底抹除，deja forget 不仅从索引中删除记录，还会写入墓碑文件（~/.config/deja/tombstones），确保即使重建索引也无法恢复被删除的内容——这是真正的不可逆删除。

Agent 子会话（subagent）默认被排除在索引之外，因为它们通常只是复制父会话的行为，单独索引价值有限且增加存储噪音。

<p align="center"><img src="https://raw.githubusercontent.com/vshulcz/deja-vu/main/assets/demo.gif" alt="deja demo"></p>

部署体验：极简到极致的安装流程

deja-vu 打包为一个零依赖的 Go 二进制文件，安装方式覆盖了几乎所有常见场景：

# 官方脚本（macOS/Linux）
curl -fsSL https://raw.githubusercontent.com/vshulcz/deja-vu/main/install.sh | sh

# 或者：Homebrew / npm / Go install / Windows
brew install vshulcz/tap/deja-vu
npm install -g @vshulcz/deja-vu
go install github.com/vshulcz/deja-vu/cmd/deja@latest

install.sh 会自动检测操作系统和架构（macOS/Linux + x86_64/arm64），从 GitHub Releases 下载对应压缩包并校验 SHA256 完整性，然后安装到 $HOME/.local/bin 或 /usr/local/bin。安装完成后，deja install --all 可以一键把所有检测到的 Agent（Claude Code、Codex、opencode 等）全部配置好 MCP 连接。

Dockerfile 提供了容器化路径，使用 golang:1.25-alpine 多阶段构建（CGO_ENABLED=0 静态链接），最终镜像基于 alpine:3.20 并仅安装 sqlite3 运行时。容器内运行适合在 CI 环境中做基准测试，但实用场景有限——因为容器内的 Agent 会话文件通常不是主要的工作目录。

无 Web UI，所有交互通过 CLI 和 MCP 协议完成。deja view 提供本地 HTML 页面查看记忆库，不依赖任何外部服务。

局限与值得关注的点

1. 纯词法搜索的天花板：deja-vu 默认不使用 embedding，在处理同义词、语义变换查询时不如向量检索精确。启用语义层需要额外配置 Ollama 等本地 embedding 服务，有一定学习成本。

2. 中文支持是近年才完善的：v0.15.x 之前，中文分词存在严重问题（全角标点粘连、MIRACL 中文 hit@1 约 40%）。从 CHANGELOG 看，v0.15.6-0.15.7 集中修复了中文/俄语/韩语等多语言分词问题，中文提升到 42.5%，但仍有改善空间。

3. opencode/Cursor IDE 聊天需要 sqlite3：这两个工具的会话存储在 SQLite 数据库中，deja-vu 需要调用系统 sqlite3 CLI。虽然 macOS 和大多数 Linux 发行版预装了 sqlite3，但 Windows 用户可能需要单独安装。

4. Agent 生态锁定：deja-vu 的价值高度依赖各 Agent 的会话文件格式稳定性。如果某个 Agent 更新了会话格式但 deja-vu 解析器未同步，索引会出错——好在项目维护了合成测试 fixture 配合 CI 检测格式漂移。

行业意义：Agent 互联互通的早期尝试

deja-vu 的出现，折射出一个正在浮现的趋势：不同 AI Agent 之间的「记忆孤岛」问题开始被重视。随着 Claude Code、Codex、Cursor 等工具的普及，开发者越来越多地在一个项目里交叉使用多种 Agent——每个 Agent 各有擅长，但彼此之间无法共享上下文，导致知识碎片化。

deja-vu 通过「以文件为媒介」的思路，在不需要任何 Agent 主动配合的情况下，实现了跨 Agent 的记忆共享。这种「事后索引」的模式虽然依赖各 Agent 把会话写入本地文件这一事实，但恰好是目前几乎所有主流 Agent 的共同行为。这种「依赖但不侵入」的设计哲学值得借鉴。

对于团队场景，deja sync 的跨机器同步能力提供了一个轻量级的团队知识沉淀方案——不需要搭建服务器，不需要注册账号，所有数据在团队成员的机器之间以 append-only 的方式流转，本质上是一个极简的端到端加密知识库。

总体而言，deja-vu 是一个技术选型非常务实的项目：Go + 零依赖 + 纯词法搜索 = 极低运行开销和极佳可移植性；MCP 协议支持 = 广泛兼容主流 Agent；本地优先 + 二次脱敏 = 隐私保障。对于任何重度使用 AI 编程工具的开发者，它都是值得一试的效率提升工具。