@danielmarbach/mnemonic-mcp 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@ 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
+
+### Added
+
+- Bounded 1-hop relationship expansion layer (`src/relationships.ts`): `recall`, `project_memory_summary`, and `get` now surface direct related notes as compact previews, scored by same-project priority, anchor status, recency, and confidence.
+- `recall` automatically attaches relationship previews to top results (top 1 by default, top 3 when result count is small). Previews appear in both text and structured output.
+- `project_memory_summary` orientation entries (`primaryEntry` and `suggestedNext`) include bounded relationship previews, including the fallback primaryEntry when no anchor notes exist.
+- `get` accepts an optional `includeRelationships` parameter; when true, each returned note includes a bounded 1-hop relationship preview in both text and structured output.
+
+### Changed
+
+- `RecallResult.results` entries now include an optional `relationships` field (`RelationshipPreview`).
+- `GetResult.notes` entries now include an optional `relationships` field (`RelationshipPreview`).
+- `OrientationNote` now includes an optional `relationships` field (`RelationshipPreview`).
+- `discover_tags` now defaults to note-oriented tag suggestions using title/content/query context, returning bounded `recommendedTags`; broader inventory output is now explicit via `mode: "browse"`.
+
+## [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.
@@ -414,10 +429,10 @@ Imported notes are written to the main vault with `lifecycle: permanent` and `sc
 |-----------------------------|--------------------------------------------------------------------------|
 | `consolidate`               | Merge multiple notes into one with relationship to sources               |
 | `detect_project`            | Resolve `cwd` to stable project id via git remote URL                   |
-| `discover_tags`            | List existing tags with usage counts and examples for consistent terminology |
+| `discover_tags`            | Suggest canonical tags for a note using title/content/query context; `mode: "browse"` opts into broader inventory output |
 | `execute_migration`         | Execute a named migration (supports dry-run)                             |
 | `forget`                    | Delete note + embedding, git commit + push, cleanup relationships        |
-| `get`                       | Fetch one or more notes by exact id                                      |
+| `get`                       | Fetch one or more notes by exact id; `includeRelationships: true` adds bounded 1-hop previews |
 | `get_project_identity`      | Show effective project identity and remote override                      |
 | `get_project_memory_policy` | Show saved write scope, consolidation mode, and protected-branch settings |
 | `list`                      | List notes filtered by scope/tags/storage                                |