@danielmarbach/mnemonic-mcp 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -4,7 +4,14 @@ 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.16.0] - Unreleased
+## [0.17.0] - 2026-03-25
+
+### Added
+
+- Active session project cache (`src/cache.ts`): notes and embeddings are cached in memory after the first access within an MCP session, so repeated calls to `recall`, `get`, and `project_memory_summary` skip redundant storage reads.
+- The cache is invalidated automatically on every write-path tool (`remember`, `update`, `forget`, `relate`, `unrelate`, `move_memory`, `consolidate`, `sync`) and on branch switch.
+
+## [0.16.0] - 2026-03-24
 
 ### Added
 

package/README.md

@@ -23,6 +23,7 @@ mnemonic is at the inception stage. The storage format (frontmatter schema, vaul
 
 - Hundreds to low thousands of notes: excellent fit.
 - Several thousand: often fine, depending on note size, machine speed, and embedding throughput.
+- Within a session, notes and embeddings are cached after first access — repeated `recall`, `get`, and `project_memory_summary` calls skip storage reads regardless of vault size.
 - Very large collections: expect pain points around reindex time, recall latency, and git churn.
 - Many concurrent writers or massive scale: consider a dedicated database and indexing layer instead.
 

package/build/cache.d.ts

@@ -0,0 +1,66 @@
+import type { Note, EmbeddingRecord } from "./storage.js";
+import type { NoteProjection } from "./structured-content.js";
+import type { Vault } from "./vault.js";
+interface VaultCache {
+    notesById: Map<string, Note>;
+    noteList: Note[];
+    embeddings: EmbeddingRecord[];
+}
+export interface SessionProjectCache {
+    projectId: string;
+    /** Per-vault caches keyed by vaultPath. Built lazily per vault on first access. */
+    vaultCaches: Map<string, VaultCache>;
+    /** Projection cache shared across all cached vaults for this project. */
+    projectionsById: Map<string, NoteProjection>;
+    /** ISO timestamp of when this cache entry was first created. */
+    lastBuiltAt: string;
+}
+/**
+ * Discard the entire active project cache.
+ *
+ * Call this after any mutation that modifies notes, embeddings, or relationships
+ * so the next read rebuilds from storage. Safe to call when no cache exists (no-op).
+ */
+export declare function invalidateActiveProjectCache(): void;
+/**
+ * Return the active project cache for the given projectId without triggering a build.
+ * Returns undefined when no cache exists or the cached project is different.
+ */
+export declare function getActiveProjectCache(projectId: string): SessionProjectCache | undefined;
+/**
+ * Get the full note list for a vault from the session cache, building it lazily if needed.
+ *
+ * When the vault cache is first built, notes AND embeddings are loaded together so
+ * both are available for subsequent calls at no extra I/O cost.
+ *
+ * Fail-soft: returns `undefined` on error. Callers must fall back to direct storage access.
+ */
+export declare function getOrBuildVaultNoteList(projectId: string, vault: Vault): Promise<Note[] | undefined>;
+/**
+ * Get the embeddings list for a vault from the session cache, building it lazily if needed.
+ *
+ * When the vault cache is first built, notes AND embeddings are loaded together so
+ * both are available for subsequent calls at no extra I/O cost.
+ *
+ * Fail-soft: returns `undefined` on error. Callers must fall back to direct storage access.
+ */
+export declare function getOrBuildVaultEmbeddings(projectId: string, vault: Vault): Promise<EmbeddingRecord[] | undefined>;
+/**
+ * Look up a single note from an already-built vault cache.
+ * Returns `undefined` when the vault cache has not been built yet or the note is not found.
+ * Does NOT trigger a cache build — callers should use `getOrBuildVaultNoteList` or
+ * `getOrBuildVaultEmbeddings` to ensure the vault cache is warm first.
+ */
+export declare function getSessionCachedNote(projectId: string, vaultPath: string, noteId: string): Note | undefined;
+/**
+ * Retrieve a cached projection for a note.
+ * Returns `undefined` when no cache or projection exists.
+ */
+export declare function getSessionCachedProjection(projectId: string, noteId: string): NoteProjection | undefined;
+/**
+ * Store a projection in the session cache.
+ * No-op when no active cache exists for this project.
+ */
+export declare function setSessionCachedProjection(projectId: string, noteId: string, projection: NoteProjection): void;
+export {};
+//# sourceMappingURL=cache.d.ts.map

package/build/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAIxC,UAAU,UAAU;IAClB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC7B,QAAQ,EAAE,IAAI,EAAE,CAAC;IACjB,UAAU,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,yEAAyE;IACzE,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC7C,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;CACrB;AAqCD;;;;;GAKG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CAKnD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAIxF;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,IAAI,EAAE,GAAG,SAAS,CAAC,CA6B7B;AAED;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,eAAe,EAAE,GAAG,SAAS,CAAC,CA6BxC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,IAAI,GAAG,SAAS,CAIlB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,cAAc,GAAG,SAAS,CAI5B;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,cAAc,GACzB,IAAI,CAIN"}

package/build/cache.js

@@ -0,0 +1,149 @@
+import { performance } from "perf_hooks";
+// ── Module-level singleton ─────────────────────────────────────────────────────
+const sessionCaches = {};
+// ── Internal helpers ───────────────────────────────────────────────────────────
+function debugLog(event, message) {
+    console.error(`[${event}] ${message}`);
+}
+function ensureActiveProjectCache(projectId) {
+    const current = sessionCaches.activeProject;
+    if (current?.projectId === projectId) {
+        return current;
+    }
+    // Different project (or first use): create fresh cache
+    if (current) {
+        debugLog("cache:invalidate", `switching project from=${current.projectId} to=${projectId}`);
+    }
+    const fresh = {
+        projectId,
+        vaultCaches: new Map(),
+        projectionsById: new Map(),
+        lastBuiltAt: new Date().toISOString(),
+    };
+    sessionCaches.activeProject = fresh;
+    return fresh;
+}
+// ── Public API ─────────────────────────────────────────────────────────────────
+/**
+ * Discard the entire active project cache.
+ *
+ * Call this after any mutation that modifies notes, embeddings, or relationships
+ * so the next read rebuilds from storage. Safe to call when no cache exists (no-op).
+ */
+export function invalidateActiveProjectCache() {
+    if (sessionCaches.activeProject) {
+        debugLog("cache:invalidate", `project=${sessionCaches.activeProject.projectId}`);
+        sessionCaches.activeProject = undefined;
+    }
+}
+/**
+ * Return the active project cache for the given projectId without triggering a build.
+ * Returns undefined when no cache exists or the cached project is different.
+ */
+export function getActiveProjectCache(projectId) {
+    const cache = sessionCaches.activeProject;
+    if (cache?.projectId === projectId)
+        return cache;
+    return undefined;
+}
+/**
+ * Get the full note list for a vault from the session cache, building it lazily if needed.
+ *
+ * When the vault cache is first built, notes AND embeddings are loaded together so
+ * both are available for subsequent calls at no extra I/O cost.
+ *
+ * Fail-soft: returns `undefined` on error. Callers must fall back to direct storage access.
+ */
+export async function getOrBuildVaultNoteList(projectId, vault) {
+    const vaultPath = vault.storage.vaultPath;
+    const cache = ensureActiveProjectCache(projectId);
+    const existing = cache.vaultCaches.get(vaultPath);
+    if (existing) {
+        debugLog("cache:hit", `project=${projectId} vault=${vaultPath} notes=${existing.noteList.length}`);
+        return existing.noteList;
+    }
+    debugLog("cache:miss", `project=${projectId} vault=${vaultPath}`);
+    try {
+        const t0 = performance.now();
+        const [noteList, embeddings] = await Promise.all([
+            vault.storage.listNotes(),
+            vault.storage.listEmbeddings(),
+        ]);
+        const notesById = new Map(noteList.map((n) => [n.id, n]));
+        cache.vaultCaches.set(vaultPath, { notesById, noteList, embeddings });
+        const ms = (performance.now() - t0).toFixed(1);
+        debugLog("cache:build", `project=${projectId} vault=${vaultPath} notes=${noteList.length} embeddings=${embeddings.length} time=${ms}ms`);
+        return noteList;
+    }
+    catch (err) {
+        debugLog("cache:fallback", `project=${projectId} vault=${vaultPath} error=${String(err)}`);
+        return undefined;
+    }
+}
+/**
+ * Get the embeddings list for a vault from the session cache, building it lazily if needed.
+ *
+ * When the vault cache is first built, notes AND embeddings are loaded together so
+ * both are available for subsequent calls at no extra I/O cost.
+ *
+ * Fail-soft: returns `undefined` on error. Callers must fall back to direct storage access.
+ */
+export async function getOrBuildVaultEmbeddings(projectId, vault) {
+    const vaultPath = vault.storage.vaultPath;
+    const cache = ensureActiveProjectCache(projectId);
+    const existing = cache.vaultCaches.get(vaultPath);
+    if (existing) {
+        debugLog("cache:hit", `project=${projectId} vault=${vaultPath} embeddings=${existing.embeddings.length}`);
+        return existing.embeddings;
+    }
+    debugLog("cache:miss", `project=${projectId} vault=${vaultPath}`);
+    try {
+        const t0 = performance.now();
+        const [noteList, embeddings] = await Promise.all([
+            vault.storage.listNotes(),
+            vault.storage.listEmbeddings(),
+        ]);
+        const notesById = new Map(noteList.map((n) => [n.id, n]));
+        cache.vaultCaches.set(vaultPath, { notesById, noteList, embeddings });
+        const ms = (performance.now() - t0).toFixed(1);
+        debugLog("cache:build", `project=${projectId} vault=${vaultPath} notes=${noteList.length} embeddings=${embeddings.length} time=${ms}ms`);
+        return embeddings;
+    }
+    catch (err) {
+        debugLog("cache:fallback", `project=${projectId} vault=${vaultPath} error=${String(err)}`);
+        return undefined;
+    }
+}
+/**
+ * Look up a single note from an already-built vault cache.
+ * Returns `undefined` when the vault cache has not been built yet or the note is not found.
+ * Does NOT trigger a cache build — callers should use `getOrBuildVaultNoteList` or
+ * `getOrBuildVaultEmbeddings` to ensure the vault cache is warm first.
+ */
+export function getSessionCachedNote(projectId, vaultPath, noteId) {
+    const cache = sessionCaches.activeProject;
+    if (!cache || cache.projectId !== projectId)
+        return undefined;
+    return cache.vaultCaches.get(vaultPath)?.notesById.get(noteId);
+}
+/**
+ * Retrieve a cached projection for a note.
+ * Returns `undefined` when no cache or projection exists.
+ */
+export function getSessionCachedProjection(projectId, noteId) {
+    const cache = sessionCaches.activeProject;
+    if (!cache || cache.projectId !== projectId)
+        return undefined;
+    return cache.projectionsById.get(noteId);
+}
+/**
+ * Store a projection in the session cache.
+ * No-op when no active cache exists for this project.
+ */
+export function setSessionCachedProjection(projectId, noteId, projection) {
+    const cache = sessionCaches.activeProject;
+    if (!cache || cache.projectId !== projectId)
+        return;
+    cache.projectionsById.set(noteId, projection);
+}
+//# sourceMappingURL=cache.js.map

package/build/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/build/index.js

@@ -9,6 +9,8 @@ import { NOTE_LIFECYCLES } from "./storage.js";
 import { embed, cosineSimilarity, embedModel } from "./embeddings.js";
 import { buildTemporalHistoryEntry, computeConfidence, getNoteProvenance } from "./provenance.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 { getRelationshipPreview } from "./relationships.js";
@@ -360,6 +362,8 @@ async function ensureBranchSynced(cwd) {
     }
     const mainBackfill = await backfillEmbeddingsAfterSync(vaultManager.main.storage, "main vault", [], true);
     console.error(`[branch] Main vault embedded ${mainBackfill.embedded} notes`);
+    // Vault contents changed — discard session cache so next access rebuilds from fresh state
+    invalidateActiveProjectCache();
     return true;
 }
 function formatProjectIdentityText(identity) {
@@ -782,7 +786,7 @@ function vaultMatchesStorageScope(vault, storedIn) {
     // "project-vault" covers the primary project vault and all submodule vaults.
     return vault.isProject;
 }
-async function collectVisibleNotes(cwd, scope = "all", tags, storedIn = "any") {
+async function collectVisibleNotes(cwd, scope = "all", tags, storedIn = "any", sessionProjectId) {
     const project = await resolveProject(cwd);
     const vaults = await vaultManager.searchOrder(cwd);
     let filterProject = undefined;
@@ -793,8 +797,23 @@ async function collectVisibleNotes(cwd, scope = "all", tags, storedIn = "any") {
     const seen = new Set();
     const entries = [];
     for (const vault of vaults) {
-        const vaultNotes = await vault.storage.listNotes(filterProject !== undefined ? { project: filterProject } : undefined);
-        for (const note of vaultNotes) {
+        let rawNotes;
+        if (sessionProjectId) {
+            const cached = await getOrBuildVaultNoteList(sessionProjectId, vault);
+            if (cached !== undefined) {
+                // Apply project filter on the full cached list
+                rawNotes = filterProject !== undefined
+                    ? cached.filter((n) => filterProject === null ? !n.project : n.project === filterProject)
+                    : cached;
+            }
+            else {
+                rawNotes = await vault.storage.listNotes(filterProject !== undefined ? { project: filterProject } : undefined);
+            }
+        }
+        else {
+            rawNotes = await vault.storage.listNotes(filterProject !== undefined ? { project: filterProject } : undefined);
+        }
+        for (const note of rawNotes) {
             if (seen.has(note.id)) {
                 continue;
             }
@@ -1442,6 +1461,7 @@ server.registerTool("remember", {
         timestamp: now,
         persistence,
     };
+    invalidateActiveProjectCache();
     return {
         content: [{ type: "text", text: textContent }],
         structuredContent,
@@ -1674,6 +1694,7 @@ server.registerTool("recall", {
     }),
     outputSchema: RecallResultSchema,
 }, async ({ query, cwd, limit, minSimilarity, mode, verbose, tags, scope }) => {
+    const t0Recall = performance.now();
     await ensureBranchSynced(cwd);
     const project = await resolveProject(cwd);
     const queryVec = await embed(query);
@@ -1681,6 +1702,12 @@ server.registerTool("recall", {
     const noteCache = new Map();
     const noteCacheKey = (vault, id) => `${vault.storage.vaultPath}::${id}`;
     const readCachedNote = async (vault, id) => {
+        // Check session cache first (populated when getOrBuildVaultEmbeddings was called)
+        if (project) {
+            const sessionNote = getSessionCachedNote(project.id, vault.storage.vaultPath, id);
+            if (sessionNote !== undefined)
+                return sessionNote;
+        }
         const key = noteCacheKey(vault, id);
         const cached = noteCache.get(key);
         if (cached) {
@@ -1697,7 +1724,9 @@ server.registerTool("recall", {
     }
     const scored = [];
     for (const vault of vaults) {
-        const embeddings = await vault.storage.listEmbeddings();
+        const embeddings = project
+            ? (await getOrBuildVaultEmbeddings(project.id, vault)) ?? await vault.storage.listEmbeddings()
+            : await vault.storage.listEmbeddings();
         for (const rec of embeddings) {
             const rawScore = cosineSimilarity(queryVec, rec.embedding);
             if (rawScore < minSimilarity)
@@ -1792,6 +1821,7 @@ server.registerTool("recall", {
         scope: scope || "all",
         results: structuredResults,
     };
+    console.error(`[recall:timing] ${(performance.now() - t0Recall).toFixed(1)}ms`);
     return {
         content: [{ type: "text", text: textContent }],
         structuredContent,
@@ -1942,6 +1972,7 @@ server.registerTool("update", {
         lifecycle: updated.lifecycle,
         persistence,
     };
+    invalidateActiveProjectCache();
     return { content: [{ type: "text", text: `Updated memory '${id}'\n${formatPersistenceSummary(persistence)}` }], structuredContent };
 });
 // ── forget ────────────────────────────────────────────────────────────────────
@@ -2048,6 +2079,7 @@ server.registerTool("forget", {
         retry,
     };
     const retrySummary = formatRetrySummary(retry);
+    invalidateActiveProjectCache();
     return {
         content: [{
                 type: "text",
@@ -2085,12 +2117,26 @@ server.registerTool("get", {
     }),
     outputSchema: GetResultSchema,
 }, async ({ ids, cwd, includeRelationships }) => {
+    const t0Get = performance.now();
     await ensureBranchSynced(cwd);
     const project = await resolveProject(cwd);
     const found = [];
     const notFound = [];
     for (const id of ids) {
-        const result = await vaultManager.findNote(id, cwd);
+        // Check session cache before hitting storage
+        let result = null;
+        if (project) {
+            for (const vault of vaultManager.allKnownVaults()) {
+                const cached = getSessionCachedNote(project.id, vault.storage.vaultPath, id);
+                if (cached !== undefined) {
+                    result = { note: cached, vault };
+                    break;
+                }
+            }
+        }
+        if (!result) {
+            result = await vaultManager.findNote(id, cwd);
+        }
         if (!result) {
             notFound.push(id);
             continue;
@@ -2138,6 +2184,7 @@ server.registerTool("get", {
         notes: found,
         notFound,
     };
+    console.error(`[get:timing] ${(performance.now() - t0Get).toFixed(1)}ms`);
     return { content: [{ type: "text", text: lines.join("\n").trim() }], structuredContent };
 });
 // ── where_is_memory ───────────────────────────────────────────────────────────
@@ -2690,8 +2737,11 @@ server.registerTool("project_memory_summary", {
     }),
     outputSchema: ProjectSummaryResultSchema,
 }, async ({ cwd, maxPerTheme, recentLimit, anchorLimit, includeRelatedGlobal, relatedGlobalLimit }) => {
+    const t0Summary = performance.now();
     await ensureBranchSynced(cwd);
-    const { project, entries } = await collectVisibleNotes(cwd, "all");
+    // Pre-resolve project so we can pass its id to collectVisibleNotes for session caching
+    const preProject = await resolveProject(cwd);
+    const { project, entries } = await collectVisibleNotes(cwd, "all", undefined, "any", preProject?.id);
     if (!project) {
         return { content: [{ type: "text", text: `Could not detect a project for: ${cwd}` }], isError: true };
     }
@@ -3007,6 +3057,7 @@ server.registerTool("project_memory_summary", {
         orientation,
         relatedGlobal,
     };
+    console.error(`[summary:timing] ${(performance.now() - t0Summary).toFixed(1)}ms`);
     return { content: [{ type: "text", text: sections.join("\n") }], structuredContent };
 });
 // ── sync ──────────────────────────────────────────────────────────────────────
@@ -3093,6 +3144,8 @@ server.registerTool("sync", {
         action: "synced",
         vaults: vaultResults,
     };
+    // Vault contents may have changed via pull — discard session cache
+    invalidateActiveProjectCache();
     return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
 });
 // ── move_memory ───────────────────────────────────────────────────────────────
@@ -3244,6 +3297,7 @@ server.registerTool("move_memory", {
     const associationText = metadataRewritten
         ? `Project association is now ${associationValue}.`
         : `Project association remains ${associationValue}.`;
+    invalidateActiveProjectCache();
     return {
         content: [{
                 type: "text",
@@ -3416,6 +3470,7 @@ server.registerTool("relate", {
         retry,
     };
     const retrySummary = formatRetrySummary(retry);
+    invalidateActiveProjectCache();
     return {
         content: [{
                 type: "text",
@@ -3582,6 +3637,7 @@ server.registerTool("unrelate", {
         retry,
     };
     const retrySummary = formatRetrySummary(retry);
+    invalidateActiveProjectCache();
     return {
         content: [{
                 type: "text",
@@ -3680,13 +3736,19 @@ server.registerTool("consolidate", {
             return findClusters(projectNotes, project);
         case "suggest-merges":
             return suggestMerges(projectNotes, threshold, defaultConsolidationMode, project, mode);
-        case "execute-merge":
+        case "execute-merge": {
             if (!mergePlan) {
                 return { content: [{ type: "text", text: "execute-merge strategy requires a mergePlan with sourceIds and targetTitle." }], isError: true };
             }
-            return executeMerge(entries, mergePlan, defaultConsolidationMode, project, cwd, mode, policy, allowProtectedBranch);
-        case "prune-superseded":
-            return pruneSuperseded(projectNotes, mode ?? defaultConsolidationMode, project, cwd, policy, allowProtectedBranch);
+            const mergeResult = await executeMerge(entries, mergePlan, defaultConsolidationMode, project, cwd, mode, policy, allowProtectedBranch);
+            invalidateActiveProjectCache();
+            return mergeResult;
+        }
+        case "prune-superseded": {
+            const pruneResult = await pruneSuperseded(projectNotes, mode ?? defaultConsolidationMode, project, cwd, policy, allowProtectedBranch);
+            invalidateActiveProjectCache();
+            return pruneResult;
+        }
         case "dry-run":
             return dryRunAll(projectNotes, threshold, defaultConsolidationMode, project, mode);
         default: