@zenera/cli 1.1.14 → 1.1.16

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 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      |
@@ -405,14 +405,14 @@ 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.
 
-What memory should hold is the **route** — the resolution, not the source:
+What memory should hold 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                            |
+| 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 +420,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 +436,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,7 +450,7 @@ 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
+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:
 
@@ -460,8 +460,8 @@ 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. Commit the pointer -
+  document, heading, line range - and read it back with `zen rag docs show`.
 ```
 
 ## Inspecting and repairing it
@@ -472,8 +472,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                          |
@@ -525,13 +525,13 @@ agents:
 ## Review checklist
 
 - [ ] `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.
@@ -541,15 +541,15 @@ agents:
 | 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                |
+| `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                       |
+| 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 |
+| 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                                   |
+| 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                                |