@rohirik/openltm-core 2.14.0 → 2.14.2

package/migrations/001_baseline.sql

@@ -0,0 +1,11 @@
+-- Migration 001: baseline — initial schema captured in schema.sql
+-- All core tables (memories, context_items, tags, memory_tags, memory_relations,
+-- memories_fts, settings) are created by schema.sql on fresh installs.
+-- This file records the baseline in the migration log so subsequent migrations
+-- can assume the schema.sql shape exists.
+
+-- UP
+-- (no DDL — schema.sql CREATE IF NOT EXISTS handles fresh installs)
+
+-- DOWN
+-- (no rollback — dropping core tables would destroy all data)

package/migrations/002_phase2_columns.sql

@@ -0,0 +1,30 @@
+-- Migration 002: Phase 2 columns — status, embedding, last_used_at, memory_id
+-- These columns were previously added by hand-rolled ALTER TABLE in shared-db.ts.
+-- Moving them here makes the migration history authoritative.
+
+-- UP
+ALTER TABLE memories ADD COLUMN status TEXT NOT NULL DEFAULT 'active' CHECK(status IN ('active','pending','deprecated','superseded'));
+ALTER TABLE memories ADD COLUMN embedding BLOB;
+ALTER TABLE memories ADD COLUMN last_used_at TEXT NOT NULL DEFAULT (datetime('now'));
+
+ALTER TABLE context_items ADD COLUMN memory_id INTEGER REFERENCES memories(id) ON DELETE SET NULL;
+ALTER TABLE context_items ADD COLUMN status TEXT NOT NULL DEFAULT 'active' CHECK(status IN ('active','pending_promotion','promoted'));
+
+CREATE TABLE IF NOT EXISTS settings (
+  key        TEXT PRIMARY KEY,
+  value      TEXT NOT NULL,
+  updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_memories_status    ON memories(status);
+CREATE INDEX IF NOT EXISTS idx_memories_last_used ON memories(last_used_at);
+
+-- DOWN
+-- DROP INDEX IF EXISTS idx_memories_last_used;
+-- DROP INDEX IF EXISTS idx_memories_status;
+-- DROP TABLE IF EXISTS settings;
+-- ALTER TABLE context_items DROP COLUMN status;
+-- ALTER TABLE context_items DROP COLUMN memory_id;
+-- ALTER TABLE memories DROP COLUMN last_used_at;
+-- ALTER TABLE memories DROP COLUMN embedding;
+-- ALTER TABLE memories DROP COLUMN status;

package/migrations/003_embedding_index.sql

@@ -0,0 +1,6 @@
+-- Migration 003: index for embedding presence check
+-- UP
+CREATE INDEX IF NOT EXISTS idx_memories_embedding ON memories(id) WHERE embedding IS NOT NULL;
+
+-- DOWN
+-- DROP INDEX IF EXISTS idx_memories_embedding;

package/migrations/004_graph_reasoning.sql

@@ -0,0 +1,18 @@
+-- Migration 004: Graph reasoning convenience view
+-- Creates a view of conflicting memory pairs for quick inspection.
+-- No new tables needed — all data already lives in memory_relations.
+
+CREATE VIEW IF NOT EXISTS memory_conflict_pairs AS
+  SELECT
+    r.source_memory_id,
+    r.target_memory_id,
+    r.relationship_type,
+    r.created_at,
+    a.content AS source_content,
+    b.content AS target_content,
+    a.category AS source_category,
+    b.category AS target_category
+  FROM memory_relations r
+  JOIN memories a ON a.id = r.source_memory_id
+  JOIN memories b ON b.id = r.target_memory_id
+  WHERE r.relationship_type IN ('contradicts', 'supersedes');

package/migrations/005_clusters.sql

@@ -0,0 +1,16 @@
+CREATE TABLE IF NOT EXISTS memory_clusters (
+  id TEXT PRIMARY KEY,
+  label TEXT NOT NULL,
+  color TEXT NOT NULL,
+  node_ids TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS cluster_overrides (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  cluster_id TEXT NOT NULL,
+  action TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);

package/migrations/006_temporal_metadata.sql

@@ -0,0 +1,19 @@
+-- Migration 006: temporal metadata for memories
+-- UP
+ALTER TABLE memories ADD COLUMN first_recalled_at TEXT;
+ALTER TABLE memories ADD COLUMN last_recalled_at TEXT;
+ALTER TABLE memories ADD COLUMN recall_count INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memories ADD COLUMN superseded_by INTEGER REFERENCES memories(id) ON DELETE SET NULL;
+ALTER TABLE memories ADD COLUMN superseded_at TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_memories_superseded ON memories(superseded_by);
+CREATE INDEX IF NOT EXISTS idx_memories_recall_count ON memories(recall_count DESC);
+
+-- DOWN
+-- DROP INDEX IF EXISTS idx_memories_superseded;
+-- DROP INDEX IF EXISTS idx_memories_recall_count;
+-- ALTER TABLE memories DROP COLUMN superseded_at;
+-- ALTER TABLE memories DROP COLUMN superseded_by;
+-- ALTER TABLE memories DROP COLUMN recall_count;
+-- ALTER TABLE memories DROP COLUMN last_recalled_at;
+-- ALTER TABLE memories DROP COLUMN first_recalled_at;

package/migrations/007_workspaces.sql

@@ -0,0 +1,18 @@
+-- Migration 007: workspace_id + agent_id for multi-agent memory isolation
+-- UP
+ALTER TABLE memories ADD COLUMN workspace_id TEXT;
+ALTER TABLE memories ADD COLUMN agent_id TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_memories_workspace ON memories(workspace_id);
+CREATE INDEX IF NOT EXISTS idx_memories_agent ON memories(agent_id);
+
+ALTER TABLE context_items ADD COLUMN workspace_id TEXT;
+ALTER TABLE context_items ADD COLUMN agent_id TEXT;
+
+-- DOWN
+-- ALTER TABLE context_items DROP COLUMN agent_id;
+-- ALTER TABLE context_items DROP COLUMN workspace_id;
+-- DROP INDEX IF EXISTS idx_memories_agent;
+-- DROP INDEX IF EXISTS idx_memories_workspace;
+-- ALTER TABLE memories DROP COLUMN agent_id;
+-- ALTER TABLE memories DROP COLUMN workspace_id;

package/migrations/008_add_memory_provenance.sql

@@ -0,0 +1,28 @@
+-- Migration 008: memory_provenance table — per-memory source traceability (C5, W9)
+-- One-to-many: a memory may have multiple provenance entries.
+-- memory_id FK cascades on delete so provenance rows clean up with the memory.
+-- Backfill: all pre-existing memories get a single 'legacy' provenance row.
+-- UP
+CREATE TABLE IF NOT EXISTS memory_provenance (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  memory_id   INTEGER NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  source_type TEXT    NOT NULL CHECK(source_type IN (
+                'learn','git-backfill','evaluate-session','import-bundle',
+                'user-promotion','janitor-rollup','legacy')),
+  source_ref  TEXT,
+  actor       TEXT,
+  created_at  TEXT    NOT NULL DEFAULT (datetime('now')),
+  metadata    TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_provenance_memory      ON memory_provenance(memory_id);
+CREATE INDEX IF NOT EXISTS idx_provenance_source_type ON memory_provenance(source_type, created_at DESC);
+
+-- Backfill all existing memories with a 'legacy' sentinel row.
+INSERT INTO memory_provenance (memory_id, source_type, actor)
+  SELECT id, 'legacy', 'migration-008' FROM memories;
+
+-- DOWN
+-- DROP INDEX IF EXISTS idx_provenance_source_type;
+-- DROP INDEX IF EXISTS idx_provenance_memory;
+-- DROP TABLE IF EXISTS memory_provenance;

package/migrations/009_add_memory_audit.sql

@@ -0,0 +1,26 @@
+-- Migration 009: memory_audit table — append-only write audit log (W11, C5, C9)
+-- memory_id is intentionally NOT a foreign key: audit rows must survive memory deletion.
+-- No backfill — audit is forward-only from this migration onward.
+-- Powers Phase 7 time-travel (C9) and /openltm:admin audit queries.
+-- UP
+CREATE TABLE IF NOT EXISTS memory_audit (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  memory_id   INTEGER NOT NULL,
+  op          TEXT    NOT NULL CHECK(op IN (
+                'insert','update','forget','deprecate','supersede','redact','restore')),
+  actor       TEXT    NOT NULL,
+  session_id  TEXT,
+  before_json TEXT,
+  after_json  TEXT,
+  created_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_memory  ON memory_audit(memory_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_audit_op      ON memory_audit(op, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_audit_session ON memory_audit(session_id, created_at DESC);
+
+-- DOWN
+-- DROP INDEX IF EXISTS idx_audit_session;
+-- DROP INDEX IF EXISTS idx_audit_op;
+-- DROP INDEX IF EXISTS idx_audit_memory;
+-- DROP TABLE IF EXISTS memory_audit;

package/migrations/010_memory_embeddings_split.sql

@@ -0,0 +1,30 @@
+-- Migration 010: split memories.embedding blob into memory_embeddings table
+-- SQLite 3.35+ required for ALTER TABLE … DROP COLUMN (Bun ships 3.35+).
+-- Runner wraps this in a transaction — no BEGIN/COMMIT here.
+
+CREATE TABLE IF NOT EXISTS memory_embeddings (
+  memory_id  INTEGER PRIMARY KEY REFERENCES memories(id) ON DELETE CASCADE,
+  embedding  BLOB    NOT NULL,
+  model      TEXT    NOT NULL DEFAULT 'unknown',
+  dim        INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_embeddings_memory ON memory_embeddings(memory_id);
+
+-- Copy existing non-null blobs before dropping the column
+INSERT OR IGNORE INTO memory_embeddings (memory_id, embedding, model, dim)
+  SELECT id, embedding, 'unknown', 0
+  FROM memories
+  WHERE embedding IS NOT NULL;
+
+-- Drop the partial index from migration 003 (references embedding column — must drop before DROP COLUMN)
+DROP INDEX IF EXISTS idx_memories_embedding;
+
+-- Drop the inline blob column now that data is in the side table
+ALTER TABLE memories DROP COLUMN embedding;
+
+-- DOWN
+DROP INDEX IF EXISTS idx_embeddings_memory;
+DROP TABLE IF EXISTS memory_embeddings;
+ALTER TABLE memories ADD COLUMN embedding BLOB;

package/migrations/011_add_decay_score_and_archive.sql

@@ -0,0 +1,25 @@
+-- Migration 011: materialised decay_score column + memory_archive table
+-- Runner wraps this in a transaction — no BEGIN/COMMIT here.
+
+-- Add pre-computed decay_score to memories (defaults to 1.0; janitor refreshes on first run)
+ALTER TABLE memories ADD COLUMN decay_score REAL NOT NULL DEFAULT 1.0;
+CREATE INDEX IF NOT EXISTS idx_memories_decay_score ON memories (decay_score DESC);
+
+-- Archive table for evicted deprecated memories (snapshot, not live FK)
+CREATE TABLE IF NOT EXISTS memory_archive (
+  id            INTEGER PRIMARY KEY,
+  memory_json   TEXT    NOT NULL,
+  archived_at   TEXT    NOT NULL DEFAULT (datetime('now')),
+  reason        TEXT    NOT NULL CHECK(reason IN ('decay','rollup','manual')),
+  decay_score   REAL,
+  project_scope TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_archive_project ON memory_archive (project_scope);
+CREATE INDEX IF NOT EXISTS idx_archive_reason  ON memory_archive (reason, archived_at DESC);
+
+-- DOWN
+DROP INDEX IF EXISTS idx_archive_reason;
+DROP INDEX IF EXISTS idx_archive_project;
+DROP TABLE IF EXISTS memory_archive;
+DROP INDEX IF EXISTS idx_memories_decay_score;
+ALTER TABLE memories DROP COLUMN decay_score;

package/migrations/012_seed_janitor_settings.sql

@@ -0,0 +1,11 @@
+-- Migration 012: seed janitor run-tracking settings
+-- INSERT OR IGNORE — safe on existing DBs.
+-- Runner wraps this in a transaction — no BEGIN/COMMIT here.
+
+INSERT OR IGNORE INTO settings (key, value, updated_at) VALUES
+  ('ltm.janitor.lastRunAt',          '',  datetime('now')),
+  ('ltm.janitor.lastDecayRefreshed', '0', datetime('now')),
+  ('ltm.janitor.lastDeprecated',     '0', datetime('now')),
+  ('ltm.janitor.lastArchived',       '0', datetime('now'));
+
+-- DOWN (no-op: removing settings rows is safe, they'll just re-seed on next migration run)

package/migrations/013_add_created_by.sql

@@ -0,0 +1,13 @@
+-- Migration 013: add created_by column to memories
+-- Backfills from the earliest memory_provenance.actor for each memory.
+ALTER TABLE memories ADD COLUMN created_by TEXT;
+
+UPDATE memories
+SET created_by = (
+  SELECT actor
+  FROM memory_provenance
+  WHERE memory_provenance.memory_id = memories.id
+  ORDER BY created_at ASC
+  LIMIT 1
+)
+WHERE created_by IS NULL;

package/migrations/014_update_audit_op_check.sql

@@ -0,0 +1,29 @@
+-- Migration 014: rebuild memory_audit with updated CHECK constraint to include 'archive' op.
+-- SQLite cannot ALTER a CHECK constraint — must recreate the table.
+-- UP
+PRAGMA foreign_keys=OFF;
+
+CREATE TABLE memory_audit_new (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  memory_id   INTEGER NOT NULL,
+  op          TEXT    NOT NULL CHECK(op IN (
+                'insert','update','forget','deprecate','supersede','redact','restore','archive')),
+  actor       TEXT    NOT NULL,
+  session_id  TEXT,
+  before_json TEXT,
+  after_json  TEXT,
+  created_at  TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+INSERT INTO memory_audit_new SELECT * FROM memory_audit;
+DROP TABLE memory_audit;
+ALTER TABLE memory_audit_new RENAME TO memory_audit;
+
+CREATE INDEX IF NOT EXISTS idx_audit_memory  ON memory_audit(memory_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_audit_op      ON memory_audit(op, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_audit_session ON memory_audit(session_id, created_at DESC);
+
+PRAGMA foreign_keys=ON;
+
+-- DOWN
+-- (reversing would require removing 'archive' from CHECK — not worth automating)

package/migrations/015_add_titles.sql

@@ -0,0 +1,14 @@
+-- Migration 015: add title columns to memories and context_items (DDL only)
+-- Title is a short human-readable label (≤60 chars).
+--
+-- Pure-DDL, isolated from the value backfill so this step is self-heal eligible
+-- on a fresh install: schema.sql already pre-bakes `title`, so the ALTERs
+-- collide and the four-form DDL self-heal gate records the version once it
+-- proves both columns exist. On a legacy pre-015 install the columns are
+-- genuinely missing, so the ALTERs succeed and add them here.
+--
+-- The data-changing backfill (UPDATE ... SET title FROM content) lives in
+-- 024_title_backfill.sql with its own status gate and idempotency check.
+
+ALTER TABLE memories ADD COLUMN title TEXT;
+ALTER TABLE context_items ADD COLUMN title TEXT;

package/migrations/016_memory_layout.sql

@@ -0,0 +1,15 @@
+-- Migration 016: per-view layout persistence
+-- Positions are saved only when the user explicitly drags or pins a node.
+-- 'view' = 'global' for the global graph, or a project name for drill-down.
+
+CREATE TABLE IF NOT EXISTS memory_layout (
+  memory_id  INTEGER NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  view       TEXT    NOT NULL,
+  x          REAL    NOT NULL,
+  y          REAL    NOT NULL,
+  pinned     INTEGER NOT NULL DEFAULT 0,
+  updated_at TEXT    NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (memory_id, view)
+);
+
+CREATE INDEX IF NOT EXISTS idx_layout_view ON memory_layout(view);

package/migrations/017_node_ui_state.sql

@@ -0,0 +1,14 @@
+-- Migration 017: per-node UI state columns (DDL only)
+-- hidden: excluded from /api/graph unless ?includeHidden=1
+-- color: manual override; NULL means use category color
+-- icon: optional emoji/icon key
+--
+-- Pure DDL, isolated from the supporting index: the four ALTER statements
+-- self-heal cleanly on a fresh install (schema.sql pre-bakes the columns).
+-- The partial index that backs `hidden=1` lookups lives in
+-- 025_idx_memories_hidden.sql with its own status gate, so on fresh installs
+-- the column step never fails just because the index target is still missing.
+
+ALTER TABLE memories ADD COLUMN hidden INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memories ADD COLUMN color  TEXT;
+ALTER TABLE memories ADD COLUMN icon   TEXT;

package/migrations/018_relation_semantics.sql

@@ -0,0 +1,7 @@
+-- Migration 018: edge semantics — rationale note + base weight
+-- Effective weight = base × decay, computed at read time (never stored).
+-- Manual edges default to 1.0; LLM-inferred edges use confidence-derived weight.
+
+ALTER TABLE memory_relations ADD COLUMN note   TEXT;
+ALTER TABLE memory_relations ADD COLUMN weight REAL NOT NULL DEFAULT 1.0
+  CHECK(weight BETWEEN 0.0 AND 1.0);

package/migrations/019_user_note.sql

@@ -0,0 +1,5 @@
+-- Migration 019: human-authored annotation on memories
+-- user_note is never overwritten by learn() re-confirmation or the janitor.
+-- Kept separate from machine-written content.
+
+ALTER TABLE memories ADD COLUMN user_note TEXT;

package/migrations/020_fts_coverage.sql

@@ -0,0 +1,68 @@
+-- Migration 020: extend FTS coverage to include titles and context_items
+-- Drops and recreates memories_fts to add the title column.
+-- Adds context_items_fts for in-graph search coverage.
+
+-- ── memories_fts rebuild ──────────────────────────────────────────────────────
+
+DROP TABLE IF EXISTS memories_fts;
+
+CREATE VIRTUAL TABLE memories_fts USING fts5(
+  title,
+  content,
+  content='memories',
+  content_rowid='id'
+);
+
+-- Repopulate from base table (title may be NULL for very old rows — coalesce to '').
+INSERT INTO memories_fts(rowid, title, content)
+  SELECT id, coalesce(title, ''), content FROM memories;
+
+DROP TRIGGER IF EXISTS memories_ai;
+DROP TRIGGER IF EXISTS memories_ad;
+DROP TRIGGER IF EXISTS memories_au;
+
+CREATE TRIGGER memories_ai AFTER INSERT ON memories BEGIN
+  INSERT INTO memories_fts(rowid, title, content)
+    VALUES (new.id, coalesce(new.title, ''), new.content);
+END;
+
+CREATE TRIGGER memories_ad AFTER DELETE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, title, content)
+    VALUES ('delete', old.id, coalesce(old.title, ''), old.content);
+END;
+
+CREATE TRIGGER memories_au AFTER UPDATE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, title, content)
+    VALUES ('delete', old.id, coalesce(old.title, ''), old.content);
+  INSERT INTO memories_fts(rowid, title, content)
+    VALUES (new.id, coalesce(new.title, ''), new.content);
+END;
+
+-- ── context_items_fts ─────────────────────────────────────────────────────────
+
+CREATE VIRTUAL TABLE IF NOT EXISTS context_items_fts USING fts5(
+  title,
+  content,
+  content='context_items',
+  content_rowid='id'
+);
+
+INSERT OR IGNORE INTO context_items_fts(rowid, title, content)
+  SELECT id, coalesce(title, ''), content FROM context_items;
+
+CREATE TRIGGER IF NOT EXISTS context_items_ai AFTER INSERT ON context_items BEGIN
+  INSERT INTO context_items_fts(rowid, title, content)
+    VALUES (new.id, coalesce(new.title, ''), new.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS context_items_ad AFTER DELETE ON context_items BEGIN
+  INSERT INTO context_items_fts(context_items_fts, rowid, title, content)
+    VALUES ('delete', old.id, coalesce(old.title, ''), old.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS context_items_au AFTER UPDATE ON context_items BEGIN
+  INSERT INTO context_items_fts(context_items_fts, rowid, title, content)
+    VALUES ('delete', old.id, coalesce(old.title, ''), old.content);
+  INSERT INTO context_items_fts(rowid, title, content)
+    VALUES (new.id, coalesce(new.title, ''), new.content);
+END;

package/migrations/021_cluster_manual_label.sql

@@ -0,0 +1,5 @@
+-- Migration 021: manual_label flag on memory_clusters
+-- When 1, the user has manually renamed this cluster.
+-- The recompute logic preserves manual labels by matching via sorted node_ids hash.
+
+ALTER TABLE memory_clusters ADD COLUMN manual_label INTEGER NOT NULL DEFAULT 0;

package/migrations/022_add_relevance_signal.sql

@@ -0,0 +1,11 @@
+-- Migration 022: personal relevance signal on memories
+-- Lets a user mark a memory as "works for me" / "doesn't work for me".
+-- Human-authored, like user_note — never touched by learn() or the janitor.
+-- relevance_signal is one of 'works' | 'doesnt' (NULL = unrated).
+
+ALTER TABLE memories ADD COLUMN relevance_signal TEXT;
+ALTER TABLE memories ADD COLUMN relevance_signal_at TEXT;
+
+-- DOWN
+ALTER TABLE memories DROP COLUMN relevance_signal;
+ALTER TABLE memories DROP COLUMN relevance_signal_at;

package/migrations/023_memory_files.sql

@@ -0,0 +1,27 @@
+-- Migration 023: code-anchored invalidation — memory_files join + staleness columns
+-- Runner wraps this in a transaction — no BEGIN/COMMIT here.
+-- Anchors memories to the repo files they reference, so a commit touching those
+-- files can flag the anchored memories stale (see flagStaleByPaths / GitCommit hook).
+
+-- Many-to-many: a memory ↔ the repo-relative paths it references.
+CREATE TABLE IF NOT EXISTS memory_files (
+  memory_id     INTEGER NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  path          TEXT    NOT NULL,            -- normalised repo-relative path
+  project_scope TEXT,                        -- NULL = global, else project name (cross-repo safety)
+  created_at    TEXT    NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (memory_id, path)
+);
+CREATE INDEX IF NOT EXISTS idx_memory_files_path ON memory_files(path);
+
+-- Staleness flag (set by code-change invalidation; cleared on re-confirm/revalidate).
+-- NULL = not flagged. Distinct from decay/supersession — driven by code change, not recall.
+ALTER TABLE memories ADD COLUMN stale_flagged_at TEXT;
+ALTER TABLE memories ADD COLUMN stale_reason     TEXT;
+CREATE INDEX IF NOT EXISTS idx_memories_stale ON memories(stale_flagged_at);
+
+-- DOWN
+DROP INDEX IF EXISTS idx_memories_stale;
+ALTER TABLE memories DROP COLUMN stale_reason;
+ALTER TABLE memories DROP COLUMN stale_flagged_at;
+DROP INDEX IF EXISTS idx_memory_files_path;
+DROP TABLE IF EXISTS memory_files;

package/migrations/024_title_backfill.sql

@@ -0,0 +1,38 @@
+-- Migration 024: backfill title values from content (data-changing, own gate)
+-- Populates title for rows that predate the title column (legacy pre-015
+-- installs). Kept in its own migration so the DDL step (015) stays pure-DDL
+-- and self-heal eligible; this step is its own status-gated unit like any
+-- migration, and the runner's checksum is recorded as usual.
+--
+-- Idempotent by construction: only rows WHERE title IS NULL are touched, so
+-- re-running this migration (or the runner) is a no-op on already-backfilled
+-- rows. No destructiveness, no rename — fail-closed runner accepts it as a
+-- data-changing step that never needs self-heal because the columns it reads
+-- (content, title) exist for both fresh (pre-baked or added by 015) and legacy
+-- installs by the time this version runs (015 < 016 < ... < 024).
+
+-- Backfill memories: first sentence (up to '.', '!', '?', or newline), else first 57 chars + ellipsis.
+UPDATE memories SET title =
+  CASE
+    WHEN instr(content, '.') > 1 AND instr(content, '.') <= 61
+      THEN trim(substr(content, 1, instr(content, '.') - 1))
+    WHEN instr(content, char(10)) > 1 AND instr(content, char(10)) <= 61
+      THEN trim(substr(content, 1, instr(content, char(10)) - 1))
+    WHEN length(trim(content)) <= 60
+      THEN trim(content)
+    ELSE substr(trim(content), 1, 57) || '…'
+  END
+WHERE title IS NULL;
+
+-- Backfill context_items with same heuristic.
+UPDATE context_items SET title =
+  CASE
+    WHEN instr(content, '.') > 1 AND instr(content, '.') <= 61
+      THEN trim(substr(content, 1, instr(content, '.') - 1))
+    WHEN instr(content, char(10)) > 1 AND instr(content, char(10)) <= 61
+      THEN trim(substr(content, 1, instr(content, char(10)) - 1))
+    WHEN length(trim(content)) <= 60
+      THEN trim(content)
+    ELSE substr(trim(content), 1, 57) || '…'
+  END
+WHERE title IS NULL;

package/migrations/025_idx_memories_hidden.sql

@@ -0,0 +1,12 @@
+-- Migration 025: partial index on memories(hidden) (pure DDL, idempotent)
+-- Supports the /api/graph exclude-hidden filter. Split out of 017 so that
+-- migration stays pure-DDL and self-heal eligible: on a fresh install
+-- schema.sql pre-bakes hidden/color/icon but NOT this index, so the gate
+-- would otherwise refuse 017 because the index target doesn't exist yet.
+--
+-- Own status-gated unit. `CREATE INDEX IF NOT EXISTS` is natively idempotent
+-- in SQLite, so it succeeds identically whether the index already exists
+-- (legacy install that ran the old 017) or not (fresh install that only just
+-- added the column). Pure DDL, indistinguishable to the fail-closed runner.
+
+CREATE INDEX IF NOT EXISTS idx_memories_hidden ON memories(hidden) WHERE hidden = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohirik/openltm-core",
-  "version": "2.14.0",
+  "version": "2.14.2",
   "description": "Shared LTM storage engine — path-agnostic SQLite core used by Claude Code, OpenCode, and Pi adapters",
   "type": "module",
   "main": "./src/index.ts",

package/src/__tests__/packaging.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Packaging tests.
+ *
+ * The published npm tarball is the install path the README advertises, so a
+ * missing runtime file is a shipping bug — not a cosmetic one. These tests
+ * guard the files that must be inside the tarball and keep the duplicated
+ * migration copies from drifting.
+ */
+import { describe, expect, it } from "bun:test";
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { join } from "path";
+
+const REPO_ROOT = join(import.meta.dir, "..", "..", "..", "..");
+const CORE_ROOT = join(REPO_ROOT, "packages", "openltm-core");
+
+describe("migration files are shipped with the package", () => {
+  it("keeps a package-local copy of every root migration", () => {
+    const rootDir = join(REPO_ROOT, "migrations");
+    const pkgDir = join(CORE_ROOT, "migrations");
+
+    const rootFiles = readdirSync(rootDir).filter((f) => f.endsWith(".sql")).sort();
+    const pkgFiles = readdirSync(pkgDir).filter((f) => f.endsWith(".sql")).sort();
+
+    expect(pkgFiles).toEqual(rootFiles);
+  });
+
+  it("keeps the two migration copies byte-identical", () => {
+    for (const file of readdirSync(join(REPO_ROOT, "migrations")).filter((f) => f.endsWith(".sql"))) {
+      const root = readFileSync(join(REPO_ROOT, "migrations", file), "utf-8");
+      const packaged = readFileSync(join(CORE_ROOT, "migrations", file), "utf-8");
+      expect(`${file}:${packaged === root}`).toBe(`${file}:true`);
+    }
+  });
+
+  it("resolves the packaged copy first, not the monorepo root", async () => {
+    const { getMigrationsDir } = await import("../paths.js");
+    const resolved = getMigrationsDir();
+    expect(existsSync(resolved)).toBe(true);
+    expect(resolved).toBe(join(CORE_ROOT, "migrations"));
+  });
+});
+
+describe("package manifest includes runtime files", () => {
+  it("does not exclude migrations from the published tarball", async () => {
+    const pkg = JSON.parse(readFileSync(join(CORE_ROOT, "package.json"), "utf-8"));
+    const files = pkg.files as string[] | undefined;
+    // An explicit `files` allowlist that omits migrations/ would reintroduce the
+    // bug this suite exists to prevent.
+    if (files) {
+      expect(files.some((entry) => entry.includes("migrations"))).toBe(true);
+    }
+  });
+
+  it("exposes the same runtime entrypoints npm consumers need", () => {
+    const pkg = JSON.parse(readFileSync(join(CORE_ROOT, "package.json"), "utf-8"));
+    for (const entry of [".", "./cli", "./mcp"]) {
+      expect(Object.keys(pkg.exports)).toContain(entry);
+    }
+    for (const bin of ["ltm", "openltm", "openltm-core"]) {
+      expect(Object.keys(pkg.bin)).toContain(bin);
+    }
+  });
+});

package/src/paths.ts

@@ -4,6 +4,7 @@
  * The CLAUDE_DIR constant is intentionally absent — adapters inject paths via LtmCoreConfig.
  */
 import { join } from "path";
+import { existsSync } from "fs";
 
 export function getDbPath(): string {
   if (process.env["LTM_DB_PATH"]) return process.env["LTM_DB_PATH"];
@@ -15,8 +16,19 @@ export function getSchemaPath(): string {
   return join(import.meta.dir, "schema.sql");
 }
 
+/**
+ * Locate the versioned SQL migrations.
+ *
+ * Order matters: the package-local `migrations/` copy is checked FIRST because
+ * it is the one that ships inside the published npm tarball. The monorepo-root
+ * path is only the development fallback. A published install that resolved to
+ * the root path would silently find zero migrations and hand back a
+ * column-incomplete database (missing `decay_score`, `workspace_id`, …).
+ */
 export function getMigrationsDir(): string {
-  // Resolves to project-root migrations/ during development inside the monorepo.
-  // Adapters should set LtmCoreConfig.migrationsDir when deploying standalone.
+  const packaged = join(import.meta.dir, "..", "migrations");
+  if (existsSync(packaged)) return packaged;
+
+  // Development inside the monorepo.
   return join(import.meta.dir, "..", "..", "..", "migrations");
 }