Merge pull request #7 from focaxisdev/codex/remember-writeback-lifecycle

focaxisdev · web-flow · commit 0e3f4e54f43b · 2026-04-25T21:48:35.000+08:00
Add remember writeback lifecycle tooling
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.0] - 2026-04-25
+
+- Made remember/writeback a first-class companion to recall with a post-task writeback routing table in the README, protocol, workflow, and AGENTS template.
+- Added `writeback_hint` guidance to scripted memory scans so recall naturally leads into durable memory maintenance.
+- Added `deja-vu-feedback-report` to aggregate recall feedback into maintenance suggestions for aliases, weights, compaction, and route cleanup.
+- Expanded memory linting beyond JSONL into Markdown lifecycle checks for summaries, decisions, open loops, frontmatter, supersession, and transcript-like records.
+- Added tests for writeback hints, feedback reporting, Markdown memory linting, and package binary inclusion.
+
 ## [0.4.1] - 2026-04-25
 
 - Reaffirmed Deja Vu as an ultra-light protocol-first memory system rather than a required package, service, daemon, vector database, or engine.
diff --git a/README.md b/README.md
@@ -27,6 +27,18 @@ Follow the Deja Vu rules in AGENTS.md. Before substantial work, scan memory/impr
 
 That is the base product. Add scripts, feedback, decisions, open loops, or the optional TypeScript engine only when the project grows enough to justify them.
 
+Post-task writeback should stay just as small:
+
+```text
+Decision made -> memory/decisions/ + memory/impressions.jsonl
+Unresolved follow-up -> memory/open-loops/ + memory/impressions.jsonl
+Project-level truth changed -> memory/summary.md + memory/impressions.jsonl
+One-off low-value trace -> memory/events/ or skip
+Recall was missed, irrelevant, helpful, or overloaded -> memory/recall-feedback.jsonl
+```
+
+If the outcome is not durable enough to help a future agent, do not write it into memory.
+
 Use Deja Vu if your team keeps repeating:
 
 - "We already decided this."
@@ -71,11 +83,14 @@ 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, with one optional feedback ledger when recall results should change future behavior:
+The minimum viable setup uses three project-local plain text files:
 
+- `AGENTS.md`
 - `memory/summary.md`
 - `memory/impressions.jsonl`
 
+Add one optional feedback ledger when recall results should change future behavior:
+
 - `memory/recall-feedback.jsonl`
 
 No npm package, embeddings, vector search, or database is required.
@@ -109,7 +124,6 @@ Deja Vu follows a cue-first lifecycle:
 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. 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.
@@ -142,6 +156,12 @@ The canonical layout and field rules are specified in [docs/storage-markdown.md]
   - stable preferences
   - unresolved follow-up items
   - milestone summaries
+- Route writeback by artifact:
+  - decisions -> `memory/decisions/` plus `memory/impressions.jsonl`
+  - follow-ups -> `memory/open-loops/` plus `memory/impressions.jsonl`
+  - project-level truth -> `memory/summary.md` plus `memory/impressions.jsonl`
+  - cheap trace -> `memory/events/` or skip
+  - recall quality -> `memory/recall-feedback.jsonl`
 - Default recall budget:
   - impression scan: always allowed
   - summary: at most one file
@@ -250,6 +270,7 @@ npm install
 npm run build
 npm run test:src
 npm run lint:memory
+npm run report:feedback
 ```
 
 ## References
@@ -264,4 +285,5 @@ npm run lint:memory
 - [docs/release-v0.3.1.md](./docs/release-v0.3.1.md)
 - [docs/release-v0.4.0.md](./docs/release-v0.4.0.md)
 - [docs/release-v0.4.1.md](./docs/release-v0.4.1.md)
+- [docs/release-v0.5.0.md](./docs/release-v0.5.0.md)
 - [llms.txt](./llms.txt)
diff --git a/docs/protocol.md b/docs/protocol.md
@@ -104,12 +104,28 @@ During the task:
 
 After meaningful work completes:
 
-1. Decide whether the outcome is durable.
-2. If it is durable, write or update the appropriate memory artifact.
-3. Update `memory/impressions.jsonl` with compact keywords for future cheap scans.
-4. Update `memory/summary.md` when the project-level understanding has changed.
-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.
+1. Decide whether the outcome is durable enough to help a future agent.
+2. Route the outcome through the writeback gate.
+3. If it is durable, write or update the appropriate memory artifact.
+4. Update `memory/impressions.jsonl` with compact keywords for future cheap scans.
+5. Update `memory/summary.md` when the project-level understanding has changed.
+6. Update `memory/index.md` when the project uses one.
+7. Update `memory/events/` only when the work should remain discoverable without becoming a durable record.
+
+Writeback gate:
+
+| Outcome | Action |
+| --- | --- |
+| no durable future value | `skip` |
+| happened once but may be useful to discover later | `event_only` |
+| changes an existing durable record | `update_existing` |
+| records an accepted decision | `new_decision` |
+| leaves unresolved follow-up work | `new_open_loop` |
+| changes project-level truth | `update_summary` |
+| replaces an older durable record | `supersede_old_record` |
+| recall quality should tune future behavior | `append_feedback` |
+
+Every durable writeback must leave a future recall route. In practice, update `memory/impressions.jsonl` whenever a decision, open loop, context record, or project summary becomes the authoritative place to remember something.
 
 ### 4. Recall Feedback
 
@@ -162,6 +178,15 @@ Write back when the work produces:
 - a stable working preference
 - a milestone-level summary worth reusing later
 
+Route writeback by artifact:
+
+- decision -> `memory/decisions/` plus `memory/impressions.jsonl`
+- unresolved follow-up -> `memory/open-loops/` plus `memory/impressions.jsonl`
+- project-level truth -> `memory/summary.md` plus `memory/impressions.jsonl`
+- low-cost trace -> `memory/events/` or skip
+- recall quality signal -> `memory/recall-feedback.jsonl`
+- replacement -> newer record plus supersession links
+
 Do not write back:
 
 - temporary notes that will obviously expire
diff --git a/docs/release-v0.5.0.md b/docs/release-v0.5.0.md
@@ -0,0 +1,33 @@
+# Deja Vu v0.5.0
+
+Deja Vu now treats remember and recall as equal parts of the protocol loop.
+
+Earlier releases made cue-first recall cheap and observable. This release closes the loop after work completes: agents now get clearer routing for what to remember, where to write it, when to skip it, and how recall feedback should become future memory maintenance.
+
+## Highlights
+
+- Added post-task writeback routing to the README, protocol, workflow, and AGENTS template.
+- Added `writeback_hint` to `deja-vu-scan-memory` output.
+- Added `deja-vu-feedback-report` for aggregating recall feedback into maintenance suggestions.
+- Expanded `deja-vu-lint-memory` to inspect Markdown memory lifecycle records, not only JSONL cues.
+- Added tests for writeback hints, feedback reporting, Markdown linting, and package binary inclusion.
+
+## Why it matters
+
+Recall without disciplined writeback eventually goes stale. Writeback without disciplined recall turns into noise.
+
+Deja Vu v0.5.0 keeps the base product small while making the full loop explicit:
+
+```text
+task cue -> familiarity score -> minimal recall -> durable writeback -> feedback-guided maintenance
+```
+
+## Upgrade notes
+
+No existing memory layout migration is required.
+
+Recommended additions:
+
+- Use the README writeback routing table after meaningful work.
+- Run `deja-vu-lint-memory` to catch Markdown lifecycle issues.
+- Run `deja-vu-feedback-report` when `memory/recall-feedback.jsonl` starts to accumulate actionable recall outcomes.
diff --git a/docs/templates/AGENTS.template.md b/docs/templates/AGENTS.template.md
@@ -32,13 +32,21 @@ Recall budget:
 After meaningful work completes:
 
 1. Write back only durable, reusable memory.
-2. Update the relevant memory file.
-3. Update `memory/impressions.jsonl`.
-4. Update `memory/summary.md` when project understanding changes.
-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.
+2. Route the outcome through the writeback gate.
+3. Update the relevant memory file.
+4. Update `memory/impressions.jsonl`.
+5. Update `memory/summary.md` when project understanding changes.
+6. Update `memory/index.md` if the project uses one.
+7. Add a short entry to `memory/events/` only when the work should remain discoverable without becoming durable memory.
+8. Append `memory/recall-feedback.jsonl` only when recall was helpful, irrelevant, missed, or overloaded in a way that should tune future memory.
+
+Writeback gate:
+
+- accepted decision -> `memory/decisions/` plus `memory/impressions.jsonl`
+- unresolved follow-up -> `memory/open-loops/` plus `memory/impressions.jsonl`
+- project-level truth changed -> `memory/summary.md` plus `memory/impressions.jsonl`
+- low-value one-off trace -> `memory/events/` or skip
+- recall quality signal -> `memory/recall-feedback.jsonl`
 
 Good writeback candidates:
 
diff --git a/docs/templates/memory/decisions/decision-template.md b/docs/templates/memory/decisions/decision-template.md
@@ -8,6 +8,8 @@ updated: 2026-04-20
 
 # Decision Title
 
+Use this record only for an accepted decision that should guide future work. Do not paste exploratory chat logs here.
+
 ## Date
 
 2026-04-20
diff --git a/docs/templates/memory/open-loops/open-loop-template.md b/docs/templates/memory/open-loops/open-loop-template.md
@@ -8,6 +8,8 @@ updated: 2026-04-20
 
 # Open Loop Title
 
+Use this record only for unresolved follow-up work that should survive a new chat. Close or supersede it when the loop is no longer active.
+
 ## Owner
 
 agent-or-person
diff --git a/docs/templates/memory/summary.md b/docs/templates/memory/summary.md
@@ -8,6 +8,8 @@ updated: 2026-04-20
 
 # Project Summary
 
+Keep this as the compact project-level truth. Do not store turn-by-turn history or detailed decisions here.
+
 ## Current objective
 
 Describe the current product objective in two or three sentences.
diff --git a/docs/workflow.md b/docs/workflow.md
@@ -45,12 +45,24 @@ Default detailed reads:
 After meaningful work completes:
 
 1. decide whether the outcome is durable
-2. create or update the relevant durable memory file
-3. update `memory/impressions.jsonl`
-4. update `memory/summary.md` if project understanding changed
-5. update `memory/index.md` if the project uses one
-6. add a short event ledger entry only when the work should remain discoverable without promotion into durable memory
-7. append `memory/recall-feedback.jsonl` only when recall was helpful, irrelevant, missed, or overloaded in a way that should tune future recall
+2. route the outcome through the writeback gate
+3. create or update the relevant durable memory file
+4. update `memory/impressions.jsonl`
+5. update `memory/summary.md` if project understanding changed
+6. update `memory/index.md` if the project uses one
+7. add a short event ledger entry only when the work should remain discoverable without promotion into durable memory
+8. append `memory/recall-feedback.jsonl` only when recall was helpful, irrelevant, missed, or overloaded in a way that should tune future recall
+
+Writeback gate:
+
+| Signal | Route |
+| --- | --- |
+| accepted decision | `memory/decisions/` plus `memory/impressions.jsonl` |
+| unresolved follow-up | `memory/open-loops/` plus `memory/impressions.jsonl` |
+| project-level truth changed | `memory/summary.md` plus `memory/impressions.jsonl` |
+| low-value one-off trace | `memory/events/` or skip |
+| recall quality changed future behavior | `memory/recall-feedback.jsonl` |
+| older record replaced | supersede old record and point indexes at the new one |
 
 ## Decision Rules
 
diff --git a/encoding-status.md b/encoding-status.md
@@ -75,3 +75,14 @@
 | `docs/release-v0.4.1.md` | 編碼正常（新建，UTF-8） | New release note for protocol-first activation and the ultra-light three-file adoption path. |
 | `docs/templates/memory/recall-feedback.jsonl` | 編碼正常（新建，UTF-8） | New recall feedback template. |
 | `examples/protocol-project/memory/recall-feedback.jsonl` | 編碼正常（新建，UTF-8） | New example recall feedback ledger. |
+| `scripts/dejavu-feedback-report.mjs` | 編碼正常（新建，UTF-8） | New feedback aggregation CLI for recall maintenance suggestions. |
+| `docs/release-v0.5.0.md` | 編碼正常（新建，UTF-8） | New release note for remember/writeback lifecycle improvements. |
+| `scripts/dejavu-scan-memory.mjs` | 編碼正常（已檢查） | Updated in UTF-8; scan output now includes post-task writeback hints. |
+| `scripts/dejavu-lint-memory.mjs` | 編碼正常（已檢查） | Updated in UTF-8; linter now checks Markdown memory lifecycle records. |
+| `tests/memory-cli.test.ts` | 編碼正常（已檢查） | Updated in UTF-8; CLI tests now cover writeback hints, feedback reports, and Markdown lifecycle linting. |
+| `docs/protocol.md` | 編碼正常（已檢查） | Updated in UTF-8; protocol now defines the writeback gate and artifact routing. |
+| `docs/workflow.md` | 編碼正常（已檢查） | Updated in UTF-8; workflow now includes post-task writeback routing. |
+| `docs/templates/AGENTS.template.md` | 編碼正常（已檢查） | Updated in UTF-8; project rules template now includes the writeback gate. |
+| `docs/templates/memory/summary.md` | 編碼正常（已檢查） | Updated in UTF-8; summary template now warns against turn-by-turn history. |
+| `docs/templates/memory/decisions/decision-template.md` | 編碼正常（已檢查） | Updated in UTF-8; decision template now clarifies durable decision scope. |
+| `docs/templates/memory/open-loops/open-loop-template.md` | 編碼正常（已檢查） | Updated in UTF-8; open-loop template now clarifies unresolved follow-up scope. |
diff --git a/llms.txt b/llms.txt
@@ -9,6 +9,7 @@ Deja Vu helps agents stop re-explaining the same repository context across new c
 - tiny Markdown and JSONL memory files inside the repository
 - cue quality checks that keep the first recall step sparse and specific
 - recall budget and outcome feedback that show whether memory helped, missed, or overloaded the task
+- writeback routing and feedback reports that keep remembered project context durable and maintainable
 
 The minimum adoption path is three files: `AGENTS.md`, `memory/summary.md`, and `memory/impressions.jsonl`. It does not require npm, embeddings, vector search, a daemon, or a dedicated memory service.
 
@@ -20,6 +21,7 @@ The minimum adoption path is three files: `AGENTS.md`, `memory/summary.md`, and
 - [Markdown Storage](./docs/storage-markdown.md): minimum and optional memory layout
 - [Impression Layer](./docs/impression-layer.md): compact keyword-first familiarity surface
 - [Scripted Recall](./docs/scripted-recall.md): host script contract for cheap pre-task scans
+- [v0.5.0 Release](./docs/release-v0.5.0.md): remember/writeback lifecycle improvements
 - [Templates](./docs/templates): copyable rules and memory templates
 - [Protocol Example](./examples/protocol-project): repo-first example with no engine
 
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@focaxisdev/deja-vu",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Ultra-light repo-local memory protocol for AI coding agents: stop re-explaining your repo to every new chat.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -14,7 +14,8 @@
   },
   "bin": {
     "deja-vu-scan-memory": "scripts/dejavu-scan-memory.mjs",
-    "deja-vu-lint-memory": "scripts/dejavu-lint-memory.mjs"
+    "deja-vu-lint-memory": "scripts/dejavu-lint-memory.mjs",
+    "deja-vu-feedback-report": "scripts/dejavu-feedback-report.mjs"
   },
   "files": [
     "dist/src",
@@ -32,6 +33,7 @@
     "test:src": "node --import \"data:text/javascript,import { register } from 'node:module'; import { pathToFileURL } from 'node:url'; register('ts-node/esm', pathToFileURL('./'));\" --test tests/**/*.test.ts",
     "scan:memory": "node scripts/dejavu-scan-memory.mjs",
     "lint:memory": "node scripts/dejavu-lint-memory.mjs --memory-root examples/protocol-project/memory",
+    "report:feedback": "node scripts/dejavu-feedback-report.mjs --memory-root examples/protocol-project/memory",
     "example:basic": "node --loader ts-node/esm examples/basic/index.ts",
     "example:agent-pm": "node --loader ts-node/esm examples/agent-pm/index.ts",
     "example:chat-memory": "node --loader ts-node/esm examples/chat-memory/index.ts",
diff --git a/scripts/dejavu-feedback-report.mjs b/scripts/dejavu-feedback-report.mjs
diff --git a/scripts/dejavu-lint-memory.mjs b/scripts/dejavu-lint-memory.mjs
diff --git a/scripts/dejavu-scan-memory.mjs b/scripts/dejavu-scan-memory.mjs
diff --git a/tests/memory-cli.test.ts b/tests/memory-cli.test.ts
