@danielmarbach/mnemonic-mcp 0.18.0 → 0.19.1

package/CHANGELOG.md

@@ -4,6 +4,29 @@ 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.1] - 2026-03-28
+
+### Fixed
+
+- Thin dynamic theme buckets (fewer than 2 notes) are now collapsed into "other" in `project_memory_summary`, reducing theme noise without affecting fixed themes.
+- `suggestedNext` in `project_memory_summary` now prefers theme-diverse anchors, avoiding suggestions that repeat the primary entry's theme.
+- `changeDescription` for `unknown`-category history entries now uses stats to produce "Substantially updated the note." or "Minor update to the note." instead of always "Updated the note."
+- `summarizeHistory` now produces more informative summaries for `unknown`-dominant multi-commit notes, using total additions and substantial-update count as signals.
+- `isProjectionStale` now skips re-embedding when `updatedAt` differs but projected content is unchanged, avoiding unnecessary re-embeds for relationship-only note changes.
+
+## [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

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
 
@@ -556,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, classifyThemeWithGraduation, computeThemesWithGraduation, 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");
 }
@@ -1817,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) });
         }
     }
@@ -1842,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)
@@ -1878,6 +1886,7 @@ server.registerTool("recall", {
                 provenance,
                 confidence,
                 history,
+                historySummary,
                 relationships,
             });
         }
@@ -2839,12 +2848,38 @@ 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)
-    // This uses simple classifyTheme for consistent diversity calculations
-    const themeCache = buildThemeCache(projectEntries.map(e => e.note));
+    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) {
@@ -2857,6 +2892,17 @@ server.registerTool("project_memory_summary", {
     const fixedThemes = ["overview", "decisions", "tooling", "bugs", "architecture", "quality"];
     const dynamicThemes = graduationResult.promotedThemes.filter(t => !fixedThemes.includes(t));
     const themeOrder = [...fixedThemes, ...dynamicThemes.sort(), "other"];
+    // Collapse thin dynamic-theme buckets (< 2 notes) into "other" to reduce noise.
+    // Fixed themes are kept even when small; only keyword-graduated themes are collapsed.
+    const fixedThemeSet = new Set(fixedThemes);
+    for (const [theme, bucket] of Array.from(themed.entries())) {
+        if (!fixedThemeSet.has(theme) && theme !== "other" && bucket.length < 2) {
+            const otherBucket = themed.get("other") ?? [];
+            otherBucket.push(...bucket);
+            themed.set("other", otherBucket);
+            themed.delete(theme);
+        }
+    }
     // Calculate notes distribution (project-scoped only)
     const projectVaultCount = projectEntries.filter(e => e.vault.isProject).length;
     const mainVaultProjectEntries = projectEntries.filter(e => !e.vault.isProject);
@@ -2877,7 +2923,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}\`)`));
@@ -2897,49 +2943,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)
@@ -3039,8 +3068,29 @@ server.registerTool("project_memory_summary", {
     };
     const primaryEnriched = primaryAnchor ? await enrichOrientationNote(primaryAnchor) : {};
     const primaryRelationships = primaryAnchor ? await enrichOrientationNoteWithRelationships(primaryAnchor) : {};
-    const suggestedEnriched = await Promise.all(anchors.slice(1, 4).map(enrichOrientationNote));
-    const suggestedRelationships = await Promise.all(anchors.slice(1, 4).map(enrichOrientationNoteWithRelationships));
+    // Select theme-diverse suggestedNext: avoid repeating the primary anchor's theme.
+    // Backfills without constraint if not enough theme-distinct candidates exist.
+    const primaryTheme = primaryAnchor ? (themeCache.get(primaryAnchor.id) ?? "other") : "other";
+    const usedSuggestedThemes = new Set([primaryTheme]);
+    const suggestedCandidates = [];
+    for (const anchor of anchors.slice(1)) {
+        if (suggestedCandidates.length >= 3)
+            break;
+        const anchorTheme = themeCache.get(anchor.id) ?? "other";
+        if (!usedSuggestedThemes.has(anchorTheme)) {
+            suggestedCandidates.push(anchor);
+            usedSuggestedThemes.add(anchorTheme);
+        }
+    }
+    for (const anchor of anchors.slice(1)) {
+        if (suggestedCandidates.length >= 3)
+            break;
+        if (!suggestedCandidates.includes(anchor)) {
+            suggestedCandidates.push(anchor);
+        }
+    }
+    const suggestedEnriched = await Promise.all(suggestedCandidates.map(enrichOrientationNote));
+    const suggestedRelationships = await Promise.all(suggestedCandidates.map(enrichOrientationNoteWithRelationships));
     // Enrich fallback primaryEntry when no anchors exist
     let fallbackEnriched = {};
     let fallbackRelationships = {};
@@ -3075,7 +3125,7 @@ server.registerTool("project_memory_summary", {
                 ...fallbackEnriched,
                 ...fallbackRelationships,
             },
-        suggestedNext: anchors.slice(1, 4).map((a, i) => ({
+        suggestedNext: suggestedCandidates.map((a, i) => ({
             id: a.id,
             title: a.title,
             rationale: `Centrality ${a.centrality}, connects ${a.connectionDiversity} themes`,
@@ -4597,18 +4647,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" +