@batalabs/virlow-mcp-core 3.83.0 → 3.84.1

package/dist/cjs/memories.js

@@ -6,6 +6,7 @@ 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 entity_registry_js_1 = require("./entity-registry.js");
 const memory_graph_js_1 = require("./memory-graph.js");
 const memory_secrets_js_1 = require("./memory-secrets.js");
 /**
@@ -52,6 +53,12 @@ class MemoryStore {
     embeddings = null;
     embeddingsLoaded = false;
     syncInFlight = null;
+    /** The entity registry as last read, and the note(s) holding it, oldest
+     *  first. `registrySupported` is false when the API refused the note type
+     *  (an API older than the registry): kinds are then only guessed. */
+    registry = null;
+    registryRows = [];
+    registrySupported = null;
     mutationChain = Promise.resolve();
     /** Bumped every time clear() runs (i.e. every lock). Operations capture it
      * at the top and re-check before every cache write, so anything still
@@ -67,6 +74,9 @@ class MemoryStore {
     }
     clear() {
         this.cache.clear();
+        this.registry = null;
+        this.registryRows = [];
+        this.registrySupported = null;
         this.tree = null;
         this.embeddings = null;
         this.embeddingsLoaded = false;
@@ -115,6 +125,9 @@ class MemoryStore {
                     // Hidden notes are segregated in the app; they are not memories.
                     if (row.hidden === true)
                         continue;
+                    // The entity registry lives in the root but is not a memory.
+                    if (row.type === entity_registry_js_1.ENTITY_REGISTRY_NOTE_TYPE)
+                        continue;
                     seen.add(row.id);
                     const existing = this.cache.get(row.id);
                     if (existing && existing.updatedAt === row.updatedAt) {
@@ -173,8 +186,171 @@ class MemoryStore {
             }
             await embeddings.save(key);
         }
+        await this.refreshRegistry(key, tree.rootId, startEpoch);
         return result;
     }
+    /** Re-reads the entity registry. A failure other than "this API does not
+     *  know the type" keeps what was read before: kinds are a nicety, and a
+     *  registry hiccup must never fail a recall. */
+    async refreshRegistry(key, rootId, startEpoch) {
+        try {
+            const fresh = await this.fetchRegistry(key, rootId);
+            if (this.epoch !== startEpoch)
+                return;
+            this.registry = fresh.registry;
+            this.registryRows = fresh.rows;
+            this.registrySupported = fresh.supported;
+        }
+        catch {
+            // Keep the previous registry.
+        }
+    }
+    async fetchRegistry(key, rootId) {
+        let rows;
+        try {
+            const res = await this.api.listNotes({
+                folderId: rootId,
+                type: entity_registry_js_1.ENTITY_REGISTRY_NOTE_TYPE,
+                deleted: false,
+                limit: exports.SYNC_PAGE_LIMIT,
+            });
+            // Filtered here too: an API that ignored the type filter would hand
+            // back every memory in the root.
+            rows = res.notes.filter((r) => r.type === entity_registry_js_1.ENTITY_REGISTRY_NOTE_TYPE && r.deleted !== true);
+        }
+        catch (err) {
+            // An API that predates the registry rejects the type in its query
+            // schema. Degrade to guessed kinds.
+            if (err instanceof api_js_1.ApiError && err.status === 400) {
+                return { registry: (0, entity_registry_js_1.emptyRegistry)(), rows: [], supported: false };
+            }
+            throw err;
+        }
+        // Two devices that each created the registry at once leave two notes;
+        // they are read as one, and the next save folds them into the oldest.
+        rows.sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+        let registry = (0, entity_registry_js_1.emptyRegistry)();
+        for (const row of rows) {
+            const { content } = await this.decryptRow(key, row);
+            registry = (0, entity_registry_js_1.mergeRegistries)(registry, (0, entity_registry_js_1.parseRegistry)(content));
+        }
+        return { registry, rows, supported: true };
+    }
+    /** Whether this API stores entity kinds (false: an API older than the
+     *  registry), and the registry as last read. Requires a prior sync. */
+    registryState() {
+        return { supported: this.registrySupported !== false, registry: this.registry ?? (0, entity_registry_js_1.emptyRegistry)() };
+    }
+    /**
+     * Describe entities in the registry: kind, aliases, note. Read, change,
+     * save with expectedUpdatedAt; on a 409 (another device saved first) read
+     * again and re-apply, so per-key changes from both survive. With
+     * `onlyIfUntyped`, a kind is set only where none is stored: how add_memory
+     * records the kinds an AI names without overruling the person's choice.
+     *
+     * `unsupported` when the API does not accept the registry note type yet;
+     * nothing is saved then and kinds stay guesses.
+     */
+    describeEntities(patches, opts = {}) {
+        return this.enqueue(async () => {
+            await this.sync();
+            const key = this.requireSession();
+            const startEpoch = this.epoch;
+            const tree = await this.requireTree();
+            if (this.registrySupported === false)
+                return { changed: [], unsupported: true };
+            for (const patch of patches) {
+                (0, memory_secrets_js_1.assertNoSecret)(patch.name, patch.note ?? '', ...(patch.aliases ?? []));
+            }
+            for (let attempt = 0; attempt < 4; attempt++) {
+                const fresh = attempt === 0 && this.registry && this.registrySupported
+                    ? { registry: this.registry, rows: this.registryRows, supported: true }
+                    : await this.fetchRegistry(key, tree.rootId);
+                if (!fresh.supported) {
+                    if (this.epoch === startEpoch)
+                        this.registrySupported = false;
+                    return { changed: [], unsupported: true };
+                }
+                if (!(0, entity_registry_js_1.canWriteRegistry)(fresh.registry)) {
+                    throw new Error('The entity registry was saved by a newer version of Virlow. Update this connector to change it.');
+                }
+                const now = new Date().toISOString();
+                let next = fresh.registry;
+                const changed = [];
+                for (const patch of patches) {
+                    const existing = next.entities[(0, entity_registry_js_1.registryKeyFor)(next, patch.name)];
+                    const effective = opts.onlyIfUntyped && existing?.kind ? { ...patch, kind: undefined } : patch;
+                    const after = (0, entity_registry_js_1.describeInRegistry)(next, effective, now);
+                    if (after !== next)
+                        changed.push(patch.name);
+                    next = after;
+                }
+                if (changed.length === 0)
+                    return { changed, unsupported: false };
+                const { encryptedTitle, encryptedContent, iv } = await (0, virlow_crypto_1.encryptNoteFields)(key, entity_registry_js_1.ENTITY_REGISTRY_TITLE, (0, entity_registry_js_1.serializeRegistry)(next));
+                const write = {
+                    title: '[ENCRYPTED]',
+                    content: '[ENCRYPTED]',
+                    encryptedTitle,
+                    encryptedContent,
+                    iv,
+                    salt: (0, virlow_crypto_1.bytesToBase64)(crypto.getRandomValues(new Uint8Array(32))),
+                    type: entity_registry_js_1.ENTITY_REGISTRY_NOTE_TYPE,
+                };
+                const [primary, ...extra] = fresh.rows;
+                let row;
+                try {
+                    row = primary
+                        ? await this.api.updateNote(primary.id, { ...write, expectedUpdatedAt: primary.updatedAt })
+                        : await this.api.createNote({ ...write, folderId: tree.rootId });
+                }
+                catch (err) {
+                    if (err instanceof api_js_1.ApiError && err.status === 409)
+                        continue;
+                    if (err instanceof api_js_1.ApiError && err.status === 400 && !primary) {
+                        if (this.epoch === startEpoch)
+                            this.registrySupported = false;
+                        return { changed: [], unsupported: true };
+                    }
+                    throw err;
+                }
+                // Their entries are in `next` now; trash the duplicates so the
+                // registry is one note again. Best effort: a leftover is merged on
+                // the next read anyway.
+                for (const dup of extra) {
+                    await this.api.updateNote(dup.id, { deleted: true }).catch(() => undefined);
+                }
+                if (this.epoch === startEpoch) {
+                    this.registry = next;
+                    this.registryRows = [row];
+                    this.registrySupported = true;
+                }
+                return { changed, unsupported: false };
+            }
+            throw new Error('The entity registry kept changing while saving. Try again.');
+        });
+    }
+    /**
+     * Names nothing types yet, most known first, each with a few of the
+     * memories that name it and a suggested kind when one signal points one
+     * way: what an AI needs to propose kinds, and then call describe_entity.
+     */
+    async untyped(namespace, limit = 25) {
+        await this.sync();
+        this.requireSession();
+        const graph = this.graph(namespace);
+        const all = (0, memory_graph_js_1.untypedEntities)(graph);
+        const entities = all.slice(0, limit).map((entity) => {
+            const memories = [...entity.memoryIds]
+                .map((id) => this.cache.get(id))
+                .filter((m) => m !== undefined)
+                .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+                .slice(0, 3)
+                .map((m) => ({ id: m.id, label: m.label, text: m.text }));
+            return { name: entity.name, facts: entity.memoryIds.size, memories, suggestion: (0, memory_graph_js_1.suggestKind)(graph, entity.name) };
+        });
+        return { total: all.length, entities, supported: this.registrySupported !== false };
+    }
     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}`));
@@ -308,7 +484,7 @@ class MemoryStore {
     /** 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));
+        return (0, memory_graph_js_1.buildGraph)([...this.cache.values()].filter((m) => namespace === undefined || m.namespace === namespace || m.namespace === undefined), (0, entity_registry_js_1.describedEntities)(this.registry));
     }
     /** New names spelled the way existing memories already spell them, and
      *  predicates in snake_case, so one entity does not split in two. */
@@ -364,16 +540,22 @@ class MemoryStore {
         await this.sync();
         this.requireSession();
         const graph = this.graph(namespace);
-        const entity = graph.entities.get((0, memory_graph_js_1.entityKey)(name));
+        const entity = (0, memory_graph_js_1.findEntity)(graph, name);
         if (!entity)
             return null;
         const now = Date.now();
+        const described = graph.described.get(entity.key);
         const memories = [...entity.memoryIds]
             .map((id) => this.cache.get(id))
             .filter(Boolean)
             .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
         return {
             name: entity.name,
+            kind: (0, memory_graph_js_1.entityKinds)(graph).get(entity.key) ?? 'other',
+            /** Whether the kind is stored (set by a person or an AI) or guessed. */
+            kindStored: described?.kind !== undefined,
+            aliases: described?.aliases ?? [],
+            note: described?.note,
             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 })),
@@ -443,10 +625,16 @@ class MemoryStore {
         this.requireSession();
         const now = Date.now();
         const graph = this.graph(namespace);
+        const kinds = (0, memory_graph_js_1.entityKinds)(graph);
         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 }));
+            .map((e) => ({
+            name: e.name,
+            facts: e.memoryIds.size,
+            kind: kinds.get(e.key) ?? 'other',
+            ...(graph.described.get(e.key)?.note !== undefined && { note: graph.described.get(e.key).note }),
+        }));
         const facts = this.list(namespace)
             .filter((m) => (0, memory_graph_js_1.memoryHeldAt)(m, now))
             .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))

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

@@ -38,7 +38,37 @@ export interface Entity {
 export interface MemoryGraph {
     entities: Map<string, Entity>;
     edges: Edge[];
+    /** Alias key to the key of the entity it is another name for, from the
+     *  entity registry. Empty when there is no registry. */
+    aliases: Map<string, string>;
+    /** What the registry says about each entity, by entity key: a kind the
+     *  person or an AI set, aliases and a note. Empty when there is none. */
+    described: Map<string, DescribedEntity>;
 }
+/**
+ * The part of an entity registry entry the graph reads. The registry itself
+ * (an encrypted note beside the memories) is `entity-registry.ts`; the graph
+ * takes this narrow shape so it stays pure and has no format to know.
+ */
+export interface DescribedEntity {
+    /** Display spelling, when one was given. */
+    name?: string;
+    kind?: EntityKind;
+    aliases?: string[];
+    note?: string;
+}
+/** The key an entity is filed under in `graph`: its own key, or, when the
+ *  registry names it as an alias, the key of the entity it is an alias of. */
+export declare function keyOf(graph: Pick<MemoryGraph, 'aliases'>, name: string): string;
+/** The entity a name refers to, through aliases. */
+export declare function findEntity(graph: MemoryGraph, name: string): Entity | undefined;
+/**
+ * Alias keys from registry entries. One level only: an alias names the entry
+ * it sits on, never a chain. When two entries claim one alias, the first by
+ * key wins, so every client resolves it the same way. An alias that is the
+ * entry's own key is ignored.
+ */
+export declare function aliasMap(described: Map<string, DescribedEntity>): Map<string, string>;
 /** 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;
@@ -65,7 +95,13 @@ export declare function heldAt(from: string | undefined, to: string | undefined,
  * 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 and edges from memories. With `described` (the entity registry,
+ * by entity key), names the registry lists as aliases fold into the entity
+ * they are aliases of, and the registry's display name, kind and note ride
+ * along. The memories themselves are never rewritten for this.
+ */
+export declare function buildGraph(memories: Iterable<GraphMemory>, described?: Map<string, DescribedEntity>): 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[];
@@ -94,8 +130,8 @@ export declare function rankMemories(graph: MemoryGraph, query: string, scored:
 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.
+ * that look like one entity spelled two ways, single-valued predicates
+ * holding two values at once, and names with no kind.
  */
 export declare function graphHealth(graph: MemoryGraph, memories: GraphMemory[], at?: number): {
     unlinked: string[];
@@ -105,6 +141,7 @@ export declare function graphHealth(graph: MemoryGraph, memories: GraphMemory[],
         predicate: string;
         objects: string[];
     }[];
+    untyped: string[];
 };
 /**
  * A memory's links with one name swapped for another: how "Dana" becomes
@@ -119,10 +156,55 @@ export declare function renameEntityInMeta(meta: MemoryMeta, from: string, into:
  * Null when the memory does not link it.
  */
 export declare function unlinkEntityFromMeta(meta: MemoryMeta, name: string): MemoryMeta | null;
-export type EntityKind = 'person' | 'project' | 'tool' | 'place' | 'organisation' | 'other';
 /**
- * A best guess at what each entity is, from the roles it plays in its
- * relations; "other" when nothing says. A guess for filtering and colour,
- * never written back.
+ * What an entity is. `organization` was spelled `organisation` before the
+ * registry existed; readers accept both (see normalizeKind) and writers use
+ * this spelling. `other` is the fallback when nothing says.
+ */
+export declare const ENTITY_KINDS: readonly ["person", "organization", "project", "tool", "place", "event", "topic", "product", "media", "pet", "group", "goal", "other"];
+export type EntityKind = (typeof ENTITY_KINDS)[number];
+/** A kind as stored or typed, as one of ENTITY_KINDS; undefined when it is
+ *  not one. Case and a plural "s" do not matter; `organisation` reads as
+ *  `organization`. */
+export declare function normalizeKind(value: unknown): EntityKind | undefined;
+/**
+ * What each end of a predicate usually is. "Dana works_at Acme" says Dana
+ * is a person and Acme an organization; "Atlas uses Postgres" says Atlas is
+ * a project and Postgres a tool. Unknown predicates say nothing.
+ */
+export declare const ROLES: Record<string, [EntityKind | null, EntityKind | null]>;
+/**
+ * What each entity is. A kind stored in the entity registry (set by the
+ * person or by an AI with describe_entity or add_memory) wins; otherwise a
+ * best guess from the roles the entity plays in its relations; "other" when
+ * nothing says. The guess is never written back.
  */
 export declare function entityKinds(graph: MemoryGraph): Map<string, EntityKind>;
+/** The kind the registry stores for an entity, if any. */
+export declare function storedKind(graph: MemoryGraph, name: string): EntityKind | undefined;
+/**
+ * Entities nothing types: no kind in the registry and no relation role to
+ * guess one from. These are what a review asks the person (or an AI) to
+ * sort out. Most known first.
+ */
+export declare function untypedEntities(graph: MemoryGraph): Entity[];
+export interface KindSuggestion {
+    kind: EntityKind;
+    /** Why, in a few words a person can check: "works at in 2 memories". */
+    reason: string;
+}
+/**
+ * A suggested kind for an untyped entity, from signals on this device only
+ * (memory content is end-to-end encrypted, so no server can suggest
+ * anything). Only signals that point one way:
+ * - relation roles (ROLES), when the entity plays one;
+ * - how typed entities are used: if every typed subject (or object) of a
+ *   predicate is one kind, an untyped one in the same place is that kind
+ *   too ("Dana mentors Sam", with Dana a person, makes Lee in "Lee mentors
+ *   Kim" a person), with at least two typed examples;
+ * - the name: a company suffix (Inc, LLC, Ltd, GmbH...) is an organization,
+ *   and a single name that is the first name of exactly one typed person
+ *   ("Dana" beside the person "Dana Whitfield") is a person.
+ * Null when nothing points one way; a wrong guess costs more than none.
+ */
+export declare function suggestKind(graph: MemoryGraph, name: string): KindSuggestion | null;