agentfootprint 9.4.0 → 9.5.1

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":"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"}
+{"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,134 @@
+/**
+ * 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 + the two guards that enforce
+ *          them — SHAPE first (`assertStrategyShape`: is this even a
+ *          strategy?), REQUIREMENTS after (`assertStrategyRequirements`: can
+ *          this deployment run it?).
+ * 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 strategy whose SHAPE is wrong, before anything reads into it.
+ *
+ * WHY it runs FIRST, ahead of both the pipeline dispatch and the
+ * requirements walk: those two read FIELDS off the strategy
+ * (`strategies[0]`, `s.embedder`, `for (const sub of strategy.strategies)`),
+ * and a field read off a shape that never had it is a `TypeError` with the
+ * library's internals in the text — `Cannot read properties of undefined
+ * (reading '0')` for `{ kind: 'hybrid', size: 5 }`, which names neither the
+ * option the caller got wrong nor the one they meant. A caller cannot act on
+ * that. This guard turns every such read into a refusal that names the
+ * field, shows the line that would have worked, and points at the catalogue.
+ *
+ * It checks SHAPE only — is this an object, does it carry a `kind`, does a
+ * `hybrid` carry the array that makes it a hybrid. It deliberately does NOT
+ * judge whether the kind is real or legal for the type: the dispatch refuses
+ * those and names the alternative for that type, which is the better message.
+ *
+ * @param strategy the strategy exactly as the caller wrote it — `unknown`,
+ *                 because the whole point is that it may not be a `Strategy`.
+ * @param site     the call to name in the message, e.g. `defineMemory[chat]`.
+ */
+export declare function assertStrategyShape(strategy: unknown, site: string): void;
+/**
+ * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;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;AAuBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEzE;AA6ED;;;;;;;;;;;;;;;;;;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.1",
   "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",