@danielmarbach/mnemonic-mcp 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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.15.0] - 2026-03-23
+
+### Added
+
+- Projection layer: compact, deterministic derived representations of notes used as embedding input instead of raw title+content. Projections extract title, lifecycle, tags, summary, and headings (h1–h3) into a structured format capped at 1200 characters, improving embedding quality by removing prose noise and markdown formatting.
+- `project_memory_summary` now uses projection summaries for related global note previews when available, falling back to content extraction. Previews are capped at 100 characters for consistent output.
+
+### Changed
+
+- All embedding operations (`remember`, `update`, `embedMissingNotes`, `consolidate`) now use `embedTextForNote()` which builds projections on demand and falls back to raw title+content if projection fails. Embeddings are never blocked by projection errors.
+- Projections are stored in `vaultPath/projections/` as JSON files alongside embeddings, gitignored and never synced. Each projection includes `noteId`, `title`, `summary`, `headings`, `tags`, `lifecycle`, `updatedAt` (staleness anchor), `projectionText` (what's embedded), and `generatedAt`.
+- Staleness detection is timestamp-based: a projection is stale when `projection.updatedAt !== note.updatedAt`. No hashing required.
+
 ## [0.14.0] - 2026-03-22
 
 ### Added

package/README.md

@@ -259,11 +259,13 @@ Two vault types store notes:
 
 ```
 ~/mnemonic-vault/
-  .gitignore             ← auto-created, gitignores embeddings/
+  .gitignore             ← auto-created, gitignores embeddings/ and projections/
   notes/
     setup-notes-a1b2c3.md
   embeddings/            ← local only, never committed
     setup-notes-a1b2c3.json
+  projections/           ← local only, never committed
+    setup-notes-a1b2c3.json
 ```
 
 **Project vault** — project-specific memories committed into the project repo:
@@ -271,11 +273,13 @@ Two vault types store notes:
 ```
 <git-root>/
   .mnemonic/
-    .gitignore           ← auto-created, gitignores embeddings/
+    .gitignore           ← auto-created, gitignores embeddings/ and projections/
     notes/
       auth-bug-fix-d4e5f6.md
     embeddings/          ← local only, never committed
       auth-bug-fix-d4e5f6.json
+    projections/        ← local only, never committed
+      auth-bug-fix-d4e5f6.json
 ```
 
 ### Routing
@@ -339,10 +343,21 @@ We fixed the JWT expiry issue by switching to RS256 and...
 
 Content is markdown-linted on `remember`/`update`: fixable issues are auto-corrected before save; non-fixable issues are rejected.
 
-### Embeddings and migrations
+### Embeddings and projections
 
 Embeddings are generated by Ollama's `/api/embed` with truncation enabled, stored as local JSON alongside notes, and gitignored. `sync` backfills missing embeddings on every run; `sync { force: true }` rebuilds all.
 
+**Projections** improve embedding quality by extracting structured representations instead of embedding raw markdown. Each note has a projection stored in `projections/<noteId>.json` (also gitignored) containing:
+
+- `projectionText`: compact embedding input (max 1200 chars) with title, lifecycle, tags, summary, and h1–h3 headings
+- `summary`: extracted from the first non-heading paragraph, first bullet list, or first 200 chars of body
+- `headings`: up to 8 deduplicated h1–h3 headings (plain text, in order)
+- `updatedAt`: staleness anchor matching the note's updatedAt timestamp
+
+Projections are built lazily on first embed and rebuilt when `note.updatedAt !== projection.updatedAt`. No global rebuild needed — staleness is timestamp-based. If projection generation fails, the system falls back to raw `title + content` so embeds never block.
+
+### Migrations
+
 Each vault has its own `config.json` with a `schemaVersion`, so main and project vaults migrate independently:
 
 - `list_migrations` reports schema version and pending migrations per vault.

package/build/index.js

@@ -8,6 +8,7 @@ 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 { getOrBuildProjection } from "./projections.js";
 import { filterRelationships, mergeRelationshipsFromNotes, normalizeMergePlanSourceIds, resolveEffectiveConsolidationMode, } from "./consolidate.js";
 import { selectRecallResults } from "./recall.js";
 import { cleanMarkdown } from "./markdown.js";
@@ -539,6 +540,20 @@ async function wouldRelationshipCleanupTouchProjectVault(noteIds) {
     }
     return false;
 }
+/**
+ * Get the text to use for embedding a note.
+ * Uses the projection's projectionText when available and fresh;
+ * falls back to the raw title+content if projection fails.
+ */
+async function embedTextForNote(storage, note) {
+    try {
+        const projection = await getOrBuildProjection(storage, note);
+        return projection.projectionText;
+    }
+    catch {
+        return `${note.title}\n\n${note.content}`;
+    }
+}
 async function embedMissingNotes(storage, noteIds, force = false) {
     const notes = noteIds
         ? (await Promise.all(noteIds.map((id) => storage.readNote(id)))).filter(Boolean)
@@ -560,7 +575,8 @@ async function embedMissingNotes(storage, noteIds, force = false) {
                 }
             }
             try {
-                const vector = await embed(`${note.title}\n\n${note.content}`);
+                const text = await embedTextForNote(storage, note);
+                const vector = await embed(text);
                 await storage.writeEmbedding({
                     id: note.id,
                     model: embedModel,
@@ -1359,7 +1375,8 @@ server.registerTool("remember", {
     await vault.storage.writeNote(note);
     let embeddingStatus = { status: "written" };
     try {
-        const vector = await embed(`${title}\n\n${cleanedContent}`);
+        const text = await embedTextForNote(vault.storage, note);
+        const vector = await embed(text);
         await vault.storage.writeEmbedding({ id, model: embedModel, embedding: vector, updatedAt: now });
     }
     catch (err) {
@@ -1838,7 +1855,8 @@ server.registerTool("update", {
     await vault.storage.writeNote(updated);
     let embeddingStatus = { status: "written" };
     try {
-        const vector = await embed(`${updated.title}\n\n${updated.content}`);
+        const text = await embedTextForNote(vault.storage, updated);
+        const vector = await embed(text);
         await vault.storage.writeEmbedding({ id, model: embedModel, embedding: vector, updatedAt: now });
     }
     catch (err) {
@@ -2671,11 +2689,15 @@ server.registerTool("project_memory_summary", {
                         maxSim = sim;
                 }
                 if (maxSim > 0.4) {
+                    const projection = await entry.vault.storage.readProjection(entry.note.id);
+                    const preview = projection?.summary
+                        ? projection.summary.slice(0, 100)
+                        : summarizePreview(entry.note.content, 100);
                     globalCandidates.push({
                         id: entry.note.id,
                         title: entry.note.title,
                         similarity: maxSim,
-                        preview: summarizePreview(entry.note.content, 100),
+                        preview,
                     });
                 }
             }
@@ -3855,7 +3877,8 @@ async function executeMerge(entries, mergePlan, defaultConsolidationMode, projec
     let embeddingStatus = { status: "written" };
     // Generate embedding for consolidated note
     try {
-        const vector = await embed(`${targetTitle}\n\n${consolidatedNote.content}`);
+        const text = await embedTextForNote(targetVault.storage, consolidatedNote);
+        const vector = await embed(text);
         await targetVault.storage.writeEmbedding({
             id: targetId,
             model: embedModel,