@batalabs/virlow-mcp-core 3.19.0 → 3.68.0

package/dist/cjs/memories.d.ts

@@ -2,6 +2,8 @@ import { type Embedder } from '@batalabs/virlow-memory';
 import { type VirlowApi } from './api.js';
 import type { EmbeddingCacheLike } from './embedding-cache.js';
 import { type MemoryMeta } from './memory-note.js';
+import { type MemoryGraph } from './memory-graph.js';
+import type { MemoryRelation } from './memory-note.js';
 import type { Vault } from './vault.js';
 /**
  * Page size for the sync walk over each memory folder.
@@ -33,6 +35,13 @@ export interface SimilarMemory {
     text: string;
     similarity: number;
 }
+/** A fact the new memory ended: it said something single-valued (who leads
+ *  a project, where someone works) that the new one replaces. */
+export interface ClosedFact {
+    id: string;
+    label: string;
+    relation: MemoryRelation;
+}
 export type SyncResult = {
     added: number;
     updated: number;
@@ -66,10 +75,79 @@ export declare class MemoryStore {
         action: 'stored' | 'updated';
         id: string;
         similar: SimilarMemory[];
+        closed: ClosedFact[];
     }>;
-    search(query: string, namespace?: string, limit?: number): Promise<Array<Omit<CachedMemory, 'embedding' | 'folderId' | 'updatedAt'> & {
+    /**
+     * Ends the facts a new memory replaces. Each superseded relation gets a
+     * `to` date (the new fact's start); a memory whose relations have all
+     * ended gets `valid_to` and `superseded_by`. Nothing is deleted, so "who
+     * led Atlas before Sam?" stays answerable.
+     */
+    private closeSuperseded;
+    /** The graph over what is cached now. Cheap: rebuilt from the notes on
+     *  demand, never stored. */
+    graph(namespace?: string): MemoryGraph;
+    /** New names spelled the way existing memories already spell them, and
+     *  predicates in snake_case, so one entity does not split in two. */
+    private canonicalize;
+    /**
+     * Hybrid recall: similarity, then the graph (memories about an entity the
+     * query names, and one relation out from it) and recency. Current facts
+     * only, unless `includeHistory`, or as they stood on `asOf`.
+     */
+    search(query: string, namespace?: string, limit?: number, opts?: {
+        asOf?: string;
+        includeHistory?: boolean;
+    }): Promise<Array<Omit<CachedMemory, 'embedding' | 'folderId' | 'updatedAt'> & {
         similarity: number;
     }>>;
+    /** Everything known about one entity: its current and past relations and
+     *  the facts behind them. Null when no memory names it. */
+    recallEntity(name: string, namespace?: string): Promise<{
+        name: string;
+        current: CachedMemory[];
+        past: CachedMemory[];
+        relations: {
+            memoryId: string;
+            s: string;
+            p: string;
+            o: string;
+            from?: string;
+            to?: string;
+        }[];
+    } | null>;
+    /** Adds entities and relations to an existing memory: how a memory saved
+     *  before the graph existed gets linked. Also ends what it replaces. */
+    link(id: string, add: {
+        about?: string[];
+        relations?: MemoryRelation[];
+    }): Promise<ClosedFact[]>;
+    /** One entity spelled two ways becomes one: every memory naming `from`
+     *  is rewritten to name `into`. Returns how many memories changed. */
+    mergeEntities(from: string, into: string): Promise<number>;
+    /**
+     * What to load at the start of a session: the entities this namespace
+     * talks about most, and its most recent current facts, within `limit`
+     * facts. Global memories are included alongside a project's.
+     */
+    context(namespace?: string, limit?: number): Promise<{
+        entities: {
+            name: string;
+            facts: number;
+        }[];
+        facts: CachedMemory[];
+    }>;
+    /** Findings for a tidy pass: unlinked memories, likely duplicate names and
+     *  single-valued facts holding two values at once. */
+    health(namespace?: string): Promise<{
+        unlinked: string[];
+        possibleDuplicates: [string, string][];
+        contradictions: {
+            subject: string;
+            predicate: string;
+            objects: string[];
+        }[];
+    }>;
     /** Requires a prior sync() in the same unlock to have populated the cache. */
     list(namespace?: string): CachedMemory[];
     update(id: string, changes: {

package/dist/cjs/memories.js

@@ -6,6 +6,8 @@ const virlow_memory_1 = require("@batalabs/virlow-memory");
 const api_js_1 = require("./api.js");
 const memory_note_js_1 = require("./memory-note.js");
 const memory_tree_js_1 = require("./memory-tree.js");
+const memory_graph_js_1 = require("./memory-graph.js");
+const memory_secrets_js_1 = require("./memory-secrets.js");
 /**
  * Page size for the sync walk over each memory folder.
  *
@@ -20,6 +22,25 @@ const memory_tree_js_1 = require("./memory-tree.js");
  * lowering it only costs round trips.
  */
 exports.SYNC_PAGE_LIMIT = 50;
+/** Today as YYYY-MM-DD, the default start of a fact learned now. */
+function today() {
+    return new Date().toISOString().slice(0, 10);
+}
+/** Merge two relation lists, one entry per subject, predicate and object. */
+function unionRelations(a = [], b = []) {
+    const byKey = new Map();
+    for (const r of [...a, ...b]) {
+        byKey.set(`${(0, memory_graph_js_1.entityKey)(r.s)}|${(0, memory_graph_js_1.normalizePredicate)(r.p)}|${(0, memory_graph_js_1.entityKey)(r.o)}`, r);
+    }
+    return [...byKey.values()];
+}
+function unionNames(a = [], b = []) {
+    const byKey = new Map();
+    for (const n of [...a, ...b])
+        if (!byKey.has((0, memory_graph_js_1.entityKey)(n)))
+            byKey.set((0, memory_graph_js_1.entityKey)(n), n);
+    return [...byKey.values()];
+}
 const round3 = (n) => Math.round(n * 1000) / 1000;
 class MemoryStore {
     api;
@@ -156,17 +177,32 @@ class MemoryStore {
     }
     add(label, text, namespace, meta = {}) {
         return this.enqueue(async () => {
+            (0, memory_secrets_js_1.assertNoSecret)(label, text, ...(meta.relations ?? []).map((r) => `${r.s} ${r.p} ${r.o}`));
             await this.sync();
             const key = this.requireSession();
             const startEpoch = this.epoch;
+            meta = this.canonicalize(meta);
             const embedding = await this.embedder.embed(embeddingInput(label, text));
             const candidates = this.candidatesFor(namespace);
-            const hit = (0, virlow_memory_1.findDuplicate)(embedding, candidates);
+            // A near-identical sentence that changes a single-valued fact ("Sam
+            // leads Atlas" after "Dana leads Atlas") is not a restatement: merging
+            // would overwrite the old fact and lose its history. It is stored as a
+            // new memory, which then ends the old one.
+            const found = (0, virlow_memory_1.findDuplicate)(embedding, candidates);
+            const contradicts = found !== null &&
+                found !== undefined &&
+                (meta.relations ?? []).some((r) => (0, memory_graph_js_1.supersededBy)((0, memory_graph_js_1.buildGraph)([this.cache.get(found.id)]), r, Date.now()).length > 0);
+            const hit = contradicts ? null : found;
             if (hit) {
                 // Same memory said again: fold it into the existing note rather than
-                // accumulating near-identical copies. Its metadata carries forward.
+                // accumulating near-identical copies. Its metadata carries forward,
+                // and its entities and relations gain whatever the new one names.
                 const existing = this.cache.get(hit.id);
                 const merged = (0, memory_note_js_1.mergeMeta)(existing.meta, meta);
+                if (meta.about)
+                    merged.about = unionNames(existing.meta.about, meta.about);
+                if (meta.relations)
+                    merged.relations = unionRelations(existing.meta.relations, meta.relations);
                 const row = await this.writeNote(key, hit.id, label, text, merged);
                 if (this.epoch === startEpoch) {
                     this.cache.set(hit.id, {
@@ -180,7 +216,7 @@ class MemoryStore {
                     this.embeddings?.set(hit.id, row.updatedAt, embedding);
                     await this.saveEmbeddings(key, startEpoch);
                 }
-                return { action: 'updated', id: hit.id, similar: [] };
+                return { action: 'updated', id: hit.id, similar: [], closed: [] };
             }
             const tree = await this.requireTree();
             const folderId = namespace !== undefined
@@ -191,6 +227,8 @@ class MemoryStore {
                 source: meta.source ?? 'virlow-mcp',
                 created: meta.created ?? new Date().toISOString(),
             };
+            // The graph as it stood before this memory, to find what it replaces.
+            const before = this.graph();
             const row = await this.writeNote(key, null, label, text, stamped, folderId);
             if (this.epoch === startEpoch) {
                 this.cache.set(row.id, {
@@ -216,26 +254,221 @@ class MemoryStore {
                     similarity: round3(similarity),
                 };
             });
-            return { action: 'stored', id: row.id, similar };
+            const closed = await this.closeSuperseded(key, startEpoch, before, row.id, stamped);
+            return { action: 'stored', id: row.id, similar, closed };
         });
     }
-    async search(query, namespace, limit = 10) {
+    /**
+     * Ends the facts a new memory replaces. Each superseded relation gets a
+     * `to` date (the new fact's start); a memory whose relations have all
+     * ended gets `valid_to` and `superseded_by`. Nothing is deleted, so "who
+     * led Atlas before Sam?" stays answerable.
+     */
+    async closeSuperseded(key, startEpoch, graph, newId, meta) {
+        const closed = [];
+        const byMemory = new Map();
+        for (const relation of meta.relations ?? []) {
+            const start = relation.from ?? meta.validFrom ?? today();
+            const at = Date.parse(start.length === 10 ? `${start}T00:00:00Z` : start);
+            for (const edge of (0, memory_graph_js_1.supersededBy)(graph, relation, Number.isNaN(at) ? Date.now() : at)) {
+                if (edge.memoryId === newId)
+                    continue;
+                const list = byMemory.get(edge.memoryId) ?? [];
+                list.push({ s: edge.s, p: edge.p, o: edge.o, ...(edge.from && { from: edge.from }), to: start });
+                byMemory.set(edge.memoryId, list);
+            }
+        }
+        for (const [memoryId, ended] of byMemory) {
+            const memory = this.cache.get(memoryId);
+            if (!memory)
+                continue;
+            const relations = (memory.meta.relations ?? []).map((r) => {
+                const hit = ended.find((e) => (0, memory_graph_js_1.entityKey)(e.s) === (0, memory_graph_js_1.entityKey)(r.s) &&
+                    (0, memory_graph_js_1.normalizePredicate)(e.p) === (0, memory_graph_js_1.normalizePredicate)(r.p) &&
+                    (0, memory_graph_js_1.entityKey)(e.o) === (0, memory_graph_js_1.entityKey)(r.o));
+                return hit ? { ...r, to: hit.to } : r;
+            });
+            const next = { ...memory.meta, relations };
+            if (relations.every((r) => r.to)) {
+                next.validTo = ended[0].to;
+                next.supersededBy = newId;
+            }
+            const row = await this.writeNote(key, memoryId, memory.label, memory.text, next);
+            if (this.epoch === startEpoch) {
+                this.cache.set(memoryId, { ...memory, meta: next, updatedAt: row.updatedAt });
+                this.embeddings?.set(memoryId, row.updatedAt, memory.embedding);
+            }
+            for (const relation of ended)
+                closed.push({ id: memoryId, label: memory.label, relation });
+        }
+        if (closed.length > 0)
+            await this.saveEmbeddings(key, startEpoch);
+        return closed;
+    }
+    /** The graph over what is cached now. Cheap: rebuilt from the notes on
+     *  demand, never stored. */
+    graph(namespace) {
+        return (0, memory_graph_js_1.buildGraph)([...this.cache.values()].filter((m) => namespace === undefined || m.namespace === namespace || m.namespace === undefined));
+    }
+    /** New names spelled the way existing memories already spell them, and
+     *  predicates in snake_case, so one entity does not split in two. */
+    canonicalize(meta) {
+        if (!meta.about && !meta.relations)
+            return meta;
+        const graph = this.graph();
+        const name = (n) => graph.entities.get((0, memory_graph_js_1.entityKey)(n))?.name ?? n.trim();
+        const next = { ...meta };
+        if (meta.about)
+            next.about = unionNames([], meta.about.map(name));
+        if (meta.relations) {
+            next.relations = meta.relations.map((r) => ({
+                ...r,
+                s: name(r.s),
+                p: (0, memory_graph_js_1.normalizePredicate)(r.p),
+                o: graph.entities.has((0, memory_graph_js_1.entityKey)(r.o)) ? name(r.o) : r.o.trim(),
+            }));
+            // Everything a relation names is also what the memory is about.
+            next.about = unionNames(next.about, next.relations.flatMap((r) => [r.s, ...(graph.entities.has((0, memory_graph_js_1.entityKey)(r.o)) || /^[A-Z0-9]/.test(r.o) ? [r.o] : [])]));
+        }
+        return next;
+    }
+    /**
+     * Hybrid recall: similarity, then the graph (memories about an entity the
+     * query names, and one relation out from it) and recency. Current facts
+     * only, unless `includeHistory`, or as they stood on `asOf`.
+     */
+    async search(query, namespace, limit = 10, opts = {}) {
         await this.sync();
         this.requireSession();
         const embedding = await this.embedder.embed(query);
-        const ranked = (0, virlow_memory_1.rankBySimilarity)(embedding, this.candidatesFor(namespace), limit);
-        return ranked.map(({ id, similarity }) => {
-            const memory = this.cache.get(id);
-            return {
-                id,
-                label: memory.label,
-                text: memory.text,
-                meta: memory.meta,
-                ...namespaceField(memory.namespace),
-                similarity: round3(similarity),
+        const candidates = this.candidatesFor(namespace);
+        const scored = (0, virlow_memory_1.rankBySimilarity)(embedding, candidates, candidates.length).map(({ id, similarity }) => ({ memory: this.cache.get(id), similarity }));
+        const at = opts.asOf ? Date.parse(opts.asOf.length === 10 ? `${opts.asOf}T23:59:59Z` : opts.asOf) : undefined;
+        const ranked = (0, memory_graph_js_1.rankMemories)(this.graph(namespace), query, scored, {
+            ...(at !== undefined && !Number.isNaN(at) && { at }),
+            includeHistory: opts.includeHistory === true,
+            limit,
+        });
+        return ranked.map(({ memory, similarity }) => ({
+            id: memory.id,
+            label: memory.label,
+            text: memory.text,
+            meta: memory.meta,
+            ...namespaceField(memory.namespace),
+            similarity: round3(similarity),
+        }));
+    }
+    /** Everything known about one entity: its current and past relations and
+     *  the facts behind them. Null when no memory names it. */
+    async recallEntity(name, namespace) {
+        await this.sync();
+        this.requireSession();
+        const graph = this.graph(namespace);
+        const entity = graph.entities.get((0, memory_graph_js_1.entityKey)(name));
+        if (!entity)
+            return null;
+        const now = Date.now();
+        const memories = [...entity.memoryIds]
+            .map((id) => this.cache.get(id))
+            .filter(Boolean)
+            .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        return {
+            name: entity.name,
+            current: memories.filter((m) => (0, memory_graph_js_1.memoryHeldAt)(m, now)),
+            past: memories.filter((m) => !(0, memory_graph_js_1.memoryHeldAt)(m, now)),
+            relations: entity.edges.map((e) => ({ ...e })),
+        };
+    }
+    /** Adds entities and relations to an existing memory: how a memory saved
+     *  before the graph existed gets linked. Also ends what it replaces. */
+    link(id, add) {
+        return this.enqueue(async () => {
+            await this.sync();
+            const key = this.requireSession();
+            const startEpoch = this.epoch;
+            const existing = this.cache.get(id);
+            if (!existing)
+                throw new Error(`Memory ${id} not found`);
+            (0, memory_secrets_js_1.assertNoSecret)(...(add.relations ?? []).map((r) => `${r.s} ${r.p} ${r.o}`));
+            const before = this.graph();
+            const extra = this.canonicalize({
+                ...(add.about && { about: add.about }),
+                ...(add.relations && { relations: add.relations }),
+            });
+            const meta = {
+                ...existing.meta,
+                about: unionNames(existing.meta.about, extra.about),
+                relations: unionRelations(existing.meta.relations, extra.relations),
             };
+            const row = await this.writeNote(key, id, existing.label, existing.text, meta);
+            if (this.epoch === startEpoch) {
+                this.cache.set(id, { ...existing, meta, updatedAt: row.updatedAt });
+                this.embeddings?.set(id, row.updatedAt, existing.embedding);
+                await this.saveEmbeddings(key, startEpoch);
+            }
+            return this.closeSuperseded(key, startEpoch, before, id, { relations: extra.relations ?? [] });
+        });
+    }
+    /** One entity spelled two ways becomes one: every memory naming `from`
+     *  is rewritten to name `into`. Returns how many memories changed. */
+    mergeEntities(from, into) {
+        return this.enqueue(async () => {
+            await this.sync();
+            const key = this.requireSession();
+            const startEpoch = this.epoch;
+            const fromKey = (0, memory_graph_js_1.entityKey)(from);
+            const swap = (n) => ((0, memory_graph_js_1.entityKey)(n) === fromKey ? into.trim() : n);
+            let changed = 0;
+            for (const memory of [...this.cache.values()]) {
+                const names = [...(memory.meta.about ?? []), ...(memory.meta.relations ?? []).flatMap((r) => [r.s, r.o])];
+                if (!names.some((n) => (0, memory_graph_js_1.entityKey)(n) === fromKey))
+                    continue;
+                const meta = { ...memory.meta };
+                if (memory.meta.about)
+                    meta.about = unionNames([], memory.meta.about.map(swap));
+                if (memory.meta.relations) {
+                    meta.relations = unionRelations([], memory.meta.relations.map((r) => ({ ...r, s: swap(r.s), o: swap(r.o) })));
+                }
+                const row = await this.writeNote(key, memory.id, memory.label, memory.text, meta);
+                if (this.epoch === startEpoch) {
+                    this.cache.set(memory.id, { ...memory, meta, updatedAt: row.updatedAt });
+                    this.embeddings?.set(memory.id, row.updatedAt, memory.embedding);
+                }
+                changed++;
+            }
+            if (changed > 0)
+                await this.saveEmbeddings(key, startEpoch);
+            return changed;
         });
     }
+    /**
+     * What to load at the start of a session: the entities this namespace
+     * talks about most, and its most recent current facts, within `limit`
+     * facts. Global memories are included alongside a project's.
+     */
+    async context(namespace, limit = 12) {
+        await this.sync();
+        this.requireSession();
+        const now = Date.now();
+        const graph = this.graph(namespace);
+        const entities = [...graph.entities.values()]
+            .sort((a, b) => b.memoryIds.size - a.memoryIds.size)
+            .slice(0, 8)
+            .map((e) => ({ name: e.name, facts: e.memoryIds.size }));
+        const facts = this.list(namespace)
+            .filter((m) => (0, memory_graph_js_1.memoryHeldAt)(m, now))
+            .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+            .slice(0, limit);
+        return { entities, facts };
+    }
+    /** Findings for a tidy pass: unlinked memories, likely duplicate names and
+     *  single-valued facts holding two values at once. */
+    async health(namespace) {
+        await this.sync();
+        this.requireSession();
+        const memories = this.list(namespace);
+        return (0, memory_graph_js_1.graphHealth)(this.graph(namespace), memories);
+    }
     /** Requires a prior sync() in the same unlock to have populated the cache. */
     list(namespace) {
         this.requireSession();
@@ -255,6 +488,7 @@ class MemoryStore {
                 throw new Error(`Memory ${id} not found`);
             const label = changes.label ?? existing.label;
             const text = changes.text ?? existing.text;
+            (0, memory_secrets_js_1.assertNoSecret)(label, text);
             const meta = (0, memory_note_js_1.mergeMeta)(existing.meta, changes.meta ?? {});
             const row = await this.writeNote(key, id, label, text, meta);
             const embedding = await this.embedder.embed(embeddingInput(label, text));

package/dist/cjs/memory-graph.d.ts

@@ -0,0 +1,105 @@
+import type { MemoryMeta, MemoryRelation } from './memory-note.js';
+/**
+ * The memory graph, built from memories rather than stored beside them.
+ *
+ * A memory's frontmatter names the entities it is about (`about`) and the
+ * relations it asserts (`relations`). This module turns a set of memories
+ * into entities and edges, answers "is this still true" for a date, and
+ * ranks recall with the graph and recency as well as similarity. Pure: no
+ * network, no crypto, so every rule here is tested directly.
+ *
+ * Entities are names. Two mentions are the same entity when their names
+ * match ignoring case, spacing and a leading "the"; anything looser (Dana
+ * and Dana Whitfield) is a merge the AI or the person asks for, never a
+ * guess. See docs/memory-graph.md.
+ */
+export interface GraphMemory {
+    id: string;
+    label: string;
+    text: string;
+    meta: MemoryMeta;
+    namespace?: string;
+    updatedAt: string;
+}
+export interface Edge extends MemoryRelation {
+    /** The memory that asserted it. */
+    memoryId: string;
+}
+export interface Entity {
+    key: string;
+    /** The spelling most memories use. */
+    name: string;
+    memoryIds: Set<string>;
+    edges: Edge[];
+}
+export interface MemoryGraph {
+    entities: Map<string, Entity>;
+    edges: Edge[];
+}
+/** The matching key for a name: case, spacing and a leading article do not
+ *  make a different entity. */
+export declare function entityKey(name: string): string;
+/**
+ * Predicates where one side holds one value at a time, so a new fact ends
+ * the old one. Which side matters:
+ * - one object per subject: a person works at one place, reports to one
+ *   manager (Dana works_at Acme, then Dana works_at Initech);
+ * - one subject per object: a project has one lead (Dana leads Atlas, then
+ *   Sam leads Atlas).
+ * Anything else accumulates (prefers, uses, knows).
+ */
+export declare const ONE_OBJECT_PER_SUBJECT: Set<string>;
+export declare const ONE_SUBJECT_PER_OBJECT: Set<string>;
+/** Either kind: a predicate that holds one value at a time. */
+export declare const SINGLE_VALUED: Set<string>;
+/** snake_case, so "Works at" and "works_at" are one predicate. */
+export declare function normalizePredicate(p: string): string;
+/** Whether a span held at `at`: started on or before it, ended after it. */
+export declare function heldAt(from: string | undefined, to: string | undefined, at: number): boolean;
+/**
+ * Whether a memory's fact held at `at`. It starts at `valid_from`, else the
+ * earliest date its relations give (a fact about "since January" learned
+ * today started in January), else when it was learned.
+ */
+export declare function memoryHeldAt(memory: GraphMemory, at: number): boolean;
+export declare function buildGraph(memories: Iterable<GraphMemory>): MemoryGraph;
+/** Entities named in a piece of text (a prompt, a query), longest names
+ *  first so "Dana Whitfield" wins over "Dana". Whole words only. */
+export declare function entitiesMentioned(graph: MemoryGraph, text: string): Entity[];
+/** Entities one relation away from any of `from`. */
+export declare function neighbours(graph: MemoryGraph, from: Entity[]): Entity[];
+export interface RankInput {
+    memory: GraphMemory;
+    similarity: number;
+}
+/** How much the graph and recency move a similarity score. Small on
+ *  purpose: similarity still decides, the graph breaks ties and pulls in
+ *  facts that share an entity with the query but none of its words. */
+export declare const DIRECT_BOOST = 0.15;
+export declare const NEIGHBOUR_BOOST = 0.07;
+export declare function rankMemories(graph: MemoryGraph, query: string, scored: RankInput[], opts: {
+    at?: number;
+    includeHistory?: boolean;
+    limit: number;
+}): Array<RankInput & {
+    score: number;
+}>;
+/**
+ * Current edges a new relation replaces: same subject and single-valued
+ * predicate, a different object, still holding when the new one starts.
+ */
+export declare function supersededBy(graph: MemoryGraph, relation: MemoryRelation, at: number): Edge[];
+/**
+ * Housekeeping findings for a tidy pass: memories linked to nothing, names
+ * that look like one entity spelled two ways, and single-valued predicates
+ * holding two values at once.
+ */
+export declare function graphHealth(graph: MemoryGraph, memories: GraphMemory[], at?: number): {
+    unlinked: string[];
+    possibleDuplicates: [string, string][];
+    contradictions: {
+        subject: string;
+        predicate: string;
+        objects: string[];
+    }[];
+};