deja-vu

deja indexes all of it, months back, and hands the part that matters to whichever agent is working now.

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

Windows, Homebrew, npm and the rest

Recall97.2% R@5 on LongMemEval-SMemPalace publishes 96.6%, agentmemory 95.2% Tokenshalf the tokens of agentmemoryon a task this machine had already solved Index time17.6 s to index 19,195 sessionsthe next of seven tools takes 72 s

the head-to-head, and how to re-run a row you doubt · every run

Search it yourself

deja with no arguments in a terminal opens a search over every agent's history. It starts on the sessions behind your uncommitted change, then the recent ones in this project, and the list narrows as you type.

• ↑↓ picks a session, ↵ opens it at the match, n and N step through the matches, esc goes back. Inside a session, / finds a word and ] [ jump between the turns you asked.
• The box takes filters: an agent with a colon (codex:), today, yesterday, week, month, and in:.
• ^s lists the results newest first under day headings, and back to best match first. deja search --sort date does the same from a script.
• r resumes the session in the agent that wrote it. o continues it in any other agent, which starts with what the session asked, decided and left open.
• tab switches between this project, all projects and Deleted, the sessions their agent deleted that deja still holds; R puts one back.
• D erases a session from its agent and from deja, after asking (deja delete from a script).
• ? lists every key, ^k has the rest (copy the session id or project path, forget a session), q quits from the list; esc steps back and quits from an empty search box.

With DEJA_TUI=0 it prints the text summary instead, which is also deja brief. Piped, it prints what is indexed and which command to run next.

Highlights

• Starts full. Months of history from before you installed it are searchable on day one: deja "connection pool exhausted" over gigabytes.
• One memory, every agent. A fix found in Codex comes back in Claude Code, Cursor or opencode; all forty-three agents read the same index.
• Nobody has to ask. Recall arrives at session start, before a file is edited or a command runs, and after a command fails.
• Survives compaction. Over 43 measured compactions the summary kept 77% of the decisions and 0.2% of the commands; deja hands back the rest (how).
• Indexes the work, not just the talk. The files each turn opened, the commands with their exit status, the exact spans an edit replaced.
• Knows what held. deja promote --state rejected marks a reverted decision, and every later hit says it was tried and why it was dropped; --state accepted takes the mark back.
• Says when the ground moved. A hit reports *4 files this session touched have changed since*, and stays quiet when it cannot tell.
• Local and private. No model and no server; embeddings only if you turn on semantic recall. Keys and tokens are stripped as the index is built (privacy).
• Moves with you. deja sync ssh laptop between machines, no cloud in between; deja handoff --to codex to continue in another agent.
• One Go binary. macOS, Linux and Windows, through Homebrew, Scoop, winget, npm or go install.

Your own work, wrapped

deja stats --card draws it in the terminal; give it a filename and it writes an SVG for a profile README. To post it anywhere else, turn it into a PNG — that page converts it in your own browser.

The full feature reference lives in the docs.

Install

The two commands at the top are the whole install on macOS and Linux:

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

The script puts the binary in ~/.local/bin. If that directory is not on your PATH yet, the second command is not found in the same shell: run the next: line the script prints, which has the full path, or open a new shell once the PATH line is added.

Ten seconds to install, about ten to index, and it is useful. The second command wires MCP recall into every agent it finds, turns on session-start recall where the agent supports it, and builds the first index so the next session does not pay for it.

Start a new agent session and ask it something you worked on months ago:

have we dealt with jwt refresh rotation before? check your memory

It does not have to be asked, either — with auto-recall the agent already knows what you solved in that project when the session opens. To look for yourself, run deja.

Other ways to install, and what to do if you want less than all of it

brew install 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.

Claude Code, Cursor, Qwen and OpenClaw can take the same plugin bundle from their own marketplaces instead (Codex has a bundle of its own, in the table under Harnesses with a package of their own). Copilot CLI installs it too but takes only the skill, so use deja install copilot-auto there:

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

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:

scoop install deja-vu
winget install vshulcz.deja-vu

Or take deja-vu__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, 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:] 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:

$ 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

Ask your history

Command · What it does deja · Search every history. Multi-word is AND and quoted phrases require contiguous text; a query with no exact match then tries word forms and close spellings, which is where a substring reaches its word (code finds opencode). --sort date lists the newest match first. deja · In a terminal, the full-screen search above. deja brief prints the text summary instead: today's sessions, what deja served, recent work and a search to try. deja wip · What the last session in this directory was doing: the task, what it settled, the files in flight, the last command and whether it failed — derived from the transcript, not from a note someone remembered to write. deja blame [:line] · Which sessions discussed a file, what was decided, and why. With a line: the commit that last changed it, and the session that wrote that line or the text the commit replaced. --attribution prints the line answer alone, as JSON with --json, and --git-note records it in refs/notes/deja. deja files · The other direction: which files the work on a subject actually touched. deja how · How this machine actually runs a thing, with the real flags, from what agents ran before. deja fix · What this machine ran after that same error before, when the error did not come back. Never a merge, a force push or a deletion. deja friction · Errors that hit three or more separate sessions, with the harnesses named.

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 skips the suggestion.

Using what it finds, and moving it between machines

Use what it finds

Command · What it does deja ctx · Markdown digest of the best match, with the code it changed, ready to pipe into a prompt. deja recall · The page the MCP recall tool gives an agent: about 4 KB, this project first. For skills and scripts that run deja through the shell. deja resume · Reopen a found session in its native harness. --app opens a Codex session in the ChatGPT desktop app. deja restore · Hand back a span an agent replaced, from the old_string its edit recorded. Never writes over the original. deja promote · Distill a session into a curated note with provenance, tags and a lifecycle state. Notes outrank raw transcripts. deja share · A sanitized session digest for a colleague, with secrets already scrubbed.

Move it and check it

Command · What it does deja sync export/import/ssh · Move memory between machines. Watermarked, append-only, idempotent. deja view · Your whole memory as one local HTML file. No server, and the file never leaves the machine. deja stats · Your agent work, wrapped. --card draws it in the terminal, --card .svg writes one for a profile, --html a browsable timeline. deja secrets [--scrub] · Which sessions' source transcripts carry credentials, and what kind. Never prints a value. --scrub rewrites the ones it can, original kept beside the file. deja rules [sync] · Keep your standing rules in ~/.config/deja/rules.md; sync copies them as a marked block into every installed agent's global rules file. deja rules candidates [--json] [--limit n] [--since 90d] · The turns where you corrected an agent, across every tool, numbered with their session. Ask your agent to suggest rules and it groups them; nothing is written until you pick. deja doctor [--deep] · Self-diagnosis, and with --deep, proof of the index against the sources. deja mcp · The stdio MCP server, which is what deja install wires in.

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.

Arguments and return shapes

Tool · Arguments · Returns deja · mode, q, harness?, project?, limit? · Depends on the mode, below.

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.

Mode · q is · Also reads · Returns recall · the question, or an exact error string, name or flag · harness?, limit?, offset? · Dense matching snippets, capped at 4KB. context · the same as recall · harness? · Markdown digest of the best-matching session, with the code it changed. blame · a file path · harness?, project?, since?, limit?, all? · Sessions that discussed a file. fix · the failing output, verbatim · limit? · What this machine ran, or changed, after that same error before. how · the tool or target, e.g. go test · project?, limit? · The real invocation, from what agents ran here. orient · nothing — it asks about the project · project?, limit? · The commands past sessions ran here and the files they worked in. remember · one durable fact or decision · project?, tags? · Stores a durable decision for later recall. handoff · a session id or harness name; empty for the newest session here · harness? · Another session's goal, standing instructions, latest conclusions, passed checks and where it stopped, to continue it.

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

Harness · MCP recall · Auto-recall · Skill · Command · Resume · Handoff · Needs aider · ⚠ · ✅ · ✕ · ⚠ · ✕ · ✅ · deja aider Amp · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · threads from 0.0.1774963753 on live on ampcode.com; deja reads those its plugin has written out, and older local ones Antigravity · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · — Claude Code · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · — Cline · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · — Codex CLI · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · — Copilot CLI · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · — VS Code Copilot Chat · ✅ · ✅ · ✅ · ✅ · ✕ · ✅ · — Cursor · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · sqlite3 (IDE chats, CLI tool output) DeepSeek Harness · ✅ · ✅ · ✅ · ✅ · ✕ · ✅ · zstd Gemini CLI · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · — Goose · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · deja goose Grok Build · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · sqlite3 (grok-dev store) Hermes · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · sqlite3 Kimi Code · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · — omp (Oh My Pi) · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · — OpenClaw · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · sqlite3 (2026.8+ store); zstd for .zst archives and compressed events (2026.9.9+) opencode · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · sqlite3 Continue · ✅ · ⚠ · ✅ · ✅ · ✅ · ✅ · — Crush · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · sqlite3 pi · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · — prime-agent (PrimeIntellect) · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · — Qwen Code · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · — Cherry Studio · ✅ · ✅ · ✅ · ✕ · ✕ · paste · import the server once in Settings -> MCP; enable the skill for the agent Senpi · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · none gajae-code · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · none Kimchi Coding · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · none Command Code · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · none ZCode · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · sqlite3 for the CLI database Kiro · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · sqlite3 for the CLI database Kilo Code · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · sqlite3 for the CLI store Roo Code · ✅ · ✕ · ✅ · ✅ · ✅ · paste · roo CLI (editor tasks reopen in the editor) Zed · ✅ · ✕ · ✅ · ✅ · ✕ · paste · sqlite3 + zstd Devin CLI · ✅ · ✅ · ✅ · ✕ · ✅ · ✅ · sqlite3 CodeWhale · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · none Junie · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · none JetBrains AI Assistant · ✅ · ⚠ · ⚠ · ⚠ · ✕ · paste · none Windsurf / Devin Desktop · ✅ · ⚠ · ✅ · ✅ · ✕ · paste · none CodeBuddy Code · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · none Reasonix · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · zstd for 1.x sessions TRAE CLI · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · none Muse Code · ✅ · ✅ · ✅ · ✅ · ✅ · ✅ · none MiniMax Code · ✅ · ✅ · ✅ · ✕ · ✅ · ✅ · the MiniMax Code CLI (mcode) for deja resume and deja handoff --to mcode --exec; sqlite3 for the session's workspace

✅ works · — possible, not built yet · ✕ the harness has no such mechanism · ⚠ waiting on the ha