@danielmarbach/mnemonic-mcp 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.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
+
+- `update` now supports `semanticPatch` for token-efficient targeted edits (insert, replace, append, remove content under specific headings) without round-tripping the full note body.
+
 ## [0.23.0] - 2026-04-17
 
 ### 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,11 @@ 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 { 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";
 import { classifyTheme, classifyThemeWithGraduation, computeThemesWithGraduation, summarizePreview, titleCaseTheme, daysSinceUpdate, withinThemeScore, anchorScore, computeConnectionDiversity, workingStateScore, extractNextAction, } from "./project-introspection.js";
@@ -406,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) {
@@ -923,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(", ")}`);
@@ -1028,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",
@@ -1425,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()
@@ -1453,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);
@@ -1482,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,
@@ -1840,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" +
@@ -1866,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
@@ -1995,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 };
@@ -2056,6 +2078,7 @@ server.registerTool("recall", {
                 vault: storageLabel(vault),
                 tags: note.tags,
                 lifecycle: note.lifecycle,
+                role: note.role,
                 updatedAt: note.updatedAt,
                 provenance,
                 confidence,
@@ -2103,7 +2126,8 @@ server.registerTool("update", {
         "- The updated memory id, changed fields, and persistence status\n\n" +
         "Side effects: rewrites the note, refreshes embeddings, git commits, and may push.\n\n" +
         "Typical next step:\n" +
-        "- Use `relate` or `consolidate` if the update changes how this note connects to others.",
+        "- Use `relate` or `consolidate` if the update changes how this note connects to others.\n\n" +
+        "Use `semanticPatch` for targeted edits (more token-efficient). Use `content` only for complete rewrites.",
     annotations: {
         readOnlyHint: false,
         destructiveHint: false,
@@ -2112,13 +2136,41 @@ server.registerTool("update", {
     },
     inputSchema: z.object({
         id: z.string().describe("Exact memory id. Use an id returned by `recall`, `list`, `recent_memories`, or `where_is`."),
-        content: z.string().optional().describe("Markdown note body. Put the key fact, decision, or outcome in the opening lines, then supporting detail."),
+        semanticPatch: z
+            .array(z.object({
+            selector: z.object({
+                heading: z.string().optional(),
+                headingStartsWith: z.string().optional(),
+                nthChild: z.number().int().optional(),
+                lastChild: z.literal(true).optional(),
+            }).refine((sel) => {
+                const keys = [sel.heading, sel.headingStartsWith, sel.nthChild, sel.lastChild].filter((v) => v !== undefined);
+                return keys.length === 1;
+            }, { message: "Selector must have exactly one of: heading, headingStartsWith, nthChild, lastChild" }),
+            operation: z.discriminatedUnion("op", [
+                z.object({ op: z.literal("appendChild"), value: z.string() }),
+                z.object({ op: z.literal("prependChild"), value: z.string() }),
+                z.object({ op: z.literal("replace"), value: z.string() }),
+                z.object({ op: z.literal("replaceChildren"), value: z.string() }),
+                z.object({ op: z.literal("insertAfter"), value: z.string() }),
+                z.object({ op: z.literal("insertBefore"), value: z.string() }),
+                z.object({ op: z.literal("remove") }),
+            ]),
+        }))
+            .optional()
+            .describe("Use for targeted edits when you know the structure. More token-efficient than passing full content. " +
+            "Mutually exclusive with content."),
+        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."),
         lifecycle: z
             .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()
@@ -2133,12 +2185,18 @@ server.registerTool("update", {
             "When true, update can commit on a protected branch without changing project policy."),
     }),
     outputSchema: UpdateResultSchema,
-}, async ({ id, content, 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) {
         return { content: [{ type: "text", text: `No memory found with id '${id}'` }], isError: true };
     }
+    // Validate: content and semanticPatch are mutually exclusive
+    const hasContent = content !== undefined;
+    const hasSemanticPatch = semanticPatch !== undefined && semanticPatch.length > 0;
+    if (hasContent && hasSemanticPatch) {
+        return { content: [{ type: "text", text: "Exactly one of content or semanticPatch must be provided, not both." }], isError: true };
+    }
     const { note, vault } = found;
     if (vault.isProject) {
         const resolvedProject = await resolveProject(cwd);
@@ -2163,13 +2221,24 @@ server.registerTool("update", {
         }
     }
     const now = new Date().toISOString();
+    let patchedContent;
+    if (semanticPatch && semanticPatch.length > 0) {
+        try {
+            patchedContent = await applySemanticPatches(note.content, semanticPatch);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: "text", text: `Semantic patch failed: ${message}` }], isError: true };
+        }
+    }
     const cleanedContent = content === undefined ? undefined : await cleanMarkdown(content);
     const updated = {
         ...note,
         title: title ?? note.title,
-        content: cleanedContent ?? note.content,
+        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,
     };
@@ -2211,10 +2280,14 @@ server.registerTool("update", {
         changes.push("title");
     if (content !== undefined)
         changes.push("content");
+    if (semanticPatch !== undefined)
+        changes.push("semanticPatch");
     if (tags !== undefined)
         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";
@@ -2259,10 +2332,12 @@ server.registerTool("update", {
         timestamp: now,
         project: noteProjectRef(updated),
         lifecycle: updated.lifecycle,
+        role: updated.role,
         persistence,
     };
     invalidateActiveProjectCache();
-    return { content: [{ type: "text", text: `Updated memory '${id}'\n${formatPersistenceSummary(persistence)}` }], structuredContent };
+    const fieldText = changes.length > 0 ? `\nfields modified: ${changes.join(", ")}` : "";
+    return { content: [{ type: "text", text: `Updated memory '${id}'${fieldText}\n${formatPersistenceSummary(persistence)}` }], structuredContent };
 });
 // ── forget ────────────────────────────────────────────────────────────────────
 server.registerTool("forget", {
@@ -2442,6 +2517,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,
@@ -2457,7 +2533,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("");
@@ -2603,6 +2679,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,
@@ -3740,6 +3817,8 @@ const RELATIONSHIP_TYPES = [
     "explains",
     "example-of",
     "supersedes",
+    "derives-from",
+    "follows",
 ];
 server.registerTool("relate", {
     title: "Relate Memories",
@@ -3765,7 +3844,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,
     }),
@@ -4937,7 +5016,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" +
@@ -4982,6 +5061,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();