deja
Memory that lets your coding assistant pick up where it left off.
AI coding assistants forget everything between sessions. You re-explain the same project details over and over. Deja keeps the decisions and preferences that matter for this project in one small file on your computer. Nothing leaves your machine unless you choose to share a specific note.
Memory across time, hands across machines.
Deja remembers what earlier sessions learned. Terrarium runs agent tasks on Cloudflare and hands back a receipt. Your agent sits between them: it starts with memory, sends work out, and leaves a handoff for whoever comes next.
- kept notes, drafts, handoffs
- one bank, every note labelled with its origin
- one SQLite file on your machine
- Pi, OpenCode, or any MCP client
- you ask, the agent plans and acts
- checks memory against live state
- runs agent tasks on Cloudflare
- run ID, task fingerprint, proof
- children can recall Deja too
- start First prompt arrives. Deja recalls matching notes from every repo and hands the agent the few that fit, each labelled with where it came from.
- work The agent hands bounded jobs to Terrarium. Each job runs on Cloudflare and comes back with a run ID and a verified receipt.
- learn As the context fills, auto-memory drafts what is worth keeping. Drafts expire in a day unless another session finds them again.
- end A handoff records where the work stopped. The next session, here or in a cloud sandbox, starts from it instead of from zero.
A database is not enough.
Memory has to show up in the right project, stay short enough to fit inside a prompt, remember when you corrected something, stop repeating work you finished, and show evidence when it gets something wrong. Deja builds those constraints into the tool.
One bank, labelled
Every note records the Git repository it came from. Recall reads the whole bank, ranks the current project first, and labels each hit with its origin. Set DEJA_RECALL_REACH=scope to stay inside one project.
Keeps it short
Recall accepts a limit on how much to return and what kind of memory you want. It sends the smallest useful packet, not the whole history.
Old versions stay visible
When a note gets corrected, the old version stays in the file so you can see what changed. Recall follows the current version while keeping the evidence inspectable.
Write less. Recover more.
const decision = d.remember(
"Decision: use Bun for repo scripts",
{ kind: "decision" }
);
d.keep([decision.id]);
d.handoff({
summary: "Converted scripts; tests pass.",
next: ["update the release workflow"],
});const context = d.recall("release workflow", {
maxTokens: 600,
kinds: ["decision", "pitfall", "wip"],
});
// one active catch-up note
// provenance + trust score
// a receipt to evaluate later
d.assessRecall(context.traceId, "useful");A complete local memory loop.
Seven useful kinds
Decision, preference, procedure, pitfall, fact, work-in-progress, and note. Your assistant can classify explicitly; the fallback is conservative.
Relevance is not truth
BM25 finds matching text. Draft-versus-kept state and used-versus-wrong outcomes determine trust. High means repeatedly useful, not magically authoritative.
Old work stops directing
Catch-up notes are active, completed, or abandoned. Only the active note from the current project reaches a fresh assistant.
Recall can be evaluated
Every retrieval has a content-free receipt. Mark it useful, wrong, missed, or unnecessary, then inspect real quality with deja eval.
Changes are explicit
Link a new note to an old one as a replacement, contradiction, or related. Old matches resolve to the current note without deleting history.
One file, ordinary tools
Open ~/.deja/deja.db with SQLite. Use the library, MCP tools, or CLI. No daemon, account, hidden model call, or remote ingestion path.
Give your assistant memory in sixty seconds.
bun add github:acoyfellow/deja
bunx github:acoyfellow/deja init{
"mcpServers": {
"deja": {
"command": "bunx",
"args": ["github:acoyfellow/deja", "mcp"]
}
}
} Tool descriptions are the operating contract. No SKILL.md, AGENTS.md, or memory prompt pasted into every session.
Small primitives, closed loop.
recall Scoped, budgeted context plus the active catch-up note.
remember Draft or keep typed memory; link corrections immediately.
handoff Leave one short note for the next session.
resolve_handoff Complete or abandon work so it stops resurfacing.
signal Mark one memory used, wrong, or forgotten.
assess Evaluate the whole retrieval after acting.
link Replace, contradict, or relate existing notes.
send / inbox / reply Optional local coordination; deliberately separate from memory.
The failures stay in the repository.
Deja includes behavior tests, negative results, protocol experiments, claim-to-evidence mapping, and a one-command release gate. The eight-case lexical score is a smoke test, not proof that memory improves every assistant.
bun run check
# tests
# strict TypeScript
# lexical recall smoke bench
# behavioral evidence benchLet the next session start further ahead.
Stays on your computer. Inspectable. Falsifiable. Built for the assistant using it.
Install Deja