@zenera/cli 1.1.25 → 1.1.27

package/templates/project/agents/memory-instructions.md

@@ -4,496 +4,225 @@ requires: [memory]
 
 # Memory
 
-This project has a memory: a graph of what earlier runs worked out, kept with
-the project rather than with the session, and shared with every other agent that
-can see it. It is reached **only** through the `memory_*` tools - `memory_search`
-to find by meaning, `memory_grep` to find an exact string, `memory_load` to
-read.
-
-Not every agent may write to it. Read what follows against the tools you
-actually have: if `memory_commit` is not among them, everything under
-[Updating it](#updating-it) is not yours to do, and if `memory_forget` is not
-among them, neither is [Forgetting](#forgetting).
-
-It exists to make the next run cheaper. Work that cost something - a long
-investigation, a fan-out of searches, a build, an invocation found by trial -
-should be paid for once. A recollection is a cache hit: check it, do not
-rebuild it.
-
-## What belongs in it
-
-One question decides both what to keep and how far to trust it:
-
-**Can the next run get this itself, cheaply and current?**
-
-| When the answer is                                                                    | Keep                                                                |
-| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| one read, one call, one command away                                                  | the way to get it - the route, the call, the script, the invocation |
-| assembled from several sources, with a judgement on top                               | what you concluded, and a pointer to every source it came from      |
-| out of something that cannot change - a released spec, a pinned or versioned document | the finding itself, whole, in a file that names where it came from  |
-| a reading of the moment - an API response, a query result, what a script printed      | the call that produces it, never the reading                        |
-
-Remember the **route** when the answer is cheap, the **answer** when the route
-is expensive, and never a value that is stale by the next run.
-
-## How it is organised
-
-A node is one thing worth keeping. It carries a `kind`, a `text` - the only
-thing searched - and optionally a remembered file. An edge says how one node led
-to another.
-
-The two halves do different jobs, and the split is the same every time: the
-**text is how the node is found** - what it is, what it establishes, where it
-came from - and the **file is what the node holds**. Only the text is searched,
-and only its first 160 characters are ever shown, so content written into it is
-both unfindable and in the way. Once something is worth committing at all, the
-usual shape is therefore a short description and a file behind it.
-
-A node with no file is for what fits on **one line** - a path and a line range,
-a command, a standing instruction, a single stated fact. If what you are keeping
-runs past a line or two, it is content, and content goes in the file.
-
-| Kind         | Is                                                                                   |
-| ------------ | ------------------------------------------------------------------------------------ |
-| `task`       | the request that started a piece of work                                             |
-| `plan`       | an approach that worked and would work again                                         |
-| `fact`       | a durable truth about this codebase, API or environment                              |
-| `snippet`    | a few lines of code or configuration                                                 |
-| `file`       | an artifact kept whole - a script to re-run, an answer or passage too big for a text |
-| `operation`  | an external call that was made - endpoint, command, query. The call, not its answer  |
-| `preference` | a standing instruction from the user, or what they told you about themselves         |
-
-| Relation     | Reads as                                            |
-| ------------ | --------------------------------------------------- |
-| `PRODUCED`   | the source led to the target being made             |
-| `CALLS`      | the source invokes the target                       |
-| `SUPERSEDES` | the source replaces the target; the target is stale |
-| `INFORMED`   | the source was context the target was built from    |
-
-So a remembered piece of work is a subgraph, not a row:
-
-```
-task       the request that started this
-  PRODUCED → file | snippet | operation     what came out of it
-  INFORMED ← fact                            what had to be known first
-file
-  CALLS    → operation                       what it calls
-```
-
-What you are shown is ranked, masked and clipped. **Assume a recollection is
-part of the answer, never all of it.**
-
-Relation is what decides where the clipping falls. Everything reached across
-`PRODUCED`, `CALLS` or `SUPERSEDES` is the work itself; everything reached
-across `INFORMED` is context, and context is what a short recollection drops
-first - so the answer degrades by losing its background rather than by being cut
-in half. Attach with `INFORMED` what **explains** a node, never what the next run
-needs in order to **use** it: the endpoint a script calls, or the request that
-produced it, belongs on the spine, where it is still there when the budget is
-tight.
-
-`INFORMED` also reads in a direction - from the background to the work it fed,
-so a `fact` informs an answer and never the other way round. Written backwards
-it still traverses, and still renders; it just says the answer was context for
-its own source.
-
-## Reading it
-
-`memory_search` hands back an outline of a subgraph with each node's text cut to
-160 characters. `memory_grep` hands back the nodes containing an exact string,
-with the lines it matched on. `memory_load` is what reads a node whole, by id -
-load anything you are going to rely on.
-
-### The shape of a recollection
-
-A recollection arrives in a `<memory-recollection>` block, and it is a subgraph
-rather than a ranked list - the links are as much of the answer as the nodes. It
-is an outline, and the indentation is the graph.
-
-A line at the left margin reads `score kind id` and is something the search
-matched; a root the walk reached rather than matched carries `--` where the
-score would be. A line indented under it reads `<arrow>relation kind id` and is
-a neighbour: `→produced` means the line above produced this one, `←informed`
-means this one informed the line above. A neighbour the search matched in its
-own right carries its score too, after the arrow.
-
-Under each header, indented further, is that node's text. A `file` node carries
-one line more, above the text: the path under `/memory` to open or run, its
-size, and how often it has been read.
-
-A line beginning `+` is a link to an id already shown above, for an edge the
-outline could not nest. It never points forward, so resolving one only ever
-means looking back up the block.
-
-Text is clipped at 160 characters - copy an id into `memory_load` to read a node
-whole. `memory_search` finds ids; it does not return contents.
-
-A remembered file appears at `/memory/<id>.<ext>`. Open it or run it, but arrive
-at that path through `memory_load`, never by looking around in the directory.
-
-**Never read the store directly.** `/memory` holds `graph.json`, `vectors.f32`,
-`vectors.json` and `manifest.json` - its internal format. Do not open, list,
-grep, `cat` or `find` them, and do not point a shell command at that directory:
-
-- `graph.json` is every node ever committed, as one line;
-- a raw read bypasses the audience mask and serves **superseded** nodes -
-  corrections that were withdrawn - as if they were current;
-- it records no use, so the ranking that decides what gets recalled next decays;
-- another run may be writing, and the manifest is written last.
-
-**`memory_grep` is that search, done properly.** It reads every node exactly -
-the text, the metadata and the bytes of remembered files - and hands back the
-matching lines with the node they belong to. It applies the mask, it leaves out
-what has been superseded unless you ask for it, and it names any file it could
-not read, so a file that went unsearched never passes for one with no match.
-
-A memory is a record, not an authority - but checking one is not the same as
-redoing it, and how you check depends on where its content came from.
-**Pinned** - a released spec, a versioned document: its content cannot have
-moved, so use what the node says and check only that the route still resolves.
-**Living** - code, an API, anything that changes: confirm the named lines still
-say what the node says, the route still resolves, the command still exists.
-Work it out from nothing only when that check fails, or when being wrong is
-expensive. A check that costs what the original investigation cost is not a
-check - it is the investigation again, and the memory bought nothing.
-
-### None of it appears in an answer
-
-The store is your apparatus, not your subject. An answer says what was found and
-where it can be checked - the sources, the commands, the files the work left
-behind. It never says that a recollection was what put you on to them.
-
-Never write `/memory`, a node id, or the words "memory", "recalled" or
-"remembered" into an answer. Read your text before you send it: if it holds
-`/memory` or a node id, cut the sentence around it and say what was done
-instead. "Loaded the script from memory (`/memory/01J….py`) and ran it" is
-"ran `<path>`" with your working left in by mistake.
-
-Two reasons, and both hold even where the reader would find it interesting. A
-node id names nothing the reader can open, so it reads as a citation and cannot
-be followed; and it stops being true the moment the node is superseded, while
-the source it was drawn from does not. Cite the source, never the memory of it.
-
-This binds on a branch's answer exactly as it binds on the final one. A branch
-rejoins as a single result that the agent above writes its own answer from, so
-an id that survives the join is an id in the reply.
-
-The one exception is a question about the store itself - what is known about
-something, whether it was seen before, what to forget. Then it is the subject,
-and ids are what the reader needs.
-
-## Searching it
-
-Search **before** paying for anything: an investigation, an index query, a
-build, a long command. The point is not to find a pointer - it is to arrive at
-the answer without buying it twice.
-
-Four moments are each worth one search:
-
-| At                                       | Search for                                                             |
-| ---------------------------------------- | ---------------------------------------------------------------------- |
-| a request arriving                       | the request itself, before the first step is planned                   |
-| arriving by handoff, or as a fork branch | the brief you were handed - it is new to you, not to the project       |
-| the point where real work would start    | the question that work would answer, whenever it is more than one call |
-| a dead end mid-run                       | what you now know you are missing, in the words you would ask it in    |
-
-Search the QUESTION, not the turn. Asking the same question again in different
-words is a round trip for an answer you already have; search again when what
-you need to know changes, not when the step does.
-
-One `memory_load` is not cheaper than re-reading the single file a node names.
-It is far cheaper than redoing what produced that node: several documents read
-in sequence, a fan-out of searches, a delegated lookup, a long run. Price a
-recollection against what it **saves**, never against one read.
-
-Phrase the query as the question you are actually asking, in the words a person
-would use - node texts are written to be found that way. Narrow with `kinds`,
-`newer_than`, `limit`, `max_hops` and `max_nodes` when a recollection comes back
-broad rather than wrong.
-
-### Which of the two
-
-`memory_search` ranks, so it returns what is closest and stops. That makes it
-right for a question and wrong for a fact about the store itself - whether one
-exact name, path or command was ever written down. An empty search on a
-question is still the answer to that question: it matched by meaning, so other
-wordings of the same question were covered. Do not follow it with a
-`memory_grep` for words taken from the question.
-
-`memory_grep` is exact and complete. Reach for it when the thing you are looking
-for is a **string** rather than a subject, and when the answer has to be all of
-them:
-
-| Looking for                                                     | Use             |
-| --------------------------------------------------------------- | --------------- |
-| what was learned about a subject, however it was phrased        | `memory_search` |
-| a name, path, id, host, flag or command, spelled exactly        | `memory_grep`   |
-| whether an exact name, path or command was written down at all  | `memory_grep`   |
-| everywhere a thing is mentioned, before changing or retiring it | `memory_grep`   |
-| a starting point, when you do not yet know the vocabulary       | `memory_search` |
-
-Either way, ids from one are ids for the other: grep a name, then `memory_load`
-what it turned up.
-
-Recalling nothing is not proof of anything: work it out normally, then commit
-the result so the next run does not repeat it. A `memory_grep` that found
-nothing is stronger - it means the string is not there - but it says nothing
-about the subject under another name.
-
-## Updating it
-
-Commit when **the next run would otherwise have to work this out again** and
-working it out cost more than a `memory_load` will. The measure is what the
-answer COST, not what kind of thing it is: one cheap tool call away, do not;
-five reads, a fan-out and a judgement, commit the judgement and not only the
-five paths.
-
-| Worth committing                                                  | Not worth committing                                                |
-| ----------------------------------------------------------------- | ------------------------------------------------------------------- |
-| The route through the codebase to a recurring question            | A verbatim copy of one living file, which a read gives current      |
-| What a schema or docs search resolved to, and what you made of it | The ranked guesses it returned on the way there                     |
-| The call or command sequence that turned out to be necessary      | A single tool call that answers in milliseconds                     |
-| The exact invocation that finally worked, with its directory      | The request restated, or notes on progress                          |
-| A working script or request body, committed whole                 | What running it printed - a reading, which the script gives current |
-| An interface that behaved differently from its documentation      | What a call returned, which the call gives current                  |
-| The passage itself, when its source cannot change under you       | A passage quoted out of something that can                          |
-| A proven absence - looked here and here, it is not there          | Anything not actually verified                                      |
-
-A restatement is not merely wasted space. Recall seeds on text alone, so a run
-that commits its own request as a task, a plan and a result has committed three
-near-copies of one sentence - and on the next similar question those three take
-the seed slots between them. Everything actually learned then ranks below them
-and is never reached.
-
-A search over a schema or a documentation index costs a round trip and comes
-back ranked, so it is the thing most worth not paying for twice. Commit what it
-**resolved to** - the operation and its shape, or the document, heading and line
-range - **and what you concluded from reading it**. The pointers alone make the
-next run repeat the reading; the conclusion alone cannot be checked. Both, in
-one subgraph, and the next run answers at once and verifies cheaply.
-
-When the index is over something pinned - a released spec, a versioned reference
-tree - go one further and carry the passage itself in a `file` node, headed with
-the documents and line ranges it was taken from. The pointer says where to look
-and the conclusion says what it meant, but only the passage saves the next run
-from opening the sources to find out what they actually said. Say in the node's
-text which kind of source it was, so a later run can see why a copy was allowed.
-
-### When to commit
-
-That test says what is worth keeping. It does not say when to write it down, and
-work that is never written down cost what it cost for nothing.
-
-Two things call for a commit while the run is still going:
-
-- **A search came back empty, or came back beside the point, and you went on to
-  work the answer out anyway.** That gap is the next run's gap too, and you are
-  the only one in a position to close it. It is the usual reason a memory stays
-  useless: every run pays for the same answer, no run writes it down.
-- **Something cost more than a `memory_load` will** - several reads, a fan-out,
-  a build, a long command, a delegated lookup - or produced an artifact that
-  works: a script, a query, a request body, the invocation that finally ran.
-
-And three moments must not pass without one:
-
-| Before                                 | Because                                                           |
-| -------------------------------------- | ----------------------------------------------------------------- |
-| returning your final answer            | the turn ends there, and nothing is written after it              |
-| handing off to another agent           | control moves and does not come back - what you know goes with it |
-| returning to the agent that forked you | only your answer returns; your transcript is dropped at the join  |
-
-Commit a piece of work when it is finished rather than saving all of it for one
-call at the end: a run that is interrupted, or that runs out of room, loses
-whatever was being held back. That is not licence to split one subgraph across
-calls - refs resolve only within a single `memory_commit`, so whatever links
-together is still committed together.
-
-### How to write it down
-
-**Commit the whole subgraph in one call.** A script with no record of what asked
-for it, or a fact with nothing that acts on it, is a memory nobody can use. Refs
-resolve only within a single `memory_commit`, so a subgraph split across calls
-arrives without its links.
-
-**Use `ref` (not `id`) for new nodes.** A new node uses `ref` as its local name
-(for example, `"ask"`, `"script"`), and edges connect them using those refs:
-
-```json
-{
-    "nodes": [
-        { "ref": "ask", "kind": "task", "text": "audit firewall rules for risky ports" },
-        { "ref": "script", "kind": "file", "text": "risk report generator", "file": "report.py" }
-    ],
-    "edges": [{ "from": "ask", "to": "script", "relation": "PRODUCED" }]
-}
-```
-
-Use `id` only when updating an existing node that is already in memory from a
-previous search or load. Never pass `id` when creating a new node, and do not
-pass both `ref` and `id` on the same node.
-
-**Do not re-commit what a search already returned.** A node that says what one
-already in memory says is folded into it, and its existing id comes back under
-your ref - so the links you asked for still land, on the memory that was already
-there.
-
-**Take the task text you were handed.** When your instructions give you the
-task text, commit that text verbatim as your `task` node and look nothing up for
-it. Agents that commit at the same moment cannot see each other; identical
-wording is what folds their nodes into one.
-
-**Grep for an entity before minting a node for it.** An endpoint, a command, a
-host, a tool, a file - anything that recurs across runs is one node the rest of
-the graph hangs off, and folding by similarity will not catch a second copy
-worded differently. `memory_grep` the exact string first, and attach your edges
-to what comes back. One grep per entity you are about to mint, for its exact
-string. A sentence describing the subject is not an entity, and neither is a
-task's text: a literal phrase misses every other wording of it, and a
-near-duplicate is folded anyway.
-
-A duplicated hub is worse than a missing one. It splits the graph into islands:
-the question reaches one copy, the artifact that answers it hangs off another,
-and the walk out from a seed cannot cross between them - so a memory that is
-present returns nothing, and nothing in the recollection says it happened.
-
-**Say where the content came from.** This is what lets an incomplete
-recollection be continued instead of believed:
-
-| The node holds                  | Name                                                                                                                          |
-| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| A fact about this codebase      | the file and the line range it was read from - `src/models/factory.ts:120-168`                                                |
-| Anything spanning several files | every one of them, each with its range, in the order they are read                                                            |
-| An API route or a behaviour     | the document and operation id, or the request sent and the status that came back                                              |
-| Something a document states     | document, heading and line range, next to what it states - the pointer is how the passage is checked, not a substitute for it |
-| Something a command established | the exact command, its arguments, and the directory it ran in                                                                 |
-| A plan                          | the steps, and where each step's target lives                                                                                 |
-| A negative result               | where you looked, so the search is not repeated                                                                               |
-
-**Write the text as the question.** Not the way the system that produced it
-names things, and with the identifying facts first - only the first 160
-characters appear in a recollection.
-
-| Instead of        | Write                                                                                      |
-| ----------------- | ------------------------------------------------------------------------------------------ |
-| `fix for the 409` | `A duplicate customer email returns 409, not 422 - retry is wrong (src/billing.ts:88-104)` |
-| `retry.ts`        | `Where retries are configured: one policy for all adapters, src/models/factory.ts:40-96`   |
-
-**Put the content in a file, not in the text.** This is the usual shape, not a
-special case: a script, a config, a query, a request body, a rendered table of
-findings, a passage worth keeping whole, an answer that took several sources to
-assemble - all of it is a `file` node split in two. The `text` describes the
-content and says where it came from; the file holds the content itself, whole
-and exactly as it was - the entire block, not a summary of it. Content in a file
-costs nothing until a `memory_load` asks for it, and comes back at
-`/memory/<id>.<ext>` to be read or run. Commit a node with no file only when the
-whole of what you know is one line long.
-
-**The file must exist in the workspace first.** `memory_commit` copies an
-existing file from the workspace; it is not an upload channel and does not
-write file contents from raw arguments. Write the file to the workspace first
-(using `write_file`, `apply_patch`, `copy_file`, or a command saving under
-`/workspace`), then pass its workspace path (e.g. `"file": "report.py"` or
-`"file": "/workspace/report.py"`). Write it with its provenance header (below)
-the first time: adding the header in a second write pays for the whole file
-twice.
-
-Do not commit files from the living codebase (use a pointer with file and line
-ranges instead - copies go stale silently), raw ephemeral command logs, or
-anything outside the workspace.
-
-**Name the sources inside the file as well as in the text.** The two halves
-arrive separately - a recollection shows the text, and only a later
-`memory_load` opens the file - so a file read on its own is an assertion with
-nothing behind it. Open it with a header naming every document, heading and line
-range the content came from, and when it was taken, then the content verbatim:
-
-```markdown
-<!-- reference-docs-1.4/overview.html.md:112-160 and
-     reference-docs-1.4/architecture.html.md:38-91
-     pinned 1.4 reference tree, read 2026-04-09 -->
-
-...the passages, whole and unedited...
-```
-
-Use whatever comment form the file's own format takes. A header costs two lines
-and is the difference between a copy that can be re-checked against its source
-and one that can only be believed.
-
-Make the file self-contained - it will be opened in a different workspace, so it
-takes its inputs as arguments and reads credentials from the environment - and
-say so in the text. **Give it a configurable output path.** `/memory` is
-read-only: a script that writes beside itself fails, while one that takes
-`--out` writes into the workspace and is reusable unchanged. Use a `snippet`
-only for the few lines that are read rather than run.
-
-A remembered script runs from where it is - the mount is readable, so
-`python3 /memory/<id>.py` or `node /memory/<id>.js` needs no copy first:
-
-```
-python3 /memory/01JD9Q7X8N2K4M6P8R0T2V4W6Y.py --out ./report.csv
-```
-
-**Read it before running it.** It is code an earlier run wrote, recalled by
-similarity: `memory_load` returns its contents, or its path when it is large, in
-which case read the file. Confirm it is the thing you want, and that its
-arguments are what you think, before executing anything.
-
-**Commit what produces the answer, not the material it was made from.** This is
-about what to keep, not what form to keep it in - whatever survives the test
-still goes in a file. A file the project holds: the pointer, never a copy - a
-copy goes stale silently and looks exactly as authoritative when it is wrong. An
-external call: the `operation` - route, auth, the parameters that mattered, the
-status a case returns - never the body that came back. A script: the file and
-the invocation that worked, never its output. What a run ESTABLISHED belongs in
-the node's text - that it works, what it was run against, the verdict that was
-the point; the rows it emitted do not.
-
-Two things fall outside that. An answer you assembled from several sources is a
-copy of none of them and exists nowhere in the project, so commit it, with a
-pointer node per source `INFORMED`ing it. And a passage from a pinned source
-does not go stale silently, so it may be kept whole, as described for indexes
-above.
-
-A body or a result set may still be worth keeping as a SPECIMEN - a shape to
-write against, a case to reproduce. Commit it as a `file` node whose text says
-what was asked, when, and that it is what came back then, never what the data
-is. Keep credentials out of the store, along with any personal data the specimen
-did not need: it outlives the session and every later run can read it.
-
-**Correct by superseding, never by editing.** Commit the new node and link it to
-the old one with `SUPERSEDES`. Recall then stops serving the wrong answer
-without destroying the record of why it changed.
-
-**Ask whether it will still be true next month.** Memory has no expiry and no
-reviewer. A durable fact about this project survives; a fact about this
-afternoon's state is how a graph becomes confidently wrong.
-
-### Preferences
-
-A `preference` is a standing instruction from the user, and it is not recalled
-like everything else: every preference you can see is rendered into a
-`<memory-preferences>` block at the start of every later run, each with its id.
-They apply unless that run's request contradicts them.
-
-So commit one only when the user's own words generalise - "always", "from now
-on", "I prefer", "never". A single request being fulfilled is not a standing
-instruction, and one committed by mistake is in every future prompt until
-something supersedes it.
-
-What the user says about THEMSELVES belongs here too, and for the same reason: a
-later run that has to ask again has already lost what the block is for. Their
-name and how they want to be addressed, the role they work in, the timezone
-their dates are in, which of several accounts, environments or repositories is
-theirs, the language or the units they want answers in. Commit what they stated,
-in their own terms - never what you inferred from how they happened to phrase a
-request, and never a credential or a secret, which is not a preference however
-it was offered.
-
-To change one, commit the replacement and link it to the id shown in that block
-with `SUPERSEDES`.
-
-### Forgetting
-
-Forget only what is wrong and has no successor. A superseded memory is already
-hidden from recall and should stay for the history, so `memory_forget` is for
-what should never have been written, not for what has been replaced.
+This project shares a persistent graph between runs. Reach it only through the
+`memory_*` tools. Never inspect, list, grep, or modify the store directly.
+
+Use only the capabilities you hold. If `memory_commit` is absent, do not update
+the graph. If `memory_forget` is absent, do not remove nodes.
+
+Memory exists to avoid paying twice for durable work. Reuse and verify useful
+prior work; do not treat the graph as an authority or a store for current API
+results.
+
+## Read
+
+Search before starting work that costs more than one cheap read or call:
+
+- On request arrival, search for the question before planning.
+- On handoff or fork arrival, search for the brief you received.
+- Before a substantial investigation, search for the question it would answer.
+- At a dead end, search for the newly identified missing fact.
+
+Do not repeat the same search in different words. Search again only when the
+question has changed.
+
+### Choose the retrieval tool
+
+| Need                                           | Tool            |
+| ---------------------------------------------- | --------------- |
+| A subject, however it was phrased              | `memory_search` |
+| A known name, path, id, host, flag, or command | `memory_grep`   |
+| Every occurrence of an exact string            | `memory_grep`   |
+| The complete content of a returned node        | `memory_load`   |
+
+Use `memory_search` with the complete natural-language question. Narrow broad
+results with `kinds`, `newer_than`, `limit`, `max_hops`, or `max_nodes`.
+
+Never use `memory_grep` as a generic first lookup or after an empty semantic
+search. An empty `memory_search` means no semantic match was recalled, not that
+the subject is absent. An empty `memory_grep` establishes only that the exact
+string is absent.
+
+Load every node you will rely on. Search results contain clipped descriptions,
+not complete node contents.
+
+### Read recollections as graphs
+
+A `<memory-recollection>` is an outline of nodes and relations, not a ranked
+list; the indentation is the graph. A root line reads `score kind id`; a root
+the walk reached without matching carries `--` instead of a score. An indented
+line is a connected node, prefixed by its relation: `→produced` means the line
+above produced it, `←informed` means it informed the line above.
+`PRODUCED`, `CALLS`, and `SUPERSEDES` form the reusable work; `INFORMED` adds
+background. A `+` reference points to an id already shown above.
+
+Node text is clipped to 160 characters. A file node adds one line with its
+`/memory/<id>.<ext>` path, size, and use count. Use `memory_load` to obtain the
+complete node and its usable path. Touch only paths returned by a `memory_*`
+tool.
+
+Direct store access is prohibited because it bypasses audience controls, may
+serve superseded nodes, does not record use, and can race with another writer.
+
+### Verify before reuse
+
+- For a pinned release, versioned specification, or immutable document, verify
+  that the recorded source still resolves.
+- For code, APIs, commands, and other living sources, verify the cited location,
+  route, or invocation still behaves as recorded.
+- Redo the investigation only when that cheap check fails or the cost of being
+  wrong justifies it.
+
+Read a remembered script before running it. Confirm its purpose, arguments,
+inputs, outputs, and credentials handling.
+
+### Keep memory out of ordinary answers
+
+Report findings and checkable sources, not the mechanism that found them. Do
+not expose `/memory` paths, node ids, or say that something was recalled or
+remembered. The exception is a request about the store itself, where ids and
+memory state are the subject.
+
+## Keep only durable value
+
+Commit something only when the next run would otherwise have to do meaningful
+work again and the result should still be valid next month.
+
+Keep:
+
+- A route, call, command, or invocation that retrieves a current answer.
+- A conclusion assembled from several sources, with every source named.
+- A proven absence, with the complete search boundary named.
+- A reusable plan, request body, query, or verified script.
+- A passage copied from an immutable, pinned source, with provenance.
+
+Do not keep:
+
+- Raw user input, progress notes, or a restatement of the request.
+- A value available from one cheap current call.
+- Live API results, inventories, counts, or raw command output.
+- Unverified, failed, partial, or speculative work.
+- A copy of a living project file that will silently become stale.
+- A duplicate of a node already returned by search.
+
+Remember the route when the answer is cheap and current. Remember the supported
+conclusion when deriving it is expensive. Remember the script, never what its
+last run printed.
+
+## Write the graph
+
+A node is one reusable thing. Its `text` is how it is found; an optional file
+holds content too large for one line.
+
+| Kind         | Use                                                    |
+| ------------ | ------------------------------------------------------ |
+| `task`       | The request that initiated the work                    |
+| `plan`       | A reusable approach that worked                        |
+| `fact`       | A durable truth with provenance                        |
+| `snippet`    | A few lines intended to be read                        |
+| `file`       | A complete reusable artifact                           |
+| `operation`  | An endpoint, command, or query that was used           |
+| `preference` | A standing instruction or user fact stated by the user |
+
+| Relation     | Meaning                                  |
+| ------------ | ---------------------------------------- |
+| `PRODUCED`   | The source produced the target           |
+| `CALLS`      | The source invokes the target            |
+| `SUPERSEDES` | The source replaces the stale target     |
+| `INFORMED`   | The source was background for the target |
+
+Put required reusable work on the `PRODUCED`, `CALLS`, or `SUPERSEDES` spine.
+Use `INFORMED` only for background that may be omitted under a tight recall
+budget. Direct `INFORMED` from the background fact to the work it informed.
+
+### Commit at the right time
+
+Commit finished durable work as soon as it is verified. Do not pass any of
+these points with uncommitted reusable work:
+
+- Before a final answer.
+- Before a handoff, because control does not return automatically.
+- Before returning from a fork, because only the branch answer rejoins.
+
+Commit one connected subgraph in one `memory_commit`. Refs resolve only inside
+that call; splitting connected nodes across calls loses their links.
+
+### Create nodes correctly
+
+- Use `ref` as the local name for every new node.
+- Use `id` only for an existing node returned by search or load.
+- Never set both `ref` and `id` on one node.
+- Link the task to what it produced and link artifacts to operations they call.
+- When instructions supply canonical task text, use it verbatim so parallel
+  commits fold together.
+- Do not recommit a node that search already returned; link to its existing id.
+
+Before creating a recurring entity node such as an endpoint, command, host,
+tool, or file, use `memory_grep` for its exact string. Reuse the existing id
+when found. Do not grep prose subjects or task text merely to avoid semantic
+near-duplicates; normal folding handles those.
+
+Write node text as the question a future user will ask. Put identifying facts
+first because recall shows only the first 160 characters. Keep the text short;
+put substantial content in a file node.
+
+### Record provenance
+
+Every durable claim must name how it can be checked:
+
+- Codebase fact: file and line range.
+- Multi-file conclusion: every file and range used.
+- API behavior: document and operation id, or request and returned status.
+- Document fact: document, heading, and opened line range.
+- Command result: exact command, arguments, and working directory.
+- Negative result: every location and query checked.
+
+A pointer without a conclusion makes the next run repeat the reading. A
+conclusion without a pointer cannot be checked. Store both.
+
+### Commit files safely
+
+Use a file node for scripts, configurations, request bodies, substantial
+answers, multi-source findings, and passages from pinned sources. The node text
+describes what the file does and its provenance; the file holds the complete
+content.
+
+The source file must already exist under `/workspace`. `memory_commit` copies
+it; it does not accept file contents. Never commit files outside the workspace,
+raw logs, live result sets, credentials, unnecessary personal data, or copies
+of living project files.
+
+Put provenance in the file itself as a short header. Make executable artifacts
+self-contained, take request-specific values as arguments, read credentials
+from the environment, and accept an output path under `/workspace`. The
+`/memory` mount is read-only.
+
+Commit a script only after it ran successfully against the intended environment
+and produced verified output. Commit its invocation and operations, not its
+output. When reusing a remembered script, run it from the path returned by
+`memory_load` only after reading it.
+
+A response body or result set may be kept only as an explicit specimen for
+development or reproduction. Its text must say what was requested, when it was
+captured, and that it is historical output rather than a current fact.
+
+### Correct and replace
+
+Never edit an existing memory as though its old claim had always been correct.
+Commit the replacement and connect it to the old node with `SUPERSEDES`. Recall
+then hides the stale node while preserving the history.
+
+## Preferences
+
+Use `preference` only for a standing instruction or personal fact the user
+explicitly states: wording such as "always", "from now on", "I prefer", or
+"never". Do not infer a preference from one request and never store a secret.
+
+Preferences appear in every later prompt. Replace one by committing the new
+preference with a `SUPERSEDES` edge to the old id.
+
+## Forget
+
+Use `memory_forget` only for information that should never have been stored and
+has no valid successor. Do not forget a corrected node: superseding already
+hides it and preserves why the correction happened.