@theglitchking/semantic-memory 1.1.1 → 1.2.1

package/.claude-plugin/marketplace.json

@@ -6,18 +6,18 @@
   },
   "metadata": {
     "description": "Single-plugin marketplace for semantic-memory — the unified memory-layer plugin. v1.1.0 absorbs brain's strengths: AGENTS.md contract artifact, hard-gated verification sessions, multi-agent skill bundler (codex/copilot/pi), and SessionStart drift detection — all backwards-compatible with v1.0.x via deprecation shims.",
-    "version": "1.1.1"
+    "version": "1.2.1"
   },
   "plugins": [
     {
       "name": "semantic-memory",
       "description": "Unified memory-layer plugin for Claude Code. One MCP server, 40 tools across multi-corpus search/read/write/graph/lint/sessions/contract. v1.1.0 adds: AGENTS.md contract artifact, hard-gated verification sessions (session_start/run/finish/status), proposal-mode synthesize_note + synthesize_promote, multi-agent skill bundler (codex/copilot/pi via the new `skills` CLI), and SessionStart drift detection. Backwards-compatible with v1.0.x — every previous tool name remains callable through deprecation shims (removed in v2.0.0).",
-      "version": "1.1.1",
+      "version": "1.2.1",
       "author": {
         "name": "TheGlitchKing"
       },
-      "homepage": "https://github.com/TheGlitchKing/semantic-sidekick",
-      "repository": "https://github.com/TheGlitchKing/semantic-sidekick.git",
+      "homepage": "https://github.com/TheGlitchKing/semantic-memory",
+      "repository": "https://github.com/TheGlitchKing/semantic-memory.git",
       "license": "MIT",
       "keywords": [
         "mcp",

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 All notable changes to semantic-memory (formerly semantic-sidekick) will be documented here.
 
+## [1.2.1] - 2026-06-11 — Capture-cue false-positive fixes
+
+Fixes two classes of false positives in the Stop-hook capture nudge (`hooks/vault-context.js`), where the cue scanner over-fired and asked to synthesize moments that carried no new knowledge.
+
+### Fixed
+
+- **Conversational "gotcha" no longer fires the cue.** The `gotcha` cue was a bare-word match (`\bgotcha\b`), so filler acknowledgments like "Gotcha, ok…" tripped it. It now requires noun-context (`a/the gotcha`, `gotcha:`, `gotchas`, `gotcha is/was/here/with`). `workaround`/`hack` are unchanged.
+- **Quoted machinery no longer re-primes the cue.** Cue detection ran over the entire raw prompt, so pasting tool output back — especially this hook's own `<vault-capture-prompt>` block, which contains the words "gotcha"/"workaround"/"hack" and the cue regexes themselves — re-primed `capture-pending` in a self-referential loop. New `stripQuotedMachinery()` removes self-emitted `<vault-*>` blocks, fenced code, and inline-code spans before matching, so only the user's own prose is scanned.
+
+### Tests
+
+- Extended `test/phase4/mode-hook.test.ts` with four regression cases: conversational "gotcha" does not prime; noun-context "the gotcha is…" does; pasting a `<vault-capture-prompt>` block does not re-prime; and a real cue alongside fenced machinery still primes (the strip is surgical, not total).
+
+## [1.2.0] - 2026-05-09 — State consolidation under .claude/.semantic-memory/
+
+Consolidates every transient state file under one namespace. Renames the legacy `.sidekick-*` files to drop the obsolete prefix. All legacy paths remain readable through v1.x via fallback; v2.0 will remove the fallback.
+
+### Changed (state file paths)
+
+The three v1.1-era state files in `hooks/vault-context.js` move:
+
+| Old path | New path |
+|---|---|
+| `.claude/.sidekick-mode` | `.claude/.semantic-memory/mode` |
+| `.claude/.sidekick-fingerprints.json` | `.claude/.semantic-memory/fingerprints.json` |
+| `.claude/.sidekick-capture-pending.json` | `.claude/.semantic-memory/capture-pending.json` |
+
+Reads check the new path first; if absent, fall back to the old path. Writes always go to the new path. The `bin/semantic-memory migrate-state` command does the explicit move for users who want the legacy files cleaned up immediately.
+
+`session.json` and `healthcheck-cache.json` were already correctly placed under `.claude/.semantic-memory/` since v1.1 — no change.
+
+### Added
+
+- **`bin/semantic-memory migrate-state`** — one-shot CLI command that atomically moves the three legacy state files. Idempotent. `--dry-run` previews; `--force` resolves conflicts (when both old and new exist) by preferring the new path and deleting the old.
+- **`legacy_state_files` healthcheck finding** — fast-tier check that detects legacy `.sidekick-*` files and surfaces a `warn` with a pointer to `migrate-state`. Pure read-only detection; never auto-migrates.
+
+### Backwards compatibility
+
+Three statements that remain true after v1.2.0 ships:
+
+1. **All legacy paths continue to be readable through v1.x.** Users who never run `migrate-state` see no behavioral change.
+2. **No state files are silently moved or deleted.** Migration is opt-in via `bin/semantic-memory migrate-state`; healthcheck only warns.
+3. **v2.0 will remove the legacy-path read fallback** — committed in this CHANGELOG entry. Users have all of v1.x to migrate. Storage paths (`.semantic-sidekick-index/`, `~/.semantic-sidekick/models/`) are NOT affected by this change; those are preserved through v1.x per the v1.0 promise.
+
+### Tests
+
+- New: `test/unit/migrate-state.test.ts` (idempotency, dry-run, conflict refusal, force resolution)
+- Extended: `test/unit/healthcheck.test.ts` (legacy state file detection)
+- Updated: `test/phase4/mode-hook.test.ts` (verifies writes land at new path)
+
+## [1.1.2] - 2026-05-09 — Add ROADMAP.md (docs-only)
+
+Adds a public-facing `ROADMAP.md` at the repo root tracking the committed near-term direction. Captures v1.2 (state consolidation, `/healthcheck --fix`, fresh-install CI smoke, code-symbol drift), v1.3 (confidence-decay), and v2.0 (close the migration window — remove deprecation shims, move the vector index out of the vault, drop legacy fallbacks). Also documents what's deferred and what we've actively decided NOT to ship.
+
+`ROADMAP.md` is now in the published npm tarball alongside `README.md` and `CHANGELOG.md`. No code changes; pure documentation.
+
+The detailed per-version task plans live under `.planning/v1*-*` (gitignored runtime state); ROADMAP.md is the durable summary.
+
 ## [1.1.1] - 2026-05-08 — Hotfix: complete the rebrand wiring
 
 v1.1.0 published with the rebrand-to-`semantic-memory` half-finished: the npm package, marketplace entry, and tool surface all moved to the new name, but the postinstall, SessionStart reconcile, slash commands, and CLI helpers were still hardcoded to the legacy `@theglitchking/semantic-sidekick` package path. Fresh `npm install @theglitchking/semantic-memory@1.1.0` installs failed to register hooks correctly and slash commands hit ancient code from the legacy npm package (still on the registry at 0.2.x).

package/ROADMAP.md

@@ -0,0 +1,218 @@
+# semantic-memory Roadmap
+
+This file tracks the committed near-term direction for `@theglitchking/semantic-memory`. It's a planning surface — not a contract. Items move between sections as the work clarifies; the canonical state lives here in git.
+
+> **Current shipped version:** [v1.1.1](https://github.com/TheGlitchKing/semantic-sidekick/releases/tag/v1.1.1) (npm `latest`)
+> **Last updated:** 2026-05-09
+
+## Legend
+
+- 🎯 **Committed** — planned for the named version, plan file exists under `.planning/`
+- ✅ **Shipped** — already released
+- 🤔 **Considering** — likely but not yet planned in detail
+- 🌙 **Deferred** — ideas with merit but not on the near-term roadmap
+- 🚫 **Won't ship** — actively decided against
+
+## v1.2 — hygiene release (next)
+
+Small-scope cleanup work that closes loose ends from v1.1 before the bigger v1.3 retrieval work lands. Targeted as a single bundled release.
+
+### 🎯 State consolidation under `.claude/.semantic-memory/`
+- Move `.claude/.sidekick-mode` → `.claude/.semantic-memory/mode`
+- Move `.claude/.sidekick-fingerprints.json` → `.claude/.semantic-memory/fingerprints.json`
+- Move `.claude/.sidekick-capture-pending.json` → `.claude/.semantic-memory/capture-pending.json`
+- Drop the legacy `.sidekick-*` prefix; rename to drop the redundant leading dot
+- New CLI: `bin/semantic-memory migrate-state` (idempotent, opt-in)
+- Read-with-fallback: legacy paths still work through all of v1.x
+- Healthcheck surfaces a `legacy_state_files` warning when old paths are present
+- **Plan:** `.planning/v12-state-consolidation/task_plan.md`
+- **Effort:** ~3 days
+
+### 🎯 `/healthcheck --fix` flag
+- Auto-apply safe fixes for drift findings: re-link skills, reconcile `.mcp.json`, regenerate AGENTS.md, run `migrate-state`
+- Refuses non-safe fixes (stale notes, broken wikilinks, hand-edited managed blocks → human review)
+- Documented in `commands/healthcheck.md` since v1.1; implementation deferred
+- **Effort:** ~1 week
+
+### 🎯 Fresh-install CI smoke test
+- Pre-publish CI job: `npm pack` → install tarball into clean tmpdir → verify hooks register, `.mcp.json` populates, `bin --version` works
+- Mechanically prevents the v1.1.0-class packaging bug
+- This is the highest-ROI v1.2 item — would have caught v1.1.0 → v1.1.1 hotfix before publish
+- **Effort:** ~1 day
+
+### 🎯 Code-symbol drift detection (conditional on babel-fish)
+- New `lint_vault({checks: ["code_symbols"]})` rule
+- Cross-references vault note inline code mentions against project-map's symbol index
+- Flags notes whose referenced symbols no longer exist
+- Fails open when babel-fish is not installed
+- **Effort:** ~3 days
+
+**v1.2 total estimate:** ~2 weeks active work + ≥1 week dogfood before v1.3 starts.
+
+## v1.3 — confidence-decay (after v1.2 ships clean)
+
+Replaces age-blind retrieval ranking with smooth, type-aware, composable confidence decay. Notes age out of relevance gracefully; explicitly-verified notes reset the clock.
+
+### 🎯 Smooth exponential decay engine
+- `multiplier = 0.5^(age_days / half_life)`
+- Per-type half-life: `decision: 365d`, `note: 365d`, `gotcha: 180d`, `source: ∞`, `proposal: 14d`
+- Configurable via `vault.schema.yml`
+- Floor at 0.1 (notes never disappear, just down-weight)
+
+### 🎯 `last_verified` semantically split from `last_modified`
+- `last_modified`: auto-stamped on every edit
+- `last_verified`: only updated by note creation OR explicit `verify_note` tool
+- Idempotent migration helper: `bin/semantic-memory migrate-schema`
+
+### 🎯 New tool: `verify_note(path)`
+- Updates `last_verified` only — no content change
+- Logs a `kind: verify` event to `log.md`
+- Resets the decay clock for one note
+
+### 🎯 Surface decay in search output
+- `search_semantic` and `search_hybrid` results gain an optional `decay: { multiplier, age_days, effective_half_life, reason }` block
+- Block omitted on healthy (multiplier 1.0) results
+- Agents see staleness and can proactively offer to re-verify
+
+### 🎯 `evergreen` frontmatter opt-out
+- `evergreen: true` → decay multiplier locked at 1.0
+- BUT requires `last_verified` within 365 days — evergreen claim itself expires periodically
+
+### 🎯 Backlink hotness boost (feature-flagged off by default)
+- Notes with high inbound link count get extended effective half-life
+- Capped at 2× extension
+- Earn it via Phase 10 telemetry rather than ship it on by default
+
+### 🎯 `decay_candidates` lint rule
+- `lint_vault({checks: ["decay_candidates"]})` surfaces stale-but-frequently-relevant notes
+- Wires into `/healthcheck` slow tier
+
+### 🎯 CLI introspection
+- `bin/semantic-memory decay-config` — print active decay parameters
+- `bin/semantic-memory decay-trace <path>` — debug one note's decay calculation
+
+### 🎯 Selection logging (local JSONL telemetry)
+- `.claude/.semantic-memory/decay-telemetry.log` (gitignored)
+- Tracks query → results → which result agent actually used
+- Local only, opt-out via `decay.telemetry.enabled: false`
+- Two weeks of passive collection informs the next round of half-life tuning
+
+**Plan:** `.planning/v13-confidence-decay/task_plan.md`
+**v1.3 total estimate:** ~2.5 weeks active + ≥2 weeks dogfood (longer than v1.1 — ranking changes need more soak).
+
+## v2.0 — close the migration window
+
+The release where every legacy fallback collected during v1.x finally goes away. Coordinates the deprecation-shim removal with the rest of the layout cleanup so users do their migration once.
+
+### 🎯 Remove deprecation shims (committed in v1.1 CHANGELOG)
+- `find_schema_violations` → `lint_vault({checks: ["schema"]})`
+- `find_missing_provenance` → `lint_vault({checks: ["provenance"]})`
+- `find_stale` → `lint_vault({checks: ["stale"]})`
+- `find_broken_links` → `lint_vault({checks: ["broken_links"]})`
+- `read_multiple_notes` → `read_note` in a loop or batched MCP calls
+- `rename_tag` → `manage_tags({action: "rename", from, to})`
+
+### 🎯 Move the vector index out of the vault
+- `<vault>/.semantic-sidekick-index/` → `.claude/.semantic-memory/index/`
+- Atomic move-with-verify migration on first run after upgrade
+- Cleaner separation: derived state stops living inside user content
+- Honors the v1.0 storage promise's spirit (no re-index, no model re-download) by transparent move
+
+### 🎯 Move the global model cache
+- `~/.semantic-sidekick/models/` → `~/.semantic-memory/models/`
+- One-shot rename (or atomic move) on first v2.0 run
+- Higher cost than the index move (cross-device, multiple repos may share); document carefully
+
+### 🎯 Remove legacy-state read fallback
+- v1.2 introduced "read new path first, fall back to old"
+- v2.0 drops the fallback — old paths are no longer respected
+- `bin/semantic-memory migrate-state` becomes a hard prerequisite (run during upgrade or lose state)
+
+### 🎯 Remove `bin/semantic-sidekick` alias
+- The legacy CLI name kept since the v1.0.0 rebrand goes away
+- Anyone still scripting against `semantic-sidekick` updates to `semantic-memory`
+
+### 🎯 Remove legacy `@theglitchking/semantic-sidekick` package fallback paths
+- All four fallback sites in `reconcile.js`, `link-skills.js`, `vault-context.js`, `src/cli/index.ts` collapse to single new-path lookups
+- The legacy npm package (still on the registry at 0.2.x) gets a final deprecation `README` pointer to the new package
+
+### 🎯 Rename `reindex` and `regenerate_index`
+- `reindex` → `rebuild_search_index`
+- `regenerate_index` → `regenerate_index_notes`
+- The confusable pair finally becomes unambiguous
+
+### 🤔 Tighten default decay constants
+- Based on telemetry from v1.3 dogfood, ship more aggressive defaults
+- Conservative-then-tighten was the right v1.3 strategy; v2.0 is when we use the data
+
+**v2.0 total estimate:** ~2 weeks active + ≥2 weeks dogfood. The bulk is migration helpers + writing migration documentation, not new features.
+
+## v1.3+ — multi-corpus completion (separate effort)
+
+The README at v1.0.0 promised "multi-corpus architecture: vault, code, plans, docs, research, project-map." Today only the **vault** corpus is fully wired. The other 5 corpora exist as conceptual placeholders, not as separate indices, separate tool registrations, or separate retrieval tuning.
+
+This is **multi-quarter work**, not one release. Suggested first step: pick ONE additional corpus (probably `code`) and wire it end-to-end. Decide whether multi-corpus is the future or whether to consolidate back to vault-only based on what that integration teaches.
+
+🤔 **Considering for a v1.4 or v1.5:**
+- Code corpus wiring (separate index, separate tools, separate retrieval)
+- Cross-corpus graph queries (the unified knowledge graph actually unifies)
+- Per-corpus retrieval tuning (chunking strategy varies by content type)
+
+Don't pre-build adapters for the other 4 corpora; let real demand surface them.
+
+## 🤔 Considering (no committed slot yet)
+
+Stuff with merit but no version commitment.
+
+- **Confidence-multiplier composition** — `confidence: low|medium|high` already in the schema; v1.3 wires it as a multiplicative boost, but per-vault tuning could be useful
+- **Per-agent skill format transforms** — codex/copilot/pi may need format adapters once we see real usage
+- **Stale-session auto-cleanup** — sessions open >7 days with no activity could auto-close with `verified: false, reason: "auto-stale"`. Decide based on dogfood feedback.
+- **Mode-state in JSON instead of plain text** — only if we ever need metadata (last_changed, prior_mode). Today's plain text is fine.
+
+## 🌙 Deferred wishlist (would be cool, no plan)
+
+These are real ideas, not committed work. Order roughly by expected value-per-effort:
+
+### Authoring & retrieval
+- Auto-suggest `derived_from` candidates when synthesizing
+- Duplicate-content detection (cluster chunk vectors, surface 0.92+ similar pairs)
+- `bin/semantic-memory ingest <url>` — fetch + readability + write as `source` note
+
+### Visualization
+- Read-only local web UI (`bin/semantic-memory ui`)
+- Provenance heatmap — which notes are most-cited
+- Drift trend chart over time
+
+### Cross-tool integration
+- GitHub Action: `lint_vault` as a CI step
+- VS Code extension for `read_note` / `synthesize_note` / `search_hybrid`
+
+### Session evolution
+- Session diff at finish — auto-emit a structured what-changed report
+- Named/concurrent sessions (probably not worth it; the constraint is also a feature)
+
+### Wild
+- Adversarial vault auditor — generate "trick questions," flag where vault is silently wrong
+- Vault-against-PR drift (requires multi-corpus first)
+- LLM-summarized SessionStart context (vs. raw top-N hits)
+
+## 🚫 Won't ship
+
+Decided against. Documented to prevent rediscovery.
+
+- **Skills marketplace** — scope creep, not the project's concern
+- **Custom embedding model fine-tuning per project** — costly, niche, fragile
+- **Hosted analytics / centralized telemetry** — breaks the local-first promise
+- **Premium tier of any kind** — same
+- **Account requirement** — same
+- **Hosted MCP-as-a-service mode** — would change the project's character
+
+These all break the "local-first, no surveillance, no central server" promise that's quietly the most attractive thing about both this project and `JimmyMcBride/brain`. We resist scope creep that erodes that.
+
+## How this file is maintained
+
+- **Source of truth:** the .planning/ artifacts under `.planning/v1*-*` are the detailed task plans. This file summarizes them.
+- **Update cadence:** at every release, move shipped items from "committed" to "shipped" with a link to the release tag. Add new committed items as plans graduate from "considering."
+- **`/.planning/` is gitignored** — those are runtime planning artifacts. This ROADMAP.md is the durable, public-facing summary.
+- **Don't promise dates.** Effort estimates only. Dates are a forecasting trap.
+- **Honest scope:** if something turns out to be larger than estimated, move it to a later version rather than scope-creep the current one.

package/dist/{chunk-XBAN7GRT.js → chunk-CYWPDFNI.js}

@@ -880,7 +880,7 @@ function buildManagedBlock(opts) {
   lines.push("- Markdown is canonical. The vault under `.claude/.vault/` (or wherever `--notes` points) is the source of truth.");
   lines.push("- Indexes (vector / graph / FTS) are derived state \u2014 rebuildable via `reindex` without losing knowledge.");
   lines.push("- Provenance frontmatter is required for `note`/`decision`/`gotcha` types \u2014 `sources` (external) or `derived_from` (internal).");
-  lines.push("- Mode router lives at `.claude/.sidekick-mode`; explicit `/mode` is ground truth.");
+  lines.push("- Mode router lives at `.claude/.semantic-memory/mode` (legacy `.claude/.sidekick-mode` still readable through v1.x); explicit `/mode` is ground truth.");
   lines.push("");
   lines.push(END_MARKER);
   return lines.join("\n");
@@ -1133,4 +1133,4 @@ export {
   deriveProjectRoot,
   deriveSessionDir
 };
-//# sourceMappingURL=chunk-XBAN7GRT.js.map
+//# sourceMappingURL=chunk-CYWPDFNI.js.map