agentfootprint 1.13.0 → 1.15.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/auto.js

@@ -0,0 +1,177 @@
+/**
+ * autoPipeline — opinionated preset combining facts + beats on one store.
+ *
+ * The one-line default for "I want memory — just make it good."
+ *
+ *   READ  :  LoadAll → split by payload shape → FormatAuto
+ *            (one system msg with facts block + narrative paragraph)
+ *
+ *   WRITE :  LoadFacts → ExtractFacts → WriteFacts
+ *            → ExtractBeats → WriteBeats
+ *
+ * Facts carry "what's currently true" (identity, preferences,
+ * commitments — dedup on key). Beats carry "what happened" (traceable
+ * summaries — append-only). Together they cover the two memory shapes
+ * that matter for long-running agents without forcing the consumer to
+ * compose three presets by hand.
+ *
+ * **Default extractors**: zero-LLM-cost defaults so `autoPipeline({ store })`
+ * works out of the box:
+ *   - facts:  `patternFactExtractor()` (regex heuristics, free)
+ *   - beats:  `heuristicExtractor()`    (keyword heuristics, free)
+ *
+ * Pass `provider` to upgrade BOTH to LLM-backed extractors in one
+ * knob — `llmFactExtractor({ provider })` and `llmExtractor({ provider })`.
+ * The same cheap model (e.g. `claude-haiku-4-5`) handles both extraction
+ * calls per turn.
+ *
+ * **Why not include raw messages?** Raw messages come from the agent's
+ * ongoing conversation state — they don't need a memory strategy. This
+ * preset focuses on the two *compressed / deduplicated* shapes. Layer on
+ * `defaultPipeline` or `semanticPipeline` manually if you want raw recall.
+ *
+ * @example
+ * ```ts
+ * import { Agent, anthropic } from 'agentfootprint';
+ * import { autoPipeline, InMemoryStore } from 'agentfootprint/memory';
+ *
+ * // Free defaults — regex + heuristics, no LLM cost.
+ * const pipeline = autoPipeline({ store: new InMemoryStore() });
+ *
+ * // Or upgrade both extractors in one knob:
+ * const hq = autoPipeline({
+ *   store: new InMemoryStore(),
+ *   provider: anthropic('claude-haiku-4-5'),
+ * });
+ *
+ * const agent = Agent.create({ provider: anthropic('claude-sonnet-4-5') })
+ *   .system('You remember the user across turns.')
+ *   .memoryPipeline(pipeline)
+ *   .build();
+ * ```
+ */
+import { flowChart } from 'footprintjs';
+import { extractFacts, writeFacts, loadFacts, patternFactExtractor, llmFactExtractor, isFactId, } from '../facts';
+import { extractBeats, writeBeats, heuristicExtractor, llmExtractor, isNarrativeBeat, } from '../beats';
+const DEFAULT_FACTS_HEADER = 'Known facts about the user:';
+const DEFAULT_LEAD_IN = 'From earlier: ';
+const DEFAULT_LOAD_LIMIT = 200;
+/** Escape `</memory>` in user-controlled text to prevent tag-escape injection. */
+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);
+    }
+}
+/**
+ * Emit a single system message combining facts (key/value block) and
+ * beats (narrative paragraph). Empty sections are skipped; when BOTH
+ * are empty, `formatted = []` (no injection).
+ */
+function renderAutoMessage(facts, beats, opts) {
+    const sections = [];
+    if (facts.length > 0) {
+        const lines = facts.map((entry) => {
+            const f = entry.value;
+            const value = escapeMemoryTag(renderValue(f.value));
+            const conf = opts.showConfidence && typeof f.confidence === 'number'
+                ? ` (conf ${f.confidence.toFixed(2)})`
+                : '';
+            return `- ${f.key}: ${value}${conf}`;
+        });
+        sections.push(`${opts.factsHeader}\n\n${lines.join('\n')}`);
+    }
+    if (beats.length > 0) {
+        const sentences = beats.map((entry) => {
+            const beat = entry.value;
+            const text = escapeMemoryTag(beat.summary.trim());
+            const withRefs = opts.showRefs && beat.refs.length > 0 ? `${text} (refs: ${beat.refs.join(', ')})` : text;
+            return /[.!?]$/.test(withRefs) ? withRefs : `${withRefs}.`;
+        });
+        sections.push(`${opts.leadIn}${sentences.join(' ')}`);
+    }
+    if (sections.length === 0)
+        return [];
+    return [{ role: 'system', content: sections.join('\n\n') }];
+}
+export function autoPipeline(config) {
+    const factExtractor = config.factExtractor ??
+        (config.provider ? llmFactExtractor({ provider: config.provider }) : patternFactExtractor());
+    const beatExtractor = config.beatExtractor ??
+        (config.provider ? llmExtractor({ provider: config.provider }) : heuristicExtractor());
+    const loadLimit = config.loadLimit ?? DEFAULT_LOAD_LIMIT;
+    const factsHeader = config.factsHeader ?? DEFAULT_FACTS_HEADER;
+    const leadIn = config.narrativeLeadIn ?? DEFAULT_LEAD_IN;
+    const showConfidence = config.showConfidence ?? false;
+    const showRefs = config.showRefs ?? false;
+    // ── READ subflow ────────────────────────────────────────────
+    // One combined load + split stage. Keeps the subflow short and
+    // avoids pulling `loadRecent` + `pickByBudget` (which were designed
+    // for single-payload pipelines) into a mixed-payload context.
+    const read = flowChart('LoadAll', async (scope) => {
+        const listOpts = {
+            limit: loadLimit,
+            ...(config.tiers && { tiers: config.tiers }),
+        };
+        const { entries } = await config.store.list(scope.identity, listOpts);
+        const loadedFacts = [];
+        const loadedBeats = [];
+        for (const entry of entries) {
+            if (isFactId(entry.id)) {
+                loadedFacts.push(entry);
+            }
+            else if (isNarrativeBeat(entry.value)) {
+                loadedBeats.push(entry);
+            }
+            // Other payloads (raw messages) are intentionally ignored —
+            // auto() is the "compressed + deduped" preset.
+        }
+        // Stores typically return most-recently-updated first. Beats are
+        // more readable oldest-first (chronological narrative), so
+        // reverse before injection. Facts render as a list, order-agnostic.
+        scope.loadedFacts = loadedFacts;
+        scope.loadedBeats = [...loadedBeats].reverse();
+    }, 'load-all', undefined, 'Load facts + beats from the shared store; split by payload shape')
+        .addFunction('FormatAuto', async (scope) => {
+        const facts = (scope.loadedFacts ?? []);
+        const beats = (scope.loadedBeats ?? []);
+        scope.formatted = renderAutoMessage(facts, beats, {
+            factsHeader,
+            leadIn,
+            showConfidence,
+            showRefs,
+        });
+    }, 'format-auto', 'Emit one system message with facts block + narrative paragraph')
+        .build();
+    // ── WRITE subflow ───────────────────────────────────────────
+    // LoadFacts first so the (possibly LLM-backed) fact extractor sees
+    // existing facts via scope.loadedFacts and can update rather than
+    // duplicate. Then extract+write facts, then extract+write beats.
+    const write = flowChart('LoadFacts', loadFacts({
+        store: config.store,
+        limit: loadLimit,
+        ...(config.tiers && { tiers: config.tiers }),
+    }), 'load-facts', undefined, 'Surface existing facts for update-awareness')
+        .addFunction('ExtractFacts', extractFacts({
+        extractor: factExtractor,
+        ...(config.writeTier && { tier: config.writeTier }),
+        ...(config.writeTtlMs !== undefined && { ttlMs: config.writeTtlMs }),
+    }), 'extract-facts', 'Distill scope.newMessages into stable Fact entries')
+        .addFunction('WriteFacts', writeFacts({ store: config.store }), 'write-facts', 'Persist facts via store.putMany (overwrite on key collision)')
+        .addFunction('ExtractBeats', extractBeats({
+        extractor: beatExtractor,
+        ...(config.writeTier && { tier: config.writeTier }),
+        ...(config.writeTtlMs !== undefined && { ttlMs: config.writeTtlMs }),
+    }), 'extract-beats', 'Compress scope.newMessages into NarrativeBeat entries')
+        .addFunction('WriteBeats', writeBeats({ store: config.store }), 'write-beats', 'Persist beats via store.putMany')
+        .build();
+    return { read, write };
+}
+//# sourceMappingURL=auto.js.map