Dejavu

Memory that lets coding agents continue instead of start over

A fast, repository-scoped memory for coding agents —
stored in one inspectable SQLite file.

Local · Bounded · Cited · Honest about uncertainty

Quick start  · 
Agent setup  · 
Features  · 
API  · 
CLI

No account. No daemon. No embeddings required. No transcript dump into the prompt.

Local Dejavu is the production surface in v0.1.0. Shared mode is a tested preview and intentionally remains local-only until its security review is complete.

The problem

Coding agents repeatedly lose the expensive parts of prior work:

A notes database is not enough. Real agent memory must appear in the right repository, fit inside a context budget, distinguish relevance from trust, stop surfacing completed work, and expose evidence when it fails. Those constraints shape Dejavu.

What Dejavu is

Dejavu gives an agent a fast, repository-scoped memory between sessions. It stores decisions, preferences, procedures, pitfalls, facts, and work-in-progress as immutable slips in one inspectable SQLite file, indexed with FTS5 full-text search.

How it works: the session loop

An agent remembers and leaves a handoff when a session ends, then recalls a bounded, cited packet when the next session starts — closing the loop with useful/wrong feedback.

flowchart LR
    subgraph SN["Session N — finish"]
        A1["Coding Agent"]
    end
    subgraph SN1["Session N+1 — continue"]
        A2["Coding Agent"]
    end

    DB[("SQLite + FTS5<br/>repository-scoped")]

    A1 -->|"remember / keep"| DB
    A1 -->|"leave a handoff"| DB
    DB -->|"recall: bounded, cited packet<br/>+ active handoff"| A2
    A2 -->|"useful / wrong / missed feedback"| DB

Architecture

Three access surfaces (CLI, MCP server, library) share one core engine, which composes small deterministic modules over a single local SQLite store.

flowchart TB
    subgraph Access["Access surfaces"]
        CLI["CLI<br/><i>src/cli.ts</i>"]
        MCP["MCP server<br/><i>src/mcp.ts</i>"]
        LIB["Library API<br/><i>Dejavu — src/index.ts</i>"]
    end

    subgraph Core["Core engine"]
        CTX["context<br/>repo scope derivation"]
        LC["lifecycle<br/>session id + trust"]
        FMT["format<br/>bounded packets"]
        NA["next-agent<br/>ranker (off by default)"]
    end

    STORE[("storage<br/>SQLite + FTS5<br/>slips · links · handoffs<br/>recall_traces · messages")]

    CLI --> LIB
    MCP --> LIB
    LIB --> CTX
    LIB --> LC
    LIB --> FMT
    LIB --> NA
    LIB --> STORE
    CTX --> STORE

Repository isolation is the foundation. The context module derives a stable scope from the nearest Git repository and its normalized origin, so two checkouts of the same repo share memory while unrelated projects stay isolated.

Recall pipeline

Recall is local, deterministic, and budget-aware. It matches, follows supersession to current truth, deduplicates, and stops before the packet exceeds the token budget.

flowchart LR
    Q["recall(query)<br/>+ token budget<br/>+ kind filters"] --> SC["resolve<br/>repository scope"]
    SC --> FTS["FTS5 / BM25<br/>lexical match"]
    FTS --> SUP["follow 'supersedes'<br/>→ current slip"]
    SUP --> DED["deduplicate"]
    DED --> BUD{"within token<br/>budget?"}
    BUD -->|yes| PKT["add hit:<br/>kind · trust · provenance · links"]
    PKT --> BUD
    BUD -->|no| OUT["context packet<br/>+ active handoff<br/>+ trace receipt"]

Quick start

Dejavu currently requires Bun.

# Add and initialize
bun add github:sanjayrohith/Dejavu
bunx github:sanjayrohith/Dejavu init

git clone https://github.com/sanjayrohith/Dejavu
cd Dejavu
bun install
bun run src/cli.ts init

dejavu init creates ~/.dejavu/dejavu.db and prints MCP configuration for Claude Code, OpenCode, and Pi.

Agent setup (60 seconds)

{
  "mcpServers": {
    "dejavu": {
      "command": "bunx",
      "args": ["github:sanjayrohith/Dejavu", "mcp"]
    }
  }
}

The tool descriptions are the operating contract. Dejavu does not require a SKILL.md, AGENTS.md, or a memory paragraph copied into every system prompt.

recall("")

handoff({
  summary: "Implemented scoped auth",
  next: ["run the remote smoke test"]
})

What ships in v0.1.0

Repository isolation by default

Dejavu derives a stable scope from the nearest Git repository and its normalized origin. Two checkouts of the same repository share a scope; unrelated repositories do not leak slips or handoffs into each other.

Use DEJAVU_SCOPE=global deliberately for a cross-project preference. Global slips may match any repository query, but global handoffs never direct repository work. Databases created before scoping migrate safely to legacy:global and are excluded unless DEJAVU_INCLUDE_LEGACY=1 is set during migration.

Typed memory without filing work

Every slip has exactly one kind:

Agents may set the kind. If they don't, Dejavu uses a conservative deterministic heuristic — never a hidden model call.

Bounded context packets

const result = d.recall("deploy staging", {
  limit: 8,
  maxTokens: 700,
  kinds: ["decision", "procedure", "pitfall"],
});

Dejavu retrieves locally, follows explicit supersession to current memory, deduplicates, and stops before the packet grows beyond the budget. Each hit carries its kind, provenance, evidence trust, and links.

Trust is not relevance

BM25 answers "does this text match?" — not "is this true?" Dejavu keeps those concepts separate:

Mutable facts should still be checked against live code and systems. Dejavu never labels a lexical match "authoritative."

Current truth without rewriting history

Slips are immutable. A correction creates a new slip and links it:

const old = d.remember("Use Jest", { kind: "decision" });
const current = d.remember("Use Vitest", {
  kind: "decision",
  links: [{ toId: old.id, kind: "supersedes" }],
});

Recall follows supersedes to the current slip. contradicts keeps both claims visible. The history remains inspectable.

Handoffs that stop when work stops

A handoff is an active continuation packet, not a permanent instruction:

const h = d.handoff({
  summary: "Auth refactor is implemented but not deployed.",
  next: ["run integration tests", "deploy canary"],
});

// Later:
d.resolveHandoff(h.id, "completed");

Only active, repository-scoped handoffs appear in normal recall. Resolved or abandoned work no longer directs the next agent. An unresolved handoff older than three days is labeled stale and advisory, so an agent verifies it before acting.

A measurable feedback loop

By default, each recall returns a content-free receipt id. After acting, an agent can assess the retrieval:

const result = d.recall("test runner");
d.assessRecall(result.traceId, "useful");

The trace stores query, scope, returned IDs, handoff ID, session, author, and timestamp — but not memory text or transcripts. Library callers handling sensitive queries may disable trace storage with recordRecallTraces: false (those calls return traceId: null). dejavu eval reports scoped evidence so retrieval changes can be evaluated against real use.

Agent API

import { Dejavu } from "dejavu";

const d = new Dejavu();

const slip = d.remember("Decision: use Bun for repository scripts", {
  kind: "decision",
  tags: ["tooling"],
});

d.keep([slip.id]);

const recalled = d.recall("repository runtime", {
  maxTokens: 600,
  kinds: ["decision", "pitfall"],
});

if (recalled.hits[0]) d.used(recalled.hits[0].slip.id);
d.assessRecall(recalled.traceId, "useful", "avoided rechecking package scripts");

d.handoff({
  summary: "Converted scripts to Bun; tests pass.",
  next: ["update the release workflow"],
});

Core lifecycle

d.remember(text, options?)
d.keep(ids)
d.recall(query, { limit?, maxTokens?, kinds? })
d.handoff({ summary, next? })
d.resolveHandoff(id, "completed" | "abandoned")

Evidence and correction

d.used(slipId)
d.wrong(slipId)
d.forget(slipId)
d.link(fromId, toId, "supersedes" | "contradicts" | "related")
d.assessRecall(traceId, assessment, note?)
d.recallReport()

Deliberate bulk cleanup

d.forgetSession(sessionId) // current repository scope only

MCP tools

The local MCP server exposes two small groups.

The mailbox is intentionally not memory truth — it is a small local coordination channel.

CLI

dejavu init
dejavu verify
dejavu stats

dejavu recall                         # scoped recents + active handoff
dejavu recall "deployment decision" --tokens=700 --kind=decision,pitfall
dejavu remember "Decision: deploy with Wrangler" --kind=decision --keep
dejavu handoff "Canary is live; verify logs next"
dejavu resolve <handoff-id> completed

dejavu link <new-id> supersedes <old-id>
dejavu assess <trace-id> useful "saved a repository scan"
dejavu eval

dejavu ls
dejavu show <slip-id>
dejavu handoffs
dejavu forget-session <session-id> --yes

Destructive session cleanup requires --yes and is restricted to the current repository scope.

Storage & migration

The default database is ~/.dejavu/dejavu.db.

Schema changes are additive and run automatically when Dejavu opens the database. Existing text is never rewritten during migration.

Environment variables

DEJAVU_DB=~/.dejavu/dejavu.db   # database path
DEJAVU_AUTHOR=pi                # provenance identity
DEJAVU_SESSION=<conversation>   # stable session supplied by the harness
DEJAVU_SCOPE=global             # deliberate override; normally automatic
DEJAVU_INCLUDE_LEGACY=1         # temporary pre-v0.1 migration aid

Local SQLite is plaintext. Do not store credentials, customer data, or secrets. See SECURITY.md for the supported boundary and vulnerability-reporting guidance.

Shared mode — preview

Shared Dejavu uses Cloudflare infrastructure only: a Worker fronts one Durable Object SQL database per memory space, streams numbered committed changes over SSE, and clients keep rebuildable local SQLite/FTS mirrors.

flowchart TB
    subgraph Cloud["Cloudflare (preview — do not deploy yet)"]
        W["Worker"] --> DO[("Durable Object<br/>SQL authority")]
    end

    subgraph CA["Client A"]
        MA[("Local SQLite<br/>mirror + FTS")]
    end
    subgraph CB["Client B"]
        MB[("Local SQLite<br/>mirror + FTS")]
    end

    MA -->|"write"| W
    W -->|"commit + revision (write receipt)"| MA
    DO -->|"numbered changes · SSE"| MA
    DO -->|"numbered changes · SSE"| MB

It already proves: server commit before write receipt; immediate read-after-write in the writer's mirror; live peer updates that never block writes; contiguous revision watermarks and explicit stale state; offline catch-up; replayable hard deletion with payload redaction; bounded stream lifetimes and reauthentication points; and token-to-space isolation in local dogfood.

Run the full two-client proof locally:

./shared-server/test-local.sh

Do not deploy it yet. Bearer-token dogfood is not a production identity system. Multi-user use still requires verified identity, revocation, content policy, audit/retention decisions, and an encryption story. The blocking review is documented in docs/shared-security-review.md. See docs/shared-memory.md for the protocol and docs/shared-memory-implementation-contract.md for invariants.

Project structure

Dejavu/
├── src/                    # Core engine, MCP server, CLI
│   ├── index.ts            #   Dejavu library API
│   ├── storage.ts          #   SQLite + FTS5 store
│   ├── context.ts          #   repository scope derivation
│   ├── lifecycle.ts        #   session id + trust helpers
│   ├── format.ts           #   bounded recall/recents packets
│   ├── next-agent.ts       #   experimental ranker (off by default)
│   ├── mcp.ts              #   local MCP server
│   ├── cli.ts              #   command-line interface
│   ├── shared-authority/   #   shared-mode server authority
│   ├── shared-mirror/      #   shared-mode local mirror + SSE client
│   └── shared-client/      #   SharedDejavu client facade
├── shared-server/          # Cloudflare Worker + Durable Object (preview)
├── test/                   # Unit + integration tests
├── bench/                  # Recall latency + behavior benchmarks
├── eval/next-agent/        # Retrieval evaluation harness + retained results
├── docs/                   # Roadmap, specs, benchmark claims, loop notes
└── experiments/            # Research spikes and receipts

Evidence

Run the complete local release gate:

bun run check

bun test ./test
bun run typecheck
bun run bench/recall.ts
bun run bench:behavior

The repository also contains:

• docs/bench/claims.md — claim-to-evidence map;
• docs/loops/ — failed and successful agent-behavior experiments;
• experiments/ — Cloudflare shared-memory protocol receipts;
• experiments/MEMORY-SEAMS-2026-06-11.md — Cloudflare-native Workspace, Containers, Workflows, DO, AI Gateway, Access, continuity, provider-contract, and model-compatibility experiments;
• eval/next-agent/ — a retained negative result that kept an unproven ranker from becoming default behavior.

The eight-case lexical benchmark is a smoke test, not proof that memory improves agents. Recall receipts and baseline-vs-Dejavu session experiments are the path to stronger claims.

Design boundaries

Dejavu is deliberately:

• local-first, not remote-only;
• lexical and deterministic by default, not vector-first;
• repository-scoped, not one global memory soup;
• append-only and auditable, not silently self-rewriting;
• budgeted, not a transcript injector;
• honest about stale state, not eventually-consistent theater.

Dejavu is not a secrets manager, generic RAG platform, team ACL product, or replacement for source control.

The complete production/share roadmap, release gates, and next feature batch live in docs/ROADMAP.md. Completed work stays checked off; hypotheses remain explicitly unshipped until an eval earns them.