@danielmarbach/mnemonic-mcp 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ 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.
 
+## [0.19.0] - 2026-03-28
+
+### Added
+
+- Role and importance inference (`src/role-suggestions.ts`): notes are automatically assigned a suggested `role` and `importance` from structural signals; inference is language-independent and never overwrites explicit frontmatter.
+- `alwaysLoad: true` in note frontmatter marks a note as an explicit session anchor with highest recall and relationship-expansion priority.
+- `recall` and relationship expansion now factor in effective role and importance, so summary and decision notes surface higher without manual tagging.
+- Temporal recall history entries now include a `changeDescription` and notes include a `historySummary` capturing the overall evolution pattern; classification uses structural signals only and degrades gracefully when stats are unavailable.
+
+### Changed
+
+- The workflow hint and user-facing docs now state that roles are optional prioritization hints, inferred roles stay internal-only, lifecycle remains the durability control, and default prioritization is language-independent.
+
+## [0.18.0] - 2026-03-27
+
+### Added
+
+- Theme graduation from "other": keywords appearing across multiple notes become named themes automatically.
+- Keyword extraction with synonym normalization for theme classification.
+- `analyzeThemeQuality()` utility for checking theme distribution metrics.
+
+### Changed
+
+- All 23 MCP tools now include complete SDK tool hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`). Previously, read-only tools were missing `destructiveHint: false`.
+- Mutating tool retry results now return explicit recovery guidance instead of vague `Retry: safe` text, including recovery kind and no-inference instructions for partial-persistence failures.
+- Recovery precedence is now encoded in retry metadata: deterministic tool reconciliation is preferred where available, and same-vault retries must be replayed serially.
+- Retry metadata now uses `attemptedCommit.subject` instead of `attemptedCommit.message`.
+- `classifyTheme` now uses keyword-based graduation in addition to tag matching.
+- `project_memory_summary` includes both fixed themes and dynamically promoted keywords.
+
 ## [0.17.0] - 2026-03-25
 
 ### Added

package/README.md

@@ -310,6 +310,16 @@ Project identity derives from the **git remote URL**, normalized to a stable slu
 
 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.
 
+**What temporal mode shows:**
+
+- **Per-change descriptions** (`changeDescription`): human-readable summaries like "Expanded the note with additional detail" or "Minor refinement to existing content."
+- **Note-level history summaries** (`historySummary`): overall patterns like "The core decision remained stable while rationale and examples expanded." or "The note was connected to related work through incremental updates."
+- **Semantic change categories**: create, refine, expand, clarify, connect, restructure, reverse, unknown
+
+**How it works:**
+
+mnemonic interprets change semantically using structural and statistical signals (size ratios, heading changes, section movements) rather than language-dependent analysis. Raw diffs are intentionally NOT part of default temporal output—you get interpretive summaries that explain what kind of change happened, not patch noise.
+
 Use `verbose: true` together with temporal mode when you want richer change stats such as additions, deletions, files changed, and change classification. Those stats describe the whole commit that touched the note, not a raw diff excerpt, so recall stays bounded and does not return full diffs.
 
 The `scope` parameter on `recall` narrows results:
@@ -325,6 +335,14 @@ Each note carries a `lifecycle`:
 - `"permanent"` *(default)* — durable knowledge for future sessions
 - `"temporary"` — working-state scaffolding (plans, WIP checkpoints) that can be cleaned up once consolidated
 
+### 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`.
+
+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`.
+
 ### Note format
 
 Notes are standard markdown with YAML frontmatter:
@@ -422,7 +440,7 @@ Imported notes are written to the main vault with `lifecycle: permanent` and `sc
 
 | Prompt | Description |
 |--------|-------------|
-| `mnemonic-workflow-hint` | Optional. Returns an imperative decision protocol for weaker and stronger models: use `recall` or `list` first, inspect with `get`, update existing memories, remember only when nothing matches, then organize with `relate`, `consolidate`, or `move_memory`. Not auto-injected — request it on demand. |
+| `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`. Also reminds models that roles are optional prioritization hints, inferred roles are internal-only, prioritization is language-independent by default, and lifecycle stays separate. |
 
 ## Tools
 
@@ -452,6 +470,18 @@ Imported notes are written to the main vault with `lifecycle: permanent` and `sc
 | `update`                    | Update note content/title/tags/lifecycle, re-embeds always               |
 | `where_is_memory`           | Show note's project association and storage location                     |
 
+### Theme emergence
+
+`project_memory_summary` categorizes notes by theme. Themes **emerge automatically** from your notes:
+
+- **Tag-based classification** — notes with matching tags (e.g., `["decisions"]`, `["bugs"]`) are grouped immediately
+- **Keyword graduation** — keywords that appear across multiple notes become named themes over time
+- **"other" bucket** — notes that don't match any theme are grouped here; this shrinks as themes emerge
+
+No predefined schema required. The system adapts to your project's vocabulary.
+
+**Language handling:** The system degrades gracefully for non-English notes. Stopwords and synonyms are optional English enhancements; keywords that don't match pass through unchanged, allowing non-English keywords to graduate if they meet frequency thresholds.
+
 ### Relationships
 
 Notes can be linked with typed edges stored in frontmatter:
@@ -544,6 +574,8 @@ mnemonic and Beads address complementary concerns. mnemonic is a **knowledge gra
 
 mnemonic distinguishes between two lifecycle states. `temporary` notes capture evolving working-state: hypotheses, in-progress plans, experiment results, draft reasoning. `permanent` notes capture durable knowledge: decisions, root cause explanations, architectural guidance, lessons learned. As an investigation progresses, a cluster of temporary notes is typically `consolidate`d into one or more permanent notes, and the scaffolding is discarded. This two-phase lifecycle keeps exploratory thinking from polluting long-term memory while still giving agents a place to reason incrementally before committing to a conclusion.
 
+Roles, when present, are separate from lifecycle: they help prioritization and retrieval, not retention policy. mnemonic still works without roles, and any inferred role metadata remains an internal hint rather than part of the user-facing note contract.
+
 ## Contributing
 
 See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup, dogfooding workflow, testing requirements, and pull request guidelines.

package/build/index.js

@@ -8,16 +8,18 @@ import { promises as fs } from "fs";
 import { NOTE_LIFECYCLES } from "./storage.js";
 import { embed, cosineSimilarity, embedModel } from "./embeddings.js";
 import { buildTemporalHistoryEntry, computeConfidence, getNoteProvenance } from "./provenance.js";
+import { enrichTemporalHistory } from "./temporal-interpretation.js";
 import { getOrBuildProjection } from "./projections.js";
 import { invalidateActiveProjectCache, getOrBuildVaultEmbeddings, getOrBuildVaultNoteList, getSessionCachedNote, } from "./cache.js";
 import { performance } from "perf_hooks";
 import { filterRelationships, mergeRelationshipsFromNotes, normalizeMergePlanSourceIds, resolveEffectiveConsolidationMode, } from "./consolidate.js";
-import { selectRecallResults } from "./recall.js";
+import { computeRecallMetadataBoost, selectRecallResults } from "./recall.js";
 import { getRelationshipPreview } from "./relationships.js";
 import { cleanMarkdown } from "./markdown.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, summarizePreview, titleCaseTheme, withinThemeScore, anchorScore, buildThemeCache, computeConnectionDiversity, } from "./project-introspection.js";
+import { classifyTheme, classifyThemeWithGraduation, computeThemesWithGraduation, summarizePreview, titleCaseTheme, withinThemeScore, anchorScore, computeConnectionDiversity, } from "./project-introspection.js";
+import { getEffectiveMetadata } from "./role-suggestions.js";
 import { detectProject, getCurrentGitBranch, resolveProjectIdentity } from "./project.js";
 import { VaultManager } from "./vault.js";
 import { checkBranchChange } from "./branch-tracker.js";
@@ -405,7 +407,8 @@ function formatTemporalHistory(history) {
     const lines = ["**history:**"];
     for (const entry of history) {
         const summary = entry.summary ? ` — ${entry.summary}` : "";
-        lines.push(`- \`${entry.commitHash.slice(0, 7)}\` ${entry.timestamp} — ${entry.message}${summary}`);
+        const changeDesc = entry.changeDescription ? ` (${entry.changeDescription})` : "";
+        lines.push(`- \`${entry.commitHash.slice(0, 7)}\` ${entry.timestamp} — ${entry.message}${summary}${changeDesc}`);
     }
     return lines.join("\n");
 }
@@ -693,9 +696,22 @@ function buildMutationRetryContract(args) {
     if (args.commit.status !== "failed") {
         return undefined;
     }
+    const recoveryKind = args.preferredRecovery ?? (args.mutationApplied
+        ? "manual-exact-git-recovery"
+        : "no-manual-recovery");
+    const recoveryReason = recoveryKind === "rerun-tool-call-serial"
+        ? "Tool-level reconciliation exists for this mutation; rerun the same tool call serially for the affected vault."
+        : recoveryKind === "manual-exact-git-recovery"
+            ? "Mutation is already persisted on disk; manual git recovery is allowed only with the exact attemptedCommit values."
+            : "Mutation was not applied deterministically; manual git recovery is not authorized.";
     return {
+        recovery: {
+            kind: recoveryKind,
+            allowed: recoveryKind !== "no-manual-recovery",
+            reason: recoveryReason,
+        },
         attemptedCommit: {
-            message: args.commitMessage,
+            subject: args.commitMessage,
             body: args.commitBody,
             files: args.files,
             cwd: args.cwd,
@@ -708,19 +724,69 @@ function buildMutationRetryContract(args) {
         rationale: args.mutationApplied
             ? "Mutation is already persisted on disk; commit can be retried deterministically."
             : "Mutation was not applied; retry may require re-running the operation.",
+        instructions: {
+            sourceOfTruth: recoveryKind === "manual-exact-git-recovery" ? "attemptedCommit" : "tool-response",
+            useExactSubject: recoveryKind === "manual-exact-git-recovery",
+            useExactBody: recoveryKind === "manual-exact-git-recovery",
+            useExactFiles: recoveryKind === "manual-exact-git-recovery",
+            forbidInferenceFromHistory: true,
+            forbidInferenceFromTitleOrSummary: true,
+            forbidParallelSameVaultRetries: true,
+            preferToolReconciliation: recoveryKind === "rerun-tool-call-serial",
+            rerunSameToolCallSerially: recoveryKind === "rerun-tool-call-serial",
+        },
     };
 }
 function formatRetrySummary(retry) {
     if (!retry) {
         return undefined;
     }
-    const safety = retry.retrySafe ? "safe" : "requires review";
     const opLabel = retry.attemptedCommit.operation === "add" ? "add" : "commit";
     const error = retry.attemptedCommit.error;
-    return [
-        `Retry: ${safety} | vault=${retry.attemptedCommit.vault} | files=${retry.attemptedCommit.files.length}`,
-        `Git ${opLabel} error: ${error}`,
-    ].join("\n");
+    const lines = [];
+    switch (retry.recovery.kind) {
+        case "rerun-tool-call-serial":
+            lines.push("Recovery: rerun same tool call serially");
+            lines.push(retry.recovery.reason);
+            lines.push("Rerun the same mnemonic tool call one time for the affected vault.");
+            lines.push("Do not replay same-vault mutations in parallel.");
+            lines.push("Manual git recovery is not authorized for this failure.");
+            lines.push("Git failure:");
+            lines.push(`${opLabel}: ${error}`);
+            break;
+        case "manual-exact-git-recovery":
+            lines.push("Recovery: manual exact git recovery allowed");
+            lines.push(retry.recovery.reason);
+            lines.push("Use only the exact values below. Do not infer from git history, note title, summary, or repo state.");
+            lines.push("");
+            lines.push("Commit subject:");
+            lines.push(retry.attemptedCommit.subject);
+            if (retry.attemptedCommit.body) {
+                lines.push("");
+                lines.push("Commit body:");
+                lines.push(retry.attemptedCommit.body);
+            }
+            lines.push("");
+            lines.push("Files:");
+            for (const file of retry.attemptedCommit.files) {
+                lines.push(`- ${file}`);
+            }
+            lines.push("");
+            lines.push("Git failure:");
+            lines.push(`${opLabel}: ${error}`);
+            break;
+        case "no-manual-recovery":
+            lines.push("Recovery: no manual recovery authorized");
+            lines.push(retry.recovery.reason);
+            lines.push("Git failure:");
+            lines.push(`${opLabel}: ${error}`);
+            break;
+        default: {
+            const _exhaustive = retry.recovery.kind;
+            throw new Error(`Unknown recovery kind: ${_exhaustive}`);
+        }
+    }
+    return lines.join("\n");
 }
 function formatPersistenceSummary(persistence) {
     const parts = [
@@ -731,14 +797,14 @@ function formatPersistenceSummary(persistence) {
     if (persistence.embedding.reason) {
         lines[0] += ` | embedding reason=${persistence.embedding.reason}`;
     }
-    if (persistence.git.commit === "failed" && persistence.git.commitError) {
+    const retrySummary = formatRetrySummary(persistence.retry);
+    if (!retrySummary && persistence.git.commit === "failed" && persistence.git.commitError) {
         const opLabel = persistence.git.commitOperation === "add" ? "add" : "commit";
         lines.push(`Git ${opLabel} error: ${persistence.git.commitError}`);
     }
     if (persistence.git.push === "failed" && persistence.git.pushError) {
         lines.push(`Git push error: ${persistence.git.pushError}`);
     }
-    const retrySummary = formatRetrySummary(persistence.retry);
     if (retrySummary) {
         lines.push(retrySummary);
     }
@@ -969,6 +1035,7 @@ server.registerTool("detect_project", {
         "- Use `recall` or `project_memory_summary` to orient on existing memory.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -1023,6 +1090,7 @@ server.registerTool("get_project_identity", {
         "- Use `set_project_identity` only if the wrong remote is defining identity.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -1179,6 +1247,7 @@ server.registerTool("list_migrations", {
         "- Run `execute_migration` with `dryRun: true` first.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -1600,6 +1669,7 @@ server.registerTool("get_project_memory_policy", {
         "- Call `remember` with explicit `scope` for a one-off override, or `set_project_memory_policy` to change defaults.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -1673,6 +1743,7 @@ server.registerTool("recall", {
         "- Use `get`, `update`, `relate`, or `consolidate` based on the results.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: true,
     },
@@ -1749,7 +1820,8 @@ server.registerTool("recall", {
                 if (isProjectNote)
                     continue;
             }
-            const boost = isCurrentProject ? 0.15 : 0;
+            const metadataBoost = computeRecallMetadataBoost(getEffectiveMetadata(note));
+            const boost = (isCurrentProject ? 0.15 : 0) + metadataBoost;
             scored.push({ id: rec.id, score: rawScore, boosted: rawScore + boost, vault, isCurrentProject: Boolean(isCurrentProject) });
         }
     }
@@ -1774,13 +1846,17 @@ server.registerTool("recall", {
             const provenance = await getNoteProvenance(vault.git, filePath);
             const confidence = computeConfidence(note.lifecycle, note.updatedAt, centrality);
             let history;
+            let historySummary;
             if (mode === "temporal") {
                 if (index < TEMPORAL_HISTORY_NOTE_LIMIT) {
                     const commits = await vault.git.getFileHistory(filePath, TEMPORAL_HISTORY_COMMIT_LIMIT);
-                    history = await Promise.all(commits.map(async (commit) => {
+                    const rawHistory = await Promise.all(commits.map(async (commit) => {
                         const stats = await vault.git.getCommitStats(filePath, commit.hash);
                         return buildTemporalHistoryEntry(commit, stats, verbose);
                     }));
+                    const enriched = enrichTemporalHistory(rawHistory);
+                    history = enriched.interpretedHistory;
+                    historySummary = enriched.historySummary;
                 }
             }
             // Add relationship preview for top N results (fail-soft)
@@ -1810,6 +1886,7 @@ server.registerTool("recall", {
                 provenance,
                 confidence,
                 history,
+                historySummary,
                 relationships,
             });
         }
@@ -2107,6 +2184,7 @@ server.registerTool("get", {
         "- Use `update`, `forget`, `move_memory`, or `relate` after inspection.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -2204,6 +2282,7 @@ server.registerTool("where_is_memory", {
         "- Use `move_memory` if the storage location is wrong, or `get` for full inspection.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -2260,6 +2339,7 @@ server.registerTool("list", {
         "- Use `get` for exact inspection or `update` / `consolidate` for cleanup.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -2370,6 +2450,7 @@ server.registerTool("discover_tags", {
         "Read-only.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -2576,6 +2657,7 @@ server.registerTool("recent_memories", {
         "- Use `get` for exact inspection or `update` to continue refining a recent note.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -2645,6 +2727,7 @@ server.registerTool("memory_graph", {
         "- Use `get`, `relate`, `unrelate`, or `consolidate` based on what the graph reveals.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -2724,6 +2807,7 @@ server.registerTool("project_memory_summary", {
         "- Use `recall` or `list` to drill down into specific areas.",
     annotations: {
         readOnlyHint: true,
+        destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
     },
@@ -2764,18 +2848,50 @@ server.registerTool("project_memory_summary", {
         return { content: [{ type: "text", text: `No memories found for project ${project.name}.` }], structuredContent };
     }
     const policyLine = await formatProjectPolicyLine(project.id);
-    // Build theme cache for connection diversity scoring (project-scoped only)
-    const themeCache = buildThemeCache(projectEntries.map(e => e.note));
-    // Categorize by theme (project-scoped only)
+    const projectNoteIds = new Set(projectEntries.map(e => e.note.id));
+    // Compute promoted themes from keywords (graduation system)
+    const graduationResult = computeThemesWithGraduation(projectEntries.map(e => e.note));
+    const promotedThemes = new Set(graduationResult.promotedThemes);
+    const themeCache = graduationResult.themeAssignments;
+    const inboundReferences = new Map();
+    const linkedByPermanentNotes = new Map();
+    for (const entry of projectEntries) {
+        for (const rel of entry.note.relatedTo ?? []) {
+            if (!projectNoteIds.has(rel.id)) {
+                continue;
+            }
+            inboundReferences.set(rel.id, (inboundReferences.get(rel.id) ?? 0) + 1);
+            if (entry.note.lifecycle === "permanent") {
+                linkedByPermanentNotes.set(rel.id, (linkedByPermanentNotes.get(rel.id) ?? 0) + 1);
+            }
+        }
+    }
+    const effectiveMetadataById = new Map(projectEntries.map((entry) => {
+        const inbound = inboundReferences.get(entry.note.id) ?? 0;
+        const visibleOutbound = (entry.note.relatedTo ?? []).filter((rel) => projectNoteIds.has(rel.id)).length;
+        const metadata = getEffectiveMetadata(entry.note, {
+            inboundReferences: inbound,
+            linkedByPermanentNotes: linkedByPermanentNotes.get(entry.note.id) ?? 0,
+            anchorCandidate: entry.note.lifecycle === "permanent" && (visibleOutbound > 0 || inbound > 0),
+        });
+        return [entry.note.id, {
+                metadata,
+                inbound,
+                visibleOutbound,
+            }];
+    }));
+    // Categorize by theme with graduation (project-scoped only)
     const themed = new Map();
     for (const entry of projectEntries) {
-        const theme = classifyTheme(entry.note);
+        const theme = classifyThemeWithGraduation(entry.note, promotedThemes);
         const bucket = themed.get(theme) ?? [];
         bucket.push(entry);
         themed.set(theme, bucket);
     }
-    // Theme order for display
-    const themeOrder = ["overview", "decisions", "tooling", "bugs", "architecture", "quality", "other"];
+    // Theme order: fixed themes first, then promoted themes alphabetically, then "other"
+    const fixedThemes = ["overview", "decisions", "tooling", "bugs", "architecture", "quality"];
+    const dynamicThemes = graduationResult.promotedThemes.filter(t => !fixedThemes.includes(t));
+    const themeOrder = [...fixedThemes, ...dynamicThemes.sort(), "other"];
     // Calculate notes distribution (project-scoped only)
     const projectVaultCount = projectEntries.filter(e => e.vault.isProject).length;
     const mainVaultProjectEntries = projectEntries.filter(e => !e.vault.isProject);
@@ -2796,7 +2912,7 @@ server.registerTool("project_memory_summary", {
         if (!bucket || bucket.length === 0)
             continue;
         // Sort by within-theme score
-        const sorted = [...bucket].sort((a, b) => withinThemeScore(b.note) - withinThemeScore(a.note));
+        const sorted = [...bucket].sort((a, b) => withinThemeScore(b.note, effectiveMetadataById.get(b.note.id)?.metadata) - withinThemeScore(a.note, effectiveMetadataById.get(a.note.id)?.metadata));
         const top = sorted.slice(0, maxPerTheme);
         sections.push(`\n${titleCaseTheme(theme)}:`);
         sections.push(...top.map(e => `- ${e.note.title} (\`${e.note.id}\`)`));
@@ -2816,49 +2932,32 @@ server.registerTool("project_memory_summary", {
     sections.push(`\nRecent activity (start here):`);
     sections.push(...recent.map(e => `- ${e.note.updatedAt} — ${e.note.title}`));
     // Anchor notes with diversity constraint (project-scoped only)
-    // Separate tagged anchors (can have no relationships) from scored anchors (need relationships)
-    const taggedAnchorEntries = projectEntries.filter(e => e.note.lifecycle === "permanent" &&
-        e.note.tags.some(t => t.toLowerCase() === "anchor" || t.toLowerCase() === "alwaysload"));
     const scoredAnchorCandidates = projectEntries
-        .filter(e => e.note.lifecycle === "permanent" && (e.note.relatedTo?.length ?? 0) > 0)
-        .map(e => ({
-        entry: e,
-        score: anchorScore(e.note, themeCache),
-        theme: classifyTheme(e.note),
-    }))
-        .filter(x => x.score > -Infinity)
-        .sort((a, b) => b.score - a.score);
-    // Score tagged anchors too, so they can compete for primaryEntry
-    const scoredTaggedAnchors = taggedAnchorEntries
-        .map(e => ({
-        entry: e,
-        score: anchorScore(e.note, themeCache),
-        theme: classifyTheme(e.note),
-    }))
-        .sort((a, b) => b.score - a.score);
+        .map(e => {
+        const baselineContext = effectiveMetadataById.get(e.note.id);
+        const metadata = baselineContext?.metadata;
+        return {
+            entry: e,
+            metadata,
+            score: anchorScore(e.note, themeCache, metadata),
+            theme: themeCache.get(e.note.id) ?? "other",
+            alwaysLoad: metadata?.alwaysLoad === true,
+            explicitOrientationRole: metadata?.roleSource === "explicit" &&
+                (metadata.role === "summary" || metadata.role === "decision"),
+            hasVisibleGraphParticipation: (baselineContext?.visibleOutbound ?? 0) > 0 || (baselineContext?.inbound ?? 0) > 0,
+        };
+    })
+        .filter(candidate => candidate.score > -Infinity)
+        .filter(candidate => candidate.alwaysLoad || candidate.explicitOrientationRole || candidate.hasVisibleGraphParticipation)
+        .sort((a, b) => b.score - a.score || a.entry.note.title.localeCompare(b.entry.note.title));
     // Enforce max 2 per theme for scored anchors
     const anchorThemeCounts = new Map();
     const anchors = [];
     const anchorIds = new Set();
-    // Add tagged anchors first (capped at 10 total across all themes), scored by anchorScore
-    for (const candidate of scoredTaggedAnchors.slice(0, 10)) {
-        if (anchors.length >= 10)
-            break;
-        anchors.push({
-            id: candidate.entry.note.id,
-            title: candidate.entry.note.title,
-            centrality: candidate.entry.note.relatedTo?.length ?? 0,
-            connectionDiversity: computeConnectionDiversity(candidate.entry.note, themeCache),
-            updatedAt: candidate.entry.note.updatedAt,
-        });
-        anchorIds.add(candidate.entry.note.id);
-    }
     // Add scored anchors with theme diversity constraint
     for (const candidate of scoredAnchorCandidates) {
         if (anchors.length >= 10)
             break;
-        if (anchorIds.has(candidate.entry.note.id))
-            continue;
         const theme = candidate.theme;
         const themeCount = anchorThemeCounts.get(theme) ?? 0;
         if (themeCount >= 2)
@@ -3051,7 +3150,7 @@ server.registerTool("project_memory_summary", {
             id: e.note.id,
             title: e.note.title,
             updatedAt: e.note.updatedAt,
-            theme: classifyTheme(e.note),
+            theme: classifyThemeWithGraduation(e.note, promotedThemes),
         })),
         anchors,
         orientation,
@@ -3403,6 +3502,7 @@ server.registerTool("relate", {
                     cwd,
                     vault,
                     mutationApplied: true,
+                    preferredRecovery: "rerun-tool-call-serial",
                 });
                 const structuredContent = {
                     action: "related",
@@ -3452,6 +3552,7 @@ server.registerTool("relate", {
                 cwd,
                 vault,
                 mutationApplied: true,
+                preferredRecovery: "rerun-tool-call-serial",
             });
         }
         if (commitStatus.status === "committed") {
@@ -3574,6 +3675,7 @@ server.registerTool("unrelate", {
                     cwd,
                     vault,
                     mutationApplied: true,
+                    preferredRecovery: "rerun-tool-call-serial",
                 });
                 const structuredContent = {
                     action: "unrelated",
@@ -3617,6 +3719,7 @@ server.registerTool("unrelate", {
                 cwd,
                 vault,
                 mutationApplied: true,
+                preferredRecovery: "rerun-tool-call-serial",
             });
         }
         if (commitStatus.status === "committed") {
@@ -4512,18 +4615,13 @@ server.registerPrompt("mnemonic-workflow-hint", {
                 type: "text",
                 text: "## Mnemonic MCP workflow hints\n\n" +
                     "Avoid duplicate memories. Prefer inspecting and updating existing memories before creating new ones.\n\n" +
-                    "### Hard rules\n\n" +
                     "- REQUIRES: Before `remember`, call `recall` or `list` first.\n" +
                     "- If `recall` or `list` returns a plausible match, call `get` before deciding whether to `update` or `remember`.\n" +
                     "- If an existing memory already covers the topic, use `update`, not `remember`.\n" +
                     "- When unsure, prefer `recall` over `remember`.\n" +
                     "- For repo-related tasks, pass `cwd` so mnemonic can route project memories correctly.\n\n" +
-                    "### Decision protocol\n\n" +
-                    "1. Need to store, refine, or connect knowledge about a topic? Start with `recall`, or use `list` when you need deterministic browsing by scope, storage, or tags.\n" +
-                    "2. If `recall` or `list` returns matching ids, use `get` to inspect the best match.\n" +
-                    "3. If one memory should be refined, call `update`.\n" +
-                    "4. If no memory covers the topic and tag choice is ambiguous, call `discover_tags` with note context, then call `remember`.\n" +
-                    "5. After storing or updating, use `relate` for strong connections, `consolidate` for overlap, and `move_memory` for wrong storage location.\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" +
                     "### Anti-patterns\n\n" +
                     "- Bad: call `remember` immediately because the user said 'remember'.\n" +
                     "- Good: `recall` or `list` first, then `get`, then `update` or `remember`.\n" +