@atomicmemory/core 1.0.0

package/dist/db/repository-representations.js

@@ -0,0 +1,162 @@
+/**
+ * Child representation storage for dual-write memory cells.
+ * Parent `memories` rows remain the packaging unit; atomic facts and foresight
+ * rows provide retrieval-optimized child views over the same memory.
+ */
+import pgvector from 'pgvector/pg';
+import { config } from '../config.js';
+import { normalizeAtomicFactRow, normalizeForesightRow, normalizeSearchRow, } from './repository-types.js';
+import { RRF_K, buildHybridSearchParams } from './query-helpers.js';
+export async function storeAtomicFacts(queryable, facts) {
+    const insertedIds = [];
+    for (const fact of facts) {
+        const result = await queryable.query(`INSERT INTO memory_atomic_facts (
+         user_id, parent_memory_id, fact_text, embedding, fact_type, importance,
+         source_site, source_url, episode_id, keywords, metadata,
+         workspace_id, agent_id
+       )
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11::jsonb, $12, $13)
+       RETURNING id`, [
+            fact.userId,
+            fact.parentMemoryId,
+            fact.factText,
+            pgvector.toSql(fact.embedding),
+            fact.factType,
+            fact.importance,
+            fact.sourceSite,
+            fact.sourceUrl ?? '',
+            fact.episodeId ?? null,
+            fact.keywords ?? '',
+            JSON.stringify(fact.metadata ?? {}),
+            fact.workspaceId ?? null,
+            fact.agentId ?? null,
+        ]);
+        insertedIds.push(result.rows[0].id);
+    }
+    return insertedIds;
+}
+export async function replaceAtomicFactsForMemory(queryable, userId, parentMemoryId, facts) {
+    await queryable.query('DELETE FROM memory_atomic_facts WHERE user_id = $1 AND parent_memory_id = $2', [userId, parentMemoryId]);
+    if (facts.length === 0)
+        return [];
+    return storeAtomicFacts(queryable, facts);
+}
+export async function listAtomicFactsForMemory(queryable, userId, parentMemoryId) {
+    const result = await queryable.query(`SELECT * FROM memory_atomic_facts
+     WHERE user_id = $1 AND parent_memory_id = $2
+     ORDER BY created_at ASC`, [userId, parentMemoryId]);
+    return result.rows.map(normalizeAtomicFactRow);
+}
+export async function storeForesight(queryable, foresight) {
+    const insertedIds = [];
+    for (const entry of foresight) {
+        const result = await queryable.query(`INSERT INTO memory_foresight (
+         user_id, parent_memory_id, content, embedding, foresight_type, source_site,
+         source_url, episode_id, metadata, valid_from, valid_to,
+         workspace_id, agent_id
+       )
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10, $11, $12, $13)
+       RETURNING id`, [
+            entry.userId,
+            entry.parentMemoryId,
+            entry.content,
+            pgvector.toSql(entry.embedding),
+            entry.foresightType,
+            entry.sourceSite,
+            entry.sourceUrl ?? '',
+            entry.episodeId ?? null,
+            JSON.stringify(entry.metadata ?? {}),
+            (entry.validFrom ?? new Date()).toISOString(),
+            entry.validTo?.toISOString() ?? null,
+            entry.workspaceId ?? null,
+            entry.agentId ?? null,
+        ]);
+        insertedIds.push(result.rows[0].id);
+    }
+    return insertedIds;
+}
+export async function replaceForesightForMemory(queryable, userId, parentMemoryId, foresight) {
+    await queryable.query('DELETE FROM memory_foresight WHERE user_id = $1 AND parent_memory_id = $2', [userId, parentMemoryId]);
+    if (foresight.length === 0)
+        return [];
+    return storeForesight(queryable, foresight);
+}
+export async function listForesightForMemory(queryable, userId, parentMemoryId) {
+    const result = await queryable.query(`SELECT * FROM memory_foresight
+     WHERE user_id = $1 AND parent_memory_id = $2
+     ORDER BY valid_from ASC, created_at ASC`, [userId, parentMemoryId]);
+    return result.rows.map(normalizeForesightRow);
+}
+export async function searchAtomicFactsHybrid(pool, userId, queryText, queryEmbedding, limit, sourceSite, referenceTime) {
+    const { params, siteFilter } = buildHybridSearchParams(queryEmbedding, userId, queryText, limit, 'af.source_site', sourceSite, referenceTime);
+    const result = await pool.query(`WITH vector_ranked AS (
+       SELECT af.id, af.parent_memory_id, af.fact_text,
+         ROW_NUMBER() OVER (ORDER BY af.embedding <=> $1) AS vrank,
+         1 - (af.embedding <=> $1) AS similarity
+       FROM memory_atomic_facts af
+       JOIN memories m ON m.id = af.parent_memory_id
+       WHERE af.user_id = $2
+         AND m.deleted_at IS NULL
+         AND m.expired_at IS NULL
+         AND m.status = 'active'
+         AND m.workspace_id IS NULL
+         ${siteFilter}
+       ORDER BY af.embedding <=> $1
+       LIMIT $4 * 6
+     ),
+     fts_ranked AS (
+       SELECT af.id, af.parent_memory_id, af.fact_text,
+         ROW_NUMBER() OVER (ORDER BY ts_rank(af.search_vector, plainto_tsquery('english', $3)) DESC) AS ftsrank
+       FROM memory_atomic_facts af
+       JOIN memories m ON m.id = af.parent_memory_id
+       WHERE af.user_id = $2
+         AND m.deleted_at IS NULL
+         AND m.expired_at IS NULL
+         AND m.status = 'active'
+         AND m.workspace_id IS NULL
+         ${siteFilter}
+         AND af.search_vector @@ plainto_tsquery('english', $3)
+       ORDER BY ts_rank(af.search_vector, plainto_tsquery('english', $3)) DESC
+       LIMIT $4 * 6
+     ),
+     fused_facts AS (
+       SELECT
+         COALESCE(v.id, f.id) AS fact_id,
+         COALESCE(v.parent_memory_id, f.parent_memory_id) AS parent_memory_id,
+         COALESCE(v.fact_text, f.fact_text) AS fact_text,
+         COALESCE(v.similarity, 0) AS similarity,
+         COALESCE(1.0 / (${RRF_K} + v.vrank), 0) + COALESCE(1.0 / (${RRF_K} + f.ftsrank), 0) AS rrf_score
+       FROM vector_ranked v
+       FULL OUTER JOIN fts_ranked f ON v.id = f.id
+     ),
+     parent_ranked AS (
+       SELECT
+         parent_memory_id,
+         MAX(similarity) AS similarity,
+         MAX(rrf_score) AS best_rrf_score,
+         (ARRAY_AGG(fact_text ORDER BY (similarity + rrf_score) DESC))[1:3] AS matched_facts,
+         (ARRAY_AGG(fact_id::text ORDER BY (similarity + rrf_score) DESC))[1:3] AS matched_fact_ids
+       FROM fused_facts
+       GROUP BY parent_memory_id
+     )
+     SELECT
+       m.*,
+       p.similarity,
+       (
+         $5 * p.similarity
+         + CASE WHEN p.similarity >= $9 THEN (
+           $6 * m.importance
+           + $7 * EXP(-EXTRACT(EPOCH FROM ($8::timestamptz - m.last_accessed_at)) / 2592000.0)
+         ) ELSE 0 END
+         -- Lexical RRF stays outside the semantic boost gate because exact text match is itself a relevance signal.
+         + ${config.retrievalProfileSettings.lexicalWeight} * p.best_rrf_score
+       ) * COALESCE(m.trust_score, 1.0) AS score,
+       p.matched_facts,
+       p.matched_fact_ids,
+       'atomic_fact'::text AS retrieval_layer
+     FROM parent_ranked p
+     JOIN memories m ON m.id = p.parent_memory_id
+     ORDER BY score DESC
+     LIMIT $4`, params);
+    return result.rows.map(normalizeSearchRow);
+}

package/dist/db/repository-temporal-state.d.ts

@@ -0,0 +1,35 @@
+/**
+ * BEAM v38: temporal-state repository helpers.
+ *
+ * Two operations are exposed:
+ *   - `supersedePriorStateMemories` — UPDATE prior memories with the same
+ *     (user_id, state_key) so they close their event_end window when a
+ *     new memory takes over that key. Fails closed; the caller MUST
+ *     propagate the error and abort the ingest if this throws.
+ *   - `findActiveStateMemoryIds` — diagnostic / test helper returning the
+ *     IDs of memories that are currently active (event_end IS NULL) for
+ *     a (user_id, state_key) pair.
+ */
+import type pg from 'pg';
+/**
+ * Set `event_end = $eventEnd` on every prior, non-deleted memory whose
+ * (user_id, state_key) matches, EXCEPT the new memory itself. Returns
+ * the number of rows updated.
+ *
+ * Why fail closed: the supersede signal is the entire point of the
+ * temporal layer. Silently dropping it would leave both rows active
+ * and break the read-time rerank invariant.
+ */
+export declare function supersedePriorStateMemories(pool: pg.Pool, args: {
+    userId: string;
+    stateKey: string;
+    newMemoryId: string;
+    eventEnd: Date;
+}): Promise<number>;
+/**
+ * Return the IDs of the active memories for a (user_id, state_key) pair.
+ * Used in tests and as a diagnostic seam — production retrieval does NOT
+ * call this; it reranks the candidates already in hand by their
+ * `event_end` field.
+ */
+export declare function findActiveStateMemoryIds(pool: pg.Pool, userId: string, stateKey: string): Promise<string[]>;

package/dist/db/repository-temporal-state.js

@@ -0,0 +1,46 @@
+/**
+ * BEAM v38: temporal-state repository helpers.
+ *
+ * Two operations are exposed:
+ *   - `supersedePriorStateMemories` — UPDATE prior memories with the same
+ *     (user_id, state_key) so they close their event_end window when a
+ *     new memory takes over that key. Fails closed; the caller MUST
+ *     propagate the error and abort the ingest if this throws.
+ *   - `findActiveStateMemoryIds` — diagnostic / test helper returning the
+ *     IDs of memories that are currently active (event_end IS NULL) for
+ *     a (user_id, state_key) pair.
+ */
+/**
+ * Set `event_end = $eventEnd` on every prior, non-deleted memory whose
+ * (user_id, state_key) matches, EXCEPT the new memory itself. Returns
+ * the number of rows updated.
+ *
+ * Why fail closed: the supersede signal is the entire point of the
+ * temporal layer. Silently dropping it would leave both rows active
+ * and break the read-time rerank invariant.
+ */
+export async function supersedePriorStateMemories(pool, args) {
+    const result = await pool.query(`UPDATE memories
+        SET event_end = $4
+      WHERE user_id = $1
+        AND state_key = $2
+        AND id <> $3::uuid
+        AND event_end IS NULL
+        AND deleted_at IS NULL`, [args.userId, args.stateKey, args.newMemoryId, args.eventEnd.toISOString()]);
+    return result.rowCount ?? 0;
+}
+/**
+ * Return the IDs of the active memories for a (user_id, state_key) pair.
+ * Used in tests and as a diagnostic seam — production retrieval does NOT
+ * call this; it reranks the candidates already in hand by their
+ * `event_end` field.
+ */
+export async function findActiveStateMemoryIds(pool, userId, stateKey) {
+    const result = await pool.query(`SELECT id FROM memories
+      WHERE user_id = $1
+        AND state_key = $2
+        AND event_end IS NULL
+        AND deleted_at IS NULL
+      ORDER BY event_start DESC NULLS LAST`, [userId, stateKey]);
+    return result.rows.map((row) => row.id);
+}

package/dist/db/repository-tll.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Repository for the Temporal Linkage List (TLL) — per-entity sparse graph
+ * of event nodes connected by predecessor/successor edges.
+ *
+ * Purpose: maintain "what happened in what order, per entity" without
+ * paying the full graph-DB cost. Each new memory referencing an entity
+ * appends an event node; the predecessor pointer lets us traverse the
+ * chain backward at query time for EO/MSR/TR questions.
+ */
+import pg from 'pg';
+export interface TLLEvent {
+    memoryId: string;
+    predecessorMemoryId: string | null;
+    observationDate: Date;
+    positionInChain: number;
+}
+export declare class TllRepository {
+    private pool;
+    constructor(pool: pg.Pool);
+    /**
+     * Append an event node to each entity's chain. Idempotent on
+     * (user_id, entity_id, memory_id). Predecessor is the most-recent
+     * existing event for the entity; position is len(chain).
+     *
+     * Race-safety: each (user_id, entity_id) append runs inside a transaction
+     * guarded by `pg_advisory_xact_lock`. Concurrent appends targeting the
+     * same chain serialize on the lock, then compute the next position from
+     * committed rows via INSERT...SELECT. The
+     * `(user_id, entity_id, position_in_chain)` unique index is the
+     * defense-in-depth backstop that fails loudly if any caller bypasses the
+     * lock path.
+     */
+    append(userId: string, memoryId: string, entityIds: string[], observationDate: Date): Promise<void>;
+    /**
+     * Append one (entity, memory) row under an advisory lock keyed on the
+     * chain. The INSERT...SELECT computes predecessor + position inline from
+     * the latest committed row, so the read-then-write window the previous
+     * implementation exposed cannot reorder concurrent appends.
+     */
+    private appendOne;
+    /**
+     * Get the full event chain for an entity, ordered by observation_date
+     * (the conversation timestamp). Used for EO/TR/MSR queries that need
+     * chronological order — a backfilled event with an earlier
+     * observation_date surfaces in its true chronological position even
+     * though it was inserted last.
+     *
+     * `positionInChain` returned here is the 0-based chronological rank,
+     * derived via `ROW_NUMBER()` over the chronological order. The stored
+     * `position_in_chain` column is insertion-order audit metadata and is
+     * not exposed by this API. `predecessorMemoryId` is the immediate
+     * chronologically-prior memory (via `LAG()`) — also chronological,
+     * not the position-tip predecessor recorded at insert time.
+     *
+     * Tiebreaker for events sharing an `observation_date` (e.g. the same
+     * conversation timestamp) is the stored `position_in_chain` (insertion
+     * order), keeping the result deterministic.
+     */
+    chain(userId: string, entityId: string): Promise<TLLEvent[]>;
+    /**
+     * Bulk: get chains for multiple entities. Returns memory_ids in order
+     * across all entity chains, deduplicated. Used as a retrieval signal
+     * for queries that span multiple entities (MSR).
+     */
+    chainsFor(userId: string, entityIds: string[]): Promise<string[]>;
+    /**
+     * Bulk-retrieve enriched event chains: per-entity ordered list of events
+     * joined with memory content. Used by the event-chains HTTP endpoint and
+     * by EO-shaped read paths that need content alongside chain position.
+     *
+     * Returns one entry per entity; entities with no events are dropped.
+     * Within an entity, events are ordered by `observation_date` (the
+     * conversation timestamp), not insertion order — see `chain()` for
+     * the rationale and the `LAG`/`ROW_NUMBER` derivation of
+     * `predecessorMemoryId` and `positionInChain`. Tiebreaker for events
+     * sharing an observation_date is the stored insertion `position_in_chain`.
+     */
+    chainEventsForEntities(userId: string, entityIds: string[]): Promise<Array<{
+        entityId: string;
+        events: Array<{
+            memoryId: string;
+            content: string;
+            observationDate: Date;
+            positionInChain: number;
+            predecessorMemoryId: string | null;
+        }>;
+    }>>;
+}

package/dist/db/repository-tll.js

@@ -0,0 +1,179 @@
+/**
+ * Repository for the Temporal Linkage List (TLL) — per-entity sparse graph
+ * of event nodes connected by predecessor/successor edges.
+ *
+ * Purpose: maintain "what happened in what order, per entity" without
+ * paying the full graph-DB cost. Each new memory referencing an entity
+ * appends an event node; the predecessor pointer lets us traverse the
+ * chain backward at query time for EO/MSR/TR questions.
+ */
+// Stable namespace for pg_advisory_xact_lock keying. Keeps TLL appends from
+// colliding with unrelated advisory-lock callers in the same process.
+const TLL_ADVISORY_LOCK_NAMESPACE = 0x544c4c00; // "TLL\0"
+export class TllRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /**
+     * Append an event node to each entity's chain. Idempotent on
+     * (user_id, entity_id, memory_id). Predecessor is the most-recent
+     * existing event for the entity; position is len(chain).
+     *
+     * Race-safety: each (user_id, entity_id) append runs inside a transaction
+     * guarded by `pg_advisory_xact_lock`. Concurrent appends targeting the
+     * same chain serialize on the lock, then compute the next position from
+     * committed rows via INSERT...SELECT. The
+     * `(user_id, entity_id, position_in_chain)` unique index is the
+     * defense-in-depth backstop that fails loudly if any caller bypasses the
+     * lock path.
+     */
+    async append(userId, memoryId, entityIds, observationDate) {
+        if (entityIds.length === 0)
+            return;
+        const uniqueEntities = [...new Set(entityIds)];
+        // Per-entity transactions keep the advisory-lock scope narrow and let
+        // independent chains proceed in parallel.
+        for (const entityId of uniqueEntities) {
+            await this.appendOne(userId, memoryId, entityId, observationDate);
+        }
+    }
+    /**
+     * Append one (entity, memory) row under an advisory lock keyed on the
+     * chain. The INSERT...SELECT computes predecessor + position inline from
+     * the latest committed row, so the read-then-write window the previous
+     * implementation exposed cannot reorder concurrent appends.
+     */
+    async appendOne(userId, memoryId, entityId, observationDate) {
+        const client = await this.pool.connect();
+        try {
+            await client.query('BEGIN');
+            await client.query('SELECT pg_advisory_xact_lock($1, hashtext($2))', [
+                TLL_ADVISORY_LOCK_NAMESPACE,
+                `${userId}:${entityId}`,
+            ]);
+            await client.query(`INSERT INTO temporal_linkage_list
+           (user_id, entity_id, memory_id, predecessor_memory_id,
+            observation_date, position_in_chain)
+         SELECT
+           $1, $2, $3,
+           (SELECT memory_id FROM temporal_linkage_list
+              WHERE user_id = $1 AND entity_id = $2
+              ORDER BY position_in_chain DESC LIMIT 1),
+           $4,
+           COALESCE(
+             (SELECT MAX(position_in_chain) FROM temporal_linkage_list
+                WHERE user_id = $1 AND entity_id = $2),
+             -1
+           ) + 1
+         ON CONFLICT (user_id, entity_id, memory_id) DO NOTHING`, [userId, entityId, memoryId, observationDate]);
+            await client.query('COMMIT');
+        }
+        catch (err) {
+            await client.query('ROLLBACK').catch((rollbackErr) => console.error('[tll] rollback failed:', rollbackErr instanceof Error ? rollbackErr.message : rollbackErr));
+            throw err;
+        }
+        finally {
+            client.release();
+        }
+    }
+    /**
+     * Get the full event chain for an entity, ordered by observation_date
+     * (the conversation timestamp). Used for EO/TR/MSR queries that need
+     * chronological order — a backfilled event with an earlier
+     * observation_date surfaces in its true chronological position even
+     * though it was inserted last.
+     *
+     * `positionInChain` returned here is the 0-based chronological rank,
+     * derived via `ROW_NUMBER()` over the chronological order. The stored
+     * `position_in_chain` column is insertion-order audit metadata and is
+     * not exposed by this API. `predecessorMemoryId` is the immediate
+     * chronologically-prior memory (via `LAG()`) — also chronological,
+     * not the position-tip predecessor recorded at insert time.
+     *
+     * Tiebreaker for events sharing an `observation_date` (e.g. the same
+     * conversation timestamp) is the stored `position_in_chain` (insertion
+     * order), keeping the result deterministic.
+     */
+    async chain(userId, entityId) {
+        const result = await this.pool.query(`SELECT memory_id,
+              observation_date,
+              LAG(memory_id) OVER w AS chronological_predecessor,
+              ROW_NUMBER() OVER w - 1 AS chronological_position
+       FROM temporal_linkage_list
+       WHERE user_id = $1 AND entity_id = $2
+       WINDOW w AS (ORDER BY observation_date ASC, position_in_chain ASC)
+       ORDER BY observation_date ASC, position_in_chain ASC`, [userId, entityId]);
+        return result.rows.map((row) => ({
+            memoryId: row.memory_id,
+            predecessorMemoryId: row.chronological_predecessor ?? null,
+            observationDate: row.observation_date,
+            positionInChain: Number(row.chronological_position),
+        }));
+    }
+    /**
+     * Bulk: get chains for multiple entities. Returns memory_ids in order
+     * across all entity chains, deduplicated. Used as a retrieval signal
+     * for queries that span multiple entities (MSR).
+     */
+    async chainsFor(userId, entityIds) {
+        if (entityIds.length === 0)
+            return [];
+        const result = await this.pool.query(`SELECT DISTINCT memory_id, observation_date
+       FROM temporal_linkage_list
+       WHERE user_id = $1 AND entity_id = ANY($2::uuid[])
+       ORDER BY observation_date ASC`, [userId, [...new Set(entityIds)]]);
+        return result.rows.map((row) => row.memory_id);
+    }
+    /**
+     * Bulk-retrieve enriched event chains: per-entity ordered list of events
+     * joined with memory content. Used by the event-chains HTTP endpoint and
+     * by EO-shaped read paths that need content alongside chain position.
+     *
+     * Returns one entry per entity; entities with no events are dropped.
+     * Within an entity, events are ordered by `observation_date` (the
+     * conversation timestamp), not insertion order — see `chain()` for
+     * the rationale and the `LAG`/`ROW_NUMBER` derivation of
+     * `predecessorMemoryId` and `positionInChain`. Tiebreaker for events
+     * sharing an observation_date is the stored insertion `position_in_chain`.
+     */
+    async chainEventsForEntities(userId, entityIds) {
+        if (entityIds.length === 0)
+            return [];
+        const unique = [...new Set(entityIds)];
+        // `m.workspace_id IS NULL` — this is the global event-chain endpoint;
+        // workspace-scoped memories must not surface here even if they share
+        // an entity with a global memory.
+        const result = await this.pool.query(`SELECT t.entity_id,
+              t.memory_id,
+              t.observation_date,
+              LAG(t.memory_id) OVER w AS chronological_predecessor,
+              ROW_NUMBER() OVER w - 1 AS chronological_position,
+              m.content
+       FROM temporal_linkage_list t
+       JOIN memories m ON m.id = t.memory_id
+       WHERE t.user_id = $1
+         AND t.entity_id = ANY($2::uuid[])
+         AND m.deleted_at IS NULL
+         AND m.status = 'active'
+         AND m.workspace_id IS NULL
+       WINDOW w AS (
+         PARTITION BY t.entity_id
+         ORDER BY t.observation_date ASC, t.position_in_chain ASC
+       )
+       ORDER BY t.entity_id, t.observation_date ASC, t.position_in_chain ASC`, [userId, unique]);
+        const grouped = new Map();
+        for (const row of result.rows) {
+            const list = grouped.get(row.entity_id) ?? [];
+            list.push({
+                memoryId: row.memory_id,
+                content: row.content,
+                observationDate: row.observation_date,
+                positionInChain: Number(row.chronological_position),
+                predecessorMemoryId: row.chronological_predecessor ?? null,
+            });
+            grouped.set(row.entity_id, list);
+        }
+        return [...grouped.entries()].map(([entityId, events]) => ({ entityId, events }));
+    }
+}