emocentric 0.1.0

package/dist/postgres/short-term.js

@@ -0,0 +1,95 @@
+import pg from "pg";
+import { instanceKey } from "../blueprint/scope.js";
+import { DEFAULT_STM_CAPACITY, } from "../short-term/short-term.js";
+import { SHORT_TERM_SCHEMA } from "./schema.js";
+/**
+ * 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 class PostgresShortTermMemory {
+    pool;
+    ownsPool;
+    instanceKey;
+    capacity;
+    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("PostgresShortTermMemory 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.capacity = Math.max(1, options.capacity ?? DEFAULT_STM_CAPACITY);
+    }
+    async recent(limit) {
+        await this.ensureReady();
+        const n = Math.max(0, limit ?? this.capacity);
+        if (n === 0)
+            return [];
+        const { rows } = await this.pool.query(`SELECT occurred_at, actor_id, actor_name, perceived, responded
+       FROM emocentric_short_term
+       WHERE instance_key = $1
+       ORDER BY id DESC
+       LIMIT $2`, [this.instanceKey, n]);
+        // SQL returns newest-first; flip to oldest-first for the window.
+        return rows.reverse().map((r) => ({
+            occurredAt: r.occurred_at.toISOString(),
+            actor: r.actor_name !== null
+                ? { id: r.actor_id, displayName: r.actor_name }
+                : { id: r.actor_id },
+            perceived: r.perceived,
+            responded: r.responded,
+        }));
+    }
+    async append(engagement) {
+        await this.ensureReady();
+        await this.pool.query(`INSERT INTO emocentric_short_term
+         (instance_key, occurred_at, actor_id, actor_name, perceived, responded)
+       VALUES ($1, $2, $3, $4, $5, $6)`, [
+            this.instanceKey,
+            engagement.occurredAt,
+            engagement.actor.id,
+            engagement.actor.displayName ?? null,
+            engagement.perceived,
+            engagement.responded,
+        ]);
+        // Capacity trim: drop everything older than the newest `capacity` rows.
+        await this.pool.query(`DELETE FROM emocentric_short_term
+       WHERE instance_key = $1
+         AND id < (
+           SELECT min(id) FROM (
+             SELECT id FROM emocentric_short_term
+             WHERE instance_key = $1
+             ORDER BY id DESC
+             LIMIT $2
+           ) keep
+         )`, [this.instanceKey, this.capacity]);
+    }
+    async close() {
+        if (this.ownsPool)
+            await this.pool.end();
+    }
+    ensureReady() {
+        if (!this.ready) {
+            this.ready = this.pool
+                .query(SHORT_TERM_SCHEMA)
+                .then(() => undefined)
+                .catch((error) => {
+                this.ready = undefined;
+                throw error;
+            });
+        }
+        return this.ready;
+    }
+}

package/dist/postgres/store.d.ts

@@ -0,0 +1,85 @@
+import pg from "pg";
+import type { Fact, FactInput, FactPatch } from "../memory/fact.js";
+import type { Embedder, MemoryQuery, MemoryStore, ScoredFact } from "../memory/store.js";
+import { type ScoringWeights } from "../memory/scoring.js";
+import { type InstanceScope } from "../blueprint/scope.js";
+export interface PostgresMemoryStoreOptions {
+    /** 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;
+    /** Pass `{ rejectUnauthorized: false }` when connecting to Railway's
+     * public proxy; leave unset for localhost / private networking. */
+    ssl?: pg.PoolConfig["ssl"];
+    /** Which instance's memory this store handle is scoped to. One database
+     * serves many instances; every query is filtered by this scope's key. */
+    scope: InstanceScope;
+    /** Defaults to {@link OpenAIEmbedder} (needs OPENAI_API_KEY). Pass any other
+     * Embedder to override; run reembedAll({ confirm: true }) after switching
+     * dimensions. */
+    embedder?: Embedder;
+    weights?: Partial<ScoringWeights>;
+    /** Cosine-relevance floor for text queries — results below it are dropped as
+     * "no real match". Overrides the embedder's own default; a per-query
+     * `minRelevance` overrides this. Omit to use the embedder's default. */
+    minRelevance?: number;
+}
+export interface ReembedAllOptions {
+    /** Required acknowledgement. `reembedAll` rebuilds the SHARED embedding
+     * column for every instance in the table, not just this store's scope —
+     * pass `true` only when you intend a full table-wide re-embed. */
+    confirm: boolean;
+    /** Rows re-embedded per batch. Default 100. */
+    batchSize?: number;
+}
+/**
+ * The SDK's production MemoryStore: Postgres + pgvector.
+ *
+ * - `add` embeds each fact's content and stores row + vector
+ * - `fetch` embeds the query, scans this instance's facts exactly, then blends
+ *   relevance/importance/recency and returns the top N
+ * - schema is created automatically on first use (`migrate()` is also
+ *   public and idempotent if you prefer to run it explicitly)
+ *
+ * Works against any Postgres with the pgvector extension — the bundled
+ * docker-compose locally, Railway's PostgreSQL service in production.
+ */
+export declare class PostgresMemoryStore implements MemoryStore {
+    private readonly pool;
+    private readonly ownsPool;
+    private readonly instanceKey;
+    private readonly embedder;
+    private readonly weights;
+    private readonly minRelevance;
+    private ready;
+    constructor(options: PostgresMemoryStoreOptions);
+    /**
+     * Create the schema if needed and verify the embedding column matches the
+     * configured embedder's dimensions. Idempotent; called lazily by every
+     * other method, so you only need it explicitly for startup health checks.
+     */
+    migrate(): Promise<void>;
+    /**
+     * Rebuild the embedding column and re-embed every fact with the currently
+     * configured embedder. Run once after switching to a different-dimension
+     * embedder.
+     *
+     * DESTRUCTIVE and TABLE-WIDE: this drops and recreates the shared `embedding`
+     * column for EVERY instance in `emocentric_facts`, not just this store's
+     * scope — pass `{ confirm: true }` to acknowledge that. The whole rebuild
+     * runs in one transaction under a pg advisory lock, so it's atomic (a
+     * failure rolls back to the prior column rather than leaving a half-NULL
+     * one) and serialized against concurrent rebuilds. The embedder calls happen
+     * inside that transaction, so for a very large table this holds an exclusive
+     * lock for the duration — treat it as a maintenance operation.
+     */
+    reembedAll(options: ReembedAllOptions): Promise<number>;
+    add(inputs: FactInput[]): Promise<Fact[]>;
+    fetch(query: MemoryQuery): Promise<ScoredFact[]>;
+    get(id: string): Promise<Fact | null>;
+    update(id: string, patch: FactPatch): Promise<Fact | null>;
+    delete(id: string): Promise<boolean>;
+    close(): Promise<void>;
+    private ensureReady;
+    private embeddingColumnDimensions;
+}

package/dist/postgres/store.js

@@ -0,0 +1,347 @@
+import pg from "pg";
+import { generateEventId } from "../events/context-event.js";
+import { DEFAULT_SCORING_WEIGHTS, blendScore, clamp01, } from "../memory/scoring.js";
+import { OpenAIEmbedder } from "../memory/openai-embedder.js";
+import { instanceKey } from "../blueprint/scope.js";
+import { CORE_SCHEMA, DROP_EMBEDDING, EMBEDDING_COLUMN_TYPE, REEMBED_ADVISORY_LOCK, VECTOR_EXTENSION, addEmbeddingColumn, } from "./schema.js";
+/** Candidate pool for the no-text "what's on my mind" branch (re-ranked by the
+ * blend). Text queries don't use this — they return all facts above the floor. */
+const CANDIDATE_POOL = 25;
+/** Default cap for the no-text browse mode, which has no relevance floor to
+ * bound it. Text queries are bounded by the floor instead, not a fixed K. */
+const DEFAULT_BROWSE_LIMIT = 10;
+/**
+ * The SDK's production MemoryStore: Postgres + pgvector.
+ *
+ * - `add` embeds each fact's content and stores row + vector
+ * - `fetch` embeds the query, scans this instance's facts exactly, then blends
+ *   relevance/importance/recency and returns the top N
+ * - schema is created automatically on first use (`migrate()` is also
+ *   public and idempotent if you prefer to run it explicitly)
+ *
+ * Works against any Postgres with the pgvector extension — the bundled
+ * docker-compose locally, Railway's PostgreSQL service in production.
+ */
+export class PostgresMemoryStore {
+    pool;
+    ownsPool;
+    instanceKey;
+    embedder;
+    weights;
+    minRelevance;
+    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("PostgresMemoryStore 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.embedder = options.embedder ?? new OpenAIEmbedder();
+        this.weights = { ...DEFAULT_SCORING_WEIGHTS, ...options.weights };
+        this.minRelevance = options.minRelevance;
+    }
+    /**
+     * Create the schema if needed and verify the embedding column matches the
+     * configured embedder's dimensions. Idempotent; called lazily by every
+     * other method, so you only need it explicitly for startup health checks.
+     */
+    async migrate() {
+        try {
+            await this.pool.query(VECTOR_EXTENSION);
+        }
+        catch (error) {
+            throw new Error("Could not enable the pgvector extension. Use a Postgres with pgvector " +
+                "(locally: the bundled docker-compose image; on Railway: the standard " +
+                `PostgreSQL service). Underlying error: ${error.message}`);
+        }
+        await this.pool.query(CORE_SCHEMA);
+        const existing = await this.embeddingColumnDimensions();
+        if (existing === null) {
+            await this.pool.query(addEmbeddingColumn(this.embedder.dimensions));
+        }
+        else if (existing !== this.embedder.dimensions) {
+            throw new Error(`Embedding column is vector(${existing}) but the configured embedder ` +
+                `produces ${this.embedder.dimensions} dimensions. You probably ` +
+                "switched embedders — call reembedAll({ confirm: true }) once to " +
+                "migrate stored vectors.");
+        }
+    }
+    /**
+     * Rebuild the embedding column and re-embed every fact with the currently
+     * configured embedder. Run once after switching to a different-dimension
+     * embedder.
+     *
+     * DESTRUCTIVE and TABLE-WIDE: this drops and recreates the shared `embedding`
+     * column for EVERY instance in `emocentric_facts`, not just this store's
+     * scope — pass `{ confirm: true }` to acknowledge that. The whole rebuild
+     * runs in one transaction under a pg advisory lock, so it's atomic (a
+     * failure rolls back to the prior column rather than leaving a half-NULL
+     * one) and serialized against concurrent rebuilds. The embedder calls happen
+     * inside that transaction, so for a very large table this holds an exclusive
+     * lock for the duration — treat it as a maintenance operation.
+     */
+    async reembedAll(options) {
+        if (!options?.confirm) {
+            throw new Error("reembedAll() is destructive and table-wide: it drops and rebuilds the " +
+                "shared `embedding` column for EVERY instance in emocentric_facts and " +
+                "re-embeds all rows. It is NOT scoped to this store. Pass " +
+                "{ confirm: true } to proceed.");
+        }
+        const batchSize = options.batchSize ?? 100;
+        const client = await this.pool.connect();
+        try {
+            await client.query("BEGIN");
+            // Serialize against any concurrent rebuild; auto-released on COMMIT/ROLLBACK.
+            await client.query("SELECT pg_advisory_xact_lock($1)", [
+                REEMBED_ADVISORY_LOCK,
+            ]);
+            await client.query(VECTOR_EXTENSION);
+            await client.query(CORE_SCHEMA);
+            await client.query(DROP_EMBEDDING);
+            await client.query(addEmbeddingColumn(this.embedder.dimensions));
+            let total = 0;
+            for (;;) {
+                const { rows } = await client.query(`SELECT id, content FROM emocentric_facts
+           WHERE embedding IS NULL ORDER BY created_at LIMIT $1`, [batchSize]);
+                if (rows.length === 0)
+                    break;
+                const vectors = await this.embedder.embed(rows.map((r) => r.content));
+                if (vectors.length !== rows.length) {
+                    throw new Error(`Embedder returned ${vectors.length} vectors for ${rows.length} inputs.`);
+                }
+                for (let i = 0; i < rows.length; i++) {
+                    await client.query(`UPDATE emocentric_facts SET embedding = $1::vector WHERE id = $2`, [toVectorLiteral(vectors[i]), rows[i].id]);
+                }
+                total += rows.length;
+            }
+            await client.query("COMMIT");
+            this.ready = undefined; // re-run dimension check on next use
+            return total;
+        }
+        catch (error) {
+            await client.query("ROLLBACK").catch(() => { });
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async add(inputs) {
+        await this.ensureReady();
+        if (inputs.length === 0)
+            return [];
+        const vectors = await this.embedder.embed(inputs.map((i) => i.content));
+        const facts = [];
+        for (let i = 0; i < inputs.length; i++) {
+            const input = inputs[i];
+            const fact = {
+                id: input.id ?? generateEventId(),
+                kind: input.kind,
+                content: input.content,
+                importance: input.importance ?? 0.5,
+                createdAt: input.createdAt ?? new Date().toISOString(),
+                ...(input.subjectId !== undefined && { subjectId: input.subjectId }),
+                ...(input.metadata !== undefined && { metadata: input.metadata }),
+            };
+            await this.pool.query(`INSERT INTO emocentric_facts
+           (id, instance_key, kind, content, subject_id, importance, created_at, metadata, embedding)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::vector)`, [
+                fact.id,
+                this.instanceKey,
+                fact.kind,
+                fact.content,
+                fact.subjectId ?? null,
+                fact.importance,
+                fact.createdAt,
+                JSON.stringify(fact.metadata ?? {}),
+                toVectorLiteral(vectors[i]),
+            ]);
+            facts.push(fact);
+        }
+        return facts;
+    }
+    async fetch(query) {
+        await this.ensureReady();
+        const hasText = query.text.trim().length > 0;
+        // Relevance floor, resolved up front so a text query can push it into SQL:
+        // query override → store default → embedder's recommendation → 0. A semantic
+        // embedder returns a small positive cosine even for unrelated text, so the
+        // floor is what bounds the result set (in place of a fixed top-K).
+        const floor = query.minRelevance ?? this.minRelevance ?? this.embedder.minRelevance ?? 0;
+        const conditions = ["instance_key = $1"];
+        const params = [this.instanceKey];
+        if (!query.includeSuperseded)
+            conditions.push("superseded_by IS NULL");
+        if (query.kinds && query.kinds.length > 0) {
+            params.push(query.kinds);
+            conditions.push(`kind = ANY($${params.length})`);
+        }
+        if (query.subjectId !== undefined) {
+            params.push(query.subjectId);
+            conditions.push(`subject_id = $${params.length}`);
+        }
+        let rows;
+        if (hasText) {
+            const [queryVector] = await this.embedder.embed([query.text]);
+            params.push(toVectorLiteral(queryVector));
+            const vectorParam = `$${params.length}::vector`;
+            conditions.push("embedding IS NOT NULL");
+            // Exact per-instance scan returning EVERY fact above the relevance floor
+            // — no fixed top-K. The selective instance_key filter keeps the scan to
+            // this instance's rows; the floor is pushed into SQL so noise never
+            // crosses the wire. An explicit `limit` still caps it to the N nearest.
+            params.push(floor);
+            conditions.push(`1 - (embedding <=> ${vectorParam}) >= $${params.length}`);
+            let sql = `SELECT id, kind, content, subject_id, importance, created_at,
+                last_accessed_at, superseded_by, metadata,
+                1 - (embedding <=> ${vectorParam}) AS relevance
+         FROM emocentric_facts
+         WHERE ${conditions.join(" AND ")}
+         ORDER BY embedding <=> ${vectorParam}`;
+            if (query.limit !== undefined) {
+                params.push(query.limit);
+                sql += ` LIMIT $${params.length}`;
+            }
+            rows = (await this.pool.query(sql, params)).rows;
+        }
+        else {
+            // No query text: rank purely by importance + recency. No relevance signal
+            // bounds the set, so this "what's on my mind" mode stays capped.
+            const browseLimit = query.limit ?? DEFAULT_BROWSE_LIMIT;
+            params.push(Math.max(CANDIDATE_POOL, browseLimit));
+            const result = await this.pool.query(`SELECT id, kind, content, subject_id, importance, created_at,
+                last_accessed_at, superseded_by, metadata,
+                0 AS relevance
+         FROM emocentric_facts
+         WHERE ${conditions.join(" AND ")}
+         ORDER BY importance DESC, created_at DESC
+         LIMIT $${params.length}`, params);
+            rows = result.rows;
+        }
+        const now = Date.now();
+        const scored = [];
+        for (const row of rows) {
+            const relevance = clamp01(Number(row.relevance));
+            // Non-positive relevance is never a real match (the SQL floor already
+            // excludes sub-floor rows for text queries).
+            if (hasText && relevance <= 0)
+                continue;
+            const fact = rowToFact(row);
+            const score = blendScore(relevance, fact.importance, fact.createdAt, this.weights, now);
+            if (query.minScore !== undefined && score < query.minScore)
+                continue;
+            scored.push({ fact, score, relevance });
+        }
+        scored.sort((a, b) => b.score - a.score);
+        // Text queries return every fact above the floor (no fixed top-K) unless an
+        // explicit `limit` was given; the no-text browse mode stays bounded.
+        const top = hasText
+            ? query.limit !== undefined
+                ? scored.slice(0, query.limit)
+                : scored
+            : scored.slice(0, query.limit ?? DEFAULT_BROWSE_LIMIT);
+        if (top.length > 0) {
+            const accessedAt = new Date(now).toISOString();
+            await this.pool.query(`UPDATE emocentric_facts SET last_accessed_at = $1 WHERE id = ANY($2)`, [accessedAt, top.map((s) => s.fact.id)]);
+            for (const s of top)
+                s.fact.lastAccessedAt = accessedAt;
+        }
+        return top;
+    }
+    async get(id) {
+        await this.ensureReady();
+        const { rows } = await this.pool.query(`SELECT id, kind, content, subject_id, importance, created_at,
+              last_accessed_at, superseded_by, metadata
+       FROM emocentric_facts WHERE instance_key = $1 AND id = $2`, [this.instanceKey, id]);
+        return rows[0] ? rowToFact(rows[0]) : null;
+    }
+    async update(id, patch) {
+        await this.ensureReady();
+        const sets = [];
+        const params = [this.instanceKey, id];
+        const push = (fragment, value) => {
+            params.push(value);
+            sets.push(`${fragment} = $${params.length}`);
+        };
+        if (patch.kind !== undefined)
+            push("kind", patch.kind);
+        if (patch.content !== undefined)
+            push("content", patch.content);
+        if (patch.subjectId !== undefined)
+            push("subject_id", patch.subjectId);
+        if (patch.importance !== undefined)
+            push("importance", patch.importance);
+        if (patch.supersededBy !== undefined) {
+            push("superseded_by", patch.supersededBy);
+        }
+        if (patch.metadata !== undefined) {
+            push("metadata", JSON.stringify(patch.metadata));
+        }
+        if (patch.content !== undefined) {
+            const [vector] = await this.embedder.embed([patch.content]);
+            params.push(toVectorLiteral(vector));
+            sets.push(`embedding = $${params.length}::vector`);
+        }
+        if (sets.length === 0)
+            return this.get(id);
+        const { rows } = await this.pool.query(`UPDATE emocentric_facts SET ${sets.join(", ")}
+       WHERE instance_key = $1 AND id = $2
+       RETURNING id, kind, content, subject_id, importance, created_at,
+                 last_accessed_at, superseded_by, metadata`, params);
+        return rows[0] ? rowToFact(rows[0]) : null;
+    }
+    async delete(id) {
+        await this.ensureReady();
+        const result = await this.pool.query(`DELETE FROM emocentric_facts WHERE instance_key = $1 AND id = $2`, [this.instanceKey, id]);
+        return (result.rowCount ?? 0) > 0;
+    }
+    async close() {
+        if (this.ownsPool)
+            await this.pool.end();
+    }
+    ensureReady() {
+        if (!this.ready) {
+            this.ready = this.migrate().catch((error) => {
+                this.ready = undefined; // allow retry after transient failures
+                throw error;
+            });
+        }
+        return this.ready;
+    }
+    async embeddingColumnDimensions() {
+        const { rows } = await this.pool.query(EMBEDDING_COLUMN_TYPE);
+        const match = rows[0]?.column_type.match(/^vector\((\d+)\)$/);
+        return match ? Number(match[1]) : null;
+    }
+}
+function rowToFact(row) {
+    const metadata = row.metadata;
+    return {
+        id: row.id,
+        kind: row.kind,
+        content: row.content,
+        importance: row.importance,
+        createdAt: row.created_at.toISOString(),
+        ...(row.subject_id !== null && { subjectId: row.subject_id }),
+        ...(row.last_accessed_at !== null && {
+            lastAccessedAt: row.last_accessed_at.toISOString(),
+        }),
+        ...(row.superseded_by !== null && { supersededBy: row.superseded_by }),
+        ...(Object.keys(metadata).length > 0 && { metadata }),
+    };
+}
+/** pgvector accepts vectors as '[0.1,0.2,...]' text literals. */
+function toVectorLiteral(vector) {
+    return "[" + vector.join(",") + "]";
+}

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

@@ -0,0 +1 @@
+export { DEFAULT_STM_CAPACITY, InMemoryShortTermMemory, relativeTime, renderEngagements, type Engagement, type InMemoryShortTermMemoryOptions, type ShortTermMemory, } from "./short-term.js";

package/dist/short-term/index.js

@@ -0,0 +1 @@
+export { DEFAULT_STM_CAPACITY, InMemoryShortTermMemory, relativeTime, renderEngagements, } from "./short-term.js";

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

@@ -0,0 +1,66 @@
+/** Default number of engagements kept in the window. One engagement is one
+ * incoming event plus the agent's response to it. */
+export declare const DEFAULT_STM_CAPACITY = 12;
+/**
+ * One turn the agent recently lived through: what it perceived and how it
+ * responded, stamped with when it happened. The unit of short-term memory.
+ */
+export interface Engagement {
+    /** When the incoming event happened (the event's occurredAt). */
+    occurredAt: string;
+    /** Who the event was from. */
+    actor: {
+        id: string;
+        displayName?: string;
+    };
+    /** How the agent understood the incoming event — the interpreter's
+     * description. */
+    perceived: string;
+    /** What the agent did in response — its rendered output. Empty string when
+     * it stayed silent. */
+    responded: string;
+}
+/**
+ * The agent's working memory: a small, recency-ordered window of the most
+ * recent engagements with one instance, kept fresh so the agent always has
+ * the immediate thread in mind. Distinct from {@link MemoryStore} (durable,
+ * semantic, "relevant") — this is "recent". Per-instance; persisted so it
+ * survives across sessions. Two methods — swap the backend freely.
+ */
+export interface ShortTermMemory {
+    /** The most recent engagements, oldest-first (newest last). Up to `limit`,
+     * defaulting to the window's full capacity. */
+    recent(limit?: number): Promise<Engagement[]>;
+    /** Record one engagement, trimming the window to capacity. */
+    append(engagement: Engagement): Promise<void>;
+}
+export interface InMemoryShortTermMemoryOptions {
+    /** Max engagements kept. Default {@link DEFAULT_STM_CAPACITY}. */
+    capacity?: number;
+    /** Pre-existing engagements (oldest-first) to start from. */
+    seed?: Engagement[];
+}
+/**
+ * Process-local short-term memory: a trimmed array. Good for tests and
+ * single-process use; NOT persistent (use the Postgres-backed store for the
+ * "survives closing the chat" guarantee).
+ */
+export declare class InMemoryShortTermMemory implements ShortTermMemory {
+    private readonly capacity;
+    private engagements;
+    constructor(options?: InMemoryShortTermMemoryOptions);
+    recent(limit?: number): Promise<Engagement[]>;
+    append(engagement: Engagement): Promise<void>;
+}
+/**
+ * Human "how long ago" between an engagement and the current event, for the
+ * prompt. Both are ISO strings; `now` is the current event's time, so the
+ * agent reads recency relative to what's happening now, not wall-clock.
+ */
+export declare function relativeTime(occurredAt: string, now: string): string;
+/**
+ * Render the window into a prompt block, newest last, each line tagged with
+ * how long ago it was relative to `now`. Returns "" when the window is empty
+ * (so callers can omit the block entirely — the neutral case).
+ */
+export declare function renderEngagements(engagements: Engagement[], now: string): string;

package/dist/short-term/short-term.js

@@ -0,0 +1,72 @@
+/** Default number of engagements kept in the window. One engagement is one
+ * incoming event plus the agent's response to it. */
+export const DEFAULT_STM_CAPACITY = 12;
+/**
+ * Process-local short-term memory: a trimmed array. Good for tests and
+ * single-process use; NOT persistent (use the Postgres-backed store for the
+ * "survives closing the chat" guarantee).
+ */
+export class InMemoryShortTermMemory {
+    capacity;
+    engagements;
+    constructor(options = {}) {
+        this.capacity = options.capacity ?? DEFAULT_STM_CAPACITY;
+        this.engagements = (options.seed ?? []).slice(-this.capacity);
+    }
+    async recent(limit) {
+        const n = limit ?? this.capacity;
+        return this.engagements.slice(-Math.max(0, n));
+    }
+    async append(engagement) {
+        this.engagements.push(engagement);
+        if (this.engagements.length > this.capacity) {
+            this.engagements = this.engagements.slice(-this.capacity);
+        }
+    }
+}
+/**
+ * Human "how long ago" between an engagement and the current event, for the
+ * prompt. Both are ISO strings; `now` is the current event's time, so the
+ * agent reads recency relative to what's happening now, not wall-clock.
+ */
+export function relativeTime(occurredAt, now) {
+    const then = Date.parse(occurredAt);
+    const ref = Date.parse(now);
+    if (Number.isNaN(then) || Number.isNaN(ref))
+        return "earlier";
+    const sec = Math.floor((ref - then) / 1000);
+    if (sec < 45)
+        return "just now";
+    const min = Math.floor(sec / 60);
+    if (min < 60)
+        return `${min}m ago`;
+    const hr = Math.floor(min / 60);
+    if (hr < 24)
+        return `${hr}h ago`;
+    const day = Math.floor(hr / 24);
+    if (day < 7)
+        return `${day}d ago`;
+    const wk = Math.floor(day / 7);
+    if (wk < 5)
+        return `${wk}w ago`;
+    const mo = Math.floor(day / 30);
+    if (mo < 12)
+        return `${mo}mo ago`;
+    return `${Math.floor(day / 365)}y ago`;
+}
+/**
+ * Render the window into a prompt block, newest last, each line tagged with
+ * how long ago it was relative to `now`. Returns "" when the window is empty
+ * (so callers can omit the block entirely — the neutral case).
+ */
+export function renderEngagements(engagements, now) {
+    if (engagements.length === 0)
+        return "";
+    return engagements
+        .map((e) => {
+        const ago = relativeTime(e.occurredAt, now);
+        const responded = e.responded.trim() === "" ? "(stayed silent)" : `"${e.responded}"`;
+        return `- [${ago}] ${e.perceived} — you: ${responded}`;
+    })
+        .join("\n");
+}