@danielmarbach/mnemonic-mcp 0.20.0 → 0.21.0

package/build/index.js

@@ -19,7 +19,7 @@ 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, computeConnectionDiversity, } from "./project-introspection.js";
+import { classifyTheme, classifyThemeWithGraduation, computeThemesWithGraduation, summarizePreview, titleCaseTheme, daysSinceUpdate, withinThemeScore, anchorScore, computeConnectionDiversity, workingStateScore, extractNextAction, } from "./project-introspection.js";
 import { getEffectiveMetadata } from "./role-suggestions.js";
 import { detectProject, getCurrentGitBranch, resolveProjectIdentity } from "./project.js";
 import { VaultManager } from "./vault.js";
@@ -321,6 +321,18 @@ async function resolveProject(cwd) {
         getProjectIdentityOverride: async (projectId) => configStore.getProjectIdentityOverride(projectId),
     });
 }
+function toProjectRef(project) {
+    return project ? { id: project.id, name: project.name } : undefined;
+}
+function noteProjectRef(note) {
+    if (!note.project || !note.projectName) {
+        return undefined;
+    }
+    return {
+        id: note.project,
+        name: note.projectName,
+    };
+}
 async function resolveProjectIdentityForCwd(cwd) {
     if (!cwd)
         return undefined;
@@ -1815,9 +1827,10 @@ server.registerTool("recall", {
             .describe("'project' = only this project's memories (project-scoped storage), " +
             "'global' = only unscoped memories (main/global storage), " +
             "'all' = both, with project notes boosted (default)"),
+        lifecycle: z.enum(["temporary", "permanent"]).optional().describe("Filter results by lifecycle. Useful for recovering working-state with `lifecycle: temporary` after `project_memory_summary` orientation."),
     }),
     outputSchema: RecallResultSchema,
-}, async ({ query, cwd, limit, minSimilarity, mode, verbose, tags, scope }) => {
+}, async ({ query, cwd, limit, minSimilarity, mode, verbose, tags, scope, lifecycle }) => {
     const t0Recall = performance.now();
     await ensureBranchSynced(cwd);
     const project = await resolveProject(cwd);
@@ -1863,6 +1876,9 @@ server.registerTool("recall", {
                 if (!tags.every((t) => noteTags.has(t)))
                     continue;
             }
+            if (lifecycle && note.lifecycle !== lifecycle) {
+                continue;
+            }
             const isProjectNote = note.project !== undefined;
             const isCurrentProject = project && note.project === project.id;
             if (scope === "project") {
@@ -1967,8 +1983,7 @@ server.registerTool("recall", {
                 title: note.title,
                 score,
                 boosted,
-                project: note.project,
-                projectName: note.projectName,
+                project: noteProjectRef(note),
                 vault: storageLabel(vault),
                 tags: note.tags,
                 lifecycle: note.lifecycle,
@@ -2142,8 +2157,7 @@ server.registerTool("update", {
         title: updated.title,
         fieldsModified: changes,
         timestamp: now,
-        project: updated.project,
-        projectName: updated.projectName,
+        project: noteProjectRef(updated),
         lifecycle: updated.lifecycle,
         persistence,
     };
@@ -2247,8 +2261,7 @@ server.registerTool("forget", {
         action: "forgotten",
         id,
         title: note.title,
-        project: note.project,
-        projectName: note.projectName,
+        project: noteProjectRef(note),
         relationshipsCleaned: vaultChanges.size > 0 ? Array.from(vaultChanges.values()).reduce((sum, files) => sum + files.length - 1, 0) : 0,
         vaultsModified: Array.from(vaultChanges.keys()).map(v => storageLabel(v)),
         retry,
@@ -2326,10 +2339,10 @@ server.registerTool("get", {
             id: note.id,
             title: note.title,
             content: note.content,
-            project: note.project,
-            projectName: note.projectName,
+            project: noteProjectRef(note),
             tags: note.tags,
             lifecycle: note.lifecycle,
+            alwaysLoad: note.alwaysLoad,
             relatedTo: note.relatedTo,
             createdAt: note.createdAt,
             updatedAt: note.updatedAt,
@@ -2340,7 +2353,7 @@ server.registerTool("get", {
     const lines = [];
     for (const note of found) {
         lines.push(`## ${note.title} (${note.id})`);
-        lines.push(`project: ${note.projectName ?? note.project ?? "global"} | stored: ${note.vault} | lifecycle: ${note.lifecycle}`);
+        lines.push(`project: ${note.project?.name ?? "global"} | stored: ${note.vault} | lifecycle: ${note.lifecycle}`);
         if (note.tags.length > 0)
             lines.push(`tags: ${note.tags.join(", ")}`);
         lines.push("");
@@ -2405,8 +2418,7 @@ server.registerTool("where_is_memory", {
         action: "located",
         id: note.id,
         title: note.title,
-        project: note.project,
-        projectName: note.projectName,
+        project: noteProjectRef(note),
         vault: vaultLabel,
         updatedAt: note.updatedAt,
         relatedCount,
@@ -2484,8 +2496,7 @@ server.registerTool("list", {
     const structuredNotes = entries.map(({ note, vault }) => ({
         id: note.id,
         title: note.title,
-        project: note.project,
-        projectName: note.projectName,
+        project: noteProjectRef(note),
         tags: note.tags,
         lifecycle: note.lifecycle,
         vault: storageLabel(vault),
@@ -2786,16 +2797,21 @@ server.registerTool("recent_memories", {
         limit: z.number().int().min(1).max(20).optional().default(5),
         includePreview: z.boolean().optional().default(true),
         includeStorage: z.boolean().optional().default(true),
+        lifecycle: z.enum(["temporary", "permanent"]).optional().describe("Filter results by lifecycle. Useful for recovering working-state with `lifecycle: temporary` after `project_memory_summary` orientation."),
     }),
     outputSchema: RecentResultSchema,
-}, async ({ cwd, scope, storedIn, limit, includePreview, includeStorage }) => {
+}, async ({ cwd, scope, storedIn, limit, includePreview, includeStorage, lifecycle }) => {
     await ensureBranchSynced(cwd);
     const { project, entries } = await collectVisibleNotes(cwd, scope, undefined, storedIn);
-    const recent = [...entries]
+    let filteredEntries = entries;
+    if (lifecycle) {
+        filteredEntries = entries.filter(({ note }) => note.lifecycle === lifecycle);
+    }
+    const recent = [...filteredEntries]
         .sort((a, b) => b.note.updatedAt.localeCompare(a.note.updatedAt))
         .slice(0, limit);
     if (recent.length === 0) {
-        const structuredContent = { action: "recent_shown", project: project?.id, projectName: project?.name, count: 0, limit: limit || 5, notes: [] };
+        const structuredContent = { action: "recent_shown", project: toProjectRef(project), count: 0, limit: limit || 5, notes: [] };
         return { content: [{ type: "text", text: "No memories found." }], structuredContent };
     }
     const header = project && scope !== "global"
@@ -2810,8 +2826,7 @@ server.registerTool("recent_memories", {
     const structuredNotes = recent.map(({ note, vault }) => ({
         id: note.id,
         title: note.title,
-        project: note.project,
-        projectName: note.projectName,
+        project: noteProjectRef(note),
         tags: note.tags,
         lifecycle: note.lifecycle,
         vault: storageLabel(vault),
@@ -2820,8 +2835,7 @@ server.registerTool("recent_memories", {
     }));
     const structuredContent = {
         action: "recent_shown",
-        project: project?.id,
-        projectName: project?.name,
+        project: toProjectRef(project),
         count: recent.length,
         limit: limit || 5,
         notes: structuredNotes,
@@ -2860,7 +2874,7 @@ server.registerTool("memory_graph", {
     await ensureBranchSynced(cwd);
     const { project, entries } = await collectVisibleNotes(cwd, scope, undefined, storedIn);
     if (entries.length === 0) {
-        const structuredContent = { action: "graph_shown", project: project?.id, projectName: project?.name, nodes: [], limit, truncated: false };
+        const structuredContent = { action: "graph_shown", project: toProjectRef(project), nodes: [], limit, truncated: false };
         return { content: [{ type: "text", text: "No memories found." }], structuredContent };
     }
     const visibleIds = new Set(entries.map((entry) => entry.note.id));
@@ -2875,7 +2889,7 @@ server.registerTool("memory_graph", {
     })
         .filter(Boolean);
     if (lines.length === 0) {
-        const structuredContent = { action: "graph_shown", project: project?.id, projectName: project?.name, nodes: [], limit, truncated: false };
+        const structuredContent = { action: "graph_shown", project: toProjectRef(project), nodes: [], limit, truncated: false };
         return { content: [{ type: "text", text: "No relationships found for that scope." }], structuredContent };
     }
     const header = project && scope !== "global"
@@ -2899,8 +2913,7 @@ server.registerTool("memory_graph", {
         .filter((node) => node.edges.length > 0);
     const structuredContent = {
         action: "graph_shown",
-        project: project?.id,
-        projectName: project?.name,
+        project: toProjectRef(project),
         nodes: structuredNodes,
         limit,
         truncated: structuredNodes.length < entries.filter(e => (e.note.relatedTo?.length ?? 0) > 0).length,
@@ -2920,6 +2933,7 @@ server.registerTool("project_memory_summary", {
         "Returns:\n" +
         "- A synthesized project-level summary based on stored memories\n" +
         "- Bounded 1-hop relationship previews on orientation entry points (primaryEntry and suggestedNext)\n\n" +
+        "- Optional compact working-state recovery hints when relevant temporary notes exist\n\n" +
         "Read-only.\n\n" +
         "Typical next step:\n" +
         "- Use `recall` or `list` to drill down into specific areas.",
@@ -3060,6 +3074,48 @@ server.registerTool("project_memory_summary", {
         .slice(0, recentLimit);
     sections.push(`\nRecent activity (start here):`);
     sections.push(...recent.map(e => `- ${e.note.updatedAt} — ${e.note.title}`));
+    const temporaryEntries = projectEntries
+        .filter((entry) => entry.note.lifecycle === "temporary")
+        .map((entry) => {
+        const metadata = effectiveMetadataById.get(entry.note.id)?.metadata;
+        const score = workingStateScore(entry.note, metadata);
+        const nextAction = extractNextAction(entry.note);
+        const relatedCount = entry.note.relatedTo?.length ?? 0;
+        const days = daysSinceUpdate(entry.note.updatedAt);
+        const rationaleParts = [`updated ${days < 1 ? "today" : `${Math.round(days)}d ago`}`];
+        if (relatedCount > 0)
+            rationaleParts.push(`${relatedCount} linked note${relatedCount === 1 ? "" : "s"}`);
+        if (nextAction)
+            rationaleParts.push("explicit next action");
+        if (metadata?.role === "plan" || metadata?.role === "context")
+            rationaleParts.push(`${metadata.role} note`);
+        return {
+            entry,
+            score,
+            rationale: rationaleParts.join(", "),
+            preview: summarizePreview(entry.note.content, 120),
+            nextAction,
+        };
+    })
+        .filter((candidate) => candidate.score > -Infinity)
+        .sort((a, b) => b.score - a.score || b.entry.note.updatedAt.localeCompare(a.entry.note.updatedAt))
+        .slice(0, 3);
+    const workingState = temporaryEntries.length > 0
+        ? {
+            summary: temporaryEntries.length === 1
+                ? `1 temporary note may help resume active work.`
+                : `${temporaryEntries.length} temporary notes may help resume active work.`,
+            recoveryHint: "Orient with project_memory_summary first, then inspect these temporary notes if you need to continue in-progress work.",
+            notes: temporaryEntries.map(({ entry, rationale, preview, nextAction }) => ({
+                id: entry.note.id,
+                title: entry.note.title,
+                updatedAt: entry.note.updatedAt,
+                rationale,
+                preview,
+                nextAction,
+            })),
+        }
+        : undefined;
     // Anchor notes with diversity constraint (project-scoped only)
     const scoredAnchorCandidates = projectEntries
         .map(e => {
@@ -3209,11 +3265,14 @@ server.registerTool("project_memory_summary", {
     }
     const suggestedEnriched = await Promise.all(suggestedCandidates.map(enrichOrientationNote));
     const suggestedRelationships = await Promise.all(suggestedCandidates.map(enrichOrientationNoteWithRelationships));
+    const recentPermanent = recent.find((entry) => entry.note.lifecycle === "permanent");
+    const fallbackEntry = recentPermanent ?? recent[0];
+    const permanentOverrideUsed = Boolean(recentPermanent && recent[0] && recentPermanent.note.id !== recent[0].note.id);
     // Enrich fallback primaryEntry when no anchors exist
     let fallbackEnriched = {};
     let fallbackRelationships = {};
-    if (!primaryAnchor && recent[0]) {
-        const fallbackNote = recent[0].note;
+    if (!primaryAnchor && fallbackEntry) {
+        const fallbackNote = fallbackEntry.note;
         const vault = noteVaultMap.get(fallbackNote.id);
         if (vault) {
             const filePath = `${vault.notesRelDir}/${fallbackNote.id}.md`;
@@ -3235,11 +3294,13 @@ server.registerTool("project_memory_summary", {
                 ...primaryRelationships,
             }
             : {
-                id: recent[0]?.note.id ?? projectEntries[0]?.note.id ?? "",
-                title: recent[0]?.note.title ?? projectEntries[0]?.note.title ?? "No notes",
-                rationale: recent[0]
-                    ? "Most recent note — no high-centrality anchors found"
-                    : "Only note available",
+                id: fallbackEntry?.note.id ?? projectEntries[0]?.note.id ?? "",
+                title: fallbackEntry?.note.title ?? projectEntries[0]?.note.title ?? "No notes",
+                rationale: permanentOverrideUsed
+                    ? "Most recent permanent note — no high-centrality anchors found"
+                    : fallbackEntry
+                        ? "Most recent note — no high-centrality anchors found"
+                        : "Only note available",
                 ...fallbackEnriched,
                 ...fallbackRelationships,
             },
@@ -3285,6 +3346,18 @@ server.registerTool("project_memory_summary", {
             sections.push(`  - ${w}`);
         }
     }
+    if (workingState) {
+        sections.push(`\nWorking state:`);
+        sections.push(workingState.summary);
+        sections.push(`Recovery hint: ${workingState.recoveryHint}`);
+        for (const note of workingState.notes) {
+            sections.push(`- ${note.title} (\`${note.id}\`) — ${note.rationale}`);
+            sections.push(`  Preview: ${note.preview}`);
+            if (note.nextAction) {
+                sections.push(`  Next action: ${note.nextAction}`);
+            }
+        }
+    }
     // Related global notes (optional, anchor-based similarity)
     const structuredContent = {
         action: "project_summary_shown",
@@ -3304,6 +3377,7 @@ server.registerTool("project_memory_summary", {
         })),
         anchors,
         orientation,
+        workingState,
         relatedGlobal,
     };
     console.error(`[summary:timing] ${(performance.now() - t0Summary).toFixed(1)}ms`);
@@ -4059,8 +4133,7 @@ async function detectDuplicates(entries, threshold, project) {
     const structuredContent = {
         action: "consolidated",
         strategy: "detect-duplicates",
-        project: project?.id,
-        projectName: project?.name,
+        project: toProjectRef(project),
         notesProcessed: entries.length,
         notesModified: 0,
     };
@@ -4147,8 +4220,7 @@ function findClusters(entries, project) {
     const structuredContent = {
         action: "consolidated",
         strategy: "find-clusters",
-        project: project?.id,
-        projectName: project?.name,
+        project: toProjectRef(project),
         notesProcessed: entries.length,
         notesModified: 0,
         themeGroups,
@@ -4235,8 +4307,7 @@ async function suggestMerges(entries, threshold, defaultConsolidationMode, proje
     const structuredContent = {
         action: "consolidated",
         strategy: "suggest-merges",
-        project: project?.id,
-        projectName: project?.name,
+        project: toProjectRef(project),
         notesProcessed: entries.length,
         notesModified: 0,
     };
@@ -4260,8 +4331,7 @@ async function executeMerge(entries, mergePlan, defaultConsolidationMode, projec
         const structuredContent = {
             action: "consolidated",
             strategy: "execute-merge",
-            project: project?.id,
-            projectName: project?.name,
+            project: toProjectRef(project),
             notesProcessed: entries.length,
             notesModified: 0,
             warnings: ["execute-merge requires at least two distinct sourceIds."],
@@ -4272,8 +4342,7 @@ async function executeMerge(entries, mergePlan, defaultConsolidationMode, projec
         const structuredContent = {
             action: "consolidated",
             strategy: "execute-merge",
-            project: project?.id,
-            projectName: project?.name,
+            project: toProjectRef(project),
             notesProcessed: entries.length,
             notesModified: 0,
             warnings: ["execute-merge requires a non-empty targetTitle."],
@@ -4288,8 +4357,7 @@ async function executeMerge(entries, mergePlan, defaultConsolidationMode, projec
             const structuredContent = {
                 action: "consolidated",
                 strategy: "execute-merge",
-                project: project?.id,
-                projectName: project?.name,
+                project: toProjectRef(project),
                 notesProcessed: entries.length,
                 notesModified: 0,
                 warnings: [`Source note '${id}' not found.`],
@@ -4324,8 +4392,7 @@ async function executeMerge(entries, mergePlan, defaultConsolidationMode, projec
             const structuredContent = {
                 action: "consolidated",
                 strategy: "execute-merge",
-                project: project?.id,
-                projectName: project?.name,
+                project: toProjectRef(project),
                 notesProcessed: entries.length,
                 notesModified: 0,
                 warnings: [message],
@@ -4537,8 +4604,7 @@ async function executeMerge(entries, mergePlan, defaultConsolidationMode, projec
     const structuredContent = {
         action: "consolidated",
         strategy: "execute-merge",
-        project: project?.id,
-        projectName: project?.name,
+        project: toProjectRef(project),
         notesProcessed: entries.length,
         notesModified: vaultChanges.size,
         persistence,
@@ -4578,8 +4644,7 @@ async function pruneSuperseded(entries, consolidationMode, project, cwd, policy,
         const structuredContent = {
             action: "consolidated",
             strategy: "prune-superseded",
-            project: project?.id,
-            projectName: project?.name,
+            project: toProjectRef(project),
             notesProcessed: entries.length,
             notesModified: 0,
             warnings: [`prune-superseded requires consolidationMode="delete". Current mode: ${consolidationMode}.`],
@@ -4611,8 +4676,7 @@ async function pruneSuperseded(entries, consolidationMode, project, cwd, policy,
         const structuredContent = {
             action: "consolidated",
             strategy: "prune-superseded",
-            project: project?.id,
-            projectName: project?.name,
+            project: toProjectRef(project),
             notesProcessed: entries.length,
             notesModified: 0,
         };
@@ -4641,8 +4705,7 @@ async function pruneSuperseded(entries, consolidationMode, project, cwd, policy,
             const structuredContent = {
                 action: "consolidated",
                 strategy: "prune-superseded",
-                project: project?.id,
-                projectName: project?.name,
+                project: toProjectRef(project),
                 notesProcessed: entries.length,
                 notesModified: 0,
                 warnings: [message],
@@ -4697,8 +4760,7 @@ async function pruneSuperseded(entries, consolidationMode, project, cwd, policy,
     const structuredContent = {
         action: "consolidated",
         strategy: "prune-superseded",
-        project: project?.id,
-        projectName: project?.name,
+        project: toProjectRef(project),
         notesProcessed: entries.length,
         notesModified: vaultChanges.size,
         retry,
@@ -4726,8 +4788,7 @@ async function dryRunAll(entries, threshold, defaultConsolidationMode, project,
     const structuredContent = {
         action: "consolidated",
         strategy: "dry-run",
-        project: project?.id,
-        projectName: project?.name,
+        project: toProjectRef(project),
         notesProcessed: entries.length,
         notesModified: 0,
     };
@@ -4773,11 +4834,32 @@ server.registerPrompt("mnemonic-workflow-hint", {
                     "- 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" +
+                    "### 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" +
+                    "- Title pattern: 'WIP: <topic>' or 'Checkpoint: <description>'\n" +
+                    "- Opening paragraph: current status and next immediate step\n" +
+                    "- Body: what was attempted, what worked, blockers, alternatives considered\n" +
+                    "- End with explicit next action and confidence level\n\n" +
+                    "**Checkpoint note guidance:**\n" +
+                    "- One checkpoint per active task or investigation thread\n" +
+                    "- Update the same checkpoint note as work progresses (don't create new ones)\n" +
+                    "- Link to related decisions: use `relate` to connect temporary checkpoints to permanent decisions\n" +
+                    "- Consolidate into a durable note when complete; let lifecycle defaults delete temporary scaffolding unless you intentionally need preserved history\n\n" +
+                    "**Recovery workflow:**\n" +
+                    "- Call `project_memory_summary` first for orientation (do not skip to recovery)\n" +
+                    "- Use `lifecycle: temporary` for active plans, WIP checkpoints, draft investigations, and unvalidated options\n" +
+                    "- Use `lifecycle: permanent` for decisions, discovered constraints, bug causes, and reusable lessons\n" +
+                    "- After orientation, recover working-state from temporary notes via `recall` with lifecycle filter\n" +
+                    "- Consolidate temporary notes into durable ones once knowledge stabilizes\n" +
+                    "- Recovery is a follow-on step, not a replacement for orientation\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" +
                     "- Bad: create another note when `recall` or `list` already found the same decision.\n" +
-                    "- Good: `update` the existing memory and relate it if needed.\n\n" +
+                    "- Good: `update` the existing memory and relate it if needed.\n" +
+                    "- Bad: skip orientation and jump straight to working-state recovery.\n" +
+                    "- Good: `project_memory_summary` first, then recover temporary notes.\n\n" +
                     "### Storage model\n\n" +
                     "Memories can live in:\n" +
                     "- `main-vault` for global knowledge\n" +
@@ -4790,7 +4872,8 @@ server.registerPrompt("mnemonic-workflow-hint", {
                     "### Tiny examples\n\n" +
                     "- Existing bug note found by `recall` -> inspect with `get` -> refine with `update`.\n" +
                     "- No matching note found by `recall` -> optional `discover_tags` with note context -> create with `remember`.\n" +
-                    "- Two notes overlap heavily -> inspect -> clean up with `consolidate`.",
+                    "- Two notes overlap heavily -> inspect -> clean up with `consolidate`.\n" +
+                    "- Resume work: `project_memory_summary` -> `recall` (lifecycle: temporary) -> continue from temporary notes.",
             },
         },
     ],