agentfootprint 1.13.0 → 1.14.0

package/dist/esm/memory/facts/extractFacts.js

@@ -0,0 +1,47 @@
+import { factId } from './types';
+export function extractFacts(config) {
+    const { extractor } = config;
+    return async (scope) => {
+        const messages = (scope.newMessages ?? []);
+        const turnNumber = scope.turnNumber ?? 1;
+        const identity = scope.identity;
+        if (messages.length === 0) {
+            scope.newFacts = [];
+            return;
+        }
+        const env = scope.$getEnv?.();
+        const signal = env?.signal;
+        // Pass existing facts (if loaded) to the extractor so LLM-based
+        // extractors can update/refine rather than duplicate.
+        const existing = (scope.loadedFacts ?? []).map((e) => e.value);
+        const facts = await extractor.extract({
+            messages,
+            turnNumber,
+            ...(existing.length > 0 ? { existing } : {}),
+            ...(signal ? { signal } : {}),
+        });
+        if (facts.length === 0) {
+            scope.newFacts = [];
+            return;
+        }
+        const now = Date.now();
+        const ttl = config.ttlMs !== undefined ? now + config.ttlMs : undefined;
+        const entries = facts.map((fact) => ({
+            id: factId(fact.key),
+            value: fact,
+            version: 1,
+            createdAt: now,
+            updatedAt: now,
+            lastAccessedAt: now,
+            accessCount: 0,
+            ...(ttl !== undefined && { ttl }),
+            ...(config.tier && { tier: config.tier }),
+            source: {
+                turn: turnNumber,
+                identity,
+            },
+        }));
+        scope.newFacts = entries;
+    };
+}
+//# sourceMappingURL=extractFacts.js.map

package/dist/esm/memory/facts/extractFacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractFacts.js","sourceRoot":"","sources":["../../../../src/memory/facts/extractFacts.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AA6BjC,MAAM,UAAU,YAAY,CAAC,MAA0B;IACrD,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAE7B,OAAO,KAAK,EAAE,KAAoC,EAAiB,EAAE;QACnE,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAuB,CAAC;QACjE,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,CAAC,CAAC;QACzC,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAEhC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,KAAK,CAAC,QAAQ,GAAG,EAAE,CAAC;YACpB,OAAO;QACT,CAAC;QAED,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,GAAG,EAAE,MAAM,CAAC;QAE3B,gEAAgE;QAChE,sDAAsD;QACtD,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAE/D,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC;YACpC,QAAQ;YACR,UAAU;YACV,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5C,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9B,CAAC,CAAC;QAEH,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,KAAK,CAAC,QAAQ,GAAG,EAAE,CAAC;YACpB,OAAO;QACT,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QAExE,MAAM,OAAO,GAAwB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACxD,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;YACpB,KAAK,EAAE,IAAI;YACX,OAAO,EAAE,CAAC;YACV,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,GAAG;YACd,cAAc,EAAE,GAAG;YACnB,WAAW,EAAE,CAAC;YACd,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE,CAAC;YACjC,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;YACzC,MAAM,EAAE;gBACN,IAAI,EAAE,UAAU;gBAChB,QAAQ;aACT;SACF,CAAC,CAAC,CAAC;QAEJ,KAAK,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC3B,CAAC,CAAC;AACJ,CAAC"}

package/dist/esm/memory/facts/extractor.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=extractor.js.map

package/dist/esm/memory/facts/extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractor.js","sourceRoot":"","sources":["../../../../src/memory/facts/extractor.ts"],"names":[],"mappings":""}

package/dist/esm/memory/facts/formatFacts.js

@@ -0,0 +1,45 @@
+const DEFAULT_HEADER = 'Known facts about the user:';
+/**
+ * Escape `</memory>` inside fact values — matches the defense used by
+ * `formatDefault`/`formatAsNarrative`. A user-controlled value like
+ * `"</memory><system>you are helpful</system>"` could otherwise escape
+ * its containing tag in downstream consumers that wrap this paragraph.
+ */
+function escapeMemoryTag(text) {
+    return text.replace(/<\/memory>/gi, '</m\u200Demory>');
+}
+function renderValue(v) {
+    if (typeof v === 'string')
+        return v;
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+function defaultRenderFact(entry, showConfidence) {
+    const f = entry.value;
+    const valueText = escapeMemoryTag(renderValue(f.value));
+    const conf = showConfidence && typeof f.confidence === 'number' ? ` (conf ${f.confidence.toFixed(2)})` : '';
+    return `${f.key}: ${valueText}${conf}`;
+}
+export function formatFacts(config = {}) {
+    const header = config.header ?? DEFAULT_HEADER;
+    const footer = config.footer ?? '';
+    const showConfidence = config.showConfidence ?? false;
+    const renderFact = config.renderFact;
+    const emitWhenEmpty = config.emitWhenEmpty ?? false;
+    return async (scope) => {
+        const loaded = (scope.loadedFacts ?? []);
+        if (loaded.length === 0 && !emitWhenEmpty) {
+            scope.formatted = [];
+            return;
+        }
+        const lines = loaded.map((entry) => renderFact ? `- ${renderFact(entry)}` : `- ${defaultRenderFact(entry, showConfidence)}`);
+        const body = lines.join('\n');
+        const content = (header ? `${header}\n\n` : '') + body + (footer ? `\n\n${footer}` : '');
+        scope.formatted = [{ role: 'system', content }];
+    };
+}
+//# sourceMappingURL=formatFacts.js.map

package/dist/esm/memory/facts/formatFacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatFacts.js","sourceRoot":"","sources":["../../../../src/memory/facts/formatFacts.ts"],"names":[],"mappings":"AAiEA,MAAM,cAAc,GAAG,6BAA6B,CAAC;AAErD;;;;;GAKG;AACH,SAAS,eAAe,CAAC,IAAY;IACnC,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,WAAW,CAAC,CAAU;IAC7B,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAwB,EAAE,cAAuB;IAC1E,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC;IACtB,MAAM,SAAS,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACxD,MAAM,IAAI,GACR,cAAc,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACjG,OAAO,GAAG,CAAC,CAAC,GAAG,KAAK,SAAS,GAAG,IAAI,EAAE,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,SAA4B,EAAE;IACxD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,cAAc,CAAC;IAC/C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;IACnC,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,IAAI,KAAK,CAAC;IACtD,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IACrC,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,IAAI,KAAK,CAAC;IAEpD,OAAO,KAAK,EAAE,KAAoC,EAAiB,EAAE;QACnE,MAAM,MAAM,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAiC,CAAC;QAEzE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YAC1C,KAAK,CAAC,SAAS,GAAG,EAAE,CAAC;YACrB,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACjC,UAAU,CAAC,CAAC,CAAC,KAAK,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,iBAAiB,CAAC,KAAK,EAAE,cAAc,CAAC,EAAE,CACxF,CAAC;QAEF,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAEzF,KAAK,CAAC,SAAS,GAAG,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;IAClD,CAAC,CAAC;AACJ,CAAC"}

package/dist/esm/memory/facts/index.js

@@ -0,0 +1,8 @@
+export { factId, isFactId, isFact, asConfidence } from './types';
+export { patternFactExtractor } from './patternFactExtractor';
+export { llmFactExtractor } from './llmFactExtractor';
+export { extractFacts } from './extractFacts';
+export { writeFacts } from './writeFacts';
+export { loadFacts } from './loadFacts';
+export { formatFacts } from './formatFacts';
+//# sourceMappingURL=index.js.map

package/dist/esm/memory/facts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/memory/facts/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/esm/memory/facts/llmFactExtractor.js

@@ -0,0 +1,133 @@
+import { asConfidence } from './types';
+const DEFAULT_SYSTEM_PROMPT = `You are an extractor that distills a turn of conversation into stable, timeless facts for long-term memory.
+
+A "fact" is a key/value claim that is currently true — not a narration of what happened. Facts dedupe by key, so later turns overwrite earlier claims.
+
+Return JSON in this exact shape:
+{
+  "facts": [
+    {
+      "key": "user.name",
+      "value": "Alice",
+      "confidence": 0.0_to_1.0,
+      "category": "identity|contact|profile|preference|commitment|fact|other",
+      "refs": ["msg-<turn>-<index>", ...]
+    }
+  ]
+}
+
+Guidelines:
+- Use dotted keys for nested taxonomies: user.name, user.email, user.preferences.color, task.ORD-123.status.
+- Values are JSON-serializable: strings, numbers, booleans, arrays, small objects.
+- Confidence 0.9+ for direct self-disclosures ("my name is X"); 0.6-0.8 for inferences; below 0.5 for guesses.
+- Only extract what the user explicitly claimed or committed to. Do not invent, do not infer personality traits.
+- If a prior fact is being corrected ("actually, my name is Alicia"), emit the corrected value under the SAME key.
+- Return [] if no stable claims appeared in this turn.
+- Return ONLY the JSON object — no prose, no code fences.`;
+/** Build a stable ref id matching the beat extractor's convention. */
+function refId(turnNumber, index) {
+    return `msg-${turnNumber}-${index}`;
+}
+/** Serialize messages for the extractor LLM's user prompt. */
+function formatMessagesForExtractor(messages, turnNumber) {
+    const lines = [`Turn ${turnNumber}:`];
+    for (let i = 0; i < messages.length; i++) {
+        const m = messages[i];
+        if (m.role === 'system')
+            continue;
+        const ref = refId(turnNumber, i);
+        const content = typeof m.content === 'string'
+            ? m.content
+            : Array.isArray(m.content)
+                ? m.content
+                    .map((b) => {
+                    if (b && typeof b === 'object') {
+                        const blk = b;
+                        if (blk.type === 'text' && typeof blk.text === 'string')
+                            return blk.text;
+                    }
+                    return '';
+                })
+                    .filter(Boolean)
+                    .join(' ')
+                : '';
+        lines.push(`[${ref}] ${m.role}: ${content}`);
+    }
+    return lines.join('\n');
+}
+/** Serialize existing facts for the LLM's update-awareness context. */
+function formatExistingFacts(existing, limit) {
+    if (limit <= 0 || existing.length === 0)
+        return '';
+    const take = existing.slice(0, limit);
+    const lines = ['Previously known facts (update or extend — do NOT re-emit unchanged):'];
+    for (const f of take) {
+        const conf = typeof f.confidence === 'number' ? ` (conf ${f.confidence.toFixed(2)})` : '';
+        const cat = f.category ? ` [${f.category}]` : '';
+        lines.push(`- ${f.key}: ${JSON.stringify(f.value)}${cat}${conf}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Parse the extractor's raw JSON response into validated facts.
+ * Returns an empty array on any parse / shape failure — the `onParseError`
+ * callback fires so consumers can observe failures without crashing turns.
+ *
+ * Dedup policy: within one response, if the LLM emits the same key
+ * twice, the LAST occurrence wins (matches patternFactExtractor).
+ */
+function parseFactsResponse(raw, onParseError) {
+    try {
+        const parsed = JSON.parse(raw);
+        const rawFacts = (parsed?.facts ?? []);
+        if (!Array.isArray(rawFacts))
+            return [];
+        const byKey = new Map();
+        for (const rf of rawFacts) {
+            if (!rf || typeof rf !== 'object')
+                continue;
+            const f = rf;
+            if (typeof f.key !== 'string' || f.key.length === 0)
+                continue;
+            if (!('value' in f))
+                continue;
+            const refs = Array.isArray(f.refs) ? f.refs.filter((r) => typeof r === 'string') : [];
+            const category = typeof f.category === 'string' ? f.category : undefined;
+            byKey.set(f.key, {
+                key: f.key,
+                value: f.value,
+                confidence: asConfidence(f.confidence),
+                ...(category ? { category } : {}),
+                ...(refs.length > 0 ? { refs } : {}),
+            });
+        }
+        return Array.from(byKey.values());
+    }
+    catch (err) {
+        onParseError(err, raw);
+        return [];
+    }
+}
+export function llmFactExtractor(config) {
+    const { provider } = config;
+    const systemPrompt = config.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
+    const includeExistingLimit = config.includeExistingLimit ?? 16;
+    const onParseError = config.onParseError ??
+        ((err, raw) => {
+            // eslint-disable-next-line no-console
+            console.warn('[agentfootprint] llmFactExtractor: failed to parse LLM response — returning no facts', { error: err, rawPreview: raw.slice(0, 200) });
+        });
+    return {
+        async extract(args) {
+            const turn = formatMessagesForExtractor(args.messages, args.turnNumber);
+            const prior = formatExistingFacts(args.existing ?? [], includeExistingLimit);
+            const userContent = prior.length > 0 ? `${prior}\n\n${turn}` : turn;
+            const response = await provider.chat([
+                { role: 'system', content: systemPrompt },
+                { role: 'user', content: userContent },
+            ], args.signal ? { signal: args.signal } : undefined);
+            return parseFactsResponse(response.content ?? '', onParseError);
+        },
+    };
+}
+//# sourceMappingURL=llmFactExtractor.js.map

package/dist/esm/memory/facts/llmFactExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llmFactExtractor.js","sourceRoot":"","sources":["../../../../src/memory/facts/llmFactExtractor.ts"],"names":[],"mappings":"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"}

package/dist/esm/memory/facts/loadFacts.js

@@ -0,0 +1,22 @@
+import { isFactId } from './types';
+const DEFAULT_LIMIT = 100;
+export function loadFacts(config) {
+    const limit = config.limit ?? DEFAULT_LIMIT;
+    return async (scope) => {
+        const { entries } = await config.store.list(scope.identity, {
+            limit,
+            ...(config.tiers && { tiers: config.tiers }),
+        });
+        // Filter by fact-id prefix. `list` may return mixed payloads
+        // (messages + beats + facts) if the store is shared. Prefix filter
+        // keeps only the fact-shaped entries.
+        const facts = [];
+        for (const entry of entries) {
+            if (isFactId(entry.id))
+                facts.push(entry);
+        }
+        const existing = scope.loadedFacts ?? [];
+        scope.loadedFacts = [...existing, ...facts];
+    };
+}
+//# sourceMappingURL=loadFacts.js.map

package/dist/esm/memory/facts/loadFacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadFacts.js","sourceRoot":"","sources":["../../../../src/memory/facts/loadFacts.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAsBnC,MAAM,aAAa,GAAG,GAAG,CAAC;AAE1B,MAAM,UAAU,SAAS,CAAC,MAAuB;IAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,aAAa,CAAC;IAE5C,OAAO,KAAK,EAAE,KAAoC,EAAiB,EAAE;QACnE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,CAAO,KAAK,CAAC,QAAQ,EAAE;YAChE,KAAK;YACL,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;SAC7C,CAAC,CAAC;QAEH,6DAA6D;QAC7D,mEAAmE;QACnE,sCAAsC;QACtC,MAAM,KAAK,GAAwB,EAAE,CAAC;QACtC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC;QAED,MAAM,QAAQ,GAAG,KAAK,CAAC,WAAW,IAAI,EAAE,CAAC;QACzC,KAAK,CAAC,WAAW,GAAG,CAAC,GAAG,QAAQ,EAAE,GAAG,KAAK,CAAC,CAAC;IAC9C,CAAC,CAAC;AACJ,CAAC"}

package/dist/esm/memory/facts/patternFactExtractor.js

@@ -0,0 +1,106 @@
+import { asConfidence } from './types';
+/** Extract plaintext from any Message content shape. */
+function textOf(message) {
+    const c = message.content;
+    if (typeof c === 'string')
+        return c;
+    if (Array.isArray(c)) {
+        const parts = [];
+        for (const block of c) {
+            if (block && typeof block === 'object') {
+                const b = block;
+                if (b.type === 'text' && typeof b.text === 'string')
+                    parts.push(b.text);
+            }
+        }
+        return parts.join(' ');
+    }
+    return '';
+}
+const RULES = [
+    {
+        key: 'user.name',
+        category: 'identity',
+        confidence: 0.9,
+        patterns: [
+            // "my name is Alice" / "My name is Alice Smith" — lead-in case-insensitive
+            // via explicit [Mm], but captured name must be capitalized to avoid matching
+            // "my name is bob" (lowercase name is almost certainly not self-disclosure).
+            /\b[Mm]y name is\s+([A-Z][a-zA-Z]+(?:\s+[A-Z][a-zA-Z]+)?)/,
+            // "I'm Alice" / "I am Alice" — capitalized single word to reduce false positives
+            /\bI(?:'m|\s+am)\s+([A-Z][a-zA-Z]+)(?=[\s,.!?]|$)/,
+        ],
+    },
+    {
+        key: 'user.email',
+        category: 'contact',
+        confidence: 0.95,
+        patterns: [
+            // Basic RFC-5322-ish: username@domain.tld. Not exhaustive; good enough.
+            /\b([A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,})\b/,
+        ],
+    },
+    {
+        key: 'user.location',
+        category: 'profile',
+        confidence: 0.8,
+        patterns: [
+            // "I live in San Francisco" / "I'm in NYC" / "I live in New York City"
+            // Captures 1-3 capitalized words (handles multi-word place names).
+            /\bI\s+(?:live|am)\s+in\s+([A-Z][\w-]*(?:\s+[A-Z][\w-]*){0,2})(?=[.!?,;]|$)/,
+        ],
+    },
+    {
+        key: 'user.preferences',
+        category: 'preference',
+        confidence: 0.7,
+        patterns: [
+            // "I prefer dark mode" / "I like pizza" / "I prefer hot coffee"
+            // Captures 1-3 words — stops at sentence-ending punctuation.
+            /\bI\s+(?:prefer|like)\s+([a-zA-Z][\w-]*(?:\s+[a-zA-Z][\w-]*){0,2})(?=[.!?,;]|$)/,
+        ],
+    },
+];
+/** Trim trailing punctuation / whitespace from an extracted value. */
+function cleanValue(s) {
+    return s.replace(/[\s.!?,;:]+$/, '').trim();
+}
+export function patternFactExtractor() {
+    return {
+        async extract(args) {
+            // Track matches by key so later messages in this turn override
+            // earlier ones (user may restate with correction). Within a turn,
+            // last-write-wins per key.
+            const byKey = new Map();
+            for (const msg of args.messages) {
+                if (msg.role !== 'user')
+                    continue;
+                const text = textOf(msg);
+                if (text.length === 0)
+                    continue;
+                for (const rule of RULES) {
+                    for (const pattern of rule.patterns) {
+                        const match = text.match(pattern);
+                        if (!match)
+                            continue;
+                        const raw = match[1];
+                        if (!raw)
+                            continue;
+                        const value = cleanValue(raw);
+                        if (value.length === 0)
+                            continue;
+                        byKey.set(rule.key, {
+                            key: rule.key,
+                            value,
+                            confidence: asConfidence(rule.confidence),
+                            category: rule.category,
+                        });
+                        break; // first pattern-match per rule wins for this message
+                    }
+                }
+            }
+            return Array.from(byKey.values());
+        },
+    };
+}
+//# sourceMappingURL=patternFactExtractor.js.map

package/dist/esm/memory/facts/patternFactExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patternFactExtractor.js","sourceRoot":"","sources":["../../../../src/memory/facts/patternFactExtractor.ts"],"names":[],"mappings":"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"}

package/dist/esm/memory/facts/types.js

@@ -0,0 +1,49 @@
+/**
+ * Facts — stable, timeless claims about the user or world.
+ *
+ * Unlike beats (which summarize what happened in a turn) and messages
+ * (which are the raw conversation), facts capture *what's currently
+ * true*:
+ *   - Identity: "user.name" = "Alice"
+ *   - Preferences: "user.favorite_color" = "blue"
+ *   - Commitments: "task.ORD-123.status" = "refunded"
+ *
+ * Facts dedupe by `key`. The storage layer uses stable ids of the form
+ * `fact:${key}`, so a second write to the same key overwrites the
+ * first. This is the difference from beats/messages (which are
+ * append-only log entries).
+ */
+/** Build the stable `MemoryStore` id for a fact with the given key. */
+export function factId(key) {
+    return `fact:${key}`;
+}
+/** True iff the string is a fact id (starts with the `fact:` prefix). */
+export function isFactId(id) {
+    return id.startsWith('fact:');
+}
+/**
+ * Duck-typed guard — true iff `value` has the shape of a `Fact`.
+ * Used by pipelines that handle mixed-payload stores (facts +
+ * beats + raw messages) to route entries correctly.
+ */
+export function isFact(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return typeof v.key === 'string' && v.key.length > 0 && 'value' in v;
+}
+/**
+ * Clamp a value to `[0, 1]`; non-finite → 0.5 (neutral). Matches the
+ * `asImportance` convention in the beats layer so pickers can treat
+ * `confidence` and `importance` the same way.
+ */
+export function asConfidence(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return 0.5;
+    if (value < 0)
+        return 0;
+    if (value > 1)
+        return 1;
+    return value;
+}
+//# sourceMappingURL=types.js.map

package/dist/esm/memory/facts/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/memory/facts/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA4CH,uEAAuE;AACvE,MAAM,UAAU,MAAM,CAAC,GAAW;IAChC,OAAO,QAAQ,GAAG,EAAE,CAAC;AACvB,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,QAAQ,CAAC,EAAU;IACjC,OAAO,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,KAAc;IACnC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,IAAI,CAAC,CAAC;AACvE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IACrE,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACxB,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACxB,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/esm/memory/facts/writeFacts.js

@@ -0,0 +1,9 @@
+export function writeFacts(config) {
+    return async (scope) => {
+        const facts = (scope.newFacts ?? []);
+        if (facts.length === 0)
+            return;
+        await config.store.putMany(scope.identity, facts);
+    };
+}
+//# sourceMappingURL=writeFacts.js.map

package/dist/esm/memory/facts/writeFacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeFacts.js","sourceRoot":"","sources":["../../../../src/memory/facts/writeFacts.ts"],"names":[],"mappings":"AAsBA,MAAM,UAAU,UAAU,CAAC,MAAwB;IACjD,OAAO,KAAK,EAAE,KAAoC,EAAiB,EAAE;QACnE,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAiC,CAAC;QACrE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC/B,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACpD,CAAC,CAAC;AACJ,CAAC"}

package/dist/esm/memory/pipeline/fact.js

@@ -0,0 +1,87 @@
+/**
+ * factPipeline — key/value fact memory preset.
+ *
+ * Distills stable user claims out of each turn and recalls them as a
+ * compact key/value block. Complements `narrativePipeline` (beats are
+ * "what happened") — facts are "what's true right now."
+ *
+ *   READ   :  LoadFacts → FormatFacts
+ *   WRITE  :  LoadFacts → ExtractFacts → WriteFacts
+ *
+ * Why `LoadFacts` on BOTH sides?
+ *   - Read side: obvious — inject what we know.
+ *   - Write side: surfaces existing facts to the extractor via
+ *     `scope.loadedFacts`, so LLM-based extractors can UPDATE rather
+ *     than duplicate. Costs one extra `store.list` per turn; saves
+ *     many LLM-emitted duplicate facts.
+ *
+ * **Default extractor**: `patternFactExtractor()` — zero-dep, zero-cost
+ * regex heuristics for common identity / contact disclosures. Opt into
+ * `llmFactExtractor({ provider })` when you want semantic-quality
+ * extraction (preferences, commitments, task statuses).
+ *
+ * **Stable ids**: every fact is stored under `fact:${key}`, so writing
+ * `user.name = "Alice"` twice in two turns produces ONE entry in the
+ * store, not two. Updates overwrite in place — there's no
+ * accumulation, no "fact history" by default. Consumers who need fact
+ * history should run `narrativePipeline` alongside.
+ *
+ * @example
+ * ```ts
+ * import { Agent, anthropic } from 'agentfootprint';
+ * import { factPipeline, InMemoryStore, llmFactExtractor } from 'agentfootprint/memory';
+ *
+ * // Cheap default — regex heuristics, no LLM cost.
+ * const pipeline = factPipeline({ store: new InMemoryStore() });
+ *
+ * // Or opt into LLM-backed extraction:
+ * const hqPipeline = factPipeline({
+ *   store: new InMemoryStore(),
+ *   extractor: llmFactExtractor({ provider: anthropic('claude-haiku-4-5') }),
+ * });
+ *
+ * const agent = Agent.create({ provider: anthropic('claude-sonnet-4-5') })
+ *   .system('You remember facts about the user across turns.')
+ *   .memoryPipeline(pipeline)
+ *   .build();
+ * ```
+ */
+import { flowChart } from 'footprintjs';
+import { extractFacts, } from '../facts/extractFacts';
+import { writeFacts } from '../facts/writeFacts';
+import { loadFacts } from '../facts/loadFacts';
+import { formatFacts } from '../facts/formatFacts';
+import { patternFactExtractor } from '../facts/patternFactExtractor';
+export function factPipeline(config) {
+    const extractor = config.extractor ?? patternFactExtractor();
+    const loadConfig = {
+        store: config.store,
+        ...(config.loadLimit !== undefined && { limit: config.loadLimit }),
+        ...(config.tiers && { tiers: config.tiers }),
+    };
+    const formatConfig = {
+        ...(config.formatHeader !== undefined && { header: config.formatHeader }),
+        ...(config.formatFooter !== undefined && { footer: config.formatFooter }),
+        ...(config.formatShowConfidence !== undefined && {
+            showConfidence: config.formatShowConfidence,
+        }),
+    };
+    const extractConfig = {
+        extractor,
+        ...(config.writeTier && { tier: config.writeTier }),
+        ...(config.writeTtlMs !== undefined && { ttlMs: config.writeTtlMs }),
+    };
+    // ── Read subflow: LoadFacts → FormatFacts
+    const read = flowChart('LoadFacts', loadFacts(loadConfig), 'load-facts', undefined, 'Load stored Fact entries (ids starting with `fact:`) into scope.loadedFacts')
+        .addFunction('FormatFacts', formatFacts(formatConfig), 'format-facts', 'Render loaded facts as one system message; writes scope.formatted')
+        .build();
+    // ── Write subflow: LoadFacts → ExtractFacts → WriteFacts
+    // LoadFacts first so llmFactExtractor can see existing facts and
+    // update rather than duplicate.
+    const write = flowChart('LoadFacts', loadFacts(loadConfig), 'load-facts-for-extract', undefined, 'Surface existing facts to the extractor for update-awareness')
+        .addFunction('ExtractFacts', extractFacts(extractConfig), 'extract-facts', 'Distill scope.newMessages into Fact entries')
+        .addFunction('WriteFacts', writeFacts({ store: config.store }), 'write-facts', 'Batch-persist extracted facts via store.putMany (overwrite on key collision)')
+        .build();
+    return { read, write };
+}
+//# sourceMappingURL=fact.js.map

package/dist/esm/memory/pipeline/fact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact.js","sourceRoot":"","sources":["../../../../src/memory/pipeline/fact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAKxC,OAAO,EACL,YAAY,GAGb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAwB,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,WAAW,EAA0B,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAgCrE,MAAM,UAAU,YAAY,CAAC,MAA0B;IACrD,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,oBAAoB,EAAE,CAAC;IAE7D,MAAM,UAAU,GAAoB;QAClC,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,GAAG,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;QAClE,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;KAC7C,CAAC;IACF,MAAM,YAAY,GAAsB;QACtC,GAAG,CAAC,MAAM,CAAC,YAAY,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC;QACzE,GAAG,CAAC,MAAM,CAAC,YAAY,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC;QACzE,GAAG,CAAC,MAAM,CAAC,oBAAoB,KAAK,SAAS,IAAI;YAC/C,cAAc,EAAE,MAAM,CAAC,oBAAoB;SAC5C,CAAC;KACH,CAAC;IACF,MAAM,aAAa,GAAuB;QACxC,SAAS;QACT,GAAG,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;QACnD,GAAG,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;KACrE,CAAC;IAEF,2CAA2C;IAC3C,MAAM,IAAI,GAAG,SAAS,CACpB,WAAW,EACX,SAAS,CAAC,UAAU,CAAC,EACrB,YAAY,EACZ,SAAS,EACT,6EAA6E,CAC9E;SACE,WAAW,CACV,aAAa,EACb,WAAW,CAAC,YAAY,CAAC,EACzB,cAAc,EACd,mEAAmE,CACpE;SACA,KAAK,EAAE,CAAC;IAEX,0DAA0D;IAC1D,iEAAiE;IACjE,gCAAgC;IAChC,MAAM,KAAK,GAAG,SAAS,CACrB,WAAW,EACX,SAAS,CAAC,UAAU,CAAC,EACrB,wBAAwB,EACxB,SAAS,EACT,8DAA8D,CAC/D;SACE,WAAW,CACV,cAAc,EACd,YAAY,CAAC,aAAa,CAAC,EAC3B,eAAe,EACf,6CAA6C,CAC9C;SACA,WAAW,CACV,YAAY,EACZ,UAAU,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,EACnC,aAAa,EACb,8EAA8E,CAC/E;SACA,KAAK,EAAE,CAAC;IAEX,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC"}

package/dist/esm/memory/pipeline/index.js

@@ -2,4 +2,5 @@ export { defaultPipeline } from './default';
 export { ephemeralPipeline } from './ephemeral';
 export { narrativePipeline } from './narrative';
 export { semanticPipeline } from './semantic';
+export { factPipeline } from './fact';
 //# sourceMappingURL=index.js.map

package/dist/esm/memory/pipeline/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/memory/pipeline/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/memory/pipeline/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC"}

package/dist/esm/memory.barrel.js

@@ -37,9 +37,11 @@ export { defaultPipeline } from './memory/pipeline';
 export { ephemeralPipeline } from './memory/pipeline';
 export { narrativePipeline } from './memory/pipeline';
 export { semanticPipeline } from './memory/pipeline';
+export { factPipeline } from './memory/pipeline';
 export { cosineSimilarity, mockEmbedder } from './memory/embedding';
 export { embedMessages, loadRelevant } from './memory/embedding';
 export { asImportance, isNarrativeBeat, heuristicExtractor, llmExtractor, extractBeats, writeBeats, formatAsNarrative, } from './memory/beats';
+export { factId, isFactId, isFact, asConfidence, patternFactExtractor, llmFactExtractor, extractFacts, writeFacts, loadFacts, formatFacts, } from './memory/facts';
 // ── Wire helpers (for custom flowcharts) ────────────────────
 export { mountMemoryRead, mountMemoryWrite, mountMemoryPipeline } from './memory/wire';
 //# sourceMappingURL=memory.barrel.js.map

package/dist/esm/memory.barrel.js.map

@@ -1 +1 @@
-{"version":3,"file":"memory.barrel.js","sourceRoot":"","sources":["../../src/memory.barrel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAItD,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAUzE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAI/C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAK9E,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAKrD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEpE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAYjE,OAAO,EACL,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AASxB,+DAA+D;AAC/D,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"memory.barrel.js","sourceRoot":"","sources":["../../src/memory.barrel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAItD,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAUzE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAI/C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAK9E,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAKjD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEpE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAYjE,OAAO,EACL,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAWxB,OAAO,EACL,MAAM,EACN,QAAQ,EACR,MAAM,EACN,YAAY,EACZ,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,SAAS,EACT,WAAW,GACZ,MAAM,gBAAgB,CAAC;AAUxB,+DAA+D;AAC/D,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}