@illuma-ai/agents 1.1.28 → 1.3.1

package/src/memory/constants.ts

@@ -0,0 +1,229 @@
+/**
+ * Autonomous memory — shared constants.
+ *
+ * Single source of truth for defaults, limits, and magic strings used across
+ * the memory store, tools, flush phase, and tests. Changing a value here
+ * changes it everywhere — no hunting through files.
+ */
+
+/** Default embedding provider when {@link process.env.MEMORY_EMBEDDINGS_PROVIDER} is unset. */
+export const DEFAULT_MEMORY_PROVIDER = 'bedrock' as const;
+
+/** Default embedding model (Titan v2 — AWS-native, 6× cheaper than Cohere v4). */
+export const DEFAULT_MEMORY_MODEL = 'amazon.titan-embed-text-v2:0';
+
+/** Default vector width (Titan v2 supports 256 / 512 / 1024). */
+export const DEFAULT_MEMORY_DIMENSIONS = 1024;
+
+/** Default Postgres table name; can be overridden via env for dev/prod sharing. */
+export const DEFAULT_MEMORY_TABLE = 'agent_memories';
+
+/** Default Postgres schema. */
+export const DEFAULT_MEMORY_SCHEMA = 'public';
+
+/** Phase values used by the flush-phase gate. */
+export const MEMORY_PHASE_NORMAL = 'normal';
+export const MEMORY_PHASE_FLUSHING = 'memory_flushing';
+
+/**
+ * Search defaults — aligned with upstream's upstream defaults.
+ *
+ * Sources:
+ * - `upstream reference` → maxResults=6
+ * - `upstream reference` → maxInjectedChars=4000
+ *
+ * Keeping these in lockstep with upstream means the mandatory-recall tool
+ * description, budget clamps, and eval corpora line up with upstream's
+ * tuning — we inherit their calibration instead of re-tuning from scratch.
+ */
+export const DEFAULT_MAX_SEARCH_RESULTS = 6;
+export const DEFAULT_MIN_SCORE = 0.1;
+export const DEFAULT_MAX_INJECTED_CHARS = 4000;
+
+/** Hybrid retrieval weights — 70% vector cosine, 30% BM25 / ts_rank text score. */
+export const HYBRID_VECTOR_WEIGHT = 0.7;
+export const HYBRID_TEXT_WEIGHT = 0.3;
+
+/**
+ * Phase 2 rerank defaults — ported from upstream.
+ *
+ * Sources:
+ * - `upstream reference` → lambda=0.7
+ * - `upstream reference` → halfLifeDays=30
+ *
+ * Both features are opt-in (enabled=false by default) — the Phase 2
+ * features are layered on top of hybrid search and don't change default
+ * behavior for callers that upgrade in place.
+ */
+export const DEFAULT_MMR_ENABLED = false;
+export const DEFAULT_MMR_LAMBDA = 0.7;
+export const DEFAULT_TEMPORAL_DECAY_ENABLED = false;
+export const DEFAULT_TEMPORAL_DECAY_HALF_LIFE_DAYS = 30;
+export const DEFAULT_RECALL_TRACKING_ENABLED = false;
+export const DEFAULT_CITATIONS_MODE = 'auto' as const;
+
+/**
+ * Flush trigger margins (token counts) — aligned with upstream upstream.
+ *
+ * Sources:
+ * - `upstream reference` → softThreshold=4000
+ * - `upstream reference` → reserveFloor=20000
+ */
+export const DEFAULT_FLUSH_SOFT_THRESHOLD_TOKENS = 4000;
+export const DEFAULT_FLUSH_RESERVE_FLOOR_TOKENS = 20000;
+
+/** Hard cap on append calls per flush phase — prevents runaway writes. */
+export const DEFAULT_MAX_APPENDS_PER_FLUSH = 20;
+
+/**
+ * Hard cap on agentic loop iterations inside {@link runMemoryFlush}.
+ *
+ * Each iteration = one model.invoke() followed by execution of any
+ * `memory_append` tool_calls it emits. Mirrors upstream's flush-plan
+ * loop cap; 8 is enough for ~2–3 reflections of batched notes while
+ * protecting against runaway cycles if the model refuses to stop.
+ */
+export const DEFAULT_MAX_FLUSH_ITERATIONS = 8;
+
+/** Path prefix enforced on every append. Paths outside this are rejected. */
+export const MEMORY_PATH_PREFIX = 'memory/';
+
+/** Tool names — kept as constants so server code + tests never drift. */
+export const MEMORY_SEARCH_TOOL_NAME = 'memory_search';
+export const MEMORY_GET_TOOL_NAME = 'memory_get';
+export const MEMORY_APPEND_TOOL_NAME = 'memory_append';
+
+/**
+ * Mandatory-recall description — the single most load-bearing line in the
+ * whole memory system. Do not soften, shorten, or reword without an eval run.
+ *
+ * Ported VERBATIM from upstream `extensions/memory-core/src/tools.ts:186`.
+ * The wiki/corpus clause is retained even though Phase 1 doesn't ship
+ * compiled-wiki supplements — keeping the string identical means upstream's
+ * eval corpora remain drop-in valid.
+ */
+export const MEMORY_SEARCH_DESCRIPTION =
+  'Mandatory recall step: semantically search MEMORY.md + memory/*.md ' +
+  '(and optional session transcripts) before answering questions about ' +
+  'prior work, decisions, dates, people, preferences, or todos. Optional ' +
+  '`corpus=wiki` or `corpus=all` also searches registered compiled-wiki ' +
+  'supplements. If response has disabled=true, memory retrieval is ' +
+  'unavailable and should be surfaced to the user.';
+
+/**
+ * Ported VERBATIM from upstream `extensions/memory-core/src/tools.ts:322`.
+ */
+export const MEMORY_GET_DESCRIPTION =
+  'Safe snippet read from MEMORY.md or memory/*.md with optional from/lines; ' +
+  '`corpus=wiki` reads from registered compiled-wiki supplements. Use after ' +
+  'search to pull only the needed lines and keep context small.';
+
+/**
+ * `memory_append` tool description.
+ *
+ * Phase 1 historically wrote to a single date-keyed file
+ * (`memory/YYYY-MM-DD.md`), ported verbatim from upstream. That scheme
+ * is now replaced by an 8-path canonical whitelist — see
+ * {@link ./paths.MEMORY_ALL_PATHS}. The tool description no longer
+ * names a specific file; the flush-turn prompt renders the full rubric
+ * inline so the model sees every writable path at inference time.
+ */
+export const MEMORY_APPEND_DESCRIPTION =
+  "Append a durable note to one of the agent's canonical memory documents. " +
+  'The `path` argument MUST be one of the whitelisted paths listed in the ' +
+  'flush prompt rubric — unknown paths are rejected. Content is merged into ' +
+  'the existing row for that document via UPSERT, so the same document ' +
+  'accumulates across sessions.';
+
+/**
+ * Reply token that signals the flush turn produced no user-visible output.
+ * Ported VERBATIM from upstream `src/auto-reply/tokens.ts:4`.
+ */
+export const SILENT_REPLY_TOKEN = 'NO_REPLY';
+
+/**
+ * Placeholder replaced at flush time with the rendered path-rubric for
+ * the caller's scope. See `renderPathsRubric()` in `./paths.ts` and
+ * `resolveFlushPrompts()` in `../prompts/memoryFlushPrompt.ts`.
+ *
+ * Kept as a unique sentinel so `replaceAll` is safe even if the rubric
+ * content happens to contain regex metacharacters.
+ */
+export const FLUSH_PROMPT_RUBRIC_PLACEHOLDER = '{{MEMORY_PATHS_RUBRIC}}';
+
+/**
+ * Memory-flush prompts — canonical-document model.
+ *
+ * Every durable memory routes into one of 8 stable canonical documents
+ * (4 agent-tier + 4 user-tier). The rubric is injected at flush time so
+ * the model reads the authoritative path list with descriptions, and for
+ * isolated/autonomous agents the user-tier rows are transparently omitted
+ * from the rubric — making "user-tier writes require a scoped caller" a
+ * compile-time guarantee rather than a runtime check alone.
+ *
+ * Two-tier semantics the prompt enforces:
+ *   - **agent/** — shared operational knowledge; every user of this agent
+ *     benefits from rows written here. Do NOT put personal facts here.
+ *   - **user/** — personalization for the specific caller only. Row is
+ *     private to that user; other users never see it.
+ */
+const MEMORY_FLUSH_ROUTING_HINT =
+  'Route every note into exactly one of the canonical documents below by ' +
+  'picking the best match. Do NOT invent new paths; do NOT create date-keyed ' +
+  'files; unknown paths are rejected by the store.';
+
+const MEMORY_FLUSH_TIER_HINT =
+  'Two tiers: `memory/agent/*` is SHARED operational knowledge visible to ' +
+  'every user of this agent — put successful patterns, pitfalls, domain ' +
+  'facts, and house-style there. `memory/user/*` is PRIVATE to the specific ' +
+  'caller — put their identity, preferences, projects, and references there. ' +
+  'Never put user-specific facts in an agent/* document.';
+
+const MEMORY_FLUSH_READ_ONLY_HINT =
+  'Treat workspace bootstrap/reference files such as MEMORY.md, DREAMS.md, SOUL.md, TOOLS.md, and AGENTS.md as read-only during this flush; never overwrite, replace, or edit them.';
+
+/**
+ * Learning hint — steers the flush turn to capture the things that
+ * matter most for future turns: reusable patterns, tool failures
+ * (so the same mistake is not repeated), explicit corrections, and
+ * durable user-specific facts. Append-only via `memory_append`; one
+ * note per lesson.
+ */
+const MEMORY_FLUSH_LEARNING_HINT =
+  'Capture durable lessons the agent (and future turns) should retain: ' +
+  '(a) successful task patterns and workflows → memory/agent/playbook.md; ' +
+  '(b) tool failures and schema mistakes → memory/agent/pitfalls.md; ' +
+  '(c) stable domain facts about the systems/APIs → memory/agent/domain.md; ' +
+  "(d) this user's preferences, tone, and corrections → memory/user/preferences.md; " +
+  "(e) this user's identity and role → memory/user/profile.md. " +
+  'Write one note per distinct lesson. Do not log conversation summaries ' +
+  'or anything derivable from the code or recent history.';
+
+const MEMORY_FLUSH_RUBRIC_BLOCK =
+  'Canonical documents available for this turn (path — tag — description):\n' +
+  FLUSH_PROMPT_RUBRIC_PLACEHOLDER;
+
+export const DEFAULT_MEMORY_FLUSH_PROMPT = [
+  'Pre-compaction memory flush.',
+  MEMORY_FLUSH_ROUTING_HINT,
+  MEMORY_FLUSH_TIER_HINT,
+  MEMORY_FLUSH_READ_ONLY_HINT,
+  MEMORY_FLUSH_LEARNING_HINT,
+  'Call the `memory_append` tool for every note you want to persist, passing one of the whitelisted paths as the `path` argument. Do NOT describe what you are about to write; just call the tool.',
+  `If nothing worth storing, reply with exactly ${SILENT_REPLY_TOKEN}.`,
+  '',
+  MEMORY_FLUSH_RUBRIC_BLOCK,
+].join('\n');
+
+export const DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT = [
+  'Pre-compaction memory flush turn.',
+  'The session is near auto-compaction; capture durable memories to disk.',
+  MEMORY_FLUSH_ROUTING_HINT,
+  MEMORY_FLUSH_TIER_HINT,
+  MEMORY_FLUSH_READ_ONLY_HINT,
+  MEMORY_FLUSH_LEARNING_HINT,
+  'Use the `memory_append` tool for every durable note, with `path` set to one of the whitelisted canonical documents. Never claim you wrote a note without actually calling the tool.',
+  `If there is nothing worth storing, reply with exactly ${SILENT_REPLY_TOKEN}.`,
+  '',
+  MEMORY_FLUSH_RUBRIC_BLOCK,
+].join('\n');

package/src/memory/embeddings.ts

@@ -0,0 +1,188 @@
+/**
+ * Provider-agnostic embedding client for autonomous memory.
+ *
+ * Factory pattern mirrors host's `getSharedSummaryBedrockClient()` in
+ * `api/server/controllers/agents/client.js` — lazy init, shared instance,
+ * testable reset. Same AWS credential chain as host's existing Bedrock
+ * calls, so no new IAM policy or secret.
+ */
+import {
+  BedrockRuntimeClient,
+  InvokeModelCommand,
+} from '@aws-sdk/client-bedrock-runtime';
+import {
+  DEFAULT_MEMORY_DIMENSIONS,
+  DEFAULT_MEMORY_MODEL,
+  DEFAULT_MEMORY_PROVIDER,
+} from './constants';
+
+export type EmbeddingProviderKind = 'bedrock' | 'openai';
+
+export interface EmbeddingProvider {
+  readonly kind: EmbeddingProviderKind;
+  readonly model: string;
+  readonly dimensions: number;
+  embed(text: string): Promise<number[]>;
+  embedBatch(texts: string[]): Promise<number[][]>;
+}
+
+interface ResolvedEmbedderConfig {
+  provider: EmbeddingProviderKind;
+  model: string;
+  dimensions: number;
+}
+
+/**
+ * Read embedder config from environment. Called once per factory invocation;
+ * fresh reads make testing override-friendly via {@link resetMemoryEmbedder}.
+ */
+function resolveConfig(): ResolvedEmbedderConfig {
+  const rawProvider = (
+    process.env.MEMORY_EMBEDDINGS_PROVIDER ?? DEFAULT_MEMORY_PROVIDER
+  ).toLowerCase();
+  if (rawProvider !== 'bedrock' && rawProvider !== 'openai') {
+    throw new Error(
+      `Unsupported MEMORY_EMBEDDINGS_PROVIDER: "${rawProvider}". Supported: bedrock, openai.`
+    );
+  }
+  const model = process.env.MEMORY_EMBEDDINGS_MODEL ?? DEFAULT_MEMORY_MODEL;
+  const dimensions =
+    Number(process.env.MEMORY_EMBEDDINGS_DIMENSIONS) ||
+    DEFAULT_MEMORY_DIMENSIONS;
+  return { provider: rawProvider, model, dimensions };
+}
+
+class BedrockEmbedder implements EmbeddingProvider {
+  readonly kind = 'bedrock' as const;
+  readonly model: string;
+  readonly dimensions: number;
+  private client: BedrockRuntimeClient;
+
+  constructor(params: { model: string; dimensions: number }) {
+    this.model = params.model;
+    this.dimensions = params.dimensions;
+    const region =
+      process.env.BEDROCK_AWS_DEFAULT_REGION ??
+      process.env.AWS_REGION ??
+      'us-east-1';
+    // Default credential provider chain — identical to host's existing
+    // Bedrock client. In ECS this resolves to the task role.
+    this.client = new BedrockRuntimeClient({ region });
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const input = text.trim();
+    if (!input) {
+      throw new Error('Cannot embed empty text');
+    }
+    const body = {
+      inputText: input,
+      dimensions: this.dimensions,
+      normalize: true,
+    };
+    const command = new InvokeModelCommand({
+      modelId: this.model,
+      contentType: 'application/json',
+      accept: 'application/json',
+      body: new TextEncoder().encode(JSON.stringify(body)),
+    });
+    const response = await this.client.send(command);
+    const decoded = JSON.parse(new TextDecoder().decode(response.body)) as {
+      embedding: number[];
+    };
+    if (!Array.isArray(decoded.embedding)) {
+      throw new Error('Bedrock embedding response missing `embedding` field');
+    }
+    return decoded.embedding;
+  }
+
+  async embedBatch(texts: string[]): Promise<number[][]> {
+    // Titan embed v2 has no native batch API — sequential calls are the
+    // documented pattern. Parallelism here can trip per-account TPS ceilings,
+    // so we keep it serial. For Phase 4 we can introduce a bounded queue.
+    const out: number[][] = [];
+    for (const text of texts) {
+      out.push(await this.embed(text));
+    }
+    return out;
+  }
+}
+
+class OpenAIEmbedder implements EmbeddingProvider {
+  readonly kind = 'openai' as const;
+  readonly model: string;
+  readonly dimensions: number;
+  private apiKey: string;
+  private baseUrl: string;
+
+  constructor(params: { model: string; dimensions: number }) {
+    this.model = params.model;
+    this.dimensions = params.dimensions;
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        'OPENAI_API_KEY is not set — required when MEMORY_EMBEDDINGS_PROVIDER=openai'
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = process.env.OPENAI_BASEURL ?? 'https://api.openai.com/v1';
+  }
+
+  private async call(texts: string[]): Promise<number[][]> {
+    const res = await fetch(`${this.baseUrl}/embeddings`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({ model: this.model, input: texts }),
+    });
+    if (!res.ok) {
+      const errText = await res.text();
+      throw new Error(`OpenAI embeddings ${res.status}: ${errText}`);
+    }
+    const json = (await res.json()) as { data: Array<{ embedding: number[] }> };
+    return json.data.map((d) => d.embedding);
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const [vec] = await this.call([text]);
+    return vec;
+  }
+
+  async embedBatch(texts: string[]): Promise<number[][]> {
+    if (texts.length === 0) return [];
+    return this.call(texts);
+  }
+}
+
+let sharedEmbedder: EmbeddingProvider | null = null;
+
+/**
+ * Lazy singleton accessor. Same idiom as host's
+ * `getSharedSummaryBedrockClient()`.
+ */
+export function getMemoryEmbedder(): EmbeddingProvider {
+  if (sharedEmbedder) return sharedEmbedder;
+  const cfg = resolveConfig();
+  switch (cfg.provider) {
+    case 'bedrock':
+      sharedEmbedder = new BedrockEmbedder({
+        model: cfg.model,
+        dimensions: cfg.dimensions,
+      });
+      break;
+    case 'openai':
+      sharedEmbedder = new OpenAIEmbedder({
+        model: cfg.model,
+        dimensions: cfg.dimensions,
+      });
+      break;
+  }
+  return sharedEmbedder;
+}
+
+/** Test hook — drops the cached embedder so the next call re-reads env. */
+export function resetMemoryEmbedder(): void {
+  sharedEmbedder = null;
+}

package/src/memory/factory.ts

@@ -0,0 +1,111 @@
+/**
+ * Factory for building a memory backend from environment variables.
+ *
+ * Called once at startup by host's singleton (`api/server/services/memoryStore.js`).
+ * Returns `null` — never throws — when required env vars are missing, so
+ * agents with `memory_enabled=true` still run, just without memory. Host
+ * logs a single warning on boot instead of crashing.
+ */
+import { Pool } from 'pg';
+import { DEFAULT_MEMORY_TABLE } from './constants';
+import { PgvectorMemoryStore } from './pgvectorStore';
+import { runMemoryMigration } from './migrate';
+import { PgvectorRecallTracker, type RecallTracker } from './recallTracking';
+import type { MemoryBackend } from './types';
+
+export interface BuildMemoryBackendResult {
+  backend: MemoryBackend;
+  pool: Pool;
+  /** Phase 2 — shared recall tracker bound to the same pool/migration. */
+  recallTracker: RecallTracker;
+}
+
+interface PgConfig {
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+  database: string;
+  ssl: boolean;
+}
+
+function readPgConfig(): PgConfig | null {
+  // Dev shortcut: single URL overrides discrete fields if present.
+  const url = process.env.MEMORY_DATABASE_URL;
+  if (url) {
+    try {
+      const u = new URL(url);
+      return {
+        host: u.hostname,
+        port: Number(u.port || 5432),
+        user: decodeURIComponent(u.username),
+        password: decodeURIComponent(u.password),
+        database: u.pathname.replace(/^\//, ''),
+        ssl: (process.env.MEMORY_POSTGRES_SSL ?? 'disable') === 'require',
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  const host = process.env.MEMORY_POSTGRES_HOST;
+  const user = process.env.MEMORY_POSTGRES_USER;
+  const password = process.env.MEMORY_POSTGRES_PASSWORD;
+  const database = process.env.MEMORY_POSTGRES_DB;
+  if (!host || !user || !password || !database) {
+    return null;
+  }
+  return {
+    host,
+    port: Number(process.env.MEMORY_POSTGRES_PORT ?? 5432),
+    user,
+    password,
+    database,
+    ssl: (process.env.MEMORY_POSTGRES_SSL ?? 'disable') === 'require',
+  };
+}
+
+/**
+ * Try to build a configured memory backend. Returns null when the required
+ * env vars are absent — caller should log a single "memory disabled" warning
+ * and continue. Never throws on missing config.
+ */
+export async function buildMemoryBackendFromEnv(): Promise<BuildMemoryBackendResult | null> {
+  const cfg = readPgConfig();
+  if (!cfg) return null;
+
+  const pool = new Pool({
+    host: cfg.host,
+    port: cfg.port,
+    user: cfg.user,
+    password: cfg.password,
+    database: cfg.database,
+    ssl: cfg.ssl ? { rejectUnauthorized: false } : undefined,
+    max: 10,
+  });
+
+  const table = process.env.MEMORY_TABLE_NAME ?? DEFAULT_MEMORY_TABLE;
+
+  try {
+    await runMemoryMigration({ pool, table });
+  } catch (err) {
+    // Migration failures ARE fatal — they mean dimension mismatch or
+    // permissions wrong, and silently running past that would produce
+    // corrupt or missing memory reads.
+    await pool.end().catch(() => undefined);
+    throw err;
+  }
+
+  const backend = new PgvectorMemoryStore({ pool, table });
+
+  // Phase 2 — recall tracker migration is best-effort at boot. If it fails,
+  // tool wiring continues with a null tracker rather than crashing host.
+  const recallTracker = new PgvectorRecallTracker(pool);
+  try {
+    await recallTracker.migrate();
+  } catch {
+    // [phase2-recall-tracking] debug: migration skipped — non-fatal
+  }
+
+  return { backend, pool, recallTracker };
+}

package/src/memory/index.ts

@@ -0,0 +1,46 @@
+/** Public entry point for the memory package. */
+export * from './types';
+export * from './constants';
+export * from './paths';
+export { PgvectorMemoryStore } from './pgvectorStore';
+export type { PgvectorStoreOptions } from './pgvectorStore';
+export { CompositeMemoryBackend } from './compositeBackend';
+export { getMemoryEmbedder, resetMemoryEmbedder } from './embeddings';
+export type { EmbeddingProvider, EmbeddingProviderKind } from './embeddings';
+export { runMemoryMigration } from './migrate';
+export type { MigrationOptions } from './migrate';
+export { buildMemoryBackendFromEnv } from './factory';
+export type { BuildMemoryBackendResult } from './factory';
+
+// Phase 2
+export {
+  mmrRerank,
+  applyMMRToMemoryHits,
+  DEFAULT_MMR_CONFIG,
+  tokenize,
+  jaccardSimilarity,
+  textSimilarity,
+  computeMMRScore,
+} from './mmr';
+export type { MMRConfig, MMRItem } from './mmr';
+export {
+  applyTemporalDecayToHits,
+  applyTemporalDecayToScore,
+  calculateTemporalDecayMultiplier,
+  parseMemoryDateFromPath,
+  isEvergreenMemoryPath,
+  DEFAULT_TEMPORAL_DECAY_CONFIG,
+} from './temporalDecay';
+export type { TemporalDecayConfig, DecayCandidate } from './temporalDecay';
+export {
+  decorateCitations,
+  resolveMemoryCitationsMode,
+  shouldIncludeCitations,
+} from './citations';
+export type { MemoryCitationsMode, CitationCandidate } from './citations';
+export {
+  PgvectorRecallTracker,
+  NullRecallTracker,
+  RECALL_TABLE,
+} from './recallTracking';
+export type { RecallTracker, RecallRecordParams } from './recallTracking';

package/src/memory/migrate.ts

@@ -0,0 +1,116 @@
+/**
+ * Idempotent schema install + vector-dimension safety check.
+ *
+ * Called once at agents-library startup by host's `memoryStore.js` singleton
+ * factory. Safe to call multiple times — every statement is `IF NOT EXISTS`.
+ */
+import type { Pool } from 'pg';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { DEFAULT_MEMORY_DIMENSIONS, DEFAULT_MEMORY_TABLE } from './constants';
+import { getMemoryEmbedder } from './embeddings';
+
+export interface MigrationOptions {
+  pool: Pool;
+  table?: string;
+  /** If true, skip the live embedder probe (tests). */
+  skipEmbedderProbe?: boolean;
+}
+
+function resolveSchemaSqlPath(): string {
+  // Works under both ESM (import.meta.url) and compiled CJS (fall back to __dirname).
+  const meta = import.meta as unknown as { url?: string };
+  const metaUrl = typeof meta.url === 'string' ? meta.url : undefined;
+  if (metaUrl) {
+    return join(dirname(fileURLToPath(metaUrl)), 'schema.sql');
+  }
+  const globalDirname = (globalThis as unknown as { __dirname?: string })
+    .__dirname;
+  return join(globalDirname ?? process.cwd(), 'schema.sql');
+}
+
+export async function runMemoryMigration(
+  opts: MigrationOptions
+): Promise<void> {
+  const table = opts.table ?? DEFAULT_MEMORY_TABLE;
+  const schemaPath = resolveSchemaSqlPath();
+  const schemaSql = readFileSync(schemaPath, 'utf8').replace(
+    /agent_memories/g,
+    table
+  );
+
+  // Drop the legacy `(agent_id, path)` unique constraint BEFORE running
+  // the schema SQL. The schema creates the new
+  // `(agent_id, user_id, path)` NULLS-NOT-DISTINCT constraint, which
+  // must not collide with the old one. Dropping by the legacy name is a
+  // no-op on fresh installs where the constraint never existed, and on
+  // upgrades it cleanly frees the unique-index slot so the new
+  // constraint can be installed.
+  await opts.pool
+    .query(
+      `ALTER TABLE ${table} DROP CONSTRAINT IF EXISTS ${table}_agent_path_uq`
+    )
+    .catch(() => undefined);
+
+  await opts.pool.query(schemaSql);
+
+  // Adopt legacy rows if the table pre-existed with an older shape.
+  // Idempotent — every statement is no-op-safe on a fresh schema.
+  await opts.pool
+    .query(`ALTER TABLE ${table} ALTER COLUMN user_id DROP NOT NULL`)
+    .catch(() => undefined);
+  await opts.pool.query(
+    `ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`
+  );
+  await opts.pool.query(
+    `ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS last_user_id TEXT`
+  );
+  // Belt-and-suspenders: if the schema CREATE was skipped because the
+  // table already existed AND the new constraint was absent, add it
+  // explicitly. Swallow duplicate-object errors on happy-path re-runs.
+  await opts.pool
+    .query(
+      `ALTER TABLE ${table}
+         ADD CONSTRAINT ${table}_agent_user_path_uq
+         UNIQUE NULLS NOT DISTINCT (agent_id, user_id, path)`
+    )
+    .catch(() => undefined);
+
+  if (opts.skipEmbedderProbe) return;
+
+  // Vector dimension sanity check — refuses to serve if the column width
+  // disagrees with the live embedder and the table has data. See plan §3.
+  const embedder = getMemoryEmbedder();
+  const liveDim = embedder.dimensions || DEFAULT_MEMORY_DIMENSIONS;
+
+  // pgvector stores the declared width directly in atttypmod (unlike varchar
+  // which uses atttypmod = N + VARHDRSZ). Reading it raw gives the true dim.
+  const dimResult = await opts.pool.query(
+    `
+    SELECT atttypmod AS dim
+    FROM pg_attribute
+    WHERE attrelid = to_regclass($1)
+      AND attname = 'embedding'
+    `,
+    [table]
+  );
+  const columnDim = dimResult.rows[0]?.dim;
+  if (columnDim && Number(columnDim) !== liveDim) {
+    const countRes = await opts.pool.query(
+      `SELECT COUNT(*)::int AS n FROM ${table}`
+    );
+    const rowCount = Number(countRes.rows[0]?.n ?? 0);
+    if (rowCount === 0) {
+      await opts.pool.query(
+        `ALTER TABLE ${table} ALTER COLUMN embedding TYPE VECTOR(${liveDim})`
+      );
+    } else {
+      throw new Error(
+        `Memory vector dimension mismatch: column is VECTOR(${columnDim}) but ` +
+          `embedder "${embedder.model}" produces ${liveDim}-d vectors, and ${rowCount} ` +
+          `rows exist. Refusing to serve memory. Admin must run a reindex job.`
+      );
+    }
+  }
+}