@framers/agentos 0.3.1 → 0.3.2

package/dist/memory/retrieval/typed-network/FourWayRrf.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @file FourWayRrf.ts
+ * @description Four-way Reciprocal Rank Fusion over the typed-network
+ * retrieval signals: semantic similarity, BM25 lexical match, graph
+ * spreading activation, and temporal interval overlap. Per Hindsight
+ * §2.4.3, the fusion uses standard RRF with `k=60`:
+ *
+ *   score(f) = Σ over rankings R of [1 / (k + rank_R(f))]
+ *
+ * Output is a single ranked list combining all four signals. Facts
+ * present in only some rankings are still scored — RRF naturally
+ * tolerates missing rankings because absent IDs contribute zero.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/FourWayRrf
+ */
+/**
+ * Inputs to the fusion. Each list is an ordered array of fact IDs
+ * from a separate retrieval signal.
+ */
+export interface FourWayRrfInput {
+    /** Cosine-similarity ranking over fact embeddings. */
+    semantic: string[];
+    /** BM25 ranking over fact text. */
+    bm25: string[];
+    /** Spreading-activation ranking over the typed-network graph. */
+    graphActivation: string[];
+    /** Temporal-interval-overlap ranking against the query timestamp. */
+    temporalOverlap: string[];
+}
+/**
+ * Fusion options.
+ */
+export interface FourWayRrfOptions {
+    /** RRF constant. Default 60 per the standard literature. */
+    k?: number;
+    /**
+     * Optional per-signal weight multiplier. Defaults to {1, 1, 1, 1}
+     * (uniform RRF). Use to emphasize one signal over others — e.g.
+     * downweighting graph activation when the typed network is sparse.
+     */
+    weights?: Partial<Record<keyof FourWayRrfInput, number>>;
+}
+/**
+ * Fuse four retrieval rankings via Reciprocal Rank Fusion. Returns
+ * the merged list ordered by descending fused score.
+ *
+ * @param input - Four ranked lists (semantic, BM25, graph, temporal).
+ * @param options - RRF k constant + optional per-signal weights.
+ */
+export declare function fourWayRrf(input: FourWayRrfInput, options?: FourWayRrfOptions): string[];
+//# sourceMappingURL=FourWayRrf.d.ts.map

package/dist/memory/retrieval/typed-network/FourWayRrf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FourWayRrf.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/FourWayRrf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,mCAAmC;IACnC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,iEAAiE;IACjE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,qEAAqE;IACrE,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,CAAC,CAAC,EAAE,MAAM,CAAC;IACX;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,eAAe,EAAE,MAAM,CAAC,CAAC,CAAC;CAC1D;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,iBAAsB,GAC9B,MAAM,EAAE,CA8BV"}

package/dist/memory/retrieval/typed-network/FourWayRrf.js

@@ -0,0 +1,47 @@
+/**
+ * @file FourWayRrf.ts
+ * @description Four-way Reciprocal Rank Fusion over the typed-network
+ * retrieval signals: semantic similarity, BM25 lexical match, graph
+ * spreading activation, and temporal interval overlap. Per Hindsight
+ * §2.4.3, the fusion uses standard RRF with `k=60`:
+ *
+ *   score(f) = Σ over rankings R of [1 / (k + rank_R(f))]
+ *
+ * Output is a single ranked list combining all four signals. Facts
+ * present in only some rankings are still scored — RRF naturally
+ * tolerates missing rankings because absent IDs contribute zero.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/FourWayRrf
+ */
+/**
+ * Fuse four retrieval rankings via Reciprocal Rank Fusion. Returns
+ * the merged list ordered by descending fused score.
+ *
+ * @param input - Four ranked lists (semantic, BM25, graph, temporal).
+ * @param options - RRF k constant + optional per-signal weights.
+ */
+export function fourWayRrf(input, options = {}) {
+    const k = options.k ?? 60;
+    const w = {
+        semantic: options.weights?.semantic ?? 1,
+        bm25: options.weights?.bm25 ?? 1,
+        graphActivation: options.weights?.graphActivation ?? 1,
+        temporalOverlap: options.weights?.temporalOverlap ?? 1,
+    };
+    const scores = new Map();
+    const accumulate = (ranking, weight) => {
+        ranking.forEach((id, idx) => {
+            const rank = idx + 1;
+            const contribution = (1.0 / (k + rank)) * weight;
+            scores.set(id, (scores.get(id) ?? 0) + contribution);
+        });
+    };
+    accumulate(input.semantic, w.semantic);
+    accumulate(input.bm25, w.bm25);
+    accumulate(input.graphActivation, w.graphActivation);
+    accumulate(input.temporalOverlap, w.temporalOverlap);
+    return [...scores.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([id]) => id);
+}
+//# sourceMappingURL=FourWayRrf.js.map

package/dist/memory/retrieval/typed-network/FourWayRrf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FourWayRrf.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/FourWayRrf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA+BH;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACxB,KAAsB,EACtB,UAA6B,EAAE;IAE/B,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1B,MAAM,CAAC,GAAG;QACR,QAAQ,EAAE,OAAO,CAAC,OAAO,EAAE,QAAQ,IAAI,CAAC;QACxC,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC;QAChC,eAAe,EAAE,OAAO,CAAC,OAAO,EAAE,eAAe,IAAI,CAAC;QACtD,eAAe,EAAE,OAAO,CAAC,OAAO,EAAE,eAAe,IAAI,CAAC;KACvD,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEzC,MAAM,UAAU,GAAG,CACjB,OAAiB,EACjB,MAAc,EACR,EAAE;QACR,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE;YAC1B,MAAM,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC;YACrB,MAAM,YAAY,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC;YACjD,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC;QACvD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,UAAU,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC;IACvC,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC/B,UAAU,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC,CAAC,eAAe,CAAC,CAAC;IACrD,UAAU,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC,CAAC,eAAe,CAAC,CAAC;IAErD,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;SACzB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;SAC3B,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;AACvB,CAAC"}

package/dist/memory/retrieval/typed-network/TemporalIntervalOverlap.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file TemporalIntervalOverlap.ts
+ * @description Temporal-overlap ranking signal for the 4-way RRF
+ * fusion. Given a query timestamp and a set of typed facts, ranks the
+ * facts by how tightly their occurrence intervals (`τs, τe`) bracket
+ * the query timestamp, with a graceful fallback to mention-timestamp
+ * distance for facts without a full interval.
+ *
+ * Hindsight Eq. 12 weighs temporal edges by `exp(−Δt / σt)`. This
+ * file's `rankByTemporalOverlap` produces the same monotone signal in
+ * a form suitable for the BM25 / semantic / spreading-activation /
+ * temporal four-way RRF fusion (see {@link FourWayRrf}).
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/TemporalIntervalOverlap
+ */
+import type { TypedFact } from './types.js';
+/**
+ * Rank an array of typed facts by their temporal proximity to a query
+ * timestamp. Facts whose `(start, end)` interval contains the query
+ * rank highest, with tighter intervals (smaller width) scoring higher
+ * within the contained set. Facts whose interval lies outside the
+ * query rank by the minimum endpoint distance. Facts with only a
+ * mention timestamp fall back to mention-distance.
+ *
+ * Returns a new array; the input is not mutated. Stable ordering
+ * within tied scores follows JavaScript's `Array.prototype.sort`
+ * insertion order.
+ *
+ * @param facts - Typed facts to rank.
+ * @param queryTimestamp - ISO 8601 string. Invalid timestamps fall
+ *   back to original ordering.
+ */
+export declare function rankByTemporalOverlap(facts: TypedFact[], queryTimestamp: string): TypedFact[];
+//# sourceMappingURL=TemporalIntervalOverlap.d.ts.map

package/dist/memory/retrieval/typed-network/TemporalIntervalOverlap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TemporalIntervalOverlap.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/TemporalIntervalOverlap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAK5C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,EAAE,EAClB,cAAc,EAAE,MAAM,GACrB,SAAS,EAAE,CAUb"}

package/dist/memory/retrieval/typed-network/TemporalIntervalOverlap.js

@@ -0,0 +1,86 @@
+/**
+ * @file TemporalIntervalOverlap.ts
+ * @description Temporal-overlap ranking signal for the 4-way RRF
+ * fusion. Given a query timestamp and a set of typed facts, ranks the
+ * facts by how tightly their occurrence intervals (`τs, τe`) bracket
+ * the query timestamp, with a graceful fallback to mention-timestamp
+ * distance for facts without a full interval.
+ *
+ * Hindsight Eq. 12 weighs temporal edges by `exp(−Δt / σt)`. This
+ * file's `rankByTemporalOverlap` produces the same monotone signal in
+ * a form suitable for the BM25 / semantic / spreading-activation /
+ * temporal four-way RRF fusion (see {@link FourWayRrf}).
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/TemporalIntervalOverlap
+ */
+/** One day in milliseconds — used as the natural unit for distance penalties. */
+const DAY_MS = 86400000;
+/**
+ * Rank an array of typed facts by their temporal proximity to a query
+ * timestamp. Facts whose `(start, end)` interval contains the query
+ * rank highest, with tighter intervals (smaller width) scoring higher
+ * within the contained set. Facts whose interval lies outside the
+ * query rank by the minimum endpoint distance. Facts with only a
+ * mention timestamp fall back to mention-distance.
+ *
+ * Returns a new array; the input is not mutated. Stable ordering
+ * within tied scores follows JavaScript's `Array.prototype.sort`
+ * insertion order.
+ *
+ * @param facts - Typed facts to rank.
+ * @param queryTimestamp - ISO 8601 string. Invalid timestamps fall
+ *   back to original ordering.
+ */
+export function rankByTemporalOverlap(facts, queryTimestamp) {
+    const queryMs = Date.parse(queryTimestamp);
+    if (Number.isNaN(queryMs))
+        return [...facts];
+    const scored = facts.map((f) => ({
+        fact: f,
+        score: scoreOverlap(f, queryMs),
+    }));
+    scored.sort((a, b) => b.score - a.score);
+    return scored.map((s) => s.fact);
+}
+/**
+ * Score a single fact against the query timestamp. Higher = more
+ * relevant.
+ *
+ * Score scale:
+ * - In-interval facts produce scores in (1.0, 2.0] — every in-interval
+ *   fact outranks every out-of-interval fact regardless of width vs
+ *   endpoint-distance. Tighter intervals score closer to 2.0.
+ * - Out-of-interval facts produce scores in (0, 1.0) — closer
+ *   endpoint distances score nearer to 1.0.
+ * - Mention-only facts produce scores in (0, 1.0) — same scale as
+ *   out-of-interval (the mention timestamp is treated as a degenerate
+ *   point-interval).
+ *
+ * The +1.0 boost on in-interval guarantees the order semantics the
+ * Hindsight paper §2.4.1 implies: temporal containment is a
+ * categorical match; width breaks ties within that category. Without
+ * the boost, a wide containing interval can score below a narrow non-
+ * containing one (which is geometrically wrong).
+ */
+function scoreOverlap(fact, queryMs) {
+    const start = fact.temporal.start ? Date.parse(fact.temporal.start) : NaN;
+    const end = fact.temporal.end ? Date.parse(fact.temporal.end) : NaN;
+    const mention = Date.parse(fact.temporal.mention);
+    if (!Number.isNaN(start) && !Number.isNaN(end)) {
+        if (queryMs >= start && queryMs <= end) {
+            // Query inside interval — score by inverse interval width,
+            // boosted by +1.0 so it outranks all out-of-interval facts.
+            const width = Math.max(1, end - start);
+            return 1.0 + 1.0 / (1 + width / DAY_MS);
+        }
+        // Query outside — penalize by distance to nearest endpoint.
+        const dist = Math.min(Math.abs(queryMs - start), Math.abs(queryMs - end));
+        return 1.0 / (1 + dist / DAY_MS);
+    }
+    // Fall back to mention-timestamp distance.
+    if (Number.isNaN(mention))
+        return 0;
+    const dist = Math.abs(queryMs - mention);
+    return 1.0 / (1 + dist / DAY_MS);
+}
+//# sourceMappingURL=TemporalIntervalOverlap.js.map

package/dist/memory/retrieval/typed-network/TemporalIntervalOverlap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TemporalIntervalOverlap.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/TemporalIntervalOverlap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,iFAAiF;AACjF,MAAM,MAAM,GAAG,QAAU,CAAC;AAE1B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAkB,EAClB,cAAsB;IAEtB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC3C,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;IAE7C,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/B,IAAI,EAAE,CAAC;QACP,KAAK,EAAE,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC,CAAC,CAAC;IACJ,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IACzC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAS,YAAY,CAAC,IAAe,EAAE,OAAe;IACpD,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC1E,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACpE,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAElD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,IAAI,OAAO,IAAI,KAAK,IAAI,OAAO,IAAI,GAAG,EAAE,CAAC;YACvC,2DAA2D;YAC3D,4DAA4D;YAC5D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,KAAK,CAAC,CAAC;YACvC,OAAO,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC,GAAG,KAAK,GAAG,MAAM,CAAC,CAAC;QAC1C,CAAC;QACD,4DAA4D;QAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,KAAK,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC;QAC1E,OAAO,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,MAAM,CAAC,CAAC;IACnC,CAAC;IAED,2CAA2C;IAC3C,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC,CAAC;IACzC,OAAO,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,MAAM,CAAC,CAAC;AACnC,CAAC"}

package/dist/memory/retrieval/typed-network/TypedNetworkObserver.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @file TypedNetworkObserver.ts
+ * @description LLM-driven extractor that turns a conversation block
+ * into 0+ {@link TypedFact}s. Wraps the 6-step extraction prompt and
+ * the zod-validated parsing of the LLM's structured-output response.
+ *
+ * Production wiring: a typical caller constructs the observer once per
+ * pipeline (re-using the same `gpt-5-mini` adapter), then invokes
+ * {@link TypedNetworkObserver.extract} per session. The returned facts
+ * are then upserted into a {@link TypedNetworkStore} and embedded by
+ * the host's {@link IEmbeddingManager}.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/TypedNetworkObserver
+ */
+import type { TypedFact } from './types.js';
+/**
+ * Provider-agnostic LLM interface for the extractor. Matches the
+ * shape used elsewhere in agentos for classifier / observer LLM
+ * adapters: a single `invoke(args)` async method returning the raw
+ * text response. Implementations wrap OpenAI, Anthropic, local
+ * models, or test mocks.
+ */
+export interface ITypedExtractionLLM {
+    invoke(args: {
+        system: string;
+        user: string;
+        maxTokens: number;
+        temperature: number;
+    }): Promise<string>;
+}
+/**
+ * Construction options for the observer.
+ */
+export interface TypedNetworkObserverOptions {
+    /** LLM adapter implementing the 6-step extraction call. */
+    llm: ITypedExtractionLLM;
+    /** Max output tokens. Default 4096 (Hindsight extractions are typically 50-200 facts × ~30 tokens each). */
+    maxTokens?: number;
+    /** Temperature. Default 0 for deterministic extraction. */
+    temperature?: number;
+}
+/**
+ * The 6-step extractor. Stateless aside from its constructor options;
+ * safe to share across concurrent extractions.
+ */
+export declare class TypedNetworkObserver {
+    private readonly llm;
+    private readonly maxTokens;
+    private readonly temperature;
+    constructor(options: TypedNetworkObserverOptions);
+    /**
+     * Extract typed facts from a conversation block. Uses the 6-step
+     * prompt + zod-validated parsing. The resulting facts have stable
+     * IDs of the form `<sessionId>-fact-<index>` so re-extraction
+     * against the same content reproduces the same IDs.
+     *
+     * @param sessionText - Full conversation text. Will be wrapped in
+     *   the user prompt's delimiters automatically.
+     * @param sessionId - Stable identifier used to namespace the
+     *   resulting fact IDs.
+     * @returns Array of {@link TypedFact}s, possibly empty.
+     * @throws ZodError if the LLM output fails schema validation.
+     * @throws SyntaxError if the LLM output is not valid JSON.
+     */
+    extract(sessionText: string, sessionId: string): Promise<TypedFact[]>;
+}
+//# sourceMappingURL=TypedNetworkObserver.d.ts.map

package/dist/memory/retrieval/typed-network/TypedNetworkObserver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TypedNetworkObserver.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/TypedNetworkObserver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,IAAI,EAAE;QACX,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,2DAA2D;IAC3D,GAAG,EAAE,mBAAmB,CAAC;IACzB,4GAA4G;IAC5G,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsB;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,OAAO,EAAE,2BAA2B;IAMhD;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;CAwB5E"}

package/dist/memory/retrieval/typed-network/TypedNetworkObserver.js

@@ -0,0 +1,78 @@
+/**
+ * @file TypedNetworkObserver.ts
+ * @description LLM-driven extractor that turns a conversation block
+ * into 0+ {@link TypedFact}s. Wraps the 6-step extraction prompt and
+ * the zod-validated parsing of the LLM's structured-output response.
+ *
+ * Production wiring: a typical caller constructs the observer once per
+ * pipeline (re-using the same `gpt-5-mini` adapter), then invokes
+ * {@link TypedNetworkObserver.extract} per session. The returned facts
+ * are then upserted into a {@link TypedNetworkStore} and embedded by
+ * the host's {@link IEmbeddingManager}.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/TypedNetworkObserver
+ */
+import { TypedExtractionSchema } from './prompts/extraction-schema.js';
+import { TYPED_EXTRACTION_SYSTEM_PROMPT, buildExtractionUserPrompt, } from './prompts/extraction-prompt.js';
+/**
+ * The 6-step extractor. Stateless aside from its constructor options;
+ * safe to share across concurrent extractions.
+ */
+export class TypedNetworkObserver {
+    constructor(options) {
+        this.llm = options.llm;
+        this.maxTokens = options.maxTokens ?? 4096;
+        this.temperature = options.temperature ?? 0;
+    }
+    /**
+     * Extract typed facts from a conversation block. Uses the 6-step
+     * prompt + zod-validated parsing. The resulting facts have stable
+     * IDs of the form `<sessionId>-fact-<index>` so re-extraction
+     * against the same content reproduces the same IDs.
+     *
+     * @param sessionText - Full conversation text. Will be wrapped in
+     *   the user prompt's delimiters automatically.
+     * @param sessionId - Stable identifier used to namespace the
+     *   resulting fact IDs.
+     * @returns Array of {@link TypedFact}s, possibly empty.
+     * @throws ZodError if the LLM output fails schema validation.
+     * @throws SyntaxError if the LLM output is not valid JSON.
+     */
+    async extract(sessionText, sessionId) {
+        const raw = await this.llm.invoke({
+            system: TYPED_EXTRACTION_SYSTEM_PROMPT,
+            user: buildExtractionUserPrompt(sessionText),
+            maxTokens: this.maxTokens,
+            temperature: this.temperature,
+        });
+        // Strip markdown code fences if the LLM wraps the JSON in them
+        // (some models do this even with explicit "no commentary" prompts).
+        const stripped = stripCodeFence(raw);
+        const json = JSON.parse(stripped);
+        const parsed = TypedExtractionSchema.parse(json);
+        return parsed.facts.map((f, idx) => ({
+            id: `${sessionId}-fact-${idx}`,
+            bank: f.bank,
+            text: f.text,
+            embedding: [],
+            temporal: f.temporal,
+            participants: f.participants,
+            reasoningMarkers: f.reasoning_markers,
+            entities: f.entities,
+            confidence: f.confidence,
+        }));
+    }
+}
+/**
+ * Strip leading/trailing markdown code fences. Tolerates both
+ * triple-backtick-with-language and bare triple-backtick wrappers.
+ */
+function stripCodeFence(s) {
+    const trimmed = s.trim();
+    if (!trimmed.startsWith('```'))
+        return trimmed;
+    // Drop the opening ``` (with or without language tag) and any trailing ```
+    const withoutOpen = trimmed.replace(/^```(?:json|JSON)?\s*\n?/, '');
+    return withoutOpen.replace(/\n?```\s*$/, '');
+}
+//# sourceMappingURL=TypedNetworkObserver.js.map

package/dist/memory/retrieval/typed-network/TypedNetworkObserver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TypedNetworkObserver.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/TypedNetworkObserver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,gCAAgC,CAAC;AA+BxC;;;GAGG;AACH,MAAM,OAAO,oBAAoB;IAK/B,YAAY,OAAoC;QAC9C,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;QAC3C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,OAAO,CAAC,WAAmB,EAAE,SAAiB;QAClD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;YAChC,MAAM,EAAE,8BAA8B;YACtC,IAAI,EAAE,yBAAyB,CAAC,WAAW,CAAC;YAC5C,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC,CAAC;QACH,+DAA+D;QAC/D,oEAAoE;QACpE,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAClC,MAAM,MAAM,GAAG,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACjD,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;YACnC,EAAE,EAAE,GAAG,SAAS,SAAS,GAAG,EAAE;YAC9B,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,SAAS,EAAE,EAAE;YACb,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,YAAY,EAAE,CAAC,CAAC,YAAY;YAC5B,gBAAgB,EAAE,CAAC,CAAC,iBAAiB;YACrC,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,UAAU,EAAE,CAAC,CAAC,UAAU;SACzB,CAAC,CAAC,CAAC;IACN,CAAC;CACF;AAED;;;GAGG;AACH,SAAS,cAAc,CAAC,CAAS;IAC/B,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACzB,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IAC/C,2EAA2E;IAC3E,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,0BAA0B,EAAE,EAAE,CAAC,CAAC;IACpE,OAAO,WAAW,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC"}

package/dist/memory/retrieval/typed-network/TypedNetworkStore.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @file TypedNetworkStore.ts
+ * @description In-memory 4-bank store for typed facts plus a
+ * bidirectional edge index. Stage E primary data structure.
+ *
+ * The store is independent of persistence — it holds the working set
+ * of typed facts and their edges for a single retrieval session. A
+ * future SQL-backed extension can wrap the same interface for cross-
+ * session persistence.
+ *
+ * Insertion semantics:
+ * - {@link addFact} routes by `fact.bank` into the correct bank set.
+ * - {@link addEdge} stores the forward edge AND a paired reverse edge
+ *   for {@link EdgeKind} entries that are bidirectional in Hindsight
+ *   §2.4.1 (entity, semantic, temporal). Causal edges are directional
+ *   in the paper; this implementation stores both directions for
+ *   simplicity at small graph sizes — the consumer can filter by
+ *   `kind === 'causal'` + edge ordering if direction-sensitive queries
+ *   are needed.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/TypedNetworkStore
+ */
+import type { BankId, TypedFact, TypedEdge } from './types.js';
+/**
+ * In-memory 4-bank store. Holds facts indexed by ID + per-bank ID set
+ * + outgoing-edge map. Constructed empty; populate via {@link addFact}
+ * and {@link addEdge}.
+ */
+export declare class TypedNetworkStore {
+    private readonly facts;
+    private readonly banks;
+    private readonly edgesFrom;
+    /**
+     * Construct an empty store with one entry per bank in
+     * {@link BANK_IDS}. Pre-allocating avoids null-checks in the
+     * insertion path.
+     */
+    constructor();
+    /**
+     * Insert a fact. Routes into `fact.bank` by membership in the
+     * appropriate `banks[bank]` set. Re-inserting the same ID overwrites
+     * the prior fact and leaves bank membership unchanged.
+     */
+    addFact(fact: TypedFact): void;
+    /**
+     * Lookup a fact by ID. Returns `undefined` if not present.
+     */
+    getFact(id: string): TypedFact | undefined;
+    /**
+     * Return the set of fact IDs in a given bank. Live reference — do
+     * not mutate the returned `Set` directly.
+     */
+    getBank(bank: BankId): Set<string>;
+    /**
+     * Total fact count across all banks. Useful for debugging /
+     * consolidation pruning thresholds.
+     */
+    size(): number;
+    /**
+     * Insert a typed edge. Stores both the forward edge (`from → to`)
+     * and a paired reverse edge (`to → from`) so spreading activation
+     * traverses bidirectionally per Hindsight §2.4.1. Identical reverse-
+     * edge insertion is what makes entity, semantic, and temporal links
+     * bidirectional by construction.
+     */
+    addEdge(edge: TypedEdge): void;
+    /**
+     * Outgoing edges from a fact. Empty array if the fact has no
+     * outgoing edges or is unknown.
+     */
+    getEdges(factId: string): TypedEdge[];
+    /**
+     * Iterate every fact in the store. Useful for export and
+     * persistence.
+     */
+    iterateFacts(): IterableIterator<TypedFact>;
+    /**
+     * Append an edge to the outgoing-edge map for `fromId`, allocating
+     * the inner array on first insertion.
+     */
+    private appendEdge;
+}
+//# sourceMappingURL=TypedNetworkStore.d.ts.map

package/dist/memory/retrieval/typed-network/TypedNetworkStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TypedNetworkStore.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/TypedNetworkStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG/D;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;IAE5D;;;;OAIG;;IAOH;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAK9B;;OAEG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAI1C;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAIlC;;;OAGG;IACH,IAAI,IAAI,MAAM;IAId;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAU9B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE;IAIrC;;;OAGG;IACF,YAAY,IAAI,gBAAgB,CAAC,SAAS,CAAC;IAI5C;;;OAGG;IACH,OAAO,CAAC,UAAU;CAKnB"}

package/dist/memory/retrieval/typed-network/TypedNetworkStore.js

@@ -0,0 +1,109 @@
+/**
+ * @file TypedNetworkStore.ts
+ * @description In-memory 4-bank store for typed facts plus a
+ * bidirectional edge index. Stage E primary data structure.
+ *
+ * The store is independent of persistence — it holds the working set
+ * of typed facts and their edges for a single retrieval session. A
+ * future SQL-backed extension can wrap the same interface for cross-
+ * session persistence.
+ *
+ * Insertion semantics:
+ * - {@link addFact} routes by `fact.bank` into the correct bank set.
+ * - {@link addEdge} stores the forward edge AND a paired reverse edge
+ *   for {@link EdgeKind} entries that are bidirectional in Hindsight
+ *   §2.4.1 (entity, semantic, temporal). Causal edges are directional
+ *   in the paper; this implementation stores both directions for
+ *   simplicity at small graph sizes — the consumer can filter by
+ *   `kind === 'causal'` + edge ordering if direction-sensitive queries
+ *   are needed.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/TypedNetworkStore
+ */
+import { BANK_IDS } from './types.js';
+/**
+ * In-memory 4-bank store. Holds facts indexed by ID + per-bank ID set
+ * + outgoing-edge map. Constructed empty; populate via {@link addFact}
+ * and {@link addEdge}.
+ */
+export class TypedNetworkStore {
+    /**
+     * Construct an empty store with one entry per bank in
+     * {@link BANK_IDS}. Pre-allocating avoids null-checks in the
+     * insertion path.
+     */
+    constructor() {
+        this.facts = new Map();
+        this.edgesFrom = new Map();
+        this.banks = Object.fromEntries(BANK_IDS.map((b) => [b, new Set()]));
+    }
+    /**
+     * Insert a fact. Routes into `fact.bank` by membership in the
+     * appropriate `banks[bank]` set. Re-inserting the same ID overwrites
+     * the prior fact and leaves bank membership unchanged.
+     */
+    addFact(fact) {
+        this.facts.set(fact.id, fact);
+        this.banks[fact.bank].add(fact.id);
+    }
+    /**
+     * Lookup a fact by ID. Returns `undefined` if not present.
+     */
+    getFact(id) {
+        return this.facts.get(id);
+    }
+    /**
+     * Return the set of fact IDs in a given bank. Live reference — do
+     * not mutate the returned `Set` directly.
+     */
+    getBank(bank) {
+        return this.banks[bank];
+    }
+    /**
+     * Total fact count across all banks. Useful for debugging /
+     * consolidation pruning thresholds.
+     */
+    size() {
+        return this.facts.size;
+    }
+    /**
+     * Insert a typed edge. Stores both the forward edge (`from → to`)
+     * and a paired reverse edge (`to → from`) so spreading activation
+     * traverses bidirectionally per Hindsight §2.4.1. Identical reverse-
+     * edge insertion is what makes entity, semantic, and temporal links
+     * bidirectional by construction.
+     */
+    addEdge(edge) {
+        this.appendEdge(edge.fromFactId, edge);
+        this.appendEdge(edge.toFactId, {
+            fromFactId: edge.toFactId,
+            toFactId: edge.fromFactId,
+            kind: edge.kind,
+            weight: edge.weight,
+        });
+    }
+    /**
+     * Outgoing edges from a fact. Empty array if the fact has no
+     * outgoing edges or is unknown.
+     */
+    getEdges(factId) {
+        return this.edgesFrom.get(factId) ?? [];
+    }
+    /**
+     * Iterate every fact in the store. Useful for export and
+     * persistence.
+     */
+    *iterateFacts() {
+        yield* this.facts.values();
+    }
+    /**
+     * Append an edge to the outgoing-edge map for `fromId`, allocating
+     * the inner array on first insertion.
+     */
+    appendEdge(fromId, edge) {
+        const list = this.edgesFrom.get(fromId) ?? [];
+        list.push(edge);
+        this.edgesFrom.set(fromId, list);
+    }
+}
+//# sourceMappingURL=TypedNetworkStore.js.map

package/dist/memory/retrieval/typed-network/TypedNetworkStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TypedNetworkStore.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/TypedNetworkStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;GAIG;AACH,MAAM,OAAO,iBAAiB;IAK5B;;;;OAIG;IACH;QATiB,UAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;QAErC,cAAS,GAAG,IAAI,GAAG,EAAuB,CAAC;QAQ1D,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,WAAW,CAC7B,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,GAAG,EAAU,CAAC,CAAC,CACb,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,IAAe;QACrB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,EAAU;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,IAAY;QAClB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;;OAGG;IACH,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,IAAe;QACrB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE;YAC7B,UAAU,EAAE,IAAI,CAAC,QAAQ;YACzB,QAAQ,EAAE,IAAI,CAAC,UAAU;YACzB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,MAAc;QACrB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC1C,CAAC;IAED;;;OAGG;IACH,CAAC,YAAY;QACX,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;IAC7B,CAAC;IAED;;;OAGG;IACK,UAAU,CAAC,MAAc,EAAE,IAAe;QAChD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC9C,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;CACF"}

package/dist/memory/retrieval/typed-network/TypedSpreadingActivation.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file TypedSpreadingActivation.ts
+ * @description Spreading activation across the typed-network graph
+ * per Hindsight Equation 12 (§2.4.1):
+ *
+ *   A(fj, t+1) = max[(fi,fj,w,ℓ)∈E] [A(fi,t) · w · δ · μ(ℓ)]
+ *
+ * Where:
+ * - `δ ∈ (0, 1)` — decay factor per hop
+ * - `μ(ℓ)` — link-type multiplier (one of: temporal, semantic,
+ *   entity, causal)
+ * - `A(fi,t)` — activation of node fi at hop t
+ * - `w` — edge weight
+ *
+ * The implementation is a bounded BFS with the max-aggregator over
+ * incoming edges (per the `max[...]` in Eq. 12) and an early-exit
+ * when no node's activation exceeds the threshold. Default depth=3
+ * matches the existing untyped {@link SpreadingActivation} primitive
+ * in agentos.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/TypedSpreadingActivation
+ */
+import type { TypedNetworkStore } from './TypedNetworkStore.js';
+import type { EdgeKind } from './types.js';
+/**
+ * Per-edge-kind activation multipliers `μ(ℓ)` from Hindsight §2.4.1.
+ * - **entity**: 1.0 (the strongest link, bidirectional shared-entity)
+ * - **causal**: 1.0 (LLM-extracted reasoning chain — high signal)
+ * - **temporal**: 0.7 (loose proximity in time)
+ * - **semantic**: 0.6 (cosine ≥ θs threshold; treat as supporting,
+ *   not primary, since the embedding path also runs separately at
+ *   the four-way RRF fusion)
+ *
+ * These default values are tunable per-deployment; pass an override
+ * map via {@link TypedSpreadingActivationOptions.edgeMultipliers}.
+ */
+export declare const DEFAULT_EDGE_MULTIPLIERS: Record<EdgeKind, number>;
+/**
+ * Construction options for spreading activation.
+ */
+export interface TypedSpreadingActivationOptions {
+    /** Per-hop decay factor δ ∈ (0, 1). Default 0.5. */
+    decay: number;
+    /** Override the default {@link DEFAULT_EDGE_MULTIPLIERS}. */
+    edgeMultipliers?: Record<EdgeKind, number>;
+}
+/**
+ * Per-call options.
+ */
+export interface SpreadOptions {
+    /** Maximum hops from a seed node. Default cap on graph traversal. */
+    maxDepth: number;
+    /** Activation cutoff. Nodes below this threshold are not propagated. */
+    activationThreshold?: number;
+}
+/**
+ * Spreading-activation primitive over a typed network. Constructed
+ * once per pipeline; safe to share across queries (all per-call state
+ * lives in the local activation map).
+ */
+export declare class TypedSpreadingActivation {
+    private readonly decay;
+    private readonly μ;
+    constructor(options: TypedSpreadingActivationOptions);
+    /**
+     * Run spreading activation from a set of seed fact IDs. Returns a
+     * map from fact ID to activation level, including the seeds (at
+     * activation 1.0) and every reachable fact above the threshold.
+     *
+     * Uses Eq. 12's max-aggregation: each step computes the candidate
+     * activation `current · weight · δ · μ(kind)` for every outgoing
+     * edge, then keeps the max across paths into a node.
+     *
+     * @param store - The typed network to traverse.
+     * @param seedIds - Initial seed fact IDs (activated at 1.0).
+     * @param options - maxDepth + activationThreshold.
+     */
+    spread(store: TypedNetworkStore, seedIds: string[], options: SpreadOptions): Map<string, number>;
+}
+//# sourceMappingURL=TypedSpreadingActivation.d.ts.map

package/dist/memory/retrieval/typed-network/TypedSpreadingActivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TypedSpreadingActivation.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/TypedSpreadingActivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAK7D,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,CAAC,CAA2B;gBAEjC,OAAO,EAAE,+BAA+B;IAKpD;;;;;;;;;;;;OAYG;IACH,MAAM,CACJ,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,aAAa,GACrB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;CAkCvB"}

package/dist/memory/retrieval/typed-network/TypedSpreadingActivation.js

@@ -0,0 +1,97 @@
+/**
+ * @file TypedSpreadingActivation.ts
+ * @description Spreading activation across the typed-network graph
+ * per Hindsight Equation 12 (§2.4.1):
+ *
+ *   A(fj, t+1) = max[(fi,fj,w,ℓ)∈E] [A(fi,t) · w · δ · μ(ℓ)]
+ *
+ * Where:
+ * - `δ ∈ (0, 1)` — decay factor per hop
+ * - `μ(ℓ)` — link-type multiplier (one of: temporal, semantic,
+ *   entity, causal)
+ * - `A(fi,t)` — activation of node fi at hop t
+ * - `w` — edge weight
+ *
+ * The implementation is a bounded BFS with the max-aggregator over
+ * incoming edges (per the `max[...]` in Eq. 12) and an early-exit
+ * when no node's activation exceeds the threshold. Default depth=3
+ * matches the existing untyped {@link SpreadingActivation} primitive
+ * in agentos.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/TypedSpreadingActivation
+ */
+/**
+ * Per-edge-kind activation multipliers `μ(ℓ)` from Hindsight §2.4.1.
+ * - **entity**: 1.0 (the strongest link, bidirectional shared-entity)
+ * - **causal**: 1.0 (LLM-extracted reasoning chain — high signal)
+ * - **temporal**: 0.7 (loose proximity in time)
+ * - **semantic**: 0.6 (cosine ≥ θs threshold; treat as supporting,
+ *   not primary, since the embedding path also runs separately at
+ *   the four-way RRF fusion)
+ *
+ * These default values are tunable per-deployment; pass an override
+ * map via {@link TypedSpreadingActivationOptions.edgeMultipliers}.
+ */
+export const DEFAULT_EDGE_MULTIPLIERS = {
+    entity: 1.0,
+    causal: 1.0,
+    temporal: 0.7,
+    semantic: 0.6,
+};
+/**
+ * Spreading-activation primitive over a typed network. Constructed
+ * once per pipeline; safe to share across queries (all per-call state
+ * lives in the local activation map).
+ */
+export class TypedSpreadingActivation {
+    constructor(options) {
+        this.decay = options.decay;
+        this.μ = options.edgeMultipliers ?? DEFAULT_EDGE_MULTIPLIERS;
+    }
+    /**
+     * Run spreading activation from a set of seed fact IDs. Returns a
+     * map from fact ID to activation level, including the seeds (at
+     * activation 1.0) and every reachable fact above the threshold.
+     *
+     * Uses Eq. 12's max-aggregation: each step computes the candidate
+     * activation `current · weight · δ · μ(kind)` for every outgoing
+     * edge, then keeps the max across paths into a node.
+     *
+     * @param store - The typed network to traverse.
+     * @param seedIds - Initial seed fact IDs (activated at 1.0).
+     * @param options - maxDepth + activationThreshold.
+     */
+    spread(store, seedIds, options) {
+        const threshold = options.activationThreshold ?? 0.05;
+        const activations = new Map();
+        for (const id of seedIds)
+            activations.set(id, 1.0);
+        let frontier = new Set(seedIds);
+        for (let depth = 0; depth < options.maxDepth; depth++) {
+            const nextFrontier = new Set();
+            let updated = false;
+            for (const factId of frontier) {
+                const currentAct = activations.get(factId);
+                if (currentAct === undefined)
+                    continue;
+                for (const edge of store.getEdges(factId)) {
+                    const candidate = currentAct * edge.weight * this.decay * this.μ[edge.kind];
+                    if (candidate < threshold)
+                        continue;
+                    // Eq. 12: max-aggregate over incoming edges.
+                    const existing = activations.get(edge.toFactId) ?? 0;
+                    if (candidate > existing) {
+                        activations.set(edge.toFactId, candidate);
+                        nextFrontier.add(edge.toFactId);
+                        updated = true;
+                    }
+                }
+            }
+            if (!updated)
+                break;
+            frontier = nextFrontier;
+        }
+        return activations;
+    }
+}
+//# sourceMappingURL=TypedSpreadingActivation.js.map

package/dist/memory/retrieval/typed-network/TypedSpreadingActivation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TypedSpreadingActivation.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/TypedSpreadingActivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAA6B;IAChE,MAAM,EAAE,GAAG;IACX,MAAM,EAAE,GAAG;IACX,QAAQ,EAAE,GAAG;IACb,QAAQ,EAAE,GAAG;CACd,CAAC;AAsBF;;;;GAIG;AACH,MAAM,OAAO,wBAAwB;IAInC,YAAY,OAAwC;QAClD,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,eAAe,IAAI,wBAAwB,CAAC;IAC/D,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CACJ,KAAwB,EACxB,OAAiB,EACjB,OAAsB;QAEtB,MAAM,SAAS,GAAG,OAAO,CAAC,mBAAmB,IAAI,IAAI,CAAC;QACtD,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;QAC9C,KAAK,MAAM,EAAE,IAAI,OAAO;YAAE,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QAEnD,IAAI,QAAQ,GAAG,IAAI,GAAG,CAAS,OAAO,CAAC,CAAC;QACxC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC;YACtD,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;YACvC,IAAI,OAAO,GAAG,KAAK,CAAC;YAEpB,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;gBAC9B,MAAM,UAAU,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBAC3C,IAAI,UAAU,KAAK,SAAS;oBAAE,SAAS;gBAEvC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC1C,MAAM,SAAS,GACb,UAAU,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBAC5D,IAAI,SAAS,GAAG,SAAS;wBAAE,SAAS;oBACpC,6CAA6C;oBAC7C,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;oBACrD,IAAI,SAAS,GAAG,QAAQ,EAAE,CAAC;wBACzB,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;wBAC1C,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;wBAChC,OAAO,GAAG,IAAI,CAAC;oBACjB,CAAC;gBACH,CAAC;YACH,CAAC;YAED,IAAI,CAAC,OAAO;gBAAE,MAAM;YACpB,QAAQ,GAAG,YAAY,CAAC;QAC1B,CAAC;QAED,OAAO,WAAW,CAAC;IACrB,CAAC;CACF"}

package/dist/memory/retrieval/typed-network/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @file index.ts
+ * @description Barrel exports for the Hindsight 4-network typed
+ * observer module. The new agentos primitive for typed graph
+ * traversal at retrieval time. Imported by the bench wiring and by
+ * any consumer building a Hindsight-style memory pipeline.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network
+ */
+export { BANK_IDS, EDGE_KINDS, isBankId, type BankId, type EdgeKind, type TypedFact, type TypedEdge, type FactTemporal, type Participant, } from './types.js';
+export { TypedNetworkStore } from './TypedNetworkStore.js';
+export { rankByTemporalOverlap } from './TemporalIntervalOverlap.js';
+export { TypedNetworkObserver, type ITypedExtractionLLM, type TypedNetworkObserverOptions, } from './TypedNetworkObserver.js';
+export { TYPED_EXTRACTION_SYSTEM_PROMPT, buildExtractionUserPrompt, } from './prompts/extraction-prompt.js';
+export { TypedExtractionSchema, TypedExtractionFactSchema, type TypedExtractionOutput, type TypedExtractionFact, } from './prompts/extraction-schema.js';
+export { TypedSpreadingActivation, DEFAULT_EDGE_MULTIPLIERS, type TypedSpreadingActivationOptions, type SpreadOptions, } from './TypedSpreadingActivation.js';
+export { fourWayRrf, type FourWayRrfInput, type FourWayRrfOptions, } from './FourWayRrf.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/retrieval/typed-network/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EACL,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,GACjC,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,GACzB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,+BAA+B,EACpC,KAAK,aAAa,GACnB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC"}

package/dist/memory/retrieval/typed-network/index.js

@@ -0,0 +1,18 @@
+/**
+ * @file index.ts
+ * @description Barrel exports for the Hindsight 4-network typed
+ * observer module. The new agentos primitive for typed graph
+ * traversal at retrieval time. Imported by the bench wiring and by
+ * any consumer building a Hindsight-style memory pipeline.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network
+ */
+export { BANK_IDS, EDGE_KINDS, isBankId, } from './types.js';
+export { TypedNetworkStore } from './TypedNetworkStore.js';
+export { rankByTemporalOverlap } from './TemporalIntervalOverlap.js';
+export { TypedNetworkObserver, } from './TypedNetworkObserver.js';
+export { TYPED_EXTRACTION_SYSTEM_PROMPT, buildExtractionUserPrompt, } from './prompts/extraction-prompt.js';
+export { TypedExtractionSchema, TypedExtractionFactSchema, } from './prompts/extraction-schema.js';
+export { TypedSpreadingActivation, DEFAULT_EDGE_MULTIPLIERS, } from './TypedSpreadingActivation.js';
+export { fourWayRrf, } from './FourWayRrf.js';
+//# sourceMappingURL=index.js.map

package/dist/memory/retrieval/typed-network/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,QAAQ,EACR,UAAU,EACV,QAAQ,GAOT,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EACL,oBAAoB,GAGrB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,qBAAqB,EACrB,yBAAyB,GAG1B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,wBAAwB,EACxB,wBAAwB,GAGzB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACL,UAAU,GAGX,MAAM,iBAAiB,CAAC"}

package/dist/memory/retrieval/typed-network/prompts/extraction-prompt.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file extraction-prompt.ts
+ * @description The 6-step extraction prompt for the Hindsight 4-network
+ * typed observer. The system prompt defines the six decomposition
+ * steps verbatim from Hindsight §2.3 (coreference resolution, temporal
+ * normalization, participant attribution, reasoning preservation, fact
+ * type classification, entity extraction). The user prompt frames the
+ * conversation as a single block and asks the model to emit structured
+ * JSON conforming to {@link TypedExtractionSchema}.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/prompts/extraction-prompt
+ */
+/**
+ * System prompt for the 6-step extraction. Verbatim from Hindsight
+ * §2.3 with one omission: the spec doesn't include the "do not
+ * commentate" line, but the LLM tends to drift into prose without it,
+ * which breaks JSON parsing. Included.
+ */
+export declare const TYPED_EXTRACTION_SYSTEM_PROMPT = "You are an information extractor for a typed memory network. Process the conversation below into structured facts.\n\nFor each fact, perform these six steps:\n\n1. COREFERENCE: resolve \"he/she/they/it/this/that\" to the actual referent.\n2. TEMPORAL: normalize times to ISO 8601. Extract ranges as (start, end) when applicable.\n3. PARTICIPANTS: list every named participant and their role.\n4. REASONING: preserve any explicit reasoning marker (because, since, therefore, etc.) verbatim.\n5. FACT TYPE: classify into ONE of:\n   - WORLD: objective facts about the external world\n   - EXPERIENCE: biographical / first-person events\n   - OPINION: claims with confidence < 1.0\n   - OBSERVATION: preference-neutral summaries of entities\n6. ENTITIES: list every named entity (proper nouns, organizations, places, products).\n\nOutput JSON matching the schema strictly. Do not add commentary.";
+/**
+ * Build the user prompt for a single conversation block. Wraps the
+ * source text in delimiters that resist accidental inline-injection
+ * if the conversation contains JSON-looking content.
+ *
+ * @param sessionText - The conversation text to extract from. Whole
+ *   session passed as one block; the model decomposes per turn
+ *   internally.
+ */
+export declare function buildExtractionUserPrompt(sessionText: string): string;
+//# sourceMappingURL=extraction-prompt.d.ts.map

package/dist/memory/retrieval/typed-network/prompts/extraction-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extraction-prompt.d.ts","sourceRoot":"","sources":["../../../../../src/memory/retrieval/typed-network/prompts/extraction-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,i4BAesB,CAAC;AAElE;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAErE"}

package/dist/memory/retrieval/typed-network/prompts/extraction-prompt.js

@@ -0,0 +1,47 @@
+/**
+ * @file extraction-prompt.ts
+ * @description The 6-step extraction prompt for the Hindsight 4-network
+ * typed observer. The system prompt defines the six decomposition
+ * steps verbatim from Hindsight §2.3 (coreference resolution, temporal
+ * normalization, participant attribution, reasoning preservation, fact
+ * type classification, entity extraction). The user prompt frames the
+ * conversation as a single block and asks the model to emit structured
+ * JSON conforming to {@link TypedExtractionSchema}.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/prompts/extraction-prompt
+ */
+/**
+ * System prompt for the 6-step extraction. Verbatim from Hindsight
+ * §2.3 with one omission: the spec doesn't include the "do not
+ * commentate" line, but the LLM tends to drift into prose without it,
+ * which breaks JSON parsing. Included.
+ */
+export const TYPED_EXTRACTION_SYSTEM_PROMPT = `You are an information extractor for a typed memory network. Process the conversation below into structured facts.
+
+For each fact, perform these six steps:
+
+1. COREFERENCE: resolve "he/she/they/it/this/that" to the actual referent.
+2. TEMPORAL: normalize times to ISO 8601. Extract ranges as (start, end) when applicable.
+3. PARTICIPANTS: list every named participant and their role.
+4. REASONING: preserve any explicit reasoning marker (because, since, therefore, etc.) verbatim.
+5. FACT TYPE: classify into ONE of:
+   - WORLD: objective facts about the external world
+   - EXPERIENCE: biographical / first-person events
+   - OPINION: claims with confidence < 1.0
+   - OBSERVATION: preference-neutral summaries of entities
+6. ENTITIES: list every named entity (proper nouns, organizations, places, products).
+
+Output JSON matching the schema strictly. Do not add commentary.`;
+/**
+ * Build the user prompt for a single conversation block. Wraps the
+ * source text in delimiters that resist accidental inline-injection
+ * if the conversation contains JSON-looking content.
+ *
+ * @param sessionText - The conversation text to extract from. Whole
+ *   session passed as one block; the model decomposes per turn
+ *   internally.
+ */
+export function buildExtractionUserPrompt(sessionText) {
+    return `CONVERSATION:\n<<<\n${sessionText}\n>>>`;
+}
+//# sourceMappingURL=extraction-prompt.js.map

package/dist/memory/retrieval/typed-network/prompts/extraction-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extraction-prompt.js","sourceRoot":"","sources":["../../../../../src/memory/retrieval/typed-network/prompts/extraction-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;;;;;;;;;;;;;;;iEAemB,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CAAC,WAAmB;IAC3D,OAAO,uBAAuB,WAAW,OAAO,CAAC;AACnD,CAAC"}

package/dist/memory/retrieval/typed-network/prompts/extraction-schema.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @file extraction-schema.ts
+ * @description Zod schema for parsing the LLM's structured-output
+ * response in the typed-network extraction pipeline. Mirrors
+ * {@link TypedFact} fields but uses snake_case for the LLM API
+ * boundary (LLMs tend to emit snake_case more reliably than
+ * camelCase). The {@link TypedNetworkObserver} translates from this
+ * schema's snake_case shape to the camelCase TypedFact at construction
+ * time.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/prompts/extraction-schema
+ */
+import { z } from 'zod';
+/**
+ * Schema for one extracted fact, matching the LLM's expected output.
+ * `confidence` defaults to 1.0 when missing — the schema permits
+ * omission for non-Opinion facts where the value is structurally 1.0.
+ */
+export declare const TypedExtractionFactSchema: z.ZodObject<{
+    text: z.ZodString;
+    bank: z.ZodEnum<{
+        WORLD: "WORLD";
+        EXPERIENCE: "EXPERIENCE";
+        OPINION: "OPINION";
+        OBSERVATION: "OBSERVATION";
+    }>;
+    temporal: z.ZodObject<{
+        start: z.ZodOptional<z.ZodString>;
+        end: z.ZodOptional<z.ZodString>;
+        mention: z.ZodString;
+    }, z.core.$strip>;
+    participants: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        role: z.ZodString;
+    }, z.core.$strip>>;
+    reasoning_markers: z.ZodArray<z.ZodString>;
+    entities: z.ZodArray<z.ZodString>;
+    confidence: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Top-level schema. Wraps the fact array under a `facts` key so the
+ * LLM has a stable structural anchor to emit against.
+ */
+export declare const TypedExtractionSchema: z.ZodObject<{
+    facts: z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        bank: z.ZodEnum<{
+            WORLD: "WORLD";
+            EXPERIENCE: "EXPERIENCE";
+            OPINION: "OPINION";
+            OBSERVATION: "OBSERVATION";
+        }>;
+        temporal: z.ZodObject<{
+            start: z.ZodOptional<z.ZodString>;
+            end: z.ZodOptional<z.ZodString>;
+            mention: z.ZodString;
+        }, z.core.$strip>;
+        participants: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            role: z.ZodString;
+        }, z.core.$strip>>;
+        reasoning_markers: z.ZodArray<z.ZodString>;
+        entities: z.ZodArray<z.ZodString>;
+        confidence: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** TypeScript type inferred from {@link TypedExtractionSchema}. */
+export type TypedExtractionOutput = z.infer<typeof TypedExtractionSchema>;
+/** Per-fact type inferred from {@link TypedExtractionFactSchema}. */
+export type TypedExtractionFact = z.infer<typeof TypedExtractionFactSchema>;
+//# sourceMappingURL=extraction-schema.d.ts.map

package/dist/memory/retrieval/typed-network/prompts/extraction-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extraction-schema.d.ts","sourceRoot":"","sources":["../../../../../src/memory/retrieval/typed-network/prompts/extraction-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;iBAcpC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;iBAEhC,CAAC;AAEH,mEAAmE;AACnE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAC1E,qEAAqE;AACrE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/memory/retrieval/typed-network/prompts/extraction-schema.js

@@ -0,0 +1,39 @@
+/**
+ * @file extraction-schema.ts
+ * @description Zod schema for parsing the LLM's structured-output
+ * response in the typed-network extraction pipeline. Mirrors
+ * {@link TypedFact} fields but uses snake_case for the LLM API
+ * boundary (LLMs tend to emit snake_case more reliably than
+ * camelCase). The {@link TypedNetworkObserver} translates from this
+ * schema's snake_case shape to the camelCase TypedFact at construction
+ * time.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/prompts/extraction-schema
+ */
+import { z } from 'zod';
+/**
+ * Schema for one extracted fact, matching the LLM's expected output.
+ * `confidence` defaults to 1.0 when missing — the schema permits
+ * omission for non-Opinion facts where the value is structurally 1.0.
+ */
+export const TypedExtractionFactSchema = z.object({
+    text: z.string().min(1),
+    bank: z.enum(['WORLD', 'EXPERIENCE', 'OPINION', 'OBSERVATION']),
+    temporal: z.object({
+        start: z.string().optional(),
+        end: z.string().optional(),
+        mention: z.string(),
+    }),
+    participants: z.array(z.object({ name: z.string(), role: z.string() })),
+    reasoning_markers: z.array(z.string()),
+    entities: z.array(z.string()),
+    confidence: z.number().min(0).max(1).default(1.0),
+});
+/**
+ * Top-level schema. Wraps the fact array under a `facts` key so the
+ * LLM has a stable structural anchor to emit against.
+ */
+export const TypedExtractionSchema = z.object({
+    facts: z.array(TypedExtractionFactSchema),
+});
+//# sourceMappingURL=extraction-schema.js.map

package/dist/memory/retrieval/typed-network/prompts/extraction-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extraction-schema.js","sourceRoot":"","sources":["../../../../../src/memory/retrieval/typed-network/prompts/extraction-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC;IAC/D,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC;QACjB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC5B,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC1B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;KACpB,CAAC;IACF,YAAY,EAAE,CAAC,CAAC,KAAK,CACnB,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CACjD;IACD,iBAAiB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACtC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC7B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;CAClD,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,yBAAyB,CAAC;CAC1C,CAAC,CAAC"}

package/dist/memory/retrieval/typed-network/types.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @file types.ts
+ * @description Core types for the Hindsight 4-network typed observer.
+ * Each fact lives in one of four typed banks: World (objective external
+ * facts), Experience (first-person biographical), Opinion (claims with
+ * confidence < 1), Observation (preference-neutral entity summaries).
+ *
+ * The schema follows Hindsight paper Equation 1
+ * (arxiv.org/html/2512.12818v1 §2.1):
+ *
+ *   f = (u, b, t, v, τs, τe, τm, ℓ, c, x)
+ *
+ * mapped to TypeScript field names below. See spec
+ * `packages/agentos-bench/docs/specs/2026-04-26-hindsight-4network-observer-design.md`
+ * §2.1-§2.2 for the verbatim definition.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/types
+ */
+/**
+ * Bank identifier — one of four typed networks per Hindsight §2.2. The
+ * bank determines retrieval semantics: World facts compose under
+ * objective truth, Experience under first-person continuity, Opinion
+ * under belief evolution, Observation under entity descriptions.
+ */
+export declare const BANK_IDS: readonly ["WORLD", "EXPERIENCE", "OPINION", "OBSERVATION"];
+/** {@link BANK_IDS} as a TypeScript literal type. */
+export type BankId = (typeof BANK_IDS)[number];
+/**
+ * Type guard: narrows an arbitrary string to {@link BankId}. Use to
+ * validate untrusted inputs (LLM extraction output, deserialized
+ * persistence) before routing into the typed network.
+ */
+export declare function isBankId(s: string): s is BankId;
+/**
+ * Edge kind in the typed-network graph. Each kind carries a different
+ * spreading-activation multiplier μ(ℓ) per Hindsight Eq. 12 (§2.4.1).
+ *
+ * - **temporal**: connects facts that share an occurrence-interval
+ *   overlap. Weight derived from `exp(−Δt / σt)`.
+ * - **semantic**: connects facts whose embeddings exceed a cosine
+ *   threshold θs.
+ * - **entity**: bidirectional link between facts mentioning the same
+ *   named entity. Weight 1.0.
+ * - **causal**: explicit reasoning marker linking premise → conclusion
+ *   facts. LLM-extracted at observation time; weight 1.0.
+ */
+export declare const EDGE_KINDS: readonly ["temporal", "semantic", "entity", "causal"];
+/** {@link EDGE_KINDS} as a TypeScript literal type. */
+export type EdgeKind = (typeof EDGE_KINDS)[number];
+/**
+ * Single named participant in a fact (e.g. "Alice", "the deployment
+ * server"). Roles match the participant's grammatical / conversational
+ * function — speaker, addressee, subject, object, etc.
+ */
+export interface Participant {
+    /** Resolved name (after coreference). */
+    name: string;
+    /** Conversational or semantic role. */
+    role: string;
+}
+/**
+ * Temporal envelope per Hindsight Eq. 1 fields τs, τe, τm. ISO 8601
+ * strings; missing `start` / `end` indicates an instant rather than an
+ * interval. `mention` is always populated — it's the timestamp at
+ * which the fact was authored.
+ */
+export interface FactTemporal {
+    /** Interval start (inclusive). ISO 8601. Optional for instant facts. */
+    start?: string;
+    /** Interval end (inclusive). ISO 8601. Optional for instant facts. */
+    end?: string;
+    /** Mention timestamp — when the fact was first authored. ISO 8601. */
+    mention: string;
+}
+/**
+ * A typed fact in the Hindsight memory schema. Carries narrative text,
+ * embedding, temporal envelope, participants, reasoning markers,
+ * extracted entities, and a confidence score in [0, 1]. Confidence
+ * defaults to 1.0 for World/Experience/Observation facts; the Opinion
+ * bank stores `(text, confidence, timestamp)` tuples per §2.2.
+ */
+export interface TypedFact {
+    /** Stable unique identifier. Convention: `<sessionId>-fact-<index>`. */
+    id: string;
+    /** Bank assignment from the LLM extractor's fact-type classification. */
+    bank: BankId;
+    /** Narrative text of the fact, post-coreference resolution. */
+    text: string;
+    /** Embedding vector. Empty until {@link IEmbeddingManager.embed} populates. */
+    embedding: number[];
+    /** Temporal envelope (occurrence interval + mention timestamp). */
+    temporal: FactTemporal;
+    /** Named participants and their roles. */
+    participants: Participant[];
+    /**
+     * Verbatim reasoning markers preserved from the source content
+     * ("because", "since", "therefore", etc.). Used downstream to
+     * extract causal edges.
+     */
+    reasoningMarkers: string[];
+    /** Named entities mentioned in the fact (proper nouns, products, places). */
+    entities: string[];
+    /** Confidence ∈ [0, 1]. 1.0 for non-Opinion facts; LLM-output for Opinion. */
+    confidence: number;
+    /** Optional auxiliary metadata (source ID, conversation turn index, etc.). */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Typed edge between two facts in the network graph. Direction matters
+ * for causal edges (premise → conclusion); other kinds are
+ * bidirectional and stored as a pair of edges.
+ */
+export interface TypedEdge {
+    /** Source fact ID. */
+    fromFactId: string;
+    /** Target fact ID. */
+    toFactId: string;
+    /** Edge kind — drives μ(ℓ) multiplier in spreading activation. */
+    kind: EdgeKind;
+    /** Edge weight. Composed with decay δ and μ(ℓ) at activation time. */
+    weight: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/memory/retrieval/typed-network/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,4DAA6D,CAAC;AAEnF,qDAAqD;AACrD,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/C;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,MAAM,CAE/C;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,uDAAwD,CAAC;AAChF,uDAAuD;AACvD,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,mEAAmE;IACnE,QAAQ,EAAE,YAAY,CAAC;IACvB,0CAA0C;IAC1C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,sBAAsB;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,IAAI,EAAE,QAAQ,CAAC;IACf,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/memory/retrieval/typed-network/types.js

@@ -0,0 +1,48 @@
+/**
+ * @file types.ts
+ * @description Core types for the Hindsight 4-network typed observer.
+ * Each fact lives in one of four typed banks: World (objective external
+ * facts), Experience (first-person biographical), Opinion (claims with
+ * confidence < 1), Observation (preference-neutral entity summaries).
+ *
+ * The schema follows Hindsight paper Equation 1
+ * (arxiv.org/html/2512.12818v1 §2.1):
+ *
+ *   f = (u, b, t, v, τs, τe, τm, ℓ, c, x)
+ *
+ * mapped to TypeScript field names below. See spec
+ * `packages/agentos-bench/docs/specs/2026-04-26-hindsight-4network-observer-design.md`
+ * §2.1-§2.2 for the verbatim definition.
+ *
+ * @module @framers/agentos/memory/retrieval/typed-network/types
+ */
+/**
+ * Bank identifier — one of four typed networks per Hindsight §2.2. The
+ * bank determines retrieval semantics: World facts compose under
+ * objective truth, Experience under first-person continuity, Opinion
+ * under belief evolution, Observation under entity descriptions.
+ */
+export const BANK_IDS = ['WORLD', 'EXPERIENCE', 'OPINION', 'OBSERVATION'];
+/**
+ * Type guard: narrows an arbitrary string to {@link BankId}. Use to
+ * validate untrusted inputs (LLM extraction output, deserialized
+ * persistence) before routing into the typed network.
+ */
+export function isBankId(s) {
+    return BANK_IDS.includes(s);
+}
+/**
+ * Edge kind in the typed-network graph. Each kind carries a different
+ * spreading-activation multiplier μ(ℓ) per Hindsight Eq. 12 (§2.4.1).
+ *
+ * - **temporal**: connects facts that share an occurrence-interval
+ *   overlap. Weight derived from `exp(−Δt / σt)`.
+ * - **semantic**: connects facts whose embeddings exceed a cosine
+ *   threshold θs.
+ * - **entity**: bidirectional link between facts mentioning the same
+ *   named entity. Weight 1.0.
+ * - **causal**: explicit reasoning marker linking premise → conclusion
+ *   facts. LLM-extracted at observation time; weight 1.0.
+ */
+export const EDGE_KINDS = ['temporal', 'semantic', 'entity', 'causal'];
+//# sourceMappingURL=types.js.map

package/dist/memory/retrieval/typed-network/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/memory/retrieval/typed-network/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,aAAa,CAAU,CAAC;AAKnF;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,CAAS;IAChC,OAAQ,QAA8B,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/agentos",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Modular AgentOS orchestration library",
   "type": "module",
   "main": "dist/index.js",