agentfootprint 9.4.0 → 9.5.0

package/dist/memory/strategies.js

@@ -0,0 +1,238 @@
+"use strict";
+/**
+ * Named memory strategies — what each one does, which TYPES accept it, and
+ * what the host must supply before it can run.
+ *
+ * `MEMORY_STRATEGIES` is a const of seven bare strings. A string is enough to
+ * WRITE `strategy: { kind: … }` and not nearly enough to OFFER the choice: a
+ * host rendering a strategy picker off that const offers seven options, and
+ * learns which of them this deployment can actually run by calling
+ * `defineMemory` and reading the exception. That is a selector that discovers
+ * its own capabilities by failing.
+ *
+ * So each strategy declares itself, and `listMemoryStrategies()` enumerates
+ * the declarations. The shape mirrors the influence exemplar in this same
+ * package (`listInfluenceStrategies()` → `{ name, description, requirements,
+ * scorer }`), with two deliberate differences:
+ *
+ *   • the id is `kind`, not `name` — it is the value the caller writes into
+ *     `strategy.kind`, so a picker's option value IS the id;
+ *   • there is no `scorer`, because a memory strategy is not a function the
+ *     host calls; what it needs instead is `types` — the memory TYPES that
+ *     accept it, which is the other half of "can I offer this?" (`decay` on a
+ *     SEMANTIC store is refused however good the host's credentials are).
+ *
+ * `requirements` is what a host must SUPPLY (an embedder, an LLM, a store
+ * that can search). Empty means the strategy runs anywhere, at $0.
+ *
+ * Pattern: declared capability descriptors + a guard that enforces them.
+ * Role:    memory/ layer-1, beside the const it describes.
+ * Emits:   N/A — build-time only.
+ *
+ * @see ./define.types.ts  for `MEMORY_STRATEGIES` and the strategy union
+ * @see ../lib/influence-core/strategies.ts  for the exemplar this follows
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertStrategyRequirements = exports.memoryStrategyInfo = exports.listMemoryStrategies = void 0;
+const define_types_js_1 = require("./define.types.js");
+const capability_js_1 = require("./store/capability.js");
+const WINDOW = Object.freeze({
+    kind: define_types_js_1.MEMORY_STRATEGIES.WINDOW,
+    description: 'Keeps the last `size` entries — messages on an Episodic store, facts or beats on the ' +
+        'others. A pure rule: no LLM, no embeddings, nothing to configure but the number. The ' +
+        'right default for short-to-medium chats.',
+    requirements: Object.freeze([]),
+    types: Object.freeze([define_types_js_1.MEMORY_TYPES.EPISODIC, define_types_js_1.MEMORY_TYPES.SEMANTIC, define_types_js_1.MEMORY_TYPES.NARRATIVE]),
+});
+const BUDGET = Object.freeze({
+    kind: define_types_js_1.MEMORY_STRATEGIES.BUDGET,
+    description: 'Injects as many recent entries as fit a token budget, and injects none at all when the ' +
+        'budget is below the floor. Free — the count is estimated, not modelled by a tokenizer ' +
+        'call. The decision (pick / skip-empty / skip-no-budget) is recorded as branch evidence.',
+    requirements: Object.freeze([]),
+    types: Object.freeze([define_types_js_1.MEMORY_TYPES.EPISODIC]),
+});
+const SUMMARIZE = Object.freeze({
+    kind: define_types_js_1.MEMORY_STRATEGIES.SUMMARIZE,
+    description: 'Names a cheap LLM to compress older turns while the most recent `recent` turns stay ' +
+        'raw. HONEST CAVEAT (9.5.0): the compression stage exists but is not composed into the ' +
+        'pipeline `defineMemory` builds, so what runs today is the last `recent` entries, ' +
+        'verbatim — the `llm` is required and not yet called. Until it is wired, ' +
+        '`.compaction({ summarizer, model })` on the Agent is the summarizer that does run.',
+    requirements: Object.freeze(['llm']),
+    types: Object.freeze([define_types_js_1.MEMORY_TYPES.EPISODIC]),
+});
+const TOP_K = Object.freeze({
+    kind: define_types_js_1.MEMORY_STRATEGIES.TOP_K,
+    description: 'Embeds the query and returns the closest stored entries above a threshold — strictly: ' +
+        'when nothing clears the threshold, nothing is injected. The embedder is exempt for a ' +
+        "store that declares `ranksBy: 'server-text'`, which takes the question as words and " +
+        'ranks it on its own side.',
+    requirements: Object.freeze(['embedder', 'vector-store']),
+    types: Object.freeze([define_types_js_1.MEMORY_TYPES.SEMANTIC, define_types_js_1.MEMORY_TYPES.CAUSAL]),
+});
+const EXTRACT = Object.freeze({
+    kind: define_types_js_1.MEMORY_STRATEGIES.EXTRACT,
+    description: 'Distills each turn into structured facts or narrative beats on the WRITE side. ' +
+        "`extractor: 'pattern'` is regex heuristics — free, no dependency, which is why this " +
+        "strategy requires nothing. `extractor: 'llm'` additionally needs an `llm`, and is " +
+        'refused without one.',
+    requirements: Object.freeze([]),
+    types: Object.freeze([define_types_js_1.MEMORY_TYPES.SEMANTIC, define_types_js_1.MEMORY_TYPES.NARRATIVE]),
+});
+const DECAY = Object.freeze({
+    kind: define_types_js_1.MEMORY_STRATEGIES.DECAY,
+    description: 'Lets old memory fade: each loaded entry is scored by age against a half-life and ' +
+        'dropped below `minScore`, so a long-running agent stops rehearsing last month. Free — ' +
+        'arithmetic on a timestamp, no LLM and no embeddings.',
+    requirements: Object.freeze([]),
+    types: Object.freeze([define_types_js_1.MEMORY_TYPES.EPISODIC]),
+});
+const HYBRID = Object.freeze({
+    kind: define_types_js_1.MEMORY_STRATEGIES.HYBRID,
+    description: 'Composes several strategies on one store. It requires nothing of its own — each ' +
+        'sub-strategy carries its own requirements, and every one of them is checked at build ' +
+        'so a hybrid cannot smuggle in a strategy this deployment cannot run.',
+    requirements: Object.freeze([]),
+    types: Object.freeze([define_types_js_1.MEMORY_TYPES.EPISODIC, define_types_js_1.MEMORY_TYPES.SEMANTIC, define_types_js_1.MEMORY_TYPES.NARRATIVE]),
+});
+const BUILT_IN = Object.freeze([
+    WINDOW,
+    BUDGET,
+    SUMMARIZE,
+    TOP_K,
+    EXTRACT,
+    DECAY,
+    HYBRID,
+]);
+/**
+ * Every memory strategy, described — cheapest first, in the order the docs
+ * teach them. Frozen: a host renders its picker straight off this.
+ *
+ * @example Offer only what this deployment can actually run
+ * ```ts
+ * import { listMemoryStrategies } from 'agentfootprint/memory';
+ *
+ * const available = new Set(embedder ? ['embedder', 'vector-store'] : []);
+ * const offerable = listMemoryStrategies().filter(
+ *   (s) => s.types.includes('episodic') && s.requirements.every((r) => available.has(r)),
+ * );
+ * // → window, budget, decay, hybrid — the four that cost nothing to run.
+ * ```
+ */
+function listMemoryStrategies() {
+    return BUILT_IN;
+}
+exports.listMemoryStrategies = listMemoryStrategies;
+/**
+ * One strategy's description by `kind`, or `undefined` for a string that is
+ * not a strategy at all.
+ */
+function memoryStrategyInfo(kind) {
+    return BUILT_IN.find((s) => s.kind === kind);
+}
+exports.memoryStrategyInfo = memoryStrategyInfo;
+// ─── The guard that makes the declaration true ──────────────────────
+/**
+ * Refuse a config whose strategy declares a requirement the caller did not
+ * supply — by name, at BUILD, with the fix in the message.
+ *
+ * WHY it runs LAST, after the pipeline dispatch rather than before it: the
+ * dispatch's own refusals know more than this one does. `defineMemory`'s
+ * TOP_K arm knows about the `ranksBy: 'server-text'` exemption AND about the
+ * write half it takes away; the CAUSAL arm knows that exemption does not
+ * apply to it; the EXTRACT arm knows the `llm` matters only for
+ * `extractor: 'llm'`. Speaking first would replace those messages with a
+ * blunter one. This is the BACKSTOP: it says something only when nothing
+ * better already did, and its job is that no declared requirement can go
+ * unchecked — the failure it exists to prevent is a missing dependency
+ * surfacing as a `TypeError` from five frames inside a stage, halfway
+ * through a paid run.
+ *
+ * @param options the config as written by the caller.
+ * @param site    the call to name in the message, e.g. `defineMemory[chat]`.
+ */
+function assertStrategyRequirements(options, site) {
+    checkStrategy(options.strategy, options.type, options.store, site, undefined);
+}
+exports.assertStrategyRequirements = assertStrategyRequirements;
+function checkStrategy(strategy, type, store, site, insideHybrid) {
+    const info = memoryStrategyInfo(strategy.kind);
+    // An unknown kind, or a kind this TYPE does not accept, is not this guard's
+    // business — the dispatch refuses both, and names the alternative.
+    if (!info || !info.types.includes(type))
+        return;
+    for (const requirement of info.requirements) {
+        if (isSatisfied(requirement, strategy, type, store, site))
+            continue;
+        throw new Error(missingRequirement(requirement, info, site, insideHybrid === true));
+    }
+    if (strategy.kind === define_types_js_1.MEMORY_STRATEGIES.HYBRID) {
+        // A hybrid is only as runnable as its parts, and the pipelines it builds
+        // do not all read every part — so the parts are checked HERE, where the
+        // caller's words still exist, rather than trusted to whatever the
+        // composed pipeline happens to consume.
+        for (const sub of strategy.strategies)
+            checkStrategy(sub, type, store, site, true);
+    }
+}
+function isSatisfied(requirement, strategy, type, store, site) {
+    // Read through a structural shape: the union's arms declare each other's
+    // fields as `never`, so the union itself cannot be asked these questions.
+    const s = strategy;
+    switch (requirement) {
+        case 'embedder':
+            // The one exemption, and it is a fact about the STORE: a backend that
+            // ranks TEXT on its own side has nothing here to embed. It does not
+            // extend to CAUSAL, which matches a stored query VECTOR — there is
+            // always a vector to produce there.
+            if (type !== define_types_js_1.MEMORY_TYPES.CAUSAL && (0, capability_js_1.resolveRankingMode)(store, site) === 'server-text') {
+                return true;
+            }
+            return s.embedder !== undefined;
+        case 'vector-store':
+            return typeof store.search === 'function';
+        case 'llm':
+            return s.llm !== undefined;
+        default:
+            // A requirement this library does not know how to check is not a
+            // requirement it may fail the caller over.
+            return true;
+    }
+}
+function missingRequirement(requirement, info, site, insideHybrid) {
+    const where = insideHybrid
+        ? `the \`${info.kind}\` strategy inside \`hybrid\``
+        : `the \`${info.kind}\` strategy`;
+    const declared = `  Every strategy declares what it needs — \`listMemoryStrategies()\` reports ` +
+        `\`requirements: [${info.requirements.map((r) => `'${r}'`).join(', ')}]\` for this one, so a ` +
+        `host can check before it offers the choice.\n`;
+    switch (requirement) {
+        case 'embedder':
+            return (`${site}: ${where} needs an \`embedder\` and none was passed — somebody has to turn ` +
+                `the query into a vector before a store can rank it.\n` +
+                declared +
+                `  Fix:  pass \`embedder\` on the strategy (\`mockEmbedder()\` for dev/tests), or omit ` +
+                `it only for a store that declares \`ranksBy: 'server-text'\` and embeds on its own side.`);
+        case 'vector-store':
+            return (`${site}: ${where} needs a store that can \`search()\`, and the store you passed does ` +
+                `not implement one — nothing would ever rank the entries written to it.\n` +
+                declared +
+                `  Fix:  pass a vector-capable store — \`InMemoryStore\` (dev/tests), ` +
+                `\`sqliteVectorStore\` (durable, one file), \`pgVectorStore\`, \`s3VectorsStore\`, or any ` +
+                `adapter that ranks the vectors you give it.\n` +
+                `  Or:   keep this store and pick a strategy that ranks nothing — \`window\` (last N) ` +
+                `or \`budget\` (fit-to-tokens).`);
+        case 'llm':
+            return (`${site}: ${where} names an \`llm\` and none was passed.\n` +
+                declared +
+                `  Fix:  pass \`llm\` on the strategy — a cheap model is the point of it.\n` +
+                `  Or:   use \`{ kind: 'window', size: <recent> }\`, which needs nothing, and which is ` +
+                `what this strategy's read path does today (its compression stage is not yet wired).`);
+        default:
+            return (`${site}: ${where} declares \`${requirement}\` and it was not supplied.\n` +
+                declared +
+                `  Fix:  supply it, or pick a strategy whose \`requirements\` are empty.`);
+    }
+}
+//# sourceMappingURL=strategies.js.map

package/dist/memory/strategies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategies.js","sourceRoot":"","sources":["../../src/memory/strategies.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;;;AAEH,uDAO2B;AAC3B,yDAA2D;AAyC3D,MAAM,MAAM,GAAuB,MAAM,CAAC,MAAM,CAAC;IAC/C,IAAI,EAAE,mCAAiB,CAAC,MAAM;IAC9B,WAAW,EACT,uFAAuF;QACvF,uFAAuF;QACvF,0CAA0C;IAC5C,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,EAAW,CAAC;IACxC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,8BAAY,CAAC,QAAQ,EAAE,8BAAY,CAAC,QAAQ,EAAE,8BAAY,CAAC,SAAS,CAAC,CAAC;CAC7F,CAAC,CAAC;AAEH,MAAM,MAAM,GAAuB,MAAM,CAAC,MAAM,CAAC;IAC/C,IAAI,EAAE,mCAAiB,CAAC,MAAM;IAC9B,WAAW,EACT,yFAAyF;QACzF,wFAAwF;QACxF,yFAAyF;IAC3F,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,EAAW,CAAC;IACxC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,8BAAY,CAAC,QAAQ,CAAC,CAAC;CAC9C,CAAC,CAAC;AAEH,MAAM,SAAS,GAAuB,MAAM,CAAC,MAAM,CAAC;IAClD,IAAI,EAAE,mCAAiB,CAAC,SAAS;IACjC,WAAW,EACT,sFAAsF;QACtF,wFAAwF;QACxF,mFAAmF;QACnF,0EAA0E;QAC1E,oFAAoF;IACtF,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAU,CAAC;IAC7C,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,8BAAY,CAAC,QAAQ,CAAC,CAAC;CAC9C,CAAC,CAAC;AAEH,MAAM,KAAK,GAAuB,MAAM,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,mCAAiB,CAAC,KAAK;IAC7B,WAAW,EACT,wFAAwF;QACxF,uFAAuF;QACvF,sFAAsF;QACtF,2BAA2B;IAC7B,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,cAAc,CAAU,CAAC;IAClE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,8BAAY,CAAC,QAAQ,EAAE,8BAAY,CAAC,MAAM,CAAC,CAAC;CACnE,CAAC,CAAC;AAEH,MAAM,OAAO,GAAuB,MAAM,CAAC,MAAM,CAAC;IAChD,IAAI,EAAE,mCAAiB,CAAC,OAAO;IAC/B,WAAW,EACT,iFAAiF;QACjF,sFAAsF;QACtF,oFAAoF;QACpF,sBAAsB;IACxB,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,EAAW,CAAC;IACxC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,8BAAY,CAAC,QAAQ,EAAE,8BAAY,CAAC,SAAS,CAAC,CAAC;CACtE,CAAC,CAAC;AAEH,MAAM,KAAK,GAAuB,MAAM,CAAC,MAAM,CAAC;IAC9C,IAAI,EAAE,mCAAiB,CAAC,KAAK;IAC7B,WAAW,EACT,mFAAmF;QACnF,wFAAwF;QACxF,sDAAsD;IACxD,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,EAAW,CAAC;IACxC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,8BAAY,CAAC,QAAQ,CAAC,CAAC;CAC9C,CAAC,CAAC;AAEH,MAAM,MAAM,GAAuB,MAAM,CAAC,MAAM,CAAC;IAC/C,IAAI,EAAE,mCAAiB,CAAC,MAAM;IAC9B,WAAW,EACT,kFAAkF;QAClF,uFAAuF;QACvF,sEAAsE;IACxE,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,EAAW,CAAC;IACxC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,8BAAY,CAAC,QAAQ,EAAE,8BAAY,CAAC,QAAQ,EAAE,8BAAY,CAAC,SAAS,CAAC,CAAC;CAC7F,CAAC,CAAC;AAEH,MAAM,QAAQ,GAAkC,MAAM,CAAC,MAAM,CAAC;IAC5D,MAAM;IACN,MAAM;IACN,SAAS;IACT,KAAK;IACL,OAAO;IACP,KAAK;IACL,MAAM;CACP,CAAC,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,SAAgB,oBAAoB;IAClC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAFD,oDAEC;AAED;;;GAGG;AACH,SAAgB,kBAAkB,CAAC,IAAY;IAC7C,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AAC/C,CAAC;AAFD,gDAEC;AAED,uEAAuE;AAEvE;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,0BAA0B,CAAC,OAA4B,EAAE,IAAY;IACnF,aAAa,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;AAChF,CAAC;AAFD,gEAEC;AAED,SAAS,aAAa,CACpB,QAAkB,EAClB,IAAgB,EAChB,KAAkB,EAClB,IAAY,EACZ,YAAiC;IAEjC,MAAM,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC/C,4EAA4E;IAC5E,mEAAmE;IACnE,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO;IAEhD,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;QAC5C,IAAI,WAAW,CAAC,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC;YAAE,SAAS;QACpE,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC;IACtF,CAAC;IAED,IAAI,QAAQ,CAAC,IAAI,KAAK,mCAAiB,CAAC,MAAM,EAAE,CAAC;QAC/C,yEAAyE;QACzE,wEAAwE;QACxE,kEAAkE;QAClE,wCAAwC;QACxC,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,UAAU;YAAE,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACrF,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAClB,WAAsC,EACtC,QAAkB,EAClB,IAAgB,EAChB,KAAkB,EAClB,IAAY;IAEZ,yEAAyE;IACzE,0EAA0E;IAC1E,MAAM,CAAC,GAAG,QAAmE,CAAC;IAC9E,QAAQ,WAAW,EAAE,CAAC;QACpB,KAAK,UAAU;YACb,sEAAsE;YACtE,oEAAoE;YACpE,mEAAmE;YACnE,oCAAoC;YACpC,IAAI,IAAI,KAAK,8BAAY,CAAC,MAAM,IAAI,IAAA,kCAAkB,EAAC,KAAK,EAAE,IAAI,CAAC,KAAK,aAAa,EAAE,CAAC;gBACtF,OAAO,IAAI,CAAC;YACd,CAAC;YACD,OAAO,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC;QAClC,KAAK,cAAc;YACjB,OAAO,OAAO,KAAK,CAAC,MAAM,KAAK,UAAU,CAAC;QAC5C,KAAK,KAAK;YACR,OAAO,CAAC,CAAC,GAAG,KAAK,SAAS,CAAC;QAC7B;YACE,iEAAiE;YACjE,2CAA2C;YAC3C,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CACzB,WAAsC,EACtC,IAAwB,EACxB,IAAY,EACZ,YAAqB;IAErB,MAAM,KAAK,GAAG,YAAY;QACxB,CAAC,CAAC,SAAS,IAAI,CAAC,IAAI,+BAA+B;QACnD,CAAC,CAAC,SAAS,IAAI,CAAC,IAAI,aAAa,CAAC;IACpC,MAAM,QAAQ,GACZ,+EAA+E;QAC/E,oBAAoB,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,yBAAyB;QAC9F,+CAA+C,CAAC;IAElD,QAAQ,WAAW,EAAE,CAAC;QACpB,KAAK,UAAU;YACb,OAAO,CACL,GAAG,IAAI,KAAK,KAAK,oEAAoE;gBACrF,uDAAuD;gBACvD,QAAQ;gBACR,wFAAwF;gBACxF,0FAA0F,CAC3F,CAAC;QACJ,KAAK,cAAc;YACjB,OAAO,CACL,GAAG,IAAI,KAAK,KAAK,sEAAsE;gBACvF,0EAA0E;gBAC1E,QAAQ;gBACR,uEAAuE;gBACvE,2FAA2F;gBAC3F,+CAA+C;gBAC/C,uFAAuF;gBACvF,gCAAgC,CACjC,CAAC;QACJ,KAAK,KAAK;YACR,OAAO,CACL,GAAG,IAAI,KAAK,KAAK,0CAA0C;gBAC3D,QAAQ;gBACR,4EAA4E;gBAC5E,wFAAwF;gBACxF,qFAAqF,CACtF,CAAC;QACJ;YACE,OAAO,CACL,GAAG,IAAI,KAAK,KAAK,eAAe,WAAW,+BAA+B;gBAC1E,QAAQ;gBACR,yEAAyE,CAC1E,CAAC;IACN,CAAC;AACH,CAAC"}

package/dist/types/memory/define.d.ts

@@ -42,7 +42,8 @@ import type { MemoryDefinition, ReadonlyMemoryFlowChart } from './define.types.j
  * | --------- | ------------- | ------------------------ |
  * | EPISODIC  | WINDOW        | defaultPipeline          |
  * | EPISODIC  | BUDGET        | defaultPipeline          |
- * | EPISODIC  | SUMMARIZE     | defaultPipeline + summarize stage |
+ * | EPISODIC  | SUMMARIZE     | defaultPipeline (the compression stage is NOT composed in yet — see `listMemoryStrategies()`) |
+ * | EPISODIC  | DECAY         | defaultPipeline + filterByDecay stage |
  * | SEMANTIC  | TOP_K         | semanticPipeline         |
  * | SEMANTIC  | EXTRACT       | factPipeline             |
  * | SEMANTIC  | WINDOW        | factPipeline (recency-load) |

package/dist/types/memory/define.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../src/memory/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAcH,OAAO,EAIL,KAAK,mBAAmB,EAYzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAInF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,gBAAgB,CA4B3E;AAmWD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,OAAO,CAErF"}
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../src/memory/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAeH,OAAO,EAIL,KAAK,mBAAmB,EAazB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAInF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,gBAAgB,CAqC3E;AA8XD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,OAAO,CAErF"}

package/dist/types/memory/define.types.d.ts

@@ -68,6 +68,12 @@ export type MemoryType = (typeof MEMORY_TYPES)[keyof typeof MEMORY_TYPES];
  * `CAUSAL` type accepts ONLY `TOP_K` — its snapshots are matched semantically
  * against the new query, never by recency, so `buildCausalPipeline` throws on
  * any other strategy kind. Mix and match the non-Causal types.
+ *
+ * These are BARE STRINGS, which is enough to write one and not enough to
+ * OFFER one. `listMemoryStrategies()` (./strategies.ts) is the same seven
+ * described — what each does, which TYPES accept it, and what the host must
+ * supply (`requirements`) — so a picker can grey out what this deployment
+ * cannot run instead of finding out from an exception.
  */
 export declare const MEMORY_STRATEGIES: {
     readonly WINDOW: "window";
@@ -236,14 +242,34 @@ export interface ExtractStrategy {
     readonly maxPerTurn?: number;
 }
 /**
- * Decay — score entries by `recency × accessCount`, drop below floor.
- * For long-running agents where unused memory should fade.
+ * Decay — let old memory fade. Each loaded entry is scored by AGE against
+ * `halfLifeMs` (`2^(-age / halfLife)`) and dropped below `minScore`, so a
+ * long-running agent stops rehearsing last month. Free: arithmetic on a
+ * timestamp, no LLM and no embedder. EPISODIC only.
+ *
+ * Wired in 9.5.0. Before that, this type existed, `MEMORY_STRATEGIES.DECAY`
+ * existed, and `defineMemory` threw "not yet wired" on it.
+ *
+ * AGE, not use. The underlying model (`computeDecayFactor`) also has an
+ * access term, and the read path passes a neutral `1` for it: `accessCount`
+ * is bumped by `store.get()`, and no shipped read path calls `get()` — they
+ * `list()` or `search()`. A knob for it here would be wired to a counter
+ * that never moves, so there isn't one. Nothing stored is mutated either:
+ * an entry that decays out of one turn is still in the store, and the next
+ * turn scores it again.
  */
 export interface DecayStrategy {
     readonly kind: typeof MEMORY_STRATEGIES.DECAY;
-    /** Half-life in milliseconds for the recency component. */
+    /**
+     * How long before an untouched entry is worth half as much, in
+     * milliseconds. A day is `86_400_000`. Must be finite and non-negative —
+     * a negative half-life would score OLDER entries higher, so it is refused.
+     */
     readonly halfLifeMs: number;
-    /** Drop entries scoring below this. Default 0.1. */
+    /**
+     * Drop entries scoring below this. Default 0.1 — roughly "older than
+     * three-and-a-bit half-lives". `0` keeps everything.
+     */
     readonly minScore?: number;
 }
 /**

package/dist/types/memory/define.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define.types.d.ts","sourceRoot":"","sources":["../../../src/memory/define.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAI9D;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY;;;;;CAKf,CAAC;AACX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE1E;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;CAQpB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAE5F;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;CAGhB,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAE9E;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB;;;;;CAKvB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAC;AAIlG;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,iBAAiB,CAAC,MAAM,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,iBAAiB,CAAC,MAAM,CAAC;IAC/C,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,OAAO,iBAAiB,CAAC,SAAS,CAAC;IAClD,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;CAC3B;AAED;;;;GAIG;AACH;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,qBAAqB,GAAG,qBAAqB,CAAC;AAEzE,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,OAAO,iBAAiB,CAAC,KAAK,CAAC;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC;CAC5B;AAED,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,OAAO,iBAAiB,CAAC,KAAK,CAAC;IAC9C,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,oDAAoD;IACpD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,OAAO,iBAAiB,CAAC,OAAO,CAAC;IAChD,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,KAAK,CAAC;IACtC,wCAAwC;IACxC,QAAQ,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,iDAAiD;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,iBAAiB,CAAC,KAAK,CAAC;IAC9C,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,iBAAiB,CAAC,MAAM,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,OAAO,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC;CACvE;AAED,yDAAyD;AACzD,MAAM,MAAM,QAAQ,GAChB,oBAAoB,GACpB,cAAc,GACd,iBAAiB,GACjB,YAAY,GACZ,eAAe,GACf,aAAa,GACb,cAAc,CAAC;AAInB;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,kDAAkD;IAClD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAID;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO;IAC3C,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,0CAA0C;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAE1B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC,CAAC,CAAC,CAAC;IAE1C,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,uBAAuB,CAAC,CAAC,CAAC,CAAC;IAE5C,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAQ9B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAExC,oEAAoE;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAEzC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IAEjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;CAChC;AAED,uDAAuD;AACvD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE5C;;;;;;GAMG;AAEH,MAAM,MAAM,uBAAuB,CAAC,EAAE,IAAI;IACxC,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC;CAC7C,CAAC;AAIF;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAK/B,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAExC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IAEjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAE5B,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;CAChC;AAED,MAAM,WAAW,qBAAsB,SAAQ,uBAAuB;IACpE,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC,QAAQ,CAAC;CAC7C;AAED,MAAM,WAAW,qBAAsB,SAAQ,uBAAuB;IACpE,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC,QAAQ,CAAC;CAC7C;AAED,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC,SAAS,CAAC;CAC9C;AAED,MAAM,WAAW,mBAAoB,SAAQ,uBAAuB;IAClE,QAAQ,CAAC,IAAI,EAAE,OAAO,YAAY,CAAC,MAAM,CAAC;IAC1C,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;CAC1C;AAED,2EAA2E;AAC3E,MAAM,MAAM,mBAAmB,GAC3B,qBAAqB,GACrB,qBAAqB,GACrB,sBAAsB,GACtB,mBAAmB,CAAC;AAIxB,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,kBAAkB,CAE/E;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,YAAY,CAEnE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,kBAAkB,CAE/E;AAID;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,oBAA8B,CAAC;AAEvE,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,6BAA6B,sBAAgC,CAAC;AAE3E,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE3D"}
+{"version":3,"file":"define.types.d.ts","sourceRoot":"","sources":["../../../src/memory/define.types.ts"],"names":[],"mappings":"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"}

package/dist/types/memory/index.d.ts

@@ -18,4 +18,5 @@ export * from './wire/index.js';
 export * from './retrieval/index.js';
 export { MEMORY_TYPES, MEMORY_STRATEGIES, MEMORY_TIMING, SNAPSHOT_PROJECTIONS, MEMORY_INJECTION_KEY_PREFIX, RETRIEVAL_EVIDENCE_KEY_PREFIX, isMemoryType, isMemoryStrategyKind, isMemoryTiming, isSnapshotProjection, memoryInjectionKey, isMemoryInjectionKey, retrievalEvidenceKey, isRetrievalEvidenceKey, type MemoryType, type MemoryStrategyKind, type MemoryTiming, type SnapshotProjection, type Strategy, type MemoryWindowStrategy, type BudgetStrategy, type SummarizeStrategy, type TopKStrategy, type TopKShorthandStrategy, type TopKRetrievalStrategy, type MemoryFlavor, type ExtractStrategy, type DecayStrategy, type HybridStrategy, type MemoryDefinition, type DefineMemoryOptions, type DefineEpisodicOptions, type DefineSemanticOptions, type DefineNarrativeOptions, type DefineCausalOptions, type MemoryRedactionPolicy, } from './define.types.js';
 export { defineMemory } from './define.js';
+export { listMemoryStrategies, memoryStrategyInfo, type MemoryStrategyInfo, type MemoryStrategyRequirement, } from './strategies.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/memory/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AAGrC,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,2BAA2B,EAC3B,6BAA6B,EAC7B,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AAGrC,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,2BAA2B,EAC3B,6BAA6B,EAC7B,YAAY,EACZ,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,GAC/B,MAAM,iBAAiB,CAAC"}

package/dist/types/memory/pipeline/default.d.ts

@@ -1,3 +1,4 @@
+import { type FilterByDecayConfig } from '../stages/filterByDecay.js';
 import type { MemoryStore } from '../store/index.js';
 import type { MemoryPipeline } from './types.js';
 export interface DefaultPipelineConfig {
@@ -34,6 +35,21 @@ export interface DefaultPipelineConfig {
      * retention windows.
      */
     readonly writeTtlMs?: number;
+    /**
+     * Let old entries fade (9.5.0). When present, a `FilterByDecay` stage is
+     * composed between the load and the picker: every loaded entry is scored
+     * by AGE against `halfLifeMs` and dropped below `minScore`, so a
+     * long-running conversation stops rehearsing last month.
+     *
+     * Absent — the historical behaviour — means no decay stage is compiled at
+     * all, not a decay stage that keeps everything. What is not in the chart
+     * cannot cost anything or appear in the narrative.
+     *
+     * `defineMemory({ strategy: { kind: MEMORY_STRATEGIES.DECAY, halfLifeMs } })`
+     * is the door most consumers use; this is the same thing, spelled at the
+     * pipeline level so it composes with `loadCount` / the budget knobs.
+     */
+    readonly decay?: FilterByDecayConfig;
     /**
      * Override for the formatter's header text. Omit to use the default
      * "Relevant context from prior conversations..." phrasing.

package/dist/types/memory/pipeline/default.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"default.d.ts","sourceRoot":"","sources":["../../../../src/memory/pipeline/default.ts"],"names":[],"mappings":"AAwDA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IACpC,qCAAqC;IACrC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEhC,kFAAkF;IAClF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC;IAExD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IAE7C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B,gEAAgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,cAAc,CAgD7E"}
+{"version":3,"file":"default.d.ts","sourceRoot":"","sources":["../../../../src/memory/pipeline/default.ts"],"names":[],"mappings":"AAoDA,OAAO,EAAiB,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAKrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IACpC,qCAAqC;IACrC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEhC,kFAAkF;IAClF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC;IAExD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IAE7C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAErC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B,gEAAgE;IAChE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,cAAc,CA2D7E"}

package/dist/types/memory/stages/filterByDecay.d.ts

@@ -0,0 +1,68 @@
+/**
+ * filterByDecay — read-side stage that lets old memory fade.
+ *
+ * Reads from scope:  `loaded`
+ * Writes to scope:   `loaded` (the survivors, order preserved)
+ *
+ * Where it sits:
+ *
+ *   loadRecent → filterByDecay → pickByBudget → formatDefault
+ *
+ * BEFORE the picker on purpose. The picker spends a token budget on what it
+ * is given; deciding what has faded is not a budget question, and a stale
+ * entry that fits should still not be injected. Dropping first also means
+ * the budget is spent on entries that are still worth something.
+ *
+ * ## The score
+ *
+ * `computeDecayFactor` (memory/entry/decay.ts) is the model, unchanged:
+ *
+ *     factor = 2^(-age / halfLife) · min(accessBoost^accessCount, 10)
+ *
+ * This stage passes `accessBoost: 1`, which makes the access term exactly
+ * `1` and the score purely age-based — and that is a truthful default rather
+ * than a timid one. `accessCount` is incremented by `store.get()`, and no
+ * shipped read path calls `get()`: they all `list()` or `search()`. So an
+ * access-weighted knob here would be a dial wired to a counter that never
+ * moves. When a read path starts bumping it, the term is already in the
+ * model and the knob can arrive with something real behind it.
+ *
+ * ## What is never dropped
+ *
+ * An entry whose `lastAccessedAt` is missing or not a finite number is KEPT.
+ * A store that does not date its entries has not told us they are old, and
+ * "I cannot date this" must not read as "this is ancient" — the arithmetic
+ * would produce `NaN`, and `NaN >= minScore` is false, which would silently
+ * drop every entry from such a store.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { MemoryState } from './types.js';
+export interface FilterByDecayConfig {
+    /**
+     * How long, in milliseconds, before an untouched entry is worth half as
+     * much. `0` means "anything not written this instant is gone".
+     */
+    readonly halfLifeMs: number;
+    /**
+     * Drop entries scoring below this. Default `0.1` — roughly "older than
+     * three-and-a-bit half-lives". `0` keeps everything, which is a coherent
+     * request (score, don't drop) and is honoured as written.
+     */
+    readonly minScore?: number;
+    /**
+     * Clock seam. Defaults to `Date.now`; tests pass a fixed clock so a decay
+     * assertion is arithmetic rather than a race.
+     */
+    readonly now?: () => number;
+}
+/** See {@link FilterByDecayConfig.minScore}. */
+export declare const DEFAULT_DECAY_MIN_SCORE = 0.1;
+/**
+ * Build a stage that drops faded entries from `scope.loaded`.
+ *
+ * Pure arithmetic over what is already in scope: no store call, no LLM, no
+ * embedding, and no mutation of anything stored — an entry that decays out
+ * of one turn is still in the store, and a later turn scores it again.
+ */
+export declare function filterByDecay(config: FilterByDecayConfig): (scope: TypedScope<MemoryState>) => Promise<void>;
+//# sourceMappingURL=filterByDecay.d.ts.map

package/dist/types/memory/stages/filterByDecay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filterByDecay.d.ts","sourceRoot":"","sources":["../../../../src/memory/stages/filterByDecay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,gDAAgD;AAChD,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAQ3C;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,mBAAmB,WAQlC,WAAW,WAAW,CAAC,KAAG,QAAQ,IAAI,CAAC,CAoB7D"}

package/dist/types/memory/stages/index.d.ts

@@ -11,4 +11,6 @@ export { approximateTokenCounter, countMessageTokens } from './tokenize.js';
 export type { TokenCounter } from './tokenize.js';
 export { summarize } from './summarize.js';
 export type { SummarizeConfig } from './summarize.js';
+export { filterByDecay, DEFAULT_DECAY_MIN_SCORE } from './filterByDecay.js';
+export type { FilterByDecayConfig } from './filterByDecay.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/memory/stages/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/memory/stages/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC5E,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/memory/stages/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC5E,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/types/memory/strategies.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Named memory strategies — what each one does, which TYPES accept it, and
+ * what the host must supply before it can run.
+ *
+ * `MEMORY_STRATEGIES` is a const of seven bare strings. A string is enough to
+ * WRITE `strategy: { kind: … }` and not nearly enough to OFFER the choice: a
+ * host rendering a strategy picker off that const offers seven options, and
+ * learns which of them this deployment can actually run by calling
+ * `defineMemory` and reading the exception. That is a selector that discovers
+ * its own capabilities by failing.
+ *
+ * So each strategy declares itself, and `listMemoryStrategies()` enumerates
+ * the declarations. The shape mirrors the influence exemplar in this same
+ * package (`listInfluenceStrategies()` → `{ name, description, requirements,
+ * scorer }`), with two deliberate differences:
+ *
+ *   • the id is `kind`, not `name` — it is the value the caller writes into
+ *     `strategy.kind`, so a picker's option value IS the id;
+ *   • there is no `scorer`, because a memory strategy is not a function the
+ *     host calls; what it needs instead is `types` — the memory TYPES that
+ *     accept it, which is the other half of "can I offer this?" (`decay` on a
+ *     SEMANTIC store is refused however good the host's credentials are).
+ *
+ * `requirements` is what a host must SUPPLY (an embedder, an LLM, a store
+ * that can search). Empty means the strategy runs anywhere, at $0.
+ *
+ * Pattern: declared capability descriptors + a guard that enforces them.
+ * Role:    memory/ layer-1, beside the const it describes.
+ * Emits:   N/A — build-time only.
+ *
+ * @see ./define.types.ts  for `MEMORY_STRATEGIES` and the strategy union
+ * @see ../lib/influence-core/strategies.ts  for the exemplar this follows
+ */
+import { type DefineMemoryOptions, type MemoryStrategyKind, type MemoryType } from './define.types.js';
+/**
+ * What a strategy needs the host to supply before it can run. A picker greys
+ * out (or refuses to offer) strategies whose requirements it cannot meet.
+ *
+ * Three well-known values ship; the type stays open so a consumer's own
+ * strategy descriptor can name something else:
+ *
+ *   - `'embedder'`     — an `Embedder` that turns text into a vector.
+ *   - `'vector-store'` — a store that implements `search()`. Not the same
+ *                        requirement as an embedder: the embedder makes the
+ *                        query vector, the store is what ranks against it,
+ *                        and a deployment can easily have one without the
+ *                        other (`RedisStore` is a full memory store with no
+ *                        `search()` at all).
+ *   - `'llm'`          — a chat provider the strategy calls on the host's
+ *                        behalf.
+ */
+export type MemoryStrategyRequirement = 'embedder' | 'vector-store' | 'llm' | (string & Record<never, never>);
+/**
+ * A memory strategy, described: enough for a host to render it in a picker
+ * and know, before it offers the option, whether this deployment can run it.
+ */
+export interface MemoryStrategyInfo {
+    /** The value written as `strategy.kind` — a member of `MEMORY_STRATEGIES`. */
+    readonly kind: MemoryStrategyKind;
+    /** One-or-two-sentence plain description, current-truth caveats included. */
+    readonly description: string;
+    /** What the host must supply. Empty = runs anywhere, no dependency, $0. */
+    readonly requirements: readonly MemoryStrategyRequirement[];
+    /** The memory TYPES that accept this strategy. Any other pair is refused. */
+    readonly types: readonly MemoryType[];
+}
+/**
+ * Every memory strategy, described — cheapest first, in the order the docs
+ * teach them. Frozen: a host renders its picker straight off this.
+ *
+ * @example Offer only what this deployment can actually run
+ * ```ts
+ * import { listMemoryStrategies } from 'agentfootprint/memory';
+ *
+ * const available = new Set(embedder ? ['embedder', 'vector-store'] : []);
+ * const offerable = listMemoryStrategies().filter(
+ *   (s) => s.types.includes('episodic') && s.requirements.every((r) => available.has(r)),
+ * );
+ * // → window, budget, decay, hybrid — the four that cost nothing to run.
+ * ```
+ */
+export declare function listMemoryStrategies(): readonly MemoryStrategyInfo[];
+/**
+ * One strategy's description by `kind`, or `undefined` for a string that is
+ * not a strategy at all.
+ */
+export declare function memoryStrategyInfo(kind: string): MemoryStrategyInfo | undefined;
+/**
+ * Refuse a config whose strategy declares a requirement the caller did not
+ * supply — by name, at BUILD, with the fix in the message.
+ *
+ * WHY it runs LAST, after the pipeline dispatch rather than before it: the
+ * dispatch's own refusals know more than this one does. `defineMemory`'s
+ * TOP_K arm knows about the `ranksBy: 'server-text'` exemption AND about the
+ * write half it takes away; the CAUSAL arm knows that exemption does not
+ * apply to it; the EXTRACT arm knows the `llm` matters only for
+ * `extractor: 'llm'`. Speaking first would replace those messages with a
+ * blunter one. This is the BACKSTOP: it says something only when nothing
+ * better already did, and its job is that no declared requirement can go
+ * unchecked — the failure it exists to prevent is a missing dependency
+ * surfacing as a `TypeError` from five frames inside a stage, halfway
+ * through a paid run.
+ *
+ * @param options the config as written by the caller.
+ * @param site    the call to name in the message, e.g. `defineMemory[chat]`.
+ */
+export declare function assertStrategyRequirements(options: DefineMemoryOptions, site: string): void;
+//# sourceMappingURL=strategies.d.ts.map

package/dist/types/memory/strategies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../../../src/memory/strategies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EAEhB,MAAM,mBAAmB,CAAC;AAI3B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,yBAAyB,GACjC,UAAU,GACV,cAAc,GACd,KAAK,GACL,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAEpC;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC5D,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;CACvC;AAsFD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,IAAI,SAAS,kBAAkB,EAAE,CAEpE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAE/E;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE3F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "9.4.0",
+  "version": "9.5.0",
   "description": "The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.",
   "license": "MIT",
   "type": "commonjs",