@monoes/monomindcli 2.16.12 → 2.16.13

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

@@ -0,0 +1,361 @@
+/**
+ * Memory Knowledge Graph — ingest: kgIngest (entity resolution, claim
+ * merge under compare-and-swap, placeholder endpoints) and its per-call
+ * report. Split out of memory-kg.ts, which re-exports kgIngest.
+ */
+import { bridgeGetEntry, bridgeStoreEntry } from './memory-bridge.js';
+import { applyClaim } from './memory-kg-claims.js';
+import { onEdgeWritten, onEntrySupported } from './memory-kg-index.js';
+import { canonicalName, edgeKey, KG_ID_VERSION, kgNamespaces, kgQualifyOrigin, legacyEdgeKey, MAX_DESC_LEN, MAX_EDGES_PER_CALL, MAX_NODES_PER_CALL, normalizeName, typeBucket, } from './memory-kg-model.js';
+import { resolveEntity, writeNameIndex } from './memory-kg-names.js';
+import { FailureLog, MAX_FAILURES, withCasRetry } from './memory-kg-scan.js';
+// ── Ingest ──────────────────────────────────────────────────────────
+/** Merge extracted nodes/edges into the KG.
+ *
+ *  Identity is the (type, name) tuple resolved through the name index, so an
+ *  entity is idempotent under re-extraction but two different things sharing a
+ *  name stay two things. Each write adds this origin's CONTRIBUTION to the
+ *  element's claim ledger, from which the description and `origin_refs` are
+ *  derived — which is what lets a later ingest correct an earlier one and lets
+ *  rollback put the earlier one back.
+ *
+ *  The COMPLETE payload is validated before anything is written, and every edge
+ *  endpoint is made to exist (as a placeholder entity when the caller named one
+ *  that does not) before the edge lands. An edge whose endpoint could not be
+ *  created is rejected rather than written: retrieval is seeded from nodes, so
+ *  an edge with a missing endpoint is a fact that cannot be found through
+ *  either of the things it is about.
+ *
+ *  NOT ATOMIC — the memory bridge has no transaction primitive, so a failure
+ *  part-way through leaves earlier writes persisted. The counters therefore
+ *  report only what actually landed, `failures` lists what did not, and
+ *  `success` is false whenever anything was refused. A partial ingest is safe
+ *  to retry: every write is a keyed upsert. */
+export async function kgIngest(options) {
+    const { dbPath } = options;
+    const method = options.method ?? 'asserted';
+    const ns = kgNamespaces(options.scope);
+    const originRef = kgQualifyOrigin(options.originRef, options.scope);
+    const failures = new FailureLog();
+    const report = new IngestReport();
+    let nodesAdded = 0, nodesMerged = 0, edgesAdded = 0, edgesMerged = 0;
+    try {
+        // ── Validate the COMPLETE payload before mutating anything ──
+        // An invalid item that surfaces halfway through leaves the graph holding
+        // part of a payload the caller was told was rejected.
+        const allNodes = options.nodes ?? [];
+        const allEdges = options.edges ?? [];
+        const nodes = allNodes.slice(0, MAX_NODES_PER_CALL);
+        const edges = allEdges.slice(0, MAX_EDGES_PER_CALL);
+        report.nodesTruncated = allNodes.length - nodes.length;
+        report.edgesTruncated = allEdges.length - edges.length;
+        const validNodes = [];
+        nodes.forEach((n, i) => {
+            if (!n?.name?.trim())
+                return report.rejectNode(`node[${i}]: missing name`);
+            validNodes.push({
+                input: n,
+                type: n.type?.trim() || 'entity',
+                desc: (n.description ?? '').slice(0, MAX_DESC_LEN),
+            });
+        });
+        const validEdges = [];
+        edges.forEach((e, i) => {
+            const missing = !e?.source?.trim()
+                ? 'source'
+                : !e?.target?.trim()
+                    ? 'target'
+                    : !e?.relation?.trim()
+                        ? 'relation'
+                        : '';
+            if (missing)
+                return report.rejectEdge(`edge[${i}]: missing ${missing}`);
+            validEdges.push(e);
+        });
+        /** Entity IDs this call has already resolved AND confirmed to exist, so an
+         *  edge does not re-resolve an endpoint the node loop just wrote. */
+        const resolved = new Map();
+        // Length-prefix the type so the split point is unambiguous regardless of
+        // what characters `name` contains (it can hold arbitrary text, including
+        // whatever separator a naive join might pick) — same discipline
+        // hashTuple() above uses for the same reason. A bare `\0`-joined string
+        // here was written as an actual NUL byte, not the literal two-character
+        // escape text, which is harmless at runtime (this key is an in-memory
+        // Map key only, never persisted) but made git treat this file as binary.
+        const memoKey = (name, type) => {
+            const t = typeBucket(type);
+            return `${t.length}:${t}${canonicalName(name)}`;
+        };
+        for (const { input: n, type, desc } of validNodes) {
+            const target = await resolveEntity(n.name, type, ns, dbPath);
+            if (!target) {
+                failures.note(`node ${n.name}: name index unreadable`);
+                continue;
+            }
+            report.noteAmbiguity(n.name, target.candidates);
+            const wrote = await writeEntity({
+                id: target.id,
+                name: n.name,
+                type,
+                description: desc,
+                nodeSet: n.nodeSet,
+                originRef,
+                method,
+                ns,
+                dbPath,
+                failures,
+                report,
+            });
+            if (wrote === null)
+                continue;
+            if (wrote)
+                nodesAdded++;
+            else
+                nodesMerged++;
+            resolved.set(memoKey(n.name, type), target.id);
+            if (target.index)
+                await writeNameIndex(n.name, target.index, ns, dbPath, failures);
+            await onEntrySupported(ns, ns.nodes, target.id, originRef, dbPath);
+        }
+        /** Resolve an edge endpoint, creating an explicit placeholder entity when
+         *  the caller named something that does not exist. Returns null when the
+         *  endpoint could not be made to exist — the edge is then rejected rather
+         *  than written without it. */
+        const endpoint = async (name, type) => {
+            const memo = memoKey(name, type ?? 'entity');
+            const hit = resolved.get(memo);
+            if (hit)
+                return hit;
+            const target = await resolveEntity(name, type ?? 'entity', ns, dbPath);
+            if (!target) {
+                failures.note(`endpoint ${name}: name index unreadable`);
+                return null;
+            }
+            report.noteAmbiguity(name, target.candidates);
+            // Always write: naming an endpoint IS an assertion that it exists, so
+            // this origin joins the entity's support either way. A write that CREATES
+            // the entity is the placeholder case worth reporting.
+            const wrote = await writeEntity({
+                id: target.id,
+                name,
+                type: type ?? 'entity',
+                description: '',
+                placeholder: true,
+                originRef,
+                method,
+                ns,
+                dbPath,
+                failures,
+                report,
+            });
+            if (wrote === null)
+                return null;
+            if (wrote)
+                report.placeholders++;
+            if (target.index)
+                await writeNameIndex(name, target.index, ns, dbPath, failures);
+            resolved.set(memo, target.id);
+            await onEntrySupported(ns, ns.nodes, target.id, originRef, dbPath);
+            return target.id;
+        };
+        for (const e of validEdges) {
+            const srcKey = await endpoint(e.source, e.sourceType);
+            const dstKey = await endpoint(e.target, e.targetType);
+            if (!srcKey || !dstKey) {
+                report.rejectEdge(`edge ${e.source}-${e.relation}->${e.target}: endpoint not persisted`);
+                continue;
+            }
+            const desc = (e.description ?? '').slice(0, MAX_DESC_LEN);
+            const fallbackFact = `${e.source} ${e.relation} ${e.target}`;
+            // New key first, then the pre-KG_ID_VERSION shape: a legacy edge between
+            // two adopted legacy endpoints keeps its own key rather than being
+            // duplicated under a new one. Resolved once — a CAS retry re-reads this
+            // same key, it does not re-run legacy resolution.
+            let key = edgeKey(srcKey, e.relation, dstKey);
+            const probe = await bridgeGetEntry({ key, namespace: ns.edges, dbPath });
+            if (!probe?.found) {
+                const legacy = legacyEdgeKey(srcKey, e.relation, dstKey);
+                const hit = await bridgeGetEntry({ key: legacy, namespace: ns.edges, dbPath });
+                if (hit?.found && hit.entry)
+                    key = legacy;
+            }
+            // Re-read and re-merge on every CAS attempt (see withCasRetry): a stale
+            // `md`/`derived` retried against a fresh row would silently re-lose
+            // whatever a concurrent writer just added (K5).
+            let md = {};
+            let derived;
+            let isNew = false;
+            const res = await withCasRetry(async () => {
+                const existing = await bridgeGetEntry({ key, namespace: ns.edges, dbPath });
+                isNew = !(existing?.found && existing.entry);
+                md = (existing?.entry?.metadata ?? {});
+                derived = applyClaim(md, originRef, desc, Date.now(), method);
+                const ver = existing?.entry?.version;
+                return bridgeStoreEntry({
+                    key,
+                    value: derived.description || fallbackFact,
+                    namespace: ns.edges,
+                    dbPath,
+                    upsert: true,
+                    generateEmbeddingFlag: false,
+                    tags: ['kg', normalizeName(e.relation)],
+                    metadata: {
+                        ...md,
+                        kg: 'edge',
+                        id_version: KG_ID_VERSION,
+                        src: srcKey,
+                        dst: dstKey,
+                        relation: normalizeName(e.relation),
+                        source_name: e.source,
+                        target_name: e.target,
+                        ...derived,
+                        valid_from: md.valid_from ?? Date.now(),
+                        valid_to: null,
+                    },
+                    ifVersion: isNew ? 'absent' : typeof ver === 'number' ? ver : undefined,
+                });
+            });
+            if (failures.add(res, `edge ${key}`))
+                continue;
+            report.noteProvenanceLoss(md, derived);
+            if (isNew)
+                edgesAdded++;
+            else
+                edgesMerged++;
+            await onEntrySupported(ns, ns.edges, key, originRef, dbPath);
+            if (isNew)
+                await onEdgeWritten(ns, key, srcKey, dstKey, dbPath);
+        }
+        return {
+            success: !failures.failed,
+            nodesAdded,
+            nodesMerged,
+            edgesAdded,
+            edgesMerged,
+            ...(failures.failed ? { failures: failures.messages, error: failures.summary() } : {}),
+            ...report.fields(),
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            nodesAdded,
+            nodesMerged,
+            edgesAdded,
+            edgesMerged,
+            ...(failures.messages.length ? { failures: failures.messages } : {}),
+            ...report.fields(),
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/** Write one entity's claim contribution.
+ *
+ *  @returns true when the entity was created, false when an existing one was
+ *  merged into, and null when the bridge refused the write (the caller must not
+ *  count it, and must not treat the entity as existing). */
+async function writeEntity(o) {
+    // Re-read and re-merge on every CAS attempt (see withCasRetry) rather than
+    // once up front: a stale `md`/`derived` retried against a fresh row would
+    // silently re-lose whatever a concurrent writer just added (K5).
+    let md = {};
+    let derived;
+    let isNew = false;
+    const res = await withCasRetry(async () => {
+        const existing = await bridgeGetEntry({ key: o.id, namespace: o.ns.nodes, dbPath: o.dbPath });
+        isNew = !(existing?.found && existing.entry);
+        md = (existing?.entry?.metadata ?? {});
+        derived = applyClaim(md, o.originRef, o.description, Date.now(), o.method);
+        // Keep the most specific type: a generic heuristic 'entity' never
+        // overwrites an LLM-assigned one, and a specific one promotes an untyped
+        // entity.
+        const prevType = typeof md.type === 'string' ? md.type : '';
+        const bestType = typeBucket(prevType) ? prevType : o.type;
+        const nodeSet = o.nodeSet ?? (typeof md.node_set === 'string' ? md.node_set : null);
+        const ver = existing?.entry?.version;
+        return bridgeStoreEntry({
+            key: o.id,
+            value: `${o.name} — ${derived.description || bestType}`,
+            namespace: o.ns.nodes,
+            dbPath: o.dbPath,
+            upsert: true,
+            tags: ['kg', normalizeName(bestType), ...(nodeSet ? [normalizeName(nodeSet)] : [])],
+            metadata: {
+                ...md,
+                kg: 'node',
+                id_version: KG_ID_VERSION,
+                type: bestType,
+                name: o.name,
+                node_set: nodeSet,
+                ...derived,
+                // A placeholder stops being one the moment a real assertion describes it.
+                placeholder: o.placeholder === true && !derived.description ? true : undefined,
+                version: (typeof md.version === 'number' ? md.version : 0) + 1,
+                valid_from: md.valid_from ?? Date.now(),
+                valid_to: null,
+            },
+            // isNew ⇒ this row must not already exist; otherwise it must still be at
+            // the version we just read. Absent when the loaded backend/test double
+            // does not report a version, so behaviour is unchanged there (see
+            // bridgeGetEntry's `version` field).
+            ifVersion: isNew ? 'absent' : typeof ver === 'number' ? ver : undefined,
+        });
+    });
+    // Name first: the ID is a digest, and a failure message a human cannot map
+    // back to the thing that failed is not a diagnosis.
+    if (o.failures.add(res, `node ${o.name} (${o.id})`))
+        return null;
+    // Only after the write landed: a refused write dropped no provenance, because
+    // it changed nothing.
+    o.report.noteProvenanceLoss(md, derived);
+    return isNew;
+}
+/** The accepted/rejected/truncated bookkeeping a caller needs in order to know
+ *  that what it sent is what the graph holds. */
+class IngestReport {
+    nodesRejected = 0;
+    edgesRejected = 0;
+    nodesTruncated = 0;
+    edgesTruncated = 0;
+    placeholders = 0;
+    provenanceTruncated = 0;
+    rejections = [];
+    ambiguities = [];
+    rejectNode(message) {
+        this.nodesRejected++;
+        if (this.rejections.length < MAX_FAILURES)
+            this.rejections.push(message);
+    }
+    rejectEdge(message) {
+        this.edgesRejected++;
+        if (this.rejections.length < MAX_FAILURES)
+            this.rejections.push(message);
+    }
+    noteAmbiguity(name, candidates) {
+        if (!candidates.length || this.ambiguities.length >= MAX_FAILURES)
+            return;
+        const types = candidates.map((c) => c.type || 'untyped').join(', ');
+        this.ambiguities.push(`${name}: kept separate from ${candidates.length} same-name (${types})`);
+    }
+    noteProvenanceLoss(md, derived) {
+        const before = typeof md.origins_dropped === 'number' ? md.origins_dropped : 0;
+        if (derived.origins_dropped > before)
+            this.provenanceTruncated++;
+    }
+    /** Only non-zero counters are emitted, so a clean payload yields a clean
+     *  result and the existing `KgIngestResult` shape is unchanged for callers
+     *  that construct it themselves. */
+    fields() {
+        return {
+            ...(this.nodesRejected ? { nodesRejected: this.nodesRejected } : {}),
+            ...(this.edgesRejected ? { edgesRejected: this.edgesRejected } : {}),
+            ...(this.nodesTruncated ? { nodesTruncated: this.nodesTruncated } : {}),
+            ...(this.edgesTruncated ? { edgesTruncated: this.edgesTruncated } : {}),
+            ...(this.rejections.length ? { rejections: this.rejections } : {}),
+            ...(this.placeholders ? { placeholders: this.placeholders } : {}),
+            ...(this.ambiguities.length ? { ambiguities: this.ambiguities } : {}),
+            ...(this.provenanceTruncated ? { provenanceTruncated: this.provenanceTruncated } : {}),
+        };
+    }
+}
+//# sourceMappingURL=memory-kg-ingest.js.map

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

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

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

@@ -0,0 +1,168 @@
+/**
+ * Memory Knowledge Graph — namespaces, limits, identity (entity/edge/rule
+ * keys), the ingest input/result types, and scope (org ownership). Split out
+ * of memory-kg.ts, which re-exports the public symbols; see that module's
+ * header for the design.
+ */
+export declare const KG_NODES_NS = "kg:nodes";
+export declare const KG_EDGES_NS = "kg:edges";
+export declare const RULES_NS = "rules";
+/** Name → entity index. Index rows are NOT claims, so they live outside the
+ *  three claim namespaces: putting them in `kg:nodes` would make them seed
+ *  candidates for `kgSearch` and rows in `kgStats`. */
+export declare const KG_NAMES_NS = "kg:names";
+/** Derived adjacency index namespace (K7). See `KgNamespaces.adj`. */
+export declare const KG_ADJ_NS = "kg:adj";
+/** Derived origin-support index namespace (K7). See `KgNamespaces.originIdx`. */
+export declare const KG_ORIGIN_IDX_NS = "kg:origin-idx";
+/** Derived-index status namespace (K7). See `KgNamespaces.indexStatus`. */
+export declare const KG_INDEX_STATUS_NS = "kg:index-status";
+export declare const MAX_DESC_LEN = 2000;
+/** Nodes/edges/rules accepted per call. Overflow is REPORTED, never sliced away
+ *  in silence — see `KgIngestResult.nodesTruncated`. */
+export declare const MAX_NODES_PER_CALL = 500;
+export declare const MAX_EDGES_PER_CALL = 1000;
+export declare const MAX_RULES_PER_CALL = 50;
+/** Per-origin description contributions retained on one element.
+ *
+ *  A cap has to exist — the bridge caps a stored value, and an element asserted
+ *  by ten thousand runs would otherwise stop being writable. What must NOT
+ *  happen is the old `origin_refs.slice(-100)`, which dropped the oldest
+ *  provenance and left the entry claiming complete history. Past this cap the
+ *  oldest contributions are dropped AND the entry records `origins_dropped`
+ *  with `provenance_complete: false`, so a reader can tell that a rollback of an
+ *  old origin may find nothing to withdraw. */
+export declare const MAX_CLAIMS = 200;
+/**
+ * Version of the identity scheme implemented by `entityId`/`edgeKey`/`ruleKey`.
+ *
+ * Bump when a derivation changes. Entries written under an older scheme are not
+ * orphaned: resolution probes the previous key shape and adopts the row in
+ * place (see `resolveEntity`), so a bump costs a second keyed lookup on the
+ * miss path rather than a migration.
+ *
+ * Version 1 was the name-only scheme (`n:<normalized-name>`, truncated to 200
+ * characters), under which `Person:Alex` and `Service:Alex` were one entity and
+ * two names first differing at character 250 were one entity.
+ */
+export declare const KG_ID_VERSION = 2;
+/** Identity-grade name normalization: the same folding as `normalizeName` but
+ *  WITHOUT its 200-character truncation, which silently merged long names that
+ *  differ only past the cut. `normalizeName` keeps truncating because it feeds
+ *  tags and display, where length matters and collisions do not. */
+export declare function canonicalName(name: string): string;
+/** The identity-bearing part of a type: '' when the caller told us nothing. */
+export declare function typeBucket(type: string | undefined): string;
+/** Hash a tuple injectively: every component is length-prefixed, so no
+ *  component's content can masquerade as a delimiter or bleed into its
+ *  neighbour, and no two distinct tuples share an input string. Same discipline
+ *  as monograph's `symbolId`/`fileId` (packages/@monomind/monograph/src/types.ts),
+ *  and adopted here for the same reason — the previous scheme lost distinctions
+ *  to truncation and to an unescaped separator. */
+export declare function hashTuple(components: string[]): string;
+/** Mint an entity id from the full identity tuple.
+ *
+ *  This MINTS; it does not RESOLVE. A caller that computes an id and writes to
+ *  it bypasses the name index and re-forks the entities the index exists to
+ *  keep together — every ingest path goes through `resolveEntity` instead. */
+export declare function nodeKey(type: string, name: string): string;
+/** The pre-`KG_ID_VERSION` key for a name: name-only, truncated at 200. Probed
+ *  on a miss so existing graphs keep working without being re-keyed. */
+export declare function legacyNodeKey(name: string): string;
+export interface KgNodeInput {
+    name: string;
+    /** Basic type, cognee-style ("Person", "Tool", "Service") — not over-specific. */
+    type?: string;
+    description?: string;
+    nodeSet?: string;
+}
+export interface KgEdgeInput {
+    source: string;
+    target: string;
+    /** snake_case relation name. */
+    relation: string;
+    /** One-sentence concrete fact using the endpoint names. */
+    description?: string;
+    sourceType?: string;
+    targetType?: string;
+}
+export interface KgIngestResult {
+    success: boolean;
+    nodesAdded: number;
+    nodesMerged: number;
+    edgesAdded: number;
+    edgesMerged: number;
+    /** Writes the bridge refused, one message each (capped at MAX_FAILURES).
+     *  Non-empty ⇒ `success` is false and the counters describe only what
+     *  actually persisted. */
+    failures?: string[];
+    error?: string;
+    /** Items the payload asked for that this call refused. Present only when
+     *  non-zero, so a caller who sent a clean payload sees a clean result. */
+    nodesRejected?: number;
+    edgesRejected?: number;
+    /** Items dropped because the payload exceeded the per-call cap. The cap has
+     *  not changed; what has changed is that it is now REPORTED instead of being
+     *  a silent `.slice()`. */
+    nodesTruncated?: number;
+    edgesTruncated?: number;
+    /** Why items were rejected, one message each (capped at MAX_FAILURES). */
+    rejections?: string[];
+    /** Endpoint entities created because an edge named them and they did not
+     *  exist. Edge-only ingestion used to succeed with zero nodes and one edge,
+     *  leaving a fact unreachable through both of its own endpoints. */
+    placeholders?: number;
+    /** Same-name entities this call did NOT merge with, one message each. A
+     *  same-name match is a CANDIDATE, not a merge. */
+    ambiguities?: string[];
+    /** Elements whose support ledger hit `MAX_CLAIMS` on this call, so their
+     *  oldest provenance was dropped. Never silent. */
+    provenanceTruncated?: number;
+}
+/** cognee DataPoint normalization: lowercase, spaces→_, strip apostrophes. */
+export declare function normalizeName(name: string): string;
+/** Edge identity: the endpoint IDs (already collision-free) plus the relation,
+ *  hashed injectively so a relation containing the old `|` separator can no
+ *  longer forge a different edge's key. */
+export declare function edgeKey(srcKey: string, relation: string, dstKey: string): string;
+/** The pre-`KG_ID_VERSION` edge key, for the same in-place adoption as
+ *  `legacyNodeKey`. Composed from the RESOLVED endpoint keys, so it names the
+ *  legacy edge exactly when both endpoints are themselves legacy rows. */
+export declare function legacyEdgeKey(srcKey: string, relation: string, dstKey: string): string;
+/** Rule identity: the full rule text. The old key truncated the normalized rule
+ *  at 120 characters, so two rules sharing a long preamble were one rule. */
+export declare function ruleKey(rule: string): string;
+export declare function legacyRuleKey(rule: string): string;
+/** Who owns a set of graph facts. `org` absent = project-shared knowledge. */
+export interface KgScope {
+    org?: string;
+}
+export interface KgNamespaces {
+    nodes: string;
+    edges: string;
+    rules: string;
+    /** Name → entity index backing `resolveEntity`. Holds no claims. */
+    names: string;
+    /** Derived adjacency index: entity id -> edge keys touching it (K7). Holds
+     *  no claims either — every entry is rebuildable from `edges`. */
+    adj: string;
+    /** Derived origin-support index: origin ref -> {ns,key} refs it supports,
+     *  across nodes/edges/rules (K7). Rebuildable from all three. */
+    originIdx: string;
+    /** This scope's derived-index build/readiness state (K7). One row. */
+    indexStatus: string;
+}
+/** The namespaces a scope owns. Every read and write in this module resolves
+ *  through here, which is what makes ownership enforced rather than advisory:
+ *  there is no code path that reaches an org's facts without naming that org,
+ *  and none that reaches every org at once. */
+export declare function kgNamespaces(scope?: KgScope): KgNamespaces;
+/** Stamp the asserting org onto a provenance ref, so a claim's origin says WHO
+ *  asserted it and not merely which run id — `run:m4x2` alone is ambiguous
+ *  across orgs, and a promoted claim in the shared graph would otherwise carry
+ *  an origin no one owns.
+ *
+ *  Applied by the ingest/rollback entry points rather than by callers: a
+ *  caller that forgets is exactly how ownership stopped being enforced. */
+export declare function kgQualifyOrigin(originRef: string, scope?: KgScope): string;
+//# sourceMappingURL=memory-kg-model.d.ts.map

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

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