deja-vu: local memory over the session histories of thirty-three coding agents.
io.github.vshulcz/deja-vu β Model Context Protocol (MCP) Server
deja-vu provides local memory over the session histories of twenty-two coding agents. It indexes existing on-disk sessions and retrieves the relevant prior history to support re-debugging. The project focuses on session search for agent conversation content, as indicated by its description and readme excerpt.
π οΈ Key Features
Local memory based on session histories
Indexing of agent sessions written to disk
Session search to return the right history when needed
Targets coding agents including Claude Code and Codex (per excerpt)
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 indexes the sessions Claude Code, Codex, Cursor and every other agent on this machine
already wrote to disk, and hands the right one back in whichever agent asks.
Nobody searched anything β the agent called deja itself. Every line is quoted from two real sessions.
Every memory tool starts empty and records forward. deja starts full.
And nobody has to ask for it: recall arrives at session start, on every prompt,
before a file is edited or a command runs, and after one fails. Keys and tokens are stripped as
the index is built, so what reaches the model is safe to send.
85.3% hit@1 on LongMemEval-S Β· 69.7% on LoCoMo Β· millisecond lookups over gigabytes of history Both harnesses ship in this repo and run on the public datasets in minutes Β·
check the numbers yourself
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.
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, Codex, Cursor, Qwen, OpenClaw and Copilot can take the same plugin bundle from
their own marketplaces instead:
sh
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 instead, from the main bucket every Scoop install already has:
powershell
scoop install deja-vu
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 not-wired, 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 search --json, ctx, blame, how to read
tier and total β 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, Copilot, VS Code Copilot Chat, Cursor, Goose, OpenClaw, Hermes, Roo Code, omp, Amp, prime-agent, DeepSeek Harness, Continue, Crush and Zed 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 gets the shared skill in ~/.agents/skills, which is what it reads; 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.
What you get
Solve it in Codex. Claude remembers. Thirty-three coding agents write every conversation
to local files, and deja turns those files into one memory layer all of them read.
Retroactive search
deja "connection pool exhausted" over gigabytes, including everything from before you installed deja. Natural-language questions fall back to a relevance tier. Time is a hint, not a filter.
Cross-agent recall
The MCP recall tool answers "we fixed this three weeks ago" in whichever agent asks, whoever solved it originally.
It survives compaction
Measured over 43 compactions: the summary keeps 77% of the decisions and 0.2% of the commands you ran. deja hands back the other 99.8% β and on Claude Code and Codex it captures the task, the files and the commands as the compaction starts, then returns them once in the next session.
Recall at the point of action
Before an agent edits a file or runs a command, deja names that file's prior decision, that command's working invocation, or the program this machine does not have. When a command fails, a PostToolUse hook answers with what followed that same error here before β the pair an agent never thinks to ask for.
It indexes the work, not just the talk
The files each turn opened, the commands that ran with their exit status, and the exact spans an edit replaced. That is the part every summary throws away.
Four more: rejected decisions, staleness, sync and handoff, redaction
It knows what held
deja promote <id> --state rejected --note "why" marks a decision you reverted. Every later hit for that session shows it was tried and rejected, with the reason. Nothing is deleted, and --state accepted takes the mark back.
It says when the ground moved
A hit reports 4 files this session touched have changed since, and says nothing when it cannot tell. It never claims anything is unchanged.
Sync and handoff
deja sync ssh laptop moves memory between machines, append-only, no cloud in the middle. deja handoff --to codex packages the live context so you can continue in another agent.
Redaction
Keys, tokens, JWTs and private key blocks are stripped at index time, so the cache is safe to keep.
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.
Indexing and search are local. The network is used only by deja update, deja sync ssh,
and the version check in deja doctor.
Credentials are redacted at index time: AWS keys, api_key= and token= assignments,
bearer tokens and raw JWTs, PEM private key blocks, provider tokens, scheme://user:pass@host
URLs, and high-entropy values for shapes no pattern knows. The value becomes
[redacted:<kind>] and the surrounding text stays searchable. deja share and
deja sync export re-apply redaction on the way out.
deja forget removes sessions from a rebuilt index and writes tombstones, so a later
deja index cannot restore them from the source history. --unforget lifts a tombstone.
Project exclusions are one pattern per line in ~/.config/deja/exclude; a line prefixed
harness: names a store instead β harness:opencode β and deja neither walks it nor asks
for the tool that would read it.
The security model documents data flows, redaction limits, trust
assumptions and release verification.
CLI
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 needed SameSite=Lax in local callback flow
Ask your history
Command
What it does
deja <query>
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).
deja
With an index and a terminal: today's sessions, recalls served, a question you asked in more than one session, and a wall your agents keep hitting.
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 <path>
Which sessions discussed a file, what was decided, and why.
deja files <topic>
The other direction: which files the work on a subject actually touched.
deja how <tool>
How this machine actually runs a thing, with the real flags, from what agents ran before.
deja fix <error>
What this machine ran after that same error before, when the error did not come back.
deja friction
Errors that hit three or more separate sessions, with the harnesses named.
Using what it finds, and moving it between machines
Use what it finds
Command
What it does
deja ctx <query>
Markdown digest of the best match, ready to pipe into a prompt.
deja resume <id>
Reopen a found session in its native harness.
deja restore <path>
Hand back a span an agent replaced, from the old_string its edit recorded. Never writes over the original.
deja promote <id>
Distill a session into a curated note with provenance, tags and a lifecycle state. Notes outrank raw transcripts.
deja share <id>
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, nothing leaves the machine.
deja stats
Your agent work, wrapped. --card draws it in the terminal, --card <file>.svg writes one for a profile, --html a browsable timeline.
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.
The server exposes one tool, deja, with a mode. deja install wires it in, so
this is only needed to configure an agent by hand. The six older tool names
(recall, recall_context, blame, fix, how, remember) still answer for
anything already wired to them.
What this machine ran, or changed, after that same error before.
how
what, project?, limit?
The real invocation, from what agents ran here.
remember
text, project?, tags?
Stores a durable decision for later recall.
Supported harnesses
With auto-recall installed, Claude Code and Codex hand deja the transcript as a
compaction starts, and it keeps what the summary is about to drop: the task, the
conclusions, the files, the commands with what each one did, and what was left
open. The next hook for the same session and workspace gives it back once, inside
a 4 KB budget, with a line saying whether the repository moved since. deja stats
counts the tool calls before the first edit after a compaction, which is the
number this is measured against. See automatic compaction
recovery for what is read, what is stored and where the
limits are.
import the server once in Settings -> MCP; enable the skill for the agent
Senpi
?
?
?
?
?
paste
none
gajae-code
β
β
β
β
β
paste
none
Kimchi Coding
β
β
β
β
β
paste
none
Command Code
β
β
β
β
?
paste
none
ZCode
β
β
?
?
β
paste
none
Kiro
β
β
β
?
β
paste
none
Kilo Code
β
β
β
β
β
paste
sqlite3 for the CLI store
Roo Code
β
β
β
β
β
paste
roo CLI (editor tasks reopen in the editor)
Zed
β
β
β
β
β
paste
sqlite3 + zstd
β works Β· β possible, not built yet Β· β the harness has no such mechanism Β· β blocked by an upstream bug Β· ? not investigated
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 all six 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:
codex plugin marketplace add https://github.com/vshulcz/deja-vu then codex plugin add deja-vu@deja-vu
Grok Build
plugin deja
grok plugin marketplace add xai-org/plugin-marketplace then grok plugin install deja
Either path is enough on its own, and having both is not a problem: the
opencode, dsh, Kimi, Grok and Codex packages read what deja install wrote and
contribute only what is missing, and in Zed both halves use one server id, so
there is nothing to have twice whichever order you install in.
Each uses the deja you already have; the copy it bundles is only the fallback.
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:
sh
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
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:
sh
export DEJA_EMBED_URL='https://example.com/v1/embeddings'export DEJA_EMBED_MODEL='embedding-model'export DEJA_EMBED_KEY='...'
deja embed
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.
Where the vectors live and what they cost
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
sh
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
bench block asks the question the other three 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 ms median (deja bench recall, 100 queries, half of them Russian), ~19 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 index is incremental. When a session file grows, only that file is re-read.
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
Does anything leave my machine? No, unless you ask it to. See the
data flows.
What about secrets already in my logs? They stay in the original harness files, which
are your agent's data. Known shapes β AWS keys, api_key=/token= assignments, bearer
tokens and bare JWTs, PEM blocks, provider tokens, high-entropy values β are stripped as
the index is built, so they do not reach digests, shares or sync exports. Pattern matching
is not secret detection: a shape it does not know can pass through. See the
security model.
Will it slow my agent down? A recall is a lexical lookup against a local index:
~0.7 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 β tens of milliseconds on a store of
a few gigabytes.
Do I have to change how I work? No. The agent calls recall itself, and with
auto-recall it already knows the project's prior decisions when the session opens.
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 eleven of them.
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 search reads them all in place, 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. Details: session files on disk.
What about Windows? Builds exist and CI runs the suite there. macOS and Linux are the
battle-tested paths. Field reports welcome in #9.
How do I wipe everything?
sh
deja uninstall --all
rm -rf ~/.cache/deja
Guides
Written for the situation rather than the feature:
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.
