Stop re-explaining your repo every time you open a new AI coding-agent session.
Deja Vu is a three-file, repo-local memory system that any capable coding agent can follow. It keeps durable decisions and constraints beside the code, then loads only the smallest useful slice for the current task.
No database. No vector store. No embeddings. No SaaS. No daemon. No required npm install.
In a fresh repo, run:
npx @focaxisdev/deja-vu initThat creates only the three required files:
AGENTS.md
memory/summary.md
memory/impressions.jsonl
Already have an AGENTS.md? Preserve it and append an idempotent, clearly marked Deja Vu rules block:
npx @focaxisdev/deja-vu init --merge-agentsInspect the plan without touching files, or verify the finished setup:
npx @focaxisdev/deja-vu init --dry-run
npx @focaxisdev/deja-vu doctor
Then start the next agent session with:
Follow AGENTS.md. Scan memory/impressions.jsonl before substantial work, load only the matching memory, and write back durable project context only.
Prefer a zero-package setup? Copy the starter-kit/ instead. npm is a convenience layer, not the product.
| Without Deja Vu | With Deja Vu |
|---|---|
| “Here is the architecture again…” | The repo carries a compact project summary. |
| “We already rejected that approach because…” | Accepted decisions survive new chats. |
| “Do not break the workaround from last week…” | Strong task cues route to one to three relevant records. |
| Load a huge notes file or old transcript | Scan tiny cues first; load nothing when there is no match. |
| Memory stays trapped in one vendor | Markdown and JSONL travel with the repo. |
Deja Vu does not replay old chats. It helps a new session recognize what it needs to know before planning.
Tells an agent when to recall, how much to load, what to write back, and what never belongs in memory.
Keeps the current objective, stable constraints, active priorities, accepted decisions, and unresolved follow-ups. It is compact project truth, not a log.
Keeps tiny, inspectable routes from task language to the right memory file:
{"schema_version":1,"id":"settings-sync","scope":"project:your-repo","title":"Settings stay server-backed","keywords":["settings","sync","preferences","localstorage"],"record_path":"memory/decisions/settings-sync.md","updated":"2026-08-09","weight":0.9,"status":"active"}This separation matters: rules tell the agent what to do, the summary restores broad context, and impressions prevent broad context from being loaded for every task.
task
-> scan memory/impressions.jsonl
-> none: load nothing
-> weak: load memory/summary.md
-> strong: load 1-3 linked records
-> work
-> write back durable memory only
Default recall budget:
- impression scan: always allowed
- summary: at most one file
- detailed records: one to three files
- full memory tree: only when the user explicitly asks
The goal is not to store more. The goal is to recall less, better.
The protocol is vendor-neutral. It is a strong fit when an agent can read repo files, follow project instructions, and update files.
Short prompts are included for:
For chat-only tools, paste the rules and only the relevant memory files manually. Deja Vu is a protocol agents can follow; it does not claim every agent supports it automatically. See agent compatibility.
Tracked memory is part of the repo and may be public. Write back only context that should change future work:
- accepted decisions and architecture intent
- stable project constraints and preferences
- unresolved follow-ups
- milestone summaries
- sparse recall-quality feedback
Never store secrets, credentials, private keys, customer or user PII, full transcripts, raw logs, or disposable exploration noise.
deja-vu doctor validates the required setup and flags obvious secrets, transcript-like content, oversized memory, malformed JSONL, and unresolved feedback routes. It is a guardrail, not a complete secret or PII scanner.
The optional CLI serves the file-first protocol:
npx @focaxisdev/deja-vu init --agents codex,claude-code
npx @focaxisdev/deja-vu init --merge-agents
npx @focaxisdev/deja-vu doctor --json
npx @focaxisdev/deja-vu explaininit creates missing files only. It never replaces existing files unless --force is explicitly passed. When AGENTS.md already exists without Deja Vu rules, the command reports that setup is incomplete; --merge-agents appends a marked block without deleting existing rules.
Focused tools are also available:
deja-vu-scan-memory "current task"
deja-vu-lint-memory --memory-root memory
deja-vu-feedback-report --memory-root memoryDeja Vu Protocol v0.4 defines the lifecycle:
- scan tiny cues
- classify familiarity as none, weak, or strong
- load the smallest useful memory
- work normally
- write back durable context only
- compact or retire stale memory when recall gets noisy
Start here:
- Starter kit
- Demo walkthrough
- Protocol
- Comparison with other memory approaches
- Workflow
- Markdown storage contract
- Scripted recall
- Architecture
- llms.txt
The package also contains the original TypeScript semantic recall engine for projects that outgrow manual cue routing. It adds threshold-gated recall and plugin seams for embeddings, storage, scoring, and vector search while keeping Markdown memory canonical.
npm install @focaxisdev/deja-vuimport { createInMemorySemanticRecallEngine } from "@focaxisdev/deja-vu";
const engine = createInMemorySemanticRecallEngine({
thresholds: { strong: 0.6, weak: 0.45 },
});Read the engine guide or run the basic example. The engine is an optional acceleration layer, not the default adoption path.
Issues and focused pull requests are welcome. Read CONTRIBUTING.md for the project boundaries and verification commands.
npm ci
npm run test:src:readonly
npm run check:links
npm run lint:memory
npm run report:feedback
npm testnpm test rebuilds dist and verifies package contents. Use test:src:readonly when you want source tests without build-output side effects.
If Deja Vu saves you one repo re-explanation, star the repository so other coding-agent users can find it.