🧠 deja-vu: Persistent Memory for AI Coding Agents

"Your agents already solved this."

Modern coding assistants like Claude Code, Codex, and opencode generate massive amounts of local session logs. These files contain gigabytes of critical design choices and bug fixes, yet they remain unsearchable dormant. deja transforms these static logs into a dynamic memory layer.

🚀 Core Capabilities

deja is a zero-dependency binary designed to give your agents a "long-term memory."

• Blazing Fast Search: Query gigabytes of history in $\approx 7\text{--}9\text{ms}$. It is retroactive, meaning it indexes logs created long before the tool was installed.
• MCP Recall: Via the Model Context Protocol, agents can now answer, "We already fixed this three weeks ago," instead of re-debugging the same issue starting from scratch.
• Auto-Context: By using install --auto, a SessionStart hook is created. This injects relevant memories into the agent's context before you even type a prompt.
• Privacy First: A built-in Redaction API automatically strips JWTs, private keys, and API secrets during indexing.
• Analytics: Use deja stats to view activity sparklines, top projects, and harness distributions.
• Portable Knowledge: Share sanitized session digests with teammates or sync your entire memory across multiple machines.

---

🛠️ Technical Architecture

deja operates entirely locally. There are no external services to manage and no models to download.

Note: For opencode indexing, the tool utilizes the sqlite3 CLI, which is standard on most Linux distributions and macOS.

---

📦 Installation & Setup

Follow these steps to get started:

• Install the binary (choose one method below)
• Configure your agents
• Verify indexing

Installation Methods

# Option 1: Quick install script
curl -fsSL https://raw.githubusercontent.com/vshulcz/deja-vu/main/install.sh | sh

# Option 2: Go install
go install github.com/vshulcz/deja-vu/cmd/deja@latest

# Option 3: Run via npm (no install required)
npx @vshulcz/deja-vu "your query"

# Option 4: Homebrew
brew install vshulcz/tap/deja-vu

Agent Integration

To wire deja into your existing tools (this modifies configs and creates .bak backups):

# Enable MCP recall for claude-code, codex, and opencode
deja install --all

# Enable MCP recall AND the SessionStart auto-recall hook for Claude Code
deja install claude-code --auto

---

💻 Command Reference

---

🔄 Synchronization & Advanced Usage

Context Piping (Non-MCP)

If you aren't using MCP, you can still feed memory into your agent manually: claude "Prior context: $( deja ctx 'database migration' )"

Syncing Across Machines

You can synchronize your memory using a shared folder (e.g., iCloud, Syncthing, or Git) or via SSH.

Via Shared Folder:

1. Machine A: deja sync export ~/Sync/deja (Appends new data)
2. Machine B: deja sync import ~/Sync/deja (Picks up new records)

Via SSH: deja uses your system's ssh/scp and looks for the binary on the remote PATH (or ~/.local/bin/deja).

• Push: deja sync ssh mini
• Pull: deja sync ssh mini --pull

Note: Import is idempotent, meaning you can run it repeatedly via cron without duplicating data.

---

🎓 Teaching Your Agent to Remember

To ensure your agent proactively uses its memory, add the following instruction to your CLAUDE.md or AGENTS.md file:

"Before attempting to debug or re-implement a feature, execute deja "query" or use the MCP recall tool. All previous sessions from Claude Code, Codex, and opencode are indexed locally. Use recall_context to get a Markdown digest of the most relevant past session."

Auto-Recall Logic: When --auto is enabled, the SessionStart hook automatically feeds the agent the most recent memory for the current project. This is:

1. Read-only.
2. Capped at $2\text{KB}$ to preserve context window space.