@korrlabs/mnemos-pi 2.15.0

package/integrations/skills/mnemos-checkpoint.md

@@ -0,0 +1,72 @@
+---
+name: mnemos-checkpoint
+description: Save a compaction-resilient checkpoint mid-session — survives context compression and session restart
+---
+
+# Mnemos Checkpoint
+
+Write a snapshot every time the session reaches a meaningful milestone or
+signals compaction. The checkpoint is what the agent reads back after
+compaction to recover state.
+
+## WHEN
+
+- **Just finished a multi-step phase** — a batch of files saved, a test suite
+  fixed, a refactor completed.
+- **About to invoke an expensive subagent chain** — before delegating to a
+  worker that may consume significant context.
+- **User confirmed a non-trivial decision** — before moving on.
+- **Compaction signal detected** — summary banner, long conversation
+  (≳30 turns since last checkpoint), `mnemos_auto_collect_status` recommends
+  checkpoint, or sudden loss of earlier-turn references.
+- **Before a long step** — when the next action will consume many turns.
+
+## STEPS
+
+1. Compose the checkpoint content:
+
+   | Field | Content |
+   |-------|---------|
+   | `goals` | The active goal in one sentence. |
+   | `completed` | Recent completed items (≤7 bullets). |
+   | `in_progress` | The immediate next action (one bullet). |
+   | `decisions` | Decisions worth surviving compaction (bullets). |
+   | `context` | File paths, architecture notes, gotchas (free text). |
+
+2. Save the checkpoint:
+
+   ```text
+   mnemos_save_context(
+     project=<current-project>,
+     goals=<one sentence>,
+     completed=<bullets>,
+     in_progress=<one bullet>,
+     decisions=<bullets>,
+     context=<file paths, notes>
+   )
+   ```
+
+3. Confirm with a one-line notice:
+
+   ```text
+   mnemos: checkpoint saved (project=<name>)
+   ```
+
+## DISCIPLINE
+
+- **Idempotent within a session.** Re-saving shortly after a previous
+  checkpoint should update the latest checkpoint, not create duplicates.
+- **Keep the body short.** The checkpoint is for waking up after compaction,
+  not for archival. ≤7 bullets per field.
+- **Never block on checkpoint failure.** If `mnemos_save_context` errors,
+  log a one-line notice and continue. Memory is an enhancement, not a
+  dependency.
+- **Do not checkpoint on a timer.** Write on signals (phase done, compaction
+  detected), not every N turns. Timer-based checkpoints create noise.
+- **Include the next action.** A checkpoint without `in_progress` leaves the
+  post-compaction agent without a starting point.
+
+## See also
+
+- Skill `mnemos-session-init` — recall at session start
+- Instruction `mnemos-session-lifecycle.instructions.md`

package/integrations/skills/mnemos-compress.md

@@ -0,0 +1,52 @@
+---
+name: mnemos-compress
+description: Zero-loss compression of huge tool outputs — keep context small, fetch the original back on demand
+---
+
+# Mnemos Compress (CCR)
+
+Compress oversized tool output (logs, JSON, build logs) with ZERO data loss
+before pasting it into context. The original is cached server-side; a marker
+hash lets you retrieve it later.
+
+## WHEN
+
+- **A tool returned >500 lines / huge JSON** that you only partly need now.
+- **Long command output** where the gist matters but details may matter
+  later.
+- **Before writing a memory entry** that quotes a big blob — store the
+  compressed marker, not the blob.
+
+## STEPS
+
+1. **Compress and keep the marker**:
+
+   ```text
+   mnemos_compress(text=<huge output>, profile="log")
+   # → [compressed: <sha256> | 87% saved | retrieve via mnemos_retrieve]
+   ```
+
+   Profiles: `log`, `terminal`, `code`, `docs`, `web`, `default`.
+
+2. **Carry the marker in context** instead of the original text.
+
+3. **Retrieve when details are needed** — full original or ranked snippets:
+
+   ```text
+   mnemos_retrieve(hash=<sha256>)                      # full original
+   mnemos_retrieve(hash=<sha256>, query="timeout")     # FTS-ranked snippets
+   ```
+
+## DISCIPLINE
+
+- Compression is **zero-loss** — never summarize by hand "because it's
+  compressed anyway"; retrieve instead.
+- Pick the matching profile: `code` preserves identifiers, `log` keeps
+  timestamps aligned.
+- Don't compress short outputs (<500 chars) — the marker costs more than
+  the text.
+
+## See also
+
+- Skill `mnemos-cache-align` — stabilizing prompts for provider KV caches
+- Skill `mnemos-write` — persisting the marker into a memory entry

package/integrations/skills/mnemos-exchange.md

@@ -0,0 +1,55 @@
+---
+name: mnemos-exchange
+description: Export and import the memory store — backups, migration between instances, federation payloads
+---
+
+# Mnemos Exchange
+
+Move memories between mnemos instances (or into a backup file) via
+`mnemos_export` / `mnemos_import`. JSON for selective payloads, SQLite for
+full snapshots.
+
+## WHEN
+
+- **Before risky operations** — a dated export is a cheap safety net.
+- **Migrating instances** — new machine, new container, split → merge.
+- **Federation Phase 0 sync** — compact payloads between peers.
+
+## STEPS
+
+1. **Export** (JSON by default; filters optional):
+
+   ```text
+   mnemos_export(output_path="/backup/mnemos-2026-08-21.json",
+                 format="json", project=<slug>)
+   ```
+
+   Full snapshot for restore purposes:
+
+   ```text
+   mnemos_export(output_path="...", format="sqlite")
+   ```
+
+2. **Import on the target** — merge is the safe default:
+
+   ```text
+   mnemos_import(source_path="...", mode="merge", dry_run=true)  # preview!
+   mnemos_import(source_path="...", mode="merge")
+   ```
+
+3. **Restore mode is destructive** — wipes the target store first; requires
+   `confirm=true`. Use only for full disaster recovery.
+
+## RULES
+
+- **Always `dry_run=true` first** — the validation report shows what would
+  happen with zero risk.
+- Encrypted exports: the passphrase comes from the environment variable
+  named by `passphrase_env` — never inline.
+- Import rejects schema drift and oversized content; fix the source rather
+  than forcing.
+
+## See also
+
+- Skill `mnemos-write` — what belongs in the store in the first place
+- `mnemos sync` CLI — federation batch sync between instances

package/integrations/skills/mnemos-filter.md

@@ -0,0 +1,56 @@
+---
+name: mnemos-filter
+description: Run or refresh the Context Filter on a stored memory — strip noise, pick profiles, enforce token budgets
+---
+
+# Mnemos Filter
+
+The Context Filter is the five-stage noise stripper that runs automatically
+on every `mnemos_add`. Use `mnemos_filter` to run it retroactively (when
+`auto_filter` was off) or to re-filter an entry with a different profile or
+token budget.
+
+## WHEN
+
+- **An entry was written with auto_filter off** — noisy content is bloating
+  recall results.
+- **The wrong profile was auto-detected** — e.g. a log pasted as docs kept
+  its timestamps and ANSI codes.
+- **A token budget changed** — re-filter to truncate to the new ceiling.
+- **Previewing the cost of keeping content** — the tool reports clean
+  content plus reduction stats.
+
+## STEPS
+
+1. **Re-filter with an explicit profile**:
+
+   ```text
+   mnemos_filter(memory_id=<id>, profile="terminal")
+   ```
+
+   Profiles: `log`, `terminal`, `code`, `docs`, `web`, `default`.
+   Omit `profile` to let the filter auto-select.
+
+2. **Enforce a token budget**:
+
+   ```text
+   mnemos_filter(memory_id=<id>, profile="log", budget=2000)
+   ```
+
+3. **Check the reduction stats** in the result — a tiny reduction means the
+   entry was already clean; a huge one means the raw content was mostly
+   noise worth compressing instead (see `mnemos-compress`).
+
+## DISCIPLINE
+
+- Filtering rewrites the STORED content — the vault original stays the
+  source of truth; don't hand-copy filtered output back into entries.
+- Prefer fixing the writer over re-filtering forever: if entries keep
+  arriving noisy, adjust how they're added, not the filter.
+- `code` profile preserves identifiers; don't use `default` on source code.
+
+## See also
+
+- Skill `mnemos-write` — writing clean entries in the first place
+- Skill `mnemos-compress` — zero-loss alternative for big blobs
+- [Context filter guide](https://github.com/Korrnals/mnemos/blob/main/docs/en/user/context-filter.md)

package/integrations/skills/mnemos-housekeeping.md

@@ -0,0 +1,66 @@
+---
+name: mnemos-housekeeping
+description: Memory store housekeeping — stats, queue depth, tag hygiene, and reprocessing raw entries
+---
+
+# Mnemos Housekeeping
+
+Keep the memory store healthy: check stats and queue depth, list recent
+entries and tags, reprocess the raw queue when it grows.
+
+## WHEN
+
+- **At session start** — `mnemos_stats()` is a cheap health ping (counts,
+  degraded flags, search health).
+- **Recall results look stale or thin** — check `embedding_status` and
+  `search_health` before blaming the query.
+- **After heavy write bursts** — a growing `queue_depth` means the pipeline
+  is behind; reprocess to flush.
+- **Tag hygiene** — `mnemos_list_tags()` reveals typos and near-duplicates
+  (`project:mnemos` vs `project:Project-Mnemos`).
+
+## STEPS
+
+1. **Health ping**:
+
+   ```text
+   mnemos_stats()
+   ```
+
+   Watch for: `degraded: true`, `fts_available/vector_available: false`,
+   `orphaned_vectors: true`.
+
+2. **Flush the pipeline** when `queue_depth > 0` after writes:
+
+   ```text
+   mnemos_reprocess()
+   ```
+
+3. **Review recent entries and tags**:
+
+   ```text
+   mnemos_list_recent(limit=10)
+   mnemos_list_tags()
+   ```
+
+4. **Fix tag drift** with the bulk rename (dry-run first). Two entry
+   points: the grouped pilot tool `mnemos_tags`, or the dedicated
+   `mnemos_tags_rename` (same engine, prefix→prefix, idempotent):
+
+   ```text
+   mnemos_tags_rename(from_prefix="gcw:", to_prefix="mnemos:", dry_run=true)
+   mnemos_tags(action="rename", from_prefix="gcw:", to_prefix="mnemos:",
+               dry_run=true)
+   ```
+
+## DISCIPLINE
+
+- Reprocess is for **pipeline backlog**, not a fix for bad content — bad
+  entries get rewritten, not reprocessed.
+- Tag renames are prefix-based and idempotent, but ALWAYS dry-run first.
+- Don't poll stats in a loop — it's a check, not a monitor.
+
+## See also
+
+- Skill `mnemos-tag-contract` — what valid tags look like
+- Skill `mnemos-checkpoint` — when to save session state

package/integrations/skills/mnemos-ingest.md

@@ -0,0 +1,51 @@
+---
+name: mnemos-ingest
+description: Ingest a web page into memory — fetch, extract, and store a URL as a tagged knowledge unit
+---
+
+# Mnemos Ingest URL
+
+Fetch a web page, extract its readable content, and store it in the memory
+vault as a tagged entry — much better than pasting raw HTML into context.
+
+## WHEN
+
+- **A URL contains knowledge worth keeping** — docs, an ADR, a postmortem,
+  a spec.
+- **You will cite this source later** — the vault entry preserves the URL.
+- **Teams should read the same version** — one ingested copy instead of
+  everyone re-fetching.
+
+## STEPS
+
+1. **Ingest with tags** (contract applies — `project:` and `agent:` are
+   mandatory, `source:` records where it came from):
+
+   ```text
+   mnemos_ingest_url(
+     url="https://example.com/postmortem",
+     tags=["project:<slug>", "agent:<your-slug>", "source:web",
+           "domain:reliability"]
+   )
+   ```
+
+2. **Confirm what was stored** — the tool reports the extracted title and
+   size; sanity-check that it's not a cookie-wall or JS shell.
+
+3. **Cite it later via search**, not by re-fetching:
+
+   ```text
+   mnemos_search(query="postmortem cache stampede")
+   ```
+
+## DISCIPLINE
+
+- Ingest **knowledge**, not links — a URL nobody will read again is noise.
+- One page = one entry; don't batch a link farm into the vault.
+- If the page requires auth/cookies the extraction may be empty — verify
+  the reported content before relying on it.
+
+## See also
+
+- Skill `mnemos-write` — writing your own knowledge vs. ingesting external
+- Skill `mnemos-recall` — searching ingested pages

package/integrations/skills/mnemos-recall.md

@@ -0,0 +1,87 @@
+---
+name: mnemos-recall
+description: Effective memory search — start narrow, broaden if no hits; avoids re-learning what was already learned
+---
+
+# Mnemos Recall
+
+Query the memory store for relevant prior entries. Use before architectural
+decisions, before web searches, and when resuming work on a topic.
+
+## WHEN
+
+- **Before an architectural decision** — choosing a pattern, library, or
+  approach. Check if a prior decision exists.
+- **Before a web search** — the answer may already be in memory.
+- **When resuming a topic** — recall what was learned last time.
+- **When debugging** — check if this bug-pattern was seen before.
+
+## STEPS
+
+1. **Start narrow** — tag-filtered, project-scoped:
+
+   ```text
+   mnemos_search(
+     query=<natural language query>,
+     project=<current-project>,
+     tags=["mnemos:decision"],     # or mnemos:bug-pattern, mnemos:learning
+     limit=10
+   )
+   ```
+
+2. **Broaden if no hits** — drop the tag filter, keep the project scope:
+
+   ```text
+   mnemos_search(
+     query=<query>,
+     project=<current-project>,
+     limit=10
+   )
+   ```
+
+3. **Broaden further if still no hits** — drop project scope:
+
+   ```text
+   mnemos_search(
+     query=<query>,
+     limit=10
+   )
+   ```
+
+4. **For agent-scoped recall** — when you need your own prior context:
+
+   ```text
+   mnemos_agent_recall(
+     agent=<your-slug>,
+     project=<current-project>,   # optional
+     query=<optional focus>,
+     limit=20
+   )
+   ```
+
+5. **Return a compact list** — do not paste full bodies unless the caller
+   asks:
+
+   ```text
+   - <title> (<tags>) [project=<...>]
+   ```
+
+6. **If 0 results, say so explicitly.** Do not fabricate prior context.
+
+## DISCIPLINE
+
+- **Narrow → broaden.** Starting broad returns too much noise; starting
+  narrow returns signal or confirms absence.
+- **Default to recency, not relevance, when ranking ties.** The most recent
+  entry is usually the most applicable.
+- **Do not paste full bodies.** Keep the recall list scannable. Recall the
+  full entry only if the caller needs it.
+- **Never fabricate.** If search returns nothing, say "no prior context
+  found for <query>". Do not infer what "probably" was in memory.
+- **Search before web.** A web search that re-discovers what memory already
+  has is wasted tokens and time.
+
+## See also
+
+- Skill `mnemos-write` — capture what you learned
+- Instruction `mnemos-memory-ops.instructions.md`

package/integrations/skills/mnemos-session-init.md

@@ -0,0 +1,68 @@
+---
+name: mnemos-session-init
+description: Recall prior context at session start — restores project state, open questions, and recent decisions before any work begins
+---
+
+# Mnemos Session Init
+
+Run at the start of any session that wants memory continuity. Restores prior
+context for the current project so the agent does not re-learn what was
+already learned.
+
+## WHEN
+
+- **Session start** — before reading any project file or running a search.
+- **After a context compaction** — when the harness signals compression and
+  prior context may have been lost.
+- **After switching projects** — when resuming work on a different codebase.
+
+## STEPS
+
+1. Determine `project` = workspace folder name (or explicit project slug).
+
+2. Recall prior context:
+
+   ```text
+   mnemos_recall_context(project=<project>)
+   ```
+
+3. If the result contains prior context, surface a short header (≤4 lines):
+
+   ```text
+   Memory: project=<name> | recalled=<N> entries
+   Last focus: <one line from last checkpoint>
+   Open questions: <one line or "none">
+   ```
+
+4. If recall returns nothing, say:
+
+   ```text
+   Memory: no prior context for <project>
+   ```
+
+5. Optionally, recall your own agent-scoped context if you are resuming as a
+   specific agent:
+
+   ```text
+   mnemos_agent_recall(agent=<your-slug>, project=<project>, limit=20)
+   ```
+
+6. Proceed with the task. Do not dump full recalled content into the response
+   — act on it.
+
+## DISCIPLINE
+
+- **Header ≤4 lines.** The user does not need to see the full recall — they
+  need to know that memory is active and what the last focus was.
+- **Never block on recall failure.** If `mnemos_recall_context` errors or
+  returns nothing, degrade silently to "no prior context" and continue.
+- **Recall before reading files.** The whole point is to avoid re-reading
+  what memory already summarised. If you read files first, you waste tokens
+  re-learning what memory had.
+- **Do not fabricate prior context.** If recall returns nothing, say so.
+  Never infer what "probably" was in memory.
+
+## See also
+
+- Skill `mnemos-checkpoint` — save mid-session / on compaction
+- Instruction `mnemos-session-lifecycle.instructions.md`

package/integrations/skills/mnemos-tag-contract.md

@@ -0,0 +1,104 @@
+---
+name: mnemos-tag-contract
+description: Canonical tag schema for Mnemos memory entries — required composition, whitelisted prefixes, subtypes
+---
+
+# Mnemos Tag Contract (skill reference)
+
+All memory entries — via `mnemos_add` or `mnemos_ingest_url` — must use this
+tag vocabulary. Stability of these names matters: migration and search depend
+on it.
+
+## WHEN
+
+- **Before every `mnemos_add` call** — validate the tag set.
+- **Before every `mnemos_ingest_url` call** — same requirement.
+- **When reviewing a migration** — check that legacy entries have valid
+  tags or `mnemos:legacy`.
+
+## Required tags (mandatory on all new entries)
+
+| Tag | Format | Cardinality | Purpose |
+|-----|--------|-------------|---------|
+| `project:<slug>` | `[a-z0-9][a-z0-9\-_]*` | **exactly 1** | Binds entry to a codebase / initiative |
+| `agent:<slug>` | `[a-z0-9][a-z0-9\-_]*` | **exactly 1** | Agent that authored the memory (use `agent:user` for user-authored) |
+| `mnemos:<subtype>` | see table below | **at least 1** | Cognitive category |
+
+### Mnemos subtypes (whitelist)
+
+| Subtype | When to use |
+|---------|-------------|
+| `mnemos:session` | Session continuity snapshots |
+| `mnemos:checkpoint` | Mid-session compaction-resilient checkpoints |
+| `mnemos:bug-pattern` | Recurring failure modes, root-cause patterns |
+| `mnemos:learning` | Non-obvious facts acquired during a task |
+| `mnemos:decision` | Explicit architectural / product decisions + rationale |
+| `mnemos:rule` | Hard constraints and invariants |
+| `mnemos:open-question` | Unresolved questions requiring future investigation |
+| `mnemos:legacy` | Migrated entries from ai-brain or pre-contract stores |
+
+## Optional tags (accepted, not required)
+
+| Tag | Format | Purpose |
+|-----|--------|---------|
+| `source:<slug>` | any string | Origin of the entry (chat, file, url, …) |
+| `applyTo:<glob>` | file glob | Scope a `mnemos:rule` to specific file paths |
+| `milestone:<id>` | any string | Links entry to a project milestone |
+| `domain:<slug>` | any string | Domain sub-classifier within a project |
+| `severity:<level>` | `low\|medium\|high\|critical` | Severity for bug-patterns |
+| `stack:<slug>` | any string | Technology stack (e.g. `stack:python`) |
+
+Unknown prefixes not listed here are **rejected** in strict mode.
+
+## Enforcement modes
+
+| Mode | Setting | Behaviour |
+|------|---------|-----------|
+| **Strict** (default) | `strict_tag_contract=true` | Missing/malformed required tags → `TagContractError`, write rejected. |
+| **Lax** (migrations) | `strict_tag_contract=false` | Missing required tags → warning, write succeeds. Multiple `project:`/`agent:` always raise. |
+
+## STEPS
+
+1. **Identify the project** — the codebase or initiative this entry belongs
+   to. If unknown, determine it before calling `mnemos_add`.
+
+2. **Identify the agent** — the agent slug that authored this entry. Use
+   `agent:user` for user-provided content.
+
+3. **Choose the subtype** — pick exactly one `mnemos:<subtype>` from the
+   whitelist. If none fits, do not invent one — propose a new subtype via
+   PR.
+
+4. **Add optional tags** as needed — `severity:` for bug-patterns,
+   `applyTo:` for rules, `stack:` for stack-specific learnings.
+
+5. **Assemble and write**:
+
+   ```text
+   mnemos_add(
+     content=<body>,
+     tags=[
+       "project:<slug>",
+       "agent:<slug>",
+       "mnemos:<subtype>",
+       "<optional>:<value>"
+     ]
+   )
+   ```
+
+## DISCIPLINE
+
+- **Never omit required tags.** If you do not know the project or agent,
+  determine it before writing. Do not guess.
+- **Do not invent new `mnemos:` subtypes.** Propose additions via PR to the tag
+  contract.
+- **One `project:` per entry.** If a learning spans projects, write one
+  entry per project, or use `project:shared` if genuinely cross-project.
+- **`agent:user` for user-authored content.** Do not attribute user-provided
+  facts to the agent that happened to be running.
+- **Slugs are lowercase.** `[a-z0-9][a-z0-9\-_]*` — no uppercase, no spaces.
+
+## See also
+
+- Instruction `mnemos-tag-contract.instructions.md`
+- [Tag Contract (user docs)](../../docs/en/user/tag-contract.md)

package/integrations/skills/mnemos-watch.md

@@ -0,0 +1,52 @@
+---
+name: mnemos-watch
+description: Watch directories and auto-index changes into memory — keep the vault in sync with living code and docs
+---
+
+# Mnemos Watch
+
+Start a background watcher over project directories so file changes are
+auto-indexed into memory. The vault stays current without manual
+`mnemos_add` for every doc change.
+
+## WHEN
+
+- **Long-running multi-session work** — docs/rules written between sessions
+  should be searchable without re-ingestion.
+- **A shared knowledge dir** (ADRs, runbooks) that several agents read.
+- **After restoring or migrating a vault** — one scan pass re-indexes
+  everything.
+
+## STEPS
+
+1. **Start watching** (initial scan included by default):
+
+   ```text
+   mnemos_watch_start(paths=["/project", "/project/docs"], scan=true)
+   ```
+
+2. **Check health periodically** — especially after long idle periods:
+
+   ```text
+   mnemos_watch_status()
+   ```
+
+3. **Stop cleanly** when the workstream ends:
+
+   ```text
+   mnemos_watch_stop()
+   ```
+
+## DISCIPLINE
+
+- Watch **knowledge directories**, not whole repos — `src/` churn would
+  flood the pipeline with noise.
+- `.github/instructions/*.instructions.md` is picked up automatically when
+  present — no need to add it twice.
+- The watcher is per-session background state: if the session died, restart
+  it rather than assuming it survived.
+
+## See also
+
+- Skill `mnemos-ingest` — one-shot URL ingestion vs. directory watching
+- `mnemos doctor` — reports watcher health among other checks