[deja-vu]
Your coding agents stop re-debugging what you already fixed.
Claude Code, Codex, Cursor, OpenClaw, Gemini CLI, OpenCode, Hermes and 36 more agents already save every session to disk.
deja indexes all of it locally and hands the relevant history back over MCP and hooks — no LLM, one Go binary.
English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Español | Português | Français | Deutsch | Русский | Türkçe | हिन्दी
[#1 Go Repository Of The Day]
[GitHub Stars]
[CI]
[Coverage]
[Release]
[MCP Toplist]
[MIT License]
Website & interactive search · Live browser demo · Docs · Benchmarks · How it compares · Building it into your tool
[The same question put to the same agent twice: without memory it has no record of it, with deja it answers with the decision from eight months earlier]
Or with Homebrew: brew install deja-vu && deja install --auto · Claude Code plugin: claude plugin marketplace add vshulcz/deja-vu && claude plugin install deja-vu@deja-vu · Agent Skills: npx skills add vshulcz/deja-vu
Windows (Scoop / winget), Codex, OpenCode, OpenClaw and more · Try without installing: npx @vshulcz/deja-vu sources · Live demo →
Every driver, corpus and scoring rule is in this repository: head-to-head · all benchmark runs
Search it yourself
deja with no arguments opens a terminal search across every agent's history — starting with
the sessions behind your uncommitted changes, then recent work in the current project.
[Typing a search in the deja screen, reading the session it found, and continuing that session in another agent]
- Navigate:
↑↓ picks a session, ↵ opens at the match, / searches inside a session, ] [ jump between turns, ^s toggles date/relevance sort (deja search --sort date).
- Filter: by agent (
codex:), time (today, yesterday, week, month), or project (in:<project>).
- Resume or hand off:
r reopens the session in its native agent; o continues it in another agent with its goal, decisions and open work.
- Recover deleted chats:
tab switches between this project, all projects, and Deleted (sessions an agent purged that deja still holds); R restores one, D deletes (deja delete <id>), ? lists all keys.
Prefer a browser? deja view exports the store — sessions, the recall audit trail, and promoted notes — into one local HTML file (try the live demo). With DEJA_TUI=0 (or deja brief), deja prints a plain-text summary.
Highlights
- Starts full on day one. Months of existing transcripts across all forty-three agents are searchable immediately — fix a bug in Codex and Claude Code, Cursor or OpenCode recalls it.
- Automatic recall via hooks & MCP. Surfaces prior sessions at session start, before a file edit or command runs, and when a command fails.
- Survives compaction. Over 43 measured compactions, summaries kept 77% of decisions and 0.2% of commands; deja hands back the rest (how).
- Indexes code changes, not just chat. Tracks opened files, commands with exit codes, and exact
Edit spans (deja blame <file>:<line>, deja restore <path>).
- Tracks decision lifecycle & staleness.
deja promote <id> --state rejected marks a reverted approach so later hits warn why it was dropped (--state accepted takes the mark back), and hits report when files touched by a session have changed since.
- Local and private by default. Zero LLM calls, no cloud account, and automatic credential redaction at index time (privacy).
Your own work, wrapped
deja stats --card draws your yearly agent activity in the terminal or writes an SVG for your GitHub profile (convert to PNG in browser).
[deja stats card: a year of agent sessions as a heatmap, the agents they came from, and the longest one]
Install
install.sh places the deja binary in ~/.local/bin, and deja install --auto wires MCP recall and hooks into every detected agent and builds the initial index (~10s).
[What deja prints after the first index: the mark, the agents it found, and a query taken from your own history]
Open a new session in any wired agent and it already knows what you solved in that repository — or ask it directly (have we dealt with jwt refresh rotation before?).
Homebrew, Windows (Scoop / winget), npm, plugin marketplaces, and binary-only setup
brew install deja-vu, nix run github:numtide/llm-agents.nix#deja-vu, go install github.com/vshulcz/deja-vu/cmd/deja@latest,
or npx @vshulcz/deja-vu "query" to try it without installing anything. Desktop apps that
take MCP servers as bundles can open the .mcpb from the
latest release; it carries the binary.
Codex CLI, opencode, Claude Code, Qwen and OpenClaw can also install the plugin
bundle directly from their own marketplaces or registries (see
Harnesses with a package of their own,
plus cursor-plugin/ for Cursor and antigravity-plugin/ for Antigravity). Copilot CLI installs the
marketplace bundle too, though it takes only the skill there — use
deja install copilot-auto for hooks and MCP:
On Windows the install script exits with unsupported OS — it is a shell script. Use
Scoop, from the main bucket every Scoop install already has, or winget, which ships with Windows:
Or take deja-vu_<version>_windows_amd64.zip from the
latest release and put deja.exe on
your PATH, e.g. in %USERPROFILE%\.local\bin.
The binary alone is a complete install for searching: index, search, show, ctx, blame,
--json and redaction need nothing else. deja install is what wires MCP into your agents
and turns on session-start recall — worth having, and optional. On a binary-only setup
deja doctor reports every MCP target as config missing, or not-wired where the agent
is installed, which is that setup working as intended. deja warmup also leaves a skill at ~/.agents/skills/deja-search/SKILL.md
that teaches an agent the CLI contract — deja recall, ctx, blame, how to read the
recall page and ask for the next one — so it knows history is searchable without MCP. The copy in the repo is
skills/deja-search/SKILL.md.
deja install --all is --auto without the session-start recall: agents answer from memory
when they decide to call it, rather than starting each session with it. The
agent setup guide covers what each
harness supports, aider's read-only context file, and the Windows cmd /c deja mcp wrapper.
What gets written into each agent's own guidance file
Install also writes user-level guidance for the harnesses it detects: 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 and Junie each get it in their own guidance file (or under the configured XDG_CONFIG_HOME). Re-run rewrites deja's skill or marked block without changing surrounding user content. Use deja install --all --no-guidance to opt out; Grok Build and Devin CLI get the shared skill in ~/.agents/skills, which is what they read; the ~/.grok/GROK.md written beside it is for the unrelated community CLI that shares that directory. Cursor has no user-level instructions file, so it gets the shared skill in ~/.agents/skills — one of the four places Cursor reads skills from — read only when something looks relevant rather than every session. Kilo Code, gajae-code, Kimchi, Command Code, Cherry Studio and Reasonix get the skill, MiniMax Code gets it inside the plugin package, and Kiro the skill and a steering file, from their own install target.
Privacy
Indexing and search are local. The network is used only by deja update, deja sync ssh,
the version check in deja doctor, deja embed against an endpoint you configure (and,
once it has built the semantic sidecar, each search, which sends the query to that
endpoint), and a once-a-day look at the latest release from an interactive command. That look sends no
session data; DEJA_OFFLINE=1 turns it off, and so does DEJA_NO_UPDATE_NOTICE set to any
value, which also hides the note a new version prints on its first run.
Credentials are stripped as the index is built: cloud and provider keys, tokens and JWTs,
PEM blocks, passwords in URLs or stated in prose. Each becomes [redacted:<kind>] and the
text around it stays searchable. The source transcripts still hold them
(one machine had 84 in 42 sessions):
deja secrets names those sessions without printing a value, and deja secrets --scrub
rewrites the ones it can, keeping the original beside the file.
deja forget drops sessions and keeps them dropped across rebuilds. ~/.config/deja/exclude
skips a project per line, or a whole store with harness:opencode. The
security model has the data flows and what redaction cannot catch.
CLI
Bare deja in a terminal opens the search screen. With a query,
or any command below, it prints and exits:
Ask your history
When the first word of a bare query has at least four characters and is one
edit from a command name, deja names that command on stderr and then searches
as usual. deja search <query> skips the suggestion.
Using what it finds, and moving it between machines
Use what it finds
Move it and check it
Full reference: commands and
JSON output.
MCP tools
The server exposes one tool, deja, with a mode; deja install wires it in. One tool
costs 477 tokens of definitions a turn, against 8,283 for the largest of the seven servers
measured in day zero. The six
older tool names (recall, recall_context, blame, fix, how, remember) still answer.
deja mcp --context-search is a separate server with a single context_search tool, for
Qwen Code's External Context MCP Profile v1 (Qwen page).
Arguments and return shapes
q carries whatever the mode asks about. The per-mode names below are still
accepted; they are no longer declared, because the schema is read every turn
whether or not the tool is called.
Supported harnesses
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.
What each one supports
✅ works · — possible, not built yet · ✕ the harness has no such mechanism · ⚠ waiting on the harness itself · ? not investigated
TRAE IDE is wired, not read: its chats are in an encrypted database. deja install trae-ide
adds the MCP server and the skill, and trae-ide-auto adds hooks, which TRAE IDE runs only
after you turn them on in Settings > Hooks.
Custom store locations go through DEJA_*_ROOT variables, and each agent's own relocation
variable is honored too. The
session format registry documents
the observed paths, record schemas and role mapping per harness, with synthetic fixtures
keeping those descriptions checked against the parsers.
Harnesses with a package of their own
deja install --auto wires every one of these like every other harness, and
that stays the shortest path. They also have a package in their own ecosystem,
for people who install extensions there rather than from a CLI:
Either path works alone, and both together double nothing: each package reads what
deja install already wrote and uses the deja you already have.
In a Spec Kit project, an extension adds
/speckit.deja-vu.recall, which searches past sessions for the feature before you
implement it:
The same search is also a skill, for any agent that loads a SKILL.md:
The skill drives the deja binary from the install step above; it does not bundle one.
Semantic recall (optional)
Point deja embed at a local Ollama, LM Studio or OpenAI-compatible endpoint with
DEJA_EMBED_URL and rephrased queries still hit. Without a reachable runtime, lexical
search and MCP recall continue unchanged. OpenAI Platform works with its standard key:
Local runtimes, other endpoints, and what vectors cost
With no DEJA_EMBED_URL set, deja probes localhost:11434 and localhost:1234,
so a machine already running Ollama or LM Studio is picked up without being asked.
DEJA_EMBED_OFF=1, or DEJA_EMBED_URL=off, turns that probe off — any other
configured DEJA_EMBED_URL still wins.
For another authenticated OpenAI-compatible endpoint, set DEJA_EMBED_KEY explicitly:
DEJA_EMBED_KEY takes precedence. OPENAI_API_KEY is used automatically only for an
HTTPS api.openai.com URL; it is never implicitly sent to local or third-party endpoints.
Models trained with instruction prefixes, such as the multilingual E5 family, need them on
both sides. DEJA_EMBED_QUERY_PREFIX goes in front of every search query and
DEJA_EMBED_PASSAGE_PREFIX in front of every indexed text; both are empty by default:
The passage prefix is part of the sidecar's model name, so changing it embeds everything
again, and search ignores vectors made with another model or prefix (it says so once).
The sidecar sits beside the index as .vectors.bin, not inside index.db. Float32 vectors
cost roughly 4 MB per 1k messages for a 1,024 dimension model. A remote endpoint receives
the redacted indexed text, truncated to about 2k characters, but never raw source files.
With Ollama or LM Studio, embedding stays local and needs no key.
Proof
Millisecond lookups, and on LongMemEval-S 88.9% hit@1 (470-question cleaned set) and 88.2% hit@1 on all 500 questions;
on LoCoMo retrieval, 71.9% hit@1. On a task this machine had already solved, 58% fewer
tokens: eleven runs an arm, 53,558 against 126,222 with nothing wired, and 52,815 against
103,443 on a later build with the arms alternated. Both retrieval harnesses ship in this repo
and run on the public datasets in minutes: benchmarks ·
what one task costs.
The rest is measured by deja bench:
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.
The context experiment compares deja-recall against full-history, naive grep and cold
context. With the default seed:
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:
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?
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.
What files live in ~/.config/deja, and what can I set in them?
Under ~/.config/deja (or $XDG_CONFIG_HOME/deja):
policy.json (DEJA_POLICY_FILE moves it) — JSON object with four optional keys:
"activations": per-surface origin rules for "search", "mcp" and "auto" (hooks), keyed by "local", "imported", "imported:<group>" or "*" (true/false). DEJA_AUTORECALL_LOCAL_ONLY=1 sets activations.auto.imported to false."ignore": array of shell globs matched against session path and project to exclude from recall and sync (default ["*/.claude/jobs/*"])."auto_index": false stops automatic index updates on search, MCP recall and hooks (same as DEJA_NO_AUTO_INDEX=1)."search_only": true skips mining fixes, commands and co-occurrence, saving ~20% of build CPU (same as DEJA_SEARCH_ONLY=1).
exclude — one project name or path pattern per line to skip at index time and sync export, or harness:<name> (e.g. harness:opencode) to skip a store (DEJA_EXCLUDE_PROJECTS, DEJA_EXCLUDE_HARNESSES).projects — one <path> = <name> per line to group multiple checkouts or worktrees as one project.rules.md — standing instructions copied into each installed agent's global rules file by deja rules sync.- State files written by deja —
peers.json (deja sync ssh), settled.json (deja friction --settle), tombstones (deja forget), wiring.json and bin/deja-hook (deja install).
Hook recall mode is set by DEJA_RECALL: safe (default, 2 KB cap and up to 3 sessions from the current project at session start), aggressive (4 KB cap and up to 6 sessions across projects), or off (silences all hooks). The DEJA_INDEX_* switches and full configuration table 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:
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?
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
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. Found it useful? Star deja-vu on GitHub.
License
MIT © Vladislav Shulcz
