deja-vu

The one memory your coding agents share, built from the history already on your disk.

Your agent is about to re-debug something you fixed in March — in a different agent. deja starts full: it indexes what Claude Code, Codex, Cursor and 32 more agents already wrote to disk, and hands it back in whichever agent asks.

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Español | Português | Français | Deutsch | Русский | Türkçe | हिन्दी

_{Nobody searched anything — the agent called deja itself. Two real runs against a synthetic corpus: nobody's history is published.}

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

_{macOS and Linux; ten seconds to install, about ten to index · Windows, Homebrew, npm and the rest}

_{I maintain deja-vu, so every driver, the corpus and the scoring rule are in this repository · the head-to-head, and how to re-run a row you doubt · every run}

Docs · Benchmarks · How it compares · Building it into your tool

_{Found it useful? Star deja-vu on GitHub.}

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 thirty-five 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 <id> --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, no embeddings, no server. 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

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.

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

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

Privacy

Indexing and search are local. The network is used only by deja update, deja sync ssh, the version check in deja doctor, and deja embed against an endpoint you configure.

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

$ 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

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.

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 · CodeWhale · Reasonix.

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.

The same search is also a skill, for any agent that loads a 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

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:

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

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

Proof

Millisecond lookups, and on LongMemEval-S 88.1% hit@1 (470-question cleaned set) and 87.4% hit@1 on all 500 questions; on LoCoMo retrieval, 70.5% 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:

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

How it works

Local inverted index in ~/.cache/deja: parse the JSONL and SQLite stores, redact credentials, write 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

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

Guides

Written for the situation rather than the feature:

• Does your agent remember previous conversations? — what each agent keeps between sessions, and what it drops
• Session files on disk — how big ~/.claude/projects gets, and what deleting it costs
• The agent lost the context you had — after a crash, a clear, or a session that came back empty
• The context window is full — what compaction keeps, measured, and what to do instead
• Resuming yesterday's session — find it across every agent, reopen it in the one that owns it
• The agent repeats a mistake you already fixed
• Finding the session where you solved it
• Why agents forget between sessions · Where each agent keeps its history
• What compaction drops · Switching agents · Auditing an agent · Exporting a conversation · Across machines · What memory costs

Per harness: opencode · DeepSeek Harness · Kimi Code · Zed · Grok Build · Gemini CLI · Qwen Code · OpenClaw · Goose · Cline · pi and omp · Hermes

Try it on your own history

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

Ten seconds to install, about ten to index. The next session your agent opens, it already knows what you solved in that project — including everything from before you installed this.

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