agent-working-memory 0.17.0 → 0.19.0

package/src/model-daemon.ts

@@ -0,0 +1,48 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Entry point of the shared model daemon (AWM_MODEL_DAEMON=1). Spawned detached by the
+ * first AWM process that finds no daemon for its fingerprint; see src/core/model-daemon.ts.
+ * It runs the same capped in-process functions an AWM process would run itself, and
+ * computes its fingerprint from the config those modules captured, as the client does.
+ */
+
+import { startModelDaemon } from './core/model-daemon-server.js';
+import { EXIT_FINGERPRINT_DRIFT, modelDaemonFingerprint } from './core/model-daemon.js';
+import { registeredInferenceConfig } from './core/ml-worker.js';
+import { inProcessEmbed, getEmbedder, EMBED_BATCH_SIZE } from './core/embeddings.js';
+import { inProcessRerank, getReranker } from './core/reranker.js';
+import { inProcessExpand, getExpander } from './core/query-expander.js';
+
+process.on('uncaughtException', err => {
+  console.error(`[model-daemon] uncaught: ${err?.stack ?? err}`);
+  process.exit(1);
+});
+
+const fingerprint = modelDaemonFingerprint(registeredInferenceConfig());
+const expected = process.env.AWM_MODEL_DAEMON_FINGERPRINT;
+if (expected && expected !== fingerprint) {
+  // The spawner's code or config is not this daemon's (it was rebuilt after the spawner
+  // started). Listening anyway would put a daemon on an address nobody asks for.
+  console.error(`[model-daemon] spawner expected fingerprint ${expected}, this code is ${fingerprint}: not starting`);
+  process.exit(EXIT_FINGERPRINT_DRIFT);
+}
+
+startModelDaemon({
+  fingerprint,
+  handlers: {
+    embed: args => inProcessEmbed(args),
+    rerank: args => inProcessRerank(args),
+    expand: args => inProcessExpand(args),
+    warm: async () => { await Promise.all([getEmbedder(), getReranker(), getExpander()]); },
+    embedChunk: EMBED_BATCH_SIZE,
+  },
+}).then(() => {
+  // Started by the client's launcher: tell it we listen, so it exits and stops being
+  // our parent (see LAUNCHER in model-daemon-client.ts).
+  process.send?.({ listening: true }, () => process.disconnect?.());
+}, err => {
+  // EADDRINUSE: another daemon for this fingerprint won the race. Nothing to do.
+  console.error(`[model-daemon] not started: ${(err as Error)?.message ?? err}`);
+  process.exit((err as NodeJS.ErrnoException)?.code === 'EADDRINUSE' ? 0 : 1);
+});

package/src/storage/factory.ts

@@ -38,6 +38,7 @@
 
 import { existsSync, statSync } from 'node:fs';
 import type { IEngramStore } from './store.js';
+import { assertNotLiveStoreUnderTest } from '../adapters/common.js';
 
 export type StoreBackend = 'sqlite' | 'pglite' | 'postgres';
 
@@ -49,25 +50,25 @@ export type StoreBackend = 'sqlite' | 'pglite' | 'postgres';
 function detectBackendFromDisk(): StoreBackend | null {
   // If AWM_DB_PATH is set, infer from its shape.
   const explicitPath = process.env.AWM_DB_PATH;
-  if (explicitPath) {
-    if (existsSync(explicitPath)) {
-      try {
-        const stat = statSync(explicitPath);
-        if (stat.isDirectory()) return 'pglite'; // PGlite uses a directory
-        if (stat.isFile()) return 'sqlite';      // SQLite is a single file
-      } catch { /* fall through to the default below */ }
-    }
-    // The caller named a path that does not exist yet — a brand-new store. Default it to
-    // SQLite and STOP: falling through to the cwd conventions below would pick the backend
-    // from files that have nothing to do with the path that was asked for.
-    //
-    // Not hypothetical. Running from a checkout containing a `memory-pglite/` directory
-    // made a fresh AWM_DB_PATH=/tmp/new-store.db resolve to PGlite, which is
-    // single-process — so two surfaces pointed at 'the same store' would have had the
-    // second refuse to start. Found by the cross-surface end-to-end test.
-    // PGlite at a new path is still reachable via AWM_STORE_BACKEND=pglite.
-    return 'sqlite';
-  }
+  if (explicitPath) {
+    if (existsSync(explicitPath)) {
+      try {
+        const stat = statSync(explicitPath);
+        if (stat.isDirectory()) return 'pglite'; // PGlite uses a directory
+        if (stat.isFile()) return 'sqlite';      // SQLite is a single file
+      } catch { /* fall through to the default below */ }
+    }
+    // The caller named a path that does not exist yet — a brand-new store. Default it to
+    // SQLite and STOP: falling through to the cwd conventions below would pick the backend
+    // from files that have nothing to do with the path that was asked for.
+    //
+    // Not hypothetical. Running from a checkout containing a `memory-pglite/` directory
+    // made a fresh AWM_DB_PATH=/tmp/new-store.db resolve to PGlite, which is
+    // single-process — so two surfaces pointed at 'the same store' would have had the
+    // second refuse to start. Found by the cross-surface end-to-end test.
+    // PGlite at a new path is still reachable via AWM_STORE_BACKEND=pglite.
+    return 'sqlite';
+  }
 
   // Otherwise look for the conventional defaults in cwd.
   // PGlite directory wins over SQLite file when both exist — assume the
@@ -148,6 +149,11 @@ export async function openStore(): Promise<{
   const backend = getConfiguredBackend();
   const path = getConfiguredPath();
 
+  // A-3 (2026-10-12): a harness must not OPEN the live store. Placed here, at the one
+  // place production creates a store, rather than in resolveDbPath — computing a path
+  // string is harmless, opening the file is what writes.
+  assertNotLiveStoreUnderTest(path);
+
   // The on-disk mismatch warning only applies to file/dir backends.
   if (backend !== 'postgres') warnIfBackendDisagreesWithDisk(backend, path);
 

package/src/storage/pglite-schema.ts

@@ -1,193 +1,199 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * PGlite schema DDL — translated from the SQLite schema in sqlite.ts:init().
- *
- * Translation notes:
- *   - SQLite TEXT → Postgres TEXT
- *   - SQLite REAL → Postgres DOUBLE PRECISION
- *   - SQLite INTEGER (0/1 booleans) → Postgres BOOLEAN
- *   - SQLite BLOB embedding → pgvector VECTOR(384) (native)
- *   - SQLite FTS5 virtual table + triggers → Postgres tsvector column with
- *     a GIN index, kept up-to-date via a BEFORE INSERT/UPDATE trigger.
- *
- * All tables and indexes use IF NOT EXISTS so re-running is idempotent.
- *
- * The vector extension MUST be loaded before this schema runs:
- *   await db.exec('CREATE EXTENSION IF NOT EXISTS vector')
- * PGlite's vector extension does this automatically when imported.
- */
-
-export const PGLITE_VECTOR_DIMENSIONS = parseInt(process.env.AWM_EMBED_DIMS ?? '384', 10);
-
-export const PGLITE_SCHEMA_DDL = `
-  CREATE EXTENSION IF NOT EXISTS vector;
-
-  CREATE TABLE IF NOT EXISTS engrams (
-    id                   TEXT PRIMARY KEY,
-    agent_id             TEXT NOT NULL,
-    concept              TEXT NOT NULL,
-    content              TEXT NOT NULL,
-    embedding            VECTOR(${PGLITE_VECTOR_DIMENSIONS}),
-    embedding_model      TEXT,
-    confidence           DOUBLE PRECISION NOT NULL DEFAULT 0.5,
-    salience             DOUBLE PRECISION NOT NULL DEFAULT 0.5,
-    access_count         INTEGER NOT NULL DEFAULT 0,
-    last_accessed        TEXT NOT NULL,
-    created_at           TEXT NOT NULL,
-    salience_features    TEXT NOT NULL DEFAULT '{}',
-    reason_codes         TEXT NOT NULL DEFAULT '[]',
-    stage                TEXT NOT NULL DEFAULT 'active',
-    ttl                  INTEGER,
-    retracted            BOOLEAN NOT NULL DEFAULT FALSE,
-    retracted_by         TEXT,
-    retracted_at         TEXT,
-    tags                 TEXT NOT NULL DEFAULT '[]',
-    memory_type          TEXT NOT NULL DEFAULT 'unclassified',
-    memory_class         TEXT NOT NULL DEFAULT 'working',
-    superseded_by        TEXT,
-    supersedes           TEXT,
-    episode_id           TEXT,
-    task_status          TEXT,
-    task_priority        TEXT,
-    blocked_by           TEXT,
-    sequence             INTEGER,
-    references_json      TEXT,
-    origin_class         TEXT,
-    writer_session       TEXT,
-    recipe_id            TEXT,
-    valid_from           TEXT,
-    valid_to             TEXT,
-    fts                  TSVECTOR
-  );
-
-  -- Memory-spine migration (D5/D8, 2026-07-30): idempotent column adds so
-  -- pre-existing stores gain provenance + temporal-validity fields.
-  ALTER TABLE engrams ADD COLUMN IF NOT EXISTS origin_class   TEXT;
-  ALTER TABLE engrams ADD COLUMN IF NOT EXISTS writer_session TEXT;
-  ALTER TABLE engrams ADD COLUMN IF NOT EXISTS recipe_id      TEXT;
-  ALTER TABLE engrams ADD COLUMN IF NOT EXISTS valid_from     TEXT;
-  ALTER TABLE engrams ADD COLUMN IF NOT EXISTS valid_to       TEXT;
-
-  CREATE INDEX IF NOT EXISTS idx_engrams_agent           ON engrams(agent_id);
-  CREATE INDEX IF NOT EXISTS idx_engrams_stage           ON engrams(agent_id, stage);
-  CREATE INDEX IF NOT EXISTS idx_engrams_concept         ON engrams(concept);
-  CREATE INDEX IF NOT EXISTS idx_engrams_retracted       ON engrams(agent_id, retracted);
-  CREATE INDEX IF NOT EXISTS idx_engrams_task            ON engrams(agent_id, task_status);
-  CREATE INDEX IF NOT EXISTS idx_engrams_agent_sequence  ON engrams(agent_id, sequence) WHERE sequence IS NOT NULL;
-  CREATE INDEX IF NOT EXISTS idx_engrams_fts             ON engrams USING GIN(fts);
-
-  CREATE INDEX IF NOT EXISTS idx_engrams_embedding
-    ON engrams USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
-
-  CREATE OR REPLACE FUNCTION engrams_fts_update() RETURNS TRIGGER AS $$
-  BEGIN
-    NEW.fts := to_tsvector('english',
-      COALESCE(NEW.concept, '') || ' ' ||
-      COALESCE(NEW.content, '') || ' ' ||
-      COALESCE(NEW.tags, ''));
-    RETURN NEW;
-  END;
-  $$ LANGUAGE plpgsql;
-
-  DROP TRIGGER IF EXISTS engrams_fts_trigger ON engrams;
-  CREATE TRIGGER engrams_fts_trigger
-    BEFORE INSERT OR UPDATE OF concept, content, tags ON engrams
-    FOR EACH ROW EXECUTE FUNCTION engrams_fts_update();
-
-  CREATE TABLE IF NOT EXISTS associations (
-    id                TEXT PRIMARY KEY,
-    from_engram_id    TEXT NOT NULL REFERENCES engrams(id) ON DELETE CASCADE,
-    to_engram_id      TEXT NOT NULL REFERENCES engrams(id) ON DELETE CASCADE,
-    weight            DOUBLE PRECISION NOT NULL DEFAULT 0.1,
-    confidence        DOUBLE PRECISION NOT NULL DEFAULT 0.5,
-    type              TEXT NOT NULL DEFAULT 'hebbian',
-    activation_count  INTEGER NOT NULL DEFAULT 0,
-    created_at        TEXT NOT NULL,
-    last_activated    TEXT NOT NULL
-  );
-
-  CREATE INDEX IF NOT EXISTS idx_assoc_from        ON associations(from_engram_id);
-  CREATE INDEX IF NOT EXISTS idx_assoc_to          ON associations(to_engram_id);
-  CREATE UNIQUE INDEX IF NOT EXISTS idx_assoc_pair ON associations(from_engram_id, to_engram_id);
-
-  CREATE TABLE IF NOT EXISTS agents (
-    id          TEXT PRIMARY KEY,
-    name        TEXT NOT NULL,
-    created_at  TEXT NOT NULL,
-    config      TEXT NOT NULL DEFAULT '{}'
-  );
-
-  CREATE TABLE IF NOT EXISTS activation_events (
-    id                 TEXT PRIMARY KEY,
-    agent_id           TEXT NOT NULL,
-    timestamp          TEXT NOT NULL,
-    context            TEXT NOT NULL,
-    results_returned   INTEGER NOT NULL,
-    top_score          DOUBLE PRECISION,
-    latency_ms         DOUBLE PRECISION NOT NULL,
-    engram_ids         TEXT NOT NULL DEFAULT '[]'
-  );
-
-  CREATE TABLE IF NOT EXISTS staging_events (
-    engram_id        TEXT NOT NULL,
-    agent_id         TEXT NOT NULL,
-    action           TEXT NOT NULL,
-    resonance_score  DOUBLE PRECISION,
-    timestamp        TEXT NOT NULL,
-    age_ms           INTEGER NOT NULL
-  );
-
-  CREATE TABLE IF NOT EXISTS retrieval_feedback (
-    id                   TEXT PRIMARY KEY,
-    activation_event_id  TEXT,
-    engram_id            TEXT NOT NULL,
-    useful               BOOLEAN NOT NULL,
-    context              TEXT,
-    timestamp            TEXT NOT NULL
-  );
-
-  CREATE TABLE IF NOT EXISTS episodes (
-    id             TEXT PRIMARY KEY,
-    agent_id       TEXT NOT NULL,
-    label          TEXT NOT NULL,
-    embedding      VECTOR(${PGLITE_VECTOR_DIMENSIONS}),
-    engram_count   INTEGER NOT NULL DEFAULT 0,
-    start_time     TEXT NOT NULL,
-    end_time       TEXT NOT NULL,
-    created_at     TEXT NOT NULL
-  );
-
-  CREATE INDEX IF NOT EXISTS idx_episodes_agent ON episodes(agent_id);
-  CREATE INDEX IF NOT EXISTS idx_episodes_time  ON episodes(agent_id, end_time);
-
-  CREATE TABLE IF NOT EXISTS conscious_state (
-    agent_id                            TEXT PRIMARY KEY,
-    last_write_id                       TEXT,
-    last_recall_context                 TEXT,
-    last_recall_ids                     TEXT NOT NULL DEFAULT '[]',
-    last_activity_at                    TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')),
-    write_count_since_consolidation     INTEGER NOT NULL DEFAULT 0,
-    recall_count_since_consolidation    INTEGER NOT NULL DEFAULT 0,
-    execution_state                     TEXT,
-    checkpoint_at                       TEXT,
-    last_consolidation_at               TEXT,
-    last_mini_consolidation_at          TEXT,
-    consolidation_cycle_count           INTEGER NOT NULL DEFAULT 0,
-    updated_at                          TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))
-  );
-
-  CREATE TABLE IF NOT EXISTS entity_mentions (
-    entity    TEXT NOT NULL,
-    engram_id TEXT NOT NULL,
-    agent_id  TEXT NOT NULL,
-    PRIMARY KEY (entity, engram_id)
-  );
-
-  CREATE INDEX IF NOT EXISTS idx_entity_mentions_agent ON entity_mentions(agent_id, entity);
-
-  CREATE TABLE IF NOT EXISTS entity_aliases (
-    alias  TEXT PRIMARY KEY,
-    entity TEXT NOT NULL
-  );
-`;
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * PGlite schema DDL — translated from the SQLite schema in sqlite.ts:init().
+ *
+ * Translation notes:
+ *   - SQLite TEXT → Postgres TEXT
+ *   - SQLite REAL → Postgres DOUBLE PRECISION
+ *   - SQLite INTEGER (0/1 booleans) → Postgres BOOLEAN
+ *   - SQLite BLOB embedding → pgvector VECTOR(384) (native)
+ *   - SQLite FTS5 virtual table + triggers → Postgres tsvector column with
+ *     a GIN index, kept up-to-date via a BEFORE INSERT/UPDATE trigger.
+ *
+ * All tables and indexes use IF NOT EXISTS so re-running is idempotent.
+ *
+ * The vector extension MUST be loaded before this schema runs:
+ *   await db.exec('CREATE EXTENSION IF NOT EXISTS vector')
+ * PGlite's vector extension does this automatically when imported.
+ */
+
+export const PGLITE_VECTOR_DIMENSIONS = parseInt(process.env.AWM_EMBED_DIMS ?? '384', 10);
+
+export const PGLITE_SCHEMA_DDL = `
+  CREATE EXTENSION IF NOT EXISTS vector;
+
+  CREATE TABLE IF NOT EXISTS engrams (
+    id                   TEXT PRIMARY KEY,
+    agent_id             TEXT NOT NULL,
+    concept              TEXT NOT NULL,
+    content              TEXT NOT NULL,
+    embedding            VECTOR(${PGLITE_VECTOR_DIMENSIONS}),
+    embedding_model      TEXT,
+    confidence           DOUBLE PRECISION NOT NULL DEFAULT 0.5,
+    salience             DOUBLE PRECISION NOT NULL DEFAULT 0.5,
+    access_count         INTEGER NOT NULL DEFAULT 0,
+    last_accessed        TEXT NOT NULL,
+    created_at           TEXT NOT NULL,
+    salience_features    TEXT NOT NULL DEFAULT '{}',
+    reason_codes         TEXT NOT NULL DEFAULT '[]',
+    stage                TEXT NOT NULL DEFAULT 'active',
+    ttl                  INTEGER,
+    retracted            BOOLEAN NOT NULL DEFAULT FALSE,
+    retracted_by         TEXT,
+    retracted_at         TEXT,
+    tags                 TEXT NOT NULL DEFAULT '[]',
+    memory_type          TEXT NOT NULL DEFAULT 'unclassified',
+    memory_class         TEXT NOT NULL DEFAULT 'working',
+    superseded_by        TEXT,
+    supersedes           TEXT,
+    episode_id           TEXT,
+    task_status          TEXT,
+    task_priority        TEXT,
+    blocked_by           TEXT,
+    sequence             INTEGER,
+    references_json      TEXT,
+    origin_class         TEXT,
+    writer_session       TEXT,
+    recipe_id            TEXT,
+    valid_from           TEXT,
+    valid_to             TEXT,
+    stage_changed_at     TEXT,
+    fts                  TSVECTOR
+  );
+
+  -- Memory-spine migration (D5/D8, 2026-07-30): idempotent column adds so
+  -- pre-existing stores gain provenance + temporal-validity fields.
+  ALTER TABLE engrams ADD COLUMN IF NOT EXISTS origin_class   TEXT;
+  ALTER TABLE engrams ADD COLUMN IF NOT EXISTS writer_session TEXT;
+  ALTER TABLE engrams ADD COLUMN IF NOT EXISTS recipe_id      TEXT;
+  ALTER TABLE engrams ADD COLUMN IF NOT EXISTS valid_from     TEXT;
+  ALTER TABLE engrams ADD COLUMN IF NOT EXISTS valid_to       TEXT;
+
+  -- Stage-transition timestamp (A-4, 2026-10-12). Nullable with no backfill:
+  -- null means the engram has never changed stage, so readers fall back to
+  -- created_at. See Engram.stageChangedAt for why it exists.
+  ALTER TABLE engrams ADD COLUMN IF NOT EXISTS stage_changed_at TEXT;
+
+  CREATE INDEX IF NOT EXISTS idx_engrams_agent           ON engrams(agent_id);
+  CREATE INDEX IF NOT EXISTS idx_engrams_stage           ON engrams(agent_id, stage);
+  CREATE INDEX IF NOT EXISTS idx_engrams_concept         ON engrams(concept);
+  CREATE INDEX IF NOT EXISTS idx_engrams_retracted       ON engrams(agent_id, retracted);
+  CREATE INDEX IF NOT EXISTS idx_engrams_task            ON engrams(agent_id, task_status);
+  CREATE INDEX IF NOT EXISTS idx_engrams_agent_sequence  ON engrams(agent_id, sequence) WHERE sequence IS NOT NULL;
+  CREATE INDEX IF NOT EXISTS idx_engrams_fts             ON engrams USING GIN(fts);
+
+  CREATE INDEX IF NOT EXISTS idx_engrams_embedding
+    ON engrams USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
+
+  CREATE OR REPLACE FUNCTION engrams_fts_update() RETURNS TRIGGER AS $$
+  BEGIN
+    NEW.fts := to_tsvector('english',
+      COALESCE(NEW.concept, '') || ' ' ||
+      COALESCE(NEW.content, '') || ' ' ||
+      COALESCE(NEW.tags, ''));
+    RETURN NEW;
+  END;
+  $$ LANGUAGE plpgsql;
+
+  DROP TRIGGER IF EXISTS engrams_fts_trigger ON engrams;
+  CREATE TRIGGER engrams_fts_trigger
+    BEFORE INSERT OR UPDATE OF concept, content, tags ON engrams
+    FOR EACH ROW EXECUTE FUNCTION engrams_fts_update();
+
+  CREATE TABLE IF NOT EXISTS associations (
+    id                TEXT PRIMARY KEY,
+    from_engram_id    TEXT NOT NULL REFERENCES engrams(id) ON DELETE CASCADE,
+    to_engram_id      TEXT NOT NULL REFERENCES engrams(id) ON DELETE CASCADE,
+    weight            DOUBLE PRECISION NOT NULL DEFAULT 0.1,
+    confidence        DOUBLE PRECISION NOT NULL DEFAULT 0.5,
+    type              TEXT NOT NULL DEFAULT 'hebbian',
+    activation_count  INTEGER NOT NULL DEFAULT 0,
+    created_at        TEXT NOT NULL,
+    last_activated    TEXT NOT NULL
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_assoc_from        ON associations(from_engram_id);
+  CREATE INDEX IF NOT EXISTS idx_assoc_to          ON associations(to_engram_id);
+  CREATE UNIQUE INDEX IF NOT EXISTS idx_assoc_pair ON associations(from_engram_id, to_engram_id);
+
+  CREATE TABLE IF NOT EXISTS agents (
+    id          TEXT PRIMARY KEY,
+    name        TEXT NOT NULL,
+    created_at  TEXT NOT NULL,
+    config      TEXT NOT NULL DEFAULT '{}'
+  );
+
+  CREATE TABLE IF NOT EXISTS activation_events (
+    id                 TEXT PRIMARY KEY,
+    agent_id           TEXT NOT NULL,
+    timestamp          TEXT NOT NULL,
+    context            TEXT NOT NULL,
+    results_returned   INTEGER NOT NULL,
+    top_score          DOUBLE PRECISION,
+    latency_ms         DOUBLE PRECISION NOT NULL,
+    engram_ids         TEXT NOT NULL DEFAULT '[]'
+  );
+
+  CREATE TABLE IF NOT EXISTS staging_events (
+    engram_id        TEXT NOT NULL,
+    agent_id         TEXT NOT NULL,
+    action           TEXT NOT NULL,
+    resonance_score  DOUBLE PRECISION,
+    timestamp        TEXT NOT NULL,
+    age_ms           INTEGER NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS retrieval_feedback (
+    id                   TEXT PRIMARY KEY,
+    activation_event_id  TEXT,
+    engram_id            TEXT NOT NULL,
+    useful               BOOLEAN NOT NULL,
+    context              TEXT,
+    timestamp            TEXT NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS episodes (
+    id             TEXT PRIMARY KEY,
+    agent_id       TEXT NOT NULL,
+    label          TEXT NOT NULL,
+    embedding      VECTOR(${PGLITE_VECTOR_DIMENSIONS}),
+    engram_count   INTEGER NOT NULL DEFAULT 0,
+    start_time     TEXT NOT NULL,
+    end_time       TEXT NOT NULL,
+    created_at     TEXT NOT NULL
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_episodes_agent ON episodes(agent_id);
+  CREATE INDEX IF NOT EXISTS idx_episodes_time  ON episodes(agent_id, end_time);
+
+  CREATE TABLE IF NOT EXISTS conscious_state (
+    agent_id                            TEXT PRIMARY KEY,
+    last_write_id                       TEXT,
+    last_recall_context                 TEXT,
+    last_recall_ids                     TEXT NOT NULL DEFAULT '[]',
+    last_activity_at                    TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')),
+    write_count_since_consolidation     INTEGER NOT NULL DEFAULT 0,
+    recall_count_since_consolidation    INTEGER NOT NULL DEFAULT 0,
+    execution_state                     TEXT,
+    checkpoint_at                       TEXT,
+    last_consolidation_at               TEXT,
+    last_mini_consolidation_at          TEXT,
+    consolidation_cycle_count           INTEGER NOT NULL DEFAULT 0,
+    updated_at                          TEXT NOT NULL DEFAULT (to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))
+  );
+
+  CREATE TABLE IF NOT EXISTS entity_mentions (
+    entity    TEXT NOT NULL,
+    engram_id TEXT NOT NULL,
+    agent_id  TEXT NOT NULL,
+    PRIMARY KEY (entity, engram_id)
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_entity_mentions_agent ON entity_mentions(agent_id, entity);
+
+  CREATE TABLE IF NOT EXISTS entity_aliases (
+    alias  TEXT PRIMARY KEY,
+    entity TEXT NOT NULL
+  );
+`;