@batalabs/virlow-mcp-core 3.11.5 → 3.11.6

package/dist/cjs/memories.d.ts

@@ -0,0 +1,85 @@
+import { type Embedder } from '@batalabs/virlow-memory';
+import { type VirlowApi } from './api.js';
+import type { EmbeddingCache } from './embedding-cache.js';
+import { type MemoryMeta } from './memory-note.js';
+import type { Vault } from './vault.js';
+export declare const SYNC_PAGE_LIMIT = 100;
+export interface CachedMemory {
+    id: string;
+    label: string;
+    text: string;
+    meta: MemoryMeta;
+    namespace?: string;
+    folderId: string;
+    embedding: Float32Array;
+    updatedAt: string;
+}
+export interface SimilarMemory {
+    id: string;
+    label: string;
+    text: string;
+    similarity: number;
+}
+export type SyncResult = {
+    added: number;
+    updated: number;
+    removed: number;
+    embedded: number;
+};
+export declare class MemoryStore {
+    private readonly api;
+    private readonly vault;
+    private readonly embedder;
+    private readonly cacheFactory;
+    private readonly cache;
+    private tree;
+    private embeddings;
+    private embeddingsLoaded;
+    private syncInFlight;
+    private mutationChain;
+    /** 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
+     * awaiting the network or a decrypt when the vault locked can never write
+     * decrypted plaintext back into a cache the user just emptied. */
+    private epoch;
+    constructor(api: VirlowApi, vault: Vault, embedder: Embedder, cacheFactory: (userId: string) => EmbeddingCache);
+    clear(): void;
+    get size(): number;
+    /** Concurrent callers share one in-flight sync so two overlapping tool
+     * calls never double up on network, decrypt, or embedding work. */
+    sync(): Promise<SyncResult>;
+    private doSync;
+    add(label: string, text: string, namespace?: string, meta?: MemoryMeta): Promise<{
+        action: 'stored' | 'updated';
+        id: string;
+        similar: SimilarMemory[];
+    }>;
+    search(query: string, namespace?: string, limit?: number): Promise<Array<Omit<CachedMemory, 'embedding' | 'folderId' | 'updatedAt'> & {
+        similarity: number;
+    }>>;
+    /** Requires a prior sync() in the same unlock to have populated the cache. */
+    list(namespace?: string): CachedMemory[];
+    update(id: string, changes: {
+        label?: string;
+        text?: string;
+        meta?: MemoryMeta;
+    }): Promise<void>;
+    /** Trashes the note — recoverable from the app's Trash, never hard-deleted. */
+    delete(id: string): Promise<void>;
+    /** Dedupe and search candidates: the named namespace plus the global root. */
+    private candidatesFor;
+    /** Create or update a memory note, encrypting through the note field
+     * helpers. `noteId === null` creates. */
+    private writeNote;
+    private decryptRow;
+    private requireTree;
+    private requireEmbeddings;
+    /** Persisting after a lock would write vectors the user just cleared. */
+    private saveEmbeddings;
+    private requireSession;
+    /** Serializes add/update/delete so two overlapping mutation tool calls never
+     * interleave — two concurrent near-duplicate adds must run their
+     * dedupe-check-then-write critical section one at a time, or both would miss
+     * the other's pending write and both create. */
+    private enqueue;
+}

package/dist/cjs/memories.js

@@ -0,0 +1,353 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryStore = exports.SYNC_PAGE_LIMIT = void 0;
+const virlow_crypto_1 = require("@batalabs/virlow-crypto");
+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");
+exports.SYNC_PAGE_LIMIT = 100;
+const round3 = (n) => Math.round(n * 1000) / 1000;
+class MemoryStore {
+    api;
+    vault;
+    embedder;
+    cacheFactory;
+    cache = new Map();
+    tree = null;
+    embeddings = null;
+    embeddingsLoaded = false;
+    syncInFlight = 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
+     * awaiting the network or a decrypt when the vault locked can never write
+     * decrypted plaintext back into a cache the user just emptied. */
+    epoch = 0;
+    constructor(api, vault, embedder, cacheFactory) {
+        this.api = api;
+        this.vault = vault;
+        this.embedder = embedder;
+        this.cacheFactory = cacheFactory;
+        this.vault.onLock = () => this.clear();
+    }
+    clear() {
+        this.cache.clear();
+        this.tree = null;
+        this.embeddings = null;
+        this.embeddingsLoaded = false;
+        this.epoch++;
+    }
+    get size() {
+        return this.cache.size;
+    }
+    /** Concurrent callers share one in-flight sync so two overlapping tool
+     * calls never double up on network, decrypt, or embedding work. */
+    sync() {
+        this.syncInFlight ??= this.doSync().finally(() => {
+            this.syncInFlight = null;
+        });
+        return this.syncInFlight;
+    }
+    async doSync() {
+        const key = this.requireSession();
+        const startEpoch = this.epoch;
+        const result = { added: 0, updated: 0, removed: 0, embedded: 0 };
+        const tree = await this.requireTree();
+        const embeddings = await this.requireEmbeddings(key);
+        const seen = new Set();
+        for (const folderId of tree.folderIds()) {
+            let page = 1;
+            for (;;) {
+                let batch;
+                try {
+                    batch = await this.api.listNotes({
+                        folderId,
+                        deleted: false,
+                        page,
+                        limit: exports.SYNC_PAGE_LIMIT,
+                    });
+                }
+                catch (err) {
+                    // The folder was deleted between resolving the tree and walking it.
+                    // Drop the stale tree so the next sync re-resolves, and move on.
+                    if (err instanceof api_js_1.ApiError && err.status === 404) {
+                        this.tree = null;
+                        break;
+                    }
+                    throw err;
+                }
+                for (const row of batch.notes) {
+                    // Hidden notes are segregated in the app; they are not memories.
+                    if (row.hidden === true)
+                        continue;
+                    seen.add(row.id);
+                    const existing = this.cache.get(row.id);
+                    if (existing && existing.updatedAt === row.updatedAt) {
+                        // Unchanged, but it may have been dragged to another subfolder.
+                        if (existing.folderId !== folderId) {
+                            const moved = {
+                                ...existing,
+                                folderId,
+                                ...namespaceField(tree.namespaceOf(folderId)),
+                            };
+                            if (this.epoch === startEpoch)
+                                this.cache.set(row.id, moved);
+                            result.updated++;
+                        }
+                        continue;
+                    }
+                    const { title, content } = await this.decryptRow(key, row);
+                    const { fact, meta } = (0, memory_note_js_1.parseMemoryNote)(content);
+                    let embedding = embeddings.get(row.id, row.updatedAt);
+                    if (!embedding) {
+                        embedding = await this.embedder.embed(embeddingInput(title, fact));
+                        result.embedded++;
+                    }
+                    if (this.epoch !== startEpoch)
+                        continue;
+                    embeddings.set(row.id, row.updatedAt, embedding);
+                    this.cache.set(row.id, {
+                        id: row.id,
+                        label: title,
+                        text: fact,
+                        meta,
+                        folderId,
+                        ...namespaceField(tree.namespaceOf(folderId)),
+                        embedding,
+                        updatedAt: row.updatedAt,
+                    });
+                    if (existing)
+                        result.updated++;
+                    else
+                        result.added++;
+                }
+                if (page >= batch.pagination.pages || batch.notes.length === 0)
+                    break;
+                page++;
+            }
+        }
+        // Anything no longer in the tree was trashed, hidden, or moved out of the
+        // memories folder: it stops being a memory.
+        if (this.epoch === startEpoch) {
+            for (const id of [...this.cache.keys()]) {
+                if (seen.has(id))
+                    continue;
+                this.cache.delete(id);
+                embeddings.delete(id);
+                result.removed++;
+            }
+            await embeddings.save(key);
+        }
+        return result;
+    }
+    add(label, text, namespace, meta = {}) {
+        return this.enqueue(async () => {
+            await this.sync();
+            const key = this.requireSession();
+            const startEpoch = this.epoch;
+            const embedding = await this.embedder.embed(embeddingInput(label, text));
+            const candidates = this.candidatesFor(namespace);
+            const hit = (0, virlow_memory_1.findDuplicate)(embedding, candidates);
+            if (hit) {
+                // Same memory said again: fold it into the existing note rather than
+                // accumulating near-identical copies. Its metadata carries forward.
+                const existing = this.cache.get(hit.id);
+                const merged = (0, memory_note_js_1.mergeMeta)(existing.meta, meta);
+                const row = await this.writeNote(key, hit.id, label, text, merged);
+                if (this.epoch === startEpoch) {
+                    this.cache.set(hit.id, {
+                        ...existing,
+                        label,
+                        text,
+                        meta: merged,
+                        embedding,
+                        updatedAt: row.updatedAt,
+                    });
+                    this.embeddings?.set(hit.id, row.updatedAt, embedding);
+                    await this.saveEmbeddings(key, startEpoch);
+                }
+                return { action: 'updated', id: hit.id, similar: [] };
+            }
+            const tree = await this.requireTree();
+            const folderId = namespace !== undefined
+                ? await (0, memory_tree_js_1.ensureNamespace)(this.api, tree, namespace)
+                : tree.rootId;
+            const stamped = {
+                ...meta,
+                source: meta.source ?? 'virlow-mcp',
+                created: meta.created ?? new Date().toISOString(),
+            };
+            const row = await this.writeNote(key, null, label, text, stamped, folderId);
+            if (this.epoch === startEpoch) {
+                this.cache.set(row.id, {
+                    id: row.id,
+                    label,
+                    text,
+                    meta: stamped,
+                    folderId,
+                    ...namespaceField(tree.namespaceOf(folderId)),
+                    embedding,
+                    updatedAt: row.updatedAt,
+                });
+                this.embeddings?.set(row.id, row.updatedAt, embedding);
+                await this.saveEmbeddings(key, startEpoch);
+            }
+            // Close enough to be worth mentioning, not close enough to merge.
+            const similar = (0, virlow_memory_1.findSimilar)(embedding, candidates).map(({ id, similarity }) => {
+                const memory = this.cache.get(id);
+                return {
+                    id,
+                    label: memory.label,
+                    text: memory.text,
+                    similarity: round3(similarity),
+                };
+            });
+            return { action: 'stored', id: row.id, similar };
+        });
+    }
+    async search(query, namespace, limit = 10) {
+        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),
+            };
+        });
+    }
+    /** Requires a prior sync() in the same unlock to have populated the cache. */
+    list(namespace) {
+        this.requireSession();
+        return [...this.cache.values()].filter((m) => namespace === undefined || m.namespace === namespace || m.namespace === undefined);
+    }
+    update(id, changes) {
+        return this.enqueue(async () => {
+            // Sync first: without it a cache miss (fresh unlock, or a memory this
+            // device never saw) would overwrite the server note with defaults and
+            // wipe its metadata. If the id is still missing afterwards it genuinely
+            // does not exist — never guess-write over it.
+            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`);
+            const label = changes.label ?? existing.label;
+            const text = changes.text ?? existing.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));
+            if (this.epoch !== startEpoch)
+                return;
+            this.cache.set(id, { ...existing, label, text, meta, embedding, updatedAt: row.updatedAt });
+            this.embeddings?.set(id, row.updatedAt, embedding);
+            await this.saveEmbeddings(key, startEpoch);
+        });
+    }
+    /** Trashes the note — recoverable from the app's Trash, never hard-deleted. */
+    delete(id) {
+        return this.enqueue(async () => {
+            const key = this.requireSession();
+            const startEpoch = this.epoch;
+            await this.api.updateNote(id, { deleted: true });
+            if (this.epoch !== startEpoch)
+                return;
+            this.cache.delete(id);
+            this.embeddings?.delete(id);
+            await this.saveEmbeddings(key, startEpoch);
+        });
+    }
+    /** Dedupe and search candidates: the named namespace plus the global root. */
+    candidatesFor(namespace) {
+        const result = [];
+        for (const memory of this.cache.values()) {
+            if (memory.namespace === namespace || memory.namespace === undefined) {
+                result.push({ id: memory.id, embedding: memory.embedding });
+            }
+        }
+        return result;
+    }
+    /** Create or update a memory note, encrypting through the note field
+     * helpers. `noteId === null` creates. */
+    async writeNote(key, noteId, label, text, meta, folderId) {
+        const body = (0, memory_note_js_1.toCodeEnvelope)((0, memory_note_js_1.serializeMemoryBody)(text, meta));
+        const salt = (0, virlow_crypto_1.bytesToBase64)(crypto.getRandomValues(new Uint8Array(32)));
+        const { encryptedTitle, encryptedContent, iv } = await (0, virlow_crypto_1.encryptNoteFields)(key, label, body);
+        const write = {
+            title: '[ENCRYPTED]',
+            content: '[ENCRYPTED]',
+            encryptedTitle,
+            encryptedContent,
+            iv,
+            salt,
+            type: 'code',
+            // Mirrored so the app can filter memories by tag. The frontmatter stays
+            // the source of truth; this column follows it on every write we make.
+            tags: meta.tags ?? [],
+        };
+        if (folderId !== undefined)
+            write.folderId = folderId;
+        return noteId === null
+            ? this.api.createNote(write)
+            : this.api.updateNote(noteId, write);
+    }
+    async decryptRow(key, row) {
+        if (row.encryptedTitle && row.encryptedContent && row.iv) {
+            return (0, virlow_crypto_1.decryptNoteFields)(key, row.encryptedTitle, row.encryptedContent, row.iv);
+        }
+        // A legacy plaintext note the user filed under Memories by hand.
+        return { title: row.title, content: row.content };
+    }
+    async requireTree() {
+        this.tree ??= await (0, memory_tree_js_1.resolveMemoryTree)(this.api);
+        return this.tree;
+    }
+    async requireEmbeddings(key) {
+        this.embeddings ??= this.cacheFactory(this.vault.session.userId);
+        if (!this.embeddingsLoaded) {
+            await this.embeddings.load(key);
+            this.embeddingsLoaded = true;
+        }
+        return this.embeddings;
+    }
+    /** Persisting after a lock would write vectors the user just cleared. */
+    async saveEmbeddings(key, startEpoch) {
+        if (this.epoch !== startEpoch)
+            return;
+        await this.embeddings?.save(key);
+    }
+    requireSession() {
+        const key = this.vault.session.key;
+        this.vault.touch();
+        return key;
+    }
+    /** Serializes add/update/delete so two overlapping mutation tool calls never
+     * interleave — two concurrent near-duplicate adds must run their
+     * dedupe-check-then-write critical section one at a time, or both would miss
+     * the other's pending write and both create. */
+    enqueue(fn) {
+        const next = this.mutationChain.then(fn, fn);
+        this.mutationChain = next.catch(() => { });
+        return next;
+    }
+}
+exports.MemoryStore = MemoryStore;
+/** The metadata is deliberately excluded: it is near-identical boilerplate
+ * across the corpus, so embedding it would raise the similarity floor
+ * everywhere and quietly change what the dedupe thresholds mean. */
+function embeddingInput(label, fact) {
+    return `${label}\n${fact}`;
+}
+/** `exactOptionalPropertyTypes` forbids assigning undefined to an optional
+ * property, so an absent namespace omits the key entirely. */
+function namespaceField(namespace) {
+    return namespace === undefined ? {} : { namespace };
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Metadata carried in a memory note's YAML frontmatter. Every key is optional.
+ *
+ * Deliberately absent: `id`, `label`, and `namespace`. The note id, the note
+ * title, and the containing subfolder already own those, and duplicating them
+ * here would create a second source of truth that goes stale the moment the
+ * user renames or drags the note in the app.
+ */
+export interface MemoryMeta {
+    /** Which agent or tool wrote the memory. */
+    source?: string;
+    tags?: string[];
+    /** Free-form: 'high', '0.8' — stored and editable, nothing ranks on it yet. */
+    confidence?: string;
+    /** ISO timestamp of the first write; never overwritten by later updates. */
+    created?: string;
+}
+export interface ParsedMemoryNote {
+    fact: string;
+    meta: MemoryMeta;
+}
+/** The app's code editor stores content as this envelope; `code` is what the
+ * user sees and edits in Monaco. */
+export declare function toCodeEnvelope(body: string): string;
+/**
+ * Split a decrypted note body into its fact and metadata.
+ *
+ * Total by construction: a missing fence, unparseable YAML, frontmatter that
+ * is not a mapping, or a note that was never a memory note at all all yield
+ * `{ fact: <the whole body>, meta: {} }`. A human edits these by hand, so a
+ * syntax error must cost them a bit of metadata, never the memory.
+ */
+export declare function parseMemoryNote(decryptedContent: string): ParsedMemoryNote;
+/**
+ * Canonical memory body: frontmatter then the fact, or just the fact when
+ * there is no metadata to record.
+ */
+export declare function serializeMemoryBody(fact: string, meta: MemoryMeta): string;
+/**
+ * Metadata for an update: named keys win, unnamed keys carry forward, and
+ * `created` is pinned to the first write so an in-place dedupe merge cannot
+ * make an old memory look new.
+ */
+export declare function mergeMeta(existing: MemoryMeta, changes: MemoryMeta): MemoryMeta;

package/dist/cjs/memory-note.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toCodeEnvelope = toCodeEnvelope;
+exports.parseMemoryNote = parseMemoryNote;
+exports.serializeMemoryBody = serializeMemoryBody;
+exports.mergeMeta = mergeMeta;
+const yaml_1 = require("yaml");
+/** Serialisation order, so a rewrite of unchanged metadata is a no-op diff. */
+const KEY_ORDER = ['source', 'tags', 'confidence', 'created'];
+const FENCE = '---';
+/** The app's code editor stores content as this envelope; `code` is what the
+ * user sees and edits in Monaco. */
+function toCodeEnvelope(body) {
+    return JSON.stringify({ language: 'markdown', code: body, lastExecution: null });
+}
+function unwrapEnvelope(content) {
+    try {
+        const parsed = JSON.parse(content);
+        if (parsed !== null &&
+            typeof parsed === 'object' &&
+            typeof parsed.code === 'string') {
+            return parsed.code;
+        }
+    }
+    catch {
+        // Not JSON at all — a hand-written note, which is a perfectly good memory.
+    }
+    return content;
+}
+/** Keep only keys we understand, and only when their value has the right
+ * shape. One malformed key never discards its neighbours. */
+function coerceMeta(raw) {
+    const meta = {};
+    if (typeof raw.source === 'string')
+        meta.source = raw.source;
+    if (Array.isArray(raw.tags) &&
+        raw.tags.every((t) => typeof t === 'string')) {
+        meta.tags = [...raw.tags];
+    }
+    // YAML turns `confidence: 0.8` into a number; the field is free-form text.
+    if (typeof raw.confidence === 'string') {
+        meta.confidence = raw.confidence;
+    }
+    else if (typeof raw.confidence === 'number') {
+        meta.confidence = String(raw.confidence);
+    }
+    if (typeof raw.created === 'string') {
+        meta.created = raw.created;
+    }
+    else if (raw.created instanceof Date) {
+        // YAML parses unquoted ISO timestamps into Dates.
+        meta.created = raw.created.toISOString();
+    }
+    return meta;
+}
+/**
+ * Split a decrypted note body into its fact and metadata.
+ *
+ * Total by construction: a missing fence, unparseable YAML, frontmatter that
+ * is not a mapping, or a note that was never a memory note at all all yield
+ * `{ fact: <the whole body>, meta: {} }`. A human edits these by hand, so a
+ * syntax error must cost them a bit of metadata, never the memory.
+ */
+function parseMemoryNote(decryptedContent) {
+    // The note's `type` is deliberately not consulted: an envelope is accepted
+    // wherever one is found, so a memory whose type was changed in the app — or
+    // a plain note dropped into the folder by hand — still reads correctly.
+    const body = unwrapEnvelope(decryptedContent);
+    if (!body.startsWith(`${FENCE}\n`))
+        return { fact: body, meta: {} };
+    // Only the first fence pair is frontmatter; --- lines inside the fact are
+    // ordinary content.
+    const close = body.indexOf(`\n${FENCE}\n`, FENCE.length);
+    if (close === -1)
+        return { fact: body, meta: {} };
+    const front = body.slice(FENCE.length + 1, close);
+    const fact = body.slice(close + FENCE.length + 2);
+    // An empty fence is the marker `serializeMemoryBody` writes when a fact
+    // would otherwise be misread as its own frontmatter. Strip it and keep the
+    // fact whole.
+    if (front.trim() === '')
+        return { fact, meta: {} };
+    let raw;
+    try {
+        raw = (0, yaml_1.parse)(front);
+    }
+    catch {
+        return { fact: body, meta: {} };
+    }
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { fact: body, meta: {} };
+    }
+    return { fact, meta: coerceMeta(raw) };
+}
+function yamlScalar(value) {
+    // Quote anything YAML would otherwise reinterpret (or that would break the
+    // line), so a round-trip returns the same string.
+    return /^[A-Za-z0-9][\w .:@/+-]*$/.test(value) && !value.includes(': ')
+        ? value
+        : JSON.stringify(value);
+}
+/**
+ * Canonical memory body: frontmatter then the fact, or just the fact when
+ * there is no metadata to record.
+ */
+function serializeMemoryBody(fact, meta) {
+    const lines = [];
+    for (const key of KEY_ORDER) {
+        const value = meta[key];
+        if (value === undefined)
+            continue;
+        if (key === 'tags') {
+            const tags = value;
+            if (tags.length === 0)
+                continue;
+            lines.push(`tags: [${tags.map(yamlScalar).join(', ')}]`);
+        }
+        else {
+            lines.push(`${key}: ${yamlScalar(value)}`);
+        }
+    }
+    if (lines.length === 0) {
+        // A fact that opens with its own fence (a pasted document with
+        // frontmatter, say) would be read back as metadata and lose its first
+        // lines. An empty fence disambiguates it.
+        return fact.startsWith(`${FENCE}\n`) ? `${FENCE}\n${FENCE}\n${fact}` : fact;
+    }
+    return `${FENCE}\n${lines.join('\n')}\n${FENCE}\n${fact}`;
+}
+/**
+ * Metadata for an update: named keys win, unnamed keys carry forward, and
+ * `created` is pinned to the first write so an in-place dedupe merge cannot
+ * make an old memory look new.
+ */
+function mergeMeta(existing, changes) {
+    const merged = { ...existing };
+    if (changes.source !== undefined)
+        merged.source = changes.source;
+    if (changes.tags !== undefined)
+        merged.tags = [...changes.tags];
+    if (changes.confidence !== undefined)
+        merged.confidence = changes.confidence;
+    // Pinned to the first write, so an in-place dedupe merge cannot make an old
+    // memory look newly created.
+    if (changes.created !== undefined && existing.created === undefined) {
+        merged.created = changes.created;
+    }
+    return merged;
+}

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

@@ -0,0 +1,27 @@
+import { type VirlowApi } from './api.js';
+/** Name given to the memories root when the server has to create it. The root
+ * is identified by `kind`, never by this name — the user is free to rename it. */
+export declare const MEMORIES_ROOT_NAME = "Memories";
+export interface MemoryTree {
+    rootId: string;
+    /** namespace name -> subfolder id (direct children of the root) */
+    namespaces: Map<string, string>;
+    /** folder id -> namespace name; undefined for the root itself */
+    namespaceOf(folderId: string): string | undefined;
+    /** every folder id whose notes are memories, root first */
+    folderIds(): string[];
+    /** Record a subfolder created after the tree was resolved. Used by
+     * `ensureNamespace`; callers outside this module have no reason to. */
+    attach(folderId: string, name: string): void;
+}
+/**
+ * Resolve the memories folder tree, creating the root if the user has none.
+ * The root is whichever folder carries `kind: 'memories'` — the API allows
+ * only one per user.
+ */
+export declare function resolveMemoryTree(api: VirlowApi): Promise<MemoryTree>;
+/**
+ * Folder id for `name`, creating the namespace subfolder if it does not exist
+ * yet. Mutates `tree` so a later call in the same session is a cache hit.
+ */
+export declare function ensureNamespace(api: VirlowApi, tree: MemoryTree, name: string): Promise<string>;