agentfootprint 1.12.0 → 1.14.0

package/dist/esm/memory/embedding/cosine.js

@@ -0,0 +1,39 @@
+/**
+ * cosineSimilarity — the similarity metric used by `store.search()`.
+ *
+ *   cos(a, b) = dot(a, b) / (||a|| * ||b||)
+ *
+ * Range: [-1, 1]. Equal-direction vectors → 1. Orthogonal → 0.
+ * Opposite → -1.
+ *
+ * Zero-magnitude handling: if either vector is all-zero (or the empty
+ * vector), returns 0 — never NaN. NaN in a similarity score would
+ * poison downstream picker comparisons (NaN < x is false for all x)
+ * and silently demote the entry. Explicit 0 is safer.
+ *
+ * Length mismatch THROWS: comparing vectors of different dimensions
+ * is almost always a bug (different embedders mixed in the same store).
+ * Fail loud rather than silently truncate.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`cosineSimilarity: vector length mismatch — ${a.length} vs ${b.length}. ` +
+            'Check that all entries in the store were produced by the SAME embedder instance.');
+    }
+    if (a.length === 0)
+        return 0;
+    let dot = 0;
+    let magA = 0;
+    let magB = 0;
+    for (let i = 0; i < a.length; i++) {
+        const av = a[i];
+        const bv = b[i];
+        dot += av * bv;
+        magA += av * av;
+        magB += bv * bv;
+    }
+    if (magA === 0 || magB === 0)
+        return 0;
+    return dot / (Math.sqrt(magA) * Math.sqrt(magB));
+}
+//# sourceMappingURL=cosine.js.map

package/dist/esm/memory/embedding/cosine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cosine.js","sourceRoot":"","sources":["../../../../src/memory/embedding/cosine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAoB,EAAE,CAAoB;IACzE,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,8CAA8C,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,MAAM,IAAI;YACvE,kFAAkF,CACrF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAE7B,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAChB,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAChB,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC;QACf,IAAI,IAAI,EAAE,GAAG,EAAE,CAAC;QAChB,IAAI,IAAI,EAAE,GAAG,EAAE,CAAC;IAClB,CAAC;IACD,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACvC,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACnD,CAAC"}

package/dist/esm/memory/embedding/embedMessages.js

@@ -0,0 +1,51 @@
+/** Default: extract plaintext from any supported content shape. */
+function defaultTextFrom(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 '';
+}
+/**
+ * Build the `embedMessages` stage. Prefers `embedBatch()` when the
+ * embedder implements it (one round-trip for the whole turn), otherwise
+ * falls back to N sequential `embed()` calls.
+ */
+export function embedMessages(config) {
+    const { embedder } = config;
+    const textFrom = config.textFrom ?? defaultTextFrom;
+    return async (scope) => {
+        const messages = (scope.newMessages ?? []);
+        if (messages.length === 0) {
+            scope.newMessageEmbeddings = [];
+            return;
+        }
+        const texts = messages.map(textFrom);
+        const signal = scope.$getEnv?.()?.signal;
+        let vectors;
+        if (embedder.embedBatch) {
+            vectors = (await embedder.embedBatch({
+                texts,
+                ...(signal ? { signal } : {}),
+            }));
+        }
+        else {
+            vectors = await Promise.all(texts.map((text) => embedder.embed({ text, ...(signal ? { signal } : {}) })));
+        }
+        scope.newMessageEmbeddings = vectors;
+        if (config.embedderId !== undefined) {
+            scope.newMessageEmbeddingModel = config.embedderId;
+        }
+    };
+}
+//# sourceMappingURL=embedMessages.js.map

package/dist/esm/memory/embedding/embedMessages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedMessages.js","sourceRoot":"","sources":["../../../../src/memory/embedding/embedMessages.ts"],"names":[],"mappings":"AA0DA,mEAAmE;AACnE,SAAS,eAAe,CAAC,OAAgB;IACvC,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IAC1B,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACrB,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,MAAM,KAAK,IAAI,CAAC,EAAE,CAAC;YACtB,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACvC,MAAM,CAAC,GAAG,KAAyC,CAAC;gBACpD,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;oBAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAC1E,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAA2B;IACvD,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAC5B,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,eAAe,CAAC;IAEpD,OAAO,KAAK,EAAE,KAAqC,EAAiB,EAAE;QACpE,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAuB,CAAC;QACjE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,KAAK,CAAC,oBAAoB,GAAG,EAAE,CAAC;YAChC,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACrC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC;QAEzC,IAAI,OAAmB,CAAC;QACxB,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;YACxB,OAAO,GAAG,CAAC,MAAM,QAAQ,CAAC,UAAU,CAAC;gBACnC,KAAK;gBACL,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9B,CAAC,CAAe,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CACzB,KAAK,CAAC,GAAG,CACP,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAsB,CACvF,CACF,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,oBAAoB,GAAG,OAAO,CAAC;QACrC,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACpC,KAAK,CAAC,wBAAwB,GAAG,MAAM,CAAC,UAAU,CAAC;QACrD,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,5 @@
+export { cosineSimilarity } from './cosine';
+export { mockEmbedder } from './mockEmbedder';
+export { embedMessages } from './embedMessages';
+export { loadRelevant } from './loadRelevant';
+//# sourceMappingURL=index.js.map

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

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

package/dist/esm/memory/embedding/loadRelevant.js

@@ -0,0 +1,65 @@
+/**
+ * Default query extractor — last user message.
+ *
+ * Inside the memory-read subflow (mounted by `mountMemoryRead`), the
+ * current turn's messages are piped in as `scope.messages` via the
+ * mount's inputMapper. Falls back to `newMessages` for custom pipelines
+ * that wire differently.
+ */
+function defaultQueryFrom(scope) {
+    const scopeAny = scope;
+    const incoming = scopeAny.messages ?? [];
+    const source = incoming.length > 0 ? incoming : (scope.newMessages ?? []);
+    for (let i = source.length - 1; i >= 0; i--) {
+        const m = source[i];
+        if (m.role !== 'user')
+            continue;
+        if (typeof m.content === 'string')
+            return m.content;
+        if (Array.isArray(m.content)) {
+            const parts = [];
+            for (const block of m.content) {
+                if (block && typeof block === 'object') {
+                    const b = block;
+                    if (b.type === 'text' && typeof b.text === 'string')
+                        parts.push(b.text);
+                }
+            }
+            if (parts.length > 0)
+                return parts.join(' ');
+        }
+    }
+    return '';
+}
+export function loadRelevant(config) {
+    const { store, embedder } = config;
+    if (!store.search) {
+        throw new Error('loadRelevant: the configured store does not implement search(). ' +
+            'Use a vector-capable adapter (InMemoryStore, pgvector, Pinecone, ...).');
+    }
+    const queryFrom = config.queryFrom ?? defaultQueryFrom;
+    const k = config.k ?? 20;
+    return async (scope) => {
+        const identity = scope.identity;
+        const text = queryFrom(scope).trim();
+        if (text.length === 0) {
+            scope.loaded = [];
+            return;
+        }
+        const signal = scope.$getEnv?.()?.signal;
+        const queryVec = (await embedder.embed({
+            text,
+            ...(signal ? { signal } : {}),
+        }));
+        const results = await store.search(identity, queryVec, {
+            k,
+            ...(config.minScore !== undefined && { minScore: config.minScore }),
+            ...(config.tiers && { tiers: config.tiers }),
+            ...(config.embedderId !== undefined && { embedderId: config.embedderId }),
+        });
+        // Write loaded entries to scope in best-first order — downstream
+        // pickByBudget further narrows by the token budget.
+        scope.loaded = results.map((r) => r.entry);
+    };
+}
+//# sourceMappingURL=loadRelevant.js.map

package/dist/esm/memory/embedding/loadRelevant.js.map

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

package/dist/esm/memory/embedding/mockEmbedder.js

@@ -0,0 +1,28 @@
+const DEFAULT_DIMENSIONS = 32;
+function charFrequency(text, dims) {
+    const vec = new Array(dims).fill(0);
+    for (let i = 0; i < text.length; i++) {
+        vec[text.charCodeAt(i) % dims] += 1;
+    }
+    return vec;
+}
+/**
+ * Build a deterministic mock embedder. Same text always yields the
+ * same vector; texts sharing characters share cosine similarity.
+ */
+export function mockEmbedder(options = {}) {
+    const dimensions = options.dimensions ?? DEFAULT_DIMENSIONS;
+    if (!Number.isInteger(dimensions) || dimensions <= 0) {
+        throw new Error(`mockEmbedder: dimensions must be a positive integer (got ${dimensions})`);
+    }
+    return {
+        dimensions,
+        async embed({ text }) {
+            return charFrequency(text, dimensions);
+        },
+        async embedBatch({ texts }) {
+            return texts.map((text) => charFrequency(text, dimensions));
+        },
+    };
+}
+//# sourceMappingURL=mockEmbedder.js.map

package/dist/esm/memory/embedding/mockEmbedder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mockEmbedder.js","sourceRoot":"","sources":["../../../../src/memory/embedding/mockEmbedder.ts"],"names":[],"mappings":"AAeA,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAE9B,SAAS,aAAa,CAAC,IAAY,EAAE,IAAY;IAC/C,MAAM,GAAG,GAAG,IAAI,KAAK,CAAS,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAMD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,UAA+B,EAAE;IAC5D,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,kBAAkB,CAAC;IAC5D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,4DAA4D,UAAU,GAAG,CAAC,CAAC;IAC7F,CAAC;IAED,OAAO;QACL,UAAU;QACV,KAAK,CAAC,KAAK,CAAC,EAAE,IAAI,EAAa;YAC7B,OAAO,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACzC,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,EAAE,KAAK,EAAkB;YACxC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;QAC9D,CAAC;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,17 @@
+/**
+ * Embedder — text-to-vector abstraction.
+ *
+ * Pluggable interface: consumers bring their own embedding backend
+ * (OpenAI, Voyage, Cohere, Sentence Transformers, a local model, a
+ * custom rules-based hashing scheme, etc.). The library ships
+ * `mockEmbedder()` for tests — no default real embedder, since LLM
+ * providers' embedding APIs are not uniform (Anthropic doesn't
+ * publish one at all).
+ *
+ * An embedder is configured once (model + api key + dims) and reused
+ * across many turns. `dimensions` is a constant per instance — mixing
+ * embedders of different dims within the same `MemoryStore` breaks
+ * cosine similarity, so adapters should reject mismatched sizes.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/memory/embedding/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

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":"AA2CA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AA2BvC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;0DAwB4B,CAAC;AAE3D,sEAAsE;AACtE,SAAS,KAAK,CAAC,UAAkB,EAAE,KAAa;IAC9C,OAAO,OAAO,UAAU,IAAI,KAAK,EAAE,CAAC;AACtC,CAAC;AAED,8DAA8D;AAC9D,SAAS,0BAA0B,CAAC,QAA4B,EAAE,UAAkB;IAClF,MAAM,KAAK,GAAa,CAAC,QAAQ,UAAU,GAAG,CAAC,CAAC;IAChD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ;YAAE,SAAS;QAClC,MAAM,GAAG,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;QACjC,MAAM,OAAO,GACX,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;YAC3B,CAAC,CAAC,CAAC,CAAC,OAAO;YACX,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;gBAC1B,CAAC,CAAC,CAAC,CAAC,OAAO;qBACN,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;oBACT,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;wBAC/B,MAAM,GAAG,GAAG,CAAqC,CAAC;wBAClD,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;4BAAE,OAAO,GAAG,CAAC,IAAI,CAAC;oBAC3E,CAAC;oBACD,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC;qBACD,MAAM,CAAC,OAAO,CAAC;qBACf,IAAI,CAAC,GAAG,CAAC;gBACd,CAAC,CAAC,EAAE,CAAC;QACT,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,uEAAuE;AACvE,SAAS,mBAAmB,CAAC,QAAyB,EAAE,KAAa;IACnE,IAAI,KAAK,IAAI,CAAC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACnD,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,CAAC,uEAAuE,CAAC,CAAC;IACxF,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1F,MAAM,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,GAAG,GAAG,IAAI,EAAE,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,kBAAkB,CACzB,GAAW,EACX,YAAiD;IAEjD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,KAAK,IAAI,EAAE,CAAc,CAAC;QACpD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;YAAE,OAAO,EAAE,CAAC;QAExC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAgB,CAAC;QACtC,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;YAC1B,IAAI,CAAC,EAAE,IAAI,OAAO,EAAE,KAAK,QAAQ;gBAAE,SAAS;YAC5C,MAAM,CAAC,GAAG,EAA6B,CAAC;YACxC,IAAI,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAC9D,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC;gBAAE,SAAS;YAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACtF,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;YACzE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE;gBACf,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC;gBACtC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACjC,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACrC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAA8B;IAC7D,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC;IAC5B,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,IAAI,qBAAqB,CAAC;IAClE,MAAM,oBAAoB,GAAG,MAAM,CAAC,oBAAoB,IAAI,EAAE,CAAC;IAC/D,MAAM,YAAY,GAChB,MAAM,CAAC,YAAY;QACnB,CAAC,CAAC,GAAY,EAAE,GAAW,EAAQ,EAAE;YACnC,sCAAsC;YACtC,OAAO,CAAC,IAAI,CACV,sFAAsF,EACtF,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAC9C,CAAC;QACJ,CAAC,CAAC,CAAC;IAEL,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,IAAqB;YACjC,MAAM,IAAI,GAAG,0BAA0B,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;YACxE,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,EAAE,oBAAoB,CAAC,CAAC;YAC7E,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;YAEpE,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAClC;gBACE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE;gBACzC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE;aACvC,EACD,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAClD,CAAC;YAEF,OAAO,kBAAkB,CAAC,QAAQ,CAAC,OAAO,IAAI,EAAE,EAAE,YAAY,CAAC,CAAC;QAClE,CAAC;KACF,CAAC;AACJ,CAAC"}

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