Memory promotion — episodic notes into semantic knowledge

Scratch conventions

• Scratch is an ordinary context — scratch-{agent}, or scratch-{agent}-{topic} when sessions must not mix. There is no TTL and none is planned: nothing in this store expires silently.
• Source ids name the session, globally uniquely: session:{agent}:{id} (the id a UUID or an equally unique token) for the running note, with /{doc} appended when one session produces several documents. Uniqueness is load-bearing: import is retract-then-apply per source id, so two agents sharing a bare session:{id} in one permanent context would silently replace each other's assertions. The id survives promotion, so a promoted fact's citation still names the session that produced it — provenance rides the existing source/citation machinery.
• Always declare date when storing passages. date ?? stored_at is the assertion time every windowed graph read (since/until, ADR 0011) and the staleness audit run on. An associations-only source stores no metadata and is invisible to every window — store at least the session note as a passage.
• Tag scratch sources with the session's topics; passage search's tags filter is how a later session finds its own trail.

The promotion procedure

1. Review the scratch context: recall/query, or taguru communities --context scratch-… for a themed overview once the scratch has grown (--into NAME names the derived context — default NAME::communities; --group NAME summarizes a whole group instead; --dry-run/--json preview and machine output).
2. Graph path — one call when the structure is already right (ADR 0018): when the keepers are the scratch's own structured associations (written by the session itself, nothing left to extract), the promote MCP tool (POST /contexts/{scratch}/promote, body {into, sources, audit?}, ?dry_run=true to preview) bundles steps 4–5: each named source moves whole — passage, date, tags, and only its own share of every edge's weight — with no LLM anywhere in the path. Source ids survive, so promoted citations still name the session; per-source retract-then-apply makes re-promotion idempotent; the destination must already exist and its own schema judges the incoming batches; sources shares the API's list ceiling (1,000 ids per call — over_limit past it; split a bigger promotion); the landing-zone audit rides back in the response (audit: false opts out), and a dry run previews the transfer batches only, with nothing written and no audit. What stays yours is exactly the judgment: which sources (step 1's review), the audit's candidates (step 5's rubric), and retirement (step 6). Steps 3–4 below are the text path, needed only when the keepers exist as prose that still wants extraction.
3. Extract the keepers with taguru extract over the session passages (or hand-write the batch), targeting the permanent context — keeping the session:{agent}:{id} source ids and the dates: --source-id, --date, and --tag bake all three conventions into the emitted batch directly (ADR 0017), so no hand-editing of the generated file remains. Resolve spellings against the permanent context rather than forking its vocabulary: export it (taguru export --out DIR) and hand the export to --vocabulary (ADR 0015), which steers the extraction toward the context's existing spellings and admits them through validation — the manual resolve/resolve_label pass remains for hand-written batches. --coverage (ADR 0016) reports what the extraction left behind, sentence by sentence — the mechanical floor under the review this step owes.
4. Import via POST /import / taguru import — retract-then-apply per source makes re-promoting the same session idempotent.
5. Audit the landing zone: taguru consolidation --context NAME (or the audit_consolidation MCP tool) — --checks LIST narrows the sections (comma-separated merge,contradiction,staleness; default all three), --into NAME names the judgment context (default NAME::consolidation), --dry-run previews. Promotion is exactly when merge twins and contradictions appear; judgments are proposals keyed by evidence fingerprint (re-runs over an unchanged graph cost zero LLM calls), and applying an accepted one is always an ordinary write — an alias, a retraction, a negative-weight assertion, or a re-import.
6. Retire the promoted scratch: retract_source the promoted session sources (or delete the scratch context once everything promoted). Unpromoted scratch stays until someone decides otherwise — that is the posture, not a gap.

What not to do

• Don't promote into a fresh spelling universe — the resolve-first rule in step 3 (and, on the graph path, the landing-zone audit's merge candidates) is what keeps one referent one spelling.
• Don't invent an end date for a superseded fact: assert the new fact with its own date; as-of queries (until) and the audit's dated rows sort the regimes out (ADR 0011 §6).
• Don't auto-expire scratch, and don't skip the audit on a large promotion — an unchanged graph re-audits for free.

An agent-facing version of this runbook ships as a skill template in examples/skills/memory-promotion/.