@zenera/cli 1.1.15 → 1.1.17

package/templates/editor/.github/skills/zen-memory/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: zen-memory
-description: How agent memory is organised and how to configure it in `agents.yaml` — the `memory:` block, per-agent `access`/`sees`/`writes`/`autoRecall`, the four `memory_*` tools, kinds and relations, how recall ranks and stitches a subgraph, and how to design a memory strategy for a project. Includes what to commit and what never to, how to keep a working file under `/memory` and re-run it later, and how to put memory in front of a `zen rag schema` or `zen rag docs` index so a search that already succeeded once is not paid for again.
+description: How agent memory is organised and how to configure it in `agents.yaml` - the `memory:` block, per-agent `access`/`sees`/`writes`/`autoRecall`, the four `memory_*` tools, kinds and relations, how recall ranks and stitches a subgraph, and how to design a memory strategy for a project. Includes the usage rules every memory-enabled project must carry in `agents/memory-instructions.md` (references/memory-instructions.md) and the script that says whether that copy is still current (scripts/check-instructions.sh), what to commit and what never to, how to keep a working file under `/memory` and re-run it later, and how to put memory in front of a `zen rag schema` or `zen rag docs` index so a search that already succeeded once is not paid for again.
 ---
 
 # Memory
 
 Memory is what an agent knows that nobody wrote down for it. A skill is
 authored, reviewed and versioned; a memory is **produced by a run** and read by
-the runs that follow. Both are knowledge, and they are not interchangeable —
+the runs that follow. Both are knowledge, and they are not interchangeable -
 anything authoritative belongs in a skill, where a human owns it.
 
-It is a **graph**, not a list of rows. A node is one thing worth keeping — a
-request, a plan, a fact, a script, a call that was made — and an edge says how
+It is a **graph**, not a list of rows. A node is one thing worth keeping - a
+request, a plan, a fact, a script, a call that was made - and an edge says how
 one led to another. That shape is the point: a script an agent wrote is useless
 without the request that asked for it and the endpoint it calls, and a store
 that can only return a ranked list leaves the joining to the model, every time.
@@ -36,11 +36,11 @@ agents:
 That is the whole feature working the obvious way: the agent can search, load
 and commit, and it recalls automatically before answering new user input.
 
-The top-level block is optional — an agent that says `memory: true` gets the
+The top-level block is optional - an agent that says `memory: true` gets the
 defaults without one. A project that mentions memory nowhere opens no store and
 creates no directory.
 
-### `memory:` — the graph itself
+### `memory:` - the graph itself
 
 | Field       | Type          | Default         | Meaning                             |
 | ----------- | ------------- | --------------- | ----------------------------------- |
@@ -53,7 +53,7 @@ creates no directory.
 memory phrased the way the query happened to be phrased and misses the rest,
 which is the failure mode that makes people conclude memory does not work. The
 width is learned from the first response rather than declared, and changing the
-model afterwards is **refused** rather than silently mixing two vector spaces —
+model afterwards is **refused** rather than silently mixing two vector spaces -
 so choose it before the graph has anything in it.
 
 ```yaml
@@ -63,11 +63,11 @@ memory:
     embedding: main
 ```
 
-`zen memory stats` says `embedding none — recall falls back to term overlap`
+`zen memory stats` says `embedding none - recall falls back to term overlap`
 when this was skipped, and a vector count below the node count means some nodes
 were committed before an embedder existed.
 
-### `agents[].memory` — who may see and write what
+### `agents[].memory` - who may see and write what
 
 ```yaml
 agents:
@@ -104,7 +104,7 @@ which of them the model is offered:
 | --------------- | -------------------------------------------------------------------------- |
 | `memory_search` | Ranks, then stitches. Returns an outline of a subgraph and a legend of ids |
 | `memory_load`   | Reads whole nodes by id. **The only call that counts as use**              |
-| `memory_commit` | Writes a subgraph — nodes and the edges between them — in one transaction  |
+| `memory_commit` | Writes a subgraph - nodes and the edges between them - in one transaction  |
 | `memory_forget` | Removes nodes, their vectors and their file bytes together                 |
 
 Search and load are split on purpose. Search hands back context the model never
@@ -112,7 +112,7 @@ asked for; counting that as use would poison recency ranking. Commit is one
 call because a remembered thing is a subgraph, and building it with three calls
 leaves the graph half-formed when the model stops early.
 
-The system prompt already explains all of this to the agent — how to read a
+The system prompt already explains all of this to the agent - how to read a
 recollection, when committing is worthwhile, why correction is a new node. That
 text is **derived from `access`**, so an agent that cannot write is never told
 how to. Do not restate it in a prompt; state project-specific policy instead.
@@ -132,15 +132,15 @@ later.
 | `fact`       | a durable truth about the environment or the domain            |
 | `snippet`    | a short piece of code or configuration, too small to be a file |
 | `file`       | an artifact kept whole under `/memory` and re-runnable         |
-| `operation`  | an external call that was made — an endpoint, command or query |
+| `operation`  | an external call that was made - an endpoint, command or query |
 | `preference` | a standing instruction from the user that applies to every run |
 
 | Relation     | Reads as                                                  | Effect on recall                |
 | ------------ | --------------------------------------------------------- | ------------------------------- |
-| `PRODUCED`   | the source led to the target being made (task → artifact) | spine — pulled in first         |
+| `PRODUCED`   | the source led to the target being made (task → artifact) | spine - pulled in first         |
 | `CALLS`      | the source invokes the target                             | spine                           |
 | `SUPERSEDES` | the source replaces the target; the target is stale       | spine, and **hides** the target |
-| `INFORMED`   | the source was context the target was built from          | background — dropped first      |
+| `INFORMED`   | the source was context the target was built from          | background - dropped first      |
 
 Override the vocabularies only if the defaults genuinely do not fit the domain.
 A wider vocabulary is a vaguer one, and a kind nothing else understands is a
@@ -156,7 +156,7 @@ that kind to build the system prompt.
 | `kind`                   | filters a search, and decides how it renders                |
 | `audience`               | who may see it. `['*']` is everyone; denied by default      |
 | `createdAt`              | provenance, and what `newer_than` filters on                |
-| `lastUsedAt`, `useCount` | bumped by `memory_load` alone — the input to recency        |
+| `lastUsedAt`, `useCount` | bumped by `memory_load` alone - the input to recency        |
 | `revision`               | optimistic concurrency, via `expected_revision` on a commit |
 | `file`                   | the remembered bytes, if any                                |
 
@@ -167,7 +167,7 @@ that kind to build the system prompt.
    nodes are excluded, and so are `preference` nodes unless asked for by kind.
 2. **Order by recency, but do not admit by it.** Relevance alone clears the
    threshold; decay by `lastUsedAt` only breaks the tie afterwards. Memory that
-   keeps proving useful surfaces ahead of memory written once and never read —
+   keeps proving useful surfaces ahead of memory written once and never read -
    without anything ageing out of reach however well it matches.
 3. **Stitch.** Breadth-first from every seed at once, ignoring edge direction,
    because a memory is as often reached from the artifact back to the request as
@@ -182,14 +182,14 @@ Defaults: 5 seeds, 2 hops, 25 nodes. `memory_search` takes `limit`, `max_hops`,
 What comes back is a `<memory-recollection>` block: an indented outline where
 the indentation _is_ the graph, each line reading `score kind id` or
 `→relation kind id`, with each node's text under it **clipped to 160
-characters**. That clip is a design constraint on how you write a node — see
+characters**. That clip is a design constraint on how you write a node - see
 below.
 
 ### On disk
 
 ```
 <project>/memory/
-├── manifest.json   written LAST — a half-written memory reads as empty
+├── manifest.json   written LAST - a half-written memory reads as empty
 ├── graph.json      nodes and edges, parsed whole on open
 ├── vectors.f32     raw little-endian float32, a quarter the size of JSON
 ├── vectors.json    the ids those vectors belong to
@@ -206,9 +206,9 @@ mounted **read-only** at `/memory` in the agent's namespace.
 
 **Would the next run otherwise have to work this out again?** That is the whole
 question. A script that ran, an interface that behaved differently from its
-documentation, a call sequence that turned out to be necessary — yes. The
+documentation, a call sequence that turned out to be necessary - yes. The
 request restated, progress notes, anything unverified, anything a search already
-returned — no.
+returned - no.
 
 The second test is **would it still be true next month**. Memory has no expiry
 and no reviewer. A fact about the environment survives; a fact about today's
@@ -222,9 +222,9 @@ ask for it, not the way the system that produced it names it.
 
 | Instead of                        | Write                                                                           |
 | --------------------------------- | ------------------------------------------------------------------------------- |
-| `POST /v2/subs/{id}:cancel — 204` | `Cancelling a subscription: POST /v2/subs/{id}:cancel, 204, no body`            |
-| `fix for the 409`                 | `A duplicate customer email returns 409, not 422 — retry is wrong`              |
-| `script.py`                       | `Weekly invoice reconciliation script — reads billing CSV, writes a diff table` |
+| `POST /v2/subs/{id}:cancel - 204` | `Cancelling a subscription: POST /v2/subs/{id}:cancel, 204, no body`            |
+| `fix for the 409`                 | `A duplicate customer email returns 409, not 422 - retry is wrong`              |
+| `script.py`                       | `Weekly invoice reconciliation script - reads billing CSV, writes a diff table` |
 
 Front-load the identifying facts: the first 160 characters are what appears in
 a recollection, and everything after that costs a `memory_load` to see.
@@ -238,7 +238,7 @@ task      "reconcile invoices against the ledger for a month"
   PRODUCED → file      the script that did it
   INFORMED ← fact      "ledger exports use minor units; invoices use decimals"
 file
-  CALLS    → operation "GET /v2/invoices?created[gte]= — cursor paging"
+  CALLS    → operation "GET /v2/invoices?created[gte]= - cursor paging"
 ```
 
 Committed separately, a later run finds a script with no idea why it exists, or
@@ -247,7 +247,7 @@ brings the rest.
 
 **Never edit a memory to correct it.** Commit the new one and link it to the old
 with `SUPERSEDES`. Recall follows the edge forward and hides what it points at,
-so the wrong answer stops being served without being destroyed — and the reason
+so the wrong answer stops being served without being destroyed - and the reason
 a thing changed is often the useful part. `zen memory ls --stale` is the list of
 corrections that have happened.
 
@@ -255,7 +255,7 @@ A new node whose text is a near-duplicate (cosine ≥ 0.97) of one already there
 is **folded into it**, and the existing id comes back under the model's ref, so
 the links still land on the memory that was already present.
 
-### Audiences: one graph, masked — not one graph each
+### Audiences: one graph, masked - not one graph each
 
 Every node carries an `audience`; `sees` is the set an agent reads. `*` is the
 public slice and is always included, so a binding can only ever **widen** what
@@ -275,7 +275,7 @@ agent wrote this" but "which agent would be misled by this":
 | One curator may delete                            | `access: full` on exactly one agent       |
 
 When `writes` names exactly one label, the tool schema omits the field and
-applies it — there is nothing to choose and nothing for the model to get wrong.
+applies it - there is nothing to choose and nothing for the model to get wrong.
 Neither `sees` nor `writes` is ever a tool parameter: an agent that could name
 its own audience could read another agent's slice just by asking.
 
@@ -285,7 +285,7 @@ model that can delete will occasionally tidy.
 ### Auto-recall
 
 On by default, because an agent that has to remember to go looking mostly does
-not. It fires **after new user input and after a hand-off** — not before every
+not. It fires **after new user input and after a hand-off** - not before every
 call, because recalling on every turn costs tokens and defeats prompt caching
 for a marginal gain. A turn following a tool result does not re-recall.
 
@@ -294,7 +294,7 @@ for a marginal gain. A turn following a tool result does not re-recall.
 | `true` (default) | Almost everything                                                        |
 | `{ limit: 2 }`   | A cheap model, or a graph big enough that five seeds is a page           |
 | `{ limit: 8 }`   | A research agent where breadth beats prompt size                         |
-| `false`          | An agent that should decide for itself when to look — it keeps the tools |
+| `false`          | An agent that should decide for itself when to look - it keeps the tools |
 
 `autoRecall: false` is right for a tool-driven agent whose first turn is
 mechanical, and for anything where the user's message is a payload rather than a
@@ -302,7 +302,7 @@ question.
 
 ### Preferences
 
-A `preference` node is a standing instruction — "always report findings as a
+A `preference` node is a standing instruction - "always report findings as a
 table", "use ISO dates". These are **not recalled by similarity**, because they
 are not about the request in front of the agent: an instruction on how to report
 is nowhere near a question about gateway rules in embedding space, and a search
@@ -319,7 +319,7 @@ their ids:
 
 They land in the cached prefix, so they cost once per run rather than once per
 turn, and the id is what lets a model replace one with `SUPERSEDES` instead of
-quietly ignoring it. They are left out of ordinary recall on purpose — they are
+quietly ignoring it. They are left out of ordinary recall on purpose - they are
 in the prompt already.
 
 Commit one only when the user's own words generalise: "always", "from now on",
@@ -329,7 +329,7 @@ wrote.
 
 ## Remembering files, and running them again
 
-The workspace is disposable — it may be a container about to be discarded — so a
+The workspace is disposable - it may be a container about to be discarded - so a
 reference to a path in it dangles the moment the run ends. `memory_commit` takes
 a `file` argument on a node instead, and copies the **bytes** out:
 
@@ -339,7 +339,7 @@ a `file` argument on a node instead, and copies the **bytes** out:
         {
             "ref": "s",
             "kind": "file",
-            "text": "Invoice reconciliation script — reads the billing CSV, writes a diff table",
+            "text": "Invoice reconciliation script - reads the billing CSV, writes a diff table",
             "file": "reconcile.py"
         },
         { "ref": "t", "kind": "task", "text": "reconcile invoices against the ledger for March" }
@@ -358,7 +358,7 @@ lands at `<project>/memory/files/<id>.<ext>` and appears to the agent as:
 | Rule      | Value                                                            |
 | --------- | ---------------------------------------------------------------- |
 | Size cap  | 2 MiB. Over it, keep the artifact and commit a `snippet` instead |
-| Inlined   | under 32 KiB — `memory_load` returns the contents                |
+| Inlined   | under 32 KiB - `memory_load` returns the contents                |
 | Larger    | `memory_load` returns the path; open or run it                   |
 | Mount     | `/memory`, **read-only**                                         |
 | Extension | preserved, because it decides how the file runs and renders      |
@@ -379,11 +379,14 @@ node explaining what it is and the graph cannot acquire orphans. To change a
 remembered file: copy it into the workspace, edit it there, commit the new one
 and link it with `SUPERSEDES` to the old.
 
-| Commit as | When                                                                      |
-| --------- | ------------------------------------------------------------------------- |
-| `file`    | It is runnable, or it is the artifact itself: a script, a config, a query |
-| `snippet` | It is a few lines that only make sense read: a request body, a fragment   |
-| `fact`    | It is a sentence. A file containing one sentence is a fact in a costume   |
+The node text describes and locates; the file carries the content. Reach for a
+node with no file only when the whole of what you know fits on one line.
+
+| Commit as | When                                                                        |
+| --------- | --------------------------------------------------------------------------- |
+| `file`    | It is content - a script, a config, a query, a passage, an assembled answer |
+| `snippet` | It is a few lines that only make sense read, and nothing will ever run them |
+| `fact`    | It is one line. A file containing one sentence is a fact in a costume       |
 
 ## Memory in front of a `zen rag` index
 
@@ -400,19 +403,27 @@ it is entirely a matter of **what you commit**.
 | Freshness       | as fresh as the last `index`                                    | as stale as it was allowed to get |
 | Cost of a query | one embedding round trip (`search`), or nothing (`list`/`grep`) | already in the prompt             |
 
-So: **never copy index content into memory.** A schema pasted into a node goes
-stale silently and the index already answers in milliseconds; a documentation
-passage quoted into a node outlives the release it was true for and will look
-exactly as authoritative when it is wrong.
+So: **never copy content out of an index that still changes.** A schema pasted
+into a node goes stale silently and the index already answers in milliseconds; a
+documentation passage quoted into a node outlives the release it was true for
+and will look exactly as authoritative when it is wrong.
+
+A **pinned** index is the exception, and a real one. Docs indexed from a
+released version or a versioned reference tree cannot change under the memory,
+so a passage taken out of one stays true as long as the project stays on that
+version. Keep it as a `file` node whose text names the documents and line ranges
+and says which version it was. That is as well as the route, never instead of
+it.
 
-What memory should hold is the **route** — the resolution, not the source:
+What memory should hold first is the **route** - the resolution, not the source:
 
 | Commit                                                                            | Kind               | Because                                                                           |
 | --------------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------- |
 | The endpoint that turned out to be the answer, and its shape                      | `operation`        | A `search_api` costs a round trip and returns five ranked guesses; this names one |
 | The sequence of calls that was necessary                                          | `plan`             | No ranking finds an ordering. It is not in the document                           |
-| Where the answer lives in the docs — document name, heading, line range           | `fact`             | `zen rag docs show` reads it back verbatim and current                            |
-| A convention the index cannot state — auth, casing, base path, the error envelope | `fact`             | It is not in the graph, and it is wrong to re-derive it every run                 |
+| Where the answer lives in the docs - document name, heading, line range           | `fact`             | `zen rag docs show` reads it back verbatim and current                            |
+| The passage itself, when the index is pinned to a released version                | `file`             | It cannot change under you, and the pointer alone makes the next run re-read it   |
+| A convention the index cannot state - auth, casing, base path, the error envelope | `fact`             | It is not in the graph, and it is wrong to re-derive it every run                 |
 | Where the index itself is                                                         | `fact`             | `-d` or `$ZEN_SCHEMA_DB`. An agent cannot guess a path                            |
 | A working request body, or a script that drives the API                           | `snippet` / `file` | The thing you would otherwise write again                                         |
 | That a search returned nothing, and `grep` confirmed absence                      | `fact`             | Proving a negative twice is pure waste                                            |
@@ -420,7 +431,7 @@ What memory should hold is the **route** — the resolution, not the source:
 ### Why it makes search cheaper
 
 Auto-recall fires **before the model's first tool call of the turn**. So the
-recollection arrives before the decision to search is made — and a recalled
+recollection arrives before the decision to search is made - and a recalled
 `operation` node naming `POST /v2/subs/{id}:cancel` removes the search
 entirely, rather than making it faster. When the recollection is only close, it
 still narrows: the model reaches for `list_api --name` or `grep_api` instead of
@@ -436,7 +447,7 @@ and the answer second.
 An index is rebuilt when the source changes; memory is not. Two habits keep the
 two from drifting:
 
-1. **Name the version in the node text** — "Billing API v2", "acme\_4.1.0 docs".
+1. **Name the version in the node text** - "Billing API v2", "acme\_4.1.0 docs".
    A recollection about a version the project no longer uses is then visibly
    about the wrong thing rather than invisibly wrong.
 2. **Supersede after a re-index.** When a route changes, commit the new
@@ -450,9 +461,13 @@ cheap and settles it.
 
 ### The project skill is where this is written down
 
-An index used by a project needs a skill in that project describing it — see
-`zen-rag-schema` and `zen-rag-docs`. Memory policy belongs in the same skill,
-because it is the same subject:
+An index used by a project needs a skill in that project describing it - see
+`zen-rag-schema` and `zen-rag-docs`. The memory policy that is **about the
+index** belongs in that skill, because it is the same subject and it is read at
+the moment the index is. Policy that holds whatever the agent is doing -
+audiences, what must never be written down - goes in
+`agents/memory-policy-instructions.md` instead, which every agent gets whether
+it loads the skill or not.
 
 ```md
 - Recalled routes are a shortcut, not authority. Confirm with `list_api --name`
@@ -460,10 +475,61 @@ because it is the same subject:
 - After solving something the index made you work for, commit it: the
   `operation` you ended on, linked to the `task` that asked and any `fact` you
   had to discover. Phrase the text as the question, not as the operation id.
-- Never commit schema text or documentation passages. Commit the pointer —
-  document, heading, line range — and read it back with `zen rag docs show`.
+- Never commit schema text or documentation passages copied out of a document
+  that still changes. Commit the pointer - document, heading, line range -
+  alongside what you concluded from it, and read the passage back with
+  `zen rag docs show` to check the conclusion still holds.
+- Our docs are indexed from the pinned 1.4 tree, so a passage out of them is
+  safe to keep whole: commit it as a `file` node headed with the documents and
+  line ranges, next to the pointer and the conclusion.
+```
+
+## The house rules
+
+**Every project that enables memory carries `references/memory-instructions.md`
+in its own `agents/memory-instructions.md`**, as part of turning memory on. That
+file is how the agent is told to use the store: read and search it only through
+the tools, never through `/memory` itself, and what a node must carry to still be
+worth having.
+
+`zen init` writes it, because the projects it scaffolds have memory on from the
+first run. Two cases are left to check by hand: a project that turned memory on
+afterwards, and one whose copy has drifted from the reference or was deleted.
+
+Neither is checked by eye. The skill ships the check, and it is one command:
+
+```sh
+.github/skills/zen-memory/scripts/check-instructions.sh        # the verdict
+.github/skills/zen-memory/scripts/check-instructions.sh diff   # every differing line
+.github/skills/zen-memory/scripts/check-instructions.sh fix    # copy the reference over
 ```
 
+It says whether this project turns memory on at all, exits non-zero on a copy
+that is missing or stale, and prints the `cp` that repairs it. When the only
+difference is trailing whitespace it says so - that is the usual drift, it is
+invisible on screen, and it is the reason reading the two files side by side
+never caught it.
+
+It is a copy, not a transcription - this reference already sits in the project,
+because `zen init` and `zen open` write the whole `.github/` tree, and they write
+it from the same file the project's copy came from. What `fix` runs, from the
+project root, is exactly:
+
+```sh
+cp .github/skills/zen-memory/references/memory-instructions.md agents/memory-instructions.md
+```
+
+Everything the project keeps under `agents/` named `<topic>-instructions.md` is
+prepended to every agent, in filename order, so this belongs in its own document
+rather than as another section of `agents/instructions.md` - it arrives with
+memory and it leaves with it.
+
+**Keep that file a pure copy.** Project-specific policy - audiences, what must
+never be written down, what an agent commits at the end of a job - goes in
+`agents/memory-policy-instructions.md`, which filename order puts directly after
+it. Then keeping up with a changed reference is the same one command again,
+rather than a hand-patch around prose that has to be preserved.
+
 ## Inspecting and repairing it
 
 ```
@@ -472,8 +538,8 @@ zen memory [stats|ls|show|export|forget] [args] [options]
 
 `zen memory export --open` is the one to reach for: one self-contained HTML
 page with every node, the graph as a diagram, and the remembered file's actual
-content in the detail pane. It reads **unmasked** — when the mask is what is
-wrong, the hidden part is exactly the part you need — and it contacts no model,
+content in the detail pane. It reads **unmasked** - when the mask is what is
+wrong, the hidden part is exactly the part you need - and it contacts no model,
 so inspection is free and offline.
 
 | Question                                 | Command                          |
@@ -524,32 +590,38 @@ agents:
 
 ## Review checklist
 
+- [ ] `.github/skills/zen-memory/scripts/check-instructions.sh` exits zero, so
+      `agents/memory-instructions.md` is the reference byte for byte - and
+      project policy lives in `agents/memory-policy-instructions.md`.
 - [ ] `memory.embedding` is set, and was set before the graph had content.
-- [ ] Every agent that should learn has a `memory:` binding — the top-level
+- [ ] Every agent that should learn has a `memory:` binding - the top-level
       block alone enables nothing.
 - [ ] `access: full` appears at most once.
 - [ ] `sees`/`writes` exist because an agent would be **misled** by the other
       slice, not merely because it does not need it.
 - [ ] `autoRecall: false` on any agent whose user message is a payload.
-- [ ] Nothing authoritative is expected to live here — that is a skill's job.
+- [ ] Nothing authoritative is expected to live here - that is a skill's job.
 - [ ] The project's index skill says to verify a recalled route.
 - [ ] `zen memory export --open` after a week of use, to see what it actually
       learned rather than what you hoped.
 
 ## When it goes wrong
 
-| Symptom                                           | Cause                                                                                                      |
-| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| The `memory_*` tools are missing                  | No `memory:` on the agent. They come from the binding, never from `tools:`                                 |
-| `zen memory` says the project has none            | Neither a `memory:` block nor an agent binding — nothing is opened and no directory is made                |
-| Recall finds a memory only when reworded          | No embedder. `zen memory stats` says `embedding none`                                                      |
-| Recall finds nothing after changing the embedder  | Refused rather than mixed — a manifest records the model. Re-embed or change it back                       |
-| Vectors fewer than nodes                          | Some nodes were committed with no embedder; they are only reachable by term overlap                        |
-| The graph fills with restated requests            | The commit rule is not in a prompt or skill. State the "would a later run redo this" test                  |
-| A wrong memory keeps coming back                  | It was edited instead of superseded, or superseded in the wrong direction — the **new** node is the source |
-| An agent cannot see a node you can                | Its `audience` is not in that agent's `sees`. Invisible and missing are the same thing, on purpose         |
-| "this agent cannot remember files"                | The agent has no workspace, so a path cannot be resolved. Commit without `file`                            |
-| A remembered file will not run                    | It is not self-contained — it referenced the workspace it was written in                                   |
-| Recollections are large and unhelpful             | `autoRecall.limit` is too high, or node texts describe answers rather than questions                       |
-| The model recalls a route the API no longer has   | Nothing re-checks memory against a rebuilt index. Supersede, and require verification                      |
-| A second run of the same project refuses to start | The directory lock. A lock whose process is gone is stale and is taken over                                |
+| Symptom                                             | Cause                                                                                                      |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| The `memory_*` tools are missing                    | No `memory:` on the agent. They come from the binding, never from `tools:`                                 |
+| `zen memory` says the project has none              | Neither a `memory:` block nor an agent binding - nothing is opened and no directory is made                |
+| Recall finds a memory only when reworded            | No embedder. `zen memory stats` says `embedding none`                                                      |
+| Recall finds nothing after changing the embedder    | Refused rather than mixed - a manifest records the model. Re-embed or change it back                       |
+| Vectors fewer than nodes                            | Some nodes were committed with no embedder; they are only reachable by term overlap                        |
+| The graph fills with restated requests              | The commit rule is not in a prompt or skill. State the "would a later run redo this" test                  |
+| An agent greps `/memory` or reads `graph.json`      | The house-rules block is missing from `agents/memory-instructions.md` - the system prompt never forbids it |
+| A recalled fact cannot be checked or continued      | Nodes were committed with no provenance. The block's "say where it came from" rule is what prevents it     |
+| Recall returns pointers and the run re-reads it all | Content was committed as `text` alone. A node's text describes and locates; the content belongs in a file  |
+| A wrong memory keeps coming back                    | It was edited instead of superseded, or superseded in the wrong direction - the **new** node is the source |
+| An agent cannot see a node you can                  | Its `audience` is not in that agent's `sees`. Invisible and missing are the same thing, on purpose         |
+| "this agent cannot remember files"                  | The agent has no workspace, so a path cannot be resolved. Commit without `file`                            |
+| A remembered file will not run                      | It is not self-contained - it referenced the workspace it was written in                                   |
+| Recollections are large and unhelpful               | `autoRecall.limit` is too high, or node texts describe answers rather than questions                       |
+| The model recalls a route the API no longer has     | Nothing re-checks memory against a rebuilt index. Supersede, and require verification                      |
+| A second run of the same project refuses to start   | The directory lock. A lock whose process is gone is stale and is taken over                                |

package/templates/editor/.github/skills/zen-memory/scripts/check-instructions.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+#
+# Whether this project's memory house rules are still the rules.
+#
+#   check-instructions.sh          diff the copy against the reference
+#   check-instructions.sh diff     the same, showing every differing line
+#   check-instructions.sh fix      overwrite the copy from the reference
+#
+# `agents/memory-instructions.md` is a *copy* of the `zen-memory` skill's
+# `references/memory-instructions.md`, and the reference is rewritten by every
+# `zen init` and `zen open`. So the copy goes stale silently, and it drifts by
+# trailing whitespace inside tables, which no one can see by reading. That is
+# the whole reason this is a script and not a checklist line.
+#
+# Run it from anywhere; it finds the project root from its own location.
+
+set -eu
+cd "$(dirname "$0")/../../../.."
+
+COPY=agents/memory-instructions.md
+REFERENCE=.github/skills/zen-memory/references/memory-instructions.md
+REMEDY="cp $REFERENCE $COPY"
+
+if [ ! -f "$REFERENCE" ]; then
+    echo "check-instructions.sh: no $REFERENCE in $PWD" >&2
+    echo "check-instructions.sh: run \`zen open\` to rewrite the .github tree" >&2
+    exit 2
+fi
+
+# The project turns memory on when something declares it — the top-level block
+# or an agent's binding — so any `memory:` key in the configuration counts.
+# The config is found by name, in the order a run finds it.
+config() {
+    for file in agents.yaml agents.yml agents/agents.yaml agents/agents.yml; do
+        if [ -f "$file" ]; then
+            echo "$file"
+            return 0
+        fi
+    done
+}
+
+uses_memory() {
+    # `|| true` because no configuration at all is an answer, not a failure.
+    conf="$(config || true)"
+    if [ -z "$conf" ]; then
+        return 1
+    fi
+    grep -Eq '^[[:space:]]*(-[[:space:]]+)?memory:' "$conf"
+}
+
+# The file with every line's trailing whitespace removed. Two of these being
+# equal is the drift nobody can see by reading, named as such.
+trimmed() {
+    sed 's/[[:space:]]*$//' "$1"
+}
+
+report() {
+    if uses_memory; then
+        echo "memory: on"
+    else
+        echo "memory: off"
+    fi
+
+    if [ ! -f "$COPY" ]; then
+        if uses_memory; then
+            echo "missing: $COPY"
+            echo "remedy: $REMEDY"
+            return 1
+        fi
+        echo "ok: no copy, and nothing needs one"
+        return 0
+    fi
+
+    if cmp -s "$REFERENCE" "$COPY"; then
+        if ! uses_memory; then
+            # Harmless, but it is rules for a capability nothing turned on.
+            echo "note: the copy is current, but no agent has a memory: binding"
+        fi
+        echo "ok: $COPY is the reference, byte for byte"
+        return 0
+    fi
+
+    echo "drift: $COPY differs from the reference"
+    # Said out loud because it is invisible on screen, and is the usual cause:
+    # a trailing space inside a table, or a lost final newline.
+    if [ "$(trimmed "$REFERENCE")" = "$(trimmed "$COPY")" ]; then
+        echo "drift: trailing whitespace only — nothing you could have seen"
+    fi
+    echo "remedy: $REMEDY"
+    return 1
+}
+
+show_diff() {
+    report || true
+    # `-L` names the two sides, since both files are called the same thing.
+    diff -u -L reference -L "$COPY" "$REFERENCE" "$COPY" || true
+    # The report's verdict, not the diff's.
+    report >/dev/null
+}
+
+fix() {
+    cp "$REFERENCE" "$COPY"
+    echo "wrote: $COPY"
+    echo "note: project policy belongs in agents/memory-policy-instructions.md"
+}
+
+case "${1:-status}" in
+    status) report ;;
+    diff) show_diff ;;
+    fix) fix ;;
+    *)
+        echo "usage: check-instructions.sh [status|diff|fix]" >&2
+        exit 2
+        ;;
+esac