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 ID for a themed overview once the scratch has grown (--into ID aims the artifact at a chosen context id — by default its id derives from the scratch's own, named 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 id}/promote, body {into, sources, audit?} — into is the destination's id (the id column of GET /contexts), not its name — ?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 sources; 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 sources to transfer 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 source file), targeting the permanent context (--context takes its id) — keeping the session:{agent}:{id} source ids and the dates: --source-id, --date, and --tag bake all three conventions into the emitted source file 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 source files. --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 ID (or the audit_consolidation MCP tool) — --checks LIST narrows the sections (comma-separated merge,contradiction,staleness; default all three), --into ID aims the judgment context at a chosen id (default: derived from the audited context's id, named 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/.