From 4e689861feefa4963669136688f3e14ed5f741be Mon Sep 17 00:00:00 2001 From: Focaxis Dev Date: Sun, 17 May 2026 08:37:06 +0800 Subject: [PATCH 1/3] feat: add universal agent memory starter kit and CLI helpers --- .github/workflows/ci.yml | 39 ++ CHANGELOG.md | 9 + README.md | 355 ++++++++-------- docs/agent-compatibility.md | 63 +++ docs/bootstrap-instructions.md | 26 +- docs/comparison.md | 42 ++ docs/demo-walkthrough.md | 80 ++++ docs/diagrams/deja-vu-flow.md | 39 ++ docs/launch-copy.md | 51 +++ docs/protocol.md | 19 + docs/release-v0.6.0.md | 49 +++ docs/scripted-recall.md | 32 +- docs/storage-markdown.md | 18 + docs/templates/AGENTS.template.md | 15 +- docs/workflow.md | 13 +- encoding-status.md | 41 ++ examples/protocol-project/AGENTS.md | 12 +- examples/protocol-project/README.md | 3 +- .../protocol-project/memory/impressions.jsonl | 2 +- .../memory/recall-feedback.jsonl | 2 +- llms.txt | 10 +- package-lock.json | 2 + package.json | 10 +- scripts/deja-vu.mjs | 386 ++++++++++++++++++ scripts/dejavu-scan-memory.mjs | 31 +- starter-kit/AGENTS.md | 55 +++ starter-kit/README.md | 38 ++ starter-kit/memory/decisions/.gitkeep | 1 + starter-kit/memory/impressions.jsonl | 1 + starter-kit/memory/open-loops/.gitkeep | 1 + starter-kit/memory/recall-feedback.jsonl | 1 + starter-kit/memory/summary.md | 40 ++ starter-kit/prompts/chatgpt.md | 11 + starter-kit/prompts/claude-code.md | 11 + starter-kit/prompts/codex.md | 11 + starter-kit/prompts/cursor.md | 11 + starter-kit/prompts/gemini-cli.md | 11 + starter-kit/prompts/windsurf.md | 11 + tests/memory-cli.test.ts | 116 +++++- tests/package-pack.test.ts | 20 + 40 files changed, 1445 insertions(+), 243 deletions(-) create mode 100644 .github/workflows/ci.yml create mode 100644 docs/agent-compatibility.md create mode 100644 docs/comparison.md create mode 100644 docs/demo-walkthrough.md create mode 100644 docs/diagrams/deja-vu-flow.md create mode 100644 docs/launch-copy.md create mode 100644 docs/release-v0.6.0.md create mode 100644 scripts/deja-vu.mjs create mode 100644 starter-kit/AGENTS.md create mode 100644 starter-kit/README.md create mode 100644 starter-kit/memory/decisions/.gitkeep create mode 100644 starter-kit/memory/impressions.jsonl create mode 100644 starter-kit/memory/open-loops/.gitkeep create mode 100644 starter-kit/memory/recall-feedback.jsonl create mode 100644 starter-kit/memory/summary.md create mode 100644 starter-kit/prompts/chatgpt.md create mode 100644 starter-kit/prompts/claude-code.md create mode 100644 starter-kit/prompts/codex.md create mode 100644 starter-kit/prompts/cursor.md create mode 100644 starter-kit/prompts/gemini-cli.md create mode 100644 starter-kit/prompts/windsurf.md create mode 100644 tests/package-pack.test.ts diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..0bd5a9b --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,39 @@ +name: CI + +on: + push: + branches: + - main + pull_request: + +jobs: + test: + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: 22 + cache: npm + + - name: Install + run: npm ci + + - name: Source tests + run: npm run test:src:readonly + + - name: Memory lint + run: npm run lint:memory + + - name: Feedback report + run: npm run report:feedback + + - name: Build + run: npm run build + + - name: Pack verification + run: npm run test:pack diff --git a/CHANGELOG.md b/CHANGELOG.md index 5091a7b..33e214f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,15 @@ All notable changes to this project will be documented in this file. +## Unreleased + +- Reworked the README first screen around the "3-file memory system" positioning. +- Added a copy-first `starter-kit/` with minimal `AGENTS.md`, memory files, and per-agent prompts. +- Added comparison, compatibility, flow diagram, demo walkthrough, launch copy, and v0.6.0 release checklist docs. +- Added the optional unified `deja-vu init`, `deja-vu doctor`, and `deja-vu explain` CLI. +- Split read-only source tests from npm pack verification with `test:src:readonly` and `test:pack`. +- Updated scripted recall to distinguish missing setup as `not_initialized`. + ## [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. diff --git a/README.md b/README.md index 467ce97..de4e319 100644 --- a/README.md +++ b/README.md @@ -1,192 +1,216 @@ # Deja Vu -**Stop re-explaining your repo to every new coding-agent chat.** +**A 3-file memory system for any capable AI coding agent.** -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. +Stop re-explaining your repo every time you start a new Codex, Claude Code, Cursor, Windsurf, ChatGPT, or Gemini CLI session. -It does not require a database, vector store, embedding model, hosted memory service, daemon, or npm package. +Deja Vu gives your project a tiny, repo-local memory layer: + +- `AGENTS.md` tells agents how to recall and write memory. +- `memory/summary.md` keeps durable project context. +- `memory/impressions.jsonl` stores tiny recall cues. + +No database. No vector store. No embeddings. No SaaS. No daemon. No required npm install. + +Just copy three files into your repo. ```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 +Task + -> scan tiny cues + -> no familiarity: load nothing + -> weak familiarity: load summary + -> strong familiarity: load 1-3 linked records + -> work + -> write back durable memory only ``` +Deja Vu is not trying to store more. +Deja Vu is trying to recall less, better. + ## 2-Minute Start -Start by copying or creating only three files: +Copy the starter kit into any repo: -- `AGENTS.md` -- `memory/summary.md` -- `memory/impressions.jsonl` +```bash +cp -R starter-kit/. . +``` -Then tell the next coding-agent chat: +Or use the optional CLI: -```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. +```bash +npx @focaxisdev/deja-vu init --agents all ``` -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: +Then paste this into your next agent session: ```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 +Follow AGENTS.md. Before substantial planning or code changes, scan memory/impressions.jsonl for familiar cues. If familiarity is weak, read memory/summary.md. If familiarity is strong, read only the 1-3 linked detailed records needed for this task. Do not load the whole memory tree unless I ask. After the task, write back only durable decisions, architecture intent, stable preferences, unresolved follow-ups, or milestone summaries. Never store secrets, full transcripts, low-signal chatter, or disposable exploration noise. ``` -If the outcome is not durable enough to help a future agent, do not write it into memory. +That is the base product. Scripts, feedback, decision records, open loops, and the TypeScript engine are optional scale-up paths. -Use Deja Vu if your team keeps repeating: +## Before / After -- "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." +Before Deja Vu: -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? +- "Remember, we already decided not to use X because Y..." +- "Here is the architecture again..." +- "Please do not break the IME workaround we fixed last week..." +- "The agent forgot the open issue from the previous session..." -The core loop is intentionally small: +After Deja Vu: -```text -task cue -> familiarity score -> minimal recall -> durable writeback -``` +- "Follow AGENTS.md and scan memory/impressions.jsonl before planning." +- The agent loads only relevant project memory. +- Durable decisions survive across new chats. +- Low-value chat noise is not stored. -It is packaged as three project-local assets: +## What It Is -- rules -- workflow -- tiny memory files +Deja Vu is a repo-level memory convention: -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. +| It is | It is not | +| --- | --- | +| three repo-local files first | a vector database | +| Markdown and JSONL | a hosted memory service | +| agent-readable project rules | an agent runtime | +| git-friendly durable memory | a required npm package | +| low-token recall discipline | a full chat transcript archive | -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. +The memory lives in the repo, not inside one vendor. -Use Deja Vu when you want: +Any capable coding agent can follow the protocol when it can read project files, follow instructions, respect a memory budget, and update files. For chat-only agents, paste the prompt and provide the relevant memory files manually. -- 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 -- optional CLI or TypeScript helpers only when the project outgrows the file-first protocol +## The Three Files -## What Deja Vu Is +### `AGENTS.md` -Deja Vu defines a shared memory behavior for agents working inside one project. +Tells agents how to use Deja Vu: -It answers: +- read project instructions first +- scan cues before substantial work +- load summary only when needed +- load 1-3 detailed records for strong matches +- write back only durable memory +- never store sensitive or noisy content -- what should count as durable memory -- when an agent should recall existing memory -- how memory should be stored in ordinary project files -- when memory should be updated, compacted, or retired +### `memory/summary.md` -The minimum viable setup uses three project-local plain text files: +Keeps compact project truth: -- `AGENTS.md` -- `memory/summary.md` -- `memory/impressions.jsonl` +- current objective +- durable constraints +- active priorities +- linked decisions +- unresolved follow-ups -Add one optional feedback ledger when recall results should change future behavior: +It is not a chat log. -- `memory/recall-feedback.jsonl` +### `memory/impressions.jsonl` -No npm package, embeddings, vector search, or database is required. +Keeps tiny cue routes: -## Start Here +```json +{"schema_version":1,"id":"summary","scope":"project:your-repo","title":"Project summary","keywords":["architecture","constraints","priorities"],"record_path":"memory/summary.md","updated":"2026-05-16","weight":0.7,"status":"active"} +``` -If you want to adopt Deja Vu in a project without extra infrastructure: +Agents scan these cues before spending tokens on bigger memory files. -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. +## Agent Prompts -Recommended first files: +Copy a short prompt for the tool you use: -- [docs/templates/AGENTS.template.md](./docs/templates/AGENTS.template.md) -- [docs/templates/memory/summary.md](./docs/templates/memory/summary.md) -- [docs/templates/memory/impressions.jsonl](./docs/templates/memory/impressions.jsonl) -- [docs/templates/memory/decisions/decision-template.md](./docs/templates/memory/decisions/decision-template.md) -- [docs/templates/memory/open-loops/open-loop-template.md](./docs/templates/memory/open-loops/open-loop-template.md) +- [Codex](./starter-kit/prompts/codex.md) +- [Claude Code](./starter-kit/prompts/claude-code.md) +- [Cursor](./starter-kit/prompts/cursor.md) +- [Windsurf](./starter-kit/prompts/windsurf.md) +- [ChatGPT](./starter-kit/prompts/chatgpt.md) +- [Gemini CLI](./starter-kit/prompts/gemini-cli.md) -## The Protocol in One Page +The prompts all enforce the same budget: -Deja Vu follows a cue-first lifecycle: +- scan `memory/impressions.jsonl` first +- read `memory/summary.md` only for weak familiarity +- read at most 1-3 detailed records for strong familiarity +- never load the whole memory tree by default +- write back only durable memory -1. Scan a tiny impression index before substantial planning, coding, or answering. -2. Load no memory when the scan finds no familiarity. -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. 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. +## Optional CLI -This keeps memory project-local, readable, and easy to maintain across new conversations. +The CLI exists to support the three-file protocol. It is not required. -## Canonical Project Layout +```bash +npx @focaxisdev/deja-vu init --dry-run +npx @focaxisdev/deja-vu init --agents codex,claude-code +npx @focaxisdev/deja-vu doctor --json +npx @focaxisdev/deja-vu explain +``` -```text -memory/ - summary.md - impressions.jsonl - recall-feedback.jsonl - decisions/ - open-loops/ - events/ - context/ - index.md +`init` creates missing files only. It does not overwrite existing files unless you pass `--force`. + +`doctor` checks whether a repo has a usable Deja Vu setup, validates JSONL, warns about memory bloat and transcript-like content, and flags obvious secrets. + +For public repos, remember that tracked memory files are public project files. `doctor` can catch obvious risks, but it is not a complete secret or PII scanner. + +Existing focused tools still work: + +```bash +deja-vu-scan-memory "current task" +deja-vu-lint-memory --memory-root memory +deja-vu-feedback-report --memory-root memory ``` -The canonical layout and field rules are specified in [docs/storage-markdown.md](./docs/storage-markdown.md). - -## Core Rules - -- Use a single-project scope only in MVP: `project:`. -- Recall before substantial work, but follow a strict recall budget. -- Prefer scripted impression scans first; open summary or detailed records only when needed. -- Keep impression cues sparse, specific, and linted so the first recall step stays cheap. -- Write back only durable memory: - - decisions - - architecture intent - - 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 - - detail: one to three records - - full memory tree: forbidden unless explicitly requested -- Never store: - - raw secrets or credentials - - full turn-by-turn transcripts - - low-signal chatter - - disposable exploration noise - -## Why This Exists - -Most agent memory systems fail in one of two ways: - -- they remember too little because nothing is written down in a reusable shape -- they remember too much because every conversation turn is treated like durable knowledge - -Deja Vu stays closer to first principles: - -- memory should be explicit -- memory should be scoped -- memory should be cheap to inspect -- memory should be easy to revise -- memory behavior should survive a new conversation window +## Protocol + +The Deja Vu lifecycle is: + +1. Scan tiny cues. +2. Classify familiarity: none, weak, or strong. +3. Load the smallest useful memory. +4. Work normally. +5. Write back durable memory only. +6. Compact or retire stale memory when recall gets noisy. + +Default recall budget: + +- impression scan: always allowed +- summary: at most one file +- detailed records: one to three files +- full memory tree: forbidden unless explicitly requested + +Write back only: + +- accepted decisions +- architecture intent +- stable preferences +- unresolved follow-ups +- milestone summaries +- recall feedback that should tune future cues + +Never write back: + +- secrets, tokens, credentials, or private keys +- full turn-by-turn transcripts +- customer/user PII +- low-signal chatter +- disposable exploration noise + +Read the full spec in [docs/protocol.md](./docs/protocol.md). + +## Docs + +- [Starter kit](./starter-kit/README.md) +- [Comparison](./docs/comparison.md) +- [Agent compatibility](./docs/agent-compatibility.md) +- [Flow diagram](./docs/diagrams/deja-vu-flow.md) +- [Demo walkthrough](./docs/demo-walkthrough.md) +- [Protocol](./docs/protocol.md) +- [Workflow](./docs/workflow.md) +- [Markdown storage contract](./docs/storage-markdown.md) +- [Impression layer](./docs/impression-layer.md) +- [Scripted recall](./docs/scripted-recall.md) +- [Launch copy](./docs/launch-copy.md) +- [llms.txt](./llms.txt) ## Optional Engine Layer @@ -199,24 +223,12 @@ Use it when you want: - embedding and vector ranking - an engine-backed implementation of the Deja Vu protocol -Do not treat the engine as the product center. It is an optional acceleration layer. - -Start here if you want that path: - -- [docs/engine/semantic-engine.md](./docs/engine/semantic-engine.md) -- [docs/engine/protocol-to-engine.md](./docs/engine/protocol-to-engine.md) -- [docs/agent-handshake.md](./docs/agent-handshake.md) - -## Optional npm Install +Do not treat the engine as the product center. It is an optional acceleration layer after the repo-local memory protocol is already useful. ```bash npm install @focaxisdev/deja-vu ``` -The npm package provides the optional TypeScript engine. It is not required for base protocol adoption. - -## Engine API - ```ts const engine = new SemanticRecallEngine(config); @@ -229,12 +241,6 @@ await engine.updateMemory(id, input); await engine.deleteMemory(id); ``` -The public TypeScript exports remain intact for hosts that want semantic recall. - -`scanImpressions()` performs token-only familiarity scanning and does not load summaries or chunks. - -The default engine helpers preserve low-token recall quality by generating decision/rationale/trigger summaries and by chunking Markdown or paragraph boundaries before falling back to character splits. - ## Examples - Protocol-first example: [examples/protocol-project](./examples/protocol-project) @@ -243,47 +249,14 @@ The default engine helpers preserve low-token recall quality by generating decis - Engine example: `npm run example:chat-memory` - Engine example: `npm run example:task-assistant` -## Repo Structure - -```text -deja-vu/ - docs/ - protocol.md - workflow.md - storage-markdown.md - templates/ - engine/ - examples/ - protocol-project/ - basic/ - agent-pm/ - chat-memory/ - task-assistant/ - src/ - tests/ -``` - ## Development ```bash npm install npm run build -npm run test:src +npm run test:src:readonly npm run lint:memory npm run report:feedback ``` -## References - -- [docs/protocol.md](./docs/protocol.md) -- [docs/workflow.md](./docs/workflow.md) -- [docs/storage-markdown.md](./docs/storage-markdown.md) -- [docs/impression-layer.md](./docs/impression-layer.md) -- [docs/scripted-recall.md](./docs/scripted-recall.md) -- [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) -- [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) +`npm run test` rebuilds `dist`. Use `test:src:readonly` when you want source tests without build output side effects. diff --git a/docs/agent-compatibility.md b/docs/agent-compatibility.md new file mode 100644 index 0000000..8be99a4 --- /dev/null +++ b/docs/agent-compatibility.md @@ -0,0 +1,63 @@ +# Agent Compatibility + +Deja Vu works best with agents that can: + +- read repo files +- follow project instructions +- update files +- respect memory budgets +- avoid storing secrets or noisy transcripts + +Any capable coding agent can follow the protocol. +The memory lives in the repo, not inside one vendor. + +## Strong Fit + +Use the normal Deja Vu flow when an agent can inspect and edit project files: + +1. read `AGENTS.md` +2. scan `memory/impressions.jsonl` +3. load `memory/summary.md` only for weak familiarity +4. load 1-3 linked detailed records only for strong familiarity +5. write back durable memory only + +This is the intended path for file-aware coding agents such as Codex, Claude Code, Cursor, Windsurf, Gemini CLI, and similar tools when they can access the repo. + +## Chat-Only Agents + +Some chat agents cannot directly read repo files. + +Use the manual path: + +1. paste `AGENTS.md` +2. paste `memory/impressions.jsonl` or the relevant lines +3. paste `memory/summary.md` only when the task needs project context +4. paste 1-3 detailed records only when the cue strongly matches +5. ask the agent to propose durable writeback, then review before committing it + +Do not paste the whole memory tree by default. + +## Correct Promise + +Say: + +> Any capable coding agent can follow the protocol. + +Do not say: + +> Every agent automatically supports Deja Vu. + +Deja Vu is a repo-local convention and memory discipline. Agents still need enough capability and instruction-following reliability to use it. + +## Prompt Compatibility + +Short prompts are included in [starter-kit/prompts](../starter-kit/prompts): + +- Codex +- Claude Code +- Cursor +- Windsurf +- ChatGPT +- Gemini CLI + +They are intentionally similar. The protocol should stay stable even when the tool changes. diff --git a/docs/bootstrap-instructions.md b/docs/bootstrap-instructions.md index ea16100..0fca578 100644 --- a/docs/bootstrap-instructions.md +++ b/docs/bootstrap-instructions.md @@ -27,17 +27,21 @@ Bootstrap when at least one of these is true: - confirm the active project path - choose a stable `project:` scope -### 2. Read the protocol files +### 2. Use the starter kit first -Read: +Start from: -1. `README.md` -2. `docs/protocol.md` -3. `docs/workflow.md` -4. `docs/storage-markdown.md` -5. `docs/impression-layer.md` -6. `docs/scripted-recall.md` -7. `docs/templates/AGENTS.template.md` +1. `starter-kit/AGENTS.md` +2. `starter-kit/memory/summary.md` +3. `starter-kit/memory/impressions.jsonl` + +Read the full protocol docs only when the project needs customization: + +- `docs/protocol.md` +- `docs/workflow.md` +- `docs/storage-markdown.md` +- `docs/impression-layer.md` +- `docs/scripted-recall.md` ### 3. Check whether memory already exists @@ -79,9 +83,11 @@ Ensure future work follows: After bootstrap, run: ```bash -node scripts/dejavu-lint-memory.mjs +deja-vu doctor ``` +If the optional CLI is not installed, run `node scripts/dejavu-lint-memory.mjs` when the script is available. + ### 6. Optional engine adoption Only if the host needs semantic recall at higher scale: diff --git a/docs/comparison.md b/docs/comparison.md new file mode 100644 index 0000000..8f13ca5 --- /dev/null +++ b/docs/comparison.md @@ -0,0 +1,42 @@ +# Deja Vu Compared + +Deja Vu is not trying to store more. +Deja Vu is trying to recall less, better. + +| Approach | Setup cost | Token cost | Privacy | Portability | Works across agents | Human readable | Git-friendly | Risk of memory noise | Best use case | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| Deja Vu | Copy three files, optional CLI | Low: cue scan first, summary only when needed | Repo-local; user controls files | High: Markdown and JSONL | High for agents that read files and follow instructions | High | High | Medium-low if cues stay sparse | Project memory for AI coding work | +| Vector DB memory | Database, embeddings, indexing, retrieval code | Medium: retrieval can overfetch | Depends on hosting and data flow | Medium-low: tied to stack choices | Medium: usually app/framework specific | Low-medium | Low | Medium-high if chunks are noisy | Large semantic retrieval over many documents | +| Hosted memory service | Account, API key, SDK, integration | Medium: service decides retrieved context | Depends on vendor | Low-medium: vendor-specific | Medium: usually API/client specific | Low | Low | Medium: hidden memory can drift | Production user or agent memory with managed infra | +| Screen/context capture memory | Desktop/app permissions and capture pipeline | High: captured context can be broad | Sensitive by default | Low: tool-specific | Low-medium | Low | Low | High: captures too much | Recovering UI/session state | +| Agent runtime framework | Framework install, app architecture, tools | Medium-high | Depends on framework and storage | Medium-low | Low-medium: runtime-specific | Low-medium | Medium | Medium | Building full agent applications | +| Simple project notes | Create a notes file | Medium: humans or agents may load too much | Repo-local | High | High | High | High | Medium-high: no recall discipline | Small teams needing informal project notes | +| Full chat transcript archive | Export or save chats | Very high if loaded | Risky: often contains sensitive data | Medium | Medium | Medium | Medium-low | Very high | Audit trail, not active recall | + +## Core Distinction + +Most memory systems start with storage: + +```text +capture more -> index more -> retrieve more +``` + +Deja Vu starts with recognition: + +```text +task cue -> tiny scan -> minimal recall -> durable writeback +``` + +The base product is intentionally small: + +- one repo memory +- any capable coding agent +- three files first +- no database +- no vector store +- no embeddings +- no SaaS +- no daemon +- no required npm install + +Use Deja Vu when the problem is not "search my entire knowledge base." Use it when the problem is "stop making me re-explain why this repo works the way it does." diff --git a/docs/demo-walkthrough.md b/docs/demo-walkthrough.md new file mode 100644 index 0000000..f5087c1 --- /dev/null +++ b/docs/demo-walkthrough.md @@ -0,0 +1,80 @@ +# Demo Walkthrough + +This walkthrough shows the behavior Deja Vu is designed to create. + +## Before Deja Vu + +New agent session: + +```text +User: We need to continue the settings refactor. +Agent: I can help. What is the architecture? +User: We already decided not to move preferences into localStorage because settings sync is server-backed. +User: Also do not break the IME workaround from last week. +User: And there is still an unresolved follow-up to migrate old setting names. +``` + +The user spends the first minutes reconstructing project memory. + +## Add Deja Vu + +The repo has: + +```text +AGENTS.md +memory/summary.md +memory/impressions.jsonl +memory/decisions/settings-sync.md +memory/open-loops/settings-migration.md +``` + +`memory/impressions.jsonl` contains tiny cue routes: + +```json +{"schema_version":1,"id":"decision-settings-sync","scope":"project:demo","title":"Settings sync stays server-backed","keywords":["settings","sync","localstorage","preferences"],"record_path":"memory/decisions/settings-sync.md","updated":"2026-05-16","weight":0.9,"status":"active"} +{"schema_version":1,"id":"open-loop-settings-migration","scope":"project:demo","title":"Migrate old setting names","keywords":["settings","migration","legacy","names"],"record_path":"memory/open-loops/settings-migration.md","updated":"2026-05-16","weight":0.8,"status":"active"} +``` + +## After Deja Vu + +New agent session: + +```text +User: Continue the settings refactor. +Agent: I will follow AGENTS.md and scan memory/impressions.jsonl before planning. +``` + +The cue scan finds a strong match for `settings` and `sync`. + +The agent reads only: + +- `memory/decisions/settings-sync.md` +- `memory/open-loops/settings-migration.md` + +Then it plans with the right constraints: + +- do not move synced preferences to localStorage +- preserve the existing IME workaround +- continue the legacy setting-name migration + +## Post-Task Writeback + +If the work creates durable memory, the agent writes back only that signal: + +- accepted decision -> `memory/decisions/` +- unresolved follow-up -> `memory/open-loops/` +- project-level truth -> `memory/summary.md` +- recall quality signal -> `memory/recall-feedback.jsonl` + +It does not store the whole chat. + +## Dogfooding Deja Vu + +Deja Vu should use Deja Vu on itself: + +- keep product positioning decisions in `memory/decisions/` +- keep release follow-ups in `memory/open-loops/` +- keep the current project story in `memory/summary.md` +- keep only sparse cue routes in `memory/impressions.jsonl` + +Public examples must be sanitized. Do not include private chat transcripts, secrets, customer data, or internal-only project facts. diff --git a/docs/diagrams/deja-vu-flow.md b/docs/diagrams/deja-vu-flow.md new file mode 100644 index 0000000..68c816d --- /dev/null +++ b/docs/diagrams/deja-vu-flow.md @@ -0,0 +1,39 @@ +# Deja Vu Flow + +```mermaid +flowchart TD + A["Task"] --> B["Tiny cue scan
memory/impressions.jsonl"] + B --> C{"Familiarity?"} + C -->|None| D["Load no memory by default"] + C -->|Weak| E["Load memory/summary.md"] + C -->|Strong| F["Load 1-3 linked detailed records"] + D --> G["Work"] + E --> G + F --> G + G --> H{"Durable outcome?"} + H -->|No| I["Skip writeback"] + H -->|Yes| J["Write durable memory only"] + J --> K["Update summary, impressions,
decision, open-loop, or feedback"] +``` + +ASCII fallback: + +```text +Task + | + v +Tiny cue scan + | + v +No familiarity -> load nothing +Weak familiarity -> load summary +Strong familiarity -> load 1-3 detailed records + | + v +Work + | + v +Durable writeback only +``` + +The point is not to replay old context. The point is to recognize when a task deserves more context. diff --git a/docs/launch-copy.md b/docs/launch-copy.md new file mode 100644 index 0000000..60e4c79 --- /dev/null +++ b/docs/launch-copy.md @@ -0,0 +1,51 @@ +# Launch Copy + +## X / Threads + +I got tired of re-explaining the same repo to every new AI coding agent session. + +Deja Vu is a 3-file, repo-local memory layer any capable coding agent can follow. + +No vector DB. +No SaaS. +No embeddings. +No daemon. + +Memory should feel like recognition, not replay. + +## LinkedIn + +Every new AI coding agent session starts with the same tax: explain the repo, explain the decisions, explain the constraints, explain what not to break. + +Deja Vu is a 3-file memory system for AI coding agents: + +- `AGENTS.md` +- `memory/summary.md` +- `memory/impressions.jsonl` + +It is repo-local, human-readable, git-friendly, and does not require a vector database, SaaS memory platform, embeddings, daemon, or npm install. + +The goal is not to store more. The goal is to help agents recall less, better. + +## GitHub Release Intro + +Deja Vu v0.6.0 reframes the project around the adoption path that matters most: a 3-file, repo-local memory system for any capable AI coding agent. + +This release adds a copy-first starter kit, per-agent prompts, clearer compatibility and comparison docs, a visual recall flow, launch copy, and an optional `deja-vu init/doctor/explain` CLI that serves the file-first protocol without making npm required. + +## Hacker News Titles + +- Show HN: Deja Vu, a 3-file memory system for AI coding agents +- Show HN: Repo-local memory for Codex, Claude Code, Cursor, and Windsurf +- Show HN: Stop re-explaining your repo to every new coding agent chat +- Show HN: Deja Vu stores less so coding agents recall better + +## Taglines + +- A 3-file memory system for any AI coding agent. +- Repo-local memory for coding agents. +- Long-term project memory that fits in a pull request. +- Stop re-explaining your repo to every new agent chat. +- Memory should feel like recognition, not replay. +- Store less, recall better. +- Your repo should carry its own agent memory. diff --git a/docs/protocol.md b/docs/protocol.md index 8e1bf60..087200a 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -4,6 +4,8 @@ Deja Vu is a cue-first memory protocol for AI agents. This document is the normative specification for the minimum viable Deja Vu protocol. +Protocol version and package version are separate. Package releases may ship docs, templates, or CLI helpers without changing the protocol version. + ## Goal Enable any agent to maintain useful project memory with extremely low per-conversation token cost using only: @@ -21,6 +23,23 @@ The core loop is: task cue -> familiarity score -> minimal recall -> durable writeback ``` +## Agent Contract + +An agent following Deja Vu must: + +1. Read the project rules before substantial project work. +2. Scan `memory/impressions.jsonl` before spending tokens on larger memory files. +3. Treat missing required files as `not_initialized`, not as a valid no-match. +4. Load no memory when familiarity is `none`. +5. Load only `memory/summary.md` when familiarity is `weak`. +6. Load at most one to three linked detailed records when familiarity is `strong`. +7. Never load the whole memory tree unless the user explicitly asks. +8. Write back only durable project memory. +9. Leave a future cue route in `memory/impressions.jsonl` for every durable record. +10. Avoid secrets, PII, full transcripts, raw logs, and low-signal chatter. + +The three-file model is the minimum bootstrap surface. Detailed recall becomes useful when the project later adds decision, open-loop, or context records. + ## Scope Model - MVP supports one memory scope only: `project:`. diff --git a/docs/release-v0.6.0.md b/docs/release-v0.6.0.md new file mode 100644 index 0000000..10eda75 --- /dev/null +++ b/docs/release-v0.6.0.md @@ -0,0 +1,49 @@ +# Deja Vu v0.6.0 Candidate Checklist + +v0.6.0 is the adoption release: Deja Vu becomes a copy-first, three-file project memory starter kit with optional CLI support. + +## Product Surface + +- README first screen leads with "A 3-file memory system for any capable AI coding agent." +- Starter kit can be copied into a repo root. +- Per-agent prompts exist for Codex, Claude Code, Cursor, Windsurf, ChatGPT, and Gemini CLI. +- npm package remains optional. +- TypeScript engine remains below the fold as an acceleration layer. + +## CLI Surface + +- `deja-vu init` creates missing starter files only. +- `deja-vu init --dry-run` previews file operations. +- `deja-vu init --agents all` adds per-agent prompts. +- `deja-vu doctor` checks required files, JSONL, feedback routes, memory bloat, transcript-like content, and obvious secrets. +- `deja-vu explain` prints a short protocol explanation. + +## Release Verification + +Run before tagging or publishing: + +```bash +npm run test:src:readonly +npm run lint:memory +npm run report:feedback +npm run build +npm run test:pack +``` + +`npm run test:pack` may rebuild `dist` through `prepack`. Do not treat it as a read-only test. + +## Version Policy + +- Package version can move to `0.6.0` only after release approval. +- Protocol remains `Deja Vu Protocol v0.4` unless the normative behavior changes. +- `schema_version` values in JSONL remain independent from package and protocol versions. + +## Pre-Release Checks + +- Confirm README links resolve. +- Confirm `starter-kit/` is included in npm pack output. +- Confirm `package-lock.json` bin metadata matches `package.json`. +- Confirm `.gitignore` keeps `SNS/` ignored and launch copy lives in `docs/`. +- Confirm examples pass memory lint. +- Confirm no public memory sample contains secrets, PII, or raw transcripts. +- Decide whether to add GitHub Actions before release. diff --git a/docs/scripted-recall.md b/docs/scripted-recall.md index e43a3ad..14dcf45 100644 --- a/docs/scripted-recall.md +++ b/docs/scripted-recall.md @@ -14,6 +14,14 @@ After npm installation, the same scanner can be exposed as: deja-vu-scan-memory "current task or user request" ``` +The unified optional CLI also provides setup and health checks: + +```bash +deja-vu init --dry-run +deja-vu doctor +deja-vu explain +``` + The companion linter checks whether the impression index is structurally usable: ```bash @@ -76,26 +84,34 @@ The script prints JSON: } ``` +If `memory/impressions.jsonl` is missing, the script returns `level: "not_initialized"` with a bootstrap hint instead of pretending the task had no familiarity match. + ## Host Workflow 1. Run the script before substantial planning, coding, or answering. 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. 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. +3. Treat `not_initialized` as a setup problem and create the three required files. +4. Treat `weak` as a reason to read `memory/summary.md`. +5. Treat `strong` as a reason to open one to three linked records before planning. +6. Watch `budget` before loading more memory. +7. Record recall feedback only when the result should tune future cue quality. +8. Continue to apply normal writeback and compaction rules after work completes. ## Bootstrap Rule -When installing Deja Vu into a project, copy or create: +When installing Deja Vu into a project, copy or create the three required files: +- `AGENTS.md` - `memory/impressions.jsonl` - `memory/summary.md` + +Optional scale-up files: + - `memory/recall-feedback.jsonl` -- `scripts/dejavu-scan-memory.mjs` +- `memory/decisions/` +- `memory/open-loops/` -The script is intentionally small. Hosts may replace it with a faster native implementation, but the input and output contract should stay stable. +The script is intentionally small and optional. Hosts may replace it with a faster native implementation, but the input and output contract should stay stable. Add `memory/decisions/`, `memory/open-loops/`, `memory/events/`, or `memory/index.md` only when the project has enough durable memory to justify them. diff --git a/docs/storage-markdown.md b/docs/storage-markdown.md index bbf1d7a..bcac4d8 100644 --- a/docs/storage-markdown.md +++ b/docs/storage-markdown.md @@ -94,6 +94,8 @@ Purpose: - capture reward signals without logging full transcripts - identify helpful, irrelevant, missed, or overloaded recall routes +Feedback queries should be sanitized cues, not raw user prompts. Do not include secrets, PII, or long task text. + Each line must be one JSON object with: - `schema_version` @@ -211,3 +213,19 @@ Markdown is the primary storage contract because it is: - easy to diff and review Do not require JSON as a parallel source of truth in MVP. + +## Public Repo Safety + +Track only memory that is safe to share with everyone who can read the repo. + +Recommended private/local ignore patterns when needed: + +```gitignore +memory/private/ +memory/local/ +memory/raw/ +memory/transcripts/ +memory/**/*.secret.* +``` + +Do not ignore all of `memory/` by default. The protocol works because sanitized durable memory travels with the repo. diff --git a/docs/templates/AGENTS.template.md b/docs/templates/AGENTS.template.md index 544a50c..ceb4ddc 100644 --- a/docs/templates/AGENTS.template.md +++ b/docs/templates/AGENTS.template.md @@ -8,17 +8,20 @@ After copying this template, replace every `` and placeholder memory field before using it in a real project. +Protocol version and package version are separate. Keep this line on the protocol version this project follows. + ## Required recall behavior Before substantial planning, coding, or answering: 1. Run `node scripts/dejavu-scan-memory.mjs ""` when available. -2. If the result is `none`, avoid memory reads by default. -3. If the result is `weak`, read `memory/summary.md`. -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. +2. If the result is `not_initialized`, create or ask for the three required files. +3. If the result is `none`, avoid memory reads by default. +4. If the result is `weak`, read `memory/summary.md`. +5. If the result is `strong`, open one to three linked detailed records. +6. If the script is missing, inspect `memory/impressions.jsonl` directly and apply the same budget. -6. Keep the scan output's budget fields visible before loading more memory. +7. Keep the scan output's budget fields visible before loading more memory. Recall budget: @@ -60,8 +63,10 @@ Do not store: - secrets, tokens, credentials, or private keys - full conversation transcripts +- customer or user PII - low-signal chatter - temporary exploration noise +- raw debug logs or build output ## Compaction behavior diff --git a/docs/workflow.md b/docs/workflow.md index 58b0740..fae94e2 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -8,6 +8,8 @@ Use the smallest amount of memory that preserves continuity. Deja Vu should feel like recognition, not replay. A task cue earns more context only when it matches a reusable project memory route. +Scripts are optional. If the scanner is missing, an agent can inspect `memory/impressions.jsonl` directly and apply the same budget. + ## Task Lifecycle ### Pre-task recall @@ -15,11 +17,12 @@ Deja Vu should feel like recognition, not replay. A task cue earns more context Before substantial planning, coding, or answering: 1. Run `node scripts/dejavu-scan-memory.mjs ""` when the script exists. -2. If the scan level is `none`, avoid detailed memory reads by default. -3. If the scan level is `weak`, read `memory/summary.md`. -4. If the scan level is `strong`, read the linked detailed record before planning. -5. If no script exists, fall back to `memory/summary.md` and then `memory/index.md` when present. -6. Keep the scan output's budget fields visible while deciding whether to load more memory. +2. If the scan level is `not_initialized`, create or ask for the three required files. +3. If the scan level is `none`, avoid detailed memory reads by default. +4. If the scan level is `weak`, read `memory/summary.md`. +5. If the scan level is `strong`, read one to three linked detailed records before planning. +6. If no script exists, inspect `memory/impressions.jsonl` directly and apply the same budget. +7. Keep the scan output's budget fields visible while deciding whether to load more memory. Recall budget: diff --git a/encoding-status.md b/encoding-status.md index f29765d..6b6d418 100644 --- a/encoding-status.md +++ b/encoding-status.md @@ -86,3 +86,44 @@ | `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. | +| `README.md` | 編碼正常（已檢查） | Updated in UTF-8; first screen now positions Deja Vu as a 3-file memory system with copy-first starter and optional CLI. | +| `CHANGELOG.md` | 編碼正常（已檢查） | Updated in UTF-8; Unreleased notes now describe the v0.6.0 candidate adoption work. | +| `llms.txt` | 編碼正常（已檢查） | Updated in UTF-8; AI-readable index now points to starter kit, compatibility, comparison, diagram, demo, and v0.6.0 checklist. | +| `package.json` | 編碼正常（已檢查） | Updated in UTF-8; added unified CLI bin, starter-kit package files, and split readonly source tests from pack tests. | +| `package-lock.json` | 編碼正常（已檢查） | Updated in UTF-8; root package bin metadata now matches package.json. | +| `docs/bootstrap-instructions.md` | 編碼正常（已檢查） | Updated in UTF-8; bootstrap now starts from starter-kit and uses doctor when the optional CLI is available. | +| `docs/protocol.md` | 編碼正常（已檢查） | Updated in UTF-8; added protocol/package version note and compact agent contract. | +| `docs/scripted-recall.md` | 編碼正常（已檢查） | Updated in UTF-8; scripted recall now documents not_initialized and keeps recall feedback optional. | +| `docs/storage-markdown.md` | 編碼正常（已檢查） | Updated in UTF-8; added feedback sanitization and public repo safety guidance. | +| `docs/templates/AGENTS.template.md` | 編碼正常（已檢查） | Updated in UTF-8; template now handles not_initialized and expanded safety boundaries. | +| `docs/workflow.md` | 編碼正常（已檢查） | Updated in UTF-8; workflow now distinguishes missing setup from none and clarifies script-optional recall. | +| `examples/protocol-project/AGENTS.md` | 編碼正常（已檢查） | Updated in UTF-8; example rules now include not_initialized and PII guidance. | +| `examples/protocol-project/README.md` | 編碼正常（已檢查） | Updated in UTF-8; recall feedback moved out of the minimum files list. | +| `examples/protocol-project/memory/impressions.jsonl` | 編碼正常（已檢查） | Updated in UTF-8; example cues now match protocol-first vs engine-first demo query. | +| `examples/protocol-project/memory/recall-feedback.jsonl` | 編碼正常（已檢查） | Updated in UTF-8; feedback matched_id now resolves to the active impression id. | +| `scripts/dejavu-scan-memory.mjs` | 編碼正常（已檢查） | Updated in UTF-8; missing impression file now returns not_initialized with bootstrap hint. | +| `scripts/deja-vu.mjs` | 編碼正常（新建，UTF-8） | New unified optional CLI for init, doctor, and explain. | +| `tests/memory-cli.test.ts` | 編碼正常（已檢查） | Updated in UTF-8; tests now cover not_initialized, unified CLI init/doctor/explain, and readonly source test split. | +| `tests/package-pack.test.ts` | 編碼正常（新建，UTF-8） | New pack metadata test for unified CLI bins and starter-kit package inclusion. | +| `docs/comparison.md` | 編碼正常（新建，UTF-8） | New comparison doc contrasting Deja Vu with vector DB memory, hosted memory, runtimes, notes, and transcript archives. | +| `docs/agent-compatibility.md` | 編碼正常（新建，UTF-8） | New compatibility doc for file-aware and chat-only agents. | +| `docs/diagrams/deja-vu-flow.md` | 編碼正常（新建，UTF-8） | New Mermaid and ASCII recall flow diagram. | +| `docs/launch-copy.md` | 編碼正常（新建，UTF-8） | New launch copy doc with social posts, release intro, HN titles, and taglines. | +| `docs/demo-walkthrough.md` | 編碼正常（新建，UTF-8） | New before/after demo walkthrough and dogfooding guidance. | +| `docs/release-v0.6.0.md` | 編碼正常（新建，UTF-8） | New v0.6.0 candidate checklist. | +| `starter-kit/README.md` | 編碼正常（新建，UTF-8） | New copy-first starter kit README. | +| `starter-kit/AGENTS.md` | 編碼正常（新建，UTF-8） | New minimal Deja Vu project memory rules file. | +| `starter-kit/memory/summary.md` | 編碼正常（新建，UTF-8） | New starter project summary template. | +| `starter-kit/memory/impressions.jsonl` | 編碼正常（新建，UTF-8） | New starter impression cue route. | +| `starter-kit/memory/recall-feedback.jsonl` | 編碼正常（新建，UTF-8） | New optional empty recall feedback ledger. | +| `starter-kit/prompts/codex.md` | 編碼正常（新建，UTF-8） | New Codex startup prompt. | +| `starter-kit/prompts/claude-code.md` | 編碼正常（新建，UTF-8） | New Claude Code startup prompt. | +| `starter-kit/prompts/cursor.md` | 編碼正常（新建，UTF-8） | New Cursor startup prompt. | +| `starter-kit/prompts/windsurf.md` | 編碼正常（新建，UTF-8） | New Windsurf startup prompt. | +| `starter-kit/prompts/chatgpt.md` | 編碼正常（新建，UTF-8） | New ChatGPT manual-memory startup prompt. | +| `starter-kit/prompts/gemini-cli.md` | 編碼正常（新建，UTF-8） | New Gemini CLI startup prompt. | +| `package.json` | 編碼正常（已檢查） | Updated in UTF-8; clean script is now cross-platform for CI and pack verification. | +| `.github/workflows/ci.yml` | 編碼正常（新建，UTF-8） | New GitHub Actions workflow for source tests, memory checks, build, and pack verification. | +| `README.md` | 編碼正常（已檢查） | Updated in UTF-8; added public repo and doctor limitation safety note. | +| `starter-kit/README.md` | 編碼正常（已檢查） | Updated in UTF-8; added public repo and doctor limitation safety note. | + diff --git a/examples/protocol-project/AGENTS.md b/examples/protocol-project/AGENTS.md index 4ee3d04..3818a2c 100644 --- a/examples/protocol-project/AGENTS.md +++ b/examples/protocol-project/AGENTS.md @@ -13,12 +13,13 @@ This example shows the minimum Deja Vu protocol adoption path with no engine. Before substantial planning, coding, or answering: 1. Run `node ../../scripts/dejavu-scan-memory.mjs ""` when using this example from its own directory. -2. If the result is `none`, avoid memory reads by default. -3. If the result is `weak`, read `memory/summary.md`. -4. If the result is `strong`, open the linked detailed record. -5. If the script is unavailable, fall back to `memory/summary.md` and then `memory/index.md` when present. +2. If the result is `not_initialized`, create or ask for the three required files. +3. If the result is `none`, avoid memory reads by default. +4. If the result is `weak`, read `memory/summary.md`. +5. If the result is `strong`, open one to three linked detailed records. +6. If the script is unavailable, inspect `memory/impressions.jsonl` directly and apply the same budget. -6. Keep the scan output's budget fields visible before loading more memory. +7. Keep the scan output's budget fields visible before loading more memory. Recall budget: @@ -44,4 +45,5 @@ After meaningful work completes: - Do not store secrets. - Do not store full chat transcripts. +- Do not store customer or user PII. - Do not store low-value exploration noise. diff --git a/examples/protocol-project/README.md b/examples/protocol-project/README.md index 5c8553b..db9cb82 100644 --- a/examples/protocol-project/README.md +++ b/examples/protocol-project/README.md @@ -8,10 +8,9 @@ This example shows how to adopt Deja Vu without npm or the optional TypeScript e - `memory/summary.md` - `memory/impressions.jsonl` -- `memory/recall-feedback.jsonl` - ## Optional Scale-Up Files +- `memory/recall-feedback.jsonl` - `memory/index.md` - `memory/events/` - `memory/context/project-context.md` diff --git a/examples/protocol-project/memory/impressions.jsonl b/examples/protocol-project/memory/impressions.jsonl index a1b168e..6339616 100644 --- a/examples/protocol-project/memory/impressions.jsonl +++ b/examples/protocol-project/memory/impressions.jsonl @@ -1,2 +1,2 @@ -{"schema_version":1,"id":"decision-protocol-first-positioning","scope":"project:example-protocol-project","title":"Protocol-first positioning","keywords":["protocol","workflow","markdown","memory","positioning"],"aliases":["repo-first"],"record_path":"memory/decisions/protocol-first-positioning.md","updated":"2026-04-21","weight":0.9,"status":"active"} +{"schema_version":1,"id":"decision-protocol-first-positioning","scope":"project:example-protocol-project","title":"Protocol-first positioning","keywords":["protocol","workflow","markdown","memory","positioning","engine-first"],"aliases":["repo-first","protocol-first"],"record_path":"memory/decisions/protocol-first-positioning.md","updated":"2026-04-21","weight":0.9,"status":"active"} {"schema_version":1,"id":"open-loop-add-engine-later","scope":"project:example-protocol-project","title":"Decide when to add the optional engine","keywords":["engine","semantic","recall","threshold","optional"],"aliases":["typescript-engine"],"record_path":"memory/open-loops/add-engine-later.md","updated":"2026-04-21","weight":0.6,"status":"active"} diff --git a/examples/protocol-project/memory/recall-feedback.jsonl b/examples/protocol-project/memory/recall-feedback.jsonl index d3ab516..02fba12 100644 --- a/examples/protocol-project/memory/recall-feedback.jsonl +++ b/examples/protocol-project/memory/recall-feedback.jsonl @@ -1 +1 @@ -{"schema_version":1,"query":"Should the project stay protocol-first or engine-first?","matched_id":"decision-protocol-first","outcome":"helpful","created":"2026-04-24T12:00:00Z","note":"The decision record kept the example focused on repo-local protocol adoption."} +{"schema_version":1,"query":"protocol-first or engine-first positioning","matched_id":"decision-protocol-first-positioning","outcome":"helpful","created":"2026-04-24T12:00:00Z","note":"The decision record kept the example focused on repo-local protocol adoption."} diff --git a/llms.txt b/llms.txt index fa0b758..63e6717 100644 --- a/llms.txt +++ b/llms.txt @@ -1,6 +1,6 @@ # Deja Vu -> Ultra-light repo-local memory protocol for AI coding agents. +> A 3-file memory system for any capable AI coding agent. Deja Vu helps agents stop re-explaining the same repository context across new coding-agent chats through: @@ -10,18 +10,24 @@ Deja Vu helps agents stop re-explaining the same repository context across new c - 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 +- optional `deja-vu init`, `deja-vu doctor`, and `deja-vu explain` CLI support 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 - [README](./README.md): product overview and primary adoption path +- [Starter Kit](./starter-kit/README.md): copy-first three-file setup and per-agent prompts +- [Comparison](./docs/comparison.md): how Deja Vu differs from vector DBs, hosted memory, runtimes, notes, and transcripts +- [Agent Compatibility](./docs/agent-compatibility.md): which agents can follow the protocol and how chat-only agents can use it manually +- [Flow Diagram](./docs/diagrams/deja-vu-flow.md): cue scan, minimal recall, durable writeback +- [Demo Walkthrough](./docs/demo-walkthrough.md): before/after project memory example - [Protocol](./docs/protocol.md): normative protocol definition - [Workflow](./docs/workflow.md): recall, writeback, and compaction lifecycle - [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 +- [v0.6.0 Candidate](./docs/release-v0.6.0.md): adoption release checklist - [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 index a96bd64..e1468b0 100644 --- a/package-lock.json +++ b/package-lock.json @@ -9,6 +9,8 @@ "version": "0.5.0", "license": "MIT", "bin": { + "deja-vu": "scripts/deja-vu.mjs", + "deja-vu-feedback-report": "scripts/dejavu-feedback-report.mjs", "deja-vu-lint-memory": "scripts/dejavu-lint-memory.mjs", "deja-vu-scan-memory": "scripts/dejavu-scan-memory.mjs" }, diff --git a/package.json b/package.json index 7d15b7f..7b8f910 100644 --- a/package.json +++ b/package.json @@ -13,6 +13,7 @@ } }, "bin": { + "deja-vu": "scripts/deja-vu.mjs", "deja-vu-scan-memory": "scripts/dejavu-scan-memory.mjs", "deja-vu-lint-memory": "scripts/dejavu-lint-memory.mjs", "deja-vu-feedback-report": "scripts/dejavu-feedback-report.mjs" @@ -20,17 +21,20 @@ "files": [ "dist/src", "docs", + "starter-kit", "scripts", "README.md", "LICENSE" ], "scripts": { "build": "tsc -p tsconfig.json", - "clean": "if exist dist rmdir /s /q dist", + "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"", "prepack": "npm run clean && npm run build", "prepublishOnly": "npm test", - "test": "npm run clean && npm run build && node --test dist/tests/**/*.test.js", - "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", + "test": "npm run test:src:readonly && npm run build && node --test dist/tests/semantic-recall-engine.test.js dist/tests/memory-cli.test.js && npm run test:pack", + "test:src": "npm run test:src:readonly", + "test:src:readonly": "node --import \"data:text/javascript,import { register } from 'node:module'; import { pathToFileURL } from 'node:url'; register('ts-node/esm', pathToFileURL('./'));\" --test tests/semantic-recall-engine.test.ts tests/memory-cli.test.ts", + "test:pack": "node --import \"data:text/javascript,import { register } from 'node:module'; import { pathToFileURL } from 'node:url'; register('ts-node/esm', pathToFileURL('./'));\" --test tests/package-pack.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", diff --git a/scripts/deja-vu.mjs b/scripts/deja-vu.mjs new file mode 100644 index 0000000..de0dda6 --- /dev/null +++ b/scripts/deja-vu.mjs @@ -0,0 +1,386 @@ +#!/usr/bin/env node +import { + existsSync, + mkdirSync, + readFileSync, + readdirSync, + statSync, + writeFileSync, +} from "node:fs"; +import { basename, dirname, join, relative, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), ".."); +const starterRoot = resolve(packageRoot, "starter-kit"); +const knownAgents = new Set(["codex", "claude-code", "cursor", "windsurf", "chatgpt", "gemini-cli"]); + +const args = process.argv.slice(2); +const command = args[0] ?? "help"; +const commandArgs = args.slice(1); + +function parseOptions(values) { + const positional = []; + const options = {}; + for (let index = 0; index < values.length; index += 1) { + const value = values[index]; + if (!value.startsWith("--")) { + positional.push(value); + continue; + } + const [rawKey, inlineValue] = value.slice(2).split("=", 2); + const key = rawKey.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase()); + if (inlineValue !== undefined) { + options[key] = inlineValue; + continue; + } + const next = values[index + 1]; + if (next && !next.startsWith("--")) { + options[key] = next; + index += 1; + } else { + options[key] = true; + } + } + return { positional, options }; +} + +function asBoolean(value) { + return value === true || value === "true"; +} + +function slugifyProjectId(value) { + const raw = value.replace(/^project:/, ""); + const slug = raw + .trim() + .toLowerCase() + .replace(/[^a-z0-9._-]+/g, "-") + .replace(/^-+|-+$/g, ""); + return `project:${slug || "project"}`; +} + +function today() { + return new Date().toISOString().slice(0, 10); +} + +function readStarter(path) { + return readFileSync(resolve(starterRoot, path), "utf8"); +} + +function materializeTemplate(text, projectId) { + return text.replaceAll("project:your-project", projectId).replaceAll("2026-05-16", today()); +} + +function getAgents(value) { + if (!value) return []; + const names = String(value) + .split(",") + .map((item) => item.trim()) + .filter(Boolean); + if (names.includes("all")) return [...knownAgents]; + const invalid = names.filter((name) => !knownAgents.has(name)); + if (invalid.length > 0) { + throw new Error(`Unknown agent: ${invalid.join(", ")}`); + } + return names; +} + +function print(data, json) { + if (json) { + console.log(JSON.stringify(data, null, 2)); + return; + } + if (typeof data === "string") { + console.log(data); + return; + } + console.log(JSON.stringify(data, null, 2)); +} + +function writePlannedFile(plan, targetPath, content, { force, dryRun }) { + const exists = existsSync(targetPath); + const operation = exists ? (force ? "overwrite" : "skip") : "create"; + plan.push({ operation, path: targetPath }); + if (dryRun || operation === "skip") return; + mkdirSync(dirname(targetPath), { recursive: true }); + writeFileSync(targetPath, content, "utf8"); +} + +function initCommand(values) { + const { options } = parseOptions(values); + const cwd = resolve(process.cwd(), String(options.cwd ?? ".")); + const dryRun = asBoolean(options.dryRun); + const force = asBoolean(options.force); + const json = asBoolean(options.json); + const projectId = slugifyProjectId(String(options.projectId ?? options.scope ?? basename(cwd))); + const agents = getAgents(options.agents ?? options.agent); + const plan = []; + + writePlannedFile(plan, resolve(cwd, "AGENTS.md"), materializeTemplate(readStarter("AGENTS.md"), projectId), { + dryRun, + force, + }); + writePlannedFile( + plan, + resolve(cwd, "memory", "summary.md"), + materializeTemplate(readStarter(join("memory", "summary.md")), projectId), + { dryRun, force }, + ); + writePlannedFile( + plan, + resolve(cwd, "memory", "impressions.jsonl"), + materializeTemplate(readStarter(join("memory", "impressions.jsonl")), projectId), + { dryRun, force }, + ); + + for (const agent of agents) { + writePlannedFile( + plan, + resolve(cwd, "prompts", `${agent}.md`), + readStarter(join("prompts", `${agent}.md`)), + { dryRun, force }, + ); + } + + const prompt = [ + "Follow AGENTS.md.", + "Before substantial planning or code changes, scan memory/impressions.jsonl for familiar cues.", + "If familiarity is weak, read memory/summary.md.", + "If familiarity is strong, read only the 1-3 linked detailed records needed for this task.", + "Do not load the whole memory tree unless I ask.", + "After the task, write back only durable memory.", + ].join(" "); + + if (json) { + print({ ok: true, dry_run: dryRun, project_id: projectId, agents, operations: plan, next_prompt: prompt }, true); + return; + } + + const lines = [ + dryRun ? "Deja Vu init dry run:" : "Deja Vu init complete:", + ...plan.map((item) => `- ${item.operation}: ${relative(cwd, item.path)}`), + "", + "Next agent prompt:", + prompt, + ]; + print(lines.join("\n"), false); +} + +function addDiagnostic(diagnostics, level, message, details = {}) { + diagnostics.push({ level, message, ...details }); +} + +function listFiles(root) { + if (!existsSync(root)) return []; + const files = []; + for (const entry of readdirSync(root)) { + const fullPath = resolve(root, entry); + const stat = statSync(fullPath); + if (stat.isDirectory()) { + files.push(...listFiles(fullPath)); + } else { + files.push(fullPath); + } + } + return files; +} + +function parseJsonl(filePath, diagnostics, kind) { + const records = []; + if (!existsSync(filePath)) return records; + for (const [index, line] of readFileSync(filePath, "utf8").split(/\r?\n/).entries()) { + const trimmed = line.trim(); + if (!trimmed) continue; + try { + records.push({ record: JSON.parse(trimmed), line: index + 1 }); + } catch (error) { + addDiagnostic(diagnostics, "error", `Invalid ${kind} JSONL record`, { + path: filePath, + line: index + 1, + error: error instanceof Error ? error.message : String(error), + }); + } + } + return records; +} + +function scanTextSafety(filePath, text, diagnostics) { + const checks = [ + { level: "error", message: "Possible private key in memory", pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ }, + { level: "error", message: "Possible OpenAI-style secret key in memory", pattern: /\bsk-[A-Za-z0-9_-]{20,}\b/ }, + { level: "error", message: "Possible GitHub token in memory", pattern: /\b(?:ghp|github_pat)_[A-Za-z0-9_]{20,}\b/ }, + { level: "error", message: "Possible AWS access key in memory", pattern: /\bAKIA[0-9A-Z]{16}\b/ }, + { level: "warning", message: "Possible email address in memory", pattern: /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i }, + { level: "warning", message: "Memory looks like a transcript; summarize durable signal instead", pattern: /^(user|assistant|system):/im }, + { level: "warning", message: "Memory contains subagent transcript markup", pattern: // }, + { level: "warning", message: "Memory looks like raw build or debug output", pattern: /\b(?:stack trace|traceback|npm ERR!|at .+:\d+:\d+)\b/i }, + { + level: "error", + message: "Possible credential assignment in memory", + pattern: /\b(?:api[_-]?key|secret|token|password)\s*[:=]\s*["']?[A-Za-z0-9._~+/=-]{16,}/i, + }, + ]; + + for (const check of checks) { + if (check.pattern.test(text)) { + addDiagnostic(diagnostics, check.level, check.message, { path: filePath }); + } + } + + if (text.length > 20000) { + addDiagnostic(diagnostics, "warning", "Memory file is large; consider compacting durable signal", { + path: filePath, + characters: text.length, + }); + } +} + +function doctorCommand(values) { + const { options } = parseOptions(values); + const cwd = resolve(process.cwd(), String(options.cwd ?? ".")); + const memoryRoot = resolve(cwd, String(options.memoryRoot ?? "memory")); + const json = asBoolean(options.json); + const diagnostics = []; + + const agentsPath = resolve(cwd, "AGENTS.md"); + const summaryPath = resolve(memoryRoot, "summary.md"); + const impressionsPath = resolve(memoryRoot, "impressions.jsonl"); + const feedbackPath = resolve(memoryRoot, "recall-feedback.jsonl"); + + if (!existsSync(agentsPath)) { + addDiagnostic(diagnostics, "error", "Missing AGENTS.md", { path: agentsPath }); + } + if (!existsSync(summaryPath)) { + addDiagnostic(diagnostics, "error", "Missing memory/summary.md", { path: summaryPath }); + } + if (!existsSync(impressionsPath)) { + addDiagnostic(diagnostics, "error", "Missing memory/impressions.jsonl", { path: impressionsPath }); + } + + const impressionEntries = parseJsonl(impressionsPath, diagnostics, "impression"); + const impressionIds = new Set(); + for (const { record, line } of impressionEntries) { + for (const field of ["id", "scope", "title", "record_path", "updated"]) { + if (typeof record[field] !== "string" || record[field].trim() === "") { + addDiagnostic(diagnostics, "error", `Impression missing ${field}`, { path: impressionsPath, line }); + } + } + if (!Array.isArray(record.keywords) || record.keywords.length === 0) { + addDiagnostic(diagnostics, "error", "Impression keywords must be a non-empty array", { + path: impressionsPath, + line, + id: record.id, + }); + } + if (record.id && (!record.status || record.status === "active")) impressionIds.add(record.id); + } + + const feedbackEntries = parseJsonl(feedbackPath, diagnostics, "feedback"); + for (const { record, line } of feedbackEntries) { + if (record.matched_id && record.matched_id !== "unmatched" && !impressionIds.has(record.matched_id)) { + addDiagnostic(diagnostics, "warning", "Feedback matched_id does not resolve to an active impression", { + path: feedbackPath, + line, + matched_id: record.matched_id, + }); + } + if (typeof record.query === "string" && record.query.length > 240) { + addDiagnostic(diagnostics, "warning", "Feedback query is long; store sanitized cues, not raw prompts", { + path: feedbackPath, + line, + }); + } + } + + if (existsSync(summaryPath) && readFileSync(summaryPath, "utf8").length > 12000) { + addDiagnostic(diagnostics, "warning", "memory/summary.md is large; keep summary compact", { path: summaryPath }); + } + + for (const filePath of [agentsPath, ...listFiles(memoryRoot)].filter((path) => existsSync(path))) { + if (/\.(md|jsonl|txt)$/i.test(filePath)) { + scanTextSafety(filePath, readFileSync(filePath, "utf8"), diagnostics); + } + } + + const errorCount = diagnostics.filter((item) => item.level === "error").length; + const warningCount = diagnostics.filter((item) => item.level === "warning").length; + const result = { + ok: errorCount === 0, + error_count: errorCount, + warning_count: warningCount, + diagnostics, + recommendations: [ + "Keep the required three files present: AGENTS.md, memory/summary.md, memory/impressions.jsonl.", + "Track only sanitized memory intended for the repo.", + "Ignore private/local/raw/transcript memory folders if you create them.", + "Run doctor before sharing or publishing a repo with Deja Vu memory.", + ], + }; + + if (json) { + print(result, true); + } else { + const lines = [`Deja Vu doctor: ${result.ok ? "ok" : "needs attention"}`]; + for (const item of diagnostics) { + lines.push(`- ${item.level}: ${item.message}${item.path ? ` (${relative(cwd, item.path)})` : ""}`); + } + if (diagnostics.length === 0) lines.push("- no issues found"); + lines.push("", "Recommendations:", ...result.recommendations.map((item) => `- ${item}`)); + print(lines.join("\n"), false); + } + + process.exitCode = errorCount === 0 ? 0 : 1; +} + +function explainCommand(values) { + const { options } = parseOptions(values); + const json = asBoolean(options.json); + const text = + "Deja Vu is a 3-file, repo-local memory system for AI coding agents. " + + "Use AGENTS.md for rules, memory/summary.md for durable project context, and memory/impressions.jsonl for tiny recall cues. " + + "Before substantial work, scan cues first; load the summary only for weak familiarity; load 1-3 linked records for strong familiarity; write back only durable memory. " + + "No database, vector store, embeddings, SaaS, daemon, or npm install is required."; + if (json) { + print({ explanation: text }, true); + return; + } + print(text, false); +} + +function help() { + print( + [ + "Usage: deja-vu [options]", + "", + "Commands:", + " init Create the three-file Deja Vu starter setup", + " doctor Check Deja Vu memory health and safety", + " explain Print a short explanation to paste into an agent chat", + "", + "Examples:", + " deja-vu init --dry-run", + " deja-vu init --agents codex,claude-code", + " deja-vu doctor --json", + " deja-vu explain", + ].join("\n"), + false, + ); +} + +try { + if (command === "init") { + initCommand(commandArgs); + } else if (command === "doctor") { + doctorCommand(commandArgs); + } else if (command === "explain") { + explainCommand(commandArgs); + } else if (command === "help" || command === "--help" || command === "-h") { + help(); + } else { + console.error(`Unknown command: ${command}`); + help(); + process.exitCode = 2; + } +} catch (error) { + console.error(error instanceof Error ? error.message : String(error)); + process.exitCode = 1; +} diff --git a/scripts/dejavu-scan-memory.mjs b/scripts/dejavu-scan-memory.mjs index ed820cc..ced4ea4 100644 --- a/scripts/dejavu-scan-memory.mjs +++ b/scripts/dejavu-scan-memory.mjs @@ -56,7 +56,36 @@ if (!query) { } if (!existsSync(memoryPath)) { - console.log(JSON.stringify({ matched: false, level: "none", score: 0, matches: [] }, null, 2)); + console.log( + JSON.stringify( + { + matched: false, + level: "not_initialized", + score: 0, + matches: [], + budget: { + impression_scan: 0, + summaries_loaded: 0, + detail_records_loaded: 0, + why_loaded: ["memory/impressions.jsonl was not found"], + }, + diagnostics: [ + { + id: "missing-impressions", + level: "error", + message: "Deja Vu memory is not initialized", + path: memoryPath, + }, + ], + bootstrap_hint: { + required_files: ["AGENTS.md", "memory/summary.md", "memory/impressions.jsonl"], + next_step: "copy starter-kit/. into the repo or run deja-vu init", + }, + }, + null, + 2, + ), + ); process.exit(0); } diff --git a/starter-kit/AGENTS.md b/starter-kit/AGENTS.md new file mode 100644 index 0000000..4c81dbb --- /dev/null +++ b/starter-kit/AGENTS.md @@ -0,0 +1,55 @@ +# Deja Vu Project Memory Rules + +## Memory Identity + +- Protocol: Deja Vu Protocol v0.4 +- Scope: `project:your-project` +- Memory root: `memory/` + +Replace `project:your-project` with a stable repo-local project id. + +## Recall Before Substantial Work + +Before substantial planning, coding, refactoring, debugging, or architecture discussion: + +1. Inspect `memory/impressions.jsonl` for familiar cues. +2. If there is no familiarity, do not load memory by default. +3. If familiarity is weak, read `memory/summary.md`. +4. If familiarity is strong, read only the 1-3 linked detailed records needed for the task. +5. Do not load the whole memory tree unless the user explicitly asks. + +Default budget: + +- impression scan: always allowed +- summary: at most one file +- detailed records: one to three files +- full memory tree: forbidden unless explicitly requested + +## Durable Writeback Only + +After meaningful work, write back only memory that should change future agent behavior: + +- accepted decisions +- architecture intent +- stable preferences +- unresolved follow-ups +- milestone summaries +- recall feedback that should improve future cue quality + +Route durable writeback: + +- project-level truth -> `memory/summary.md` plus `memory/impressions.jsonl` +- accepted decision -> `memory/decisions/` plus `memory/impressions.jsonl` +- unresolved follow-up -> `memory/open-loops/` plus `memory/impressions.jsonl` +- recall quality signal -> `memory/recall-feedback.jsonl` + +## Never Store + +- secrets, tokens, credentials, or private keys +- full chat transcripts +- customer or user PII +- low-signal chatter +- disposable exploration noise +- raw debug logs or build output + +Memory should feel like recognition, not replay. diff --git a/starter-kit/README.md b/starter-kit/README.md new file mode 100644 index 0000000..9b7e2a0 --- /dev/null +++ b/starter-kit/README.md @@ -0,0 +1,38 @@ +# Deja Vu Starter Kit + +Copy this folder into any repo root to add Deja Vu project memory. + +```bash +cp -R starter-kit/. . +``` + +The minimum useful setup is three files: + +- `AGENTS.md` +- `memory/summary.md` +- `memory/impressions.jsonl` + +This starter kit also includes optional empty scale-up surfaces: + +- `memory/recall-feedback.jsonl` +- `memory/decisions/` +- `memory/open-loops/` +- `prompts/` + +Use the optional files only when they help future agents recall less, better. + +## First Agent Prompt + +Paste one prompt from `prompts/` into your agent session, then ask for real work. + +The agent should: + +1. read `AGENTS.md` +2. scan `memory/impressions.jsonl` +3. read `memory/summary.md` only when useful +4. read at most 1-3 detailed records for strong matches +5. write back only durable memory + +Do not store secrets, API keys, PII, full transcripts, or low-value chatter. + +If this is a public repo, memory files can be committed and shared like any other project file. Run `deja-vu doctor` when available, but still review memory manually because doctor only catches obvious sensitive content. diff --git a/starter-kit/memory/decisions/.gitkeep b/starter-kit/memory/decisions/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/starter-kit/memory/decisions/.gitkeep @@ -0,0 +1 @@ + diff --git a/starter-kit/memory/impressions.jsonl b/starter-kit/memory/impressions.jsonl new file mode 100644 index 0000000..4bf3074 --- /dev/null +++ b/starter-kit/memory/impressions.jsonl @@ -0,0 +1 @@ +{"schema_version":1,"id":"summary","scope":"project:your-project","title":"Project summary","keywords":["project","summary","objective","constraints","priorities"],"aliases":["overview"],"record_path":"memory/summary.md","updated":"2026-05-16","weight":0.7,"status":"active"} diff --git a/starter-kit/memory/open-loops/.gitkeep b/starter-kit/memory/open-loops/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/starter-kit/memory/open-loops/.gitkeep @@ -0,0 +1 @@ + diff --git a/starter-kit/memory/recall-feedback.jsonl b/starter-kit/memory/recall-feedback.jsonl new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/starter-kit/memory/recall-feedback.jsonl @@ -0,0 +1 @@ + diff --git a/starter-kit/memory/summary.md b/starter-kit/memory/summary.md new file mode 100644 index 0000000..8e9a871 --- /dev/null +++ b/starter-kit/memory/summary.md @@ -0,0 +1,40 @@ +--- +id: summary +title: Project Summary +status: active +scope: project:your-project +updated: 2026-05-16 +--- + +# Project Summary + +Keep this file short. It should capture durable project truth, not chat history. + +## Project identity + +Describe what this repo is and who it serves in two or three sentences. + +## Current objective + +Describe the current product or engineering objective. + +## Stable constraints + +- Add constraints that future agents must preserve. +- Keep only durable constraints. + +## Active priorities + +- Add current priorities that should survive a new chat. + +## Current decisions + +- Link decision records only when they exist. + +## Open loops + +- Link unresolved follow-up records only when they exist. + +## Safety boundary + +Do not store secrets, PII, full transcripts, raw logs, or low-signal notes here. diff --git a/starter-kit/prompts/chatgpt.md b/starter-kit/prompts/chatgpt.md new file mode 100644 index 0000000..15356c9 --- /dev/null +++ b/starter-kit/prompts/chatgpt.md @@ -0,0 +1,11 @@ +# ChatGPT Prompt + +Follow the Deja Vu rules below for this repo. + +Read `AGENTS.md` when available. Before substantial planning or code changes, ask me for `memory/impressions.jsonl` or inspect it if you can access repo files. If familiarity is weak, use `memory/summary.md`. If familiarity is strong, use only the 1-3 linked detailed records needed for this task. + +Do not ask for the whole memory tree unless it is necessary and I explicitly approve it. + +After the task, suggest writeback only for durable decisions, architecture intent, stable preferences, unresolved follow-ups, milestone summaries, or recall feedback that should improve future cue quality. + +Never store secrets, full transcripts, customer/user PII, low-signal chatter, raw logs, or disposable exploration noise. diff --git a/starter-kit/prompts/claude-code.md b/starter-kit/prompts/claude-code.md new file mode 100644 index 0000000..05e1405 --- /dev/null +++ b/starter-kit/prompts/claude-code.md @@ -0,0 +1,11 @@ +# Claude Code Prompt + +Follow `AGENTS.md` for this repo. + +Before substantial planning or code changes, scan `memory/impressions.jsonl` for familiar cues. If familiarity is weak, read `memory/summary.md`. If familiarity is strong, read only the 1-3 linked detailed records needed for this task. + +Do not load the whole memory tree unless I explicitly ask. + +After the task, write back only durable decisions, architecture intent, stable preferences, unresolved follow-ups, milestone summaries, or recall feedback that should improve future cue quality. + +Never store secrets, full transcripts, customer/user PII, low-signal chatter, raw logs, or disposable exploration noise. diff --git a/starter-kit/prompts/codex.md b/starter-kit/prompts/codex.md new file mode 100644 index 0000000..ce64812 --- /dev/null +++ b/starter-kit/prompts/codex.md @@ -0,0 +1,11 @@ +# Codex Prompt + +Follow `AGENTS.md` for this repo. + +Before substantial planning or code changes, scan `memory/impressions.jsonl` for familiar cues. If familiarity is weak, read `memory/summary.md`. If familiarity is strong, read only the 1-3 linked detailed records needed for this task. + +Do not load the whole memory tree unless I explicitly ask. + +After the task, write back only durable decisions, architecture intent, stable preferences, unresolved follow-ups, milestone summaries, or recall feedback that should improve future cue quality. + +Never store secrets, full transcripts, customer/user PII, low-signal chatter, raw logs, or disposable exploration noise. diff --git a/starter-kit/prompts/cursor.md b/starter-kit/prompts/cursor.md new file mode 100644 index 0000000..7a21896 --- /dev/null +++ b/starter-kit/prompts/cursor.md @@ -0,0 +1,11 @@ +# Cursor Prompt + +Follow `AGENTS.md` for this repo. + +Before substantial planning or code changes, scan `memory/impressions.jsonl` for familiar cues. If familiarity is weak, read `memory/summary.md`. If familiarity is strong, read only the 1-3 linked detailed records needed for this task. + +Do not load the whole memory tree unless I explicitly ask. + +After the task, write back only durable decisions, architecture intent, stable preferences, unresolved follow-ups, milestone summaries, or recall feedback that should improve future cue quality. + +Never store secrets, full transcripts, customer/user PII, low-signal chatter, raw logs, or disposable exploration noise. diff --git a/starter-kit/prompts/gemini-cli.md b/starter-kit/prompts/gemini-cli.md new file mode 100644 index 0000000..8c9348d --- /dev/null +++ b/starter-kit/prompts/gemini-cli.md @@ -0,0 +1,11 @@ +# Gemini CLI Prompt + +Follow `AGENTS.md` for this repo. + +Before substantial planning or code changes, scan `memory/impressions.jsonl` for familiar cues. If familiarity is weak, read `memory/summary.md`. If familiarity is strong, read only the 1-3 linked detailed records needed for this task. + +Do not load the whole memory tree unless I explicitly ask. + +After the task, write back only durable decisions, architecture intent, stable preferences, unresolved follow-ups, milestone summaries, or recall feedback that should improve future cue quality. + +Never store secrets, full transcripts, customer/user PII, low-signal chatter, raw logs, or disposable exploration noise. diff --git a/starter-kit/prompts/windsurf.md b/starter-kit/prompts/windsurf.md new file mode 100644 index 0000000..e237f20 --- /dev/null +++ b/starter-kit/prompts/windsurf.md @@ -0,0 +1,11 @@ +# Windsurf Prompt + +Follow `AGENTS.md` for this repo. + +Before substantial planning or code changes, scan `memory/impressions.jsonl` for familiar cues. If familiarity is weak, read `memory/summary.md`. If familiarity is strong, read only the 1-3 linked detailed records needed for this task. + +Do not load the whole memory tree unless I explicitly ask. + +After the task, write back only durable decisions, architecture intent, stable preferences, unresolved follow-ups, milestone summaries, or recall feedback that should improve future cue quality. + +Never store secrets, full transcripts, customer/user PII, low-signal chatter, raw logs, or disposable exploration noise. diff --git a/tests/memory-cli.test.ts b/tests/memory-cli.test.ts index abc2757..d088378 100644 --- a/tests/memory-cli.test.ts +++ b/tests/memory-cli.test.ts @@ -1,11 +1,12 @@ import test from "node:test"; import assert from "node:assert/strict"; -import { execFileSync, execSync } from "node:child_process"; -import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs"; +import { execFileSync } from "node:child_process"; +import { existsSync, mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; const root = process.cwd(); +const unifiedCli = join(root, "scripts", "deja-vu.mjs"); const scanScript = join(root, "scripts", "dejavu-scan-memory.mjs"); const lintScript = join(root, "scripts", "dejavu-lint-memory.mjs"); const feedbackReportScript = join(root, "scripts", "dejavu-feedback-report.mjs"); @@ -25,6 +26,14 @@ function runJsonAllowFailure(script: string, args: string[], cwd: string) { } } +function runCliJson(args: string[], cwd: string) { + return runJson(unifiedCli, [...args, "--json"], cwd); +} + +function runCliJsonAllowFailure(args: string[], cwd: string) { + return runJsonAllowFailure(unifiedCli, [...args, "--json"], cwd); +} + test("scan CLI reports unmatched when overlap stays below threshold", () => { const project = mkdtempSync(join(tmpdir(), "dejavu-scan-")); const memory = join(project, "memory"); @@ -58,6 +67,17 @@ test("scan CLI reports unmatched when overlap stays below threshold", () => { assert.ok(result.writeback_hint.after_work.includes("durable decision -> memory/decisions/ + memory/impressions.jsonl")); }); +test("scan CLI distinguishes missing setup from no familiarity", () => { + const project = mkdtempSync(join(tmpdir(), "dejavu-scan-missing-")); + + const result = runJson(scanScript, ["settings refactor"], project); + + assert.equal(result.level, "not_initialized"); + assert.equal(result.matched, false); + assert.equal(result.budget.impression_scan, 0); + assert.equal(result.bootstrap_hint.required_files.length, 3); +}); + test("lint CLI validates impression records and linked paths", () => { const project = mkdtempSync(join(tmpdir(), "dejavu-lint-")); const memory = join(project, "memory"); @@ -310,12 +330,90 @@ test("feedback report summarizes recall outcomes into maintenance suggestions", assert.ok(result.routes.some((route: { matched_id: string; suggestions: string[] }) => route.matched_id === "unmatched" && route.suggestions.includes("add aliases, keywords, or a new impression route"))); }); -test("package metadata exposes memory CLI binaries", () => { - const result = JSON.parse(execSync("npm pack --dry-run --json", { cwd: root, encoding: "utf8" })); - const files = new Set(result[0].files.map((file: { path: string }) => file.path)); +test("unified CLI init dry-run does not create files", () => { + const project = mkdtempSync(join(tmpdir(), "dejavu-init-dry-")); + + const result = runCliJson(["init", "--dry-run", "--project-id", "project:dry-run", "--agents", "codex"], project); + + assert.equal(result.ok, true); + assert.equal(result.dry_run, true); + assert.equal(result.project_id, "project:dry-run"); + assert.ok(result.operations.some((item: { operation: string; path: string }) => item.operation === "create" && item.path.endsWith("AGENTS.md"))); + assert.equal(existsSync(join(project, "AGENTS.md")), false); + assert.equal(existsSync(join(project, "memory", "summary.md")), false); + assert.equal(existsSync(join(project, "prompts", "codex.md")), false); +}); + +test("unified CLI init creates missing files without overwriting existing files", () => { + const project = mkdtempSync(join(tmpdir(), "dejavu-init-")); + writeFileSync(join(project, "AGENTS.md"), "# Existing rules\n", "utf8"); + + const result = runCliJson(["init", "--project-id", "project:sample", "--agents", "codex"], project); + + assert.equal(result.ok, true); + assert.ok(result.operations.some((item: { operation: string; path: string }) => item.operation === "skip" && item.path.endsWith("AGENTS.md"))); + assert.equal(readFileSync(join(project, "AGENTS.md"), "utf8"), "# Existing rules\n"); + assert.ok(readFileSync(join(project, "memory", "summary.md"), "utf8").includes("scope: project:sample")); + assert.ok(readFileSync(join(project, "memory", "impressions.jsonl"), "utf8").includes('"scope":"project:sample"')); + assert.equal(existsSync(join(project, "prompts", "codex.md")), true); +}); + +test("unified CLI doctor reports missing required files", () => { + const project = mkdtempSync(join(tmpdir(), "dejavu-doctor-missing-")); + + const result = runCliJsonAllowFailure(["doctor"], project); + + assert.equal(result.ok, false); + assert.equal(result.error_count, 3); + assert.ok(result.diagnostics.some((item: { message: string }) => item.message === "Missing AGENTS.md")); + assert.ok(result.diagnostics.some((item: { message: string }) => item.message === "Missing memory/summary.md")); + assert.ok(result.diagnostics.some((item: { message: string }) => item.message === "Missing memory/impressions.jsonl")); +}); + +test("unified CLI doctor catches unresolved feedback and obvious secrets", () => { + const project = mkdtempSync(join(tmpdir(), "dejavu-doctor-risk-")); + const memory = join(project, "memory"); + mkdirSync(memory); + writeFileSync(join(project, "AGENTS.md"), "# Rules\n", "utf8"); + writeFileSync(join(memory, "summary.md"), "# Summary\npassword = abcdefghijklmnopqrstuvwxyz\n", "utf8"); + writeFileSync( + join(memory, "impressions.jsonl"), + `${JSON.stringify({ + schema_version: 1, + id: "summary", + scope: "project:test", + title: "Summary", + keywords: ["summary", "project", "constraints"], + record_path: "memory/summary.md", + updated: "2026-05-16", + status: "active", + })}\n`, + "utf8", + ); + writeFileSync( + join(memory, "recall-feedback.jsonl"), + `${JSON.stringify({ + schema_version: 1, + query: "missing feedback route", + matched_id: "does-not-exist", + outcome: "helpful", + created: "2026-05-16T00:00:00Z", + })}\n`, + "utf8", + ); + + const result = runCliJsonAllowFailure(["doctor"], project); + const messages = result.diagnostics.map((item: { message: string }) => item.message); + + assert.equal(result.ok, false); + assert.ok(messages.includes("Feedback matched_id does not resolve to an active impression")); + assert.ok(messages.includes("Possible credential assignment in memory")); +}); + +test("unified CLI explain returns short protocol copy", () => { + const project = mkdtempSync(join(tmpdir(), "dejavu-explain-")); + const result = runCliJson(["explain"], project); - assert.equal(result[0].name, "@focaxisdev/deja-vu"); - assert.ok(files.has("scripts/dejavu-scan-memory.mjs")); - assert.ok(files.has("scripts/dejavu-lint-memory.mjs")); - assert.ok(files.has("scripts/dejavu-feedback-report.mjs")); + assert.ok(result.explanation.includes("3-file")); + assert.ok(result.explanation.includes("AGENTS.md")); }); diff --git a/tests/package-pack.test.ts b/tests/package-pack.test.ts new file mode 100644 index 0000000..febaa00 --- /dev/null +++ b/tests/package-pack.test.ts @@ -0,0 +1,20 @@ +import test from "node:test"; +import assert from "node:assert/strict"; +import { execSync } from "node:child_process"; + +const root = process.cwd(); + +test("package metadata exposes memory CLI binaries and starter kit", () => { + const result = JSON.parse(execSync("npm pack --dry-run --json", { cwd: root, encoding: "utf8" })); + const files = new Set(result[0].files.map((file: { path: string }) => file.path)); + + assert.equal(result[0].name, "@focaxisdev/deja-vu"); + assert.ok(files.has("scripts/deja-vu.mjs")); + assert.ok(files.has("scripts/dejavu-scan-memory.mjs")); + assert.ok(files.has("scripts/dejavu-lint-memory.mjs")); + assert.ok(files.has("scripts/dejavu-feedback-report.mjs")); + assert.ok(files.has("starter-kit/AGENTS.md")); + assert.ok(files.has("starter-kit/memory/summary.md")); + assert.ok(files.has("starter-kit/memory/impressions.jsonl")); + assert.ok(files.has("starter-kit/prompts/codex.md")); +}); From 991abc98f8ca0c9b55633483d9a9d096eec5a4d2 Mon Sep 17 00:00:00 2001 From: Focaxis Dev Date: Sun, 17 May 2026 08:37:23 +0800 Subject: [PATCH 2/3] chore: dogfood Deja Vu project memory --- AGENTS.md | 30 ++++++++++++++++++++++++ encoding-status.md | 5 +++- memory/decisions/.gitkeep | 1 + memory/impressions.jsonl | 6 +++++ memory/open-loops/.gitkeep | 1 + memory/recall-feedback.jsonl | 1 + memory/summary.md | 45 ++++++++++++++++++++++++++++++++++++ 7 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md create mode 100644 memory/decisions/.gitkeep create mode 100644 memory/impressions.jsonl create mode 100644 memory/open-loops/.gitkeep create mode 100644 memory/recall-feedback.jsonl create mode 100644 memory/summary.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..61d0cb9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,30 @@ +# Deja Vu Project Memory Rules + +## Memory Identity + +- Protocol: Deja Vu Protocol v0.4 +- Scope: `project:deja-vu` +- Memory root: `memory/` + +## Recall Before Substantial Work + +Before substantial planning, coding, release preparation, or documentation changes: + +1. Inspect `memory/impressions.jsonl` for familiar cues. +2. If there is no familiarity, do not load memory by default. +3. If familiarity is weak, read `memory/summary.md`. +4. If familiarity is strong, read only the 1-3 linked records needed for the task. +5. Do not load the whole memory tree unless the user explicitly asks. + +## Durable Writeback Only + +Write back only durable project memory: + +- accepted product positioning +- protocol or starter-kit decisions +- CLI scope decisions +- release readiness notes +- unresolved follow-ups +- safety or privacy constraints + +Never store secrets, full transcripts, PII, raw logs, low-signal chatter, or disposable exploration noise. diff --git a/encoding-status.md b/encoding-status.md index 6b6d418..482d856 100644 --- a/encoding-status.md +++ b/encoding-status.md @@ -124,6 +124,9 @@ | `starter-kit/prompts/gemini-cli.md` | 編碼正常（新建，UTF-8） | New Gemini CLI startup prompt. | | `package.json` | 編碼正常（已檢查） | Updated in UTF-8; clean script is now cross-platform for CI and pack verification. | | `.github/workflows/ci.yml` | 編碼正常（新建，UTF-8） | New GitHub Actions workflow for source tests, memory checks, build, and pack verification. | +| `AGENTS.md` | 編碼正常（新建，UTF-8） | New repo-root dogfood Deja Vu project memory rules. | +| `memory/summary.md` | 編碼正常（新建，UTF-8） | New repo-root dogfood project summary with stable v0.6.0 positioning and boundaries. | +| `memory/impressions.jsonl` | 編碼正常（新建，UTF-8） | New repo-root dogfood impression cues for positioning, starter kit, protocol/engine boundary, CLI scope, safety, and release readiness. | +| `memory/recall-feedback.jsonl` | 編碼正常（新建，UTF-8） | New empty repo-root dogfood recall feedback ledger. | | `README.md` | 編碼正常（已檢查） | Updated in UTF-8; added public repo and doctor limitation safety note. | | `starter-kit/README.md` | 編碼正常（已檢查） | Updated in UTF-8; added public repo and doctor limitation safety note. | - diff --git a/memory/decisions/.gitkeep b/memory/decisions/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/memory/decisions/.gitkeep @@ -0,0 +1 @@ + diff --git a/memory/impressions.jsonl b/memory/impressions.jsonl new file mode 100644 index 0000000..2f53f39 --- /dev/null +++ b/memory/impressions.jsonl @@ -0,0 +1,6 @@ +{"schema_version":1,"id":"positioning-three-file-memory","scope":"project:deja-vu","title":"Three-file memory positioning","keywords":["positioning","three-file","memory","coding-agent","repo-local"],"aliases":["3-file","product-positioning"],"record_path":"memory/summary.md","updated":"2026-05-17","weight":0.9,"status":"active"} +{"schema_version":1,"id":"starter-kit-main-product","scope":"project:deja-vu","title":"Starter kit is the main product","keywords":["starter-kit","copy-first","AGENTS","summary","impressions"],"aliases":["three-file-starter"],"record_path":"memory/summary.md","updated":"2026-05-17","weight":0.85,"status":"active"} +{"schema_version":1,"id":"protocol-first-not-engine-first","scope":"project:deja-vu","title":"Protocol-first, not engine-first","keywords":["protocol","engine","optional","framework","typescript"],"aliases":["engine-first","protocol-first"],"record_path":"memory/summary.md","updated":"2026-05-17","weight":0.85,"status":"active"} +{"schema_version":1,"id":"cli-helper-scope","scope":"project:deja-vu","title":"CLI is an optional helper","keywords":["cli","init","doctor","explain","optional","helper"],"aliases":["deja-vu-cli"],"record_path":"memory/summary.md","updated":"2026-05-17","weight":0.8,"status":"active"} +{"schema_version":1,"id":"safety-privacy-boundary","scope":"project:deja-vu","title":"Safety privacy boundaries","keywords":["safety","privacy","secrets","PII","transcripts","noise"],"aliases":["memory-safety"],"record_path":"memory/summary.md","updated":"2026-05-17","weight":0.85,"status":"active"} +{"schema_version":1,"id":"v060-release-readiness","scope":"project:deja-vu","title":"v0.6.0 release readiness","keywords":["v0.6.0","release","readiness","checklist","candidate"],"aliases":["release-candidate"],"record_path":"memory/summary.md","updated":"2026-05-17","weight":0.8,"status":"active"} diff --git a/memory/open-loops/.gitkeep b/memory/open-loops/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/memory/open-loops/.gitkeep @@ -0,0 +1 @@ + diff --git a/memory/recall-feedback.jsonl b/memory/recall-feedback.jsonl new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/memory/recall-feedback.jsonl @@ -0,0 +1 @@ + diff --git a/memory/summary.md b/memory/summary.md new file mode 100644 index 0000000..e09b26f --- /dev/null +++ b/memory/summary.md @@ -0,0 +1,45 @@ +--- +id: summary +title: Deja Vu Project Summary +status: active +scope: project:deja-vu +updated: 2026-05-17 +--- + +# Deja Vu Project Summary + +## Product positioning + +Deja Vu is positioned as "A 3-file memory system for any capable AI coding agent." + +## Product structure + +- Protocol is the spec. +- Starter-kit is the main product. +- CLI is an optional helper. + +## Core promise + +Deja Vu provides repo-local, low-cost, human-readable, git-friendly, cross-agent project memory. + +Base use does not require a database, vector store, embeddings, SaaS, daemon, or npm install. + +## v0.6.0 focus + +v0.6.0 focuses on adoption: + +- README landing page +- starter-kit +- per-agent prompts +- `deja-vu init`, `deja-vu doctor`, and `deja-vu explain` +- comparison and compatibility docs +- visual diagram +- launch copy +- demo walkthrough +- release checklist + +## Boundaries + +- Say "any capable coding agent can follow the protocol." +- Do not overclaim that all agents automatically support Deja Vu. +- Do not turn Deja Vu into a heavy memory framework. From 9e787cd6340da435cc7bdb428f61999483ad62b1 Mon Sep 17 00:00:00 2001 From: Focaxis Dev Date: Sun, 17 May 2026 08:46:21 +0800 Subject: [PATCH 3/3] chore: prepare v0.6.0 release --- AGENTS.md | 2 ++ CHANGELOG.md | 2 +- README.md | 4 ++-- package-lock.json | 4 ++-- package.json | 2 +- 5 files changed, 8 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 61d0cb9..bb73fc6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,8 @@ - Scope: `project:deja-vu` - Memory root: `memory/` +For the full protocol details, see docs/protocol.md. + ## Recall Before Substantial Work Before substantial planning, coding, release preparation, or documentation changes: diff --git a/CHANGELOG.md b/CHANGELOG.md index 33e214f..aa3c880 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ All notable changes to this project will be documented in this file. -## Unreleased +## [0.6.0] - 2026-05-17 - Reworked the README first screen around the "3-file memory system" positioning. - Added a copy-first `starter-kit/` with minimal `AGENTS.md`, memory files, and per-agent prompts. diff --git a/README.md b/README.md index de4e319..45e9e47 100644 --- a/README.md +++ b/README.md @@ -29,13 +29,13 @@ Deja Vu is trying to recall less, better. ## 2-Minute Start -Copy the starter kit into any repo: +Option A: copy from this repo after cloning: ```bash cp -R starter-kit/. . ``` -Or use the optional CLI: +Option B: use the optional CLI: ```bash npx @focaxisdev/deja-vu init --agents all diff --git a/package-lock.json b/package-lock.json index e1468b0..1b11cba 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@focaxisdev/deja-vu", - "version": "0.5.0", + "version": "0.6.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@focaxisdev/deja-vu", - "version": "0.5.0", + "version": "0.6.0", "license": "MIT", "bin": { "deja-vu": "scripts/deja-vu.mjs", diff --git a/package.json b/package.json index 7b8f910..6f86d6c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@focaxisdev/deja-vu", - "version": "0.5.0", + "version": "0.6.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",