deja-vu: Retroactive Memory for AI Coding Agents

Introduction

deja-vu is a unique, local-first memory tool designed for AI coding agents. It tackles the common problem of agents forgetting past solutions or re-debugging issues already resolved. Unlike many memory solutions that start empty and record forward, deja-vu begins by indexing the session history your agents, such as Claude Code, Codex, Cursor, and many others, have already written to disk. This includes months of data from before you even installed it.

Built as a single local Go binary, deja-vu provides powerful recall capabilities without requiring an external LLM or embeddings by default, though semantic recall is an optional feature. It ensures your agents have access to their collective past, improving efficiency and preventing repetitive work.

Why Use deja-vu and its Benefits

deja-vu offers a comprehensive set of features to enhance your AI coding agent's memory and productivity:

• Retroactive Search: Search gigabytes of your past coding sessions, including history from before deja-vu was installed. Natural-language queries are supported, with time acting as a hint, not a filter.
• Cross-Agent Recall: A solution found in one agent, like Codex, can be recalled by another, like Claude, through the MCP recall tool. This creates a unified memory layer across all your supported agents.
• Survives Compaction: While agents might compact their own history, discarding most commands, deja-vu preserves the full context, including decisions and commands, ensuring nothing is lost.
• Recall at the Point of Action: deja-vu provides context precisely when it's needed. It can recall prior decisions before an agent edits a file or runs a command, and suggest solutions for errors immediately after a command fails.
• Indexes the Work, Not Just the Talk: Beyond just conversations, deja-vu indexes the actual work performed, such as files opened, commands executed (with exit status), and exact code changes, which are often discarded by summaries.
• Rejected Decisions: Mark decisions you reverted with deja promote <id> --state rejected --note "why". This ensures future recalls show that a particular approach was tried and rejected, along with the reason.
• Staleness Awareness: When recalling a session, deja-vu can report if files touched in that session have changed since, providing crucial context about the current relevance of the old solution.
• Sync and Handoff: Easily move your memory between machines with deja sync ssh laptop without relying on cloud services. You can also package live context to continue work in a different agent using deja handoff --to codex.
• Redaction: Sensitive information, including API keys, tokens, and private key blocks, is automatically stripped at index time, making your local memory cache safe to keep and share.
• Work Visualization: The deja stats --card command can draw a heatmap of your agent sessions directly in the terminal or generate an SVG for your profile README, offering insights into your agent's activity.

Installation

Getting started with deja-vu is quick and straightforward. The recommended installation method for macOS and Linux is via a simple curl command:

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

The first command installs the deja binary. The deja install --auto command then wires MCP recall into every agent it finds, turns on session-start recall where supported, and builds the initial index of your existing agent history.

For Windows users, Scoop is the recommended method:

scoop install deja-vu

Other installation options include brew install deja-vu, go install github.com/vshulcz/deja-vu/cmd/deja@latest, or trying it without installation using npx @vshulcz/deja-vu "query".

Examples

Once installed, you can immediately start querying your agent's collective memory:

• Search your history:

  deja "jwt refresh token"
  

  This command searches across all your agent histories for relevant sessions, providing snippets of what was discussed and decided.
• Understand file changes:

  deja blame <path>
  

  Find out which sessions discussed a specific file, what decisions were made, and why.
• Get a markdown digest for your prompt:

  deja ctx <query>
  

  This provides a Markdown summary of the best-matching session, ready to be piped directly into an agent's prompt.
• Find solutions for errors:

  deja fix <error>
  

  Discover what commands or actions were successfully run after encountering a specific error in the past.
• Identify recurring issues:

  deja friction
  

  See errors that have appeared in three or more separate sessions, helping you identify persistent problems.

Links

For more detailed information, documentation, and to contribute, please visit the official resources:

• GitHub Repository: vshulcz/deja-vu
• Official Documentation: deja-vu Docs
• Benchmarks: Check the Numbers Yourself
• How it Compares: Comparison with Other Memory Tools