Release v0.4.0 feedback-aware recall

Author: Focaxis Dev

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.0] - 2026-04-24
+
+- Reframed the README and package metadata around repo-local Markdown memory for AI coding agents.
+- Added observable recall budget reporting to scripted scans and the TypeScript engine.
+- Added recall feedback as a lightweight reward signal with `helpful`, `irrelevant`, `missed`, and `overloaded` outcomes.
+- Added `memory/recall-feedback.jsonl` templates and example feedback records.
+- Expanded memory linting for feedback records, status values, weights, date formats, scope naming, and unsafe record paths.
+- Updated protocol, workflow, scripted recall, storage, templates, and examples for Deja Vu Protocol v0.4.
+- Updated package metadata for the 0.4.0 release.
+
 ## [0.3.1] - 2026-04-23
 
 - Added impression cue quality warnings to `deja-vu-lint-memory` for sparse, oversized, duplicate, generic, and repeated keyword sets.

README.md

@@ -1,16 +1,31 @@
 # Deja Vu
 
-**Stop AI agents from forgetting project context without adding a database, vector store, or memory service.**
+**Persistent project memory for AI coding agents, stored in your repo as Markdown and JSONL.**
 
-Deja Vu is an AI agent memory protocol for teams that want durable project context in ordinary repo files.
+Deja Vu helps Codex, Claude Code, Cursor, Windsurf, and other coding agents remember project decisions, architecture context, open loops, and team preferences across new chats.
 
-Most agent memory tools start by storing more text. Deja Vu starts by asking a cheaper question: does this task feel familiar enough to justify loading memory at all?
+It does not require a database, vector store, embedding model, hosted memory service, or npm package.
 
 ```text
-before: agent reads too much, forgets why decisions were made, or carries noisy transcript history
-after:  agent scans tiny cues, loads only relevant memory, and writes back durable project knowledge
+problem: every new agent session forgets why the project works the way it does
+result:  the agent scans tiny repo-local cues, recalls only relevant memory, and writes back durable context
 ```
 
+Start with three files:
+
+- `AGENTS.md`
+- `memory/summary.md`
+- `memory/impressions.jsonl`
+
+Use Deja Vu if your team keeps repeating:
+
+- "We already decided this."
+- "The agent forgot the architecture again."
+- "Do not load the whole repo history into context."
+- "We want memory in git, not in a vendor service."
+
+Most agent memory tools start by storing more text. Deja Vu starts by asking a cheaper question: does this task feel familiar enough to justify loading memory at all?
+
 The core loop is intentionally small:
 
 ```text
@@ -25,10 +40,13 @@ It is packaged as three project-local assets:
 
 No server. No hidden state. No required npm package. The base protocol works with Markdown and JSONL files that live beside the code.
 
+If you found this on npm: the package is only the optional TypeScript engine and CLI tooling. The main product is the repo-local memory protocol you can copy into any project.
+
 Use Deja Vu when you want:
 
 - project memory that survives a new chat or agent session
 - low-token recall before planning, coding, or answering
+- observable recall budget and recall outcome feedback
 - durable decisions, preferences, open loops, and architecture intent in plain files
 - an optional TypeScript semantic engine only when the project outgrows the file-first protocol
 
@@ -43,11 +61,13 @@ It answers:
 - 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:
+The minimum viable setup uses two project-local plain text files, with one optional feedback ledger when recall results should change future behavior:
 
 - `memory/summary.md`
 - `memory/impressions.jsonl`
 
+- `memory/recall-feedback.jsonl`
+
 No npm package, embeddings, vector search, or database is required.
 
 ## Start Here
@@ -78,7 +98,9 @@ Deja Vu follows a cue-first lifecycle:
 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.
+6. Record whether recall was helpful, irrelevant, missed, or overloaded when that feedback should tune future memory.
+
+7. Compact or supersede memories when detail becomes repetitive or stale.
 
 This keeps memory project-local, readable, and easy to maintain across new conversations.
 
@@ -88,6 +110,7 @@ This keeps memory project-local, readable, and easy to maintain across new conve
 memory/
   summary.md
   impressions.jsonl
+  recall-feedback.jsonl
   decisions/
   open-loops/
   events/
@@ -229,4 +252,5 @@ npm run lint:memory
 - [docs/bootstrap-instructions.md](./docs/bootstrap-instructions.md)
 - [docs/project-rules-template.md](./docs/project-rules-template.md)
 - [docs/release-v0.3.1.md](./docs/release-v0.3.1.md)
+- [docs/release-v0.4.0.md](./docs/release-v0.4.0.md)
 - [llms.txt](./llms.txt)

docs/bootstrap-instructions.md

@@ -7,7 +7,7 @@ This document tells an agent how to bootstrap Deja Vu into a project using the p
 Give a project durable memory continuity using only:
 
 - project rules
-- two minimum Markdown memory files
+- minimum Markdown and JSONL memory files
 - the cue-first Deja Vu workflow
 
 ## Trigger conditions
@@ -55,11 +55,13 @@ Create or update:
 - `memory/summary.md`
 - `memory/impressions.jsonl`
 - `scripts/dejavu-scan-memory.mjs`
+- `memory/recall-feedback.jsonl` when feedback should tune future recall
 
 Add only when useful:
 
 - `memory/decisions/`
 - `memory/open-loops/`
+- `memory/recall-feedback.jsonl`
 - `memory/events/`
 - `memory/context/project-context.md`
 - `memory/index.md`

docs/protocol.md

@@ -1,4 +1,4 @@
-# Deja Vu Protocol v0.3
+# Deja Vu Protocol v0.4
 
 Deja Vu is a cue-first memory protocol for AI agents.
 
@@ -11,6 +11,7 @@ Enable any agent to maintain useful project memory with extremely low per-conver
 - project rules
 - a repeatable workflow
 - project-local plain text memory cues
+- recall feedback that tells the project what was useful, noisy, missed, or overloaded
 
 The protocol must work without a custom runtime, package install, embedding model, or vector database.
 
@@ -62,6 +63,7 @@ Recommended artifacts:
 
 - `memory/decisions/`
 - `memory/open-loops/`
+- `memory/recall-feedback.jsonl`
 
 Optional artifacts:
 
@@ -81,6 +83,7 @@ Before substantial planning, coding, or answering:
 4. If the scan is `weak`, read `memory/summary.md`.
 5. If the scan is `strong`, open only the detailed records needed for the current task.
 6. If no script is available, fall back to `memory/summary.md` and only then to `memory/index.md` when present.
+7. Track the recall budget used for the task: impression scan, summary count, detailed records, and why anything was loaded.
 
 Default recall budget:
 
@@ -108,7 +111,22 @@ After meaningful work completes:
 5. Update `memory/index.md` when the project uses one.
 6. Update `memory/events/` only when the work should remain discoverable without becoming a durable record.
 
-### 4. Compaction
+### 4. Recall Feedback
+
+When recall quality changes future behavior, append a compact feedback record to `memory/recall-feedback.jsonl`.
+
+Allowed outcomes:
+
+- `helpful`: the loaded memory improved the work
+- `irrelevant`: the loaded memory matched the cue but did not help
+- `missed`: useful memory existed but the scan did not surface it
+- `overloaded`: recall loaded too much detail for the task
+
+Feedback is the reward signal for future memory maintenance. Use it to tune keywords, weights, thresholds, summaries, open loops, or supersession.
+
+Do not log every task. Record feedback only when it should change future recall.
+
+### 5. Compaction
 
 When related memories become repetitive, stale, or too granular:
 

docs/release-v0.4.0.md

@@ -0,0 +1,38 @@
+# Deja Vu v0.4.0: Feedback-Aware Memory for AI Coding Agents
+
+Deja Vu stores persistent project memory for AI coding agents in repo-local Markdown and JSONL, without a database, vector store, embedding model, or hosted memory service.
+
+v0.4.0 turns recall into an observable feedback loop. Agents can now see why memory was loaded, how much recall budget was spent, and whether the result was helpful, irrelevant, missed, or overloaded.
+
+## Why It Matters
+
+AI coding agents lose useful project context between chats. Most memory systems answer by storing and retrieving more text. Deja Vu keeps the first step cheap: scan tiny cues, load only what the task justifies, and write back durable context that belongs in git.
+
+This release adds the missing reward signal. A project can now learn which memory routes are worth keeping, which ones are noisy, and which cues missed important context.
+
+## Highlights
+
+- Recall budget output for scripted scans and the optional TypeScript engine.
+- Recall feedback outcomes: `helpful`, `irrelevant`, `missed`, and `overloaded`.
+- New `memory/recall-feedback.jsonl` template and example records.
+- Stronger memory linting for feedback, weights, statuses, dates, scopes, and record paths.
+- README and package metadata tuned for AI coding agent memory discovery.
+- Protocol, workflow, scripted recall, storage, templates, and examples updated to Deja Vu Protocol v0.4.
+
+## Upgrade Notes
+
+The minimum protocol still works with:
+
+- `AGENTS.md`
+- `memory/summary.md`
+- `memory/impressions.jsonl`
+
+Add `memory/recall-feedback.jsonl` when recall quality should tune future memory behavior. Do not log every scan; record feedback only when it changes what the project should remember, ignore, lower in weight, or revise.
+
+## Suggested GitHub Release Title
+
+Deja Vu v0.4.0: Feedback-Aware Memory for AI Coding Agents
+
+## Suggested Tagline
+
+Repo-local Markdown memory for AI coding agents, now with observable recall budgets and feedback outcomes.

docs/scripted-recall.md

@@ -26,6 +26,8 @@ The linter also warns about low-quality cue routes that make future recall more
 - duplicate keywords inside one record
 - too many generic keywords
 - duplicate keyword sets across records
+- invalid recall feedback outcomes
+- invalid weight, status, scope, date, or unsafe record paths
 
 ## Inputs
 
@@ -60,6 +62,16 @@ The script prints JSON:
       "matched_keywords": ["protocol", "memory"]
     }
   ],
+  "budget": {
+    "impression_scan": 1,
+    "summaries_loaded": 0,
+    "detail_records_loaded": 0,
+    "why_loaded": ["cue scan found a weak familiarity match"]
+  },
+  "feedback_hint": {
+    "outcomes": ["helpful", "irrelevant", "missed", "overloaded"],
+    "write_to": "memory/recall-feedback.jsonl"
+  },
   "diagnostics": []
 }
 ```
@@ -70,14 +82,17 @@ The script prints JSON:
 2. Treat `none` as permission to avoid detailed memory reads.
 3. Treat `weak` as a reason to read `memory/summary.md` and maybe one linked record.
 4. Treat `strong` as a reason to open the linked record before planning.
-5. Continue to apply normal writeback and compaction rules after work completes.
+5. Watch `budget` before loading more memory.
+6. Record recall feedback only when the result should tune future cue quality.
+7. Continue to apply normal writeback and compaction rules after work completes.
 
 ## Bootstrap Rule
 
 When installing Deja Vu into a project, copy or create:
 
 - `memory/impressions.jsonl`
 - `memory/summary.md`
+- `memory/recall-feedback.jsonl`
 - `scripts/dejavu-scan-memory.mjs`
 
 The script is intentionally small. Hosts may replace it with a faster native implementation, but the input and output contract should stay stable.
@@ -89,3 +104,22 @@ Run the linter after bootstrap and after memory file migrations:
 ```bash
 node scripts/dejavu-lint-memory.mjs
 ```
+
+## Recall Feedback
+
+Use `memory/recall-feedback.jsonl` as a small reward signal for the memory system.
+
+Each line is one JSON object:
+
+```json
+{"schema_version":1,"query":"release feedback memory","matched_id":"decision-protocol-first","outcome":"helpful","created":"2026-04-24T12:00:00Z","note":"The decision record prevented a duplicate engine-first proposal."}
+```
+
+Allowed outcomes:
+
+- `helpful`
+- `irrelevant`
+- `missed`
+- `overloaded`
+
+Do not log every scan. Add feedback only when it should change future keywords, weights, summaries, thresholds, or supersession.

docs/storage-markdown.md

@@ -18,6 +18,7 @@ These paths are the stable minimum. Agents may add more files when they improve
 memory/
   summary.md
   impressions.jsonl
+  recall-feedback.jsonl
   decisions/
   open-loops/
 ```
@@ -85,6 +86,33 @@ Each line must be one JSON object with:
 - `record_path`
 - `updated`
 
+### `memory/recall-feedback.jsonl`
+
+Purpose:
+
+- record recall outcomes that should tune future memory behavior
+- capture reward signals without logging full transcripts
+- identify helpful, irrelevant, missed, or overloaded recall routes
+
+Each line must be one JSON object with:
+
+- `schema_version`
+- `query`
+- `outcome`
+- `created`
+
+Optional fields:
+
+- `matched_id`
+- `note`
+
+Allowed outcomes:
+
+- `helpful`
+- `irrelevant`
+- `missed`
+- `overloaded`
+
 ### `memory/events/`
 
 Purpose:

docs/templates/AGENTS.template.md

@@ -2,7 +2,7 @@
 
 ## Protocol identity
 
-- Protocol: Deja Vu Protocol v0.3
+- Protocol: Deja Vu Protocol v0.4
 - Scope: `project:<project-id>`
 - Memory root: `memory/`
 
@@ -18,6 +18,8 @@ Before substantial planning, coding, or answering:
 4. If the result is `strong`, open the linked detailed record.
 5. If the script is missing, fall back to `memory/summary.md` and then `memory/index.md` when present.
 
+6. Keep the scan output's budget fields visible before loading more memory.
+
 Recall budget:
 
 - impression scan: always allowed
@@ -36,6 +38,8 @@ After meaningful work completes:
 5. Update `memory/index.md` if the project uses one.
 6. Add a short entry to `memory/events/` only when the work should remain discoverable without becoming durable memory.
 
+7. Append `memory/recall-feedback.jsonl` only when recall was helpful, irrelevant, missed, or overloaded in a way that should tune future memory.
+
 Good writeback candidates:
 
 - decisions

docs/templates/memory/recall-feedback.jsonl

@@ -0,0 +1 @@
+{"schema_version":1,"query":"example task cue","matched_id":"summary","outcome":"helpful","created":"2026-04-24T12:00:00Z","note":"This recall changed future memory behavior."}