llms.txt

# Deja Vu

> A 3-file memory system for any capable AI coding agent.

Deja Vu helps agents stop re-explaining the same repository context across new coding-agent chats through:

- explicit project rules
- a repeatable cue-scan, minimal-recall, and writeback workflow
- tiny Markdown and JSONL memory files inside the repository
- cue quality checks that keep the first recall step sparse and specific
- recall budget and outcome feedback that show whether memory helped, missed, or overloaded the task
- writeback routing and feedback reports that keep remembered project context durable and maintainable
- optional `deja-vu init`, `deja-vu doctor`, and `deja-vu explain` CLI support

The minimum adoption path is three files: `AGENTS.md`, `memory/summary.md`, and `memory/impressions.jsonl`. It does not require npm, embeddings, vector search, a daemon, or a dedicated memory service.

## Best starting points

- [README](./README.md): product overview and primary adoption path
- [Starter Kit](./starter-kit/README.md): copy-first three-file setup and per-agent prompts
- [Comparison](./docs/comparison.md): how Deja Vu differs from vector DBs, hosted memory, runtimes, notes, and transcripts
- [Agent Compatibility](./docs/agent-compatibility.md): which agents can follow the protocol and how chat-only agents can use it manually
- [Flow Diagram](./docs/diagrams/deja-vu-flow.md): cue scan, minimal recall, durable writeback
- [Demo Walkthrough](./docs/demo-walkthrough.md): before/after project memory example
- [Protocol](./docs/protocol.md): normative protocol definition
- [Workflow](./docs/workflow.md): recall, writeback, and compaction lifecycle
- [Markdown Storage](./docs/storage-markdown.md): minimum and optional memory layout
- [Impression Layer](./docs/impression-layer.md): compact keyword-first familiarity surface
- [Scripted Recall](./docs/scripted-recall.md): host script contract for cheap pre-task scans
- [v0.6.0 Candidate](./docs/release-v0.6.0.md): adoption release checklist
- [Templates](./docs/templates): copyable rules and memory templates
- [Protocol Example](./examples/protocol-project): repo-first example with no engine

## Optional engine references

- [Optional Engine Layer](./docs/engine/semantic-engine.md)
- [Protocol-to-Engine Mapping](./docs/engine/protocol-to-engine.md)
- [Plugin Types](./src/types/plugins.ts)
- [Memory Types](./src/types/memory.ts)
- [Core Engine](./src/core/semantic-recall-engine.ts)

## Concepts

- protocol-first memory
- cue-first recall
- project-scoped continuity
- recall before substantial work
- impression-first scripted recall
- cue quality linting
- gist-first summaries
- boundary-aware chunking
- recall budget
- recall outcome feedback
- selective writeback
- event ledger continuity
- Markdown memory
- compaction and supersession
- optional semantic recall engine

## Intended use

Use Deja Vu when you want:

- durable continuity across new conversations
- explicit and inspectable project memory
- a lightweight memory discipline that works in many agent environments
- an optional path to semantic recall without changing the core workflow

Do not treat this repository as a hosted memory platform or autonomous memory daemon.