@pcircle/memesh 4.5.1 → 4.6.0

package/llms-install.md

@@ -0,0 +1,138 @@
+# Installing MeMesh — deterministic steps for an AI agent
+
+This document is for an AI agent installing MeMesh (`@pcircle/memesh`) on its
+user's machine. Execute each section exactly, verify with the stated check,
+then stop. Once installed, read [AGENTS.md](AGENTS.md) for how to use it.
+
+Facts that hold for every path below:
+
+- Every host reads and writes the **same database**: `~/.memesh/knowledge-graph.db`.
+  Installing for a second host adds an access path, not a second memory.
+- **Nothing is auto-configured beyond what each step states.** `npm install -g`
+  runs **no install scripts** — the package has none, by design (it installs
+  fully working even under `--ignore-scripts`). Nothing registers MCP servers
+  except the per-host commands in this document.
+- Where a host asks for a configured MCP command, use `memesh-mcp` —
+  **never `npx -p @pcircle/memesh`**. `npx -p` resolves to the *local* package
+  whenever the host's working directory is inside a checkout of this
+  repository, silently running that working tree instead of the installed
+  release.
+
+## 1. Claude Code (plugin)
+
+Type these in Claude Code's **chat input** — they are Claude Code slash
+commands, not shell commands:
+
+```
+/plugin marketplace add PCIRCLE-AI/memesh
+/plugin install memesh@pcircle-memesh
+```
+
+Claude Code wires the MCP server, the auto-capture hooks, and the `/memesh`
+skill automatically.
+
+**Verify**: restart Claude Code. A status line beginning `◉ MeMesh` appears at
+the top of the next session.
+
+| Failure | Remedy |
+|---|---|
+| `/plugin marketplace add` fails | The marketplace is fetched as a git clone. Check `git --version` succeeds and github.com is reachable. |
+| `/plugin install` says plugin not found | The argument is exactly `memesh@pcircle-memesh` — plugin name `memesh`, marketplace name `pcircle-memesh`. Re-run the marketplace add first. |
+| No `◉ MeMesh` line after restart | Run `/plugin` inside Claude Code and confirm the `memesh` plugin is installed and enabled, then restart again. |
+
+The plugin does **not** put a `memesh` command on the shell PATH. For terminal
+use — and as a prerequisite for sections 3 and 4 — also do section 2. The two
+installs coexist and share the database.
+
+## 2. Terminal / CLI (npm global)
+
+Check Node **first** — the floor is 22.13.0 (`node:sqlite` is part of Node
+itself; npm only warns on an engine mismatch, so an install onto an old Node
+"succeeds" and fails later at runtime):
+
+```
+node --version
+```
+
+Expected: `v22.13.0` or later. If lower, stop and upgrade Node before
+continuing.
+
+```
+npm install -g @pcircle/memesh
+```
+
+Expected: exits without error; `memesh`, `memesh-mcp` and `memesh-http` are
+now in `$(npm prefix -g)/bin/`. No compiler is involved and no install script
+runs.
+
+**Verify**:
+
+```
+memesh doctor
+```
+
+Expected: a report starting `MeMesh doctor v…` with `Overall: PASS`
+(`PASS_WITH_CONCERNS` is also functional), exit code 0.
+
+| Failure | Remedy |
+|---|---|
+| `command not found: memesh` | npm's global bin dir is not on PATH. Run `npm prefix -g`, append `/bin` to its output, and add that directory to PATH. |
+| `No such built-in module: node:sqlite` | The running Node is older than 22.13.0. Upgrade Node, then re-run `memesh doctor`. |
+| `EACCES` during `npm install -g` | The global prefix is not user-writable. Use a user-level Node (nvm/fnm), or `npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to PATH, then re-install. |
+| `Overall: FAIL` (exit code 1) | The report names the failing check and prints the fix next to it. Apply that fix and re-run `memesh doctor`. |
+
+Only if Claude Code is used **without** the section-1 plugin (the plugin wires
+hooks itself — skip this if section 1 is done):
+
+```
+memesh install-hooks
+memesh doctor
+```
+
+## 3. Codex CLI
+
+Prerequisite: section 2 — `memesh-mcp` must resolve on PATH.
+
+```
+codex mcp add memesh -- memesh-mcp
+```
+
+Writes `[mcp_servers.memesh]` into `~/.codex/config.toml`.
+
+**Verify**:
+
+```
+codex mcp list
+```
+
+Expected: `memesh` is listed as enabled.
+
+| Failure | Remedy |
+|---|---|
+| `command not found: codex` | Codex CLI itself is not installed — out of scope here; install it first, then re-run the add. |
+| `memesh` absent from the list | The add did not persist. Re-run `codex mcp add memesh -- memesh-mcp` and re-check. |
+| Listed, but tool calls fail | Run `command -v memesh-mcp`. Empty output means section 2 is incomplete or PATH is wrong — fix per section 2's table. |
+
+## 4. Gemini CLI
+
+Prerequisite: section 2 — `memesh-mcp` must resolve on PATH.
+
+```
+gemini mcp add -s user memesh memesh-mcp
+```
+
+`-s user` registers at user scope, so it works from every folder.
+
+**Verify**:
+
+```
+gemini mcp list
+```
+
+Expected: `memesh` shows **Connected**.
+
+| Failure | Remedy |
+|---|---|
+| `command not found: gemini` | Gemini CLI itself is not installed — out of scope here; install it first, then re-run the add. |
+| Shows Disconnected | Run `command -v memesh-mcp`. Empty output means section 2 is incomplete or PATH is wrong — fix per section 2's table, then re-run `gemini mcp list`. |
+| `memesh` absent from the list | The add was made in a different scope or did not persist. Re-run `gemini mcp add -s user memesh memesh-mcp`. |

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@pcircle/memesh",
-  "version": "4.5.1",
-  "description": "MeMesh — Local memory for Claude Code and MCP coding agents. One SQLite file, zero cloud required.",
+  "version": "4.6.0",
+  "description": "MeMesh — agentic memory for coding agents. Captured from the agent's real work via hooks, recalled when it acts. One SQLite file, zero cloud required.",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
     "memesh": "dist/transports/cli/cli.js",
     "memesh-mcp": "dist/mcp/server.js",
-    "memesh-http": "dist/transports/http/server.js",
-    "memesh-view": "dist/cli/view.js"
+    "memesh-http": "dist/transports/http/server.js"
   },
   "files": [
     "dist/",
@@ -20,7 +19,9 @@
     "skills/",
     ".claude-plugin/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "llms-install.md",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "node scripts/check-schema-drift.mjs && tsc && node scripts/generate-hook-core.mjs && node scripts/copy-cli-assets.mjs && node scripts/set-executable-bits.mjs && node scripts/generate-skills-manifest.mjs && npm run build:dashboard && node scripts/smoke-test.mjs",
@@ -41,9 +42,9 @@
   },
   "author": "PCIRCLE-AI",
   "license": "MIT",
-  "homepage": "https://pcircle.com/memesh-llm-memory",
+  "homepage": "https://github.com/PCIRCLE-AI/memesh",
   "bugs": {
-    "url": "https://github.com/PCIRCLE-AI/memesh-llm-memory/issues"
+    "url": "https://github.com/PCIRCLE-AI/memesh/issues"
   },
   "keywords": [
     "claude-code",
@@ -51,11 +52,15 @@
     "model-context-protocol",
     "memory",
     "sqlite",
-    "knowledge-graph"
+    "knowledge-graph",
+    "agentic-memory",
+    "agent-memory",
+    "ai-agents",
+    "coding-agents"
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/PCIRCLE-AI/memesh-llm-memory.git"
+    "url": "git+https://github.com/PCIRCLE-AI/memesh.git"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",

package/scripts/hooks/_generated/capture-flag.js

@@ -0,0 +1,17 @@
+// ============================================================================
+// AUTO-GENERATED from src/core/capture-flag.ts — DO NOT EDIT BY HAND.
+// Regenerate with: npm run build  (scripts/generate-hook-core.mjs)
+//
+// Claude Code hooks import this committed copy instead of dist/, so the
+// always-on capture path survives a missing or stale dist/ while staying
+// byte-locked to core — eliminating the hand-mirror drift behind the P0 FTS bug.
+// ============================================================================
+export function autoCaptureDecision(envVal, configAutoCapture) {
+    if (envVal === 'false')
+        return { enabled: false, offSource: 'env' };
+    if (envVal === 'true')
+        return { enabled: true, offSource: null };
+    if (configAutoCapture === false)
+        return { enabled: false, offSource: 'config' };
+    return { enabled: true, offSource: null };
+}

package/scripts/hooks/_generated/fts-index.js

@@ -62,9 +62,12 @@ const LONE_UNSPACED_CHAR = new RegExp(`[${UNSPACED_SCRIPT_CLASS}]`, 'u');
 export function isLoneUnspacedChar(term) {
     return [...term].length === 1 && LONE_UNSPACED_CHAR.test(term);
 }
-export function removeFromFts(db, entityId, name, prevObsText) {
+function foldTitleIntoObservations(title, observationsText) {
+    return title ? `${title} ${observationsText}` : observationsText;
+}
+export function removeFromFts(db, entityId, name, prevObsText, prevTitle) {
     try {
-        db.prepare("INSERT INTO entities_fts (entities_fts, rowid, name, observations) VALUES('delete', ?, ?, ?)").run(entityId, toIndexForm(name), toIndexForm(prevObsText));
+        db.prepare("INSERT INTO entities_fts (entities_fts, rowid, name, observations) VALUES('delete', ?, ?, ?)").run(entityId, toIndexForm(name), toIndexForm(foldTitleIntoObservations(prevTitle, prevObsText)));
     }
     catch (err) {
         if (isBenignFtsDeleteError(err))
@@ -76,6 +79,15 @@ function isBenignFtsDeleteError(err) {
     const msg = err?.message ?? '';
     return /no such rowid|values do not match|no such row\b/i.test(msg);
 }
-export function insertFtsRow(db, entityId, name, observationsText) {
-    db.prepare('INSERT INTO entities_fts (rowid, name, observations) VALUES (?, ?, ?)').run(entityId, toIndexForm(name), toIndexForm(observationsText));
+export function joinIndexedObservations(contents) {
+    return contents.join(' ');
+}
+export function indexedObservationText(db, entityId) {
+    const rows = db
+        .prepare('SELECT content FROM observations WHERE entity_id = ? ORDER BY id')
+        .all(entityId);
+    return joinIndexedObservations(rows.map((o) => o.content));
+}
+export function insertFtsRow(db, entityId, name, observationsText, title) {
+    db.prepare('INSERT INTO entities_fts (rowid, name, observations) VALUES (?, ?, ?)').run(entityId, toIndexForm(name), toIndexForm(foldTitleIntoObservations(title, observationsText)));
 }

package/scripts/hooks/_generated/schema.js

@@ -0,0 +1,281 @@
+// ============================================================================
+// AUTO-GENERATED from src/storage/schema.ts — DO NOT EDIT BY HAND.
+// Regenerate with: npm run build  (scripts/generate-hook-core.mjs)
+//
+// Claude Code hooks import this committed copy instead of dist/, so the
+// always-on capture path survives a missing or stale dist/ while staying
+// byte-locked to core — eliminating the hand-mirror drift behind the P0 FTS bug.
+// ============================================================================
+import { insertFtsRow } from './fts-index.js';
+import { parseSqliteUtcMs } from './time-utils.js';
+export const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS entities (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL UNIQUE,
+  type TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  metadata JSON
+);
+
+CREATE TABLE IF NOT EXISTS observations (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  entity_id INTEGER NOT NULL,
+  content TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (entity_id) REFERENCES entities(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS relations (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  from_entity_id INTEGER NOT NULL,
+  to_entity_id INTEGER NOT NULL,
+  relation_type TEXT NOT NULL,
+  metadata JSON,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (from_entity_id) REFERENCES entities(id) ON DELETE CASCADE,
+  FOREIGN KEY (to_entity_id) REFERENCES entities(id) ON DELETE CASCADE,
+  UNIQUE(from_entity_id, to_entity_id, relation_type)
+);
+
+CREATE TABLE IF NOT EXISTS tags (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  entity_id INTEGER NOT NULL,
+  tag TEXT NOT NULL,
+  FOREIGN KEY (entity_id) REFERENCES entities(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_tags_entity ON tags(entity_id);
+CREATE INDEX IF NOT EXISTS idx_tags_tag ON tags(tag);
+-- The tags dedup DELETE + idx_tags_entity_tag_unique creation live in
+-- ensureTagsUniqueIndex(), AFTER this exec — the DELETE is a one-time
+-- migration, and a DML statement in this string made every open start a
+-- write transaction even when it deleted nothing (same reader-breaking
+-- pattern as the hook_runs_since note below).
+CREATE INDEX IF NOT EXISTS idx_observations_entity ON observations(entity_id);
+CREATE INDEX IF NOT EXISTS idx_relations_from ON relations(from_entity_id);
+CREATE INDEX IF NOT EXISTS idx_relations_to ON relations(to_entity_id);
+CREATE INDEX IF NOT EXISTS idx_entities_type_created ON entities(type, created_at);
+
+-- Migration markers and small bits of persistent state (index segmentation
+-- version, embedding dimension, pending-reindex flags, backfill markers).
+--
+-- This used to be created ad hoc by each helper that needed it — four inline
+-- CREATE TABLE IF NOT EXISTS copies in src/db.ts, none of them visible to
+-- schema checks. A column added to one copy would not have been caught. It
+-- also meant the hook-side schema had no metadata table at all, so hooks
+-- could not participate in migrations even in principle.
+CREATE TABLE IF NOT EXISTS memesh_metadata (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+-- Proof that a capture hook actually RAN. Nothing else in this schema can
+-- give it: every other signal is "a row was written", and "the hook ran and
+-- found nothing worth saving" is the healthy case that produces no row at
+-- all. So a quiet day and a dead capture loop were byte-identical in the
+-- database, and the one doctor message that had to cover both cried wolf on
+-- the first and stayed silent on the second.
+--
+-- Written by the three hooks that hold a read-write handle (Stop, PreCompact,
+-- PostToolUse), each calling recordHookRun() at its own SUCCESSFUL exit —
+-- after capture, not at open. Stamping at open certified the wrong thing: a
+-- hook that opened the database and then died mid-capture looked alive for a
+-- day. "Successful" is precise: a completed capture, or a well-formed
+-- payload the hook correctly decided not to capture (dedup, low-signal
+-- session). A malformed payload (schema-flip shapes) and a write that did
+-- not land both leave no stamp — either would make the heartbeat mask the
+-- exact dropout it exists to expose. The recall-side hooks open read-only
+-- and deliberately do not appear here: their liveness answers a different
+-- question, and giving them a write handle would put a lock acquisition on
+-- the SessionStart hot path.
+--
+-- One row per hook, upserted. It does not grow.
+CREATE TABLE IF NOT EXISTS hook_runs (
+  hook        TEXT PRIMARY KEY,
+  last_run_at TIMESTAMP NOT NULL,
+  run_count   INTEGER NOT NULL DEFAULT 0
+);
+
+-- The 'hook_runs_since' metadata key (when this database first became able
+-- to record hook runs) is stamped by ensureHookRunsSince() AFTER this exec,
+-- NOT here. It used to be an INSERT OR IGNORE in this string, and that made
+-- every open — including opens that only ever read — start a write
+-- transaction: an INSERT statement takes the WAL writer lock even when
+-- OR IGNORE ends up changing nothing. Two states regressed from "reads work"
+-- to "open throws": a peer holding the writer lock past busy_timeout, and a
+-- read-only database FILE (measured: "attempt to write a readonly database"
+-- killed recall along with capture). The helper SELECTs first and writes
+-- only when the key is genuinely absent — once per database lifetime.
+`;
+export const FTS_SQL = `
+CREATE VIRTUAL TABLE IF NOT EXISTS entities_fts USING fts5(
+  name, observations, content='',
+  tokenize='unicode61 remove_diacritics 1'
+);
+
+-- Term -> document-count view over the index above. Stores nothing of its own;
+-- it exists so search() can drop query terms that appear in most of the corpus,
+-- which are the ones BM25 already scores near zero. See dropUbiquitousTerms().
+CREATE VIRTUAL TABLE IF NOT EXISTS fts_vocab USING fts5vocab(entities_fts, 'row');
+`;
+export function safeAlter(db, sql) {
+    try {
+        db.exec(sql);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (!/duplicate column name/i.test(msg))
+            throw e;
+    }
+}
+export function migrateEntitiesSchema(db) {
+    const entityColumns = new Set(db.prepare("PRAGMA table_info(entities)").all().map((c) => c.name));
+    if (!entityColumns.has('status')) {
+        safeAlter(db, "ALTER TABLE entities ADD COLUMN status TEXT NOT NULL DEFAULT 'active'");
+        db.exec("CREATE INDEX IF NOT EXISTS idx_entities_status ON entities(status)");
+    }
+    if (!entityColumns.has('access_count')) {
+        safeAlter(db, "ALTER TABLE entities ADD COLUMN access_count INTEGER DEFAULT 0");
+        safeAlter(db, "ALTER TABLE entities ADD COLUMN last_accessed_at TIMESTAMP");
+        safeAlter(db, "ALTER TABLE entities ADD COLUMN confidence REAL DEFAULT 1.0");
+        safeAlter(db, "ALTER TABLE entities ADD COLUMN valid_from TIMESTAMP");
+        safeAlter(db, "ALTER TABLE entities ADD COLUMN valid_until TIMESTAMP");
+    }
+    if (!entityColumns.has('namespace')) {
+        safeAlter(db, "ALTER TABLE entities ADD COLUMN namespace TEXT DEFAULT 'personal'");
+        db.exec("CREATE INDEX IF NOT EXISTS idx_entities_namespace ON entities(namespace)");
+    }
+    if (!entityColumns.has('recall_hits')) {
+        safeAlter(db, "ALTER TABLE entities ADD COLUMN recall_hits INTEGER DEFAULT 0");
+        safeAlter(db, "ALTER TABLE entities ADD COLUMN recall_misses INTEGER DEFAULT 0");
+    }
+    if (!entityColumns.has('title')) {
+        safeAlter(db, "ALTER TABLE entities ADD COLUMN title TEXT");
+    }
+}
+export function ensureTagsUniqueIndex(db) {
+    try {
+        const present = db
+            .prepare("SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = 'idx_tags_entity_tag_unique'")
+            .get();
+        if (present)
+            return;
+        db.exec('BEGIN IMMEDIATE; ' +
+            'DELETE FROM tags WHERE id NOT IN (SELECT MIN(id) FROM tags GROUP BY entity_id, tag); ' +
+            'CREATE UNIQUE INDEX IF NOT EXISTS idx_tags_entity_tag_unique ON tags(entity_id, tag); ' +
+            'COMMIT;');
+    }
+    catch (err) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch { }
+        try {
+            process.stderr.write(`MeMesh: could not create the tags unique index (${err instanceof Error ? err.message : String(err)}). ` +
+                `Reads are unaffected; the next open retries the dedup and index together.\n`);
+        }
+        catch { }
+    }
+}
+export function ensureHookRunsSince(db) {
+    try {
+        const row = db
+            .prepare("SELECT value FROM memesh_metadata WHERE key = 'hook_runs_since'")
+            .get();
+        if (row) {
+            const then = parseSqliteUtcMs(row.value ?? '');
+            if (then !== null && then <= Date.now() + 5 * 60 * 1000)
+                return;
+            db
+                .prepare("UPDATE memesh_metadata SET value = datetime('now') WHERE key = 'hook_runs_since'")
+                .run();
+            return;
+        }
+        db
+            .prepare("INSERT OR IGNORE INTO memesh_metadata (key, value) VALUES ('hook_runs_since', datetime('now'))")
+            .run();
+    }
+    catch (err) {
+        try {
+            process.stderr.write(`MeMesh: could not stamp hook_runs_since (${err instanceof Error ? err.message : String(err)}). ` +
+                `Reads are unaffected; doctor's hook-activity tracking starts once the database is writable.\n`);
+        }
+        catch { }
+    }
+}
+export function isTransientDbError(err) {
+    const code = err?.code ?? '';
+    const msg = err?.message ?? '';
+    return (/SQLITE_BUSY|SQLITE_LOCKED|SQLITE_PROTOCOL/.test(code) ||
+        /database is locked|database table is locked|locking protocol/i.test(msg));
+}
+export const MIGRATION_RETRY_BACKOFF_MS = 24 * 60 * 60 * 1000;
+export function runOnceMigration(db, opts) {
+    const { key, version, describe, migrate } = opts;
+    const attemptKey = `${key}_last_attempt`;
+    const readMarker = (k) => db.prepare('SELECT value FROM memesh_metadata WHERE key = ?').get(k)?.value;
+    const stored = readMarker(key);
+    if (stored && parseInt(stored, 10) >= version)
+        return false;
+    const lastAttempt = readMarker(attemptKey);
+    if (lastAttempt && Date.now() - parseInt(lastAttempt, 10) < MIGRATION_RETRY_BACKOFF_MS) {
+        return false;
+    }
+    try {
+        db.transaction(() => {
+            const current = readMarker(key);
+            if (current && parseInt(current, 10) >= version)
+                return;
+            migrate(db, current ? parseInt(current, 10) : 0);
+            db.prepare('INSERT OR REPLACE INTO memesh_metadata (key, value) VALUES (?, ?)').run(key, String(version));
+            db.prepare('DELETE FROM memesh_metadata WHERE key = ?').run(attemptKey);
+        }).immediate();
+        return true;
+    }
+    catch (err) {
+        if (isTransientDbError(err)) {
+            process.stderr.write(`MeMesh: ${describe} deferred (${err instanceof Error ? err.message : String(err)}). ` +
+                `Another process holds the database; it will run on the next start.\n`);
+            return false;
+        }
+        try {
+            db.prepare('INSERT OR REPLACE INTO memesh_metadata (key, value) VALUES (?, ?)').run(attemptKey, String(Date.now()));
+        }
+        catch { }
+        process.stderr.write(`MeMesh: ${describe} failed (${err instanceof Error ? err.message : String(err)}). ` +
+            `Your memories are unaffected — this rebuilds a derived index. ` +
+            `It will retry in 24h, or run 'memesh reindex --fts' to retry now.\n`);
+        return false;
+    }
+}
+export const FTS_SEGMENTATION_VERSION = 3;
+export const FTS_REBUILD_PAGE_SIZE = 500;
+export function rebuildFtsIndex(db) {
+    db.exec("INSERT INTO entities_fts (entities_fts) VALUES('delete-all')");
+    const page = db.prepare(`SELECT e.id, e.name, e.title, COALESCE(group_concat(o.content, ' ' ORDER BY o.id), '') AS obs
+       FROM entities e
+       LEFT JOIN observations o ON o.entity_id = e.id
+      WHERE e.status = 'active' AND e.id > ?
+      GROUP BY e.id
+      ORDER BY e.id
+      LIMIT ?`);
+    let afterId = 0;
+    for (;;) {
+        const rows = page.all(afterId, FTS_REBUILD_PAGE_SIZE);
+        if (rows.length === 0)
+            break;
+        for (const row of rows)
+            insertFtsRow(db, row.id, row.name, row.obs, row.title);
+        afterId = rows[rows.length - 1].id;
+        if (rows.length < FTS_REBUILD_PAGE_SIZE)
+            break;
+    }
+}
+export function ensureFtsSegmentation(db) {
+    runOnceMigration(db, {
+        key: 'fts_segmentation_version',
+        version: FTS_SEGMENTATION_VERSION,
+        describe: 'search index rebuild',
+        migrate: rebuildFtsIndex,
+    });
+}

package/scripts/hooks/_generated/task-state.js

@@ -0,0 +1,98 @@
+// ============================================================================
+// AUTO-GENERATED from src/core/task-state.ts — DO NOT EDIT BY HAND.
+// Regenerate with: npm run build  (scripts/generate-hook-core.mjs)
+//
+// Claude Code hooks import this committed copy instead of dist/, so the
+// always-on capture path survives a missing or stale dist/ while staying
+// byte-locked to core — eliminating the hand-mirror drift behind the P0 FTS bug.
+// ============================================================================
+export const TASK_STATE_TYPE = 'task-state';
+export const TASK_STATE_FIELDS = ['goal', 'next', 'blocked', 'done'];
+export const MAX_FIELD_CHARS = 300;
+export function taskStateName(project) {
+    return `${TASK_STATE_TYPE}:${project}`;
+}
+export function parseTaskState(metadata) {
+    const state = {};
+    if (!metadata || typeof metadata !== 'object')
+        return state;
+    const raw = metadata.task_state;
+    if (!raw || typeof raw !== 'object')
+        return state;
+    const bag = raw;
+    for (const field of TASK_STATE_FIELDS) {
+        const value = bag[field];
+        if (typeof value !== 'string')
+            continue;
+        const trimmed = value.trim();
+        if (trimmed)
+            state[field] = trimmed;
+    }
+    const updated = bag.updated_at;
+    if (typeof updated === 'string' && updated.trim())
+        state.updated_at = updated.trim();
+    return state;
+}
+export function normalizeFieldValue(value) {
+    const flat = value.replace(/\s+/g, ' ').trim();
+    if (!flat)
+        return null;
+    return flat.length > MAX_FIELD_CHARS ? `${flat.slice(0, MAX_FIELD_CHARS - 1).trimEnd()}…` : flat;
+}
+export function mergeTaskState(previous, patch, now) {
+    const state = { ...previous };
+    const changed = [];
+    const observations = [];
+    for (const field of TASK_STATE_FIELDS) {
+        const incoming = patch[field];
+        if (incoming === undefined)
+            continue;
+        const normalized = normalizeFieldValue(incoming);
+        const current = state[field];
+        if (normalized === (current ?? null))
+            continue;
+        changed.push(field);
+        if (normalized === null) {
+            delete state[field];
+            observations.push(`${field} cleared`);
+        }
+        else {
+            state[field] = normalized;
+            observations.push(`${field}: ${normalized}`);
+        }
+    }
+    if (changed.length > 0)
+        state.updated_at = now;
+    return { state, changed, observations };
+}
+export function isEmptyTaskState(state) {
+    return TASK_STATE_FIELDS.every((field) => !state[field]);
+}
+const FIELD_LABELS = {
+    goal: 'Goal',
+    next: 'Next',
+    blocked: 'Blocked',
+    done: 'Just finished',
+};
+function ageInDays(updatedAt, now) {
+    if (!updatedAt)
+        return null;
+    const then = Date.parse(updatedAt);
+    if (Number.isNaN(then))
+        return null;
+    const days = Math.floor((now.getTime() - then) / 86_400_000);
+    return days >= 0 ? days : null;
+}
+export function taskStateLines(state, project, now = new Date()) {
+    if (isEmptyTaskState(state))
+        return [];
+    const days = ageInDays(state.updated_at, now);
+    const age = days === null ? '' : days === 0 ? ' (today)' : days === 1 ? ' (yesterday)' : ` (${days} days ago)`;
+    const lines = [`Where "${project}" was left off${age}:`];
+    for (const field of TASK_STATE_FIELDS) {
+        const value = state[field];
+        if (value)
+            lines.push(`- ${FIELD_LABELS[field]}: ${value}`);
+    }
+    return lines;
+}

package/scripts/hooks/_generated/time-utils.js

@@ -0,0 +1,21 @@
+// ============================================================================
+// AUTO-GENERATED from src/core/time-utils.ts — DO NOT EDIT BY HAND.
+// Regenerate with: npm run build  (scripts/generate-hook-core.mjs)
+//
+// Claude Code hooks import this committed copy instead of dist/, so the
+// always-on capture path survives a missing or stale dist/ while staying
+// byte-locked to core — eliminating the hand-mirror drift behind the P0 FTS bug.
+// ============================================================================
+export function parseSqliteUtcMs(sqliteTimestamp) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})$/.exec(sqliteTimestamp ?? '');
+    if (!m)
+        return null;
+    const then = Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6]);
+    if (!Number.isFinite(then))
+        return null;
+    const d = new Date(then);
+    if (d.getUTCFullYear() !== +m[1] || d.getUTCMonth() !== +m[2] - 1 || d.getUTCDate() !== +m[3]
+        || d.getUTCHours() !== +m[4] || d.getUTCMinutes() !== +m[5] || d.getUTCSeconds() !== +m[6])
+        return null;
+    return then;
+}

package/scripts/hooks/_generated/title.js

@@ -0,0 +1,21 @@
+// ============================================================================
+// AUTO-GENERATED from src/core/title.ts — DO NOT EDIT BY HAND.
+// Regenerate with: npm run build  (scripts/generate-hook-core.mjs)
+//
+// Claude Code hooks import this committed copy instead of dist/, so the
+// always-on capture path survives a missing or stale dist/ while staying
+// byte-locked to core — eliminating the hand-mirror drift behind the P0 FTS bug.
+// ============================================================================
+export const TITLE_MAX_LENGTH = 200;
+export function truncateTitle(text) {
+    if (!text)
+        return text;
+    const trimmed = text.trim();
+    return trimmed.length > TITLE_MAX_LENGTH
+        ? trimmed.slice(0, TITLE_MAX_LENGTH - 1).trimEnd() + '…'
+        : trimmed;
+}
+export const BOILERPLATE_OBSERVATION_PATTERN = /^(Steps|Commits|Branch|Diff stats|Compaction reason|Tool calls|Plan ".+" completed)[:\s]/;
+export function isBoilerplateObservation(text) {
+    return BOILERPLATE_OBSERVATION_PATTERN.test(text.trim());
+}