@illuma-ai/agents 1.1.25 → 1.3.0

package/dist/esm/memory/migrate.mjs

@@ -0,0 +1,78 @@
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { DEFAULT_MEMORY_TABLE, DEFAULT_MEMORY_DIMENSIONS } from './constants.mjs';
+import { getMemoryEmbedder } from './embeddings.mjs';
+
+function resolveSchemaSqlPath() {
+    // Works under both ESM (import.meta.url) and compiled CJS (fall back to __dirname).
+    const meta = import.meta;
+    const metaUrl = typeof meta.url === 'string' ? meta.url : undefined;
+    if (metaUrl) {
+        return join(dirname(fileURLToPath(metaUrl)), 'schema.sql');
+    }
+    const globalDirname = globalThis
+        .__dirname;
+    return join(globalDirname ?? process.cwd(), 'schema.sql');
+}
+async function runMemoryMigration(opts) {
+    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.`);
+        }
+    }
+}
+
+export { runMemoryMigration };
+//# sourceMappingURL=migrate.mjs.map

package/dist/esm/memory/migrate.mjs.map

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

package/dist/esm/memory/mmr.mjs

@@ -0,0 +1,130 @@
+/**
+ * Maximal Marginal Relevance (MMR) re-ranking — Phase 2.
+ *
+ * Ported from upstream `extensions/memory-core/src/memory/mmr.ts` with
+ * minor adaptation for our `MemoryEntry` shape (content vs snippet, id vs
+ * path+startLine). Behavior is identical: normalize scores, iteratively
+ * pick the item that maximizes `λ * relevance - (1-λ) * max_similarity`
+ * using Jaccard on tokenized content.
+ *
+ * @see Carbonell & Goldstein, "The Use of MMR, Diversity-Based Reranking" (1998)
+ */
+const DEFAULT_MMR_CONFIG = {
+    enabled: false,
+    lambda: 0.7,
+};
+/**
+ * CJK Unified Ideographs + Extension A, Hiragana/Katakana, Hangul.
+ * These lack whitespace boundaries so we must tokenize them differently.
+ */
+const CJK_RE = /[\u3040-\u309f\u30a0-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uac00-\ud7af\u1100-\u11ff]/;
+/**
+ * Tokenize content into a set for Jaccard similarity.
+ *
+ * ASCII: alphanumeric + underscore runs, lowercased.
+ * CJK: each char becomes a unigram; consecutive pairs become a bigram.
+ * Non-adjacent CJK chars (e.g. `我a好`) do NOT form a bigram.
+ */
+function tokenize(text) {
+    const lower = (text ?? '').toLowerCase();
+    const ascii = lower.match(/[a-z0-9_]+/g) ?? [];
+    const chars = Array.from(lower);
+    const cjkData = [];
+    for (let i = 0; i < chars.length; i++) {
+        if (CJK_RE.test(chars[i]))
+            cjkData.push({ char: chars[i], index: i });
+    }
+    const bigrams = [];
+    for (let i = 0; i < cjkData.length - 1; i++) {
+        if (cjkData[i + 1].index === cjkData[i].index + 1) {
+            bigrams.push(cjkData[i].char + cjkData[i + 1].char);
+        }
+    }
+    return new Set([...ascii, ...bigrams, ...cjkData.map((d) => d.char)]);
+}
+function jaccardSimilarity(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    const [smaller, larger] = a.size <= b.size ? [a, b] : [b, a];
+    let intersection = 0;
+    for (const t of smaller)
+        if (larger.has(t))
+            intersection++;
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+function textSimilarity(a, b) {
+    return jaccardSimilarity(tokenize(a), tokenize(b));
+}
+function computeMMRScore(relevance, maxSimilarity, lambda) {
+    return lambda * relevance - (1 - lambda) * maxSimilarity;
+}
+/**
+ * Re-rank items using MMR. Returns a new array in MMR order.
+ */
+function mmrRerank(items, config = {}) {
+    const enabled = config.enabled ?? DEFAULT_MMR_CONFIG.enabled;
+    const rawLambda = config.lambda ?? DEFAULT_MMR_CONFIG.lambda;
+    if (!enabled || items.length <= 1)
+        return [...items];
+    const lambda = Math.max(0, Math.min(1, rawLambda));
+    if (lambda === 1)
+        return [...items].sort((a, b) => b.score - a.score);
+    const tokenCache = new Map();
+    for (const item of items)
+        tokenCache.set(item.id, tokenize(item.content));
+    const scores = items.map((i) => i.score);
+    const maxScore = Math.max(...scores);
+    const minScore = Math.min(...scores);
+    const range = maxScore - minScore;
+    const normalize = (s) => range === 0 ? 1 : (s - minScore) / range;
+    const selected = [];
+    const remaining = new Set(items);
+    while (remaining.size > 0) {
+        let best = null;
+        let bestMMR = -Infinity;
+        for (const cand of remaining) {
+            const rel = normalize(cand.score);
+            const candTokens = tokenCache.get(cand.id);
+            let maxSim = 0;
+            for (const sel of selected) {
+                const sim = jaccardSimilarity(candTokens, tokenCache.get(sel.id));
+                if (sim > maxSim)
+                    maxSim = sim;
+            }
+            const mmr = computeMMRScore(rel, maxSim, lambda);
+            if (mmr > bestMMR ||
+                (mmr === bestMMR && cand.score > (best?.score ?? -Infinity))) {
+                bestMMR = mmr;
+                best = cand;
+            }
+        }
+        if (!best)
+            break;
+        selected.push(best);
+        remaining.delete(best);
+    }
+    return selected;
+}
+/**
+ * Adapter: apply MMR to an array of MemoryEntry-shaped hits.
+ *
+ * Uses (path|id|index) as the stable ID so two hits from the same file at
+ * different content still get distinct MMR identities.
+ */
+function applyMMRToMemoryHits(results, config = {}) {
+    if (results.length <= 1)
+        return results;
+    const byId = new Map();
+    const items = results.map((r, i) => {
+        const id = `${r.path}#${r.id}#${i}`;
+        byId.set(id, r);
+        return { id, score: r.score, content: r.content };
+    });
+    return mmrRerank(items, config).map((m) => byId.get(m.id));
+}
+
+export { DEFAULT_MMR_CONFIG, applyMMRToMemoryHits, computeMMRScore, jaccardSimilarity, mmrRerank, textSimilarity, tokenize };
+//# sourceMappingURL=mmr.mjs.map

package/dist/esm/memory/mmr.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mmr.mjs","sources":["../../../src/memory/mmr.ts"],"sourcesContent":["/**\n * Maximal Marginal Relevance (MMR) re-ranking — Phase 2.\n *\n * Ported from upstream `extensions/memory-core/src/memory/mmr.ts` with\n * minor adaptation for our `MemoryEntry` shape (content vs snippet, id vs\n * path+startLine). Behavior is identical: normalize scores, iteratively\n * pick the item that maximizes `λ * relevance - (1-λ) * max_similarity`\n * using Jaccard on tokenized content.\n *\n * @see Carbonell & Goldstein, \"The Use of MMR, Diversity-Based Reranking\" (1998)\n */\n\nexport interface MMRConfig {\n  /** Opt-in. Upstream default is false. */\n  enabled: boolean;\n  /** 0 = max diversity, 1 = max relevance. Upstream default 0.7. */\n  lambda: number;\n}\n\nexport const DEFAULT_MMR_CONFIG: MMRConfig = {\n  enabled: false,\n  lambda: 0.7,\n};\n\n/**\n * CJK Unified Ideographs + Extension A, Hiragana/Katakana, Hangul.\n * These lack whitespace boundaries so we must tokenize them differently.\n */\nconst CJK_RE =\n  /[\\u3040-\\u309f\\u30a0-\\u30ff\\u3400-\\u4dbf\\u4e00-\\u9fff\\uac00-\\ud7af\\u1100-\\u11ff]/;\n\n/**\n * Tokenize content into a set for Jaccard similarity.\n *\n * ASCII: alphanumeric + underscore runs, lowercased.\n * CJK: each char becomes a unigram; consecutive pairs become a bigram.\n * Non-adjacent CJK chars (e.g. `我a好`) do NOT form a bigram.\n */\nexport function tokenize(text: string): Set<string> {\n  const lower = (text ?? '').toLowerCase();\n  const ascii = lower.match(/[a-z0-9_]+/g) ?? [];\n\n  const chars = Array.from(lower);\n  const cjkData: Array<{ char: string; index: number }> = [];\n  for (let i = 0; i < chars.length; i++) {\n    if (CJK_RE.test(chars[i])) cjkData.push({ char: chars[i], index: i });\n  }\n\n  const bigrams: string[] = [];\n  for (let i = 0; i < cjkData.length - 1; i++) {\n    if (cjkData[i + 1].index === cjkData[i].index + 1) {\n      bigrams.push(cjkData[i].char + cjkData[i + 1].char);\n    }\n  }\n\n  return new Set([...ascii, ...bigrams, ...cjkData.map((d) => d.char)]);\n}\n\nexport function jaccardSimilarity(a: Set<string>, b: Set<string>): number {\n  if (a.size === 0 && b.size === 0) return 1;\n  if (a.size === 0 || b.size === 0) return 0;\n\n  const [smaller, larger] = a.size <= b.size ? [a, b] : [b, a];\n  let intersection = 0;\n  for (const t of smaller) if (larger.has(t)) intersection++;\n  const union = a.size + b.size - intersection;\n  return union === 0 ? 0 : intersection / union;\n}\n\nexport function textSimilarity(a: string, b: string): number {\n  return jaccardSimilarity(tokenize(a), tokenize(b));\n}\n\nexport function computeMMRScore(\n  relevance: number,\n  maxSimilarity: number,\n  lambda: number\n): number {\n  return lambda * relevance - (1 - lambda) * maxSimilarity;\n}\n\nexport interface MMRItem {\n  id: string;\n  score: number;\n  content: string;\n}\n\n/**\n * Re-rank items using MMR. Returns a new array in MMR order.\n */\nexport function mmrRerank<T extends MMRItem>(\n  items: T[],\n  config: Partial<MMRConfig> = {}\n): T[] {\n  const enabled = config.enabled ?? DEFAULT_MMR_CONFIG.enabled;\n  const rawLambda = config.lambda ?? DEFAULT_MMR_CONFIG.lambda;\n\n  if (!enabled || items.length <= 1) return [...items];\n\n  const lambda = Math.max(0, Math.min(1, rawLambda));\n  if (lambda === 1) return [...items].sort((a, b) => b.score - a.score);\n\n  const tokenCache = new Map<string, Set<string>>();\n  for (const item of items) tokenCache.set(item.id, tokenize(item.content));\n\n  const scores = items.map((i) => i.score);\n  const maxScore = Math.max(...scores);\n  const minScore = Math.min(...scores);\n  const range = maxScore - minScore;\n  const normalize = (s: number): number =>\n    range === 0 ? 1 : (s - minScore) / range;\n\n  const selected: T[] = [];\n  const remaining = new Set(items);\n\n  while (remaining.size > 0) {\n    let best: T | null = null;\n    let bestMMR = -Infinity;\n    for (const cand of remaining) {\n      const rel = normalize(cand.score);\n      const candTokens = tokenCache.get(cand.id)!;\n      let maxSim = 0;\n      for (const sel of selected) {\n        const sim = jaccardSimilarity(candTokens, tokenCache.get(sel.id)!);\n        if (sim > maxSim) maxSim = sim;\n      }\n      const mmr = computeMMRScore(rel, maxSim, lambda);\n      if (\n        mmr > bestMMR ||\n        (mmr === bestMMR && cand.score > (best?.score ?? -Infinity))\n      ) {\n        bestMMR = mmr;\n        best = cand;\n      }\n    }\n    if (!best) break;\n    selected.push(best);\n    remaining.delete(best);\n  }\n\n  return selected;\n}\n\n/**\n * Adapter: apply MMR to an array of MemoryEntry-shaped hits.\n *\n * Uses (path|id|index) as the stable ID so two hits from the same file at\n * different content still get distinct MMR identities.\n */\nexport function applyMMRToMemoryHits<\n  T extends { id: string; path: string; content: string; score: number },\n>(results: T[], config: Partial<MMRConfig> = {}): T[] {\n  if (results.length <= 1) return results;\n  const byId = new Map<string, T>();\n  const items: MMRItem[] = results.map((r, i) => {\n    const id = `${r.path}#${r.id}#${i}`;\n    byId.set(id, r);\n    return { id, score: r.score, content: r.content };\n  });\n  return mmrRerank(items, config).map((m) => byId.get(m.id)!);\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/memory/paths.mjs

@@ -0,0 +1,207 @@
+import { MEMORY_PATH_PREFIX } from './constants.mjs';
+
+/**
+ * Autonomous memory — canonical path whitelist + tier utilities.
+ *
+ * Single source of truth for the 8 stable memory documents. Every write
+ * goes through {@link assertWritablePath}; every reader can ask
+ * {@link getTierForPath} what a row belongs to. Adding or removing a
+ * path means editing this file — and exactly this file.
+ *
+ * ## Why a whitelist?
+ *
+ * Earlier upstream-faithful designs used date-keyed files
+ * (`memory/YYYY-MM-DD.md`), which have three problems for a persistent
+ * multi-user agent:
+ *
+ * 1. **Unbounded growth** — one row per day per agent per user, forever.
+ * 2. **LLM routing ambiguity** — "which date file do I read?" has no
+ *    good answer, so the model reads (and ranks against) all of them.
+ * 3. **No natural deduplication** — the same fact written across three
+ *    days returns three near-identical hits.
+ *
+ * With 8 stable canonical documents the LLM knows *exactly* where to
+ * write ("is this a preference? → `memory/user/preferences.md`") and
+ * each row accumulates via UPSERT instead of piling up new rows.
+ *
+ * ## Two tiers
+ *
+ * - **Agent tier** (`memory/agent/*`) — operational knowledge that
+ *   every caller of the agent benefits from. Stored with `user_id = NULL`.
+ *   Shared across all users of a collaborative agent; the only tier that
+ *   exists for isolated/autonomous agents with no invoker.
+ *
+ * - **User tier** (`memory/user/*`) — per-invoker personalization.
+ *   Stored with `user_id = <caller>`. Read path filters so User A never
+ *   sees User B's rows, even for the same agent. Not writable unless the
+ *   flush scope carries a non-empty `userId`.
+ *
+ * The tier of a path is a function of its prefix (`memory/agent/` vs
+ * `memory/user/`), so adding a new document is one line here + the
+ * constant array entry; no store or route code has to change.
+ */
+/** Agent-tier documents — shared across all users of the agent. */
+const MEMORY_AGENT_PATHS = Object.freeze([
+    Object.freeze({
+        path: 'memory/agent/playbook.md',
+        tier: 'agent',
+        label: 'Playbook',
+        description: 'Successful task patterns and workflows that have worked for this agent — ' +
+            'reusable recipes, known-good tool sequences, approaches that consistently ' +
+            'produce the right result.',
+    }),
+    Object.freeze({
+        path: 'memory/agent/pitfalls.md',
+        tier: 'agent',
+        label: 'Pitfalls',
+        description: 'Tool failures, error recoveries, schema mistakes, and invalid argument ' +
+            'shapes the agent has seen — so the same mistake is not repeated on future ' +
+            'turns. One note per distinct failure mode.',
+    }),
+    Object.freeze({
+        path: 'memory/agent/domain.md',
+        tier: 'agent',
+        label: 'Domain',
+        description: 'Durable facts about the systems, APIs, data models, and business rules ' +
+            'this agent operates on — things that are true independent of any one user ' +
+            'and that the agent repeatedly needs to know.',
+    }),
+    Object.freeze({
+        path: 'memory/agent/style.md',
+        tier: 'agent',
+        label: 'Style',
+        description: 'Tone, formatting, and response-shape conventions the agent has converged ' +
+            'on across the whole user base. Do NOT write user-specific preferences here ' +
+            '(those belong under the user tier).',
+    }),
+]);
+/** User-tier documents — per-invoker, never shared across users. */
+const MEMORY_USER_PATHS = Object.freeze([
+    Object.freeze({
+        path: 'memory/user/profile.md',
+        tier: 'user',
+        label: 'Profile',
+        description: "This specific user's identity — name, role, team, sign-off name, " +
+            'responsibilities, stable facts about who they are. Only facts ' +
+            'volunteered by the user themselves.',
+    }),
+    Object.freeze({
+        path: 'memory/user/preferences.md',
+        tier: 'user',
+        label: 'Preferences',
+        description: 'How THIS user wants things done — preferred formats, verbosity, tone, ' +
+            'cadence, output length, language conventions. Explicit corrections they ' +
+            'have given count as preferences.',
+    }),
+    Object.freeze({
+        path: 'memory/user/projects.md',
+        tier: 'user',
+        label: 'Projects',
+        description: "This user's current initiatives, ongoing work, deadlines, and active " +
+            'project context. Include dates in the prose when relevant. Retire entries ' +
+            'by overwriting them on future flushes when the user indicates a project is done.',
+    }),
+    Object.freeze({
+        path: 'memory/user/references.md',
+        tier: 'user',
+        label: 'References',
+        description: 'External systems, dashboards, accounts, links, channels, and resources ' +
+            "THIS user has pointed the agent at — the 'where to look' pointers that " +
+            'make later turns more efficient.',
+    }),
+]);
+/** All 8 canonical documents in display order: agent tier first, user tier second. */
+const MEMORY_ALL_PATHS = Object.freeze([
+    ...MEMORY_AGENT_PATHS,
+    ...MEMORY_USER_PATHS,
+]);
+/** Fast O(1) lookup map: path → descriptor. */
+const PATH_INDEX = new Map(MEMORY_ALL_PATHS.map((p) => [p.path, p]));
+/** Set of all whitelisted paths — for `has()` lookups. */
+const MEMORY_WRITABLE_PATHS = new Set(MEMORY_ALL_PATHS.map((p) => p.path));
+/** Returns the descriptor for a canonical path, or `undefined` if not on the whitelist. */
+function getPathDescriptor(path) {
+    return PATH_INDEX.get(path);
+}
+/**
+ * Returns the tier a given path belongs to.
+ *
+ * For unknown paths (e.g. legacy date-keyed rows that predate this schema),
+ * falls back to inspecting the `memory/agent/` or `memory/user/` prefix.
+ * Anything that matches neither is classified as `agent` — it will surface
+ * in the admin UI under the agent-tier header and stay read-only there.
+ */
+function getTierForPath(path) {
+    const descriptor = PATH_INDEX.get(path);
+    if (descriptor)
+        return descriptor.tier;
+    if (path.startsWith('memory/user/'))
+        return 'user';
+    return 'agent';
+}
+/**
+ * Paths that are legal to write **for this caller's scope**.
+ *
+ * If `scope.userId` is absent (isolated/autonomous agent), the user-tier
+ * paths are dropped. This is the list the flush prompt renders into its
+ * rubric — the LLM never sees paths it cannot write to.
+ */
+function getWritablePathsForScope(scope) {
+    if (scope.userId == null || scope.userId === '') {
+        return MEMORY_AGENT_PATHS;
+    }
+    return MEMORY_ALL_PATHS;
+}
+/**
+ * Validates a write path against the whitelist AND the caller's scope.
+ *
+ * Throws with an actionable message when:
+ * - the path is missing the `memory/` prefix
+ * - the path is not on the 8-doc whitelist
+ * - the path is user-tier but `scope.userId` is missing
+ *
+ * The store's append() is the single call site; other callers should
+ * never hit this directly. Kept as a standalone function for testability.
+ */
+function assertWritablePath(path, scope) {
+    if (!path || !path.startsWith(MEMORY_PATH_PREFIX)) {
+        throw new Error(`memory_append path must start with "${MEMORY_PATH_PREFIX}" (received "${path}")`);
+    }
+    const descriptor = PATH_INDEX.get(path);
+    if (!descriptor) {
+        throw new Error(`memory_append path "${path}" is not on the canonical whitelist. ` +
+            `Allowed: ${MEMORY_ALL_PATHS.map((p) => p.path).join(', ')}`);
+    }
+    if (descriptor.tier === 'user' &&
+        (scope.userId == null || scope.userId === '')) {
+        throw new Error(`memory_append to user-tier path "${path}" requires a caller userId in scope, ` +
+            `but scope.userId is missing. This path is private to a specific user and ` +
+            `cannot be written from an isolated/autonomous context.`);
+    }
+    return descriptor;
+}
+/**
+ * Renders the whitelist as a compact bullet list, used inside the flush
+ * prompt so the LLM sees the authoritative rubric at inference time.
+ *
+ * Output shape:
+ *   - memory/agent/playbook.md [Playbook, shared] — <description>
+ *   - memory/agent/pitfalls.md [Pitfalls, shared] — <description>
+ *   ...
+ *
+ * The `[Label, shared|private]` tag tells the model whether the doc is
+ * visible to all users (agent tier) or only to the caller (user tier).
+ * Filtered to only the paths writable for the given scope.
+ */
+function renderPathsRubric(scope) {
+    const writable = getWritablePathsForScope(scope);
+    return writable
+        .map((p) => {
+        const visibility = p.tier === 'agent' ? 'shared' : 'private';
+        return `- ${p.path} [${p.label}, ${visibility}] — ${p.description}`;
+    })
+        .join('\n');
+}
+
+export { MEMORY_AGENT_PATHS, MEMORY_ALL_PATHS, MEMORY_USER_PATHS, MEMORY_WRITABLE_PATHS, assertWritablePath, getPathDescriptor, getTierForPath, getWritablePathsForScope, renderPathsRubric };
+//# sourceMappingURL=paths.mjs.map

package/dist/esm/memory/paths.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.mjs","sources":["../../../src/memory/paths.ts"],"sourcesContent":["/**\n * Autonomous memory — canonical path whitelist + tier utilities.\n *\n * Single source of truth for the 8 stable memory documents. Every write\n * goes through {@link assertWritablePath}; every reader can ask\n * {@link getTierForPath} what a row belongs to. Adding or removing a\n * path means editing this file — and exactly this file.\n *\n * ## Why a whitelist?\n *\n * Earlier upstream-faithful designs used date-keyed files\n * (`memory/YYYY-MM-DD.md`), which have three problems for a persistent\n * multi-user agent:\n *\n * 1. **Unbounded growth** — one row per day per agent per user, forever.\n * 2. **LLM routing ambiguity** — \"which date file do I read?\" has no\n *    good answer, so the model reads (and ranks against) all of them.\n * 3. **No natural deduplication** — the same fact written across three\n *    days returns three near-identical hits.\n *\n * With 8 stable canonical documents the LLM knows *exactly* where to\n * write (\"is this a preference? → `memory/user/preferences.md`\") and\n * each row accumulates via UPSERT instead of piling up new rows.\n *\n * ## Two tiers\n *\n * - **Agent tier** (`memory/agent/*`) — operational knowledge that\n *   every caller of the agent benefits from. Stored with `user_id = NULL`.\n *   Shared across all users of a collaborative agent; the only tier that\n *   exists for isolated/autonomous agents with no invoker.\n *\n * - **User tier** (`memory/user/*`) — per-invoker personalization.\n *   Stored with `user_id = <caller>`. Read path filters so User A never\n *   sees User B's rows, even for the same agent. Not writable unless the\n *   flush scope carries a non-empty `userId`.\n *\n * The tier of a path is a function of its prefix (`memory/agent/` vs\n * `memory/user/`), so adding a new document is one line here + the\n * constant array entry; no store or route code has to change.\n */\n\nimport { MEMORY_PATH_PREFIX } from './constants';\nimport type { MemoryScope } from './types';\n\n/** Tier discriminator — the two kinds of memory a row can belong to. */\nexport type MemoryTier = 'agent' | 'user';\n\n/** Every canonical document the flush phase is allowed to write. */\nexport interface MemoryPathDescriptor {\n  /** Full path including the `memory/` prefix. */\n  path: string;\n  /** Which tier the path lives under. */\n  tier: MemoryTier;\n  /** Short label shown in UI tier badges and the flush prompt rubric. */\n  label: string;\n  /** One-line description — fed to the LLM to make routing unambiguous. */\n  description: string;\n}\n\n/** Agent-tier documents — shared across all users of the agent. */\nexport const MEMORY_AGENT_PATHS: readonly MemoryPathDescriptor[] =\n  Object.freeze([\n    Object.freeze({\n      path: 'memory/agent/playbook.md',\n      tier: 'agent' as const,\n      label: 'Playbook',\n      description:\n        'Successful task patterns and workflows that have worked for this agent — ' +\n        'reusable recipes, known-good tool sequences, approaches that consistently ' +\n        'produce the right result.',\n    }),\n    Object.freeze({\n      path: 'memory/agent/pitfalls.md',\n      tier: 'agent' as const,\n      label: 'Pitfalls',\n      description:\n        'Tool failures, error recoveries, schema mistakes, and invalid argument ' +\n        'shapes the agent has seen — so the same mistake is not repeated on future ' +\n        'turns. One note per distinct failure mode.',\n    }),\n    Object.freeze({\n      path: 'memory/agent/domain.md',\n      tier: 'agent' as const,\n      label: 'Domain',\n      description:\n        'Durable facts about the systems, APIs, data models, and business rules ' +\n        'this agent operates on — things that are true independent of any one user ' +\n        'and that the agent repeatedly needs to know.',\n    }),\n    Object.freeze({\n      path: 'memory/agent/style.md',\n      tier: 'agent' as const,\n      label: 'Style',\n      description:\n        'Tone, formatting, and response-shape conventions the agent has converged ' +\n        'on across the whole user base. Do NOT write user-specific preferences here ' +\n        '(those belong under the user tier).',\n    }),\n  ]);\n\n/** User-tier documents — per-invoker, never shared across users. */\nexport const MEMORY_USER_PATHS: readonly MemoryPathDescriptor[] = Object.freeze(\n  [\n    Object.freeze({\n      path: 'memory/user/profile.md',\n      tier: 'user' as const,\n      label: 'Profile',\n      description:\n        \"This specific user's identity — name, role, team, sign-off name, \" +\n        'responsibilities, stable facts about who they are. Only facts ' +\n        'volunteered by the user themselves.',\n    }),\n    Object.freeze({\n      path: 'memory/user/preferences.md',\n      tier: 'user' as const,\n      label: 'Preferences',\n      description:\n        'How THIS user wants things done — preferred formats, verbosity, tone, ' +\n        'cadence, output length, language conventions. Explicit corrections they ' +\n        'have given count as preferences.',\n    }),\n    Object.freeze({\n      path: 'memory/user/projects.md',\n      tier: 'user' as const,\n      label: 'Projects',\n      description:\n        \"This user's current initiatives, ongoing work, deadlines, and active \" +\n        'project context. Include dates in the prose when relevant. Retire entries ' +\n        'by overwriting them on future flushes when the user indicates a project is done.',\n    }),\n    Object.freeze({\n      path: 'memory/user/references.md',\n      tier: 'user' as const,\n      label: 'References',\n      description:\n        'External systems, dashboards, accounts, links, channels, and resources ' +\n        \"THIS user has pointed the agent at — the 'where to look' pointers that \" +\n        'make later turns more efficient.',\n    }),\n  ]\n);\n\n/** All 8 canonical documents in display order: agent tier first, user tier second. */\nexport const MEMORY_ALL_PATHS: readonly MemoryPathDescriptor[] = Object.freeze([\n  ...MEMORY_AGENT_PATHS,\n  ...MEMORY_USER_PATHS,\n]);\n\n/** Fast O(1) lookup map: path → descriptor. */\nconst PATH_INDEX: ReadonlyMap<string, MemoryPathDescriptor> = new Map(\n  MEMORY_ALL_PATHS.map((p) => [p.path, p])\n);\n\n/** Set of all whitelisted paths — for `has()` lookups. */\nexport const MEMORY_WRITABLE_PATHS: ReadonlySet<string> = new Set(\n  MEMORY_ALL_PATHS.map((p) => p.path)\n);\n\n/** Returns the descriptor for a canonical path, or `undefined` if not on the whitelist. */\nexport function getPathDescriptor(\n  path: string\n): MemoryPathDescriptor | undefined {\n  return PATH_INDEX.get(path);\n}\n\n/**\n * Returns the tier a given path belongs to.\n *\n * For unknown paths (e.g. legacy date-keyed rows that predate this schema),\n * falls back to inspecting the `memory/agent/` or `memory/user/` prefix.\n * Anything that matches neither is classified as `agent` — it will surface\n * in the admin UI under the agent-tier header and stay read-only there.\n */\nexport function getTierForPath(path: string): MemoryTier {\n  const descriptor = PATH_INDEX.get(path);\n  if (descriptor) return descriptor.tier;\n  if (path.startsWith('memory/user/')) return 'user';\n  return 'agent';\n}\n\n/**\n * Paths that are legal to write **for this caller's scope**.\n *\n * If `scope.userId` is absent (isolated/autonomous agent), the user-tier\n * paths are dropped. This is the list the flush prompt renders into its\n * rubric — the LLM never sees paths it cannot write to.\n */\nexport function getWritablePathsForScope(\n  scope: Pick<MemoryScope, 'userId'>\n): readonly MemoryPathDescriptor[] {\n  if (scope.userId == null || scope.userId === '') {\n    return MEMORY_AGENT_PATHS;\n  }\n  return MEMORY_ALL_PATHS;\n}\n\n/**\n * Validates a write path against the whitelist AND the caller's scope.\n *\n * Throws with an actionable message when:\n * - the path is missing the `memory/` prefix\n * - the path is not on the 8-doc whitelist\n * - the path is user-tier but `scope.userId` is missing\n *\n * The store's append() is the single call site; other callers should\n * never hit this directly. Kept as a standalone function for testability.\n */\nexport function assertWritablePath(\n  path: string,\n  scope: Pick<MemoryScope, 'userId'>\n): MemoryPathDescriptor {\n  if (!path || !path.startsWith(MEMORY_PATH_PREFIX)) {\n    throw new Error(\n      `memory_append path must start with \"${MEMORY_PATH_PREFIX}\" (received \"${path}\")`\n    );\n  }\n  const descriptor = PATH_INDEX.get(path);\n  if (!descriptor) {\n    throw new Error(\n      `memory_append path \"${path}\" is not on the canonical whitelist. ` +\n        `Allowed: ${MEMORY_ALL_PATHS.map((p) => p.path).join(', ')}`\n    );\n  }\n  if (\n    descriptor.tier === 'user' &&\n    (scope.userId == null || scope.userId === '')\n  ) {\n    throw new Error(\n      `memory_append to user-tier path \"${path}\" requires a caller userId in scope, ` +\n        `but scope.userId is missing. This path is private to a specific user and ` +\n        `cannot be written from an isolated/autonomous context.`\n    );\n  }\n  return descriptor;\n}\n\n/**\n * Renders the whitelist as a compact bullet list, used inside the flush\n * prompt so the LLM sees the authoritative rubric at inference time.\n *\n * Output shape:\n *   - memory/agent/playbook.md [Playbook, shared] — <description>\n *   - memory/agent/pitfalls.md [Pitfalls, shared] — <description>\n *   ...\n *\n * The `[Label, shared|private]` tag tells the model whether the doc is\n * visible to all users (agent tier) or only to the caller (user tier).\n * Filtered to only the paths writable for the given scope.\n */\nexport function renderPathsRubric(scope: Pick<MemoryScope, 'userId'>): string {\n  const writable = getWritablePathsForScope(scope);\n  return writable\n    .map((p) => {\n      const visibility = p.tier === 'agent' ? 'shared' : 'private';\n      return `- ${p.path} [${p.label}, ${visibility}] — ${p.description}`;\n    })\n    .join('\\n');\n}\n"],"names":[],"mappings":"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"}