deja-vu: an agent memory layer built from session history you already have

The gap deja-vu fills: memory that starts full instead of empty

Most agent memory tools record forward. You install them, and from that day on they capture what the agent does. Everything before installation is gone, which for a developer with two years of Claude Code transcripts on disk is the interesting part. deja-vu takes the opposite position, stated on its own landing page: it starts full. It reads the session files that coding agents have already written locally and builds a searchable index over them.

The intended user is someone running more than one harness on the same machine. The README names Claude Code, Codex, Cursor, Qwen, OpenClaw and Copilot among the agents it wires into, and the install step claims to write guidance into seventeen harnesses' own configuration files. The problem is not that any single agent lacks memory. It is that the memory is trapped inside each one, in a different format, and none of them can see the others. Solve something in Codex and Claude has no idea it happened.

The second problem is compaction. The README cites a measurement over 43 compactions in which the summary retained 77% of the decisions but only 0.2% of the commands that were run. That asymmetry is the argument for indexing raw session data rather than summaries: the decisions survive, the exact invocation that worked does not.

How the index is built and queried without embeddings

The repository is a Go module, github.com/vshulcz/deja-vu, on Go 1.25, with the binary under cmd/deja. The Dockerfile builds it with CGO_ENABLED=0 and a static output, and the runtime stage installs sqlite from Alpine, which tells you the index is a SQLite database rather than a vector store. The Makefile's demo target confirms the shape of the configuration: DEJA_CLAUDE_ROOT, DEJA_CODEX_ROOT, DEJA_OPENCODE_DB and DEJA_INDEX_DIR are environment variables pointing at each agent's history and at the index file.

Retrieval is lexical. The README is explicit that there is no LLM and no embeddings, and that natural-language questions fall back to a relevance tier. The claimed figures are 85.3% hit@1 on LongMemEval-S and 69.6% on LoCoMo, with both harnesses shipped in the repository so they can be run against the public datasets. The README also states that keys and tokens are stripped while the index is built, so the content handed to the model has been redacted first.

The delivery mechanism is MCP over stdio, which is why the container's CMD is mcp and the entrypoint is deja. On top of that request-response path there are hooks: a PreToolUse hook surfaces a file's prior decision before an edit, and a PostToolUse hook answers a failing command with what followed the same error previously. That is a different retrieval trigger from "the model asked a question". It fires on the agent's own actions, whether or not the model thought to ask.

Installing deja-vu and running a first search

The README's primary path is a shell installer followed by a wiring command. The first line downloads and runs install.sh; the second detects agents, wires MCP recall into each, enables session-start recall where supported, and builds the initial index.

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

After that, start a new agent session and ask about something from months ago. The README's own example prompt is "have we dealt with jwt refresh rotation before? check your memory". With session-start recall enabled you do not need to ask, because the recall arrives when the session opens.

If you would rather not run the installer, there are package-manager routes. Homebrew, go install from the module path, and a one-shot npx invocation that needs no permanent install:

brew install deja-vu
go install github.com/vshulcz/deja-vu/cmd/deja@latest
npx @vshulcz/deja-vu "query"

On Windows the shell installer exits with unsupported OS. The README directs Windows users to Scoop, which is present in the standard bucket, or to the windows_amd64 zip from the latest release with deja.exe placed on PATH.

scoop install deja-vu

One thing worth knowing before you judge the install: the binary alone is a complete setup for searching. Indexing, search, show, ctx, blame, --json output and redaction all work without any agent wiring. What deja install adds is the MCP integration and session-start recall. On a binary-only setup, deja doctor reports every MCP target as not-wired, and the README says that is the intended state rather than a fault.

Where deja-vu is the wrong tool

The design assumes local files. Every configuration key visible in the Makefile points at a directory or a database on the same machine, and the index is a local SQLite file. If your agents run in containers, on remote dev boxes, or in a hosted IDE that never writes transcripts to your disk, there is nothing for the indexer to read. The Dockerfile ships deja itself as a container, but that is the server, not a collector for history that lives elsewhere.

Lexical retrieval is the second boundary. The absence of embeddings is the reason the tool is one binary with no model dependency, and it is also why a query that shares no vocabulary with the original session is likely to miss. The README acknowledges this by describing a relevance tier as the fallback for natural-language questions, which is a graceful degradation rather than a solution. Recall quality will track how closely your phrasing matches what was actually typed months ago.

The third limitation is operational. The README states that re-running install rewrites deja's skill or marked block without touching surrounding user content, which is a careful design, but it also means the tool edits files inside seventeen harnesses' configuration directories. On a machine where those files are managed by dotfile tooling or shared across machines, that is a change you will need to account for. The README does not document a rollback command for the wiring step.

How it differs from a model-driven memory service

The obvious alternative is a hosted memory layer that extracts facts from conversations with an LLM and stores them as structured records, then injects the relevant ones into the prompt. The difference is not just local versus remote. It is what gets stored. A model-driven memory keeps conclusions: the user prefers X, the project uses Y. deja-vu keeps evidence: the files each turn opened, the commands that ran with their exit status, the exact spans an edit replaced. The README frames that as the part every summary throws away, and it is the right framing, because a conclusion without its command is often not actionable.

The second difference is the install-time promise. A model-driven memory is empty on day one and improves as it observes you. deja-vu is useful within minutes because the corpus already exists. The trade-off runs the other way too: a forward-recording tool can capture things that never hit disk, such as a decision made in a chat that was never saved to a transcript, while deja-vu can only see what a harness chose to persist. If your agents do not write sessions to disk, the whole approach collapses, and no amount of configuration fixes it.

Maintenance, licensing and what an upgrade costs

The repository is not archived, and the last push was on 2026-08-29, with a nightly build on that date and v0.19.1 on 2026-08-28. That is a recent cadence, and the release naming suggests both tagged versions and nightlies are published. The go.mod declares Go 1.25, which is a hard floor for anyone building from source, and the Dockerfile pins golang:1.25-alpine and alpine:3.20.

Upgrade cost is mostly the index. The Makefile exposes DEJA_INDEX_DIR, so the index location is configurable, and the demo target passes --rebuild to regenerate it from scratch. That flag is the escape hatch if a schema change lands between versions: you rebuild rather than migrate. The README does not describe an in-place migration path, so treat the index as disposable and keep the source session files intact.

The licence is MIT, declared in both the repository LICENSE and the package.json for the DeepSeek Harness extension. MIT permits commercial use and modification with the copyright notice retained. That is a statement about the licence text, not legal advice; if you redistribute the binary inside a product, read the LICENSE file yourself.

Editorial conclusion

Adopt it if you run several coding agents on one machine and want recall over months of history without exporting anything to a service; the cost is one binary and an index directory. Skip it if you need a memory layer that works across machines, or if you want the model itself to decide what is worth remembering rather than a deterministic retriever. Before trusting it, run deja doctor to see which MCP targets are wired, and re-run the LongMemEval-S harness in the repo on your own history rather than accepting the README's 85.3%.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes