Agents & MCP
what each agent gets, and what it does with it
deja runs an MCP server (deja mcp, stdio) that exposes your indexed history to any MCP-capable agent. deja install wires it into the agents it detects.
Tools
One tool, deja, with a mode argument — eight capabilities behind one entry so an agent's tool list stays short. The names below are still callable as tools of their own for clients wired before the change; context was recall_context.
| Mode | What it does |
|---|---|
recall | Search past sessions across every agent and return dense matches under ~4 KB. Fires on phrases like "didn't we fix this before". |
context | Return a markdown digest of the single best-matching session: the code it changed, as the lines each edit removed and added, then the problem, decision and outcome. |
blame | Given a file path, the prior sessions that discussed it, most specific first. git blame for the conversations behind the code. |
fix | Given a failing error, the command this machine ran after that same error before, when it did not come back. Matched on the error itself, not its words — evidence, not a guaranteed fix. |
how | How this machine actually runs a thing — the real command with the real flags, from what agents ran before. Call before inventing a build, test or deploy invocation that a guess would get wrong on this setup. |
orient | What work looks like in this project: the commands past sessions ran here, ranked by how many ran them, and the files they opened or edited. For the start of a session in an unfamiliar repository, in place of reading the tree to find out. |
remember | Store a durable decision so a future session can recall it. Redacted and indexed like any other source. |
handoff | Pick up another session's work where it stopped: its goal, the instructions it was given, its latest conclusions and the checks that passed. Takes a session id or a harness name; empty means the newest other session in this project. The same packet deja handoff prints, for agents that reach deja only through MCP. |
Auto-recall
deja install --auto wires recall into the moments an agent works, not only when it thinks to ask. Where a harness supports each hook, memory arrives on its own at five points:
- At session start — relevant project memory before you type, ranked by the files your repo is touching, and led by the decisions you promoted accepted for this project, so the agent follows what was settled instead of re-deciding it. Read-only, capped at 2 KB, framed as untrusted historical data so it never acts as an instruction.
- On each prompt — deja searches your history for what the prompt is actually about, and when it matches work already answered says so out loud, naming the agent it came from:
deja-vu — from Codex CLI, 4 months ago: "…". Wired wherever the harness hands a hook the prompt: in 33 of the 43 harnesses deja reads, and in part in 5 more, harness by harness in the per-prompt column under hook surfaces. Goose gets it underdeja goose. The rest get the session-start half only, which is memory chosen before you typed. Grok Build runs the hook but discards what it prints. - Before an edit or a command — a PreToolUse hook names that exact file's or command's prior decision, the fix that held, the invocation that worked, or a program this machine does not have, so the agent acts on what was settled rather than re-deriving it. A decision stands from the second session; a bare count of sessions needs five, because a count is a number an agent can do nothing with. A missing program is not named while it is on the hook's
PATH. Wired in 32 of the 43 harnesses, and in part in 5 more, listed in the pre-tool column under hook surfaces; opencode, pi, omp and Reasonix have no seam before an edit that reaches the model, so there the same line arrives with the tool's result. - When a command fails — a PostToolUse hook reads the error and, if this machine has run something after that same error before without it coming back, says what that was. Measured over eighteen opportunities, an agent asked for that pair by tool exactly zero times: it does not occur to a model to check. Delivered at the failure it lands every time. A remedy that itself exited non-zero is not offered, nor one from another project, nor a merge, a force push or a deletion.
- Before a context compaction (Claude Code, Codex, TRAE CLI, CodeBuddy, WorkBuddy, Muse Code, opencode, Kilo CLI, Cline CLI, Copilot CLI, VS Code Copilot Chat, Qwen Code, Kimi Code, Grok Build, Cursor CLI, pi, omp, Senpi, gajae-code, prime-agent, OpenClaw and DeepSeek Harness, Hermes through its memory provider, and Gemini CLI on the next prompt; Reasonix gets the same record added to its summarizer's instructions) — deja reads the transcript as the compaction starts and keeps the task, the conclusions, each command with whether it passed or failed, and what a turn said was still open; the open lines are carried until something closes them, for up to two compactions. The next hook for the same session and workspace hands that back once, in 4 KB, with a line saying whether the repository moved since. See after compaction.
Session-start auto-recall is wired across every harness that exposes a start hook — Claude Code, Codex, Cursor, Gemini CLI, opencode, Qwen, Kimi, Cline, Antigravity, OpenClaw, omp, DeepSeek Harness, Goose, Hermes and Reasonix among them; the harness matrix is the source of truth. Where only MCP is available, recall is still one tool call away.
The same injection carries what this machine keeps failing on: an error that hit three or more separate sessions — a binary that is not installed, a Python module that was never added — counted from the transcripts themselves. Agents rediscover those one failed command at a time, so the block says the count and what to do instead. It is served once per session, appears at session start where a hook is wired and on the first recall where only MCP is, and stays silent until something has failed in three separate sessions. A wall leaves the block on its own after 30 days without a hit while its projects keep getting new sessions, or at once with deja friction --settle <id>. A settled wall comes back if a session started after the settle hits it again.
Windows
cmd /c deja mcp. deja install writes that form automatically.Seeing it work
Memory that lands silently builds no habit, so the hooks talk — once, when it matters. The session-start receipt names how many sessions were recalled and the day's tally; a per-prompt match on already-solved work announces deja-vu — from Codex CLI, 3 weeks ago: "<what was said there>", at most once in twenty minutes and counted per session rather than per machine, so a second agent opened alongside the first still hears it; and deja log --last replays the exact digest an agent received. Asking the same thing again inside the hour is met with silence rather than the next session down the list — the answer is still on your screen.
Found this useful? Star deja-vu on GitHub.