openmnemex 0.1.0__py3-none-any.whl

openmnemex/__init__.py

@@ -0,0 +1,36 @@
+"""openmnemex — the OpenMnemex Context Graph engine, packaged (plan v2 §7, commit 0a).
+
+This bridge makes the flat ``scripts/`` engine importable BOTH ways without touching the
+``mnx_*`` modules themselves:
+
+  * **repo / Claude-plugin path (unchanged):** ``python3 scripts/mnx_stage.py …`` and plain
+    ``import mnx_stage`` with ``scripts/`` on ``sys.path`` — the modules import each other
+    flat (``import mnx_common``), exactly as before. Running a script directly never
+    executes this file.
+  * **packaged path (pip / uvx):** ``pyproject.toml`` maps this directory to the
+    ``openmnemex`` package. Importing ``openmnemex`` (or any ``openmnemex.mnx_*``) runs
+    this bridge first, which puts the package directory on ``sys.path`` so the flat
+    intra-engine imports keep resolving, then eagerly aliases every engine module as
+    ``openmnemex.<name>``.
+
+The eager aliasing guarantees a SINGLE module identity per engine module — ``import
+mnx_common`` and ``from openmnemex import mnx_common`` return the very same object — so
+module-level state can never fork between the two import styles (the dual-identity trap
+of path-bridged packages). Guarded by tests/test_packaging_imports.py.
+"""
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+
+_PKG_DIR = Path(__file__).resolve().parent
+
+if str(_PKG_DIR) not in sys.path:
+    sys.path.insert(0, str(_PKG_DIR))
+
+for _mod_file in sorted(_PKG_DIR.glob("mnx_*.py")):
+    _name = _mod_file.stem
+    _module = importlib.import_module(_name)        # flat identity, same as the plugin path
+    sys.modules[f"{__name__}.{_name}"] = _module    # `import openmnemex.mnx_x` → same object
+    globals()[_name] = _module                      # `from openmnemex import mnx_x`

openmnemex/data/config/mnemex.config.md

@@ -0,0 +1,72 @@
+---
+config_version: 1
+
+# --- Decay (the ONE knob you set) ---
+half_life_days: 180
+pattern_halflife_bonus: 0.30      # patterns persist ~30% longer than domain facts (derived)
+
+# --- Tiers ---
+hot_k: 12
+warm_band: 0.25
+cold_ttl_days: 120
+cold_recall_multiplier: 1.6
+strength_max: 1.0
+
+# --- Freshness (revalidation horizon; independent of decay) ---
+freshness_ttl_days: 30            # a fact goes stale this long after it was last verified
+freshness_pattern_bonus: 0.30     # patterns get a ~30% longer horizon (derived; you set one number)
+
+# --- Usage boosts ---
+boost:
+  contributed: 1.0
+  consulted: 0.5
+  traversed: 0.0
+
+# --- Budget / scale ---
+node_budget: 35
+
+# --- Maintenance ---
+compaction_cadence_days: 14
+reconcile_cold_on: update         # always | update | never
+
+# --- Death policy ---
+purge_dead: false                 # false = tombstone-and-retain (recommended)
+
+# --- Ingestion (bootstrapping the graph from an existing repo; docs/corpus-ingestion.md) ---
+ingest_bulk_soft_atoms: 500       # a bulk batch past this warns (drained continuously by --bulk promote)
+ingest_bulk_hard_atoms: 5000      # a bulk batch refuses past this (drain it first)
+ingest_max_atoms_per_run: 2000    # per-run cost ceiling; excess resumes on the next run
+er_match_threshold: 0.85          # entity-resolution: ≥ this score → same entity (deterministic merge)
+er_possible_threshold: 0.60       # [possible, match) → the HITL "⚠ suggested" band (LLM judge)
+code_extract: gated               # gated | deep | off — code value-gate (public/documented/config-only)
+# max_glean_passes lives in USER config (~/.claude/mnemex/config.md; default 2) — glean is shared with capture.
+---
+
+# Mnemex configuration
+
+This file controls how your knowledge graph remembers and forgets. It is plain Markdown with a YAML
+front-matter block, so it is readable by both you and the protocol.
+
+## The one decision that matters
+
+You set **`half_life_days`** — how long an *unused* domain fact takes to lose half its relevance.
+Everything else has a sensible default. Patterns (the "how") automatically persist longer than domain
+facts (the "what") by `pattern_halflife_bonus` (default +30%); you do not tune two rates.
+
+## When you change a value
+
+Bump `config_version`. The next consolidation (the back half of `mnx-promote`) will **re-normalize**
+stored relevance so nothing jumps tiers abruptly, and `mnx-read` will warn you if a change is pending.
+See `docs/configuration.md`.
+
+## Quick guidance
+
+- Start with a **long** half-life and **generous** `cold_ttl_days`; tighten once you have observed real
+  usage. Nothing should die prematurely while you are still learning the rhythm of your graph.
+- `hot_k` is how many nodes you want visible at *zero* extra read cost (chunk-1). 12–20 is reasonable.
+- `node_budget` exists to keep reconciliation matching fast on writes; size it by write-path comfort.
+- Keep `purge_dead: false` for audit-friendly, recoverable forgetting (tombstones, not deletion).
+- `freshness_ttl_days` is a **separate** clock from decay: it is about whether a fact is still *true*, not
+  whether it is still *used*. A fact that is 40 days past verification is flagged `stale` on read so the agent
+  re-checks it — even if it is hot. Tag `volatility: timeless` on eternal facts (also stops them ever dying)
+  and `volatility: volatile` on fast-rotting ones. See `docs/freshness-and-revalidation.md`.

openmnemex/data/integrations/opencode/mnemex.ts

@@ -0,0 +1,86 @@
+// OpenCode adapter (multi-agent plan v2, Phase 4 / commit 4a).
+//
+// Thin translator only: normalizes OpenCode's plugin event shape into the host-neutral
+// event dict `mnx_hooks.core_*()` expects (see scripts/mnx_hooks.py), then execs the same
+// Python engine Claude Code's hooks/hooks.json shells out to. No side-effect logic lives here.
+//
+// Mapping (session-lifecycle events only, per plan scope):
+//   session.created   -> session-start   (consent primer + graph sync)
+//   session.idle      -> stop            (usage-stamp flush + capture nudge bookkeeping)
+//   session.compacted -> pre-compact     (re-arms the Stop nudge for the lost window)
+//   dispose()         -> session-end     (safety-net flush; best-effort synthetic session id,
+//                                          since OpenCode's dispose() carries no event payload)
+//
+// `session.compacted` (stable, post-hoc) is used instead of the experimental
+// `experimental.session.compacting` pre-hook: core_pre_compact() is side-effect-only and never
+// injects context into the compaction itself, so before-vs-after timing does not matter for us,
+// and the stable event is a safer bet across OpenCode versions (§12 item 2 — re-verify the event
+// API at integration time; https://opencode.ai/docs/plugins/ as of 2026-07).
+//
+// Delivery gap (documented in LIMITATIONS.md #3): mnx_hooks.py's HookOutcome (context/block/
+// notice text -- e.g. the session-start consent primer) has no rendering surface here; OpenCode's
+// `event` hook is fire-and-forget with no return channel back into the model's context. Only the
+// underlying SIDE EFFECTS run (graph sync, usage-stamp flush, marker bookkeeping, doctor checks
+// via the pre-compact re-arm); the advisory/consent prompts themselves reach the model via
+// AGENTS.md instructions instead, same as any Assisted-tier host. Do not add a `console.log` of
+// the hook's stdout here as a workaround -- it would print to OpenCode's own process output, not
+// the model's context, and would look like working delivery while doing nothing.
+// Scope boundary: this path is correct for this file's location in THIS repo checkout
+// (integrations/opencode/mnemex.ts -> ../../scripts/mnx_hooks.py). When Phase 5's installer
+// copies/emits this file into a consumer project's `.opencode/plugin/mnemex.ts`, that copy needs
+// an installed-package-relative (or absolute, baked in at install time) path instead — rewriting
+// HOOKS_SCRIPT for the target layout is Phase 5's job (commit 5b), not done here.
+import type { Plugin } from "@opencode-ai/plugin"
+
+const HOOKS_SCRIPT = new URL("../../scripts/mnx_hooks.py", import.meta.url).pathname
+
+async function runHook(
+  cwd: string,
+  subcommand: string,
+  event: Record<string, unknown>,
+): Promise<void> {
+  try {
+    const proc = Bun.spawn(["python3", HOOKS_SCRIPT, subcommand], {
+      cwd,
+      stdin: "pipe",
+      stdout: "ignore",
+      stderr: "ignore",
+    })
+    proc.stdin.write(JSON.stringify(event))
+    proc.stdin.end()
+    await proc.exited
+  } catch {
+    // advisory hooks must never break a session — same fail-open contract as the Claude adapter
+  }
+}
+
+export const MnemexPlugin: Plugin = async ({ directory }) => {
+  let lastSessionID = ""
+
+  return {
+    event: async ({ event }) => {
+      switch (event.type) {
+        case "session.created": {
+          const sid = (event.properties as any)?.info?.id ?? ""
+          lastSessionID = sid
+          await runHook(directory, "session-start", { session_id: sid })
+          break
+        }
+        case "session.idle": {
+          const sid = (event.properties as any)?.sessionID ?? lastSessionID
+          lastSessionID = sid
+          await runHook(directory, "stop", { session_id: sid })
+          break
+        }
+        case "session.compacted": {
+          const sid = (event.properties as any)?.sessionID ?? lastSessionID
+          await runHook(directory, "pre-compact", { session_id: sid })
+          break
+        }
+      }
+    },
+    dispose: async () => {
+      if (lastSessionID) await runHook(directory, "session-end", { session_id: lastSessionID })
+    },
+  }
+}

openmnemex/data/templates/binding.template.md

@@ -0,0 +1,23 @@
+---
+# Project-level Mnemex binding. Lives at <project-repo>/.mnemex.md.
+# Tells the plugin which knowledge graph THIS project reads from and writes to.
+# Overrides the user-level default (~/.claude/mnemex/config.md).
+#
+# Set EXACTLY ONE of graph_remote / graph_path (if both are set, graph_path wins + a warning):
+graph_remote:        # a git remote — cloned & synced; writes commit + push.  e.g. git@github.com:acme/payments-knowledge.git
+graph_path:          # a local folder — used in place, no clone/push.          e.g. ~/knowledge/payments
+default_team:        # optional — default routing team for this project
+author:              # optional — identity for usage stamps / commits
+---
+
+# Mnemex binding
+
+This project's work is captured into the knowledge graph at `graph_remote` (a git repo) or `graph_path`
+(a local folder). The graph itself — including its decay/tier behavior (`mnemex.config.md`) — lives in
+that separate location, not here.
+
+A **local folder** that is itself a git repo gets a local commit per change; a plain (non-git) folder
+gets an append-only audit trail in its `.mnemex/history.log`. A **git remote** commits and pushes.
+
+Commit this file to share the binding with the team, or add `.mnemex.md` to `.gitignore` to keep it
+personal. See `docs/binding-and-graph-sync.md`.

openmnemex/data/templates/gitattributes.template

@@ -0,0 +1,29 @@
+# Mnemex: truth unions, derived regenerates.
+# Drop this into a knowledge-graph repo as `.gitattributes` (mnx-init does this).
+# The `mnx-regen` driver COMMAND is registered per-clone by `mnx_regen.py install`
+# (mnx-init runs it; mnx-doctor verifies it). Without the command registered, git falls
+# back to a normal 3-way merge — so the doctor flags an unregistered driver.
+
+# --- TRUTH: append-only logs concatenate cleanly (built-in union driver) ---
+registry.md            merge=union
+**/registry.md         merge=union
+.mnemex/highwater/**   merge=union
+
+# --- DERIVED: discard both sides, regenerate from truth on conflict ---
+index.md               merge=mnx-regen
+index.[0-9][0-9][0-9].md   merge=mnx-regen
+**/index.md            merge=mnx-regen
+**/index.[0-9][0-9][0-9].md merge=mnx-regen
+phonebook.md           merge=mnx-regen
+**/phonebook.md        merge=mnx-regen
+cross-links.md         merge=mnx-regen
+**/cross-links.md      merge=mnx-regen
+# split tier files (when tier_files: true)
+warm.md                merge=mnx-regen
+cold.md                merge=mnx-regen
+dead.md                merge=mnx-regen
+cold.[0-9][0-9][0-9].md    merge=mnx-regen
+**/warm.md             merge=mnx-regen
+**/cold.md             merge=mnx-regen
+**/dead.md             merge=mnx-regen
+**/cold.[0-9][0-9][0-9].md merge=mnx-regen

openmnemex/data/templates/gitignore.template

@@ -0,0 +1,10 @@
+# Mnemex knowledge-graph .gitignore
+# Ignore ONLY transient runtime state. Durable state (.mnemex/highwater/,
+# config_version, last_compaction) is intentionally committed for reproducibility.
+
+# Transient: a live/stranded team or cluster lock, and an in-flight pass plan.
+.mnemex/locks/
+.mnemex/plans/
+
+# OS
+.DS_Store

openmnemex/data/templates/index.template.md

@@ -0,0 +1,20 @@
+# <folder-name> — index
+> One-line description of this cluster. Routing decisions are made on this line.   <!-- chunk 1 -->
+
+## Children                                                                         <!-- chunk 1 -->
+- <child-folder>/ — one-line description
+<!-- (leaf clusters: "none") -->
+
+## Hot                                                                              <!-- chunk 1 tail; top-K -->
+| id | type | summary | aliases | strength | last_update | stale_after |
+|----|------|---------|---------|----------|-------------|-------------|
+
+## Warm                                                                             <!-- chunk 2 -->
+| id | type | summary | aliases | strength | last_update | stale_after |
+|----|------|---------|---------|----------|-------------|-------------|
+
+## Cold                                                                             <!-- chunk 3+ -->
+| id | type | summary | aliases | strength | last_update | stale_after | expires |
+|----|------|---------|---------|----------|-------------|-------------|---------|
+
+<!-- GENERATED FILE. Do not hand-edit. Regenerated by mnx-promote apply and mnx-doctor --fix. -->

openmnemex/data/templates/node.template.md

@@ -0,0 +1,38 @@
+---
+id: REPLACE-with-stable-slug          # [a-z0-9-]+, assigned at creation, NEVER changes
+type: domain                          # domain | pattern
+title: Human-readable title (may change freely)
+summary: One line that lands in the index verbatim — the match + routing surface.
+aliases: [other name, abbreviation, synonym]
+domain: [sub-domain]                  # may be a LIST (a node can belong to >1 sub-index)
+status: active                        # active | dead   (retired-why is a field: superseded-by, died)
+confidence: high                      # high | medium | low
+volatility: default                   # default | timeless | volatile | <int days> — freshness horizon (Freshness & Revalidation)
+trigger: null                         # REQUIRED (non-null) for type: pattern; null for domain
+mentions:                             # GENERATED from body [[wiki-links]] at promote (Link Reconciliation). Author links
+  - { name: other-node-id, resolved_id: other-node-id, type: null }  #   inline in the BODY, not here.
+  - { name: page-not-created-yet, resolved_id: null, type: null }    #   resolved_id null = a red-link
+edges:                                # GENERATED MIRROR of resolved mentions (Link Reconciliation §8) — not hand-authored
+  - { to: other-node-id, type: null }               # untyped by default; type is optional
+references: []                        # SOFT cross-TEAM pointers only (no integrity guarantee)
+provenance:
+  artifact: name-of-build-artifact
+  reviews: []                         # human review-point ids that fed this node
+  session: 1970-01-01T00:00:00Z
+created: 1970-01-01T00:00:00Z
+updated: 1970-01-01T00:00:00Z         # meaning-change time (NOT usage)
+verified: 1970-01-01T00:00:00Z       # last confirmed-still-true time (NOT usage, NOT meaning-change)
+---
+
+## Summary
+One paragraph; read first on a body expansion.
+
+## What
+(domain nodes) The knowledge itself. Link to other pages inline by NAME with wiki-links —
+e.g. "…settles against [[other-node-id]] before posting." Promote resolves them (Link Reconciliation).
+
+## How / Notes
+(pattern nodes) The prescriptive procedure / rule and its rationale.
+
+## Provenance
+Why this node exists; trace to the artifact and the specific human review points.

openmnemex/data/templates/procedures/capture.core.md

@@ -0,0 +1,150 @@
+---
+name: mnx-capture
+description: Capture the durable knowledge produced in the current build session into the local Mnemex staging tier — cheap, fast, no lock, no graph mutation. Use this when a user finishes building or designing and wants to persist what was learned — domain facts AND the patterns/decisions from human review — or says "save this to the knowledge graph", "remember this for next time", "capture this", "stage this". Run it INCREMENTALLY at natural checkpoints too, not only at session end — after a sub-task lands, a review settles, or a compaction is signalled — staging only the delta (re-capturing identical content is a no-op), keeping keypoints loss-proof. Runs in-session to mine the artifact and review points from the transcript; extracts atoms, scores each now/later/not-needed, stages them with self-sufficient provenance. Also curates staging (--drop <id>, --discard-all) — the escape valve at the hard cap. Does NOT reconcile or merge into the shared graph — that is the deliberate, batched {{PROC:promote}} step.
+---
+
+# mnx-capture — stage a session's knowledge (the `git commit` of memory)
+
+Turn what this session produced — the artifact **and** the human review/clarification points — into
+**staged atoms**: provisional, local, self-sufficient knowledge units. The *how* lives in the
+conversation (the corrections, the rejected alternatives), so mine the transcript, not just the final
+artifact, **now** — by promote time the transcript is gone.
+
+Capture is the **fast, local half** of the capture/promote split. It is cheap, takes no lock, never
+reads the graph's cluster indexes, and **never mutates the graph**. Reconcile / merge / consolidate /
+push all happen later in `{{PROC:promote}}`. (Analogy: capture = `git commit`; promote = `git push`/PR.)
+
+**Capture incrementally, at checkpoints — not only at the very end.** Since that transcript shrinks at
+every compaction, one end-of-session dump is the most loss-exposed way to run this: prefer to capture the
+**delta** at each natural checkpoint (a sub-task lands, a review decision settles, a compaction is
+signalled). Capture is built for repetition — it stages only what is new and re-staging identical content
+is an idempotent no-op (content-hash id) — so it stays cheap; the delta mechanics are Phase 0b + Phase 1.
+
+Background: `docs/staging-and-promotion.md` (the whole model), `docs/rationale-and-concepts.md`
+(node types, ids), `docs/data-model-and-schemas.md` (staged-atom front-matter). Helper:
+`mnx_stage` (the only writer here) and `mnx_binding` (locate the graph).
+
+{{INCLUDE:curate}}
+## Preflight — locate the graph (always first)
+Run {{CALL:bind_status}}.
+- If `resolved` is false → **STOP**: *"No Mnemex graph configured. Run `{{PROC:init}}`."*
+- **Echo the resolved graph before staging** so the author sees where atoms will land: show the
+  `resolution` line, e.g. *"Capturing into **payments-knowledge** (source: project .mnemex.md)."*
+  If `default_fallback` is true, make it **prominent** — there was no project `.mnemex.md`, so this is
+  going to the user's personal graph: *"⚠️ No project binding here — capturing into your personal
+  graph **personal-notes**. If that's wrong, cd into the right repo and re-capture."* This closes the
+  silent-binding gap (LIMITATIONS.md #2): the graph choice is now visible at capture time, not discovered
+  at promote time.
+- Note `graph_root` (for routing intent only — capture writes **nothing** there) and `staging_root`
+  (where atoms land). Capture is local; it does **not** need `clone_present` / a sync.
+
+## Phase 0 — Budget pre-check (backpressure)
+Run {{CALL:capture_status_budget}}.
+- `budget.level == "hard"` → **STOP capturing** and give the user the two ways out (the backpressure
+  bound): either *"run `{{PROC:promote}}` to merge + drain staging"* **or** *"make room by discarding
+  with {{CALL:capture_drop_flag}} or `--discard-all`."* Show the staged list (`mnx_stage.py list`)
+  so they can choose what to drop.
+- `budget.level == "soft"` → proceed, but **warn** the user once that a promote is due.
+
+## Phase 0b — Delta ledger (what is already staged)
+Before extracting, load the staged ledger so you capture only the **delta** and can see what is already
+covered:
+
+{{CALL:capture_status_list}}
+
+Each row is `provisional-id · type · score · summary · age`. Read it as the running record of "keypoints
+already captured this session." In Phase 1, extract only what this ledger does **not** already cover, then
+look for the next uncaptured keypoint. You do not need to diff by hand — re-staging identical content is an
+idempotent no-op (content-hash id) — but consulting the ledger keeps you from re-mining ground you already
+staged and makes the incremental checkpoint loop cheap. A genuinely refined atom (same concept, better
+body) will hash differently and stage as a new atom; that is fine — reconcile collapses the pair at promote.
+
+## Phase 1 — Extract the delta (mine the transcript, honor the node-size budget)
+Decompose the artifact + transcript into candidate atoms, skipping anything the Phase 0b ledger already
+covers — extract the **new** keypoints since your last capture. For each, decide:
+- **`domain`** (a fact about the system/business — the *what*), or
+- **`pattern`** (prescriptive *how*, with a `trigger` = the *when* it applies). **Mine human review
+  points specifically**: a correction or a rejected alternative becomes a pattern — *"do X not Y,
+  because…"* — with a trigger describing the situation it governs.
+
+Draft `summary` (one line), `aliases` (other names the concept goes by), `domain` (routing key(s)),
+and a tight body. **Propose a `volatility`** (freshness horizon, Freshness & Revalidation) from the atom's content shape —
+`volatile` for a fact that rots fast (a URL, version, price, on-call name), `timeless` for a durable
+definition/invariant (also exempts it from ever auto-dying), or leave it `default` (the type-derived
+horizon) for everything else. It is a *suggestion*: the human confirms or overrides it at the promote
+gate, so bias toward `default` when unsure.
+
+**Embed links inline as `[[wiki-links]]` (the mesh authoring surface, Link Reconciliation).** When a note refers to
+another concept, name it inline in the body with double brackets — *"…settles against
+`[[iso8583-field124]]` before posting…"*. Link freely **by name**, even to a page that does not exist in
+the graph yet: promote resolves each `[[name]]`, and an unresolved one becomes a **red-link** that goes
+live automatically the day that page is created. The pipe means display text, wiki-native
+(`[[iso8583-field124|Field 124]]`), **not** a relationship type. `mnx_stage` hoists these into the atom's
+`mentions:` for you — you just write natural `[[links]]`. Do **not** hand-author `edges:`; that is a
+generated mirror promote builds.
+
+**Node-size budget — do NOT split at capture.** Keep each atom's body focused, but if a genuinely
+single idea runs past the soft cap (`node_body_max_chars`, default ~6000), **capture it whole** — never
+truncate. **Splitting an over-budget note into sibling pages + a link is promote's job, not capture's**
+(promote is graph-aware; capture is local and dumb). Cap the number of atoms per session to what the
+session actually produced; do not pad.
+
+## Phase 1b — Glean (one bounded "what did I miss?" re-scan)
+Pass 1 (Phase 1) is your first extraction pass; a single pass reliably **under-captures the *how*** — the
+review-point patterns are the easiest to miss. So run **one** bounded recall pass (this is the shared
+*gleanings* technique, guardrail mode):
+
+- Re-read the transcript once and ask specifically: *"what durable fact — **especially a review-point
+  pattern** (a correction, a rejected alternative, a 'gotcha') — did I not stage yet?"*, guided by the
+  Phase-0b delta ledger so you look only at ground you have **not** already covered.
+- Any new candidate still passes the Phase-2 `now/later/not-needed` scoring gate and Phase-3 staging;
+  re-staging identical content stays an idempotent no-op (content-hash id), so this pass can only add.
+- **Bound the loop deterministically.** After the pass, count staged atoms before vs after and check
+  whether to stop:
+
+  {{CALL:glean_step}}
+
+  `stop:true` (`reason: no-progress` = the pass added nothing new, or `reason: cap` = the pass budget
+  `max_glean_passes` is reached — default **2**, from user config) → stop gleaning and go to Phase 2/4.
+  Only if `stop:false` do you run one more pass (`--pass 2`). This is **not** a per-topic walk — it is at
+  most a couple of bounded re-scans, keeping capture cheap/fast (the design goal). Episodic capture does
+  **not** build a coverage checklist — that (checklist mode) is ingest-only.
+
+## Phase 2 — Score each atom (`now | later | not-needed`)
+A momentary judgement of **intrinsic importance — NOT novelty**. Drift between sessions is fine; there
+is no rigid rubric. Novelty/dedup is decided later at promote (reconcile may drop an atom as a
+duplicate), so do **not** pre-judge "probably already known."
+- **`now`** → stage **with `--urgent`**. (Urgent never inline-pushes — promote is still the only
+  writer; urgent only sharpens the nag.)
+- **`later`** → stage normally.
+- **`not-needed`** → **silently drop.** No staging, no audit, no asking the user. Reserve this for the
+  clearly ephemeral or trivially derivable.
+
+## Phase 3 — Stage (the only write)
+For each kept atom, write it to the staging tier. Provenance must be **self-sufficient for a cold
+promote** — artifact ref, the specific review ids, rejected alternative(s), the rationale, and the
+session timestamp:
+
+{{CALL:capture_add}}
+
+(Or use flags for a simple atom: `add --type domain --summary "…" --domain settlement --score later
+--aliases "a;b" --artifact <id> --reviews "r3;r7" --rationale "…" --body "…"`.) The helper mints the
+**provisional id** (a content hash, `stg-…`) — never invent an id, never reuse a real node id. A
+re-capture of identical content is idempotent and reports `action: already-staged` (vs `staged` for
+new content) — count the two separately so your report reflects the true delta.
+
+## Phase 4 — Report
+Summarize what was staged **this pass**: the new atoms (counts by score), any `urgent`, and the
+post-stage `budget.level`. When capturing incrementally, distinguish this pass's delta from the total
+staged set so the checkpoint loop is legible ("staged 2 new; 7 total staged"). If the helper
+**refused** an atom (`action: refused`), surface the hard-cap message and give both ways out —
+`{{PROC:promote}}` to drain staging, or {{CALL:capture_drop_flag2}} / `--discard-all` to make
+room. Then stop — **do not** offer to push or merge; that is promote's job.
+
+## Never
+- Never reconcile, merge, re-tier, or open the graph's cluster indexes — capture is local-only.
+- Never write into `graph_root`, never take the team lock, never commit or push.
+- Never stamp a staged atom or give it a real node id (the `stg-` provisional id is content-derived).
+- Never `not-needed`-drop on a *novelty* guess — only the clearly ephemeral/derivable.
+- Never split, resolve a `[[link]]`, or hand-author `edges:` — capture preserves links; **promote** splits
+  over-budget notes and resolves links (Link Reconciliation). Never truncate an over-budget atom — capture it whole.

openmnemex/data/templates/procedures/curate.core.md

@@ -0,0 +1,13 @@
+---
+name: curate
+description: Review, drop, or discard atoms already staged in the local Mnemex staging tier — no extraction, no graph mutation. The un-stage escape valve, including at the hard capture-budget cap.
+---
+## Curate mode — review / drop / discard (no extraction)
+{{BLOCK:trigger_condition}}
+- **Review first** when helpful: {{CALL:capture_status_inline}} shows the
+  staged atoms (provisional id · score · summary · age). (`{{PROC:status}}` shows the same list.)
+- `--drop <id>` → {{CALL:capture_drop}}; report the dropped atom's id + summary (or that it
+  was not found).
+- `--discard-all` → show the list and **confirm with the user**, then {{CALL:capture_discard_all}}; report the
+  count removed.
+This touches **only** the local staging tier — never the graph, never the stamp spill. Then stop.

openmnemex/data/templates/procedures/fragments/_digests/capture.md

@@ -0,0 +1,4 @@
+Procedure: check `capture_status`'s ledger for what's already staged, mine the transcript for
+the delta (facts + review-point patterns) plus one bounded `glean_step` recall pass, score
+each atom now/later/not-needed, then `capture_add` per atom with self-sufficient provenance.
+Never split an over-budget body — stage it whole; that's promote's job.

openmnemex/data/templates/procedures/fragments/_digests/ingest.md

@@ -0,0 +1,9 @@
+Procedure: `ingest_acquire` the repo (read-only) → `ingest_probe` for the extraction
+units + a source-tree→cluster map (gate #1: confirm scope) → distil durable atoms with
+`capture_add(ingest_batch=...)`, never transcribe (zero atoms from a file is fine) →
+`glean_coverage` until complete/cap → `er_resolve` to dedupe and MERGE into existing pages
+(one entity → one node) → drain with `promote_begin`/`promote_apply` in bulk. For every
+NEW cluster created, write its one-line description into the cluster `index.md` header
+(`> …` line) — read routing decides on that line, and regeneration preserves it; never
+leave the scaffold placeholder. Two gates
+only (scope, bulk summary); deleted-file orphans surface for the human, never auto-tombstoned.

openmnemex/data/templates/procedures/fragments/_digests/promote.md

@@ -0,0 +1,4 @@
+Procedure: `promote_begin` (locks + guards) → `promote_context` (near-matches, link preview)
+→ draft one plan (create/merge/supersede/resurrect/drop_dup/hold per staged atom, plus link
+and consolidate decisions) → present it for human approval → `promote_apply` with
+`approved: true`. Contradictions go to `hold`, never force-resolved or silently dropped.

openmnemex/data/templates/procedures/fragments/_digests/read.md

@@ -0,0 +1,4 @@
+Procedure: `read_frontier` to route (by description match) → `read_cluster` (hot tier
+first, widen only if insufficient) → `read_nodes` for only the ids you'll actually use →
+`record_usage` with a role (contributed/consulted/traversed) for every id loaded. Flag stale
+rows and staged-overlay atoms in the answer; never body-merge a staged/graph contradiction.

openmnemex/data/templates/procedures/fragments/capture/bind_status.claude.md

@@ -0,0 +1,2 @@
+`python3 "${CLAUDE_PLUGIN_ROOT}/scripts/mnx_binding.py" status --session <sid>` (the session id
+from session-start, if you have one — see mnx-init step 1; honors a mid-session graph switch)

openmnemex/data/templates/procedures/fragments/capture/bind_status.mcp.md

@@ -0,0 +1 @@
+the `bind_status` tool

openmnemex/data/templates/procedures/fragments/capture/capture_add.claude.md

@@ -0,0 +1,14 @@
+```
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/mnx_stage.py" add --binding-session <sid> --json <<'JSON'
+{ "type": "pattern",
+  "summary": "Reconcile settlement before posting",
+  "aliases": ["settle-recon"],
+  "domain": ["settlement"],
+  "trigger": "reviewing or curating a settlement spec",
+  "score": "now", "urgent": true, "volatility": "default",
+  "provenance": { "artifact": "tap-vic-settlement-spec", "reviews": ["r3","r7"],
+                  "rejected": ["post-then-reconcile (causes orphaned legs)"],
+                  "rationale": "human correction in review r7" },
+  "body": "Always reconcile the settlement batch against [[iso8583-field124]] before posting legs, because …" }
+JSON
+```

openmnemex/data/templates/procedures/fragments/capture/capture_add.mcp.md

@@ -0,0 +1,2 @@
+Call `capture_add` with the atom's fields: `type, summary, aliases?, domain?, trigger?
+(required for pattern), score, urgent?, volatility?, provenance?, body`.

openmnemex/data/templates/procedures/fragments/capture/capture_drop_flag.claude.md

@@ -0,0 +1 @@
+`/mnemex:mnx-capture --drop <id>`

openmnemex/data/templates/procedures/fragments/capture/capture_drop_flag.mcp.md

@@ -0,0 +1 @@
+`capture_drop`

openmnemex/data/templates/procedures/fragments/capture/capture_drop_flag2.claude.md

@@ -0,0 +1 @@
+`/mnemex:mnx-capture --drop <id>`

openmnemex/data/templates/procedures/fragments/capture/capture_drop_flag2.mcp.md

@@ -0,0 +1 @@
+`capture_drop`

openmnemex/data/templates/procedures/fragments/capture/capture_status_budget.claude.md

@@ -0,0 +1 @@
+`python3 "${CLAUDE_PLUGIN_ROOT}/scripts/mnx_stage.py" status`

openmnemex/data/templates/procedures/fragments/capture/capture_status_budget.mcp.md

@@ -0,0 +1 @@
+the `capture_status` tool (check its `budget.level`)

openmnemex/data/templates/procedures/fragments/capture/capture_status_list.claude.md

@@ -0,0 +1,3 @@
+```
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/mnx_stage.py" list
+```

openmnemex/data/templates/procedures/fragments/capture/capture_status_list.mcp.md

@@ -0,0 +1 @@
+Call `capture_status` (its staged ledger).

openmnemex/data/templates/procedures/fragments/capture/glean_step.claude.md

@@ -0,0 +1,3 @@
+```
+  python3 "${CLAUDE_PLUGIN_ROOT}/scripts/mnx_glean.py" step --before <n_before> --after <n_after> --pass 1
+  ```

openmnemex/data/templates/procedures/fragments/capture/glean_step.mcp.md

@@ -0,0 +1 @@
+Call `glean_step` with `before=<n_before>`, `after=<n_after>`, `pass_no=1`.

openmnemex/data/templates/procedures/fragments/capture/init.claude.md

@@ -0,0 +1 @@
+/mnemex:mnx-init

openmnemex/data/templates/procedures/fragments/capture/init.mcp.md

@@ -0,0 +1 @@
+init_graph

openmnemex/data/templates/procedures/fragments/capture/promote.claude.md

@@ -0,0 +1 @@
+/mnemex:mnx-promote

openmnemex/data/templates/procedures/fragments/capture/promote.mcp.md

@@ -0,0 +1 @@
+the promote procedure

openmnemex/data/templates/procedures/fragments/curate/capture_discard_all.claude.md

@@ -0,0 +1 @@
+`mnx_stage.py clear`

openmnemex/data/templates/procedures/fragments/curate/capture_discard_all.mcp.md

@@ -0,0 +1 @@
+`capture_discard_all` with `confirm=true`

openmnemex/data/templates/procedures/fragments/curate/capture_drop.claude.md

@@ -0,0 +1 @@
+`mnx_stage.py clear-one --id <id>`

openmnemex/data/templates/procedures/fragments/curate/capture_drop.mcp.md

@@ -0,0 +1 @@
+`capture_drop` with `pid=<id>`

openmnemex/data/templates/procedures/fragments/curate/capture_status_inline.claude.md

@@ -0,0 +1 @@
+`python3 "${CLAUDE_PLUGIN_ROOT}/scripts/mnx_stage.py" list`

openmnemex/data/templates/procedures/fragments/curate/capture_status_inline.mcp.md

@@ -0,0 +1 @@
+`capture_status`

openmnemex/data/templates/procedures/fragments/curate/status.claude.md

@@ -0,0 +1 @@
+/mnemex:mnx-status

openmnemex/data/templates/procedures/fragments/curate/status.mcp.md

@@ -0,0 +1 @@
+status

openmnemex/data/templates/procedures/fragments/curate/trigger_condition.claude.md

@@ -0,0 +1,3 @@
+If invoked with `--drop <provisional-id>` or `--discard-all`, this is the local **un-stage** path — the
+cheap way to prune staging (and the escape valve when the hard cap is blocking new captures). It still
+runs the locate preflight (to find the staging tier) but does **no** extraction, scoring, or staging: