Repository navigation
Releases
v2.1.0 — institutional-memory P0 wave
Institutional-memory P0 wave — the five top-rated items from the scratch/deja roadmap audit, making recall relational and trustworthy. Two new commands, four new fields, zero new dependencies (Axiom 0 preserved). 161/161 tests.
Added
dejavue pattern "<text>"— record a discovered convention (naming, idiom, structure) intopatterns.md, the previously-missing core memory file alongsidedecisions.md/invariants.md. Surfaced bycontext, indexed byrecall.entities[]—--entity <name>(repeatable) ondecision/note/trap/incident/invariant/pattern, plusdejavue entities [<name>]to list/filter. Links events by subject (normalized kebab-case), FTS-indexed and matched byblame. The relational primitive — no graph DB.--confidence {speculative…verified}ondecision/note— a recall-trust signal so brainstorms and firm decisions no longer look identical. Labeled indecisions.md, FTS-indexed.--supersedesread-back —recall/since/contextnow surface "⚠ superseded by ''" on overridden decisions (was write-only). Event-identity self-exclusion; same-second-safe.decision --artifacts <path>(repeatable) — bind the files a decision is about, soblame <path>matches precisely instead of relying on fuzzy text. FTS-indexed.
Fixed
_load_events()ignores non-object timeline lines — a corrupt/manual12345/null/array line previously crashed every consumer (recall/since/blame/link/stats) on.get(); now filtered once at the loader.
Full changelog: https://github.com/nixpt/dejavue/blob/master/CHANGELOG.md
v2.0.2 — correctness pass
Correctness pass over the v2.0.1 feature set. No new surface area — these fix bugs in the commands v2.0.1 introduced. Axiom 0 preserved (zero new dependencies). 141/141 tests.
Supersedes v2.0.1, whose binary mislabelled itself
2.0.0and shipped the bugs below.
Fixed
note-commit --trailerno longer corrupts the link: it wrote the git note to the pre-amend SHA while--amendrewrote HEAD (orphaning the note), amended HEAD for any non-HEAD SHA, and silently folded staged changes. It now requires the SHA to be HEAD and the index to be clean, amends first, then attaches the note to the shipped commit.- Version reporting —
VERSION/pyprojectwere stuck at2.0.0;dejavue versionandpip shownow report the real version. linkno longer crashes on events whosecommit/summary/decision_reasonis an explicit JSONnull.since <base>..<tip>now honors the tip (the event window was bounded only by the base date, leaking post-tip events).invariantworks beforeinitinstead of crashing withFileNotFoundError.invariants.mdis now indexed byrecall(FTS sources + rebuild trigger).checknow verifies and repairs thepost-checkouthook thatinitinstalls.contextsurfaces traps & incidents in a dedicated section so they no longer scroll out of the recent-timeline tail; tolerant of non-object timeline lines.- Shell completions now cover
trap,incident,invariant,rejected, anddecision --supersedes/--durabilityacross bash/zsh/fish.
Full changelog: https://github.com/nixpt/dejavue/blob/master/CHANGELOG.md
v1.3.0 — Depth + git integration wave
35 commands, 100/100 tests.
Added diff, timeline, tag, note-commit, check --fix, event_type FTS indexing, since notes section.
v1.2.0 — Expression + discovery wave
31 commands, 88/88 tests.
Added stats, export --format {json,md}, reference, link, search, context -n N, --type on decision/note, tiered embedder auto-detect.
v1.1.0 — Operational wave
25 commands, 71/71 tests.
Added check, archive, roster, config, install-skill, embedder circuit breaker, log --reverse, recall --limit N.
v1.0.0 — Format stable
Format stable. 20 commands, 62/62 tests.
Ambient agent identity, staleness warnings, pre-push hook, codebase map, status, log, blame, note, init --ingest, init --map, concurrent safety (flock), per-repo config file, .gitignore entries.
v0.1.0 — first productized release
First productized release. Single-file Python 3 CLI, stdlib only, zero infrastructure. Drops into any git repo in 5 seconds.
Highlights
- 13 commands covering the full session lifecycle:
init,start,changed,decision,state,handoff,context,since,ingest,recall,worthiness,get,list,annotate. since <ref>— temporal delta over an agent's last session, a git commit, or an ISO date. Outputs git delta + timeline events + decisions + state transitions + handoffs + top keyword topics. The killer command.- FTS5 keyword recall via sqlite, with automatic LIKE fallback when FTS5 is unavailable.
- Git post-commit hook installed by
dejavue init. Auto-records onefile_changedevent per touched file on every commit. Uses absolute-path resolution so it works across git worktrees. .gitattributes merge=unionfortimeline.jsonlanddecisions.md. Critical for multi-branch / multi-worktree workflows — without this every wave merge conflicts on the append-only files. Verified end-to-end.- Rejected-alternatives field on decision events — the dead ends that future agents would otherwise cost the most to rediscover.
ingestscrape — one-shot ingest of git log + agent instruction files + CHANGELOG + ADRs + README. Marker-gated.- Worthiness gate — built-in capture/skip pedagogy. Auto-prints on first use.
- 33-test integration suite in pure bash, no external test deps.
Quickstart
curl -O https://raw.githubusercontent.com/nixpt/dejavue/main/dejavue.py
chmod +x dejavue.py
mv dejavue.py ~/.local/bin/dejavue
cd myproject/
dejavue init
dejavue start --agent claude --goal "implement X"
# ... make changes, commit normally — hook captures the file changes ...
dejavue decision "Use approach A over B" --reason "..." --rejected "B: didn't generalize"
dejavue handoff --summary "..." --next "..."
# next session:
dejavue context # boot packet
dejavue since 2026-05-10 # everything that changed since
dejavue recall "rate limiter"What this is
.dejavue/ is to project memory what .git/ is to history. The file format is the open contract — multiple tools can sit on top of it.
What this is not
Not a replacement for git. Not a vector database or embedding store. Not an MCP server. Not cross-repo memory federation. See docs/04-foreman-perspective.md for the full overlap analysis.
Roadmap
- v0.2 —
--semanticflag for embedder-backed recall (FTS5 stays as fallback). - v0.3 — MCP integration tools for richer agent ecosystems.
- v0.4 — upgrade path to fuller per-repo memory systems.
See CHANGELOG.md for the full release detail.