Deja Vu

A cue-first memory protocol for AI agents

Deja Vu is a lightweight memory protocol built around one loop:

task cue -> familiarity score -> minimal recall -> durable writeback

The protocol is packaged as three project-local assets:

• rules
• workflow
• tiny memory files

The goal is not to give every agent a heavy runtime. The goal is to give any agent a repeatable discipline for spending almost no tokens until the task proves that deeper memory is useful.

What Deja Vu Is

Deja Vu defines a shared memory behavior for agents working inside one project.

It answers:

• what should count as durable memory
• when an agent should recall existing memory
• how memory should be stored in ordinary project files
• when memory should be updated, compacted, or retired

The minimum viable setup uses two project-local plain text files:

• memory/summary.md
• memory/impressions.jsonl

No npm package, embeddings, vector search, or database is required.

Start Here

If you want to adopt Deja Vu in a project without extra infrastructure:

1. Read docs/protocol.md.
2. Read docs/workflow.md.
3. Read docs/impression-layer.md.
4. Read docs/scripted-recall.md.
5. Copy the minimum templates from docs/templates.
6. Add optional decision, open-loop, event, and context records only when the project needs them.

Recommended first files:

• docs/templates/AGENTS.template.md
• docs/templates/memory/summary.md
• docs/templates/memory/impressions.jsonl
• docs/templates/memory/decisions/decision-template.md
• docs/templates/memory/open-loops/open-loop-template.md

The Protocol in One Page

Deja Vu follows a cue-first lifecycle:

1. Scan a tiny impression index before substantial planning, coding, or answering.
2. Load no memory when the scan finds no familiarity.
3. Load the project summary when the scan finds weak familiarity.
4. Load one to three detailed records only when the scan finds strong familiarity or the task requires depth.
5. Write back only durable outcomes that should change a future agent's behavior.
6. Compact or supersede memories when detail becomes repetitive or stale.

This keeps memory project-local, readable, and easy to maintain across new conversations.

Canonical Project Layout

memory/
  summary.md
  impressions.jsonl
  decisions/
  open-loops/
  events/
  context/
  index.md

The canonical layout and field rules are specified in docs/storage-markdown.md.

Core Rules

• Use a single-project scope only in MVP: project:<project-id>.
• Recall before substantial work, but follow a strict recall budget.
• Prefer scripted impression scans first; open summary or detailed records only when needed.
• Write back only durable memory:
  • decisions
  • architecture intent
  • stable preferences
  • unresolved follow-up items
  • milestone summaries
• Default recall budget:
  • impression scan: always allowed
  • summary: at most one file
  • detail: one to three records
  • full memory tree: forbidden unless explicitly requested
• Never store:
  • raw secrets or credentials
  • full turn-by-turn transcripts
  • low-signal chatter
  • disposable exploration noise

Why This Exists

Most agent memory systems fail in one of two ways:

• they remember too little because nothing is written down in a reusable shape
• they remember too much because every conversation turn is treated like durable knowledge

Deja Vu stays closer to first principles:

• memory should be explicit
• memory should be scoped
• memory should be cheap to inspect
• memory should be easy to revise
• memory behavior should survive a new conversation window

Optional Engine Layer

This repository still includes the existing TypeScript semantic recall engine.

Use it when you want:

• stronger familiarity scoring
• threshold-gated summary and chunk loading
• embedding and vector ranking
• an engine-backed implementation of the Deja Vu protocol

Do not treat the engine as the product center. It is an optional acceleration layer.

Start here if you want that path:

• docs/engine/semantic-engine.md
• docs/engine/protocol-to-engine.md
• docs/agent-handshake.md

Optional npm Install

npm install @focaxisdev/deja-vu

The npm package provides the optional TypeScript engine. It is not required for base protocol adoption.

Engine API

const engine = new SemanticRecallEngine(config);

await engine.addMemory(input);
await engine.scanImpressions(query);
await engine.recall(query);
await engine.getSummary(id);
await engine.getChunks(id);
await engine.updateMemory(id, input);
await engine.deleteMemory(id);

The public TypeScript exports remain intact for hosts that want semantic recall.

scanImpressions() performs token-only familiarity scanning and does not load summaries or chunks.

Examples

• Protocol-first example: examples/protocol-project
• Engine example: npm run example:basic
• Engine example: npm run example:agent-pm
• Engine example: npm run example:chat-memory
• Engine example: npm run example:task-assistant

Repo Structure

deja-vu/
  docs/
    protocol.md
    workflow.md
    storage-markdown.md
    templates/
    engine/
  examples/
    protocol-project/
    basic/
    agent-pm/
    chat-memory/
    task-assistant/
  src/
  tests/

Development

npm install
npm run build
npm run test:src
npm run lint:memory

References

• docs/protocol.md
• docs/workflow.md
• docs/storage-markdown.md
• docs/impression-layer.md
• docs/scripted-recall.md
• docs/bootstrap-instructions.md
• docs/project-rules-template.md
• llms.txt