@remnic/core 1.1.0 → 1.1.1

package/dist/graph-retrieval.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Graph-based retrieval types (issue #559, PR 1 of 5).
+ *
+ * This module defines the forward-looking type contract for Remnic's
+ * first-class retrieval graph (GAAMA / GAM inspired). It ships types
+ * and a no-op `queryGraph()` stub only — no behavior, no I/O, and
+ * no importers inside the codebase yet.
+ *
+ * Subsequent slices will land:
+ *   - PR 2: Edge extraction from existing relationship facts + cross-memory
+ *           entity references during indexing (writes `~/.remnic/graph.json`).
+ *   - PR 3: Pure `personalizedPageRank()` implementation.
+ *   - PR 4: Feature-flagged wiring into `retrieval.ts` behind
+ *           `graphRetrievalEnabled` (default `false`).
+ *   - PR 5: LoCoMo A/B bench harness + default flip decision.
+ *
+ * Keeping the node/edge type enums complete from PR 1 avoids type churn
+ * when later slices add reflection/concept node synthesis or additional
+ * edge semantics.
+ */
+/**
+ * Kinds of nodes the retrieval graph can hold.
+ *
+ * - `memory`:     a stored memory file (the primary retrieval target).
+ * - `entity`:     a named entity referenced by one or more memories.
+ * - `episode`:    a temporally-bounded interaction or session grouping.
+ * - `concept`:    an abstract topic / idea (forward-looking; synthesis
+ *                 is out of scope for this issue, but the type is
+ *                 defined here to keep later slices additive).
+ * - `reflection`: an LLM-generated summary / meta-memory about other
+ *                 nodes (also forward-looking, same rationale).
+ */
+type NodeType = "memory" | "entity" | "episode" | "concept" | "reflection";
+/**
+ * Kinds of edges the retrieval graph can hold.
+ *
+ * Edges are directed. `from` → `to` semantics:
+ *
+ * - `references`:    `from` contains an explicit reference to `to`
+ *                    (e.g., a memory referencing another memory).
+ * - `supersedes`:    `from` supersedes `to` (newer memory replaces older).
+ * - `authored-by`:   `from` was authored by the entity in `to`.
+ * - `mentions`:      `from` mentions the entity/concept in `to` without
+ *                    a stronger relationship claim.
+ * - `derived-from`:  `from` was derived from `to` (reflections,
+ *                    consolidations, summaries).
+ * - `temporal-next`: `from` immediately follows `to` in time (episodes).
+ * - `related-to`:    generic weak relationship fallback for edges that
+ *                    do not fit a stronger type.
+ */
+type EdgeType = "references" | "supersedes" | "authored-by" | "mentions" | "derived-from" | "temporal-next" | "related-to";
+/**
+ * A single node in the retrieval graph.
+ *
+ * `id` is the caller-controlled stable identifier (typically a memory
+ * file path, entity slug, or episode id). `weight` is an optional prior
+ * importance score used as a starting bias during Personalized PageRank;
+ * it is intentionally optional because most nodes default to uniform
+ * priors.
+ *
+ * Named `RemnicGraphNode` (not `GraphNode`) to avoid colliding with the
+ * unrelated `GraphEdge` in `graph.ts`, which models Multi-Graph Memory
+ * (MAGMA/SYNAPSE) edges and is an incompatible shape.
+ */
+interface RemnicGraphNode {
+    id: string;
+    type: NodeType;
+    weight?: number;
+}
+/**
+ * A directed edge between two nodes.
+ *
+ * `weight` is optional; when absent PPR implementations should treat
+ * the edge as weight `1`. We keep weight optional rather than defaulting
+ * at construction so producers can serialize a minimal edge shape.
+ *
+ * Named `RemnicGraphEdge` (not `GraphEdge`) to avoid colliding with the
+ * unrelated `GraphEdge` in `graph.ts` (Multi-Graph Memory).
+ */
+interface RemnicGraphEdge {
+    from: string;
+    to: string;
+    type: EdgeType;
+    weight?: number;
+}
+/**
+ * The retrieval graph itself.
+ *
+ * Nodes are held in a `Map<string, RemnicGraphNode>` keyed by `id` so
+ * PPR lookups are O(1). Edges are kept as a flat array; adjacency
+ * indexing is a PR-3 concern (PPR will likely build a transient
+ * outgoing-adjacency map on demand).
+ */
+interface RemnicGraph {
+    nodes: Map<string, RemnicGraphNode>;
+    edges: RemnicGraphEdge[];
+}
+/**
+ * Options for `queryGraph()`.
+ *
+ * Defaults (applied when undefined):
+ *   - `damping`:    0.85 (standard PageRank value — higher values make the
+ *                   random walk follow edges longer before teleporting back
+ *                   to the seed distribution).
+ *   - `iterations`: 20 (power-iteration cap).
+ *   - `tolerance`:  1e-6 (L1 convergence threshold; iteration stops early
+ *                   when the L1 norm of the delta between successive
+ *                   rank vectors falls below this).
+ *   - `topK`:       unbounded — all nodes with positive score are returned,
+ *                   ordered by descending score.
+ */
+interface QueryGraphOptions {
+    /** Number of top-ranked nodes to return. Defaults to unbounded. */
+    topK?: number;
+    /**
+     * PPR damping factor in (0, 1). The probability of following an outgoing
+     * edge at each step (vs. teleporting back to the seed distribution).
+     * Defaults to 0.85.
+     */
+    damping?: number;
+    /** Maximum PPR iterations before falling back to current rank vector. */
+    iterations?: number;
+    /** L1 convergence threshold. Defaults to 1e-6. */
+    tolerance?: number;
+    /**
+     * Optional per-seed weights. Keys must appear in `seedIds` or (if empty)
+     * in the graph. Values must be non-negative. Weights are normalized so
+     * they sum to 1 before seeding. If omitted, seed mass is distributed
+     * uniformly across `seedIds`.
+     */
+    seedWeights?: ReadonlyMap<string, number> | Readonly<Record<string, number>>;
+}
+/**
+ * A scored node returned by `queryGraph()`.
+ */
+interface RankedGraphNode {
+    id: string;
+    score: number;
+}
+/**
+ * The shape returned by `queryGraph()`.
+ */
+interface QueryGraphResult {
+    rankedNodes: RankedGraphNode[];
+    /** Number of power-iteration rounds actually executed. */
+    iterations: number;
+    /** L1 delta at the last iteration. */
+    converged: boolean;
+}
+/** PPR damping factor default. */
+declare const DEFAULT_PPR_DAMPING = 0.85;
+/** Power-iteration cap default. */
+declare const DEFAULT_PPR_ITERATIONS = 20;
+/** L1 convergence threshold default. */
+declare const DEFAULT_PPR_TOLERANCE = 0.000001;
+/**
+ * Personalized PageRank via power iteration.
+ *
+ * Pure function — no I/O. Deterministic given the same graph and options.
+ *
+ * Algorithm:
+ *
+ *   r_{t+1}(v) = (1 - d) * s(v)
+ *              + d * Σ_{u → v} r_t(u) * w(u,v) / Σ_w w(u,·)
+ *              + d * (dangling mass) * s(v)
+ *
+ * where:
+ *   - `d` is the damping factor (default 0.85).
+ *   - `s` is the seed vector (normalized personalization distribution).
+ *   - dangling mass is the total rank on nodes with no outgoing edges,
+ *     redistributed over the seed vector so probability mass is conserved.
+ *
+ * The loop stops early when `|r_{t+1} - r_t|_1 < tolerance` or after
+ * `iterations` rounds, whichever comes first.
+ *
+ * Edge cases:
+ *   - Empty graph → `{ rankedNodes: [], iterations: 0, converged: true }`.
+ *   - Seed ids that are not in the graph are silently dropped.
+ *   - If no in-graph seed mass remains (empty seed or all seeds missing),
+ *     the uniform distribution over graph nodes is used — matching
+ *     standard PageRank semantics.
+ *   - `damping` is clamped to `[0, 1)` (a damping of exactly 1 would make
+ *     the chain non-ergodic; damping of exactly 0 reduces to the seed
+ *     distribution).
+ *   - `topK <= 0` returns an empty ranked list (but the `iterations` and
+ *     `converged` fields still reflect the actual computation).
+ */
+declare function queryGraph(graph: RemnicGraph, seedIds: readonly string[], options?: QueryGraphOptions): QueryGraphResult;
+/** Returns true iff `value` is a valid `NodeType`. */
+declare function isNodeType(value: unknown): value is NodeType;
+/** Returns true iff `value` is a valid `EdgeType`. */
+declare function isEdgeType(value: unknown): value is EdgeType;
+/**
+ * Minimum fields the edge extractor reads from a memory record. Structural
+ * typing is used so callers can pass any subset of `MemoryFrontmatter`
+ * (including richer loaded memories) without a cast.
+ *
+ * All reference fields are optional — memories written before earlier slices
+ * landed will simply contribute no edges for those dimensions.
+ */
+interface MemoryEdgeSource {
+    /** Stable identifier for the memory (typically the file path). */
+    id: string;
+    /** Older memory id this memory supersedes (1:1). */
+    supersedes?: string;
+    /** Parent memory ids this memory was derived from (lineage). */
+    lineage?: string[];
+    /**
+     * Consolidation provenance — `"<memory-id>:<version-number>"` strings.
+     * The memory-id portion before the last `:` is used as the edge target.
+     */
+    derived_from?: string[];
+    /** Primary entity reference on the memory (e.g. `person:Jane Doe`). */
+    entityRef?: string;
+    /** Additional entity references (used by episodes and ledger records). */
+    entityRefs?: string[];
+    /** Raw memory body — scanned for inline `[Source: ...]` citation blocks. */
+    content?: string;
+}
+/** Options controlling edge extraction. */
+interface ExtractGraphEdgesOptions {
+    /**
+     * When true, include edges whose `to` endpoint is not present in the
+     * provided node index. Defaults to `false` — dangling edges are silently
+     * skipped because PPR cannot propagate mass through a missing node.
+     */
+    includeDanglingEdges?: boolean;
+}
+/**
+ * Extract retrieval-graph edges from a collection of memories.
+ *
+ * Pure function — no I/O, no config access, no time-based side effects.
+ * Given the same inputs, always produces the same edges in the same order
+ * so dedup downstream is deterministic.
+ *
+ * Source → target semantics by edge type:
+ *
+ *   - `supersedes`:    memory → older memory (from `supersedes` field).
+ *   - `derived-from`:  memory → each parent in `lineage` OR `derived_from`.
+ *   - `mentions`:      memory → each entity in `entityRef` / `entityRefs`.
+ *   - `authored-by`:   memory → agent id parsed from inline `[Source: ...]`.
+ *
+ * `temporal-next`, `references`, `related-to`, and `concept` / `reflection`
+ * node synthesis are deferred to later slices — they require either episode
+ * sequencing or an abstraction synthesis pass that is out of scope for PR 2.
+ *
+ * @param memories     Memories to scan. Order is preserved; duplicates are
+ *                     not deduped (the caller controls the input set).
+ * @param options      Extraction knobs. See `ExtractGraphEdgesOptions`.
+ * @returns            A `{ nodes, edges }` pair. `nodes` contains one
+ *                     `memory` node per input memory plus one `entity` node
+ *                     per distinct entity discovered across all mentions.
+ *                     Edges reference ids in the returned node map unless
+ *                     `includeDanglingEdges` is set.
+ */
+declare function extractGraphEdges(memories: readonly MemoryEdgeSource[], options?: ExtractGraphEdgesOptions): {
+    nodes: Map<string, RemnicGraphNode>;
+    edges: RemnicGraphEdge[];
+};
+/**
+ * Build a `RemnicGraph` from a collection of memories by delegating to
+ * `extractGraphEdges()`. Convenience wrapper so callers do not have to
+ * re-wrap the `{ nodes, edges }` pair into the `RemnicGraph` interface.
+ *
+ * Pure function — no I/O. Persisting the graph (e.g. writing
+ * `~/.remnic/graph.json`) is left to the caller; that decision belongs with
+ * the maintenance / consolidation pass in PR 4, not the extractor.
+ */
+declare function buildGraphFromMemories(memories: readonly MemoryEdgeSource[], options?: ExtractGraphEdgesOptions): RemnicGraph;
+
+export { DEFAULT_PPR_DAMPING, DEFAULT_PPR_ITERATIONS, DEFAULT_PPR_TOLERANCE, type EdgeType, type ExtractGraphEdgesOptions, type MemoryEdgeSource, type NodeType, type QueryGraphOptions, type QueryGraphResult, type RankedGraphNode, type RemnicGraph, type RemnicGraphEdge, type RemnicGraphNode, buildGraphFromMemories, extractGraphEdges, isEdgeType, isNodeType, queryGraph };

package/dist/graph-retrieval.js

@@ -0,0 +1,21 @@
+import {
+  DEFAULT_PPR_DAMPING,
+  DEFAULT_PPR_ITERATIONS,
+  DEFAULT_PPR_TOLERANCE,
+  buildGraphFromMemories,
+  extractGraphEdges,
+  isEdgeType,
+  isNodeType,
+  queryGraph
+} from "./chunk-64NJRYU2.js";
+export {
+  DEFAULT_PPR_DAMPING,
+  DEFAULT_PPR_ITERATIONS,
+  DEFAULT_PPR_TOLERANCE,
+  buildGraphFromMemories,
+  extractGraphEdges,
+  isEdgeType,
+  isNodeType,
+  queryGraph
+};
+//# sourceMappingURL=graph-retrieval.js.map

package/dist/graph-retrieval.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/importance.js

@@ -3,7 +3,7 @@ import {
   isAboveImportanceThreshold,
   rescoreMemoryImportance,
   scoreImportance
-} from "./chunk-J4IYOZZ5.js";
+} from "./chunk-JXS5PDQ7.js";
 export {
   importanceLevel,
   isAboveImportanceThreshold,