@monoes/monomindcli 2.16.11 → 2.16.13

package/dist/src/memory/memory-kg-scan.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Memory Knowledge Graph — exhaustive paged namespace scans, write-failure
+ * reporting and CAS retry, per-origin collection, and the K7 reference edge
+ * lookup. Split out of memory-kg.ts, which re-exports the public symbols.
+ */
+import { bridgeListEntries, type bridgeStoreEntry } from './memory-bridge.js';
+import type { KgScope } from './memory-kg-model.js';
+/** Rows per `bridgeListEntries` call while scanning a namespace.
+ *
+ *  A single list call cannot return more than the backend's own 10,000-row
+ *  ceiling (`MAX_QUERY_LIMIT` in sql-backend.ts), so the old `limit: MAX_LIST`
+ *  scans were not "large enough to be safe" — they were exactly the point past
+ *  which the graph goes silently invisible. Everything below pages instead.
+ *
+ *  1,000 balances the two costs: one page is at most ~1 MB even at the bridge's
+ *  16 KB value cap (typical KG entries are far smaller), and it takes a tenth
+ *  of the round trips a 100-row page would. */
+export declare const SCAN_PAGE = 1000;
+/** Edge rows `kgSearch` will read before giving up and reporting `truncated`.
+ *  Search is interactive and runs a full scan per query, so unlike rollback it
+ *  keeps a ceiling — five times the old silent one, and now stated in the
+ *  result rather than hidden. */
+export declare const SEARCH_EDGE_SCAN_MAX = 50000;
+export type ScannedEntry = NonNullable<Awaited<ReturnType<typeof bridgeListEntries>>>['entries'][number];
+/** Page through an entire namespace, handing each page to `onPage` so callers
+ *  fold as they go instead of materializing the namespace.
+ *
+ *  `onPage` returning exactly `false` stops the scan early (only `kgSearch`
+ *  does that); any other return value continues. Returns false when the backend
+ *  was unavailable — an unreadable namespace must never be mistaken for an
+ *  empty one.
+ *
+ *  Callers that MUTATE what they find must collect during the scan and mutate
+ *  afterwards: deleting a row pulls every later row back one position, so under
+ *  an advancing offset the row that slid into the gap is never read. (The
+ *  bridge's upsert no longer reorders — it reuses the existing entry id and
+ *  preserves `createdAt` — so rewrites alone are safe; deletes are not, and
+ *  both callers here delete.) */
+export declare function scanNamespace(namespace: string, dbPath: string | undefined, onPage: (entries: ScannedEntry[]) => unknown): Promise<boolean>;
+/** Delete every entry in `namespace`. Used only to reset a DERIVED-index
+ *  namespace (`kg:adj`/`kg:origin-idx`) before a fresh `kgRebuildIndex` —
+ *  never a canonical one. Collect-then-delete, same reason `kgRollback`
+ *  does: deleting mid-scan pulls later rows back under an advancing offset.
+ *  Returns false (nothing deleted) on an unreadable or partially-deletable
+ *  namespace, so the caller never proceeds as if a clear that didn't fully
+ *  happen did. */
+export declare function clearNamespace(namespace: string, dbPath: string | undefined): Promise<boolean>;
+/** Cap on reported failure messages — a dead backend fails every write, and a
+ *  500-entry failure list is noise, not signal. `error` carries the true count. */
+export declare const MAX_FAILURES = 20;
+/** Accumulates write failures across a multi-write operation. The memory
+ *  bridge exposes no transaction primitive, so ingest CANNOT be atomic: some
+ *  writes land and some do not. Rather than hide that, callers get exact
+ *  counters for what persisted plus the failure list for what did not. */
+export declare class FailureLog {
+    readonly messages: string[];
+    private count;
+    /** @returns true when the write failed (caller should not count it). */
+    add(res: Awaited<ReturnType<typeof bridgeStoreEntry>>, what: string): boolean;
+    note(message: string): void;
+    get failed(): boolean;
+    /** Summary for the result's `error` field; undefined when everything landed. */
+    summary(): string | undefined;
+}
+/** Attempts a compare-and-swap claim write, retrying while the bridge reports
+ *  a version conflict (K5): a concurrent writer applied its own claim to the
+ *  same row between our read and our write. `attempt()` must re-read,
+ *  re-merge (via `applyClaim`), and re-attempt the write itself on every call
+ *  — retrying with the SAME stale write would just lose the update again,
+ *  the exact bug this exists to close.
+ *
+ *  Exhausting `maxAttempts` under sustained contention is returned as-is (the
+ *  last conflict response) rather than retried forever: the caller's
+ *  `FailureLog` reports it as a real, visible failure — never a silent lost
+ *  update — same as any other write the bridge refused. */
+export declare function withCasRetry(attempt: () => Promise<Awaited<ReturnType<typeof bridgeStoreEntry>>>, maxAttempts?: number): Promise<Awaited<ReturnType<typeof bridgeStoreEntry>>>;
+export declare function originsOf(entry: ScannedEntry): string[];
+/** Every entry in `namespace` that `originRef` supports, collected by an
+ *  EXHAUSTIVE paged scan. `covered` is false when the backend became
+ *  unreadable partway — an incomplete answer, never an empty one.
+ *
+ *  Collecting rather than streaming is required by the callers that mutate:
+ *  deleting a row pulls later rows back, so an advancing offset would skip
+ *  whatever slid into the gap. Only origin-carrying entries are retained, so
+ *  memory tracks the operation's own footprint, not the namespace size. */
+export declare function collectByOrigin(namespace: string, originRef: string, dbPath: string | undefined): Promise<{
+    entries: ScannedEntry[];
+    covered: boolean;
+}>;
+export interface KgReferenceEdge {
+    key: string;
+    src: string;
+    dst: string;
+    relation: string;
+    originRefs: string[];
+}
+/** Complete, uncapped read of every edge touching `endpointId` (as either
+ *  src or dst) and/or asserted by `originRef` — at least one filter is
+ *  required. This is the ground truth an indexed adjacency/origin lookup
+ *  (K7) must agree with once one exists: an exhaustive paged scan, the same
+ *  mechanism `kgRollback` already trusts for origin withdrawal, so it never
+ *  depends on an index and never inherits the old first-page cap.
+ *
+ *  `truncated: true` means the scan did not finish — an incomplete answer,
+ *  never an empty one. Callers comparing this against a future index must
+ *  treat a truncated reference read as "unknown", not as "no matches". */
+export declare function kgReferenceEdges(options: {
+    endpointId?: string;
+    originRef?: string;
+    scope?: KgScope;
+    dbPath?: string;
+}): Promise<{
+    success: boolean;
+    edges: KgReferenceEdge[];
+    truncated?: boolean;
+    error?: string;
+}>;
+//# sourceMappingURL=memory-kg-scan.d.ts.map

package/dist/src/memory/memory-kg-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-kg-scan.d.ts","sourceRoot":"","sources":["../../../src/memory/memory-kg-scan.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAqB,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACjG,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAGpD;;;;;;;;;+CAS+C;AAC/C,eAAO,MAAM,SAAS,OAAQ,CAAC;AAE/B;;;iCAGiC;AACjC,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C,MAAM,MAAM,YAAY,GAAG,WAAW,CACpC,OAAO,CAAC,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAC9C,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAErB;;;;;;;;;;;;;iCAaiC;AACjC,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,OAAO,GAC3C,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED;;;;;;kBAMkB;AAClB,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,OAAO,CAAC,OAAO,CAAC,CAYlB;AAED;mFACmF;AACnF,eAAO,MAAM,YAAY,KAAK,CAAC;AAkB/B;;;0EAG0E;AAC1E,qBAAa,UAAU;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAM;IACjC,OAAO,CAAC,KAAK,CAAK;IAElB,wEAAwE;IACxE,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAM5E;IAED,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAG1B;IAED,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,gFAAgF;IAChF,OAAO,IAAI,MAAM,GAAG,SAAS,CAG5B;CACF;AAED;;;;;;;;;;2DAU2D;AAC3D,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC,EACpE,WAAW,SAAI,GACd,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAOvD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,CAGvD;AAED;;;;;;;2EAO2E;AAC3E,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,OAAO,CAAC;IAAE,OAAO,EAAE,YAAY,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAMxD;AAID,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;0EAS0E;AAC1E,wBAAsB,gBAAgB,CAAC,OAAO,EAAE;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,eAAe,EAAE,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAiC/F"}

package/dist/src/memory/memory-kg-scan.js

@@ -0,0 +1,209 @@
+/**
+ * Memory Knowledge Graph — exhaustive paged namespace scans, write-failure
+ * reporting and CAS retry, per-origin collection, and the K7 reference edge
+ * lookup. Split out of memory-kg.ts, which re-exports the public symbols.
+ */
+import { bridgeDeleteEntry, bridgeListEntries } from './memory-bridge.js';
+import { kgNamespaces, kgQualifyOrigin } from './memory-kg-model.js';
+/** Rows per `bridgeListEntries` call while scanning a namespace.
+ *
+ *  A single list call cannot return more than the backend's own 10,000-row
+ *  ceiling (`MAX_QUERY_LIMIT` in sql-backend.ts), so the old `limit: MAX_LIST`
+ *  scans were not "large enough to be safe" — they were exactly the point past
+ *  which the graph goes silently invisible. Everything below pages instead.
+ *
+ *  1,000 balances the two costs: one page is at most ~1 MB even at the bridge's
+ *  16 KB value cap (typical KG entries are far smaller), and it takes a tenth
+ *  of the round trips a 100-row page would. */
+export const SCAN_PAGE = 1_000;
+/** Edge rows `kgSearch` will read before giving up and reporting `truncated`.
+ *  Search is interactive and runs a full scan per query, so unlike rollback it
+ *  keeps a ceiling — five times the old silent one, and now stated in the
+ *  result rather than hidden. */
+export const SEARCH_EDGE_SCAN_MAX = 50_000;
+/** Page through an entire namespace, handing each page to `onPage` so callers
+ *  fold as they go instead of materializing the namespace.
+ *
+ *  `onPage` returning exactly `false` stops the scan early (only `kgSearch`
+ *  does that); any other return value continues. Returns false when the backend
+ *  was unavailable — an unreadable namespace must never be mistaken for an
+ *  empty one.
+ *
+ *  Callers that MUTATE what they find must collect during the scan and mutate
+ *  afterwards: deleting a row pulls every later row back one position, so under
+ *  an advancing offset the row that slid into the gap is never read. (The
+ *  bridge's upsert no longer reorders — it reuses the existing entry id and
+ *  preserves `createdAt` — so rewrites alone are safe; deletes are not, and
+ *  both callers here delete.) */
+export async function scanNamespace(namespace, dbPath, onPage) {
+    for (let offset = 0;; offset += SCAN_PAGE) {
+        const res = await bridgeListEntries({ namespace, limit: SCAN_PAGE, offset, dbPath });
+        if (!res)
+            return false;
+        if (res.entries.length && onPage(res.entries) === false)
+            return true;
+        if (res.entries.length < SCAN_PAGE)
+            return true;
+    }
+}
+/** Delete every entry in `namespace`. Used only to reset a DERIVED-index
+ *  namespace (`kg:adj`/`kg:origin-idx`) before a fresh `kgRebuildIndex` —
+ *  never a canonical one. Collect-then-delete, same reason `kgRollback`
+ *  does: deleting mid-scan pulls later rows back under an advancing offset.
+ *  Returns false (nothing deleted) on an unreadable or partially-deletable
+ *  namespace, so the caller never proceeds as if a clear that didn't fully
+ *  happen did. */
+export async function clearNamespace(namespace, dbPath) {
+    const doomed = [];
+    const covered = await scanNamespace(namespace, dbPath, (page) => {
+        for (const e of page)
+            doomed.push(e);
+    });
+    if (!covered)
+        return false;
+    let ok = true;
+    for (const e of doomed) {
+        const del = await bridgeDeleteEntry({ id: e.id, namespace, dbPath });
+        if (!del?.deleted)
+            ok = false;
+    }
+    return ok;
+}
+/** Cap on reported failure messages — a dead backend fails every write, and a
+ *  500-entry failure list is noise, not signal. `error` carries the true count. */
+export const MAX_FAILURES = 20;
+/** `bridgeStoreEntry` never throws: it returns `null` when no backend is
+ *  reachable and `{ success: false, error }` when the write itself failed.
+ *  Both look like success to an `await` that ignores the result, which is how
+ *  the graph came to claim knowledge it had not persisted. Every write in this
+ *  module goes through here.
+ *
+ *  @returns a failure message, or null when the write landed. */
+function storeFailure(res, what) {
+    if (!res)
+        return `${what}: memory backend unavailable`;
+    if (!res.success)
+        return `${what}: ${res.error ?? 'store rejected'}`;
+    return null;
+}
+/** Accumulates write failures across a multi-write operation. The memory
+ *  bridge exposes no transaction primitive, so ingest CANNOT be atomic: some
+ *  writes land and some do not. Rather than hide that, callers get exact
+ *  counters for what persisted plus the failure list for what did not. */
+export class FailureLog {
+    messages = [];
+    count = 0;
+    /** @returns true when the write failed (caller should not count it). */
+    add(res, what) {
+        const msg = storeFailure(res, what);
+        if (!msg)
+            return false;
+        this.count++;
+        if (this.messages.length < MAX_FAILURES)
+            this.messages.push(msg);
+        return true;
+    }
+    note(message) {
+        this.count++;
+        if (this.messages.length < MAX_FAILURES)
+            this.messages.push(message);
+    }
+    get failed() {
+        return this.count > 0;
+    }
+    /** Summary for the result's `error` field; undefined when everything landed. */
+    summary() {
+        if (!this.count)
+            return undefined;
+        return `${this.count} bridge operation(s) failed; graph state is partial`;
+    }
+}
+/** Attempts a compare-and-swap claim write, retrying while the bridge reports
+ *  a version conflict (K5): a concurrent writer applied its own claim to the
+ *  same row between our read and our write. `attempt()` must re-read,
+ *  re-merge (via `applyClaim`), and re-attempt the write itself on every call
+ *  — retrying with the SAME stale write would just lose the update again,
+ *  the exact bug this exists to close.
+ *
+ *  Exhausting `maxAttempts` under sustained contention is returned as-is (the
+ *  last conflict response) rather than retried forever: the caller's
+ *  `FailureLog` reports it as a real, visible failure — never a silent lost
+ *  update — same as any other write the bridge refused. */
+export async function withCasRetry(attempt, maxAttempts = 3) {
+    let res = null;
+    for (let i = 0; i < maxAttempts; i++) {
+        res = await attempt();
+        if (!res?.conflict)
+            return res;
+    }
+    return res;
+}
+export function originsOf(entry) {
+    const origins = (entry.metadata ?? {}).origin_refs;
+    return Array.isArray(origins) ? origins : [];
+}
+/** Every entry in `namespace` that `originRef` supports, collected by an
+ *  EXHAUSTIVE paged scan. `covered` is false when the backend became
+ *  unreadable partway — an incomplete answer, never an empty one.
+ *
+ *  Collecting rather than streaming is required by the callers that mutate:
+ *  deleting a row pulls later rows back, so an advancing offset would skip
+ *  whatever slid into the gap. Only origin-carrying entries are retained, so
+ *  memory tracks the operation's own footprint, not the namespace size. */
+export async function collectByOrigin(namespace, originRef, dbPath) {
+    const entries = [];
+    const covered = await scanNamespace(namespace, dbPath, (page) => {
+        for (const e of page)
+            if (originsOf(e).includes(originRef))
+                entries.push(e);
+    });
+    return { entries, covered };
+}
+/** Complete, uncapped read of every edge touching `endpointId` (as either
+ *  src or dst) and/or asserted by `originRef` — at least one filter is
+ *  required. This is the ground truth an indexed adjacency/origin lookup
+ *  (K7) must agree with once one exists: an exhaustive paged scan, the same
+ *  mechanism `kgRollback` already trusts for origin withdrawal, so it never
+ *  depends on an index and never inherits the old first-page cap.
+ *
+ *  `truncated: true` means the scan did not finish — an incomplete answer,
+ *  never an empty one. Callers comparing this against a future index must
+ *  treat a truncated reference read as "unknown", not as "no matches". */
+export async function kgReferenceEdges(options) {
+    if (!options.endpointId && !options.originRef) {
+        return { success: false, edges: [], error: 'endpointId or originRef is required' };
+    }
+    const ns = kgNamespaces(options.scope);
+    const originRef = options.originRef
+        ? kgQualifyOrigin(options.originRef, options.scope)
+        : undefined;
+    const edges = [];
+    try {
+        const covered = await scanNamespace(ns.edges, options.dbPath, (page) => {
+            for (const e of page) {
+                const md = (e.metadata ?? {});
+                if (md.kg !== 'edge')
+                    continue;
+                const src = String(md.src ?? '');
+                const dst = String(md.dst ?? '');
+                if (options.endpointId && src !== options.endpointId && dst !== options.endpointId)
+                    continue;
+                const originRefs = originsOf(e);
+                if (originRef && !originRefs.includes(originRef))
+                    continue;
+                edges.push({
+                    key: e.key,
+                    src,
+                    dst,
+                    relation: String(md.relation ?? 'related_to'),
+                    originRefs,
+                });
+            }
+        });
+        return { success: true, edges, ...(covered ? {} : { truncated: true }) };
+    }
+    catch (err) {
+        return { success: false, edges, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+//# sourceMappingURL=memory-kg-scan.js.map

package/dist/src/memory/memory-kg-scan.js.map

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

package/dist/src/memory/memory-kg-search.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Memory Knowledge Graph — retrieval: kgSearch (seed nodes, neighbourhood
+ * expansion, evidence-aware ranking) and kgGlossary for extraction prompts.
+ * Split out of memory-kg.ts, which re-exports the public symbols.
+ */
+import type { KgExtractionMethod } from './memory-kg-claims.js';
+import type { KgScope } from './memory-kg-model.js';
+export interface KgSearchResult {
+    success: boolean;
+    /** Rendered triplet lines, best first. */
+    context: string;
+    triplets: {
+        source: string;
+        relation: string;
+        target: string;
+        fact: string;
+        score: number;
+        /** How this edge came to exist. Absent means the edge predates method
+         *  recording — not recorded, which is not the same as `asserted`. */
+        method?: KgExtractionMethod;
+        /** Live origins disagree about what this edge says. Present only when true. */
+        conflict?: boolean;
+        /** The edge's bridge entry id — feed this straight to `memory_feedback`
+         *  (`bridgeApplyFeedback`/`bridgeRecordUsage`) to rate THIS relationship
+         *  directly, rather than only the seed entity that surfaced it (K5). */
+        id: string;
+        /** The edge's stable graph key (`e:<hash>`, see `edgeKey`), for direct
+         *  `bridgeGetEntry` lookup or diagnostics — distinct from `id` above. */
+        key: string;
+    }[];
+    seeds: {
+        name: string;
+        type: string;
+        description: string;
+        score: number;
+        id: string;
+    }[];
+    /** True when the edge scan did NOT cover the whole namespace — the scan hit
+     *  `SEARCH_EDGE_SCAN_MAX`, or the backend became unreadable partway. A
+     *  relationship that exists may be missing from `triplets`; absence here is
+     *  not evidence of absence in the graph. */
+    truncated?: boolean;
+    /** Edge rows actually read, so a caller can see how close it ran to the cap. */
+    scannedEdges?: number;
+    /** What the seed retrieval ACTUALLY ran, straight from the bridge — never what
+     *  was hoped for. `keyword-fallback` means the vector path was tried and did
+     *  not serve these results. Absent only when the bridge reported nothing. */
+    method?: 'semantic' | 'keyword' | 'keyword-fallback';
+    /** Why the vector path did not serve the seeds (absent when it did). */
+    fallbackReason?: string;
+    error?: string;
+}
+/** Seeded retrieval → neighborhood → triplet ranking (cognee's brute-force
+ *  triplet search, scaled down). Seed scores already carry the Phase 1 feedback
+ *  blend, and the seed retrieval may be vector or keyword — `method` on the
+ *  result says which actually ran.
+ *
+ *  Ranking weighs exactly two evidence signals, both read off the claim ledger:
+ *  extraction method and description conflict. It deliberately does NOT model
+ *  source credibility, claim freshness, or whether the relation itself answers
+ *  the query — those need an evaluation set to tune against, and guessing at
+ *  them would be the same overclaim this weighting exists to correct. */
+export declare function kgSearch(options: {
+    query: string;
+    dbPath?: string;
+    limit?: number;
+    nodeSet?: string;
+    /** Whose graph to search. Omit for project-shared knowledge; a scoped search
+     *  never reaches another org's facts, and never the shared graph either. */
+    scope?: KgScope;
+}): Promise<KgSearchResult>;
+export declare function kgGlossary(options?: {
+    dbPath?: string;
+    limit?: number;
+    /** Whose entity names to offer. The coordinator glossary MUST be scoped:
+     *  suggesting another org's entity names is how one org's claims get merged
+     *  into another's graph under a shared name. */
+    scope?: KgScope;
+}): Promise<string[]>;
+//# sourceMappingURL=memory-kg-search.d.ts.map

package/dist/src/memory/memory-kg-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-kg-search.d.ts","sourceRoot":"","sources":["../../../src/memory/memory-kg-search.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAOpD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE;QACR,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd;6EACqE;QACrE,MAAM,CAAC,EAAE,kBAAkB,CAAC;QAC5B,+EAA+E;QAC/E,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB;;gFAEwE;QACxE,EAAE,EAAE,MAAM,CAAC;QACX;iFACyE;QACzE,GAAG,EAAE,MAAM,CAAC;KACb,EAAE,CAAC;IACJ,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACxF;;;gDAG4C;IAC5C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;iFAE6E;IAC7E,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,kBAAkB,CAAC;IACrD,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAoBD;;;;;;;;;yEASyE;AACzE,wBAAsB,QAAQ,CAAC,OAAO,EAAE;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;gFAC4E;IAC5E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,cAAc,CAAC,CA6K1B;AAID,wBAAsB,UAAU,CAAC,OAAO,CAAC,EAAE;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;oDAEgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAiCpB"}