@try-works/dsh-memory 0.1.18 → 0.1.20

package/src/SYSTEM.template.md

@@ -1,311 +1,311 @@
-# dsh-memory — how this memory system works
-
-Written by the plugin itself on every boot, describing the system **as built** rather than as
-planned. It is the manual for the machinery: read it before deciding where a fact belongs, or
-before trusting something found in the store.
-
-- Document version: {{documentVersion}}
-- Plugin version: {{version}}
-- Generated: {{generated}}
-- Store root: {{store}}
-
-## 1. Why this exists
-
-An agent forgets everything between sessions. This system gives it durable memory that (a)
-survives restarts, (b) travels between machines through git, and (c) stays plain markdown a
-human can read, diff and edit.
-
-Three intents drive every decision below:
-
-1. **The files are the truth.** The store is markdown. The search index, the ledger and every
-   cache are derived and may be deleted at any time — which is exactly why they are gitignored.
-   If a fact is not in a `.md` file, it is not remembered.
-2. **The model decides, the plugin writes.** Language models judge what matters well and produce
-   reliable structure badly. So a model is only ever asked *what* is durable; the plugin owns
-   *how* it is written — ids, formatting, routing, indexing. Nothing a model says is trusted to
-   be well-formed.
-3. **Memory must not become a junk drawer.** Every stage has a budget and a filter. Capturing
-   less and recalling the right thing beats capturing everything.
-
-## 2. The layers, and what belongs in each
-
-Every layer is **multi-layered**: the named file is an *index* of topics, and the entries live in
-one file per topic under a sibling directory. The vocabulary lives in one place, `src/entry.js`
-(`LAYER_CODES`, `LAYER_FILES`, `LAYER_DIRS`).
-
-```text
-{{diagram}}
-```
-
-{{layerTable}}
-
-Only {{workspaceOnly}} are workspace-only, because a map or a commit log of *one* repository is
-meaningless in a shared layer. `working.md` is per workspace for the same reason. Writing a
-workspace-only layer to `global` is refused rather than silently merged.
-
-### Why an index plus topic files, instead of one big file
-
-A single append-only file per layer grows without bound: slow to read, impossible to review in a
-diff, useless to grep. Splitting by topic keeps every file small and readable, and the index
-gives a one-screen overview.
-
-The index is **regenerated from the topic files after every write**, so it can never disagree
-with what it points at. It is a view, not a second source of truth. Adding a topic file by hand
-is fine — the next rebuild picks it up. Topic slugs preserve Unicode letters, so CJK and other
-non-Latin topics stay distinct files rather than collapsing into `untitled.md`. Id allocation
-spans the whole layer, so `NNNN` is unique per scope and layer rather than per file.
-
-## 2b. Memory may correctly write nothing
-
-The worker is not required to add a memory every interval or turn. Writing something merely
-to fill a gap pollutes search and creates false context. The relevance filter, the thin-signal
-floor, `NO_DURABLE_CONTENT`, and the DONE-only consolidation reply are all intentional no-op
-paths. A handled digest with zero facts is successful, writes zero entries, and is not retried.
-High signal and low noise are the goal; the common case is that nothing durable changed.
-
-## 2c. What capture refuses, and why failures retry
-
-Candidate material excludes harness-injected context (runtime snapshots, skill catalogs,
-policy notices, and this plugin's own injected block, which would be a feedback loop).
-Assistant material is the answer block, not private reasoning, and a bare status opener is
-skipped so a research answer arrives as findings. A FAILED summary (empty, unparseable or
-thrown) keeps its material and retries; a deliberate NO_DURABLE_CONTENT settles at once.
-
-## 2d. Which model does memory work
-
-Each call builds a ladder from the live registry: the configured summaryModel (a preference),
-then the session route, then everything else routable. The first model returning text wins; a
-model returning nothing or throwing is skipped and the same prompt goes to the next rung. The
-winner is remembered so the normal case costs one call, and a model that returned nothing is
-benched for 15 minutes at the end of the ladder rather than dropped. The ladder is capped at
-four models, and if none returns text the call errors so the session is retried.
-
-## 2e. Memory belongs to the main agent
-
-A subagent READS but does not write. Capture skips subagent sessions, every writing tool
-refuses with an explanation, and the injected context tells a child to report findings to its
-caller. Ownership is the reason: the parent delegated the work and its transcript carries the
-result, so a child-written entry is a second, context-poorer account of the same task.
-
-## 3. How a fact gets in — the write path
-
-There are two ways in, and the difference matters.
-
-**Explicitly**, with `memory_remember` (any layer), `memory_codebase` (map a module),
-`memory_history` (ingest commits). These are deterministic: the plugin allocates the id, stamps
-the date and source, appends the block to the right topic file, regenerates that layer's index,
-and reindexes only the files it touched.
-
-**Automatically**, from the session itself:
-
-1. **Capture** runs on turn end (throttled by `autoCaptureIntervalMs`, default {{captureInterval}}).
-   It projects only the events that arrived since a `lastSeq` watermark, so the work is
-   proportional to what is new, not to how long the session has run.
-2. The **relevance filter** decides what may reach a model at all: tool calls collapse to a
-   *count* (mechanics are not memory), user turns and assistant *gists* are clipped, bare
-   acknowledgements are dropped, and the whole candidate set is trimmed to a hard byte ceiling.
-   One exception is deliberate: the file paths a session's tool *calls* point at are kept as
-   traversal evidence, because they say where the agent actually worked.
-3. The **summarizer** turns that material into a handful of durable bullets, under standing
-   instructions about what is durable and what is not.
-4. **Consolidation** (cadence {{consolidateInterval}}, or on demand) reads pending digests,
-   decides what is worth storing and where, and hands the plugin a *decision* — never a file.
-
-Steps 2–4 are why this system does not drown: at every stage something is thrown away on
-purpose.
-
-### Why the writer, not the model, owns the format
-
-An entry is a heading plus a metadata block (`**Id:**`, `**Source:**`, `**Date:**`,
-`**Importance:**`, `**Status:**`, `**Format:**`). If a model were allowed to write that, one
-malformed block would corrupt the ledger, the id sequence and search at once.
-
-The model's contract is correspondingly small and line-oriented — one line per fact:
-
-```text
-- [<digest id> | global|<workspace:key> | <layer> | <importance>] <topic> :: <text>
-DONE <digest id>
-```
-
-This replaced a nested-JSON contract that failed repeatedly in practice: one invalid placeholder,
-one truncated brace, one reasoning preamble or one echoed prompt was enough to lose an entire
-pass. A line protocol parses per line, so a single bad line cannot kill a batch, prose is ignored
-instead of mined, and failure is safe — an unreadable reply is logged and retried, never guessed at.
-
-## 3b. Freshness: the entry says how fast it decays
-
-Every entry carries its own decay metadata, so staleness is determinable from the file alone —
-it survives a clone because it travels with the text.
-
-- `**Volatility:**` — `stable` ({{stableDays}} days: a language, a license, a convention),
-  `normal` ({{normalDays}} days: how a subsystem works), `volatile` ({{volatileDays}} days: a
-  port, a version in flight, anything that will be untrue soon).
-- `**Verified:**` — when the fact was last *confirmed true*. This is the age basis.
-- `**Valid-until:**` — a hard expiry for facts that genuinely end.
-
-Freshness is a property of the entry, not a constant applied to a write date: a language choice
-and a port number do not decay at the same rate, and only the writer knows which is which. When
-volatility is absent, time-bounded language still hints at it, then the normal window applies.
-
-`state.md` is the workspace overview — what the repository IS right now. It is replaced per
-section rather than appended, every section carries a `Verified` stamp, and a stale section is
-shown WITH its age in the injected context so it reads as a hypothesis to check rather than a
-fact to trust. Graded verdicts: fresh / aging / stale / unverified.
-
-## 3c. Working memory belongs to YOU
-
-`working.md` is **your file**, not the repository's and not durable memory. It answers *what am
-I in the middle of*: the task in hand, what you just did, and what comes next. Keep it current;
-nothing else writes there.
-
-It is deliberately separate from `state.md`. Those describe different owners: a repository has
-one current state, but several agents may work in it with entirely different intents — and one
-intent may span several repositories. Merging them would lose both meanings.
-
-| Section | Behaviour |
-| --- | --- |
-| Task, Next steps, Plan, Blocked by | **Replaced** on write: there is one current task, one current plan. |
-| Recent activity | A **rolling log**, newest last, trimmed oldest-first by entries and characters. |
-
-Working memory decays in **hours**, not days, so it is graded on its own scale (fresh / aging /
-stale / not started) and an unrecorded file is called out rather than hidden — silence would
-otherwise read as "no working memory" when it means "nothing written yet".
-
-Write it with `memory_working` (a section, or activity notes), or edit the file directly. It is
-yours: read it, edit it, keep it honest. When something there stops changing, promote it to a
-layered entry and let the file go quiet.
-
-## 4. How a fact gets out
-
-- **Injection** (`agent/pre-step`) puts a bounded context card at the top of a session: the
-  active goal, the workspace working-memory head, recent learnings, and the topics already mapped
-  for this workspace.
-- **`memory_search`** is the explicit path: lexical FTS5 over every layer file, ranked by
-  importance and recency, returning `file:line` citations so a claim can be checked.
-- **The context card** assembles lanes (working, episodes, learnings, codebase) under a token
-  budget, with floors and ceilings per lane.
-
-Search returns *pointers*, not truth: always eligible to be stale, always checkable.
-
-### Optional rerank
-
-`memory_search` can ask a model to reorder hits. It is off by default and strictly advisory:
-any failure returns the deterministic order, because search must never depend on a model.
-
-## 5. Scope — global versus workspace
-
-A **workspace** is one associated local folder or repository. The key is resolved so it is
-identical across machines: explicit input, then remote URL, then folder basename. `memory.json`
-holds the committed registry of keys; `state/associations.json` holds device-local paths, because
-paths differ per machine and must never be committed.
-
-Facts that are true *everywhere* — identity, preferences, standing rules, cross-repo lessons — go
-global. Facts tied to one repository go to that workspace. When unsure, ask whether it would be
-misleading in a different repository; if yes, it is a workspace fact.
-
-## 6. What is committed, and what is derived
-
-| Committed | Derived (gitignored, regenerable) |
-| --- | --- |
-| every `.md` layer file and topic file | `index/` — the FTS5 search index |
-| `SYSTEM.md` (this document) | `state/` — watermarks, associations, tombstones |
-| `memory.json` (workspace registry) | `digests/` — captured session material |
-| `.gitignore` | `logs/` — diagnostics |
-
-The line is: **can it be rebuilt from the committed markdown?** If yes it is derived, and it is
-safe to delete. If no, it is committed. Tombstones are the one deliberate exception — they are
-derived state, so a fresh clone re-learns a forgotten fact only if it is re-derived.
-
-## 7. Forgetting, and keeping memory honest
-
-- **Forget** supersedes an entry in place (history is never deleted) and records a hash-only
-  tombstone so the same fact cannot be silently re-added. It is reversible with undo.
-- **Freshness** flags entries that are stale or past their `Valid-until`, and a refresh pass asks
-  a model for keep / update / supersede per entry. Superseding keeps the old text.
-- Entries may carry `**Valid-until:**` for facts that genuinely expire.
-
-## 8. Models and cost
-
-Memory work is extraction, not conversation, so it does not run at the session's reasoning
-budget. `memoryReasoningEffort` (default `{{effort}}`) applies to every memory call, and a model
-that rejects that effort is retried without it rather than failing every write. `summaryModel`
-optionally points memory writes at a cheaper model; empty means the session's own model.
-
-Replies are assembled from **text blocks only**. A reasoning model streams its thinking as
-separate blocks, and folding those into the reply prepends prose to an answer that is supposed to
-be parseable.
-
-## 9. Cadences, and why they are not on the write path
-
-Nothing expensive happens synchronously with a write. Capture, consolidation, refresh, history
-ingest and git sync all run on throttle windows, on the pre-step hook, and on an idle ticker so
-they still run when nobody is chatting.
-
-| Cadence | Default |
-| --- | --- |
-| capture per session | {{captureInterval}} |
-| consolidation | {{consolidateInterval}} |
-| freshness refresh | {{refreshInterval}} |
-| commit history ingest | {{historyInterval}} |
-| git pull/push | {{syncInterval}} |
-| local commit debounce | {{commitDebounce}} |
-
-Sync failures are never swallowed: a failed pull or push is logged, recorded in `state/sync.json`,
-surfaced by `status()`, reported by `memory_sync`, and leaves a `state/CONFLICT.md` marker that
-the next clean sync clears.
-
-## 9b. The scheduled tasks layer
-
-`global/tasks/` is not a memory layer and holds no memories. It is a portable backup of the DSH
-scheduled tasks on this machine, and it exists because the schedule store is the only copy of them:
-it is in no git repository, and the host DELETES a task when the session that owns it stops. A task
-can therefore vanish with nothing to observe.
-
-One JSON file per task, plus a regenerated `index.md`. A file holds the task's record - id, kind,
-title, prompt, and the selector that says when it runs - and its lifecycle state. The owning session
-and the delivery history are deliberately NOT stored: they are machine-local, and carrying a session
-id to another machine would make a restored task fail, because the session it names does not exist
-there.
-
-Because the task files live in this store and are not gitignored, a push carries them to your other
-machines, where they are re-armed on boot.
-
-The states, and what each one means:
-
-| state | meaning |
-| --- | --- |
-| `active` | armed in the live store, waiting for its next occurrence |
-| `pending` | in the backup, not in the live store; a restore re-arms it |
-| `paused` | held back on purpose. Every automatic pass leaves it alone |
-| `stopped` | was armed, and its owning session stopped, so the host deleted it |
-| `failed` | was due and has still not delivered. The host records no failure of its own, so this is what is observable |
-| `orphaned` | armed, but the session that owns it no longer exists, so it can never fire |
-| `skipped` | captured, but its kind is not one we can re-arm, so a restore refuses it |
-| `done` | delivered, or its recurrence is exhausted |
-
-Two cadences, both off the write path. The **backup** runs with the sync cadence and is additive:
-it never deletes, so a stale backup cannot wipe a schedule. The **restore** runs once per process at
-the first real session, because a task needs a live session to own it, and it binds each restored
-task to that session - you are never asked which one. It matches tasks by CONTENT, not by id, since
-the schedule service mints a fresh id on every create.
-
-`memory_tasks` reports the whole picture and can `backup`, `restore`, `pause` or `resume` on
-demand. Holding a task back is a decision, and it outranks every automatic pass: a `paused` task is
-never silently re-armed.
-
-## 10. Current state of this store
-
-{{storeState}}
-
-## 11. How to work with this system
-
-- **Prefer `memory_search` over guessing.** The store is small and cheap to query.
-- **Write when you learn something durable**, not when you finish a task. A fact that only
-  mattered for one turn is not memory.
-- **One fact per entry**, with concrete identifiers: paths, commands, config keys, versions.
-- **Name the topic well.** For `codebase` use the path or subsystem name, so re-discovery updates
-  the same topic file instead of fragmenting it.
-- **Say why, not just what.** A decision without its rationale cannot be re-evaluated later.
-- **Supersede, never delete.** History is the point.
-- If this document ever disagrees with the code, **the code wins** — report the drift so the
-  document can be regenerated.
+# dsh-memory — how this memory system works
+
+Written by the plugin itself on every boot, describing the system **as built** rather than as
+planned. It is the manual for the machinery: read it before deciding where a fact belongs, or
+before trusting something found in the store.
+
+- Document version: {{documentVersion}}
+- Plugin version: {{version}}
+- Generated: {{generated}}
+- Store root: {{store}}
+
+## 1. Why this exists
+
+An agent forgets everything between sessions. This system gives it durable memory that (a)
+survives restarts, (b) travels between machines through git, and (c) stays plain markdown a
+human can read, diff and edit.
+
+Three intents drive every decision below:
+
+1. **The files are the truth.** The store is markdown. The search index, the ledger and every
+   cache are derived and may be deleted at any time — which is exactly why they are gitignored.
+   If a fact is not in a `.md` file, it is not remembered.
+2. **The model decides, the plugin writes.** Language models judge what matters well and produce
+   reliable structure badly. So a model is only ever asked *what* is durable; the plugin owns
+   *how* it is written — ids, formatting, routing, indexing. Nothing a model says is trusted to
+   be well-formed.
+3. **Memory must not become a junk drawer.** Every stage has a budget and a filter. Capturing
+   less and recalling the right thing beats capturing everything.
+
+## 2. The layers, and what belongs in each
+
+Every layer is **multi-layered**: the named file is an *index* of topics, and the entries live in
+one file per topic under a sibling directory. The vocabulary lives in one place, `src/entry.js`
+(`LAYER_CODES`, `LAYER_FILES`, `LAYER_DIRS`).
+
+```text
+{{diagram}}
+```
+
+{{layerTable}}
+
+Only {{workspaceOnly}} are workspace-only, because a map or a commit log of *one* repository is
+meaningless in a shared layer. `working.md` is per workspace for the same reason. Writing a
+workspace-only layer to `global` is refused rather than silently merged.
+
+### Why an index plus topic files, instead of one big file
+
+A single append-only file per layer grows without bound: slow to read, impossible to review in a
+diff, useless to grep. Splitting by topic keeps every file small and readable, and the index
+gives a one-screen overview.
+
+The index is **regenerated from the topic files after every write**, so it can never disagree
+with what it points at. It is a view, not a second source of truth. Adding a topic file by hand
+is fine — the next rebuild picks it up. Topic slugs preserve Unicode letters, so CJK and other
+non-Latin topics stay distinct files rather than collapsing into `untitled.md`. Id allocation
+spans the whole layer, so `NNNN` is unique per scope and layer rather than per file.
+
+## 2b. Memory may correctly write nothing
+
+The worker is not required to add a memory every interval or turn. Writing something merely
+to fill a gap pollutes search and creates false context. The relevance filter, the thin-signal
+floor, `NO_DURABLE_CONTENT`, and the DONE-only consolidation reply are all intentional no-op
+paths. A handled digest with zero facts is successful, writes zero entries, and is not retried.
+High signal and low noise are the goal; the common case is that nothing durable changed.
+
+## 2c. What capture refuses, and why failures retry
+
+Candidate material excludes harness-injected context (runtime snapshots, skill catalogs,
+policy notices, and this plugin's own injected block, which would be a feedback loop).
+Assistant material is the answer block, not private reasoning, and a bare status opener is
+skipped so a research answer arrives as findings. A FAILED summary (empty, unparseable or
+thrown) keeps its material and retries; a deliberate NO_DURABLE_CONTENT settles at once.
+
+## 2d. Which model does memory work
+
+Each call builds a ladder from the live registry: the configured summaryModel (a preference),
+then the session route, then everything else routable. The first model returning text wins; a
+model returning nothing or throwing is skipped and the same prompt goes to the next rung. The
+winner is remembered so the normal case costs one call, and a model that returned nothing is
+benched for 15 minutes at the end of the ladder rather than dropped. The ladder is capped at
+four models, and if none returns text the call errors so the session is retried.
+
+## 2e. Memory belongs to the main agent
+
+A subagent READS but does not write. Capture skips subagent sessions, every writing tool
+refuses with an explanation, and the injected context tells a child to report findings to its
+caller. Ownership is the reason: the parent delegated the work and its transcript carries the
+result, so a child-written entry is a second, context-poorer account of the same task.
+
+## 3. How a fact gets in — the write path
+
+There are two ways in, and the difference matters.
+
+**Explicitly**, with `memory_remember` (any layer), `memory_codebase` (map a module),
+`memory_history` (ingest commits). These are deterministic: the plugin allocates the id, stamps
+the date and source, appends the block to the right topic file, regenerates that layer's index,
+and reindexes only the files it touched.
+
+**Automatically**, from the session itself:
+
+1. **Capture** runs on turn end (throttled by `autoCaptureIntervalMs`, default {{captureInterval}}).
+   It projects only the events that arrived since a `lastSeq` watermark, so the work is
+   proportional to what is new, not to how long the session has run.
+2. The **relevance filter** decides what may reach a model at all: tool calls collapse to a
+   *count* (mechanics are not memory), user turns and assistant *gists* are clipped, bare
+   acknowledgements are dropped, and the whole candidate set is trimmed to a hard byte ceiling.
+   One exception is deliberate: the file paths a session's tool *calls* point at are kept as
+   traversal evidence, because they say where the agent actually worked.
+3. The **summarizer** turns that material into a handful of durable bullets, under standing
+   instructions about what is durable and what is not.
+4. **Consolidation** (cadence {{consolidateInterval}}, or on demand) reads pending digests,
+   decides what is worth storing and where, and hands the plugin a *decision* — never a file.
+
+Steps 2–4 are why this system does not drown: at every stage something is thrown away on
+purpose.
+
+### Why the writer, not the model, owns the format
+
+An entry is a heading plus a metadata block (`**Id:**`, `**Source:**`, `**Date:**`,
+`**Importance:**`, `**Status:**`, `**Format:**`). If a model were allowed to write that, one
+malformed block would corrupt the ledger, the id sequence and search at once.
+
+The model's contract is correspondingly small and line-oriented — one line per fact:
+
+```text
+- [<digest id> | global|<workspace:key> | <layer> | <importance>] <topic> :: <text>
+DONE <digest id>
+```
+
+This replaced a nested-JSON contract that failed repeatedly in practice: one invalid placeholder,
+one truncated brace, one reasoning preamble or one echoed prompt was enough to lose an entire
+pass. A line protocol parses per line, so a single bad line cannot kill a batch, prose is ignored
+instead of mined, and failure is safe — an unreadable reply is logged and retried, never guessed at.
+
+## 3b. Freshness: the entry says how fast it decays
+
+Every entry carries its own decay metadata, so staleness is determinable from the file alone —
+it survives a clone because it travels with the text.
+
+- `**Volatility:**` — `stable` ({{stableDays}} days: a language, a license, a convention),
+  `normal` ({{normalDays}} days: how a subsystem works), `volatile` ({{volatileDays}} days: a
+  port, a version in flight, anything that will be untrue soon).
+- `**Verified:**` — when the fact was last *confirmed true*. This is the age basis.
+- `**Valid-until:**` — a hard expiry for facts that genuinely end.
+
+Freshness is a property of the entry, not a constant applied to a write date: a language choice
+and a port number do not decay at the same rate, and only the writer knows which is which. When
+volatility is absent, time-bounded language still hints at it, then the normal window applies.
+
+`state.md` is the workspace overview — what the repository IS right now. It is replaced per
+section rather than appended, every section carries a `Verified` stamp, and a stale section is
+shown WITH its age in the injected context so it reads as a hypothesis to check rather than a
+fact to trust. Graded verdicts: fresh / aging / stale / unverified.
+
+## 3c. Working memory belongs to YOU
+
+`working.md` is **your file**, not the repository's and not durable memory. It answers *what am
+I in the middle of*: the task in hand, what you just did, and what comes next. Keep it current;
+nothing else writes there.
+
+It is deliberately separate from `state.md`. Those describe different owners: a repository has
+one current state, but several agents may work in it with entirely different intents — and one
+intent may span several repositories. Merging them would lose both meanings.
+
+| Section | Behaviour |
+| --- | --- |
+| Task, Next steps, Plan, Blocked by | **Replaced** on write: there is one current task, one current plan. |
+| Recent activity | A **rolling log**, newest last, trimmed oldest-first by entries and characters. |
+
+Working memory decays in **hours**, not days, so it is graded on its own scale (fresh / aging /
+stale / not started) and an unrecorded file is called out rather than hidden — silence would
+otherwise read as "no working memory" when it means "nothing written yet".
+
+Write it with `memory_working` (a section, or activity notes), or edit the file directly. It is
+yours: read it, edit it, keep it honest. When something there stops changing, promote it to a
+layered entry and let the file go quiet.
+
+## 4. How a fact gets out
+
+- **Injection** (`agent/pre-step`) puts a bounded context card at the top of a session: the
+  active goal, the workspace working-memory head, recent learnings, and the topics already mapped
+  for this workspace.
+- **`memory_search`** is the explicit path: lexical FTS5 over every layer file, ranked by
+  importance and recency, returning `file:line` citations so a claim can be checked.
+- **The context card** assembles lanes (working, episodes, learnings, codebase) under a token
+  budget, with floors and ceilings per lane.
+
+Search returns *pointers*, not truth: always eligible to be stale, always checkable.
+
+### Optional rerank
+
+`memory_search` can ask a model to reorder hits. It is off by default and strictly advisory:
+any failure returns the deterministic order, because search must never depend on a model.
+
+## 5. Scope — global versus workspace
+
+A **workspace** is one associated local folder or repository. The key is resolved so it is
+identical across machines: explicit input, then remote URL, then folder basename. `memory.json`
+holds the committed registry of keys; `state/associations.json` holds device-local paths, because
+paths differ per machine and must never be committed.
+
+Facts that are true *everywhere* — identity, preferences, standing rules, cross-repo lessons — go
+global. Facts tied to one repository go to that workspace. When unsure, ask whether it would be
+misleading in a different repository; if yes, it is a workspace fact.
+
+## 6. What is committed, and what is derived
+
+| Committed | Derived (gitignored, regenerable) |
+| --- | --- |
+| every `.md` layer file and topic file | `index/` — the FTS5 search index |
+| `SYSTEM.md` (this document) | `state/` — watermarks, associations, tombstones |
+| `memory.json` (workspace registry) | `digests/` — captured session material |
+| `.gitignore` | `logs/` — diagnostics |
+
+The line is: **can it be rebuilt from the committed markdown?** If yes it is derived, and it is
+safe to delete. If no, it is committed. Tombstones are the one deliberate exception — they are
+derived state, so a fresh clone re-learns a forgotten fact only if it is re-derived.
+
+## 7. Forgetting, and keeping memory honest
+
+- **Forget** supersedes an entry in place (history is never deleted) and records a hash-only
+  tombstone so the same fact cannot be silently re-added. It is reversible with undo.
+- **Freshness** flags entries that are stale or past their `Valid-until`, and a refresh pass asks
+  a model for keep / update / supersede per entry. Superseding keeps the old text.
+- Entries may carry `**Valid-until:**` for facts that genuinely expire.
+
+## 8. Models and cost
+
+Memory work is extraction, not conversation, so it does not run at the session's reasoning
+budget. `memoryReasoningEffort` (default `{{effort}}`) applies to every memory call, and a model
+that rejects that effort is retried without it rather than failing every write. `summaryModel`
+optionally points memory writes at a cheaper model; empty means the session's own model.
+
+Replies are assembled from **text blocks only**. A reasoning model streams its thinking as
+separate blocks, and folding those into the reply prepends prose to an answer that is supposed to
+be parseable.
+
+## 9. Cadences, and why they are not on the write path
+
+Nothing expensive happens synchronously with a write. Capture, consolidation, refresh, history
+ingest and git sync all run on throttle windows, on the pre-step hook, and on an idle ticker so
+they still run when nobody is chatting.
+
+| Cadence | Default |
+| --- | --- |
+| capture per session | {{captureInterval}} |
+| consolidation | {{consolidateInterval}} |
+| freshness refresh | {{refreshInterval}} |
+| commit history ingest | {{historyInterval}} |
+| git pull/push | {{syncInterval}} |
+| local commit debounce | {{commitDebounce}} |
+
+Sync failures are never swallowed: a failed pull or push is logged, recorded in `state/sync.json`,
+surfaced by `status()`, reported by `memory_sync`, and leaves a `state/CONFLICT.md` marker that
+the next clean sync clears.
+
+## 9b. The scheduled tasks layer
+
+`global/tasks/` is not a memory layer and holds no memories. It is a portable backup of the DSH
+scheduled tasks on this machine, and it exists because the schedule store is the only copy of them:
+it is in no git repository, and the host DELETES a task when the session that owns it stops. A task
+can therefore vanish with nothing to observe.
+
+One JSON file per task, plus a regenerated `index.md`. A file holds the task's record - id, kind,
+title, prompt, and the selector that says when it runs - and its lifecycle state. The owning session
+and the delivery history are deliberately NOT stored: they are machine-local, and carrying a session
+id to another machine would make a restored task fail, because the session it names does not exist
+there.
+
+Because the task files live in this store and are not gitignored, a push carries them to your other
+machines, where they are re-armed on boot.
+
+The states, and what each one means:
+
+| state | meaning |
+| --- | --- |
+| `active` | armed in the live store, waiting for its next occurrence |
+| `pending` | in the backup, not in the live store; a restore re-arms it |
+| `paused` | held back on purpose. Every automatic pass leaves it alone |
+| `stopped` | was armed, and its owning session stopped, so the host deleted it |
+| `failed` | was due and has still not delivered. The host records no failure of its own, so this is what is observable |
+| `orphaned` | armed, but the session that owns it no longer exists, so it can never fire |
+| `skipped` | captured, but its kind is not one we can re-arm, so a restore refuses it |
+| `done` | delivered, or its recurrence is exhausted |
+
+Two cadences, both off the write path. The **backup** runs with the sync cadence and is additive:
+it never deletes, so a stale backup cannot wipe a schedule. The **restore** runs once per process at
+the first real session, because a task needs a live session to own it, and it binds each restored
+task to that session - you are never asked which one. It matches tasks by CONTENT, not by id, since
+the schedule service mints a fresh id on every create.
+
+`memory_tasks` reports the whole picture and can `backup`, `restore`, `pause` or `resume` on
+demand. Holding a task back is a decision, and it outranks every automatic pass: a `paused` task is
+never silently re-armed.
+
+## 10. Current state of this store
+
+{{storeState}}
+
+## 11. How to work with this system
+
+- **Prefer `memory_search` over guessing.** The store is small and cheap to query.
+- **Write when you learn something durable**, not when you finish a task. A fact that only
+  mattered for one turn is not memory.
+- **One fact per entry**, with concrete identifiers: paths, commands, config keys, versions.
+- **Name the topic well.** For `codebase` use the path or subsystem name, so re-discovery updates
+  the same topic file instead of fragmenting it.
+- **Say why, not just what.** A decision without its rationale cannot be re-evaluated later.
+- **Supersede, never delete.** History is the point.
+- If this document ever disagrees with the code, **the code wins** — report the drift so the
+  document can be regenerated.