curate

Files (1)

• SKILL.md

SKILL.md (first lines)

# Memory curator

You are the only writer of the ummanu's memory canon (`state/memory/facts` in the instance
repository, written through `curator memory-write`). Agents only read memory. You look at the traces of
every head and move durable facts into the canon.

The canon is markdown facts in a Git journal. The index is derived. One fact is one `.md` file.

## Procedure

### 1. Take the fresh batch

```
python3 -P -m ummanu automations curator harvest [--project <canonical-id|unknown|review:po>]
```

Run it from your own workspace (the run's starting working directory is the curator worktree). **Do not
`cd`** into other repositories: the code and the watermark are taken from the workspace, and leaving it
splits them. Write facts through `curator memory-write` (see step 4); you never edit the canon by hand
and you run no Git operations.

The helper returns a redacted, deterministic bounded batch (secrets already stripped) of new turns since
the last watermark. "No new turns" means there is no work and you exit: the helper has already advanced any
complete non-emitting scan cursors, and there is no pending work for step 5. The service environment sets
maximum signal turns, source bytes and sources, plus per-source rows/records and personal-memory bytes. A
changed personal-memory file above its byte cap is rejected before it reaches this prompt. A trailing incomplete
JSONL record is source-local: its incomplete bytes remain unwatermarked, but complete prefixes and independent
sources still settle. The helper reports that partial source and retries it from its last complete cursor after
the writer finishes; it is never a role-wide clean skip.

The first fact-bearing harvest writes an identity-bound pending record. Repeating harvest before advance
returns that same batch even if sources have grown. The selector is part of that identity: use the same
`--project <canonical-id|unknown|review:po>` for harvest and advance, and do not switch between a selected project and the
explicit all-backlog mode. Do not alter the state directory or pending file. Advance accepts only that exact
pending identity and moves only its listed partial cursors; a refusal means stop and let the operator resolve
the stale or foreign pending record. To inspect work without changing state, use
`python3 -P -m ummanu automations curator backlog [--project <canonical-id|unknown|review:po>] [--json]`; it emits aggregate
metadata only, never source text.

The batch comes from two kinds of source:

- **Transcripts**: new turns of sessions. For some runtimes that is line-based JSONL per session; for
  others it is rows in the runtime's own state database.
- **Personal memory of the agent runtimes**: new or changed memory files a head wrote for itself
  (excluding the index file, which is a table of contents, not a fact). That material is already
  distilled: the head decided it was worth remembering, so the signal is denser than a transcript. Those
  files are **read-only** — you do not edit or delete them, you only read them and carry them into the
  canon. Some runtimes keep one memory for the whole installation rather than per project, so those
  entries arrive with no working directory; that is expected, not a bug.

### 2. Extract durable facts

Write **significant facts about the current state of the system** — how the ummanu, the
infrastructure, the user and the projects are built and behave **now** — so a future session does not
have to derive it again. Not a chronicle of decisions.

- **State, not events.** The canon describes how the system is built, not what was "decided, changed or
  added". If a decision changed the system, record the resulting **state**, not the fact that the
  decision was taken. "The curator pushes the canon" — yes. "We agreed that the curator will push" — no.
- **Set a high bar.** Three substantial facts beat ten small ones. The test: "will this still be true and
  useful in a month as a description of how the system works?" If not, do not write it.
- **NOT durable:** the narrative of a work session, debugging lessons, one-off bugs and flakes, small
  implementation details, anything that lives in the code or in Git, transient state. When in doubt, skip.
- **Filter out changelog facts.** A pull request or card number, an exact date, "the first run", "the
  status as of X" are not facts by themselves, they are chronicle. Write so that the fact stays true
  without a merge date: the resulting state of the system, not the event.
- **Do not write counter-history.** The body of a fact needs no "no longer X", "it used to be Y",
  "deprecated", "if you see the old one". If a new fact replaces an old one, rewrite the current card and
  remove the old one through `supersedes`; the history of the change stays in Git, not in the memory text.

Fact format:

- First paragraph: the current state only, short and self-sufficient.
- A `Why:` line is optional. Add it only when there is a working invariant there: what an agent must or
  must not do because of this fact. Do not use `Why:` for the history of a decision, dates, pull requests,
  commits, or an explanation of what came before.
- Size roughly 80–200 tokens. One fact is one thought. Before writing, check: with all change history
  removed, is there still a short description of the current state? If not, do not write it.

Scope follows the source's displayed route, not a guessed path or a directory name:

- `project:<canonical-id>` — a source routed through one registered binding's canonical `id`. A fact about
  the task pipeline (board, runtime, curator, ummanu) belongs to `project:ummanu`.
- `global` — only material explicitly marked `global`, such as a runtime's installation-wide memory.
- `review:po` — a durable conclusion that cannot be assigned to one project without product-owner
  judgment. This is a pending triage basket, not operational truth.
- `unknown` is a source selector, not a fact scope. If independently reliable context establishes one owner,
  write the fact to that project. Otherwise, every durable current conclusion from an `unknown` source goes
  to `review:po` with tags `pending-review,unknown-source`; name candidate project scopes when evidence supports
  them, or state `owner unresolved`. Ownership ambiguity is not a reason to discard a durable conclusion.

The route is authoritative only when discovery found one normalized registry match: every valid binding's checkout,
or its workspace tree when it has a safe optional `orca_binding`. Prefixes, unregistered paths and ambiguous routes
stay `unknown`; a missing `orca_binding` never invents a workspace route. Observer workspace tokens restore the
canonical `sprint:` prefix. One registered reservation routes to that project. Multiple distinct registered
reservations route to `review:po`; malformed, duplicate or unregistered reservation sets remain `unknown`.

For a `review:po` source, first separate conclusions whose owner is unambiguous and write those directly to the
corresponding `project:<canonical-id>`. Only a genuinely shared or ownership-ambiguous current conclusion belongs
in `review:po`. Such a fact must use the tags `pending-review,multi-project`, name its candidate project scopes and
state why PO judgment is required. Do not create a review fact merely to record that a session was examined or
that it contained no durable fact. The same ban on changelog, rejected alternatives and implementation history
applies to the review basket.

Apply the same separation to an `unknown` source. Do not silently skip a durable conclusion merely because its
owner remains unresolved: route it to `review:po` with `pending-review,unknown-source`, candidate scopes when
available (otherwise `owner unresolved`), and why ownership cannot be established. Do not create a review fact
merely because an unknown session was examined or contained no durable conclusion.

**Personal memory of the runtimes** (the second kind of source) is read through the same barrier and the
same durability bar as transcripts: the file is already one head's distillate, but it is not yours, so
anything doubtful is still skipped. Conversion rules:

- the source file's own type field is not carried over as is: it is an axis of "what kind of fact this
  is", not a canon tag. Use it as a hint when choosing scope and wording.
- Scope follows the file's displayed canonical route by the same rule. A runtime's installation-wide memory
  is explicitly `global`; an `unknown` file is not assigned by default.
- Those files are a **read-only** source: do not edit them, do not delete them, only carry them into the
  canon.

From vladmesh/ummanu, Apache-2.0.

More from vladmesh/ummanu