@avantf/dsh-mem 0.6.4 → 0.8.0

package/lib/dsh-build.json

@@ -1,7 +1,8 @@
 {
-  "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2",
-  "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
-  "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.2",
-  "@deepseek-ai/dsh-typert-registry": "0.2.0-rc.2",
-  "@deepseek-ai/dsh-util-values": "0.2.0-rc.2"
+  "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
+  "@deepseek-ai/dsh-system-prompt": "0.2.1-rc.2",
+  "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
+  "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2",
+  "@deepseek-ai/dsh-typert-registry": "0.2.1-rc.2",
+  "@deepseek-ai/dsh-util-values": "0.2.1-rc.2"
 }

package/lib/engine/graph-recall/in-memory.d.ts

@@ -0,0 +1,93 @@
+/**
+ * A complete {@link GraphReader} over plain arrays, used by this package's golden tests and
+ * available to consumers that need the same fixture (the mem and knowledge adapter contract tests
+ * are expected to run against it as the reference implementation).
+ *
+ * It is intentionally literal: insertion order for reads, exact-match predicate filtering, no
+ * inferred edges, no normalization beyond the alias maps a fixture declares. Anything cleverer
+ * belongs in a real adapter, where it is tested against real storage.
+ *
+ * TWO PROPERTIES A FIXTURE READER MUST HAVE, so tests over it mean something for a real adapter:
+ *
+ *  - **Reads are immutable.** Nodes and edges are copied and `Object.freeze`d when they are
+ *    registered, so a caller mutating a read result (or the node `resolveNode` returned) throws in
+ *    strict mode instead of silently rewriting the graph. The fixtures' own objects are NOT frozen:
+ *    the copy is the reader's, the original stays the caller's.
+ *  - **`resolveNode` is alias-first**, then label, then id — the order memory's adapter uses, so a
+ *    query resolves to the same node here and on a real store.
+ *  - **Re-registering an id keeps the graph consistent.** A new label (or kind) replaces the stored
+ *    node AND every already-indexed edge that names it, so `resolveNode(id)` and an edge's endpoint
+ *    never disagree. Labels are names, not identities: the old label keeps resolving to that id.
+ */
+import type { GraphEdge, GraphNode, GraphReader } from './types.js';
+/** Seed data for an {@link InMemoryGraphReader}. */
+export interface InMemoryGraphReaderOptions {
+    nodes?: readonly GraphNode[];
+    edges?: readonly GraphEdge[];
+    /** `alias → node id` for {@link InMemoryGraphReader.resolveNode}. */
+    nodeAliases?: Readonly<Record<string, string>>;
+    /** `alias → canonical predicate` for {@link InMemoryGraphReader.resolvePredicate}. */
+    predicateAliases?: Readonly<Record<string, string>>;
+}
+/**
+ * In-memory graph with adjacency and fact indexes kept in sync by {@link addEdge}.
+ *
+ * Duplicate edge ids are REJECTED: path dedup is defined on edge ids, so two different edges
+ * sharing one id would make a result ambiguous. Test fixtures must give every edge a unique id.
+ */
+export declare class InMemoryGraphReader implements GraphReader {
+    private readonly nodes;
+    private readonly nodesByLabel;
+    private readonly aliases;
+    private readonly outgoingIndex;
+    private readonly incomingIndex;
+    private readonly factIndex;
+    private readonly edgesById;
+    private readonly edgeIds;
+    private readonly predicates;
+    private readonly predicateAliases;
+    constructor(options?: InMemoryGraphReaderOptions);
+    /**
+     * Register a node (idempotent; the last registration of an id wins) and return the stored copy.
+     *
+     * Labels are names, not identities: two nodes may share one, and this adapter keeps the FIRST
+     * registration for label lookups (a duplicate label is ambiguous; pick once, not per call).
+     * Re-registering an id with a NEW label adds that label and leaves the old one pointing at the
+     * same id, so a name the reader has already answered with never stops resolving.
+     *
+     * When the re-registration CHANGES the node (a new label or kind), every already-indexed edge that
+     * names that id is rewritten to the stored copy as well. Reads hand out edges, so leaving them on
+     * the previous frozen node would make `resolveNode(id)` and `edge.subject` describe two different
+     * nodes for one id.
+     */
+    private registerNode;
+    /** Point every indexed edge that uses `node.id` at the new stored copy. */
+    private rewireIndexedEdges;
+    /** Register a node (idempotent; the last registration of an id wins). */
+    addNode(node: GraphNode): this;
+    /** Register `alias → node id`. The node must exist by the time {@link resolveNode} is called. */
+    addNodeAlias(alias: string, id: string): this;
+    /** Register a canonical predicate so {@link resolvePredicate} recognizes it without an alias. */
+    addPredicate(canonical: string): this;
+    /** Register `alias → canonical predicate` (also registers the canonical name). */
+    addPredicateAlias(alias: string, canonical: string): this;
+    /**
+     * Index one edge. Subject and object nodes are registered automatically (so a fixture only has to
+     * declare its extra nodes/aliases), and the predicate becomes a known canonical name. The edge is
+     * stored as a frozen copy whose endpoints are the reader's nodes.
+     *
+     * @throws when `edge.id` is already present — see the class comment.
+     */
+    addEdge(edge: GraphEdge): this;
+    /**
+     * Resolve a ref ALIAS → LABEL → ID, the order the `GraphReader` contract fixes and memory's
+     * adapter implements. An alias whose target node is missing falls through to the label/id lookups
+     * rather than reporting "unknown", because the ref may still name a node directly.
+     */
+    resolveNode(ref: string): GraphNode | null;
+    resolvePredicate(ref: string): string | null;
+    outgoing(node: GraphNode, predicate?: string, limit?: number): GraphEdge[];
+    incoming(node: GraphNode, predicate?: string, limit?: number): GraphEdge[];
+    /** Every edge of one evidence record, in insertion order, as a fresh array of frozen edges. */
+    edgesForFact(factId: string | number): GraphEdge[];
+}

package/lib/engine/graph-recall/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@avantf/graph-recall` — storage-agnostic relation-graph traversal.
+ *
+ * The package owns the algorithms that memory and knowledge share: one-hop, reverse, two-hop, AND
+ * and neighbour walks over a {@link GraphReader}, returning {@link RelationPath}s that keep their
+ * evidence. It deliberately does NOT own storage, filtering policy, extraction, planning, answer
+ * generation, or anything DSH/Cordis/SQLite-specific — see `docs/GRAPH_RECALL_LIBRARY.md` in the
+ * mem repository for the boundary and its rationale.
+ *
+ * @example
+ * ```ts
+ * import { InMemoryGraphReader, twoHop } from './index.js'
+ *
+ * const reader = new InMemoryGraphReader({ edges })
+ * const { paths, total, truncated } = twoHop(reader, zhang, '管理', '负责')
+ * for (const path of paths) console.log(path.evidence) // fact ids behind the path
+ * ```
+ */
+export type { AndOptions, GraphEdge, GraphNode, GraphQuery, GraphReader, GraphResult, NeighborOptions, PathOptions, RelationPath, } from './types.js';
+export { DEFAULT_LIMIT, MAX_AND_NODES, MAX_LIMIT, andPaths, compareRelationPaths, neighbors, oneHop, query, reverse, twoHop, } from './traverse.js';
+export { InMemoryGraphReader } from './in-memory.js';
+export type { InMemoryGraphReaderOptions } from './in-memory.js';

package/lib/engine/graph-recall/traverse.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The traversal half of `@avantf/graph-recall`: five explicit, bounded operators over a
+ * {@link GraphReader}, plus a thin {@link query} dispatcher.
+ *
+ * Design constraints (docs/GRAPH_RECALL_LIBRARY.md §5), enforced here rather than left to callers:
+ *
+ *  - **Two hops at most.** There is no recursive walk and no depth parameter beyond `1 | 2`.
+ *  - **Every operator is bounded.** Reader calls are over-fetched to `limit × 5` (capped at
+ *    `MAX_SCAN`), so a reader's arbitrary ordering cannot hide a better-ranked path just past the
+ *    page; nothing iterates the whole graph. The multi-read operators cap the total work as well:
+ *    `twoHop` and `andPaths` stop collecting at `MAX_SCAN` candidates, and `andPaths` accepts at
+ *    most {@link MAX_AND_NODES} distinct nodes (it throws above that rather than answering a
+ *    different question). The README's "Bounded work" table lists the cost of every operator.
+ *  - **Paths are deduplicated by edge-id tuple** — one fact reached through two equivalent walks is
+ *    one path.
+ *  - **Ordering is fixed**: confidence DESC, hops ASC, evidence recency DESC, edge ids as the final
+ *    deterministic tiebreak. The same comparator is exported as
+ *    {@link compareRelationPaths} so a consumer merging several operators' pages (Phase 4) sorts
+ *    them the same way.
+ *  - **No path means an empty result**, never a fabricated one; the caller decides whether to fall
+ *    back to fuzzy retrieval.
+ */
+import type { AndOptions, GraphNode, GraphQuery, GraphReader, GraphResult, NeighborOptions, PathOptions, RelationPath } from './types.js';
+/** Default page size of every operator (§5 "每个算子有 limit，默认 10"). */
+export declare const DEFAULT_LIMIT = 10;
+/**
+ * Hard page-size ceiling. A larger `limit` is clamped instead of honored: the package's contract is
+ * bounded work, and a caller asking for everything is asking for an unbounded page.
+ */
+export declare const MAX_LIMIT = 100;
+/**
+ * The most DISTINCT queried nodes `andPaths` accepts.
+ *
+ * Each node costs two reads, so this is the node half of that operator's bound (20 nodes × 2 reads ×
+ * `scan` edges). A longer list THROWS instead of being clamped: silently dropping nodes would turn
+ * "facts mentioning all of these entities" into a different, weaker question — the same reasoning
+ * that makes `query` reject `maxHops: 3`.
+ */
+export declare const MAX_AND_NODES = 20;
+/**
+ * The ordering every operator's page uses, exported so consumers can merge pages consistently:
+ * confidence DESC, hops ASC, evidence recency DESC, then edge ids (deterministic last resort).
+ */
+export declare function compareRelationPaths(a: RelationPath, b: RelationPath): number;
+/**
+ * Edges leaving `start` (optionally filtered by `predicate`), each as a one-hop path in the edge's
+ * stored direction. `includeIncoming` adds edges arriving at `start`; those paths are
+ * `[subject, object]` with `start` as the object.
+ *
+ * @example
+ * ```ts
+ * const { paths } = oneHop(reader, zhang, '管理')
+ * // [{ nodes: [张伟, 李娜], edges: [张伟 管理 李娜], evidence: [101], confidence: 0.9 }]
+ * ```
+ */
+export declare function oneHop(reader: GraphReader, start: GraphNode, predicate?: string, options?: PathOptions): GraphResult;
+/**
+ * Edges arriving at `object` (optionally filtered by `predicate`) — "谁管理李娜". Each path is the
+ * edge in its stored direction (`[subject, object]`), with `object` at the end and the found
+ * subject as the answer node.
+ */
+export declare function reverse(reader: GraphReader, object: GraphNode, predicate?: string, options?: PathOptions): GraphResult;
+/**
+ * Two-hop paths `start -predicate-> mid -secondPredicate-> end` ("张伟管理的人负责什么").
+ * `secondPredicate === undefined` accepts any predicate on the second hop.
+ *
+ * Only the FORWARD direction is walked: a path that returns to `start` is dropped (it is a cycle,
+ * not an answer), and a node reached twice produces one path per distinct edge pair (dedup is by
+ * edge ids, so two facts connecting the same nodes stay two paths with their own evidence).
+ */
+export declare function twoHop(reader: GraphReader, start: GraphNode, predicate?: string, secondPredicate?: string, options?: PathOptions): GraphResult;
+/**
+ * AND semantics: the evidence FACTS that contain at least `minSupport` of the queried nodes
+ * ("一条事实/路径同时包含多个实体"). Incident edges of every queried node are grouped by `factId`
+ * (edges without one form their own group), a group qualifies when at least two distinct queried
+ * nodes appear in it, and each qualifying edge becomes a one-hop path with its `factId` as
+ * evidence. Fewer than two distinct nodes can never satisfy an AND and yields an empty result.
+ *
+ * WHAT THE RETURNED PATHS ARE. Every path is ONE EDGE OF A QUALIFYING FACT — the evidence the fact
+ * was recorded as — **not** a path connecting the queried nodes. A fact naming 张伟, 李娜 and 王芳
+ * contributes all three of its edges, including 李娜 协作 王芳 between two nodes that were not both
+ * queried, and no single path here visits both 张伟 and 李娜 in one walk. A consumer that projects
+ * these paths into an answer (mem's `mode:"relation"`) must present them as "the recorded facts that
+ * mention these entities", never as "the relation between them"; use {@link twoHop} for the latter.
+ *
+ * This is what replaces the old `reason` action: it answers "which recorded facts connect these
+ * entities", not "invent a prose answer about them".
+ *
+ * Bounds: at most {@link MAX_AND_NODES} distinct queried nodes — a longer list throws, because a
+ * clamped AND would answer a different question — two reads per node, and at most `MAX_SCAN`
+ * distinct edges collected across all of them. Reaching that edge ceiling stops the collection,
+ * because more evidence would only be paged away, and reports `truncated: true`.
+ */
+export declare function andPaths(reader: GraphReader, nodes: readonly GraphNode[], options?: AndOptions): GraphResult;
+/**
+ * Distinct neighbours of `node` in both directions (or only outgoing when
+ * `includeIncoming: false`), each represented by its best single-hop path.
+ *
+ * Self-loops are skipped: an edge from `node` to itself makes `node` its own neighbour, which is a
+ * degenerate answer ("what is near 张伟" → 张伟). Memory's extractor rejects self-relations, but a
+ * knowledge adapter may store them, so the filter lives here rather than in one adapter.
+ *
+ * Dedup is by NEIGHBOUR id here, not by edge ids: "who is near this node" is a node question, and
+ * the best evidence for that neighbour (highest confidence, then most recent) is the one returned.
+ */
+export declare function neighbors(reader: GraphReader, node: GraphNode, options?: NeighborOptions): GraphResult;
+/**
+ * Dispatch a {@link GraphQuery} onto the operators above. This is a convenience for callers that
+ * already hold a structured query; it adds no planning and no interpretation.
+ *
+ * `maxHops` defaults to 2 when `secondPredicate` is present, otherwise 1. `includeIncoming` applies
+ * to one-hop only (a two-hop query walks forward). Anything other than 1 or 2 throws — the design
+ * forbids arbitrary depth, and silently clamping a request for 3 hops would hide a caller bug.
+ *
+ * `maxHops: 1` together with `secondPredicate` also throws: a one-hop query has no second hop, so
+ * the field can only be a caller mistake (the old behaviour dropped it silently and answered a
+ * different question than the caller asked).
+ */
+export declare function query(reader: GraphReader, graphQuery: GraphQuery): GraphResult;

package/lib/engine/graph-recall/types.d.ts

@@ -0,0 +1,188 @@
+/**
+ * The storage-agnostic vocabulary of `@avantf/graph-recall`.
+ *
+ * These types are the CONTRACT between the traversal algorithms in `traverse.ts` and whatever
+ * storage a consumer has: memory's `edges` table, knowledge's document/entity graph, or a test
+ * fixture. Nothing in this file (or this package) knows about tables, SQLite, Cordis or DSH — an
+ * adapter maps its rows onto these shapes and owns every filtering decision (active facts, kinds,
+ * sources, time windows, permissions).
+ *
+ * The two invariants that make a result usable as EVIDENCE rather than a string answer:
+ *
+ *  1. every `GraphEdge` can name the record it came from (`factId` / `source`);
+ *  2. every `RelationPath` keeps its edges and their evidence ids, in the same order.
+ */
+/** A graph vertex, identified by an adapter-stable id. */
+export interface GraphNode {
+    /** Adapter-stable identity (memory: `entity_id` as a string; knowledge: doc/entity id). */
+    id: string;
+    /** Human-readable name (memory: `entities.name`; knowledge: the document/entity title). */
+    label: string;
+    /** Optional adapter-defined type (`person`, `org`, `doc`, …). Never interpreted by this library. */
+    kind?: string;
+}
+/**
+ * One directed, predicate-labelled relation between two nodes, as stored.
+ *
+ * `subject -> predicate -> object` is the STORED direction. An adapter that stores inverse
+ * predicates swapped (memory's `direction='inverse'` rule) has already normalized it before the
+ * edge reaches this library; walkers never flip an edge's endpoints.
+ */
+export interface GraphEdge {
+    /** Adapter-stable edge identity (memory: `edge_id` as a string). Used for path dedup. */
+    id: string;
+    subject: GraphNode;
+    /** Canonical predicate (memory: `predicates.canonical_name`). */
+    predicate: string;
+    object: GraphNode;
+    /** Evidence pointer: memory `fact_id`, knowledge chunk/doc id. */
+    factId?: string | number;
+    /**
+     * Producer confidence in `[0, 1]`. Missing means the neutral default `0.5` — the same value
+     * memory's `edges.confidence` column defaults to, so an unannotated edge is not treated as a lie.
+     */
+    confidence?: number;
+    /** Producer of the edge (`heuristic` / `llm` / adapter-defined). Never interpreted here. */
+    source?: string;
+    /**
+     * When the evidence was recorded: an ISO-8601 timestamp or epoch milliseconds. Optional because
+     * the design's `GraphEdge` does not require it; when present it drives the recency tiebreak
+     * (§5 "证据时间 DESC"). An adapter maps `edges.created_at` / `facts.created_at` here.
+     */
+    observedAt?: string | number;
+}
+/**
+ * One walkable path and the evidence behind it.
+ *
+ * Direction invariant: `nodes[i]` is `edges[i].subject` and `nodes[i + 1]` is `edges[i].object`.
+ * A reverse query therefore returns `[subject, object]` (the edge's stored direction), NOT
+ * `[object, subject]` — consumers wanting the "answer node" read `edges[].subject`/`object`.
+ */
+export interface RelationPath {
+    nodes: GraphNode[];
+    /**
+     * The edges walked, in order. The ARRAY is this path's own (concatenating two results cannot
+     * corrupt either), but the EDGE OBJECTS are the adapter's — an adapter must hand out values that
+     * cannot be mutated through a read (see {@link GraphReader}).
+     */
+    edges: GraphEdge[];
+    /**
+     * Product of the edge confidences (an absent confidence counts as `0.5`), rounded to 4 decimals
+     * so `0.9 × 0.8` is exactly `0.72` and test expectations are not float noise.
+     */
+    confidence: number;
+    /**
+     * `factId ?? edge.id` per edge, deduplicated by `String(id)` and order preserved — one id per
+     * piece of evidence, and `7` and `"7"` are the same fact (the same identity `edgesForFact` uses).
+     */
+    evidence: Array<string | number>;
+}
+/**
+ * A structured relation question. This is deliberately a small, explicit shape: the library has no
+ * natural-language planner, and Phase 3a does not add one.
+ */
+export interface GraphQuery {
+    /** Node the walk starts from (already resolved by the caller/adapter). */
+    start: GraphNode;
+    /** Predicate (canonical name or an alias the reader can resolve) for the first hop. */
+    predicate?: string;
+    /**
+     * Predicate for the second hop; its presence implies `maxHops: 2`. Combining it with an explicit
+     * `maxHops: 1` throws: a one-hop query has no second hop, so the field is a caller mistake.
+     */
+    secondPredicate?: string;
+    /** Keep only paths whose far endpoint has this node id. */
+    target?: GraphNode;
+    /** Maximum hops. Only 1 and 2 are supported; defaults to 2 when `secondPredicate` is set, else 1. */
+    maxHops?: 1 | 2;
+    /** Maximum paths to return (default 10, clamped to `[0, MAX_LIMIT]`). */
+    limit?: number;
+    /** One-hop only: also walk edges pointing AT `start`. Ignored by two-hop queries. */
+    includeIncoming?: boolean;
+}
+/** The outcome of one operator: the bounded page plus an honest count and truncation flag. */
+export interface GraphResult {
+    paths: RelationPath[];
+    /**
+     * `total` counts the DISTINCT candidate paths found by the operator's bounded scan — not the
+     * whole graph, and not the page. The scan is over-fetched to `limit × 5` (capped at 500) so a
+     * reader's arbitrary ordering cannot hide better-ranked paths just past `limit`.
+     */
+    total: number;
+    /** `true` when more distinct candidates existed than the page returned. */
+    truncated: boolean;
+}
+/**
+ * What a storage adapter must provide. All methods are read-only and must return results in a
+ * STABLE order (insertion order is fine); the library sorts by confidence/hops/recency itself.
+ *
+ * Filters (active status, kind, source, time window, permissions) belong to the adapter: this
+ * library never guesses them. `resolveNode` / `resolvePredicate` are the adapter's normalization
+ * entry points; walkers use `resolvePredicate` so an alias resolves to the canonical name before
+ * the read, while `resolveNode` is for callers that start from a plain string.
+ *
+ * ADAPTER OBLIGATIONS, in the order the contract suite (`test/contract.ts`) checks them:
+ *
+ *  1. **`resolveNode` is alias-first**: an explicit alias wins over a node id and over a label, so
+ *     `resolveNode('ali')` and a node whose id is `ali` cannot mean different things in two
+ *     adapters. The full order is alias → label/name → node id (memory's `entity_aliases` →
+ *     `entities.name` → numeric `entity_id`). Labels are not unique; an adapter that has to choose
+ *     between two nodes with one label must choose the same one on every call. A ref that matches
+ *     nothing (or only whitespace) resolves to `null`.
+ *  2. **Edge ids are unique.** Path dedup is defined on edge ids, so one id must name one edge; an
+ *     adapter must never hold two edges under one id (the reference adapter rejects the write, and
+ *     the contract only requires that the duplicate is not visible).
+ *  3. **Reads never expose mutable internals.** A caller may mutate (or attempt to mutate) whatever
+ *     a read returned — edges, their endpoint nodes, the node `resolveNode` returned — and the next
+ *     read must return the unchanged graph. `InMemoryGraphReader` freezes its objects; an adapter
+ *     that builds fresh values per read (memory does) satisfies this by construction.
+ *  4. **Every edge can be traced back**: `factId` is the evidence pointer (`facts.fact_id`), and
+ *     `edgesForFact` returns every edge one fact produced, in a stable order.
+ */
+export interface GraphReader {
+    /** Resolve a raw reference (alias, label/name, id — in that order) to a node, else `null`. */
+    resolveNode(ref: string): GraphNode | null;
+    /** Resolve a predicate reference (canonical name or alias) to its canonical name, else `null`. */
+    resolvePredicate(ref: string): string | null;
+    /** Edges leaving `node`, optionally filtered by canonical predicate, at most `limit` of them. */
+    outgoing(node: GraphNode, predicate?: string, limit?: number): GraphEdge[];
+    /** Edges arriving at `node`, optionally filtered by canonical predicate, at most `limit`. */
+    incoming(node: GraphNode, predicate?: string, limit?: number): GraphEdge[];
+    /** Every edge one evidence record (`factId`) produced. */
+    edgesForFact(factId: string | number): GraphEdge[];
+}
+/** Options shared by the single-hop operators ({@link oneHop} / {@link reverse}). */
+export interface PathOptions {
+    /** Maximum paths to return. Default 10; clamped to `[0, MAX_LIMIT]`. */
+    limit?: number;
+    /** Keep only paths whose far endpoint (the node the walk leads to) has this id. */
+    target?: GraphNode;
+    /** `oneHop` only: also walk edges pointing at the start node. */
+    includeIncoming?: boolean;
+}
+/**
+ * Options for {@link andPaths}.
+ *
+ * `andPaths` returns ONE EDGE PER QUALIFYING FACT (the evidence the fact was recorded as), not a
+ * path that joins the queried nodes: a fact naming 张伟, 李娜 and 王芳 contributes all three of its
+ * edges even though some of them connect nodes that were not queried. Use `twoHop` for "the path
+ * between these nodes". At most `MAX_AND_NODES` (20) distinct nodes are accepted; more throws.
+ */
+export interface AndOptions {
+    /** Maximum paths to return. Default 10; clamped to `[0, MAX_LIMIT]`. */
+    limit?: number;
+    /**
+     * How many DISTINCT queried nodes one evidence fact must contain for its edges to count.
+     * Default 2 (the minimum an AND means); values below 2 are raised to 2.
+     */
+    minSupport?: number;
+}
+/** Options for {@link neighbors}. */
+export interface NeighborOptions {
+    /** Maximum distinct neighbors to return. Default 10; clamped to `[0, MAX_LIMIT]`. */
+    limit?: number;
+    /** Canonical predicate (or alias) to restrict the adjacency to. */
+    predicate?: string;
+    /** Walk incoming edges too. Default `true` — "neighbours" means both directions. */
+    includeIncoming?: boolean;
+}

package/lib/engine/mem/config/config_files.d.ts

@@ -15,7 +15,7 @@ import type { AvantfLogger } from '../../mem-contract/index.js';
  * UNCOMMENTED line is warned about by the loader, so a wrong name here would be a trap rather than a
  * hint. `config_files.spec.ts` pins the ones this template names.
  */
-export declare const DEFAULT_COMMON_CONFIG = "# avantf-mem \u516C\u5171\u914D\u7F6E\uFF08\u5206\u5C42\u7B2C\u2461\u5C42\uFF09\u3002\u8FD9\u91CC\u5168\u662F\u6CE8\u91CA\uFF1A\u5220\u6389/\u7559\u7A7A = \u7528\u5185\u5EFA\u9ED8\u8BA4\uFF0C\u53D6\u6D88\u6CE8\u91CA\u5373\u751F\u6548\u3002\n# \u5206\u5C42\uFF08\u4F4E\u2192\u9AD8\uFF09\uFF1A\u2460 \u5185\u5EFA\u9ED8\u8BA4 \u2192 \u2461 \u672C\u6587\u4EF6 \u2192 \u2462 \u540C\u76EE\u5F55\u7684 memory.yaml / knowledge.yaml\uFF08\u7F3A\u5931=\u4E0D\u8986\u76D6\uFF09\n#               \u2192 \u2463 \u73AF\u5883\u53D8\u91CF \u2192 \u2464 \u63D2\u4EF6/CLI \u663E\u5F0F\u4F20\u53C2\n# \u6240\u6709\u53EF\u7F16\u8F91\u6587\u672C\u90FD\u5728 ~/.avantf \u4E0B\uFF1Aconfigs/*.yaml\uFF08\u672C\u76EE\u5F55\uFF09\u4E0E prompts/*.md\uFF08\u6A21\u578B\u63D0\u793A\u8BCD\uFF09\u3002\n\n# \u6570\u636E\u6839\u4E0D\u5728\u8FD9\u91CC\u914D\uFF1A\u5B83\u7531 \u2463 AVANTF_HOME\uFF08\u6216 CLI --data-home\u3001\u63D2\u4EF6 profile \u7684 dataHome\uFF09\u51B3\u5B9A \u2014\u2014\n# \u672C\u6587\u4EF6\u5C31\u5728\u6570\u636E\u6839\u91CC\u9762\uFF0C\u89E3\u6790\u6839\u7684\u65F6\u5019\u8FD8\u6CA1\u8BFB\u5230\u5B83\uFF0C\u6240\u4EE5\u5199\u5728\u8FD9\u91CC\u7684 dataHome \u5BF9\u6570\u636E\u6839\u65E0\u6548\uFF08DESIGN \u00A73\uFF09\u3002\n\n# semantic:                           # \u5D4C\u5165\u540E\u7AEF\uFF08\u8BB0\u5FC6\u4E0E\u77E5\u8BC6\u5171\u7528\uFF0C\u8DE8\u5E93\u5206\u6570\u624D\u53EF\u6BD4\uFF09\n#   backend: local_bge\n#   local_model: Xenova/bge-base-zh-v1.5    # \u5FC5\u987B\u662F ONNX \u4ED3\u5E93\n#   dim: 768\n#   auto_download: true\n#   auto_migrate: true                # \u6362\u6A21\u578B/\u5BBD\u5EA6\u540E\u81EA\u52A8\u5206\u6279\u91CD\u7B97\u65E7\u7A7A\u95F4\u7684\u5411\u91CF\uFF08\u9ED8\u8BA4\u5F00\uFF09\uFF1B\u5173\u6389\u53EA\u5269\u542F\u52A8\u544A\u8B66 + vectors --fix\n#   \u26A0\uFE0F cache_dir / mirror \u7531\u5BB6\u65CF\u5E95\u5EA7 @avantf/dsh-plugin-base \u7BA1\u7406\uFF1A\u5199\u5728\u8FD9\u91CC\u4F1A\u88AB\u5FFD\u7565\u5E76\u544A\u8B66\u3002\n#      \u7F13\u5B58\u76EE\u5F55\u7528\u73AF\u5883\u53D8\u91CF AVANTF_MEM_MODEL_CACHE\uFF0C\u955C\u50CF\u7528 AVANTF_MEM_MODEL_MIRROR\uFF08\u6216 HF_ENDPOINT\uFF09\u3002\n\n# vectorStore:\n#   backend: auto                     # auto = \u8D8A\u8FC7\u9608\u503C\u81EA\u52A8\u4ECE local_numpy \u8FC1\u5230 hnswlib\n#   auto_thresholds:\n#     hnswlib: 2000\n#   hnswlib_ef_search: 256            # ANN \u7684\u53EC\u56DE/\u901F\u5EA6\u65CB\u94AE\uFF0C\u8BED\u6599\u53D8\u5927\u5148\u8C03\u5B83\n\n# retriever:                          # \u4E09\u6761\u68C0\u7D22\u817F\u5728\u878D\u5408\u91CC\u7684\u6743\u91CD\u4E0E\"\u76F8\u5173\u6027\u95E8\u69DB\"\n#   weight_semantic: 0.55\n#   weight_fts: 0.30\n#   weight_jaccard: 0.15\n#   # \u7EDD\u5BF9\u95E8\u69DB\u6253\u5728\u6BCF\u6761\u817F\u7684\u539F\u59CB\u5206\u4E0A\u3001fuse() \u4E4B\u524D\uFF08\u878D\u5408\u5206\u53EA\u5728\u4E00\u6B21\u67E5\u8BE2\u5185\u53EF\u6BD4\uFF0C\u4E0D\u80FD\u5F53\u95E8\u69DB\uFF09\u3002\n#   # 0 = \u5173\u95ED\u8BE5\u95E8\u69DB\uFF1B\u5206\u6570\u7B49\u4E8E\u95E8\u69DB\u4FDD\u7559\u3002\u8BED\u4E49\u540E\u7AEF\u4E0D\u53EF\u7528\u65F6 min_fts_terms \u7684\u751F\u6548\u503C\u653E\u5BBD\u5230 1\u3002\n#   min_semantic_similarity: 0.5      # \u8BED\u4E49\u817F\u4F59\u5F26\uFF1B0.5 \u53EA\u5BF9 bge-base-zh-v1.5/768\uFF08mean pooling\uFF09\u6807\u5B9A\u8FC7\uFF0C\u6362\u6A21\u578B\u8981\u91CD\u6807\n#   min_fts_terms: 2                  # FTS \u817F\uFF1A\u8FD9\u4E00\u884C\u547D\u4E2D\u51E0\u4E2A\u4E0D\u540C\u7684\u67E5\u8BE2\u8BCD\u5143\uFF08\u62C9\u4E01\u8BCD\u22655\u5B57\u7B26 + CJK 3-gram\uFF09\n#   min_jaccard: 0.2                  # \u5B9E\u4F53\u817F\uFF1A\u951A\u70B9\u5B9E\u4F53\u7684 Jaccard\uFF08\u4E8B\u5B9E\u5BBD\u5EA6\u9971\u548C\uFF09\uFF1B2 \u5B9E\u4F53\u547D\u4E2D 1 \u4E2A\u6B63\u597D 0.2\n#   # P-11 \u4E2D\u6587\u65F6\u95F4\u7A97\u817F\uFF08\u9ED8\u8BA4\u5173\uFF09\uFF1A\u5F00\u542F\u540E\uFF0C\u5E26\u4E2D\u6587\u65F6\u95F4\u8868\u8FBE\u7684\u67E5\u8BE2\uFF08\u4E0A\u4E2A\u6708 / \u6700\u8FD1\u4E09\u5929 / 2026\u5E749\u6708 \u2026\uFF09\n#   # \u4F1A\u989D\u5916\u628A\"\u4E8B\u4EF6\u65F6\u95F4 valid_from \u843D\u5728\u8BE5\u7A97\u53E3\"\u7684\u6D3B\u8DC3\u4E8B\u5B9E\u4F5C\u4E3A\u4E00\u6761\u817F\u53C2\u4E0E\u878D\u5408\u3002\u5B83\u662F**\u52A0\u4E00\u6761\u817F\u3001\u4E0D\u662F\u8FC7\u6EE4\u5668**\uFF1A\n#   # \u53EA\u589E\u52A0\u5019\u9009\uFF0C\u7EDD\u4E0D\u5220\u6389\u8BED\u4E49 / FTS / \u5B9E\u4F53\u817F\u5DF2\u7ECF\u627E\u5230\u7684\u4E8B\u5B9E\uFF1B\u6CA1\u6709\u4E8B\u4EF6\u65F6\u95F4\u7684\u4E8B\u5B9E\u4E0D\u4F5C\u4E3A\u8BE5\u817F\u5019\u9009\uFF0C\n#   # \u4E5F**\u4E0D\u56DE\u9000\u5230\u5199\u5165\u65F6\u95F4 created_at**\u3002\u5B83\u5171\u7528 jaccard \u6743\u91CD\u4F4D\uFF08\u5BF9\u5916\u7684\u4E09\u952E\u6743\u91CD\u4E0D\u53D8\uFF09\u3002\n#   # \u4EC0\u4E48\u65F6\u5019\u8BE5\u5F00\uFF1A\u5148\u7528 mem_admin stats \u770B validity.coverage\uFF08\u6709\u591A\u5C11\u6D3B\u8DC3\u4E8B\u5B9E\u5E26\u4E8B\u4EF6\u65F6\u95F4\uFF09\uFF0C\n#   # \u518D\u7528\u56DE\u5F52\u7F51\u786E\u8BA4\u5B83\u786E\u5B9E\u6539\u5584\u65F6\u95F4\u7C7B\u67E5\u8BE2\u2014\u2014\u8986\u76D6\u7387\u22480 \u65F6\u5B83\u7B49\u4E8E\u6CA1\u5F00\u3002\u5199\u5165\u4E8B\u4EF6\u65F6\u95F4\u7528 mem_remember \u7684 event_date\u3002\n#   time_window: false\n\n# lifecycle:\n#   purge_after_archived_days: 365    # \u5F52\u6863\u4E8B\u5B9E\u7684\u7269\u7406\u6E05\u7406\u7A97\u53E3\uFF08\u6D3B\u8DC3\u65E5\uFF09\n#   contradiction_threshold: 0.6\n\n# trust:\n#   decay_per_day: 0.0055\u2026\n#   presence:\n#     heartbeat_minutes: 60           # \u5E38\u9A7B\u8FDB\u7A0B\u7684\u5FC3\u8DF3\uFF08\u6D3B\u8DC3\u65E5\u65F6\u949F\u4E0E\u751F\u547D\u5468\u671F\u626B\u63CF\uFF09\n\n# tools:                              # \u5916\u90E8\u4E8C\u8FDB\u5236\uFF08pandoc\uFF09\u7684\u53D7\u7BA1\u76EE\u5F55\n#   dir: ''                           # \u7559\u7A7A = \u5BB6\u65CF\u6839 tools\uFF08~/.avantf/env/tools\uFF09\uFF1BAVANTF_TOOLS_DIR \u53EF\u8986\u76D6\n#   auto_install: true\n";
+export declare const DEFAULT_COMMON_CONFIG = "# avantf-mem \u516C\u5171\u914D\u7F6E\uFF08\u5206\u5C42\u7B2C\u2461\u5C42\uFF09\u3002\u8FD9\u91CC\u5168\u662F\u6CE8\u91CA\uFF1A\u5220\u6389/\u7559\u7A7A = \u7528\u5185\u5EFA\u9ED8\u8BA4\uFF0C\u53D6\u6D88\u6CE8\u91CA\u5373\u751F\u6548\u3002\n# \u5206\u5C42\uFF08\u4F4E\u2192\u9AD8\uFF09\uFF1A\u2460 \u5185\u5EFA\u9ED8\u8BA4 \u2192 \u2461 \u672C\u6587\u4EF6 \u2192 \u2462 \u540C\u76EE\u5F55\u7684 memory.yaml\uFF08\u7F3A\u5931=\u4E0D\u8986\u76D6\uFF09\n#               \u2192 \u2463 \u73AF\u5883\u53D8\u91CF \u2192 \u2464 \u63D2\u4EF6/CLI \u663E\u5F0F\u4F20\u53C2\n# \u6240\u6709\u53EF\u7F16\u8F91\u6587\u672C\u90FD\u5728 ~/.avantf \u4E0B\uFF1Aconfigs/*.yaml\uFF08\u672C\u76EE\u5F55\uFF09\u4E0E prompts/*.md\uFF08\u6A21\u578B\u63D0\u793A\u8BCD\uFF09\u3002\n\n# \u6570\u636E\u6839\u4E0D\u5728\u8FD9\u91CC\u914D\uFF1A\u5B83\u7531 \u2463 AVANTF_HOME\uFF08\u5BB6\u65CF\u6839\uFF1A\u540C\u65F6\u51B3\u5B9A\u6570\u636E\u6839\u4E0E models/tools\uFF09\u51B3\u5B9A \u2014\u2014\n# \u53EA\u60F3\u6362\u6570\u636E\u6839\u3001\u4E0D\u642C\u6A21\u578B\u7F13\u5B58\u65F6\u7528 CLI \u7684 \u2464 \u663E\u5F0F\u53C2\u6570 avantf-mem --data-home <path>\uFF08\u63D2\u4EF6\u5219\u662F profile \u7684\n# dataHome\uFF0C\u5C5E \u2461\uFF09\u3002\u672C\u6587\u4EF6\u5C31\u5728\u6570\u636E\u6839\u91CC\u9762\uFF0C\u89E3\u6790\u6839\u65F6\u8FD8\u6CA1\u8BFB\u5230\u5B83\uFF0C\u6240\u4EE5\u5199\u5728\u8FD9\u91CC\u7684 dataHome \u5BF9\u6570\u636E\u6839\u65E0\u6548\uFF08DESIGN \u00A73\uFF09\u3002\n\n# semantic:                           # \u5D4C\u5165\u540E\u7AEF\uFF08\u8BB0\u5FC6\u4E0E\u77E5\u8BC6\u5171\u7528\uFF0C\u8DE8\u5E93\u5206\u6570\u624D\u53EF\u6BD4\uFF09\n#   backend: local_bge\n#   local_model: Xenova/bge-base-zh-v1.5    # \u5FC5\u987B\u662F ONNX \u4ED3\u5E93\n#   dim: 768\n#   auto_download: true\n#   auto_migrate: true                # \u6362\u6A21\u578B/\u5BBD\u5EA6\u540E\u81EA\u52A8\u5206\u6279\u91CD\u7B97\u65E7\u7A7A\u95F4\u7684\u5411\u91CF\uFF08\u9ED8\u8BA4\u5F00\uFF09\uFF1B\u5173\u6389\u53EA\u5269\u542F\u52A8\u544A\u8B66 + vectors --fix\n#   \u26A0\uFE0F cache_dir / mirror \u7531\u5BB6\u65CF\u5E95\u5EA7 @avantf/dsh-plugin-base \u7BA1\u7406\uFF1A\u5199\u5728\u8FD9\u91CC\u4F1A\u88AB\u5FFD\u7565\u5E76\u544A\u8B66\u3002\n#      \u7F13\u5B58\u76EE\u5F55\u7528\u73AF\u5883\u53D8\u91CF AVANTF_MEM_MODEL_CACHE\uFF0C\u955C\u50CF\u7528 AVANTF_MEM_MODEL_MIRROR\uFF08\u6216 HF_ENDPOINT\uFF09\u3002\n\n# vectorStore:\n#   backend: auto                     # auto = \u8D8A\u8FC7\u9608\u503C\u81EA\u52A8\u4ECE local_numpy \u8FC1\u5230 hnswlib\n#   auto_thresholds:\n#     hnswlib: 2000\n#   hnswlib_ef_search: 256            # ANN \u7684\u53EC\u56DE/\u901F\u5EA6\u65CB\u94AE\uFF0C\u8BED\u6599\u53D8\u5927\u5148\u8C03\u5B83\n\n# retriever:                          # \u4E09\u6761\u68C0\u7D22\u817F\u5728\u878D\u5408\u91CC\u7684\u6743\u91CD\u4E0E\"\u76F8\u5173\u6027\u95E8\u69DB\"\n#   weight_semantic: 0.55\n#   weight_fts: 0.30\n#   weight_jaccard: 0.15\n#   # \u817F\u95E8\u69DB\u662F\u7EDD\u5BF9\u95E8\u69DB\uFF0C\u6253\u5728\u6BCF\u6761\u817F\u7684\u539F\u59CB\u5206\u4E0A\u3001fuse() \u4E4B\u524D\uFF1B0 = \u5173\u95ED\u8BE5\u95E8\u69DB\uFF0C\u5206\u6570\u7B49\u4E8E\u95E8\u69DB\u4FDD\u7559\u3002\n#   # \u8BED\u4E49\u540E\u7AEF\u4E0D\u53EF\u7528\u65F6 min_fts_terms \u7684\u751F\u6548\u503C\u653E\u5BBD\u5230 1\u3002\n#   min_semantic_similarity: 0.5      # \u8BED\u4E49\u817F\u4F59\u5F26\uFF1B0.5 \u53EA\u5BF9 bge-base-zh-v1.5/768\uFF08mean pooling\uFF09\u6807\u5B9A\u8FC7\uFF0C\u6362\u6A21\u578B\u8981\u91CD\u6807\n#   min_fts_terms: 2                  # FTS \u817F\uFF1A\u8FD9\u4E00\u884C\u547D\u4E2D\u51E0\u4E2A\u4E0D\u540C\u7684\u67E5\u8BE2\u8BCD\u5143\uFF08\u62C9\u4E01\u8BCD\u22655\u5B57\u7B26 + CJK 3-gram\uFF09\n#   min_jaccard: 0.2                  # \u5B9E\u4F53\u817F\uFF1A\u951A\u70B9 Jaccard \u7684**\u4E0B\u754C**\uFF1B\u5B9E\u9645\u8BC1\u636E\u95E8\u69DB\u518D\u6309\u951A\u70B9\u7A00\u6709\u5EA6\u52A0\u6743\uFF08\u00A720.19 \u7EED\uFF09\n#   # min_score \u662F\u552F\u4E00\u7684**\u663E\u793A\u5206**\u95E8\u69DB\uFF0C\u4E5F\u662F UI \u663E\u793A\u7684\u90A3\u4E2A score\uFF1A\u5408\u5E76\u6C60\u6309\u6700\u5927\u878D\u5408\u5206\u5F52\u4E00\u5316\u540E\u7684\u503C\uFF0C\n#   # \u662F**\u76F8\u5BF9\u91CF**\u2014\u2014\u540C\u4E00\u4E8B\u5B9E\u5728\u4E0D\u540C\u67E5\u8BE2\u91CC\u53EF\u80FD\u901A\u8FC7\u3001\u4E5F\u53EF\u80FD\u4E0D\u901A\u8FC7\uFF08\u53D6\u51B3\u4E8E\u540C\u4E00\u67E5\u8BE2\u91CC\u6709\u6CA1\u6709\u66F4\u5F3A\u7684\u5019\u9009\uFF09\u3002\n#   # \u5B83\u53EA\u5E94\u7528\u4E00\u6B21\uFF1A\u5728\u5408\u5E76\u540E\u7684\u5019\u9009\u6C60\u4E0A\u3001\u6309 kind/source \u8FC7\u6EE4\u4E0E slice \u4E4B\u524D\uFF08mem_recall \u4E0E UI\n#   # \u56E0\u6B64\u662F\u540C\u4E00\u4E2A\u523B\u5EA6\uFF09\uFF1B0 = \u5173\u95ED\uFF0C\u5206\u6570\u7B49\u4E8E\u95E8\u69DB\u4FDD\u7559\uFF1B\u653E\u5BBD\u6863\u53EA\u964D\u817F\u95E8\u69DB\uFF0C\u4E0D\u964D\u5B83\u3002\n#   # \u26A0\uFE0F \u88AB\u5B83\u4E22\u5F03\u7684\u6761\u76EE\u4E0D\u8FDB `dropped_by_floor`\uFF0C\u56E0\u6B64 UI \u7684\u300C\u4E25\u683C\u95E8\u69DB\u4E22\u5F03\u4E86 N \u6761\u300D**\u4E0D\u542B**\u8FD9\u4E00\u7C7B\n#   #    \uFF08\u4FE1\u5C01\u91CC\u5355\u72EC\u6709 dropped_by_score\uFF1B\u9762\u677F\u8FD9\u4E00\u7248\u8FD8\u6CA1\u6E32\u67D3\u5B83\uFF09\u3002\n#   min_score: 0.5\n#   # P-11 \u4E2D\u6587\u65F6\u95F4\u7A97\u817F\uFF08\u9ED8\u8BA4\u5173\uFF09\uFF1A\u5F00\u542F\u540E\uFF0C\u5E26\u4E2D\u6587\u65F6\u95F4\u8868\u8FBE\u7684\u67E5\u8BE2\uFF08\u4E0A\u4E2A\u6708 / \u6700\u8FD1\u4E09\u5929 / 2026\u5E749\u6708 \u2026\uFF09\n#   # \u4F1A\u989D\u5916\u628A\"\u4E8B\u4EF6\u65F6\u95F4 valid_from \u843D\u5728\u8BE5\u7A97\u53E3\"\u7684\u6D3B\u8DC3\u4E8B\u5B9E\u4F5C\u4E3A\u4E00\u6761\u817F\u53C2\u4E0E\u878D\u5408\u3002\u5B83\u662F**\u52A0\u4E00\u6761\u817F\u3001\u4E0D\u662F\u8FC7\u6EE4\u5668**\uFF1A\n#   # \u53EA\u589E\u52A0\u5019\u9009\uFF0C\u7EDD\u4E0D\u5220\u6389\u8BED\u4E49 / FTS / \u5B9E\u4F53\u817F\u5DF2\u7ECF\u627E\u5230\u7684\u4E8B\u5B9E\uFF1B\u6CA1\u6709\u4E8B\u4EF6\u65F6\u95F4\u7684\u4E8B\u5B9E\u4E0D\u4F5C\u4E3A\u8BE5\u817F\u5019\u9009\uFF0C\n#   # \u4E5F**\u4E0D\u56DE\u9000\u5230\u5199\u5165\u65F6\u95F4 created_at**\u3002\u5B83\u5171\u7528 jaccard \u6743\u91CD\u4F4D\uFF08\u5BF9\u5916\u7684\u4E09\u952E\u6743\u91CD\u4E0D\u53D8\uFF09\u3002\n#   # \u4EC0\u4E48\u65F6\u5019\u8BE5\u5F00\uFF1A\u5148\u7528 mem_admin stats \u770B validity.coverage\uFF08\u6709\u591A\u5C11\u6D3B\u8DC3\u4E8B\u5B9E\u5E26\u4E8B\u4EF6\u65F6\u95F4\uFF09\uFF0C\n#   # \u518D\u7528\u56DE\u5F52\u7F51\u786E\u8BA4\u5B83\u786E\u5B9E\u6539\u5584\u65F6\u95F4\u7C7B\u67E5\u8BE2\u2014\u2014\u8986\u76D6\u7387\u22480 \u65F6\u5B83\u7B49\u4E8E\u6CA1\u5F00\u3002\u5199\u5165\u4E8B\u4EF6\u65F6\u95F4\u7528 mem_remember \u7684 event_date\u3002\n#   time_window: false\n\n# lifecycle:\n#   purge_after_archived_days: 365    # \u5F52\u6863\u4E8B\u5B9E\u7684\u7269\u7406\u6E05\u7406\u7A97\u53E3\uFF08\u6D3B\u8DC3\u65E5\uFF09\n#   contradiction_threshold: 0.6\n\n# trust:\n#   decay_per_day: 0.0055\u2026\n#   presence:\n#     heartbeat_minutes: 60           # \u5E38\u9A7B\u8FDB\u7A0B\u7684\u5FC3\u8DF3\uFF08\u6D3B\u8DC3\u65E5\u65F6\u949F\u4E0E\u751F\u547D\u5468\u671F\u626B\u63CF\uFF09\n\n# tools:                              # \u5916\u90E8\u4E8C\u8FDB\u5236\uFF08pandoc\uFF09\u7684\u53D7\u7BA1\u76EE\u5F55\n#   dir: ''                           # \u7559\u7A7A = \u5BB6\u65CF\u6839 tools\uFF08~/.avantf/env/tools\uFF09\uFF1BAVANTF_TOOLS_DIR \u53EF\u8986\u76D6\n#   auto_install: true\n";
 /**
  * Ensure the common config exists with content, and hand back the path either way.
  *

package/lib/engine/mem/config/loader.d.ts

@@ -1,9 +1,8 @@
-import { type AvantfLogger, type Config, type MemoryConfig, type KnowledgeConfig } from '../../mem-contract/index.js';
+import { type AvantfLogger, type Config, type MemoryConfig } from '../../mem-contract/index.js';
 export interface LoadedConfig {
     home: string;
     common: Config;
     memory: MemoryConfig;
-    knowledge: KnowledgeConfig;
 }
 export interface LoadConfigOptions {
     dataHome?: string;
@@ -29,7 +28,7 @@ export interface LoadConfigOptions {
 }
 /**
  * Load config with layering: ① built-in defaults → ② `~/.avantf/configs/common.yaml`
- * (common) → ③ `~/.avantf/{memory,knowledge}/config.yaml` (store) → ④ env →
+ * (common) → ③ `~/.avantf/configs/memory.yaml` (store) → ④ env →
  * ⑤ explicit. Returns the resolved per-store config + data home.
  */
 export declare function loadConfig(opts?: LoadConfigOptions): LoadedConfig;

package/lib/engine/mem/config/paths.d.ts

@@ -31,23 +31,12 @@ export declare function resolveDataHome(input: {
  *
  * The layering is unchanged (① built-in → ② common → ③ store → ④ env → ⑤ explicit); only the
  * locations moved, so all of a deployment's editable text — `configs/*.yaml` and `prompts/*.md` —
- * is in one place instead of scattered through `memory/` and `knowledge/` next to the databases.
+ * is in one place instead of scattered through `memory/` next to the database.
  */
 export declare function configsDir(home: string): string;
 export declare function commonConfigPath(home: string): string;
 export declare function memoryDir(home: string): string;
-export declare function knowledgeDir(home: string): string;
 export declare function memoryConfigPath(home: string): string;
-export declare function knowledgeConfigPath(home: string): string;
 export declare function memoryDbPath(home: string, override?: string): string;
-export declare function knowledgeDbPath(home: string, override?: string): string;
-/**
- * The managed document directory (default `<home>/knowledge/docs`).
- *
- * One editable `.md` per document, so the corpus can be maintained with ordinary tools. It sits
- * BESIDE the database rather than replacing it: the file holds the body, the database holds the
- * identity, chunks and indexes derived from it.
- */
-export declare function knowledgeDocsDir(home: string, override?: string): string;
-/** Ensure the memory/knowledge layout exists under `home`. */
+/** Ensure the memory layout exists under `home`. */
 export declare function ensureDataLayout(home: string): void;

package/lib/engine/mem/db/dao/contradictions.d.ts

@@ -6,28 +6,10 @@
  * sides of every read are filtered to ACTIVE facts: the corpus is "changed × active", so a
  * pair whose other side left it is no longer actionable (see DESIGN §11).
  */
-import { type ContradictionRecord } from '../../../mem-contract/index.js';
+import { type ContradictionRecord, type MemoryKind } from '../../../mem-contract/index.js';
 import type { Db } from '../port.js';
-export interface ConflictPair {
-    /** Row id of the pair — the handle `contradict_resolve` takes. */
-    contradiction_id: number;
-    fact_a: number;
-    fact_b: number;
-    score: number;
-}
-/** A row of `contradiction_log` as stored: the pair plus its adjudication state. */
-export interface StoredConflict {
-    id: number;
-    fact_a: number;
-    fact_b: number;
-    score: number;
-    /** 0 = open, 1 = closed (see `resolution` / `loser_fact_id` for how). */
-    resolved: number;
-    resolution: string | null;
-    loser_fact_id: number | null;
-    /** `auto` (a fact left the corpus) or `verdict` (explicit adjudication). */
-    resolved_by: string | null;
-}
+import type { ConflictPair, StoredConflict } from '../../interfaces/repositories.js';
+export type { ConflictPair, StoredConflict } from '../../interfaces/repositories.js';
 export declare class ContradictionsDao {
     private readonly db;
     constructor(db: Db);
@@ -83,7 +65,7 @@ export declare class ContradictionsDao {
      * loser (the fact that actually left the corpus), so the recorded verdict is unchanged.
      */
     resolveForFacts(factIds: readonly number[], resolution?: 'true_positive' | 'false_positive'): number;
-    list(resolved?: number, category?: string, threshold?: number, limit?: number): ContradictionRecord[];
+    list(resolved?: number, kind?: MemoryKind, threshold?: number, limit?: number): ContradictionRecord[];
     /**
      * Every OPEN conflict that names `factId`, most severe first, with BOTH sides still active.
      *