@astragenie/astramemory-local 0.7.2

package/migrations/001-init.sql

@@ -0,0 +1,117 @@
+CREATE TABLE sessions (
+  id TEXT PRIMARY KEY,
+  repo TEXT,
+  project TEXT,
+  branch TEXT,
+  agent TEXT,
+  started_at INTEGER NOT NULL,
+  ended_at INTEGER
+);
+CREATE INDEX idx_sessions_repo_started ON sessions(repo, started_at DESC);
+
+CREATE TABLE messages (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  role TEXT NOT NULL,
+  content TEXT NOT NULL,
+  ts INTEGER NOT NULL,
+  kind TEXT
+);
+CREATE INDEX idx_messages_session ON messages(session_id, ts);
+
+CREATE TABLE transcripts (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  source TEXT NOT NULL,
+  content TEXT NOT NULL,
+  ingested_at INTEGER NOT NULL
+);
+CREATE INDEX idx_transcripts_session ON transcripts(session_id);
+
+CREATE TABLE memories (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL CHECK(type IN ('decision','fact','lesson','command','todo')),
+  text TEXT NOT NULL,
+  normalized_text TEXT NOT NULL,
+  repo TEXT,
+  project TEXT,
+  branch TEXT,
+  agent TEXT,
+  session_id TEXT REFERENCES sessions(id) ON DELETE SET NULL,
+  importance REAL NOT NULL DEFAULT 0.5,
+  confidence REAL NOT NULL DEFAULT 0.5,
+  hash TEXT NOT NULL,
+  embedding_provider TEXT,
+  embedding_model TEXT,
+  embedding_dim INTEGER,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  source_hash TEXT
+);
+CREATE UNIQUE INDEX idx_memories_hash ON memories(hash);
+CREATE INDEX idx_memories_repo_type ON memories(repo, type, created_at DESC);
+CREATE INDEX idx_memories_session ON memories(session_id);
+
+CREATE VIRTUAL TABLE memories_fts USING fts5(
+  text, normalized_text, content='memories', content_rowid='rowid'
+);
+
+CREATE TRIGGER memories_ai AFTER INSERT ON memories BEGIN
+  INSERT INTO memories_fts(rowid, text, normalized_text) VALUES (new.rowid, new.text, new.normalized_text);
+END;
+CREATE TRIGGER memories_ad AFTER DELETE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, text, normalized_text) VALUES('delete', old.rowid, old.text, old.normalized_text);
+END;
+CREATE TRIGGER memories_au AFTER UPDATE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, text, normalized_text) VALUES('delete', old.rowid, old.text, old.normalized_text);
+  INSERT INTO memories_fts(rowid, text, normalized_text) VALUES (new.rowid, new.text, new.normalized_text);
+END;
+
+-- Vector index dim is parameterized (FEAT-409, src/contracts/embed.ts
+-- DEFAULT_EMBED_DIM). __EMBED_DIM__ is substituted by storage/migrate.ts
+-- with config.embedding.dim at migration time — defaults to 1024, matching
+-- both Ollama mxbai-embed-large (native 1024) and Azure text-embedding-3-*
+-- (via `dimensions: 1024`). This substitution only affects a FRESH
+-- database (this file only runs once, the first time schema_version has no
+-- row for version 1); an EXISTING database's dim is immutable short of the
+-- resumable re-embed procedure (migration 011, `astramem-local
+-- reembed-dim`) since sqlite-vec's vec0 table fixes its dim at CREATE
+-- TABLE time. Changing the embedding provider (even at the same dim)
+-- still requires a re-embed pass — different models are different
+-- geometric spaces.
+CREATE VIRTUAL TABLE memories_vec USING vec0(embedding FLOAT[__EMBED_DIM__]);
+
+CREATE TABLE jobs (
+  id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL,
+  payload_json TEXT NOT NULL,
+  state TEXT NOT NULL CHECK(state IN ('pending','running','completed','failed','poison','paused')),
+  attempts INTEGER NOT NULL DEFAULT 0,
+  last_error TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+CREATE INDEX idx_jobs_state ON jobs(state, created_at);
+
+CREATE TABLE artifacts (
+  id TEXT PRIMARY KEY,
+  job_id TEXT NOT NULL REFERENCES jobs(id) ON DELETE CASCADE,
+  kind TEXT NOT NULL,
+  content_path TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE TABLE provider_state (
+  provider TEXT NOT NULL,
+  model TEXT NOT NULL,
+  dim INTEGER,
+  last_health_ok INTEGER NOT NULL DEFAULT 0,
+  last_check_at INTEGER,
+  PRIMARY KEY (provider, model)
+);
+
+CREATE TABLE budget_spend (
+  day TEXT PRIMARY KEY,
+  usd_total REAL NOT NULL DEFAULT 0,
+  calls INTEGER NOT NULL DEFAULT 0
+);

package/migrations/002-wire-v1.sql

@@ -0,0 +1,16 @@
+ALTER TABLE transcripts ADD COLUMN event TEXT;
+ALTER TABLE transcripts ADD COLUMN captured_at INTEGER;
+ALTER TABLE transcripts ADD COLUMN client_scrub_applied INTEGER;
+ALTER TABLE transcripts ADD COLUMN client_scrub_hits INTEGER;
+ALTER TABLE transcripts ADD COLUMN client_scrub_version TEXT;
+ALTER TABLE transcripts ADD COLUMN client_scrub_hits_by_label_json TEXT;
+ALTER TABLE transcripts ADD COLUMN client_version TEXT;
+ALTER TABLE transcripts ADD COLUMN wire_version TEXT NOT NULL DEFAULT 'v0.0';
+
+CREATE TABLE ingest_idempotency (
+  key TEXT PRIMARY KEY,
+  tenant_id TEXT,
+  body_hash TEXT NOT NULL,
+  summary_memory_id TEXT,
+  created_at INTEGER NOT NULL
+);

package/migrations/003-expand-memory-types.sql

@@ -0,0 +1,81 @@
+-- 003: Expand memories.type CHECK to include 'note' + 'event'
+-- SQLite table-rewrite pattern (CHECK constraints are immutable).
+-- migrate.ts wraps each migration in db.transaction() — no explicit BEGIN/COMMIT here.
+--
+-- FK safety: PRAGMA foreign_keys = OFF is a session-level, out-of-transaction operation
+-- and cannot be set inside better-sqlite3's transaction wrapper. It is not required here
+-- because:
+--   (a) we INSERT INTO memories_new SELECT * FROM memories — all existing session_id
+--       values are already valid referents in sessions;
+--   (b) the memories_vec virtual table has no FK dependency on memories.
+
+-- 1. Create new table with expanded CHECK (all other columns verbatim from 001-init.sql)
+CREATE TABLE memories_new (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL CHECK(type IN ('decision','fact','lesson','command','todo','note','event')),
+  text TEXT NOT NULL,
+  normalized_text TEXT NOT NULL,
+  repo TEXT,
+  project TEXT,
+  branch TEXT,
+  agent TEXT,
+  session_id TEXT REFERENCES sessions(id) ON DELETE SET NULL,
+  importance REAL NOT NULL DEFAULT 0.5,
+  confidence REAL NOT NULL DEFAULT 0.5,
+  hash TEXT NOT NULL,
+  embedding_provider TEXT,
+  embedding_model TEXT,
+  embedding_dim INTEGER,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  source_hash TEXT
+);
+
+-- 2. Copy all existing rows
+INSERT INTO memories_new SELECT * FROM memories;
+
+-- 3. Drop old triggers that reference the old memories table
+DROP TRIGGER IF EXISTS memories_ai;
+DROP TRIGGER IF EXISTS memories_ad;
+DROP TRIGGER IF EXISTS memories_au;
+
+-- 4. Drop old indexes attached to memories
+DROP INDEX IF EXISTS idx_memories_hash;
+DROP INDEX IF EXISTS idx_memories_repo_type;
+DROP INDEX IF EXISTS idx_memories_session;
+
+-- 5. Drop FTS table (FTS5 content= binding references the table by name;
+--    it does NOT follow a rename — must drop and recreate)
+DROP TABLE IF EXISTS memories_fts;
+
+-- 6. Drop old table and rename new table into place
+DROP TABLE memories;
+ALTER TABLE memories_new RENAME TO memories;
+
+-- 7. Recreate indexes (verbatim from 001-init.sql)
+CREATE UNIQUE INDEX idx_memories_hash ON memories(hash);
+CREATE INDEX idx_memories_repo_type ON memories(repo, type, created_at DESC);
+CREATE INDEX idx_memories_session ON memories(session_id);
+
+-- 8. Recreate FTS5 virtual table (verbatim from 001-init.sql)
+CREATE VIRTUAL TABLE memories_fts USING fts5(
+  text, normalized_text, content='memories', content_rowid='rowid'
+);
+
+-- 9. Repopulate FTS from existing rows
+INSERT INTO memories_fts(rowid, text, normalized_text)
+  SELECT rowid, text, normalized_text FROM memories;
+
+-- 10. Recreate triggers (verbatim from 001-init.sql)
+CREATE TRIGGER memories_ai AFTER INSERT ON memories BEGIN
+  INSERT INTO memories_fts(rowid, text, normalized_text) VALUES (new.rowid, new.text, new.normalized_text);
+END;
+CREATE TRIGGER memories_ad AFTER DELETE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, text, normalized_text) VALUES('delete', old.rowid, old.text, old.normalized_text);
+END;
+CREATE TRIGGER memories_au AFTER UPDATE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, text, normalized_text) VALUES('delete', old.rowid, old.text, old.normalized_text);
+  INSERT INTO memories_fts(rowid, text, normalized_text) VALUES (new.rowid, new.text, new.normalized_text);
+END;
+
+-- memories_vec is a separate virtual table (vec0) — unaffected by memories rewrite, leave alone.

package/migrations/004-provenance.sql

@@ -0,0 +1,4 @@
+-- AM-1: persist stage-5 extraction evidence (provenance receipts).
+-- Nullable: rows created before v0.4.0 have no evidence — why_memory
+-- degrades gracefully. See design doc 2026-07-02 §2/§3.
+ALTER TABLE memories ADD COLUMN evidence TEXT;

package/migrations/005-security.sql

@@ -0,0 +1,12 @@
+-- SEC-6: stage-0 secret-redaction counters. Counts + types only per ingest —
+-- raw secret values are NEVER written here (see src/redact/). Surfaced via
+-- `doctor` and GET /health. See docs/specs/2026-07-02-encryption-and-secret-redaction.md §4.2/§4.3.
+CREATE TABLE redaction_log (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  type TEXT NOT NULL,
+  count INTEGER NOT NULL,
+  session_id TEXT NULL,
+  created_at INTEGER NOT NULL
+);
+CREATE INDEX idx_redaction_log_created ON redaction_log(created_at DESC);
+CREATE INDEX idx_redaction_log_type ON redaction_log(type, created_at DESC);

package/migrations/006-atom-v3.sql

@@ -0,0 +1,28 @@
+-- 006: Atom v3 (ADR-001) — bitemporal validity, scope, lineage on memories.
+-- See docs/adr/ADR-001-canonical-memory-atom.md.
+--
+-- valid_from/valid_to: bitemporal valid-time window. valid_to NULL = currently
+-- valid. New rows set valid_from = created_at at insert time (see
+-- src/storage/memories.ts); existing rows are backfilled below.
+-- superseded_by: id of the memory that replaced this one. Mutated only via
+-- the lifecycle/event-log ops landing in Wave 2b — this migration just adds
+-- the column (NULL for all rows).
+-- derived_from: JSON array of memory ids — consolidation lineage (ADR-004
+-- stage 9). NULL until a consolidation pass sets it.
+-- scope: personal | team | org (ADR-009); personal is the default.
+--
+-- SQLite ALTER TABLE ADD COLUMN cannot add NOT NULL with a non-constant
+-- default on existing rows, but a literal constant default (scope) is fine
+-- directly on the ALTER. valid_from has no literal default available (it
+-- must mirror each row's own created_at), so it is backfilled via a
+-- separate UPDATE statement below.
+
+ALTER TABLE memories ADD COLUMN valid_from INTEGER;
+ALTER TABLE memories ADD COLUMN valid_to INTEGER;
+ALTER TABLE memories ADD COLUMN superseded_by TEXT;
+ALTER TABLE memories ADD COLUMN derived_from TEXT;
+ALTER TABLE memories ADD COLUMN scope TEXT NOT NULL DEFAULT 'personal';
+
+-- Backfill valid_from for pre-existing rows so bitemporal queries are
+-- correct from day one.
+UPDATE memories SET valid_from = created_at WHERE valid_from IS NULL;

package/migrations/007-memory-events.sql

@@ -0,0 +1,30 @@
+-- 007: memory_events append-only log (ADR-002 decision point 1).
+-- See docs/adr/ADR-002-local-storage-engine.md.
+--
+-- Source of truth for state *changes*: create | invalidate | supersede |
+-- promote_scope | erase_request | usefulness. Materialized state (the
+-- memories table) is updated in the same transaction as the event append —
+-- see src/storage/memory-events.ts MemoryEventRepo. This is log + tables in
+-- one file, not full event sourcing: no view rebuilding, no projection
+-- framework. The log exists so ADR-003 sync becomes log-shipping and audit
+-- becomes free.
+
+CREATE TABLE memory_events (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  event_type TEXT NOT NULL CHECK(event_type IN ('create', 'invalidate', 'supersede', 'promote_scope', 'erase_request', 'usefulness')),
+  atom_id TEXT NOT NULL,
+  payload_json TEXT,
+  content_hash TEXT,
+  created_at INTEGER NOT NULL,
+  synced_at INTEGER
+);
+
+CREATE INDEX idx_memory_events_atom_seq ON memory_events (atom_id, seq);
+
+-- Backfill: synthetic 'create' events for every pre-existing memory, so the
+-- first sync (ADR-003) ships a complete log rather than one with a gap at
+-- the start. Hash-stable: content_hash mirrors the memory's own hash column;
+-- created_at mirrors the memory's own created_at (not the migration's run
+-- time), so replays are consistent with actual atom creation order.
+INSERT INTO memory_events (event_type, atom_id, payload_json, content_hash, created_at)
+SELECT 'create', id, '{"backfill":true}', hash, created_at FROM memories;

package/migrations/008-consolidation.sql

@@ -0,0 +1,31 @@
+-- 008: consolidation proposals (ADR-004 stage 9, Wave 4b).
+--
+-- Propose-only queue for consolidation actions that must NOT auto-apply
+-- (strategy Pass 6 A4: auto-invalidation is trust-destroying). The offline
+-- consolidation job writes 'pending' rows; the user accepts or rejects via
+-- REST/MCP. Auto-merges (similarity above the merge threshold) bypass this
+-- table entirely — they go straight through the supersede event flow, which
+-- is non-destructive by construction (W4 fix: originals kept as superseded,
+-- lineage recorded in memories.derived_from).
+--
+-- kind 'merge'          — borderline near-duplicate pair, user confirms merge.
+-- kind 'contradiction'  — reserved for the v1.x LLM contradiction detector;
+--                          the confirm flow is identical, only the producer differs.
+
+CREATE TABLE consolidation_proposals (
+  id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL CHECK(kind IN ('merge', 'contradiction')),
+  -- winner_id: the atom that would survive; loser_id: the atom that would be
+  -- superseded. Pair is stored directionally after winner selection.
+  winner_id TEXT NOT NULL,
+  loser_id TEXT NOT NULL,
+  similarity REAL NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending', 'accepted', 'rejected')),
+  created_at INTEGER NOT NULL,
+  resolved_at INTEGER
+);
+
+-- One live proposal per unordered pair — the job dedups on this before insert.
+CREATE UNIQUE INDEX idx_consolidation_pair_pending
+  ON consolidation_proposals (MIN(winner_id, loser_id), MAX(winner_id, loser_id))
+  WHERE status = 'pending';

package/migrations/009-tag-hygiene.sql

@@ -0,0 +1,13 @@
+-- 009: tag hygiene (W4.3, FEAT-403) — persist session cwd.
+--
+-- `cwd` was already accepted on the canonical ingest envelope
+-- (CanonicalIngestSchema.cwd, src/server/routes/ingest.ts) but never
+-- persisted anywhere — the canonical wire path only ever wrote `project`
+-- (from project_id) into `sessions`, leaving `sessions.repo` NULL forever
+-- for every canonical-ingested session. That left no durable signal to
+-- derive a memory's `repo` tag from after the fact.
+--
+-- Storing cwd lets the tag-hygiene backfill (src/tag-hygiene/backfill.ts)
+-- derive `repo` from the last path segment of the session's cwd when
+-- `sessions.repo` itself is unset (tier-1 heuristic, AC-1).
+ALTER TABLE sessions ADD COLUMN cwd TEXT;

package/migrations/010-sync-pull.sql

@@ -0,0 +1,53 @@
+-- 010: sync pull — event_id (ADR-011 multi-device conflict policy) +
+-- sync_pull_state (FEAT-407 pull watermark).
+-- See docs/adr/ADR-011-multi-device-conflict-policy.md.
+--
+-- Part 1 — event_id on memory_events:
+-- Globally-unique per-event identity assigned once at append time. This is
+-- the pull-side idempotency key (FEAT-407 AC-2): "INSERT ... WHERE NOT
+-- EXISTS (SELECT 1 FROM memory_events WHERE event_id = ?)" per pulled row,
+-- and the deterministic tie-break key (created_at, event_id) ADR-011's
+-- conflict rules use. Additive on the wire (WireSyncEvent gains event_id,
+-- no astramem-sync@1 version bump — ADR-001's additive-field evolution
+-- rule) and additive here: existing single-device append()/invalidate()/
+-- supersede()/erase() code paths are unaffected other than now also writing
+-- event_id.
+--
+-- SQLite ALTER TABLE ADD COLUMN cannot add NOT NULL with a non-constant
+-- default on existing rows (same constraint migration 006 documented), so
+-- the column is added nullable, backfilled per-row with a distinct
+-- UUIDv4-shaped value (mirrors migration 007's synthetic-value backfill
+-- pattern), then uniquely indexed. New rows always supply event_id via
+-- MemoryEventRepo.append() (node:crypto randomUUID()) — enforced at the
+-- application layer since SQLite can't retrofit a NOT NULL constraint onto
+-- an existing column without a full table rebuild.
+
+ALTER TABLE memory_events ADD COLUMN event_id TEXT;
+
+UPDATE memory_events
+SET event_id = lower(
+  hex(randomblob(4)) || '-' ||
+  hex(randomblob(2)) || '-4' ||
+  substr(hex(randomblob(2)), 2) || '-' ||
+  substr('89ab', 1 + (abs(random()) % 4), 1) ||
+  substr(hex(randomblob(2)), 2) || '-' ||
+  hex(randomblob(6))
+)
+WHERE event_id IS NULL;
+
+CREATE UNIQUE INDEX idx_memory_events_event_id ON memory_events (event_id);
+
+-- Part 2 — sync_pull_state: persisted pull cursor/watermark (FEAT-407's own
+-- scope, per ADR-011's "Implications for FEAT-407": the merge/dedup
+-- mechanics are ADR-011's, persisting where pull left off is FEAT-407's).
+-- Single-row table (id=1 enforced) — one pull cursor per daemon install.
+-- Persisted, and advanced in the SAME transaction as the dedup-insert +
+-- projection recompute it corresponds to, so a daemon restart mid-sync
+-- resumes from the last-persisted cursor rather than re-pulling from zero
+-- or leaving a gap (AC-4).
+
+CREATE TABLE sync_pull_state (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  cursor TEXT,
+  updated_at INTEGER NOT NULL
+);

package/migrations/011-embed-dim-migration.sql

@@ -0,0 +1,28 @@
+-- FEAT-409: resumable checkpoint tracking for the embedding-dimension
+-- re-embed procedure (`astramem-local reembed-dim`, docs/embed-dim-migration.md).
+--
+-- sqlite-vec's vec0 virtual table bakes its dim into CREATE VIRTUAL TABLE
+-- DDL — there is no ALTER for it. Changing config.embedding.dim against an
+-- EXISTING database with live data therefore requires: (1) recreating
+-- memories_vec at the new dim (destructive — the pre-change backup is the
+-- rollback, per AC-4), then (2) re-embedding every memory's text with the
+-- newly-configured provider and upserting into the recreated table.
+--
+-- Step (2) calls out to the embed provider over the network per memory and
+-- can be interrupted (Ctrl+C, crash, transient provider failure). This
+-- table is the resumability mechanism: `reembed-dim` commits one row here
+-- in the SAME transaction as each memory's vec upsert, so a re-run skips
+-- memory ids already checkpointed for the target dim instead of redoing
+-- completed work or leaving a memory half-migrated.
+--
+-- This is intentionally NOT the vector store itself and carries no dim
+-- literal of its own — target_dim is data, supplied at runtime by the CLI,
+-- not baked into schema (unlike memories_vec, whose dim genuinely must be
+-- fixed at CREATE TABLE time for vec0 to work at all).
+CREATE TABLE dim_migration_progress (
+  memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  target_dim INTEGER NOT NULL,
+  completed_at INTEGER NOT NULL,
+  PRIMARY KEY (memory_id, target_dim)
+);
+CREATE INDEX idx_dim_migration_progress_target ON dim_migration_progress(target_dim);

package/migrations/012-entities.sql

@@ -0,0 +1,36 @@
+-- 012: entity extraction schema (W4.2, FEAT-402 slice 1).
+--
+-- entities: canonical named-thing registry. `name` is normalized (lowercase
+-- + trim; AC-9 seam — src/entity/normalize.ts normalizeEntityName) so
+-- "Postgres"/"postgres"/"  Postgres  " collapse to one row via the UNIQUE
+-- constraint (EntityRepo.upsert selects-then-inserts on the normalized
+-- name). An alias table ("pg" -> "postgres") is deferred — normalizeEntityName
+-- is the single seam callers go through, so adding aliasing later never
+-- touches call sites.
+--
+-- memory_entities: many-to-many link, memory_id -> entity_id, written by the
+-- distill-time embed-index stage (same LLM call as atom extraction) and by
+-- the one-shot `entity-backfill` CLI command for the pre-existing corpus.
+--
+-- Cascade (AC-3, zero orphan links):
+--   - erase() HARD-deletes the memories row (src/storage/memory-events.ts) —
+--     ON DELETE CASCADE on memory_id follows it automatically because
+--     foreign_keys=ON is set for every connection (src/storage/db.ts).
+--   - supersede() does NOT delete the memories row (bitemporal history is
+--     kept for as_of queries) so it cannot rely on FK cascade; it explicitly
+--     deletes the old memory's memory_entities rows in the same transaction
+--     — a superseded memory's facts should stop counting as "current"
+--     evidence for an entity even though the row itself survives for audit.
+CREATE TABLE entities (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL UNIQUE,
+  kind TEXT NOT NULL
+);
+
+CREATE TABLE memory_entities (
+  memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+  entity_id TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
+  PRIMARY KEY (memory_id, entity_id)
+);
+
+CREATE INDEX idx_memory_entities_entity ON memory_entities(entity_id);

package/migrations/013-archival.sql

@@ -0,0 +1,50 @@
+-- 013: memory TTL / archival tiers (FEAT-404, W4.4).
+--
+-- Additive: `memories.archived` + `memories.archived_at` track archival
+-- state (default off / null on every existing row). Archival reuses the
+-- exact non-destructive bookkeeping supersede()/invalidate() already
+-- established (migration 006/007): valid_to is set, no row is ever
+-- deleted, and the transition is restorable — see
+-- src/storage/memory-events.ts MemoryEventRepo.archive/restore. Because
+-- archived memories get valid_to set, every existing `valid_to IS NULL`
+-- candidate filter (search.ts, recall/pack.ts) already excludes them for
+-- free; restore() clearing valid_to re-admits them for free too.
+--
+-- The memory_events.event_type CHECK constraint (migration 007) enumerates
+-- valid event types; SQLite CHECK constraints are immutable (see migration
+-- 003's create-copy-swap precedent), so widening it to add 'archive' and
+-- 'restore' requires the same table-rewrite pattern. memory_events has no
+-- FK dependents; it has two indexes (atom_seq from 007, the unique
+-- event_id index from 010 ADR-011) and gained `event_id` via ALTER TABLE
+-- ADD COLUMN in migration 010 — both are carried through explicitly below
+-- (an explicit column list on the INSERT, not `SELECT *`, so this doesn't
+-- silently depend on ADD COLUMN's physical append-at-end ordering).
+
+ALTER TABLE memories ADD COLUMN archived INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memories ADD COLUMN archived_at INTEGER;
+
+-- Serves the archival pass's candidate-selection query (archived = 0 AND
+-- valid_to IS NULL AND created_at < cutoff).
+CREATE INDEX idx_memories_archival_candidates ON memories(archived, valid_to, created_at);
+
+CREATE TABLE memory_events_new (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  event_type TEXT NOT NULL CHECK(event_type IN ('create', 'invalidate', 'supersede', 'promote_scope', 'erase_request', 'usefulness', 'archive', 'restore')),
+  atom_id TEXT NOT NULL,
+  payload_json TEXT,
+  content_hash TEXT,
+  created_at INTEGER NOT NULL,
+  synced_at INTEGER,
+  event_id TEXT
+);
+
+INSERT INTO memory_events_new (seq, event_type, atom_id, payload_json, content_hash, created_at, synced_at, event_id)
+SELECT seq, event_type, atom_id, payload_json, content_hash, created_at, synced_at, event_id FROM memory_events;
+
+DROP INDEX IF EXISTS idx_memory_events_atom_seq;
+DROP INDEX IF EXISTS idx_memory_events_event_id;
+DROP TABLE memory_events;
+ALTER TABLE memory_events_new RENAME TO memory_events;
+
+CREATE INDEX idx_memory_events_atom_seq ON memory_events (atom_id, seq);
+CREATE UNIQUE INDEX idx_memory_events_event_id ON memory_events (event_id);

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@astragenie/astramemory-local",
+  "version": "0.7.2",
+  "type": "module",
+  "bin": {
+    "astramem-local": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "migrations",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "dev": "tsc -w -p .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:smoke": "vitest run tests/smoke",
+    "contracts:validate": "node contracts/validate.mjs",
+    "prepublishOnly": "bun run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "trustedDependencies": [
+    "@napi-rs/keyring",
+    "better-sqlite3-multiple-ciphers"
+  ],
+  "dependencies": {
+    "@inquirer/prompts": "^8.5.2",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@napi-rs/keyring": "^1.3.0",
+    "better-sqlite3-multiple-ciphers": "^12.11.1",
+    "fastify": "^5.9.0",
+    "pino": "^10.3.1",
+    "pino-roll": "^4.0.0",
+    "sqlite-vec": "^0.1.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.9"
+  },
+  "license": "MIT"
+}