emocentric 0.1.0

package/dist/postgres/create-instance.js

@@ -0,0 +1,182 @@
+import pg from "pg";
+import { Agent } from "../agent.js";
+import { generateEventId } from "../events/context-event.js";
+import { compileActions, } from "../blueprint/blueprint.js";
+import { instanceKey } from "../blueprint/scope.js";
+import { PostgresMemoryStore } from "./store.js";
+import { PostgresEmotionalState } from "./emotional-state.js";
+import { PostgresShortTermMemory } from "./short-term.js";
+import { claimInstance, releaseInstance } from "./instances.js";
+/**
+ * Process-level registry of live instances, keyed by instanceKey. Holds the
+ * in-flight Promise (not the resolved value) so two simultaneous first-calls
+ * for the same id share ONE build instead of racing two objects into being.
+ * This is what lets the same id return the SAME in-memory object — the
+ * prerequisite for any per-instance state (a request queue, caches) to work.
+ */
+const registry = new Map();
+/**
+ * Forget every cached instance. Does NOT close pools (you own those) — it
+ * just empties the in-memory lookup so the next `createAgentInstance` rebuilds
+ * from the database. Blunt: for tests and full teardown only — to drop a
+ * single edited instance use {@link forgetInstance}.
+ */
+export function clearInstanceRegistry() {
+    registry.clear();
+}
+/**
+ * Forget ONE instance from the registry. The next `createAgentInstance` for
+ * that id rebuilds it from the database — picking up an edited blueprint
+ * (new persona, model, actions) that the cached object was frozen with. Every
+ * other instance is untouched. Returns true if an entry was removed.
+ *
+ * Call this when the instance is IDLE — e.g. after a blueprint edit, between
+ * events. Forgetting one that has a queued or in-flight heartbeat transiently
+ * splits its queue (the running heartbeat keeps the old object while new
+ * events build a fresh one), reopening the serialization the registry exists
+ * to provide.
+ */
+export function forgetInstance(scope) {
+    return registry.delete(instanceKey(scope));
+}
+/**
+ * Forget every cached instance of a blueprint — all its users and sessions —
+ * so the next `createAgentInstance` for any of them rebuilds from the
+ * database, applying an edited blueprint (new persona, model, actions). Other
+ * blueprints are untouched. Returns how many instances were forgotten. Same
+ * idle caveat as {@link forgetInstance}: forgetting an instance mid-heartbeat
+ * transiently splits its queue.
+ */
+export function forgetBlueprint(blueprintId) {
+    const prefix = encodeURIComponent(blueprintId) + "/";
+    let forgotten = 0;
+    for (const key of [...registry.keys()]) {
+        if (key.startsWith(prefix)) {
+            registry.delete(key);
+            forgotten++;
+        }
+    }
+    return forgotten;
+}
+/**
+ * The one-call entry point: blueprint + user → that user's instance, as a
+ * shared live object.
+ *
+ * - **Omit `userId`** to MINT a new instance: a fresh id is generated, the
+ *   instance is birthed, and you read the id back off `result.scope.userId`
+ *   to address it later. (Same rule will extend to `sessionId`.)
+ * - **Pass a `userId`** to GET that instance: the first call this process
+ *   makes for an id builds it (birthing it in the DB on true first contact,
+ *   or attaching to existing persistent state otherwise) and caches the live
+ *   object; every later call with the same id returns that **same object**.
+ *
+ * Births write seed facts and claim a directory row exactly once; lived state
+ * is never re-seeded. Two ids share nothing. Pass one shared `pool` you own
+ * (recommended) — then per-instance `close()` only forgets the cache entry;
+ * you end the pool yourself at shutdown.
+ */
+export async function createAgentInstance(options) {
+    const scope = {
+        blueprintId: options.blueprint.id,
+        userId: options.userId ?? generateEventId(),
+        ...(options.sessionId !== undefined && { sessionId: options.sessionId }),
+    };
+    const key = instanceKey(scope); // validates the scope before any I/O
+    const existing = registry.get(key);
+    if (existing)
+        return existing;
+    // Wrap the build so the instance's close() also evicts THIS promise from
+    // the registry (only if the slot still points here — a rebuild after a
+    // clear must not be clobbered by a stale close).
+    const building = buildInstance(options, scope, key).then((instance) => {
+        const poolClose = instance.close;
+        instance.close = async () => {
+            if (registry.get(key) === building)
+                registry.delete(key);
+            await poolClose();
+        };
+        return instance;
+    });
+    registry.set(key, building);
+    // A failed build must not poison the slot: forget it so a later call retries.
+    building.catch(() => {
+        if (registry.get(key) === building)
+            registry.delete(key);
+    });
+    return building;
+}
+/** Construct one instance from scratch (no registry lookup). */
+async function buildInstance(options, scope, key) {
+    const { blueprint } = options;
+    let pool;
+    let ownsPool;
+    if (options.pool) {
+        pool = options.pool;
+        ownsPool = false;
+    }
+    else {
+        const connectionString = options.connectionString ?? process.env.DATABASE_URL;
+        if (!connectionString) {
+            throw new Error("createAgentInstance needs a `connectionString` (or DATABASE_URL env var) or an existing `pool`.");
+        }
+        pool = new pg.Pool({
+            connectionString,
+            ...(options.ssl !== undefined && { ssl: options.ssl }),
+        });
+        ownsPool = true;
+    }
+    const memory = new PostgresMemoryStore({
+        pool,
+        scope,
+        ...(options.embedder !== undefined && { embedder: options.embedder }),
+    });
+    const emotions = new PostgresEmotionalState({
+        pool,
+        scope,
+        persona: blueprint.persona,
+        ...(blueprint.emotions !== undefined && { emotions: blueprint.emotions }),
+    });
+    const shortTermMemory = new PostgresShortTermMemory({ pool, scope });
+    const created = await claimInstance(pool, scope, blueprint.version);
+    if (created && blueprint.seedFacts !== undefined && blueprint.seedFacts.length > 0) {
+        try {
+            await memory.add(blueprint.seedFacts);
+        }
+        catch (error) {
+            // Give back the claim so a retry re-seeds instead of skipping.
+            await releaseInstance(pool, scope);
+            if (ownsPool)
+                await pool.end();
+            throw error;
+        }
+    }
+    const agent = new Agent({
+        llm: options.llm,
+        memory,
+        emotions,
+        shortTermMemory,
+        actions: compileActions(blueprint.actions, options.executors),
+        persona: blueprint.persona,
+        ...options.overrides,
+    });
+    let closed = false;
+    return {
+        agent,
+        enqueue: (event) => agent.enqueue(event),
+        scope,
+        key,
+        created,
+        memory,
+        emotions,
+        shortTermMemory,
+        // Pool teardown only; createAgentInstance wraps this to also evict from
+        // the registry. Idempotent — a shared object may be closed more than once.
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            if (ownsPool)
+                await pool.end();
+        },
+    };
+}

package/dist/postgres/emotional-state.d.ts

@@ -0,0 +1,42 @@
+import pg from "pg";
+import { type EmotionDefinition, type EmotionDelta, type EmotionSnapshot } from "../emotion/definitions.js";
+import { type Persona } from "../emotion/persona.js";
+import { type EmotionEntry, type EmotionalState } from "../emotion/state.js";
+import { type InstanceScope } from "../blueprint/scope.js";
+export interface PostgresEmotionalStateOptions {
+    /** e.g. process.env.DATABASE_URL. Either this or `pool` is required. */
+    connectionString?: string;
+    /** Bring your own pg Pool (the store will not close it). */
+    pool?: pg.Pool;
+    ssl?: pg.PoolConfig["ssl"];
+    /** Which instance's feelings this is. One database serves many
+     * instances; every query is filtered by this scope's key. */
+    scope: InstanceScope;
+    /** The palette. Default DEFAULT_EMOTIONS. */
+    emotions?: readonly EmotionDefinition[];
+    /** Temperament (sensitivity/baseline overrides) is merged into the
+     * palette; summary/dispositions are used by the appraiser, not here. */
+    persona?: Persona;
+}
+/**
+ * Persistent emotional state: one Postgres row per slider per instance, so
+ * feelings survive restarts and deploys. Rows are seeded from baselines on
+ * first use; emotions added to the palette later get seeded on next startup
+ * while existing values are left untouched.
+ */
+export declare class PostgresEmotionalState implements EmotionalState {
+    private readonly pool;
+    private readonly ownsPool;
+    private readonly instanceKey;
+    private readonly defs;
+    private ready;
+    constructor(options: PostgresEmotionalStateOptions);
+    definitions(): EmotionDefinition[];
+    snapshot(): Promise<EmotionSnapshot>;
+    entries(): Promise<EmotionEntry[]>;
+    set(values: Partial<EmotionSnapshot>, at?: string): Promise<EmotionSnapshot>;
+    applyDeltas(deltas: EmotionDelta[]): Promise<EmotionSnapshot>;
+    close(): Promise<void>;
+    private ensureReady;
+    private migrate;
+}

package/dist/postgres/emotional-state.js

@@ -0,0 +1,134 @@
+import pg from "pg";
+import { DEFAULT_EMOTIONS, } from "../emotion/definitions.js";
+import { applyTemperament } from "../emotion/persona.js";
+import { projectDeltas, } from "../emotion/state.js";
+import { clamp01 } from "../memory/scoring.js";
+import { instanceKey } from "../blueprint/scope.js";
+import { EMOTIONS_SCHEMA } from "./schema.js";
+/**
+ * Persistent emotional state: one Postgres row per slider per instance, so
+ * feelings survive restarts and deploys. Rows are seeded from baselines on
+ * first use; emotions added to the palette later get seeded on next startup
+ * while existing values are left untouched.
+ */
+export class PostgresEmotionalState {
+    pool;
+    ownsPool;
+    instanceKey;
+    defs;
+    ready;
+    constructor(options) {
+        if (options.pool) {
+            this.pool = options.pool;
+            this.ownsPool = false;
+        }
+        else {
+            const connectionString = options.connectionString ?? process.env.DATABASE_URL;
+            if (!connectionString) {
+                throw new Error("PostgresEmotionalState needs a `connectionString` (or DATABASE_URL env var) or an existing `pool`.");
+            }
+            this.pool = new pg.Pool({
+                connectionString,
+                ...(options.ssl !== undefined && { ssl: options.ssl }),
+            });
+            this.ownsPool = true;
+        }
+        this.instanceKey = instanceKey(options.scope);
+        this.defs = applyTemperament(options.emotions ?? DEFAULT_EMOTIONS, options.persona);
+        if (this.defs.length === 0) {
+            throw new Error("PostgresEmotionalState needs at least one emotion.");
+        }
+    }
+    definitions() {
+        return this.defs.map((d) => ({ ...d }));
+    }
+    async snapshot() {
+        await this.ensureReady();
+        const { rows } = await this.pool.query(`SELECT emotion, value FROM emocentric_emotions WHERE instance_key = $1`, [this.instanceKey]);
+        const stored = new Map(rows.map((r) => [r.emotion, r.value]));
+        // Snapshot is shaped by the palette: emotions no longer in it are
+        // omitted; palette emotions missing a row fall back to baseline.
+        const snapshot = {};
+        for (const def of this.defs) {
+            snapshot[def.name] = stored.get(def.name) ?? def.baseline;
+        }
+        return snapshot;
+    }
+    async entries() {
+        await this.ensureReady();
+        const { rows } = await this.pool.query(`SELECT emotion, value, updated_at FROM emocentric_emotions WHERE instance_key = $1`, [this.instanceKey]);
+        const stored = new Map(rows.map((r) => [r.emotion, r]));
+        const nowIso = new Date().toISOString();
+        return this.defs.map((def) => {
+            const row = stored.get(def.name);
+            return row
+                ? {
+                    name: def.name,
+                    value: row.value,
+                    updatedAt: row.updated_at.toISOString(),
+                }
+                : { name: def.name, value: def.baseline, updatedAt: nowIso };
+        });
+    }
+    async set(values, at) {
+        await this.ensureReady();
+        const known = new Set(this.defs.map((d) => d.name));
+        const stamp = at ?? new Date().toISOString();
+        const names = [];
+        const clamped = [];
+        for (const [name, value] of Object.entries(values)) {
+            if (!known.has(name) || typeof value !== "number")
+                continue;
+            names.push(name);
+            clamped.push(clamp01(value));
+        }
+        if (names.length > 0) {
+            // One multi-row upsert instead of a query per slider: the whole write
+            // lands atomically and in a single round-trip.
+            await this.pool.query(`INSERT INTO emocentric_emotions (instance_key, emotion, value, updated_at)
+         SELECT $1, t.emotion, t.value, $2::timestamptz
+         FROM unnest($3::text[], $4::real[]) AS t(emotion, value)
+         ON CONFLICT (instance_key, emotion)
+         DO UPDATE SET value = EXCLUDED.value, updated_at = EXCLUDED.updated_at`, [this.instanceKey, stamp, names, clamped]);
+        }
+        return this.snapshot();
+    }
+    async applyDeltas(deltas) {
+        const before = await this.snapshot();
+        const after = projectDeltas(before, deltas, this.defs);
+        const touched = this.defs
+            .map((d) => d.name)
+            .filter((name) => after[name] !== before[name]);
+        if (touched.length > 0) {
+            const now = new Date().toISOString();
+            for (const name of touched) {
+                await this.pool.query(`INSERT INTO emocentric_emotions (instance_key, emotion, value, updated_at)
+           VALUES ($1, $2, $3, $4)
+           ON CONFLICT (instance_key, emotion)
+           DO UPDATE SET value = EXCLUDED.value, updated_at = EXCLUDED.updated_at`, [this.instanceKey, name, after[name], now]);
+            }
+        }
+        return after;
+    }
+    async close() {
+        if (this.ownsPool)
+            await this.pool.end();
+    }
+    ensureReady() {
+        if (!this.ready) {
+            this.ready = this.migrate().catch((error) => {
+                this.ready = undefined;
+                throw error;
+            });
+        }
+        return this.ready;
+    }
+    async migrate() {
+        await this.pool.query(EMOTIONS_SCHEMA);
+        for (const def of this.defs) {
+            await this.pool.query(`INSERT INTO emocentric_emotions (instance_key, emotion, value)
+         VALUES ($1, $2, $3)
+         ON CONFLICT (instance_key, emotion) DO NOTHING`, [this.instanceKey, def.name, def.baseline]);
+        }
+    }
+}

package/dist/postgres/index.d.ts

@@ -0,0 +1,5 @@
+export { PostgresMemoryStore, type PostgresMemoryStoreOptions, type ReembedAllOptions, } from "./store.js";
+export { PostgresEmotionalState, type PostgresEmotionalStateOptions, } from "./emotional-state.js";
+export { PostgresShortTermMemory, type PostgresShortTermMemoryOptions, } from "./short-term.js";
+export { claimInstance, deleteInstance, listInstances, type InstanceRecord, } from "./instances.js";
+export { createAgentInstance, clearInstanceRegistry, forgetInstance, forgetBlueprint, type AgentInstance, type CreateAgentInstanceOptions, } from "./create-instance.js";

package/dist/postgres/index.js

@@ -0,0 +1,5 @@
+export { PostgresMemoryStore, } from "./store.js";
+export { PostgresEmotionalState, } from "./emotional-state.js";
+export { PostgresShortTermMemory, } from "./short-term.js";
+export { claimInstance, deleteInstance, listInstances, } from "./instances.js";
+export { createAgentInstance, clearInstanceRegistry, forgetInstance, forgetBlueprint, } from "./create-instance.js";

package/dist/postgres/instances.d.ts

@@ -0,0 +1,32 @@
+import pg from "pg";
+import { type InstanceScope } from "../blueprint/scope.js";
+/** One row of the instance directory: a living instance and its origin. */
+export interface InstanceRecord {
+    instanceKey: string;
+    blueprintId: string;
+    userId: string;
+    sessionId?: string;
+    /** The blueprint version this instance was born from. */
+    blueprintVersion?: number;
+    /** ISO 8601. */
+    createdAt: string;
+}
+export declare function ensureInstancesTable(pool: pg.Pool): Promise<void>;
+/**
+ * Atomically claim a scope's instance row. Returns true when this call
+ * created it — the caller then owns seeding (emotion baselines, seed facts).
+ * False means the instance already exists and must not be re-seeded.
+ */
+export declare function claimInstance(pool: pg.Pool, scope: InstanceScope, blueprintVersion?: number): Promise<boolean>;
+/** Undo a claim whose seeding failed, so the next attempt re-seeds. */
+export declare function releaseInstance(pool: pg.Pool, scope: InstanceScope): Promise<void>;
+/** Enumerate instances, optionally narrowed to one blueprint and/or user. */
+export declare function listInstances(pool: pg.Pool, filter?: {
+    blueprintId?: string;
+    userId?: string;
+}): Promise<InstanceRecord[]>;
+/**
+ * Erase one instance entirely — its memories, its feelings, and its
+ * directory row. Returns true when the instance existed.
+ */
+export declare function deleteInstance(pool: pg.Pool, scope: InstanceScope): Promise<boolean>;

package/dist/postgres/instances.js

@@ -0,0 +1,77 @@
+import { instanceKey } from "../blueprint/scope.js";
+import { INSTANCES_SCHEMA } from "./schema.js";
+export async function ensureInstancesTable(pool) {
+    await pool.query(INSTANCES_SCHEMA);
+}
+/**
+ * Atomically claim a scope's instance row. Returns true when this call
+ * created it — the caller then owns seeding (emotion baselines, seed facts).
+ * False means the instance already exists and must not be re-seeded.
+ */
+export async function claimInstance(pool, scope, blueprintVersion) {
+    await ensureInstancesTable(pool);
+    const result = await pool.query(`INSERT INTO emocentric_instances
+       (instance_key, blueprint_id, user_id, session_id, blueprint_version)
+     VALUES ($1, $2, $3, $4, $5)
+     ON CONFLICT (instance_key) DO NOTHING`, [
+        instanceKey(scope),
+        scope.blueprintId,
+        scope.userId,
+        scope.sessionId ?? null,
+        blueprintVersion ?? null,
+    ]);
+    return (result.rowCount ?? 0) > 0;
+}
+/** Undo a claim whose seeding failed, so the next attempt re-seeds. */
+export async function releaseInstance(pool, scope) {
+    await pool.query(`DELETE FROM emocentric_instances WHERE instance_key = $1`, [
+        instanceKey(scope),
+    ]);
+}
+/** Enumerate instances, optionally narrowed to one blueprint and/or user. */
+export async function listInstances(pool, filter = {}) {
+    await ensureInstancesTable(pool);
+    const conditions = [];
+    const params = [];
+    if (filter.blueprintId !== undefined) {
+        params.push(filter.blueprintId);
+        conditions.push(`blueprint_id = $${params.length}`);
+    }
+    if (filter.userId !== undefined) {
+        params.push(filter.userId);
+        conditions.push(`user_id = $${params.length}`);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const { rows } = await pool.query(`SELECT instance_key, blueprint_id, user_id, session_id, blueprint_version, created_at
+     FROM emocentric_instances ${where} ORDER BY created_at`, params);
+    return rows.map((row) => ({
+        instanceKey: row.instance_key,
+        blueprintId: row.blueprint_id,
+        userId: row.user_id,
+        ...(row.session_id !== null && { sessionId: row.session_id }),
+        ...(row.blueprint_version !== null && {
+            blueprintVersion: row.blueprint_version,
+        }),
+        createdAt: row.created_at.toISOString(),
+    }));
+}
+/**
+ * Erase one instance entirely — its memories, its feelings, and its
+ * directory row. Returns true when the instance existed.
+ */
+export async function deleteInstance(pool, scope) {
+    const key = instanceKey(scope);
+    await ensureInstancesTable(pool);
+    await pool.query(`DELETE FROM emocentric_facts WHERE instance_key = $1`, [key])
+        .catch(swallowMissingTable);
+    await pool.query(`DELETE FROM emocentric_emotions WHERE instance_key = $1`, [key])
+        .catch(swallowMissingTable);
+    const result = await pool.query(`DELETE FROM emocentric_instances WHERE instance_key = $1`, [key]);
+    return (result.rowCount ?? 0) > 0;
+}
+/** 42P01 = undefined_table: an instance can predate first use of a store. */
+function swallowMissingTable(error) {
+    if (error.code === "42P01")
+        return { rowCount: 0 };
+    throw error;
+}

package/dist/postgres/schema.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Idempotent schema, applied automatically on first use (and safe to run on
+ * every startup). No migration framework — plain CREATE IF NOT EXISTS.
+ *
+ * All state is keyed by `instance_key` — the canonical string for one
+ * (blueprint, user[, session]) scope, see src/blueprint/scope.ts. The
+ * decomposition lives once, in `emocentric_instances`; facts and emotions
+ * carry only the key.
+ */
+export declare const VECTOR_EXTENSION = "CREATE EXTENSION IF NOT EXISTS vector;";
+export declare const CORE_SCHEMA = "\nCREATE TABLE IF NOT EXISTS emocentric_facts (\n  id               UUID PRIMARY KEY,\n  instance_key     TEXT NOT NULL,\n  kind             TEXT NOT NULL,\n  content          TEXT NOT NULL,\n  subject_id       TEXT,\n  importance       REAL NOT NULL DEFAULT 0.5,\n  created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),\n  last_accessed_at TIMESTAMPTZ,\n  superseded_by    UUID,\n  metadata         JSONB NOT NULL DEFAULT '{}'::jsonb\n);\n\nCREATE INDEX IF NOT EXISTS emocentric_facts_instance_kind_idx\n  ON emocentric_facts (instance_key, kind);\n\nCREATE INDEX IF NOT EXISTS emocentric_facts_instance_subject_idx\n  ON emocentric_facts (instance_key, subject_id);\n";
+/** One row per slider per instance. `updated_at` drives the time-decay
+ * stage (it runs at event arrival, before the interpreter/recall loop). */
+export declare const EMOTIONS_SCHEMA = "\nCREATE TABLE IF NOT EXISTS emocentric_emotions (\n  instance_key TEXT NOT NULL,\n  emotion      TEXT NOT NULL,\n  value        REAL NOT NULL,\n  updated_at   TIMESTAMPTZ NOT NULL DEFAULT now(),\n  PRIMARY KEY (instance_key, emotion)\n);\n";
+/** One row per living instance. A row means "this instance exists and was
+ * seeded from its blueprint" — it is created (with the seed facts) on a
+ * user's first contact and doubles as the instance directory: enumerate a
+ * blueprint's instances, find everything a user owns, delete it all. */
+export declare const INSTANCES_SCHEMA = "\nCREATE TABLE IF NOT EXISTS emocentric_instances (\n  instance_key      TEXT PRIMARY KEY,\n  blueprint_id      TEXT NOT NULL,\n  user_id           TEXT NOT NULL,\n  session_id        TEXT,\n  blueprint_version INTEGER,\n  created_at        TIMESTAMPTZ NOT NULL DEFAULT now()\n);\n\nCREATE INDEX IF NOT EXISTS emocentric_instances_blueprint_idx\n  ON emocentric_instances (blueprint_id);\n\nCREATE INDEX IF NOT EXISTS emocentric_instances_user_idx\n  ON emocentric_instances (user_id);\n";
+/** The short-term window: recent engagements per instance, capacity-trimmed
+ * (never time-expired). `id` is the insertion order used for recency. */
+export declare const SHORT_TERM_SCHEMA = "\nCREATE TABLE IF NOT EXISTS emocentric_short_term (\n  id            BIGSERIAL PRIMARY KEY,\n  instance_key  TEXT NOT NULL,\n  occurred_at   TIMESTAMPTZ NOT NULL,\n  actor_id      TEXT NOT NULL,\n  actor_name    TEXT,\n  perceived     TEXT NOT NULL,\n  responded     TEXT NOT NULL DEFAULT '',\n  created_at    TIMESTAMPTZ NOT NULL DEFAULT now()\n);\n\nCREATE INDEX IF NOT EXISTS emocentric_short_term_instance_idx\n  ON emocentric_short_term (instance_key, id DESC);\n";
+export declare function addEmbeddingColumn(dimensions: number): string;
+export declare const DROP_EMBEDDING = "\nDROP INDEX IF EXISTS emocentric_facts_embedding_idx;\nALTER TABLE emocentric_facts DROP COLUMN IF EXISTS embedding;\n";
+/**
+ * Fixed key for the pg advisory lock that serializes a destructive,
+ * table-wide embedding-column rebuild (`reembedAll`) against concurrent
+ * rebuilds. Arbitrary but stable; scoped to this database. */
+export declare const REEMBED_ADVISORY_LOCK = 2026061500;
+/** Returns e.g. "vector(256)" for the current embedding column, or null. */
+export declare const EMBEDDING_COLUMN_TYPE = "\nSELECT format_type(a.atttypid, a.atttypmod) AS column_type\nFROM pg_attribute a\nWHERE a.attrelid = 'emocentric_facts'::regclass\n  AND a.attname = 'embedding'\n  AND NOT a.attisdropped;\n";

package/dist/postgres/schema.js

@@ -0,0 +1,98 @@
+/**
+ * Idempotent schema, applied automatically on first use (and safe to run on
+ * every startup). No migration framework — plain CREATE IF NOT EXISTS.
+ *
+ * All state is keyed by `instance_key` — the canonical string for one
+ * (blueprint, user[, session]) scope, see src/blueprint/scope.ts. The
+ * decomposition lives once, in `emocentric_instances`; facts and emotions
+ * carry only the key.
+ */
+export const VECTOR_EXTENSION = `CREATE EXTENSION IF NOT EXISTS vector;`;
+export const CORE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS emocentric_facts (
+  id               UUID PRIMARY KEY,
+  instance_key     TEXT NOT NULL,
+  kind             TEXT NOT NULL,
+  content          TEXT NOT NULL,
+  subject_id       TEXT,
+  importance       REAL NOT NULL DEFAULT 0.5,
+  created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
+  last_accessed_at TIMESTAMPTZ,
+  superseded_by    UUID,
+  metadata         JSONB NOT NULL DEFAULT '{}'::jsonb
+);
+
+CREATE INDEX IF NOT EXISTS emocentric_facts_instance_kind_idx
+  ON emocentric_facts (instance_key, kind);
+
+CREATE INDEX IF NOT EXISTS emocentric_facts_instance_subject_idx
+  ON emocentric_facts (instance_key, subject_id);
+`;
+/** One row per slider per instance. `updated_at` drives the time-decay
+ * stage (it runs at event arrival, before the interpreter/recall loop). */
+export const EMOTIONS_SCHEMA = `
+CREATE TABLE IF NOT EXISTS emocentric_emotions (
+  instance_key TEXT NOT NULL,
+  emotion      TEXT NOT NULL,
+  value        REAL NOT NULL,
+  updated_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (instance_key, emotion)
+);
+`;
+/** One row per living instance. A row means "this instance exists and was
+ * seeded from its blueprint" — it is created (with the seed facts) on a
+ * user's first contact and doubles as the instance directory: enumerate a
+ * blueprint's instances, find everything a user owns, delete it all. */
+export const INSTANCES_SCHEMA = `
+CREATE TABLE IF NOT EXISTS emocentric_instances (
+  instance_key      TEXT PRIMARY KEY,
+  blueprint_id      TEXT NOT NULL,
+  user_id           TEXT NOT NULL,
+  session_id        TEXT,
+  blueprint_version INTEGER,
+  created_at        TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS emocentric_instances_blueprint_idx
+  ON emocentric_instances (blueprint_id);
+
+CREATE INDEX IF NOT EXISTS emocentric_instances_user_idx
+  ON emocentric_instances (user_id);
+`;
+/** The short-term window: recent engagements per instance, capacity-trimmed
+ * (never time-expired). `id` is the insertion order used for recency. */
+export const SHORT_TERM_SCHEMA = `
+CREATE TABLE IF NOT EXISTS emocentric_short_term (
+  id            BIGSERIAL PRIMARY KEY,
+  instance_key  TEXT NOT NULL,
+  occurred_at   TIMESTAMPTZ NOT NULL,
+  actor_id      TEXT NOT NULL,
+  actor_name    TEXT,
+  perceived     TEXT NOT NULL,
+  responded     TEXT NOT NULL DEFAULT '',
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS emocentric_short_term_instance_idx
+  ON emocentric_short_term (instance_key, id DESC);
+`;
+export function addEmbeddingColumn(dimensions) {
+    return `ALTER TABLE emocentric_facts ADD COLUMN IF NOT EXISTS embedding vector(${dimensions});`;
+}
+export const DROP_EMBEDDING = `
+DROP INDEX IF EXISTS emocentric_facts_embedding_idx;
+ALTER TABLE emocentric_facts DROP COLUMN IF EXISTS embedding;
+`;
+/**
+ * Fixed key for the pg advisory lock that serializes a destructive,
+ * table-wide embedding-column rebuild (`reembedAll`) against concurrent
+ * rebuilds. Arbitrary but stable; scoped to this database. */
+export const REEMBED_ADVISORY_LOCK = 2_026_061_500;
+/** Returns e.g. "vector(256)" for the current embedding column, or null. */
+export const EMBEDDING_COLUMN_TYPE = `
+SELECT format_type(a.atttypid, a.atttypmod) AS column_type
+FROM pg_attribute a
+WHERE a.attrelid = 'emocentric_facts'::regclass
+  AND a.attname = 'embedding'
+  AND NOT a.attisdropped;
+`;

package/dist/postgres/short-term.d.ts

@@ -0,0 +1,32 @@
+import pg from "pg";
+import { type InstanceScope } from "../blueprint/scope.js";
+import { type Engagement, type ShortTermMemory } from "../short-term/short-term.js";
+export interface PostgresShortTermMemoryOptions {
+    /** e.g. process.env.DATABASE_URL. Either this or `pool` is required. */
+    connectionString?: string;
+    /** Bring your own pg Pool (the store will not close it). */
+    pool?: pg.Pool;
+    ssl?: pg.PoolConfig["ssl"];
+    /** Which instance's window this is — every query is filtered by its key. */
+    scope: InstanceScope;
+    /** Max engagements kept; older ones are trimmed on append (never expired by
+     * time). Default {@link DEFAULT_STM_CAPACITY}. */
+    capacity?: number;
+}
+/**
+ * Persistent short-term memory: one Postgres row per engagement per instance,
+ * so the window survives restarts and reopening the chat. Capacity-bounded
+ * (the last N), never time-cleared.
+ */
+export declare class PostgresShortTermMemory implements ShortTermMemory {
+    private readonly pool;
+    private readonly ownsPool;
+    private readonly instanceKey;
+    private readonly capacity;
+    private ready;
+    constructor(options: PostgresShortTermMemoryOptions);
+    recent(limit?: number): Promise<Engagement[]>;
+    append(engagement: Engagement): Promise<void>;
+    close(): Promise<void>;
+    private ensureReady;
+}