@framers/agentos 0.3.0 → 0.3.2

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"}