@batalabs/virlow-mcp-core 3.19.0 → 3.68.0

package/dist/cjs/memory-graph.js

@@ -0,0 +1,270 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NEIGHBOUR_BOOST = exports.DIRECT_BOOST = exports.SINGLE_VALUED = exports.ONE_SUBJECT_PER_OBJECT = exports.ONE_OBJECT_PER_SUBJECT = void 0;
+exports.entityKey = entityKey;
+exports.normalizePredicate = normalizePredicate;
+exports.heldAt = heldAt;
+exports.memoryHeldAt = memoryHeldAt;
+exports.buildGraph = buildGraph;
+exports.entitiesMentioned = entitiesMentioned;
+exports.neighbours = neighbours;
+exports.rankMemories = rankMemories;
+exports.supersededBy = supersededBy;
+exports.graphHealth = graphHealth;
+/** The matching key for a name: case, spacing and a leading article do not
+ *  make a different entity. */
+function entityKey(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, ' ')
+        .replace(/^the /, '');
+}
+/**
+ * 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).
+ */
+exports.ONE_OBJECT_PER_SUBJECT = new Set([
+    'led_by',
+    'owned_by',
+    'managed_by',
+    'reports_to',
+    'works_at',
+    'lives_in',
+    'based_in',
+    'located_in',
+    'role',
+    'status',
+    'title',
+]);
+exports.ONE_SUBJECT_PER_OBJECT = new Set(['leads', 'owns', 'manages']);
+/** Either kind: a predicate that holds one value at a time. */
+exports.SINGLE_VALUED = new Set([...exports.ONE_OBJECT_PER_SUBJECT, ...exports.ONE_SUBJECT_PER_OBJECT]);
+/** snake_case, so "Works at" and "works_at" are one predicate. */
+function normalizePredicate(p) {
+    return p
+        .trim()
+        .toLowerCase()
+        .replace(/[\s-]+/g, '_')
+        .replace(/[^a-z0-9_]/g, '');
+}
+/** A date or ISO timestamp as comparable milliseconds; bare dates are the
+ *  start of that UTC day. */
+function when(value) {
+    if (!value)
+        return null;
+    const t = Date.parse(value.length === 10 ? `${value}T00:00:00Z` : value);
+    return Number.isNaN(t) ? null : t;
+}
+/** Whether a span held at `at`: started on or before it, ended after it. */
+function heldAt(from, to, at) {
+    const start = when(from);
+    const end = when(to);
+    if (start !== null && start > at)
+        return false;
+    if (end !== null && end <= at)
+        return false;
+    return true;
+}
+/**
+ * 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.
+ */
+function memoryHeldAt(memory, at) {
+    const relationStarts = (memory.meta.relations ?? [])
+        .map((r) => r.from)
+        .filter((f) => !!f && when(f) !== null)
+        .sort((a, b) => when(a) - when(b));
+    const start = memory.meta.validFrom ?? relationStarts[0] ?? memory.meta.created;
+    return heldAt(start, memory.meta.validTo, at);
+}
+function buildGraph(memories) {
+    const entities = new Map();
+    const spellings = new Map();
+    const edges = [];
+    const touch = (name, memoryId) => {
+        const key = entityKey(name);
+        let entity = entities.get(key);
+        if (!entity) {
+            entity = { key, name: name.trim(), memoryIds: new Set(), edges: [] };
+            entities.set(key, entity);
+            spellings.set(key, new Map());
+        }
+        entity.memoryIds.add(memoryId);
+        const counts = spellings.get(key);
+        counts.set(name.trim(), (counts.get(name.trim()) ?? 0) + 1);
+        return entity;
+    };
+    for (const memory of memories) {
+        for (const name of memory.meta.about ?? [])
+            touch(name, memory.id);
+        for (const relation of memory.meta.relations ?? []) {
+            const edge = { ...relation, p: normalizePredicate(relation.p), memoryId: memory.id };
+            edges.push(edge);
+            touch(relation.s, memory.id).edges.push(edge);
+            // The object is an entity only if something else names it as one;
+            // "async standups" as the object of prefers stays a literal.
+            const objectKey = entityKey(relation.o);
+            if (entities.has(objectKey) || isEntityLike(relation.o)) {
+                touch(relation.o, memory.id).edges.push(edge);
+            }
+        }
+    }
+    for (const [key, counts] of spellings) {
+        const [best] = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+        if (best)
+            entities.get(key).name = best[0];
+    }
+    return { entities, edges };
+}
+/** A capitalised name reads as an entity (Atlas, Dana Whitfield, Fly.io);
+ *  a lower-case phrase reads as a value (async standups, dark mode). */
+function isEntityLike(value) {
+    return /^[A-Z0-9]/.test(value.trim());
+}
+/** Entities named in a piece of text (a prompt, a query), longest names
+ *  first so "Dana Whitfield" wins over "Dana". Whole words only. */
+function entitiesMentioned(graph, text) {
+    // Dots survive only inside a name (Fly.io); a full stop after a word
+    // would otherwise hide the word.
+    const haystack = ` ${text
+        .toLowerCase()
+        .replace(/[^a-z0-9.\s]/g, ' ')
+        .replace(/\.(?![a-z0-9])|(?<![a-z0-9])\./g, ' ')
+        .replace(/\s+/g, ' ')} `;
+    const found = [];
+    const byLength = [...graph.entities.values()].sort((a, b) => b.key.length - a.key.length);
+    let remaining = haystack;
+    for (const entity of byLength) {
+        const needle = ` ${entity.key} `;
+        if (entity.key.length < 2 || !remaining.includes(needle))
+            continue;
+        found.push(entity);
+        remaining = remaining.split(needle).join(' ');
+    }
+    return found;
+}
+/** Entities one relation away from any of `from`. */
+function neighbours(graph, from) {
+    const seen = new Set(from.map((e) => e.key));
+    const result = [];
+    for (const entity of from) {
+        for (const edge of entity.edges) {
+            for (const end of [edge.s, edge.o]) {
+                const key = entityKey(end);
+                const other = graph.entities.get(key);
+                if (other && !seen.has(key)) {
+                    seen.add(key);
+                    result.push(other);
+                }
+            }
+        }
+    }
+    return result;
+}
+/** 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. */
+exports.DIRECT_BOOST = 0.15;
+exports.NEIGHBOUR_BOOST = 0.07;
+const RECENCY_WEIGHT = 0.08;
+const RECENCY_HORIZON_DAYS = 365;
+function rankMemories(graph, query, scored, opts) {
+    const at = opts.at ?? Date.now();
+    const direct = entitiesMentioned(graph, query);
+    const near = neighbours(graph, direct);
+    const directIds = new Set(direct.flatMap((e) => [...e.memoryIds]));
+    const nearIds = new Set(near.flatMap((e) => [...e.memoryIds]));
+    return scored
+        .filter(({ memory }) => opts.includeHistory || memoryHeldAt(memory, at))
+        .map((item) => {
+        let score = item.similarity;
+        if (directIds.has(item.memory.id))
+            score += exports.DIRECT_BOOST;
+        else if (nearIds.has(item.memory.id))
+            score += exports.NEIGHBOUR_BOOST;
+        const updated = Date.parse(item.memory.updatedAt);
+        if (!Number.isNaN(updated)) {
+            const ageDays = Math.max(0, (at - updated) / 86_400_000);
+            score -= RECENCY_WEIGHT * Math.min(1, ageDays / RECENCY_HORIZON_DAYS);
+        }
+        return { ...item, score };
+    })
+        .sort((a, b) => b.score - a.score)
+        .slice(0, opts.limit);
+}
+/**
+ * Current edges a new relation replaces: same subject and single-valued
+ * predicate, a different object, still holding when the new one starts.
+ */
+function supersededBy(graph, relation, at) {
+    const p = normalizePredicate(relation.p);
+    const s = entityKey(relation.s);
+    const o = entityKey(relation.o);
+    const bySubject = exports.ONE_OBJECT_PER_SUBJECT.has(p);
+    const byObject = exports.ONE_SUBJECT_PER_OBJECT.has(p);
+    if (!bySubject && !byObject)
+        return [];
+    return graph.edges.filter((edge) => {
+        if (edge.p !== p || !heldAt(edge.from, edge.to, at))
+            return false;
+        const es = entityKey(edge.s);
+        const eo = entityKey(edge.o);
+        if (es === s && eo === o)
+            return false;
+        return bySubject ? es === s : eo === o;
+    });
+}
+/**
+ * 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.
+ */
+function graphHealth(graph, memories, at = Date.now()) {
+    const unlinked = memories
+        .filter((m) => !(m.meta.about?.length || m.meta.relations?.length))
+        .map((m) => m.id);
+    const names = [...graph.entities.values()];
+    const possibleDuplicates = [];
+    for (let i = 0; i < names.length; i++) {
+        for (let j = i + 1; j < names.length; j++) {
+            const a = names[i].key;
+            const b = names[j].key;
+            const [short, long] = a.length <= b.length ? [a, b] : [b, a];
+            // "dana" and "dana whitfield": one name is the first word(s) of the other.
+            if (short.length >= 3 && long.startsWith(`${short} `)) {
+                possibleDuplicates.push([names[i].name, names[j].name]);
+            }
+        }
+    }
+    const contradictions = [];
+    // Keyed on the side that must be unique: the subject for works_at, the
+    // object for leads. `values` are the other side.
+    const current = new Map();
+    for (const edge of graph.edges) {
+        if (!exports.SINGLE_VALUED.has(edge.p) || !heldAt(edge.from, edge.to, at))
+            continue;
+        const bySubject = exports.ONE_OBJECT_PER_SUBJECT.has(edge.p);
+        const anchor = bySubject ? edge.s : edge.o;
+        const key = `${entityKey(anchor)}|${edge.p}`;
+        if (!current.has(key))
+            current.set(key, { anchor, predicate: edge.p, values: new Set() });
+        current.get(key).values.add(bySubject ? edge.o : edge.s);
+    }
+    for (const [key, { anchor, predicate, values }] of current) {
+        if (values.size < 2)
+            continue;
+        contradictions.push({
+            subject: graph.entities.get(key.split('|')[0])?.name ?? anchor,
+            predicate,
+            objects: [...values],
+        });
+    }
+    return { unlinked, possibleDuplicates, contradictions };
+}

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

@@ -14,10 +14,51 @@ export interface MemoryMeta {
     confidence?: string;
     /** ISO timestamp of the first write; never overwritten by later updates. */
     created?: string;
+    /**
+     * `html` when the fact was written in the app's rich editor, so the body
+     * after the frontmatter is TipTap HTML rather than plain text. Absent
+     * means plain text, which is what the connector always writes: AI tools
+     * read and write text, and the app renders it as paragraphs.
+     */
+    format?: 'html';
+    /**
+     * The graph: the entities this fact is about (people, projects, places,
+     * tools), by name. Names are matched case-insensitively across memories,
+     * so every memory that says "Atlas" is about the same Atlas.
+     */
+    about?: string[];
+    /** Typed links the fact asserts, e.g. Sam leads Atlas. A relation lives on
+     *  the memory that asserted it, so every edge has a source to open, check
+     *  or delete. */
+    relations?: MemoryRelation[];
+    /** When the fact became true (YYYY-MM-DD or ISO). Absent: when it was
+     *  learned (`created`). */
+    validFrom?: string;
+    /** When the fact stopped being true. Facts are ended, never deleted, when
+     *  they are superseded, so history stays answerable. */
+    validTo?: string;
+    /** The memory that replaced this one, when one did. */
+    supersededBy?: string;
+}
+/**
+ * One edge: subject, predicate, object. `p` is a short verb phrase in
+ * snake_case ("leads", "works_at", "prefers"); `o` is an entity name or a
+ * literal ("async standups"). `from` and `to` bound when it held.
+ */
+export interface MemoryRelation {
+    s: string;
+    p: string;
+    o: string;
+    from?: string;
+    to?: string;
 }
 export interface ParsedMemoryNote {
+    /** The fact as plain text: what AI tools read, what gets embedded. For an
+     *  HTML body, its text with line breaks and list markers kept. */
     fact: string;
     meta: MemoryMeta;
+    /** The body as written, when `meta.format` is `html`. */
+    html?: string;
 }
 /**
  * The note type a memory is written as.
@@ -36,6 +77,20 @@ export declare const MEMORY_NOTE_TYPE = "memory";
  * (or a test) can build a legacy body and confirm it still reads.
  */
 export declare function toCodeEnvelope(body: string): string;
+/**
+ * A rich fact as text an AI can read: one line per paragraph, heading or
+ * list item, list items marked, code and inline marks reduced to their text.
+ * Entities are decoded, so a fact that talks about `<p>` tags reads back as
+ * exactly that.
+ */
+export declare function memoryHtmlToText(html: string): string;
+/**
+ * Plain text as the rich editor's HTML: a paragraph per blank-line-separated
+ * block, single line breaks kept, everything escaped. Used to open a
+ * connector-written (plain) memory in the editor.
+ */
+export declare function memoryTextToHtml(text: string): string;
+export declare function looksLikeHtml(fact: string): boolean;
 /**
  * Split a decrypted note body into its fact and metadata.
  *
@@ -50,6 +105,8 @@ export declare function parseMemoryNote(decryptedContent: string): ParsedMemoryN
  * there is no metadata to record.
  */
 export declare function serializeMemoryBody(fact: string, meta: MemoryMeta): string;
+/** The app's rich editor output, marked as HTML. */
+export declare function serializeMemoryHtml(html: 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

package/dist/cjs/memory-note.js

@@ -2,12 +2,65 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MEMORY_NOTE_TYPE = void 0;
 exports.toCodeEnvelope = toCodeEnvelope;
+exports.memoryHtmlToText = memoryHtmlToText;
+exports.memoryTextToHtml = memoryTextToHtml;
+exports.looksLikeHtml = looksLikeHtml;
 exports.parseMemoryNote = parseMemoryNote;
 exports.serializeMemoryBody = serializeMemoryBody;
+exports.serializeMemoryHtml = serializeMemoryHtml;
 exports.mergeMeta = mergeMeta;
 const yaml_1 = require("yaml");
+const attrs_extract_js_1 = require("./attrs-extract.js");
 /** Serialisation order, so a rewrite of unchanged metadata is a no-op diff. */
-const KEY_ORDER = ['source', 'tags', 'confidence', 'created'];
+const KEY_ORDER = [
+    'source',
+    'tags',
+    'confidence',
+    'created',
+    'format',
+    'about',
+    'relations',
+    'validFrom',
+    'validTo',
+    'supersededBy',
+];
+/** The frontmatter key for each field: snake_case on disk, as a person
+ *  editing the YAML would write it. */
+const YAML_KEY = {
+    validFrom: 'valid_from',
+    validTo: 'valid_to',
+    supersededBy: 'superseded_by',
+};
+/** A date field as a string: YAML reads an unquoted date as a Date. */
+function dateField(value) {
+    if (typeof value === 'string' && value.trim() !== '')
+        return value.trim();
+    if (value instanceof Date && !Number.isNaN(value.getTime())) {
+        const iso = value.toISOString();
+        // A bare date comes back as midnight UTC; keep it a date.
+        return iso.endsWith('T00:00:00.000Z') ? iso.slice(0, 10) : iso;
+    }
+    return undefined;
+}
+function coerceRelation(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const r = raw;
+    const text = (v) => (typeof v === 'string' && v.trim() !== '' ? v.trim() : null);
+    const s = text(r.s);
+    const p = text(r.p);
+    const o = text(r.o);
+    if (!s || !p || !o)
+        return null;
+    const relation = { s, p, o };
+    const from = dateField(r.from);
+    const to = dateField(r.to);
+    if (from)
+        relation.from = from;
+    if (to)
+        relation.to = to;
+    return relation;
+}
 const FENCE = '---';
 /**
  * The note type a memory is written as.
@@ -66,8 +119,86 @@ function coerceMeta(raw) {
         // YAML parses unquoted ISO timestamps into Dates.
         meta.created = raw.created.toISOString();
     }
+    if (raw.format === 'html')
+        meta.format = 'html';
+    if (Array.isArray(raw.about)) {
+        const about = raw.about.filter((a) => typeof a === 'string' && a.trim() !== '');
+        if (about.length > 0)
+            meta.about = about.map((a) => a.trim());
+    }
+    if (Array.isArray(raw.relations)) {
+        // One malformed relation is dropped; its neighbours survive.
+        const relations = raw.relations
+            .map(coerceRelation)
+            .filter((r) => r !== null);
+        if (relations.length > 0)
+            meta.relations = relations;
+    }
+    const validFrom = dateField(raw.valid_from);
+    if (validFrom)
+        meta.validFrom = validFrom;
+    const validTo = dateField(raw.valid_to);
+    if (validTo)
+        meta.validTo = validTo;
+    if (typeof raw.superseded_by === 'string' && raw.superseded_by !== '') {
+        meta.supersededBy = raw.superseded_by;
+    }
     return meta;
 }
+/**
+ * A rich fact as text an AI can read: one line per paragraph, heading or
+ * list item, list items marked, code and inline marks reduced to their text.
+ * Entities are decoded, so a fact that talks about `<p>` tags reads back as
+ * exactly that.
+ */
+function memoryHtmlToText(html) {
+    const text = html
+        .replace(/<br\s*\/?>/gi, '\n')
+        // A list item's paragraph is the item, not a paragraph of its own.
+        .replace(/<li[^>]*>\s*(<p[^>]*>)?/gi, '- ')
+        .replace(/(<\/p>)?\s*<\/li>/gi, '\n')
+        .replace(/<\/(p|h[1-6]|blockquote|pre|ul|ol|table)>/gi, '\n\n')
+        .replace(/<\/tr>/gi, '\n')
+        .replace(/<\/(td|th)>/gi, ' ')
+        .replace(/<[^>]+>/g, '');
+    return (0, attrs_extract_js_1.decodeEntities)(text)
+        .split('\n')
+        .map((line) => line.replace(/[ \t]+$/, ''))
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+/**
+ * Plain text as the rich editor's HTML: a paragraph per blank-line-separated
+ * block, single line breaks kept, everything escaped. Used to open a
+ * connector-written (plain) memory in the editor.
+ */
+function memoryTextToHtml(text) {
+    const escape = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    const blocks = text.split(/\n{2,}/).filter((b) => b.trim() !== '');
+    if (blocks.length === 0)
+        return '<p></p>';
+    return blocks.map((b) => `<p>${b.split('\n').map(escape).join('<br>')}</p>`).join('');
+}
+/**
+ * A plain-text fact that is really HTML: it opens and closes with a block
+ * tag. AI tools told that Virlow notes are HTML sometimes write a memory the
+ * same way, without the `format` marker the app adds, and it then showed its
+ * tags as text. A fact that merely mentions a tag ("every paragraph in
+ * <p>") does not start and end with one, so it stays text.
+ */
+const BLOCK = '(p|ul|ol|h[1-6]|blockquote|pre|table|div)';
+const OPENS_WITH_BLOCK = new RegExp(`^\\s*<${BLOCK}[\\s>]`, 'i');
+const CLOSES_WITH_BLOCK = new RegExp(`</${BLOCK}>\\s*$`, 'i');
+function looksLikeHtml(fact) {
+    return OPENS_WITH_BLOCK.test(fact) && CLOSES_WITH_BLOCK.test(fact);
+}
+function plainOrHtml(fact, meta) {
+    if (meta.format === 'html' || looksLikeHtml(fact)) {
+        return { fact: memoryHtmlToText(fact), meta, html: fact };
+    }
+    return { fact, meta };
+}
 /**
  * Split a decrypted note body into its fact and metadata.
  *
@@ -82,19 +213,19 @@ function parseMemoryNote(decryptedContent) {
     // 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: {} };
+        return plainOrHtml(body, {});
     // 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: {} };
+        return plainOrHtml(body, {});
     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: {} };
+        return plainOrHtml(fact, {});
     let raw;
     try {
         raw = (0, yaml_1.parse)(front);
@@ -105,7 +236,7 @@ function parseMemoryNote(decryptedContent) {
     if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
         return { fact: body, meta: {} };
     }
-    return { fact, meta: coerceMeta(raw) };
+    return plainOrHtml(fact, coerceMeta(raw));
 }
 function yamlScalar(value) {
     // Quote anything YAML would otherwise reinterpret (or that would break the
@@ -119,19 +250,42 @@ function yamlScalar(value) {
  * there is no metadata to record.
  */
 function serializeMemoryBody(fact, meta) {
+    // Plain text, always: `format` describes the body, so it is dropped here
+    // rather than carried forward from the memory being updated. An AI
+    // rewriting a rich memory writes text, and the marker must not survive
+    // onto a body it no longer describes.
+    const { format: _format, ...plain } = meta;
+    return writeBody(fact, plain);
+}
+/** The app's rich editor output, marked as HTML. */
+function serializeMemoryHtml(html, meta) {
+    return writeBody(html, { ...meta, format: 'html' });
+}
+function writeBody(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)
+        const name = YAML_KEY[key] ?? key;
+        if (key === 'tags' || key === 'about') {
+            const list = value;
+            if (list.length === 0)
+                continue;
+            lines.push(`${name}: [${list.map(yamlScalar).join(', ')}]`);
+        }
+        else if (key === 'relations') {
+            const relations = value;
+            if (relations.length === 0)
                 continue;
-            lines.push(`tags: [${tags.map(yamlScalar).join(', ')}]`);
+            // Flow style, one relation per line: JSON is valid YAML, and this
+            // keeps each edge readable and editable by hand.
+            lines.push(`${name}:`);
+            for (const r of relations)
+                lines.push(`  - ${JSON.stringify(r)}`);
         }
         else {
-            lines.push(`${key}: ${yamlScalar(value)}`);
+            lines.push(`${name}: ${yamlScalar(value)}`);
         }
     }
     if (lines.length === 0) {
@@ -155,6 +309,16 @@ function mergeMeta(existing, changes) {
         merged.tags = [...changes.tags];
     if (changes.confidence !== undefined)
         merged.confidence = changes.confidence;
+    if (changes.about !== undefined)
+        merged.about = [...changes.about];
+    if (changes.relations !== undefined)
+        merged.relations = changes.relations.map((r) => ({ ...r }));
+    if (changes.validFrom !== undefined)
+        merged.validFrom = changes.validFrom;
+    if (changes.validTo !== undefined)
+        merged.validTo = changes.validTo;
+    if (changes.supersededBy !== undefined)
+        merged.supersededBy = changes.supersededBy;
     // 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) {

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

@@ -0,0 +1,19 @@
+/**
+ * Refuses memories that contain credentials, before anything is written.
+ *
+ * Memories are captured automatically, so the rule cannot depend on the AI
+ * remembering not to save a key: a memory is encrypted, but it is recalled
+ * into prompts and shown in the app, and a secret has no business in either.
+ * The check is on-device and returns a reason, so the AI can say what it
+ * left out instead of retrying with the secret reworded.
+ *
+ * Deliberately narrow: patterns that are credentials with near certainty,
+ * plus long high-entropy tokens. A false positive costs one memory; a false
+ * negative puts a live key into every future prompt that recalls it.
+ */
+/** What secret the text holds, or null when it holds none. */
+export declare function findSecret(text: string): string | null;
+export declare class SecretInMemoryError extends Error {
+    constructor(what: string);
+}
+export declare function assertNoSecret(...texts: string[]): void;