@miller-tech/uap 1.175.13 → 1.178.1

package/dist/memory/reconstruct.d.ts

@@ -0,0 +1,272 @@
+/**
+ * Active memory reconstruction over a Cue–Tag–Content graph
+ * (harness plan area E, 2026-07-31).
+ *
+ * UAP's memory retrieval is passive: embed the query, pull the top-k, reason
+ * once. "Memory is Reconstructed, Not Retrieved" (arXiv 2606.06036) shows that
+ * paradigm is strictly less expressive than letting the model traverse memory
+ * WHILE it reasons — it proves active policies solve a binary-tree
+ * needle-in-a-haystack with zero error where passive policies need an
+ * exponential budget — and measures the practical gap at up to +23% on LoCoMo
+ * with 118k tokens per query against A-Mem's 632k and LangMem's 3.26M.
+ *
+ * THE TAG LAYER IS THE CONTRIBUTION. Their ablation: cue -> content direct
+ * indexing recalls ~65%; cue -> TAG -> content with multi-turn reasoning recalls
+ * ~90%. A "graph memory" that skips the associative tag bridge gets none of the
+ * benefit, so the schema here makes tags mandatory rather than an optimisation.
+ *
+ * Off by default. The literature's numbers are theirs, not ours: this ships
+ * behind `UAP_MEMORY_ACTIVE=1` until `uap bench paired` measures the lift on our
+ * own suite (harness plan constraint 3).
+ */
+/** Which memory layer a content node lives in (MRAgent's three granularities). */
+export type MemoryLayer = 
+/** Event-specific, temporally ordered. */
+'episodic'
+/** Stable facts: preferences, attributes, decisions. */
+ | 'semantic'
+/** Topic nodes summarising recurring patterns — the top-down entry point. */
+ | 'abstraction';
+export interface ContentNode {
+    id: number;
+    layer: MemoryLayer;
+    text: string;
+    /** ISO timestamp of the source episode, when known. */
+    occurredAt?: string;
+}
+/** One (cue, tag, content) triple — the graph's only edge type. */
+export interface Triple {
+    cue: string;
+    tag: string;
+    contentId: number;
+}
+export interface ReconstructionStep {
+    /** 1-based step index. */
+    step: number;
+    /** Cues the model chose to expand this step. */
+    expandedCues: string[];
+    /** Tags reached from those cues. */
+    tags: string[];
+    /** Content ids admitted into the reconstructed context. */
+    kept: number[];
+    /** Content ids reached but judged IRRELEVANT. */
+    pruned: number[];
+    /**
+     * Content ids the policy kept but that did not fit the context budget.
+     * Separate from `pruned`: "judged irrelevant" and "budget full" are different
+     * outcomes and want different remedies.
+     */
+    dropped: number[];
+    /** Whether the model declared the evidence sufficient after this step. */
+    sufficient: boolean;
+}
+export interface ReconstructionResult {
+    /** Content, in the order it was admitted — this is what goes to the model. */
+    context: ContentNode[];
+    steps: ReconstructionStep[];
+    /** True when the loop stopped because evidence sufficed, not because it ran out of steps. */
+    converged: boolean;
+    /** Why the traversal stopped, so callers can give accurate advice. */
+    stopReason: 'sufficient' | 'context-full' | 'exhausted' | 'step-budget';
+}
+/**
+ * The reasoning seam. Injected so the traversal policy is testable without a
+ * model, and so the same graph can be driven by a local or a frontier model.
+ */
+export interface ReconstructionPolicy {
+    /**
+     * Choose which of the currently-active cues to expand next. Returning [] ends
+     * the traversal.
+     */
+    selectCues(query: string, activeCues: string[], context: ContentNode[]): string[];
+    /**
+     * Semantic routing: which reached contents are worth keeping, and is the
+     * accumulated evidence now enough to answer?
+     *
+     * `hops` carries how each candidate was reached. A router that ignores it can
+     * only judge lexical similarity to the query — and then the tag bridge, which
+     * is the whole point of the structure, buys nothing: the traversal reaches the
+     * associated memory and the router throws it away for sharing no words with
+     * the question.
+     */
+    route(query: string, candidates: ContentNode[], context: ContentNode[], hops?: HopContext): RouteDecision;
+}
+export interface RouteDecision {
+    keep: number[];
+    sufficient: boolean;
+    /**
+     * Candidates declined ONLY because a per-step cap was reached, not on the
+     * merits. The traversal keeps these reachable by a later, stronger bridge
+     * instead of blacklisting them like a genuine rejection.
+     */
+    deferred?: number[];
+}
+/** How the traversal reached this step's candidates. */
+export interface HopContext {
+    /** Candidate id -> the tags it was reached through. */
+    tagsFor: Map<number, string[]>;
+    /**
+     * Tags that have produced admitted evidence in ANY prior step — accumulated,
+     * not per-step. A bridge proves itself once; requiring it to re-prove itself
+     * every step is what stops a second hop from ever landing, since by
+     * definition the far side of a bridge does not resemble the query.
+     */
+    productiveTags: ReadonlySet<string>;
+    /**
+     * How many contents each tag links. Specificity is the honest discriminator
+     * for an associative admission: a tag on 3 memories asserts a real relation, a
+     * tag on 300 asserts almost nothing. Lexical overlap cannot serve here — the
+     * far side of a bridge shares no words with the query by construction.
+     */
+    tagSize: (tag: string) => number;
+}
+/**
+ * Zero-LLM policy: lexical overlap for routing, breadth-first for expansion.
+ *
+ * Not a toy — it is the honest default. An active traversal driven by a cheap
+ * heuristic is still active (it prunes on accumulated evidence, which is the
+ * mechanism the paper isolates); wiring an LLM in raises the ceiling but is not
+ * required for the structure to pay off, and a deterministic policy is what
+ * makes the loop unit-testable.
+ */
+export declare function heuristicPolicy(opts?: {
+    keepThreshold?: number;
+    sufficientAt?: number;
+    maxExpandPerStep?: number;
+    /** Max tag-bridged admissions per step. 0 disables associative recall. */
+    maxAssociativePerStep?: number;
+    /**
+     * A tag linking more contents than this is too broad to justify admitting a
+     * candidate that has no lexical relation to the query at all.
+     */
+    maxBridgeTagSize?: number;
+}): ReconstructionPolicy;
+/**
+ * The Cue–Tag–Content graph.
+ *
+ * Its own SQLite file rather than a table in the semantic store: the traversal
+ * is a different access pattern (many small keyed hops, no vector math) and
+ * keeping it separate means enabling the feature cannot slow the existing
+ * retrieval path.
+ */
+export declare class MemoryGraph {
+    private db;
+    constructor(dbPath: string);
+    /**
+     * Add one memory item and its (cue, tag) index entries.
+     *
+     * Tags are REQUIRED: an item indexed by cue alone is the ~65%-recall
+     * configuration the paper ablates away. Callers with no tags should supply a
+     * coarse one (the layer name) rather than none.
+     */
+    addContent(params: {
+        layer: MemoryLayer;
+        text: string;
+        occurredAt?: string;
+        cues: string[];
+        tags: string[];
+    }): number;
+    /** φ_{c→g}: the associative tags a cue activates. */
+    tagsForCue(cue: string): string[];
+    /** φ_{(c,g)→v}: contents reachable from a cue THROUGH a specific tag. */
+    contentsFor(cue: string, tag: string): ContentNode[];
+    /**
+     * Tags too broad to be bridges: attached to >= 60% of all content. Reuses the
+     * discriminativeness rule `stats()` already applies, because a tag that links
+     * everything relates nothing — and on the short-term tier EVERY item is tagged
+     * with one of ~6 type values, so without this the "bridge" is the whole store.
+     */
+    hubTags(): Set<string>;
+    private tagSizeCache;
+    /** How many distinct contents a tag links. Cached — hot in the route loop. */
+    tagSize(tag: string): number;
+    /** Cues that co-occur with a tag — how traversal discovers NEW clues. */
+    cuesForTag(tag: string): string[];
+    /** Source keys already ingested, for incremental rebuilds. */
+    ingestedKeys(): Set<string>;
+    /** Record that a refresh COMPLETED, whether or not it stored anything. */
+    markRefreshed(nowIso: string): void;
+    /** ISO timestamp of the last completed refresh, or null if never refreshed. */
+    lastRefreshedAt(): string | null;
+    /**
+     * Best-effort single-flight guard around a build.
+     *
+     * Two agents retrieving at once both see a stale graph, both build, and both
+     * insert the same items under fresh ids — permanent duplicates, since the
+     * ledger then reports them indexed. Returns false when another build holds the
+     * lock; a lock older than `staleMs` is taken over so a crashed build cannot
+     * wedge refreshes forever.
+     */
+    acquireBuildLock(nowMs: number, staleMs?: number): boolean;
+    releaseBuildLock(): void;
+    /** ISO timestamp of the most recent ingest, or null if never built. */
+    lastIngestedAt(): string | null;
+    /** Mark source keys as ingested. */
+    markIngested(keys: Iterable<string>): void;
+    /**
+     * Cheap emptiness probe. `stats()` runs five aggregates including two
+     * COUNT(DISTINCT) and a GROUP BY — far too expensive for the "should I route
+     * here" check that runs on every single query.
+     */
+    isEmpty(): boolean;
+    /** Delete everything — the truncate half of a real rebuild. */
+    clear(): void;
+    /** Shape of the graph, for `uap memory graph status` and honest reporting. */
+    stats(): {
+        contents: number;
+        cues: number;
+        tags: number;
+        triples: number;
+        bridgingTags: number;
+    };
+    /** Every cue in the graph — the seed set when the query matches nothing. */
+    allCues(): string[];
+    close(): void;
+}
+export interface ReconstructOptions {
+    /** Hard step cap. The paper's runs converge in 3–4; 5 leaves headroom. */
+    maxSteps?: number;
+    policy?: ReconstructionPolicy;
+    /** Seed cues. Omitted -> derived from the query's own tokens. */
+    seedCues?: string[];
+    /**
+     * Hard ceiling on admitted context. `sufficient` only stops FURTHER steps —
+     * everything kept in the current step is already in context — so without this
+     * one step over a well-connected graph can admit thousands of nodes and blow
+     * the token budget this whole approach exists to protect.
+     */
+    maxContext?: number;
+    /** Seed cues to draw when the query matches nothing. Default 32. */
+    maxSeeds?: number;
+    /**
+     * Hard cap on cues expanded per step, enforced HERE rather than trusted to the
+     * policy. The policy seam exists for an LLM to plug into, and an LLM will
+     * happily return 200 cues (or cues that were never active), reproducing the
+     * full-scan this bound was added to prevent.
+     */
+    maxExpandPerStep?: number;
+}
+/**
+ * Reconstruct an answer context by traversing the graph while reasoning.
+ *
+ * The loop is the paper's three-step iteration: select actions over the active
+ * set, traverse (cue -> tags -> contents), then route/prune and update state.
+ * The essential difference from retrieval is that step N+1's expansion depends
+ * on what step N actually found — cues discovered mid-traversal become new
+ * entry points, and weak paths are killed before they consume context.
+ */
+export declare function reconstruct(graph: MemoryGraph, query: string, options?: ReconstructOptions): ReconstructionResult;
+/**
+ * Seed cues = query tokens present in the graph.
+ *
+ * When nothing matches we fall back to a BOUNDED sample rather than every cue
+ * in the graph: an off-topic query would otherwise load the entire content
+ * table on step 1, which is the opposite of what this is for.
+ */
+export declare function seedCuesFromQuery(graph: MemoryGraph, query: string, maxSeeds?: number): string[];
+/**
+ * Is active reconstruction enabled? Off by default — the lift is measured on our
+ * own suite before it becomes the default retrieval path.
+ */
+export declare function activeReconstructionEnabled(): boolean;
+//# sourceMappingURL=reconstruct.d.ts.map

package/dist/memory/reconstruct.d.ts.map

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