Merge pull request #5 from focaxisdev/codex/protocol-first-activation

Release v0.4.1 protocol-first activation

Author: focaxisdev

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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.
+- Updated the README opening around the concrete adoption promise: stop re-explaining the repo to every new coding-agent chat.
+- Added a 2-minute start path centered on `AGENTS.md`, `memory/summary.md`, and `memory/impressions.jsonl`.
+- Clarified that scripts, recall feedback, detailed records, and the TypeScript engine are optional scale-up layers.
+- Added release notes for the 0.4.1 protocol-first activation patch.
+
 ## [0.4.0] - 2026-04-24
 
 - Reframed the README and package metadata around repo-local Markdown memory for AI coding agents.

README.md

@@ -1,22 +1,32 @@
 # Deja Vu
 
-**Persistent project memory for AI coding agents, stored in your repo as Markdown and JSONL.**
+**Stop re-explaining your repo to every new coding-agent chat.**
 
-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.
+Deja Vu is an ultra-light, protocol-first memory system for Codex, Claude Code, Cursor, Windsurf, and other coding agents. Add three repo-local files so a new agent session can scan tiny cues, recall only relevant project memory, and write back durable context.
 
-It does not require a database, vector store, embedding model, hosted memory service, or npm package.
+It does not require a database, vector store, embedding model, hosted memory service, daemon, or npm package.
 
 ```text
 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:
+## 2-Minute Start
+
+Start by copying or creating only three files:
 
 - `AGENTS.md`
 - `memory/summary.md`
 - `memory/impressions.jsonl`
 
+Then tell the next coding-agent chat:
+
+```text
+Follow the Deja Vu rules in AGENTS.md. Before substantial work, scan memory/impressions.jsonl, load memory/summary.md only for weak matches, and load at most one to three detailed records for strong matches.
+```
+
+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.
+
 Use Deja Vu if your team keeps repeating:
 
 - "We already decided this."
@@ -38,7 +48,7 @@ It is packaged as three project-local assets:
 - workflow
 - tiny memory files
 
-No server. No hidden state. No required npm package. The base protocol works with Markdown and JSONL files that live beside the code.
+No server. No hidden state. No required npm package. No memory platform. 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.
 
@@ -48,7 +58,7 @@ Use Deja Vu when you want:
 - 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
+- optional CLI or TypeScript helpers only when the project outgrows the file-first protocol
 
 ## What Deja Vu Is
 
@@ -74,12 +84,12 @@ No npm package, embeddings, vector search, or database is required.
 
 If you want to adopt Deja Vu in a project without extra infrastructure:
 
-1. Read [docs/protocol.md](./docs/protocol.md).
-2. Read [docs/workflow.md](./docs/workflow.md).
-3. Read [docs/impression-layer.md](./docs/impression-layer.md).
-4. Read [docs/scripted-recall.md](./docs/scripted-recall.md).
-5. Copy the minimum templates from [docs/templates](./docs/templates).
-6. Add optional decision, open-loop, event, and context records only when the project needs them.
+1. Copy [docs/templates/AGENTS.template.md](./docs/templates/AGENTS.template.md) into your project rules file.
+2. Copy [docs/templates/memory/summary.md](./docs/templates/memory/summary.md).
+3. Copy [docs/templates/memory/impressions.jsonl](./docs/templates/memory/impressions.jsonl).
+4. Ask the next agent session to follow the rules before substantial work.
+5. Read [docs/protocol.md](./docs/protocol.md) only when you need the full normative behavior.
+6. Add optional decision, open-loop, feedback, event, and context records only when the project needs them.
 
 Recommended first files:
 
@@ -253,4 +263,5 @@ npm run lint:memory
 - [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)
+- [docs/release-v0.4.1.md](./docs/release-v0.4.1.md)
 - [llms.txt](./llms.txt)

docs/bootstrap-instructions.md

@@ -10,6 +10,8 @@ Give a project durable memory continuity using only:
 - minimum Markdown and JSONL memory files
 - the cue-first Deja Vu workflow
 
+Keep the bootstrap ultra-light. The base product is the protocol, not a required package, service, daemon, vector store, or engine.
+
 ## Trigger conditions
 
 Bootstrap when at least one of these is true:
@@ -49,19 +51,18 @@ Reuse and align existing structures when possible instead of creating a competin
 
 ### 4. Install the minimum protocol artifacts
 
-Create or update:
+Create or update only the minimum first:
 
 - `AGENTS.md`
 - `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:
+Then add helper artifacts only when they reduce repeated explanation or improve recall quality:
 
+- `scripts/dejavu-scan-memory.mjs`
+- `memory/recall-feedback.jsonl`
 - `memory/decisions/`
 - `memory/open-loops/`
-- `memory/recall-feedback.jsonl`
 - `memory/events/`
 - `memory/context/project-context.md`
 - `memory/index.md`

docs/release-v0.4.1.md

@@ -0,0 +1,38 @@
+# Deja Vu v0.4.1: Protocol-First Activation
+
+Deja Vu remains an ultra-light, repo-local memory protocol for AI coding agents.
+
+v0.4.1 sharpens the adoption path around the smallest useful product: three files, one workflow, and optional helper tooling only when a project grows enough to justify it.
+
+## Why It Matters
+
+The core problem is not that agents need another memory platform. The problem is that every new coding-agent chat starts without the project decisions, architecture intent, open loops, and stable preferences that already exist.
+
+Deja Vu keeps the fix small: scan tiny repo-local cues, load the least memory that preserves continuity, and write back only durable context.
+
+## Highlights
+
+- README opening now leads with the concrete pain: stop re-explaining the repo to every new coding-agent chat.
+- Added a 2-minute start path centered on `AGENTS.md`, `memory/summary.md`, and `memory/impressions.jsonl`.
+- Reaffirmed that the base product is the protocol, not an npm package, service, daemon, vector database, or engine.
+- Clarified that scripts, recall feedback, detailed records, and the TypeScript engine are optional scale-up layers.
+
+## Upgrade Notes
+
+No protocol migration is required.
+
+Existing v0.4.0 projects can keep using the same minimum files:
+
+- `AGENTS.md`
+- `memory/summary.md`
+- `memory/impressions.jsonl`
+
+Use `memory/recall-feedback.jsonl`, decision records, open loops, events, and engine helpers only when they reduce repeated explanation or improve recall quality.
+
+## Suggested GitHub Release Title
+
+Deja Vu v0.4.1: Protocol-First Activation
+
+## Suggested Tagline
+
+Stop re-explaining your repo to every new coding-agent chat.

encoding-status.md

@@ -4,17 +4,17 @@
 | --- | --- | --- |
 | `encoding-status.md` | 編碼正常（新建，UTF-8） | Project-local registry created by agent. |
 | `.gitignore` | 編碼正常（新建，UTF-8） | New text file. |
-| `package.json` | 編碼正常（已檢查） | Updated in UTF-8; version bumped to 0.3.1 with cue-quality package description and keywords. |
-| `package-lock.json` | 編碼正常（已檢查） | Updated in UTF-8; package version metadata now matches the 0.3.1 release. |
+| `package.json` | 編碼正常（已檢查） | Updated in UTF-8; version bumped to 0.4.1 with ultra-light protocol-first package description. |
+| `package-lock.json` | 編碼正常（已檢查） | Updated in UTF-8; package version metadata now matches the 0.4.1 release. |
 | `tsconfig.json` | 編碼正常（新建，UTF-8） | New text file. |
 | `LICENSE` | 編碼正常（新建，UTF-8） | New text file. |
-| `README.md` | 編碼正常（已檢查） | Updated in UTF-8; GitHub-facing opening now emphasizes agent context loss, no database/vector dependency, and before/after value. |
-| `CHANGELOG.md` | 編碼正常（已檢查） | Updated in UTF-8; now includes the 0.3.1 recall-quality patch release notes. |
-| `llms.txt` | 編碼正常（已檢查） | Updated in UTF-8; AI-readable index now includes cue quality linting, gist summaries, and boundary-aware chunking. |
+| `README.md` | 編碼正常（已檢查） | Updated in UTF-8; opening now emphasizes ultra-light protocol-first activation and the 2-minute three-file start. |
+| `CHANGELOG.md` | 編碼正常（已檢查） | Updated in UTF-8; now includes the 0.4.1 protocol-first activation patch release notes. |
+| `llms.txt` | 編碼正常（已檢查） | Updated in UTF-8; AI-readable index now emphasizes the three-file ultra-light adoption path. |
 | `docs/architecture.md` | 編碼正常（已檢查） | Rewritten in UTF-8; architecture doc now describes the engine as the optional layer inside a protocol-first product. |
 | `docs/agent-handshake.md` | 編碼正常（已檢查） | Rewritten in UTF-8; handshake now starts from cue-first adoption and recall-budget discipline. |
 | `docs/project-rules-template.md` | 編碼正常（已檢查） | Rewritten in UTF-8; points to canonical AGENTS and memory templates. |
-| `docs/bootstrap-instructions.md` | 編碼正常（已檢查） | Rewritten in UTF-8; bootstrap now installs only minimum cue-first memory artifacts before optional scale-up. |
+| `docs/bootstrap-instructions.md` | 編碼正常（已檢查） | Updated in UTF-8; bootstrap now reinforces the ultra-light protocol-first minimum before optional helper artifacts. |
 | `docs/release-v0.1.0.md` | 編碼正常（已檢查） | Rewritten in UTF-8; release framing now centers repo-first protocol adoption for the earlier release note. |
 | `docs/release-v0.2.0.md` | 編碼正常（新建，UTF-8） | New release note for the protocol-first reboot version. |
 | `docs/protocol.md` | 編碼正常（已檢查） | Rewritten in UTF-8; protocol now defines cue-first v0.3, minimum artifacts, and recall budget. |
@@ -72,5 +72,6 @@
 | `scripts/dejavu-lint-memory.mjs` | 編碼正常（已檢查） | Updated in UTF-8; linter now warns on low-quality impression cues and duplicate keyword sets. |
 | `tests/memory-cli.test.ts` | 編碼正常（已檢查） | Updated in UTF-8; CLI tests now cover low-quality cue warnings. |
 | `docs/release-v0.4.0.md` | 編碼正常（新建，UTF-8） | New release note for feedback-aware recall budgets and recall outcomes. |
+| `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. |

llms.txt

@@ -1,16 +1,16 @@
 # Deja Vu
 
-> Repo-local Markdown memory for AI coding agents.
+> Ultra-light repo-local memory protocol for AI coding agents.
 
-Deja Vu helps agents preserve useful project memory through:
+Deja Vu helps agents stop re-explaining the same repository context across new coding-agent chats through:
 
 - explicit project rules
 - a repeatable cue-scan, minimal-recall, and writeback workflow
 - 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
 
-The minimum adoption path does not require npm, embeddings, vector search, or a dedicated memory service.
+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.
 
 ## Best starting points
 

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "@focaxisdev/deja-vu",
-  "version": "0.4.0",
-  "description": "Repo-local Markdown memory for AI coding agents: persistent project context without a database, vector store, or hosted memory service.",
+  "version": "0.4.1",
+  "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",
   "types": "./dist/src/index.d.ts",