@danielmarbach/mnemonic-mcp 0.24.0 → 0.25.1

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to `mnemonic` will be documented in this file.
 
 The format is loosely based on Keep a Changelog and uses semver-style version headings.
 
+## [Unreleased]
+
+## [0.25.1] - 2026-04-24
+
+### Changed
+
+- `semanticPatch` no longer rejects content with markdown lint issues — the patch succeeds and warnings are surfaced in the response instead, so the LLM can continue without retrying from scratch. Previously any lint issue forced a hard failure.
+- Structural errors (bad selector, invalid operation) and content lint errors are now distinguished from patch lint warnings with separate guidance, so the LLM gets the right fix direction for each failure mode.
+
+## [0.25.0] - 2026-04-24
+
+### Added
+
+- `recall` now supports `mode: "workflow"` for RPIR-oriented chain retrieval while keeping compatibility with existing note graphs.
+- Relationship types now include `derives-from` and `follows` so workflows can express directional sequencing and derivation explicitly.
+- The npm package now ships bundled skills and includes a `mnemonic-install-skills` command to install or update local skill directories for Claude, OpenCode, and custom targets.
+
+### Changed
+
+- RPIR workflow guidance now uses `mnemonic-rpi-workflow` as the prompt name.
+- The RPIR skill is now published under `skills/mnemonic-rpi-workflow`.
+
 ## [0.24.0] - 2026-04-24
 
 ### Added

package/README.md

@@ -51,8 +51,13 @@ No code changes required — set `EMBED_MODEL=qwen3-embedding:0.6b` in your envi
 npm install
 npm run build
 npm test
+
+# release-confidence gate (build + full tests + isolated dogfooding)
+npm run verify:release
 ```
 
+The gate fails on required dogfood checks and reports advisory findings separately in the dogfood output.
+
 `npm run build` already runs `typecheck`, but running it explicitly first gives a faster failure loop when iterating on the codebase.
 
 For local dogfooding, start the built MCP server with:
@@ -94,6 +99,45 @@ npm install @danielmarbach/mnemonic-mcp
 npm install @danielmarbach/mnemonic-mcp@0.2.0
 ```
 
+### Install bundled skills (Claude/OpenCode)
+
+The npm package now includes `skills/**` plus a helper binary to install them into local skill directories.
+
+```bash
+# If mnemonic is installed in this project:
+npx mnemonic-install-skills --target all --mode copy
+
+# One-off install without adding dependency:
+npx -y -p @danielmarbach/mnemonic-mcp mnemonic-install-skills --target all --mode copy
+```
+
+Supported targets:
+
+- `--target claude` -> `~/.claude/skills`
+- `--target opencode` -> `~/.config/opencode/skills`
+- `--target all` -> both (default)
+- `--target custom` -> only use `--target-dir` destinations
+- `--target-dir <path>` -> add any custom client skill directory
+
+Update flow after upgrading `@danielmarbach/mnemonic-mcp`:
+
+```bash
+npx mnemonic-install-skills --target all --mode copy --update
+```
+
+If you prefer automatic propagation without copy refreshes, use symlink mode:
+
+```bash
+npx mnemonic-install-skills --target all --mode symlink --update
+```
+
+After install, load and use the skill by name:
+
+- Skill name: `mnemonic-rpi-workflow`
+- Prompt counterpart: `mnemonic-rpi-workflow`
+
+In clients that support explicit skill loading (for example Claude Code or OpenCode), load `mnemonic-rpi-workflow` before running multi-step RPIR workflows.
+
 ### Homebrew
 
 The formula lives in this repository. Tap it with an explicit URL so no separate repository is needed:
@@ -312,7 +356,11 @@ Project identity derives from the **git remote URL**, normalized to a stable slu
 
 **Hybrid recall** enhances semantic search with lightweight lexical reranking over note projections. When semantic results are weak, a bounded lexical rescue path scans projections for additional candidates, improving exact-match and identifier-heavy recall without changing the storage model or adding new infrastructure. **Canonical explanation promotion** boosts notes that explain key decisions and concepts for "why"-style questions, using structural signals like role, connections, and format rather than keyword matching.
 
-Temporal recall is opt-in via `mode: "temporal"`. It keeps semantic selection first, then enriches only the top matches with compact git-backed history so agents can inspect how a note evolved without turning recall into raw log or diff output.
+Recall modes:
+
+- `mode: "default"` (default): semantic recall with optional lexical reranking and bounded relationship previews.
+- `mode: "temporal"`: enrich top matches with compact git-backed history (no raw diffs by default).
+- `mode: "workflow"`: prioritize RPIR-style chain reconstruction while remaining compatible with legacy `related-to` links.
 
 **What temporal mode shows:**
 
@@ -341,11 +389,21 @@ Each note carries a `lifecycle`:
 
 ### Roles and lifecycle
 
-Roles are optional prioritization hints, not required schema. mnemonic infers a `role` and `importance` from structural signals (heading count, bullet density, inbound references, relationship types) — inference is language-independent and never overwrites explicit frontmatter. Valid roles: `summary`, `decision`, `plan`, `log`, `reference`. Valid importance values: `high`, `normal`.
+Roles are optional prioritization hints, not required schema. mnemonic infers a `role` and `importance` from structural signals (heading count, bullet density, inbound references, relationship types) — inference is language-independent and never overwrites explicit frontmatter. Valid roles: `summary`, `decision`, `plan`, `context`, `reference`, `research`, `review`. Valid importance values: `high`, `normal`, `low`.
 
 Set `alwaysLoad: true` in a note's frontmatter to mark it as an explicit session anchor; it receives the highest recall and relationship-expansion priority regardless of inferred role.
 
-mnemonic works without roles. Inferred roles stay internal-only, prioritization is language-independent by default, and lifecycle remains the separate durability axis. A note with `role: plan` can still be either `temporary` or `permanent`.
+mnemonic works without roles. Inferred roles stay internal-only, prioritization is language-independent by default, and lifecycle remains the separate durability axis. When `lifecycle` is omitted, `remember` applies soft defaults based on role: `research`, `plan`, and `review` default to `temporary`; `decision`, `summary`, and `reference` default to `permanent`. Explicit `lifecycle` always overrides the role-based default.
+
+### RPIR workflow conventions
+
+For structured workflows, use the RPIR stages: research -> plan -> implement -> review (iterate only when needed).
+
+- Create one request root note per workflow: `role: context`, `lifecycle: temporary`, `tags: ["workflow", "request"]`.
+- Keep one current plan note per request (`role: plan`) and update or supersede as the plan evolves.
+- For apply/task notes, do not add a new role: use `role: plan` for executable steps and `role: context` for execution observations; tag both with `apply`.
+- Keep relationships sparse and immediate-upstream only: research -> request, plan -> request/research, apply -> plan, review -> apply/plan, outcome -> plan (optionally request).
+- Consolidate at workflow end: promote durable outcomes into permanent decision/summary/reference notes; let temporary scaffolding expire.
 
 ### Note format
 
@@ -444,6 +502,7 @@ Imported notes are written to the main vault with `lifecycle: permanent` and `sc
 
 | Prompt | Description |
 |--------|-------------|
+| `mnemonic-rpi-workflow` | Optional. Returns RPIR stage protocol and conventions: request root note pattern, stage checklists, apply/task split, sparse relationships, subagent handoff contract, and commit discipline. |
 | `mnemonic-workflow-hint` | Optional. Returns a compact decision protocol: use `recall` or `list` first, inspect with `get`, update existing memories, remember only when nothing matches, then organize with `relate`, `consolidate`, or `move_memory`. It also reinforces summary-first orientation via `project_memory_summary`, temporary-note recovery only after orientation, and that roles are optional prioritization hints while lifecycle stays separate. |
 
 ## Tools
@@ -463,7 +522,7 @@ Imported notes are written to the main vault with `lifecycle: permanent` and `sc
 | `memory_graph`              | Show compact adjacency list of relationships                             |
 | `move_memory`               | Move note between vaults without changing id                             |
 | `project_memory_summary`    | Session-start entrypoint: themed notes, anchors, and orientation for fast project orientation |
-| `recall`                    | Semantic search with optional project boost and opt-in temporal history  |
+| `recall`                    | Semantic search with optional project boost, temporal history mode, and workflow chain mode |
 | `recent_memories`           | Show most recently updated notes for scope                               |
 | `remember`                  | Write note + embedding; `cwd` sets context, `scope` picks storage, `lifecycle` picks temporary vs permanent |
 | `relate`                    | Create typed relationship between notes (bidirectional)                  |
@@ -504,6 +563,10 @@ relatedTo:
 | `explains`   | `fromId` explains `toId`                 |
 | `example-of` | `fromId` is a concrete example of `toId` |
 | `supersedes` | `fromId` is the newer version of `toId`  |
+| `derives-from` | `fromId` is derived from `toId`        |
+| `follows` | `fromId` follows `toId` in sequence         |
+
+`workflow` recall mode prefers directional and typed relationships first, then falls back to `related-to` for long-term compatibility with older vaults.
 
 `relate` is bidirectional by default. `forget` automatically removes any edges pointing at the deleted note.
 

package/build/index.js

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { randomUUID } from "crypto";
 import path from "path";
 import { promises as fs } from "fs";
-import { NOTE_LIFECYCLES } from "./storage.js";
+import { NOTE_LIFECYCLES, NOTE_ROLES } from "./storage.js";
 import { embed, cosineSimilarity, embedModel } from "./embeddings.js";
 import { buildTemporalHistoryEntry, computeConfidence, getNoteProvenance } from "./provenance.js";
 import { enrichTemporalHistory } from "./temporal-interpretation.js";
@@ -14,10 +14,10 @@ import { invalidateActiveProjectCache, getOrBuildVaultEmbeddings, getOrBuildVaul
 import { performance } from "perf_hooks";
 import { filterRelationships, mergeRelationshipsFromNotes, normalizeMergePlanSourceIds, resolveEffectiveConsolidationMode, } from "./consolidate.js";
 import { suggestAutoRelationships } from "./auto-relate.js";
-import { computeRecallMetadataBoost, computeHybridScore, selectRecallResults, applyLexicalReranking, applyCanonicalExplanationPromotion, } from "./recall.js";
+import { computeRecallMetadataBoost, computeHybridScore, selectRecallResults, selectWorkflowResults, applyLexicalReranking, applyCanonicalExplanationPromotion, } from "./recall.js";
 import { shouldTriggerLexicalRescue, rankDocumentsByTfIdf, LEXICAL_RESCUE_CANDIDATE_LIMIT, LEXICAL_RESCUE_THRESHOLD, LEXICAL_RESCUE_RESULT_LIMIT, } from "./lexical.js";
 import { getRelationshipPreview } from "./relationships.js";
-import { cleanMarkdown } from "./markdown.js";
+import { MarkdownLintError, cleanMarkdown } from "./markdown.js";
 import { applySemanticPatches } from "./semantic-patch.js";
 import { MnemonicConfigStore, readVaultSchemaVersion } from "./config.js";
 import { CONSOLIDATION_MODES, PROTECTED_BRANCH_BEHAVIORS, PROJECT_POLICY_SCOPES, WRITE_SCOPES, isProtectedBranch, resolveProtectedBranchBehavior, resolveProtectedBranchPatterns, resolveConsolidationMode, resolveWriteScope, } from "./project-memory-policy.js";
@@ -407,12 +407,13 @@ function describeLifecycle(lifecycle) {
 function formatNote(note, score, showRawRelated = true) {
     const scoreStr = score !== undefined ? ` | similarity: ${score.toFixed(3)}` : "";
     const projectStr = note.project ? ` | project: ${note.projectName ?? note.project}` : " | global";
+    const roleStr = note.role ? ` | **role: ${note.role}**` : "";
     const relStr = showRawRelated && note.relatedTo && note.relatedTo.length > 0
         ? `\n**related:** ${note.relatedTo.map((r) => `\`${r.id}\` (${r.type})`).join(", ")}`
         : "";
     return (`## ${note.title}\n` +
         `**id:** \`${note.id}\`${projectStr}${scoreStr}\n` +
-        `**tags:** ${note.tags.join(", ") || "none"} | **${describeLifecycle(note.lifecycle)}** | **updated:** ${note.updatedAt}${relStr}\n\n` +
+        `**tags:** ${note.tags.join(", ") || "none"} | **${describeLifecycle(note.lifecycle)}**${roleStr} | **updated:** ${note.updatedAt}${relStr}\n\n` +
         note.content);
 }
 function formatTemporalHistory(history) {
@@ -924,11 +925,13 @@ function formatListEntry(entry, options = {}) {
     const extras = [];
     if (note.tags.length > 0)
         extras.push(note.tags.join(", "));
-    extras.push(`lifecycle=${note.lifecycle}`);
+    extras.push(`lifecycle: ${note.lifecycle}`);
+    if (note.role)
+        extras.push(`role: ${note.role}`);
     if (options.includeStorage)
-        extras.push(`stored=${storageLabel(vault)}`);
+        extras.push(`stored: ${storageLabel(vault)}`);
     if (options.includeUpdated)
-        extras.push(`updated=${note.updatedAt}`);
+        extras.push(`updated: ${note.updatedAt}`);
     const lines = [`- **${note.title}** \`${note.id}\` ${proj}${extras.length > 0 ? ` — ${extras.join(" | ")}` : ""}`];
     if (options.includeRelations && note.relatedTo && note.relatedTo.length > 0) {
         lines.push(`  related: ${note.relatedTo.map((rel) => `${rel.id} (${rel.type})`).join(", ")}`);
@@ -1029,6 +1032,14 @@ function addVaultChange(vaultChanges, vault, file) {
         vaultChanges.set(vault, files);
     }
 }
+const ROLE_LIFECYCLE_DEFAULTS = {
+    research: "temporary",
+    plan: "temporary",
+    review: "temporary",
+    decision: "permanent",
+    summary: "permanent",
+    reference: "permanent",
+};
 // ── MCP Server ────────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: "mnemonic",
@@ -1426,7 +1437,13 @@ server.registerTool("remember", {
             .enum(NOTE_LIFECYCLES)
             .optional()
             .describe("Memory lifetime. Use `temporary` for short-lived working context such as active investigations or transient status. " +
-            "Use `permanent` for durable knowledge such as decisions, fixes, patterns, and preferences."),
+            "Use `permanent` for durable knowledge such as decisions, fixes, patterns, and preferences. " +
+            "When omitted, defaults based on role: research/plan/review → temporary, decision/summary/reference → permanent."),
+        role: z
+            .enum(NOTE_ROLES)
+            .optional()
+            .describe("Optional prioritization hint for the note. Inferred automatically when omitted. " +
+            "Set explicitly for workflow artifacts like research or review notes."),
         summary: z.string().optional().describe("Git commit summary only. Imperative mood, concise, and focused on why the change matters."),
         alwaysLoad: z
             .boolean()
@@ -1454,7 +1471,7 @@ server.registerTool("remember", {
             .describe("Optional agent hint indicating that `recall` or `list` was already used to check for an existing memory on this topic."),
     }),
     outputSchema: RememberResultSchema,
-}, async ({ title, content, tags, lifecycle, summary, alwaysLoad, cwd, scope, allowProtectedBranch = false }) => {
+}, async ({ title, content, tags, lifecycle, role, summary, alwaysLoad, cwd, scope, allowProtectedBranch = false }) => {
     await ensureBranchSynced(cwd);
     const project = await resolveProject(cwd);
     const cleanedContent = await cleanMarkdown(content);
@@ -1483,7 +1500,8 @@ server.registerTool("remember", {
     const now = new Date().toISOString();
     const note = {
         id, title, content: cleanedContent, tags,
-        lifecycle: lifecycle ?? "permanent",
+        lifecycle: lifecycle ?? (role ? ROLE_LIFECYCLE_DEFAULTS[role] : undefined) ?? "permanent",
+        ...(role ? { role } : {}),
         alwaysLoad: alwaysLoad ?? false,
         project: project?.id,
         projectName: project?.name,
@@ -1841,6 +1859,7 @@ server.registerTool("recall", {
     title: "Recall",
     description: "Semantic search over stored memories using embeddings.\n\n" +
         "Supports opt-in temporal mode (`mode: \"temporal\"`) to enrich top semantic matches with compact git-backed history.\n\n" +
+        "Supports workflow mode (`mode: \"workflow\"`) to prioritize RPIR-style chain reconstruction while retaining compatibility with legacy relationships.\n\n" +
         "Use this when:\n" +
         "- You know the topic but not the exact memory id\n" +
         "- You are starting a session and want relevant prior context\n" +
@@ -1867,7 +1886,7 @@ server.registerTool("recall", {
         cwd: projectParam,
         limit: z.number().int().min(1).max(20).optional().default(DEFAULT_RECALL_LIMIT),
         minSimilarity: z.number().min(0).max(1).optional().default(DEFAULT_MIN_SIMILARITY),
-        mode: z.enum(["default", "temporal"]).optional().default("default").describe("Temporal history is opt-in. Use `temporal` to enrich top semantic matches with compact git-backed history."),
+        mode: z.enum(["default", "temporal", "workflow"]).optional().default("default").describe("Use `temporal` for compact git-backed history, or `workflow` for RPIR-oriented chain reconstruction."),
         verbose: z.boolean().optional().default(false).describe("Only meaningful with `mode: \"temporal\"`. Adds richer stats-based history context without returning raw diffs."),
         tags: z.array(z.string()).optional().describe("Filter results to notes with all of these tags."),
         scope: z
@@ -1996,7 +2015,9 @@ server.registerTool("recall", {
         promoted.push(...rescueCandidates);
         promoted = applyCanonicalExplanationPromotion(promoted);
     }
-    const top = selectRecallResults(promoted, limit, scope);
+    const top = mode === "workflow"
+        ? selectWorkflowResults(promoted, limit, scope)
+        : selectRecallResults(promoted, limit, scope);
     if (top.length === 0) {
         const structuredContent = { action: "recalled", query, scope: scope || "all", results: [] };
         return { content: [{ type: "text", text: "No memories found matching that query." }], structuredContent };
@@ -2057,6 +2078,7 @@ server.registerTool("recall", {
                 vault: storageLabel(vault),
                 tags: note.tags,
                 lifecycle: note.lifecycle,
+                role: note.role,
                 updatedAt: note.updatedAt,
                 provenance,
                 confidence,
@@ -2137,7 +2159,8 @@ server.registerTool("update", {
         }))
             .optional()
             .describe("Use for targeted edits when you know the structure. More token-efficient than passing full content. " +
-            "Mutually exclusive with content."),
+            "Mutually exclusive with content. " +
+            "If this fails, fix the issue in your patch values and retry — do NOT fall back to full content rewrite."),
         content: z.string().optional().describe("Full note body replacement. Use only for complete rewrites or when the note is small. Mutually exclusive with semanticPatch."),
         title: z.string().optional().describe("Specific, retrieval-friendly title. Prefer the concrete topic or decision, not a vague label."),
         tags: z.array(z.string()).optional().describe("Optional tags for later filtering. Use a small number of stable, meaningful tags."),
@@ -2145,6 +2168,10 @@ server.registerTool("update", {
             .enum(NOTE_LIFECYCLES)
             .optional()
             .describe("Change lifecycle. Preserve the existing value unless you're intentionally switching it."),
+        role: z
+            .enum(NOTE_ROLES)
+            .optional()
+            .describe("Change role. Preserve the existing value unless you're intentionally switching it."),
         summary: z.string().optional().describe("Git commit summary only. Imperative mood, concise, and focused on why the change matters."),
         alwaysLoad: z
             .boolean()
@@ -2159,7 +2186,7 @@ server.registerTool("update", {
             "When true, update can commit on a protected branch without changing project policy."),
     }),
     outputSchema: UpdateResultSchema,
-}, async ({ id, content, semanticPatch, title, tags, lifecycle, summary, alwaysLoad, cwd, allowProtectedBranch = false }) => {
+}, async ({ id, content, semanticPatch, title, tags, lifecycle, role, summary, alwaysLoad, cwd, allowProtectedBranch = false }) => {
     await ensureBranchSynced(cwd);
     const found = await vaultManager.findNote(id, cwd);
     if (!found) {
@@ -2196,11 +2223,18 @@ server.registerTool("update", {
     }
     const now = new Date().toISOString();
     let patchedContent;
+    let lintWarnings;
     if (semanticPatch && semanticPatch.length > 0) {
         try {
-            patchedContent = await applySemanticPatches(note.content, semanticPatch);
+            const result = await applySemanticPatches(note.content, semanticPatch);
+            patchedContent = result.content;
+            lintWarnings = result.lintWarnings;
         }
         catch (err) {
+            if (err instanceof MarkdownLintError) {
+                const message = `Semantic patch produced content with markdown lint issues. Fix the lint issues in your patch values and retry — do NOT fall back to full content rewrite.\n\n${err.message}`;
+                return { content: [{ type: "text", text: message }], isError: true };
+            }
             const message = err instanceof Error ? err.message : String(err);
             return { content: [{ type: "text", text: `Semantic patch failed: ${message}` }], isError: true };
         }
@@ -2212,6 +2246,7 @@ server.registerTool("update", {
         content: patchedContent ?? cleanedContent ?? note.content,
         tags: tags ?? note.tags,
         lifecycle: lifecycle ?? note.lifecycle,
+        ...(role !== undefined ? { role } : (note.role ? { role: note.role } : {})),
         alwaysLoad: alwaysLoad !== undefined ? alwaysLoad : note.alwaysLoad,
         updatedAt: now,
     };
@@ -2259,6 +2294,8 @@ server.registerTool("update", {
         changes.push("tags");
     if (lifecycle !== undefined && lifecycle !== note.lifecycle)
         changes.push("lifecycle");
+    if (role !== undefined && role !== note.role)
+        changes.push("role");
     if (alwaysLoad !== undefined && alwaysLoad !== note.alwaysLoad)
         changes.push("alwaysLoad");
     const changeDesc = changes.length > 0 ? `Updated ${changes.join(", ")}` : "No changes";
@@ -2303,10 +2340,16 @@ server.registerTool("update", {
         timestamp: now,
         project: noteProjectRef(updated),
         lifecycle: updated.lifecycle,
+        role: updated.role,
+        lintWarnings: lintWarnings && lintWarnings.length > 0 ? lintWarnings : undefined,
         persistence,
     };
     invalidateActiveProjectCache();
-    return { content: [{ type: "text", text: `Updated memory '${id}'\n${formatPersistenceSummary(persistence)}` }], structuredContent };
+    const fieldText = changes.length > 0 ? `\nfields modified: ${changes.join(", ")}` : "";
+    const warningsText = lintWarnings && lintWarnings.length > 0
+        ? `\nmarkdown lint warnings (not auto-fixable):\n- ${lintWarnings.join("\n- ")}`
+        : "";
+    return { content: [{ type: "text", text: `Updated memory '${id}'${fieldText}${warningsText}\n${formatPersistenceSummary(persistence)}` }], structuredContent };
 });
 // ── forget ────────────────────────────────────────────────────────────────────
 server.registerTool("forget", {
@@ -2486,6 +2529,7 @@ server.registerTool("get", {
             project: noteProjectRef(note),
             tags: note.tags,
             lifecycle: note.lifecycle,
+            role: note.role,
             alwaysLoad: note.alwaysLoad,
             relatedTo: note.relatedTo,
             createdAt: note.createdAt,
@@ -2501,7 +2545,7 @@ server.registerTool("get", {
     const lines = [];
     for (const note of found) {
         lines.push(`## ${note.title} (${note.id})`);
-        lines.push(`project: ${note.project?.name ?? "global"} | stored: ${note.vault} | lifecycle: ${note.lifecycle}`);
+        lines.push(`project: ${note.project?.name ?? "global"} | stored: ${note.vault} | lifecycle: ${note.lifecycle}${note.role ? ` | role: ${note.role}` : ""}`);
         if (note.tags.length > 0)
             lines.push(`tags: ${note.tags.join(", ")}`);
         lines.push("");
@@ -2647,6 +2691,7 @@ server.registerTool("list", {
         project: noteProjectRef(note),
         tags: note.tags,
         lifecycle: note.lifecycle,
+        role: note.role,
         vault: storageLabel(vault),
         updatedAt: note.updatedAt,
         hasRelated: note.relatedTo && note.relatedTo.length > 0,
@@ -3784,6 +3829,8 @@ const RELATIONSHIP_TYPES = [
     "explains",
     "example-of",
     "supersedes",
+    "derives-from",
+    "follows",
 ];
 server.registerTool("relate", {
     title: "Relate Memories",
@@ -3809,7 +3856,7 @@ server.registerTool("relate", {
     inputSchema: z.object({
         fromId: z.string().describe("Source memory id"),
         toId: z.string().describe("Target memory id"),
-        type: z.enum(RELATIONSHIP_TYPES).default("related-to").describe("Relationship type: 'related-to' (same topic), 'explains' (clarifies why), 'example-of' (instance of pattern), 'supersedes' (replaces)"),
+        type: z.enum(RELATIONSHIP_TYPES).default("related-to").describe("Relationship type: 'related-to' (same topic), 'explains' (clarifies why), 'example-of' (instance of pattern), 'supersedes' (replaces), 'derives-from' (derived artifact), 'follows' (sequence order)"),
         bidirectional: z.boolean().optional().default(true).describe("Add relationship in both directions (default: true)"),
         cwd: projectParam,
     }),
@@ -4981,7 +5028,7 @@ server.registerPrompt("mnemonic-workflow-hint", {
                     "- When unsure, prefer `recall` over `remember`.\n" +
                     "- For repo-related tasks, pass `cwd` so mnemonic can route project memories correctly.\n\n" +
                     "Workflow: `recall`/`list` -> `get` -> `update` or `remember` -> `relate`/`consolidate`/`move_memory`. Use `discover_tags` only when tag choice is ambiguous.\n\n" +
-                    "Roles are optional prioritization hints, not schema. Lifecycle still governs durability. `role: plan` does not imply `temporary`. Inferred roles are internal hints only. Prioritization is language-independent by default.\n\n" +
+                    "Roles are optional prioritization hints, not schema. Lifecycle still governs durability. When `lifecycle` is omitted, `remember` applies soft defaults based on role: `research`, `plan`, and `review` default to `temporary`; `decision`, `summary`, and `reference` default to `permanent`. Explicit `lifecycle` always overrides the role-based default. Inferred roles are internal hints only. Prioritization is language-independent by default.\n\n" +
                     "### Working-state continuity\n\n" +
                     "Preserve in-progress work as temporary notes when continuation value is high. Recovery happens after project orientation.\n\n" +
                     "**Checkpoint note structure (temporary notes):**\n" +
@@ -5026,6 +5073,66 @@ server.registerPrompt("mnemonic-workflow-hint", {
         },
     ],
 }));
+// ── mnemonic-rpi-workflow prompt ───────────────────────────────────────────────
+const rpiWorkflowPrompt = async () => ({
+    messages: [
+        {
+            role: "user",
+            content: {
+                type: "text",
+                text: "## RPIR workflow: research → plan → implement → review\n\n" +
+                    "mnemonic is the artifact store, not the runtime. Store workflow artifacts with correct roles and lifecycle; do not build orchestration in core.\n\n" +
+                    "### Request root note\n\n" +
+                    "For each RPIR workflow, create one request root note: `role: context`, `lifecycle: temporary`, `tags: [\"workflow\", \"request\"]`. All artifacts relate to it.\n\n" +
+                    "### Stage 1 — Research\n\n" +
+                    "- Create or update request root note.\n" +
+                    "- Create research notes: `role: research`, `lifecycle: temporary`.\n" +
+                    "- Distill a short research summary when findings are scattered.\n" +
+                    "- Link research `related-to` request root.\n" +
+                    "- Before creating research notes, call `recall` to check whether existing notes already cover the topic.\n\n" +
+                    "### Stage 2 — Plan\n\n" +
+                    "- Create or update one plan note: `role: plan`, `lifecycle: temporary`.\n" +
+                    "- Link plan `related-to` request root + key research notes.\n" +
+                    "- Keep plan concise and executable.\n" +
+                    "- REQUIRES: One current plan per request. Update or supersede when plan evolves.\n" +
+                    "- Material changes (architecture, scope, ordering, validation, assumptions): update plan note first, then continue.\n" +
+                    "- Non-material changes (wording, phrasing, detail): update inline without branching.\n\n" +
+                    "### Stage 3 — Implement\n\n" +
+                    "- Create temporary apply/task notes, tagged with `apply`.\n" +
+                    "- Use `role: plan` for executable steps. Use `role: context` for observations and checkpoints.\n" +
+                    "- Link apply notes `related-to` plan.\n" +
+                    "- For non-trivial work, hand narrow context to subagent: request note, current plan or relevant slice, key research notes, narrow file/task scope.\n" +
+                    "- Subagent returns: updated apply note, optional review note, recommendation (continue / block / update plan).\n\n" +
+                    "### Stage 4 — Review\n\n" +
+                    "- Create review notes: `role: review`, `lifecycle: temporary`.\n" +
+                    "- Link review `related-to` apply or plan.\n" +
+                    "- Fix directly or mark blockers.\n" +
+                    "- If review changes the plan materially, update plan note first.\n\n" +
+                    "### Stage 5 — Consolidate\n\n" +
+                    "At workflow end:\n" +
+                    "- Create decision note for resolved approaches (`lifecycle: permanent`).\n" +
+                    "- Create summary note for outcome recaps (`lifecycle: permanent`).\n" +
+                    "- Promote reusable facts and patterns into permanent reference notes.\n" +
+                    "- Let pure scaffolding and redundant checkpoints expire as temporary notes.\n\n" +
+                    "### Relationship conventions\n\n" +
+                    "Minimal set. Link to immediate upstream artifacts only. No dense cross-linking.\n" +
+                    "- research → request root\n" +
+                    "- plan → request root + key research notes\n" +
+                    "- apply/task → plan\n" +
+                    "- review → apply or plan\n" +
+                    "- outcome → plan (optionally request root)\n\n" +
+                    "### Commit discipline\n\n" +
+                    "Three classes: memory (research/plan/review artifacts), work (code/test/docs), memory (consolidation/promotion). When plan changes materially: update notes, commit memory, then continue work.\n\n" +
+                    "### Iterate?\n\n" +
+                    "Only when review or checks warrant it. Not the default.",
+            },
+        },
+    ],
+});
+server.registerPrompt("mnemonic-rpi-workflow", {
+    title: "RPI Workflow: Research → Plan → Implement → Review",
+    description: "Stage protocol and conventions for structured task workflows using mnemonic as artifact store.",
+}, rpiWorkflowPrompt);
 // ── start ─────────────────────────────────────────────────────────────────────
 await warnAboutPendingMigrationsOnStartup();
 const transport = new StdioServerTransport();