@korrlabs/mnemospi 3.1.0 → 3.2.0

package/integrations/skills/mnemos-context-lifecycle.md

@@ -0,0 +1,121 @@
+---
+name: mnemos-context-lifecycle
+description: Context lifecycle automation — assemble the pre-LLM context block, report context rewrites losslessly, and wire session/tool lifecycle hooks (ADR-0017/0018)
+---
+
+# Mnemos Context Lifecycle
+
+The publication-engine tools that run the context lifecycle end to end:
+`mnemos_assemble_context` composes the model-facing context block through a
+fixed, security-gated pipeline; `mnemos_context_rewrite` is the lossless
+report of a context rewrite (compaction/slimming) so the original is never
+lost; `mnemos_hooks` groups the automation entry points behind one
+`action:` enum. ADR-0017 D1 defines the provider contract, ADR-0018 the
+rewrite lifecycle.
+
+## WHEN
+
+- **Session start (bootstrap)** — recall recent checkpoints so a new or
+  post-compaction session resumes from real state (`hooks` action
+  `on_session_start`).
+- **Pre-LLM injection (context assembly)** — before an important model call
+  where you want mnemos-retrieved memory in the prompt, composed under a
+  token budget with the entry invariant applied (secret scan, provenance,
+  published-only status gate).
+- **Compaction (context rewrite)** — the harness replaced or slimmed a
+  block of its working context: report the original to mnemos so nothing is
+  lost, then keep a thin marker in the window.
+- **Tool output compression (hooks.post_tool_call)** — a tool returned a
+  huge output you want substituted by a zero-loss CCR marker, with
+  provenance stamped for strict marker validation.
+
+## STEPS
+
+1. **Bootstrap a session** — recall recent checkpoints:
+
+   ```text
+   mnemos_hooks(action="on_session_start", session=<session-id>,
+                project=<project-slug>, agent=<agent-slug>, limit=5)
+   # → recent checkpoints, already secret-scanned at issuance
+   ```
+
+2. **Assemble the pre-LLM context block** (or use the equivalent hook):
+
+   ```text
+   mnemos_assemble_context(session=<session-id>, project=<project-slug>,
+                           file=<optional-path>, agent=<agent-slug>,
+                           budget=2048, mode="sync")
+   # → assembled text, per-block provenance lines, redaction counts,
+   #   token stats
+   ```
+
+   The fixed pipeline runs in order: hybrid RRF recall (published/processed
+   only) → optional CCR marker expansion (`expand_ccr=true`, needs `agent`)
+   → context filter → mandatory secret scan → CacheAligner → token budget.
+   Prefer `mode="async"` on latency-sensitive paths: the first call returns
+   a handle, fetch the block on a later call with `async_handle=<handle>`.
+   Use `mode="code"` / `mode="prose"` to bias recall candidates to a stored
+   content type.
+
+3. **Report a context rewrite** (compaction, window slimming) — send the
+   ORIGINAL of the replaced block:
+
+   ```text
+   mnemos_context_rewrite(content=<original text>, project=<project-slug>,
+                          agent=<agent-slug>, session=<session-id>,
+                          supersedes=<memory-id-of-replaced-block>,
+                          include_marker=true)
+   # → memory id (supersedes edge new → old); with include_marker=true
+   #   also a CCR marker to keep in the window
+   ```
+
+   The original enters the normal knowledge pipeline (raw → processed →
+   published); it is context-reachable again only after the pipeline
+   advances it. Rehydrate later via `mnemos_retrieve` or
+   `mnemos_assemble_context` — both re-scan and carry provenance.
+
+4. **Compress a tool output through the hook** (autocompression is
+   opt-in — pass `auto_compress=true` per call, or enable the
+   `hooks.auto_compress` config knob):
+
+   ```text
+   mnemos_hooks(action="post_tool_call", session=<session-id>,
+                project=<project-slug>, agent=<agent-slug>,
+                tool_name=<tool-that-ran>, output_text=<raw output>,
+                auto_compress=true)
+   # → marker-headed compressed_text; SUBSTITUTE it into your window
+   ```
+
+5. **Handle backpressure** — `mnemos_context_rewrite` may return
+   `{"error": ..., "rate_limited": true}`. Back off and re-deliver later:
+   the event is idempotent (content-addressed over
+   project/agent/session/supersedes/content), so re-delivery cannot
+   duplicate writes.
+
+## DISCIPLINE
+
+- **Never assemble context by hand.** The pipeline stages (context filter,
+  secret scan, CacheAligner, budget) are not optional — a hand-pasted
+  "context block" bypasses the entry invariant and may carry secrets or
+  noise into the prompt.
+- **The rewrite diff is advisory, the original is load-bearing.** The
+  `diff` argument is stored as metadata only; the original `content` is the
+  source of truth and must be passed verbatim, unsummarized.
+- **Identity is mandatory.** Every call needs `session` + `project` +
+  `agent` — identity-less compression mints unverifiable cache rows that
+  strict marker validation will later reject.
+- **Rewrite is version-less.** Do not invent version numbering; replacement
+  lineage is the `supersedes` edge. Pass `supersedes` when you know the
+  memory id of the replaced block.
+- **Trust the provenance line.** Injected blocks carry
+  `[mnemos:<id> project=… status=… v=<n> retrieved=<iso>]` — surface it,
+  don't strip it; it is what makes later rehydration auditable.
+
+## See also
+
+- Skill `mnemos-session-init` — the manual recall counterpart at session start
+- Skill `mnemos-compress` — direct CCR compression when no lifecycle hook applies
+- Skill `mnemos-cache-align` — stabilizing prompts for provider KV caches
+- Skill `mnemos-write` — persisting markers and memories into the store
+- ADR `docs/project/adr/0017-memory-system-evolution-roadmap.md` — provider contract D1
+- ADR `docs/project/adr/0018-context-rewrite-ltm-bridge.md` — rewrite lifecycle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korrlabs/mnemospi",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Mnemos memory & knowledge server — Pi extension. Spawns `mnemos mcp-server` over stdio and exposes every mnemos_* tool as a native Pi tool, plus the mnemos skill pack.",
   "type": "module",
   "license": "MIT",