@oharness/engine 0.4.0 → 0.5.1

package/dist/agent/memory.js

@@ -1,125 +1,289 @@
+import { MemoryError } from "./memory-errors.js";
 import { mkdir, open, readdir, writeFile, rename, rm, lstat } from "node:fs/promises";
 import { constants } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { shortId } from "../util/id.js";
 import { splitFrontmatter } from "./skills.js";
-export const validMemoryId = (id) => typeof id === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(id) && !["__proto__", "constructor", "prototype"].includes(id);
+import { DEFAULT_MEMORY_POLICY, MEMORY_SAFETY, isMemoryType } from "./memory-limits.js";
+import { buildLinkGraph } from "./memory-links.js";
+import { rankNotes, recallQuery, renderRecall, selectRecall } from "./memory-recall.js";
+export const validMemoryId = (id) => typeof id === "string" && MEMORY_SAFETY.idPattern.test(id) && !MEMORY_SAFETY.reservedIds.includes(id);
+/**
+ * The identity of a note's content, compared across machines.
+ *
+ * `type` takes part only when a note has one. Every note written before the
+ * field existed keeps exactly the hash that its sync baseline and the server's
+ * manifest already recorded; including an absent type as `null` would have
+ * made every existing note look edited on every machine at once.
+ */
 export function noteHash(note) {
-    return note ? createHash("sha256").update(JSON.stringify([note.id, note.summary, note.body, note.tags, note.createdAt])).digest("hex") : null;
+    if (!note)
+        return null;
+    const fields = [note.id, note.summary, note.body, note.tags, note.createdAt];
+    if (note.type !== undefined)
+        fields.push(note.type);
+    return createHash("sha256").update(JSON.stringify(fields)).digest("hex");
 }
-export function memoryNote(entry) { const { file: _, ...note } = entry; return note; }
-export function validateNote(note) {
-    if (!validMemoryId(note.id) || typeof note.summary !== "string" || !note.summary.trim() || note.summary.length > 500 ||
-        /[\r\n]/.test(note.summary) || note.summary !== note.summary.trim() || typeof note.body !== "string" || note.body !== note.body.trim() || Buffer.byteLength(note.body) > 128 * 1024 ||
-        !Array.isArray(note.tags) || note.tags.length > 30 || note.tags.some((tag) => typeof tag !== "string" || !/^[^\s,\r\n]{1,64}$/.test(tag)) ||
-        !Number.isSafeInteger(note.createdAt) || note.createdAt < 0)
+/**
+ * Tags as a model writes them, made into tags a note can hold.
+ *
+ * Models pad them (" aesthetics"), prefix them ("#design"), and put two in one
+ * string ("design, ux"). Refusing the whole note over that loses a note the
+ * user asked for, so each is trimmed, split and de-duplicated, and anything
+ * still unusable is dropped.
+ */
+export function normalizeTags(tags) {
+    const out = [];
+    const seen = new Set();
+    for (const raw of tags) {
+        if (typeof raw !== "string")
+            continue;
+        for (const part of raw.split(/[,，\s]+/)) {
+            const tag = part.replace(/^#+/, "");
+            if (!MEMORY_SAFETY.tagPattern.test(tag) || seen.has(tag.toLowerCase()))
+                continue;
+            seen.add(tag.toLowerCase());
+            out.push(tag);
+            if (out.length >= MEMORY_SAFETY.maxTags)
+                return out;
+        }
+    }
+    return out;
+}
+export function memoryNote(entry) {
+    const { file: _, ...note } = entry;
+    if (note.type === undefined)
+        delete note.type;
+    return note;
+}
+export function validateNote(note, maxNoteBytes = DEFAULT_MEMORY_POLICY.maxNoteBytes) {
+    const s = MEMORY_SAFETY;
+    if (!validMemoryId(note.id) || typeof note.summary !== "string" || !note.summary.trim() || note.summary.length > s.maxSummaryChars ||
+        /[\r\n]/.test(note.summary) || note.summary !== note.summary.trim() || typeof note.body !== "string" || note.body !== note.body.trim() ||
+        Buffer.byteLength(note.body) > maxNoteBytes ||
+        !Array.isArray(note.tags) || note.tags.length > s.maxTags || note.tags.some((tag) => typeof tag !== "string" || !s.tagPattern.test(tag)) ||
+        !Number.isSafeInteger(note.createdAt) || note.createdAt < 0 ||
+        (note.type !== undefined && !isMemoryType(note.type)))
         throw new Error("Invalid memory note");
 }
 const writes = new Map();
-/** How much of the memory index may enter the system prompt. */
-const MAX_PROMPT_CHARS = 4_000;
 export class MemoryStore {
     dir;
-    constructor(dir) {
+    maxNotes;
+    maxNoteBytes;
+    scope;
+    onWarning;
+    files = new Map();
+    cached;
+    warnedOmitted = 0;
+    scoped = new WeakMap();
+    listeners = new Set();
+    constructor(dir, options = {}) {
         this.dir = dir;
+        this.maxNotes = Math.max(1, Math.min(options.maxNotes ?? DEFAULT_MEMORY_POLICY.maxNotes, MEMORY_SAFETY.maxNotesCeiling));
+        this.maxNoteBytes = Math.max(1024, Math.min(options.maxNoteBytes ?? DEFAULT_MEMORY_POLICY.maxNoteBytes, MEMORY_SAFETY.maxNoteBytesCeiling));
+        this.scope = options.scope ?? "project";
+        this.onWarning = options.onWarning;
     }
     get location() {
         return this.dir;
     }
+    /** Told after every write this store makes, once the file is in place. */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    emit(id, origin) {
+        for (const listener of this.listeners) {
+            try {
+                listener({ id, origin });
+            }
+            catch { /* an observer never fails a write */ }
+        }
+    }
     async load() {
-        let files;
+        return (await this.snapshot()).entries;
+    }
+    /**
+     * Every note, read from disk only where a file changed.
+     *
+     * Recall scores notes on every user message, so rereading the directory each
+     * time would put thousands of file reads in front of every reply. A file's
+     * size and timestamps decide whether its parsed note is reused; the store's
+     * own writes drop their file from that cache outright, because two writes
+     * inside one timestamp tick with bodies of equal length would otherwise look
+     * unchanged.
+     */
+    async snapshot() {
+        let names;
         try {
             for (const directory of [this.dir, path.dirname(this.dir)]) {
                 if ((await lstat(directory)).isSymbolicLink())
                     throw new Error("Memory directory cannot be a symlink");
             }
-            files = (await readdir(this.dir)).filter((name) => name.endsWith(".md"));
+            names = (await readdir(this.dir)).filter((name) => name.endsWith(".md"));
         }
         catch (error) {
-            if (error.code === "ENOENT")
-                return [];
+            if (error.code === "ENOENT") {
+                this.files.clear();
+                this.cached = undefined;
+                return { entries: [], omitted: 0, links: buildLinkGraph([]) };
+            }
             throw error;
         }
-        if (files.length > 500)
-            throw new Error("Memory limit: 500 notes per project");
-        const entries = [];
-        for (const name of files) {
-            const file = path.join(this.dir, name);
-            let raw;
-            const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
-            try {
-                const stat = await handle.stat();
-                if (!stat.isFile() || stat.size > 256 * 1024)
+        const stats = [];
+        for (let i = 0; i < names.length; i += MEMORY_SAFETY.statConcurrency) {
+            const batch = await Promise.all(names.slice(i, i + MEMORY_SAFETY.statConcurrency).map(async (name) => {
+                const file = path.join(this.dir, name);
+                let info;
+                try {
+                    info = await lstat(file);
+                }
+                catch (error) {
+                    // Removed between listing and stat: a concurrent delete, not corruption.
+                    if (error.code === "ENOENT")
+                        return undefined;
+                    throw error;
+                }
+                if (info.isSymbolicLink() || !info.isFile())
                     throw new Error("Invalid memory file");
-                raw = await handle.readFile("utf8");
-            }
-            finally {
-                await handle.close();
-            }
-            // New writes use JSON-flow YAML metadata so quotes, colons and tags round-trip.
-            // Keep the original scalar frontmatter reader for existing local notes.
-            const jsonHeader = /^\uFEFF?---\r?\n(\{[^\n]+\})\r?\n---\r?\n([\s\S]*)$/.exec(raw);
-            if (jsonHeader) {
-                const metadata = JSON.parse(jsonHeader[1]);
-                entries.push({ id: metadata.id, summary: metadata.summary, tags: metadata.tags,
-                    createdAt: metadata.createdAt, updatedAt: metadata.updatedAt, body: jsonHeader[2].trim(), file });
-                continue;
-            }
-            const { frontmatter, body } = splitFrontmatter(raw);
-            const summary = frontmatter["summary"]?.trim();
-            // Without a summary the entry cannot appear in the index, and an entry
-            // the model never sees is one it will never ask for.
-            if (!summary)
-                throw new Error("Memory note has no summary");
-            entries.push({
-                id: frontmatter["id"]?.trim() || name.replace(/\.md$/, ""),
-                summary,
-                body: body.trim(),
-                tags: (frontmatter["tags"] ?? "")
-                    .split(/[,\s]+/)
-                    .map((tag) => tag.trim())
-                    .filter((tag) => tag !== ""),
-                createdAt: Number(frontmatter["createdAt"]) || 0,
-                updatedAt: Number(frontmatter["updatedAt"]) || 0,
-                file,
-            });
+                return { name, file, mtimeMs: info.mtimeMs, ctimeMs: info.ctimeMs, size: info.size };
+            }));
+            for (const item of batch)
+                if (item)
+                    stats.push(item);
+        }
+        const signature = stats.map((s) => `${s.name}:${s.mtimeMs}:${s.ctimeMs}:${s.size}`).sort().join("|");
+        if (this.cached?.signature === signature)
+            return this.cached.snapshot;
+        // Past the limit, the notes that stop loading are the ones nobody has
+        // touched for longest. Degrading, rather than refusing to load at all:
+        // before this, one note too many switched off the index, the tools and
+        // sync together.
+        stats.sort((a, b) => b.mtimeMs - a.mtimeMs || a.name.localeCompare(b.name));
+        const kept = stats.slice(0, this.maxNotes);
+        const omitted = stats.length - kept.length;
+        if (omitted > 0 && omitted !== this.warnedOmitted) {
+            this.warnedOmitted = omitted;
+            this.onWarning?.(`Memory holds ${stats.length} notes, over the limit of ${this.maxNotes}; the ${omitted} least recently modified are not loaded.`);
+        }
+        else if (omitted === 0)
+            this.warnedOmitted = 0;
+        const nextFiles = new Map();
+        const entries = [];
+        for (const item of kept) {
+            const previous = this.files.get(item.name);
+            const entry = previous && previous.mtimeMs === item.mtimeMs && previous.ctimeMs === item.ctimeMs && previous.size === item.size
+                ? previous.entry
+                : await this.readNote(item.file, item.name);
+            nextFiles.set(item.name, { mtimeMs: item.mtimeMs, ctimeMs: item.ctimeMs, size: item.size, entry });
+            entries.push(entry);
         }
         entries.sort((a, b) => b.createdAt - a.createdAt);
         const seen = new Set();
+        const folded = new Set();
         for (const entry of entries) {
-            validateNote(entry);
+            validateNote(entry, this.maxNoteBytes);
             if (seen.has(entry.id))
                 throw new Error("Duplicate memory id");
+            // macOS and Windows file systems do not tell `A.md` from `a.md`, so two
+            // ids that differ only in case are one file waiting to overwrite the other.
+            const lower = entry.id.toLowerCase();
+            if (folded.has(lower))
+                throw new Error("Memory ids differ only by letter case");
             seen.add(entry.id);
+            folded.add(lower);
         }
-        return entries;
+        this.files = nextFiles;
+        const snapshot = { entries, omitted, links: buildLinkGraph(entries) };
+        this.cached = { signature, snapshot };
+        return snapshot;
     }
+    async readNote(file, name) {
+        let raw;
+        // O_NOFOLLOW is undefined on Windows, which makes it 0 here: no error and
+        // no protection. The lstat above still rejects a link on every platform.
+        const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        try {
+            const stat = await handle.stat();
+            const limit = Math.max(256 * 1024, this.maxNoteBytes + MEMORY_SAFETY.fileOverheadBytes);
+            if (!stat.isFile() || stat.size > limit)
+                throw new Error("Invalid memory file");
+            raw = await handle.readFile("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+        // New writes use JSON-flow YAML metadata so quotes, colons and tags round-trip.
+        // Keep the original scalar frontmatter reader for existing local notes.
+        const jsonHeader = /^\uFEFF?---\r?\n(\{[^\n]+\})\r?\n---\r?\n([\s\S]*)$/.exec(raw);
+        if (jsonHeader) {
+            const metadata = JSON.parse(jsonHeader[1]);
+            return {
+                id: metadata.id, summary: metadata.summary, tags: metadata.tags,
+                ...(metadata.type !== undefined ? { type: metadata.type } : {}),
+                createdAt: metadata.createdAt, updatedAt: metadata.updatedAt, body: jsonHeader[2].trim(), file,
+            };
+        }
+        const { frontmatter, body } = splitFrontmatter(raw);
+        const summary = frontmatter["summary"]?.trim();
+        // Without a summary the entry cannot appear in the index, and an entry
+        // the model never sees is one it will never ask for.
+        if (!summary)
+            throw new Error("Memory note has no summary");
+        const type = frontmatter["type"]?.trim();
+        return {
+            id: frontmatter["id"]?.trim() || name.replace(/\.md$/, ""),
+            summary,
+            body: body.trim(),
+            tags: (frontmatter["tags"] ?? "").split(/[,\s]+/).map((tag) => tag.trim()).filter((tag) => tag !== ""),
+            ...(type ? { type: type } : {}),
+            createdAt: Number(frontmatter["createdAt"]) || 0,
+            updatedAt: Number(frontmatter["updatedAt"]) || 0,
+            file,
+        };
+    }
+    /**
+     * Write a note. With `id`, that note is updated and must exist. Without it,
+     * a note whose summary matches (ignoring case) is updated rather than
+     * duplicated, and otherwise a new one is created.
+     */
     async remember(input) {
-        if (typeof input.summary !== "string" || typeof input.body !== "string" || input.tags !== undefined && !Array.isArray(input.tags))
+        if (typeof input.summary !== "string" || typeof input.body !== "string" || (input.tags !== undefined && !Array.isArray(input.tags)) ||
+            (input.type !== undefined && !isMemoryType(input.type)) || (input.id !== undefined && !validMemoryId(input.id))) {
             throw new Error("Invalid memory note");
+        }
         return this.exclusive(async () => {
             await mkdir(this.dir, { recursive: true });
             const existing = await this.load();
-            // Re-learning the same lesson should update the note, not add a duplicate
-            // that competes with it in the index.
-            const match = existing.find((entry) => entry.summary.toLowerCase() === input.summary.trim().toLowerCase());
-            const id = match?.id ?? `${slug(input.summary)}-${shortId(3)}`;
-            if (!match && existing.length >= 500)
-                throw new Error("Memory limit: 500 notes per project");
+            const summary = input.summary.trim();
+            let match;
+            if (input.id !== undefined) {
+                match = existing.find((entry) => entry.id === input.id);
+                if (!match)
+                    throw new Error(`No memory note with id "${input.id}"`);
+            }
+            else {
+                // Re-learning the same lesson should update the note, not add a
+                // duplicate that competes with it in the index.
+                match = existing.find((entry) => entry.summary.toLowerCase() === summary.toLowerCase());
+            }
+            if (!match && existing.length >= this.maxNotes) {
+                throw new Error(`Memory limit: ${this.maxNotes} notes. Delete or merge notes before adding more.`);
+            }
+            const id = match?.id ?? `${slug(summary)}-${shortId(3)}`;
             const createdAt = match?.createdAt || Date.now();
             const file = match?.file ?? path.join(this.dir, `${id}.md`);
-            const note = { id, summary: input.summary.trim(), body: input.body.trim(), tags: input.tags ?? [], createdAt, updatedAt: Date.now() };
-            validateNote(note);
-            await this.atomic(file, encodeNote(note));
-            return {
-                id,
-                summary: input.summary.trim(),
-                body: input.body.trim(),
-                tags: input.tags ?? [],
-                createdAt,
-                file,
+            const type = input.type ?? match?.type;
+            const note = {
+                id, summary, body: input.body.trim(), tags: input.tags ? normalizeTags(input.tags) : match?.tags ?? [], createdAt, updatedAt: Date.now(),
+                ...(type ? { type } : {}),
             };
+            validateNote(note, this.maxNoteBytes);
+            await this.atomic(file, encodeNote(note));
+            this.emit(id, "local");
+            return { ...note, file };
         });
     }
     async forget(id) {
@@ -129,28 +293,38 @@ export class MemoryStore {
             if (!match)
                 return false;
             await rm(match.file, { force: true });
+            this.invalidate(match.file);
+            this.emit(id, "local");
             return true;
         });
     }
     /** Compare before applying downloaded data; never overwrite a concurrent edit. */
-    async apply(id, note, expected) {
+    async apply(id, note, expected, origin = "local") {
         if (!validMemoryId(id) || (note && note.id !== id))
             throw new Error("Invalid memory id");
         if (note)
-            validateNote(note);
+            validateNote(note, this.maxNoteBytes);
         await this.exclusive(async () => {
             const entries = await this.load(), current = entries.find((entry) => entry.id === id);
-            if (note && !current && entries.length >= 500)
-                throw new Error("Memory limit: 500 notes per project");
+            if (note && !current) {
+                if (entries.length >= this.maxNotes)
+                    throw new Error(`Memory limit: ${this.maxNotes} notes`);
+                if (entries.some((entry) => entry.id.toLowerCase() === id.toLowerCase()))
+                    throw new Error("Memory ids differ only by letter case");
+            }
             if (noteHash(current) !== expected)
-                throw new Error("本地记忆已改变，请重新同步。");
+                throw new MemoryError("localChanged");
             const file = current?.file ?? path.join(this.dir, id + ".md");
             if (!note) {
-                if (current)
+                if (current) {
                     await rm(file);
+                    this.invalidate(file);
+                    this.emit(id, origin);
+                }
                 return;
             }
             await this.atomic(file, encodeNote(note));
+            this.emit(id, origin);
         });
     }
     exclusive(action) {
@@ -161,6 +335,10 @@ export class MemoryStore {
             writes.delete(key); });
         return job;
     }
+    invalidate(file) {
+        this.cached = undefined;
+        this.files.delete(path.basename(file));
+    }
     async atomic(file, raw) {
         await mkdir(this.dir, { recursive: true });
         if ((await lstat(this.dir)).isSymbolicLink())
@@ -168,71 +346,194 @@ export class MemoryStore {
         const temp = path.join(this.dir, "." + randomUUID() + ".tmp");
         try {
             await writeFile(temp, raw, { mode: 0o600, flag: "wx" });
-            await rename(temp, file);
+            await renameWithRetry(temp, file);
         }
         finally {
             await rm(temp, { force: true });
+            this.invalidate(file);
         }
     }
-    /** Full-text search across summaries, bodies and tags. */
+    /** Notes as recall sees them, with this store's scope. Stable objects while a file is unchanged. */
+    scopedNotes(entries) {
+        return entries.map((entry) => {
+            let note = this.scoped.get(entry);
+            if (!note) {
+                note = {
+                    id: entry.id, summary: entry.summary, body: entry.body, tags: entry.tags, createdAt: entry.createdAt,
+                    ...(entry.updatedAt ? { updatedAt: entry.updatedAt } : {}),
+                    ...(entry.type ? { type: entry.type } : {}),
+                    scope: this.scope, entry,
+                };
+                this.scoped.set(entry, note);
+            }
+            return note;
+        });
+    }
+    /** Notes scored against a query, best first. */
+    async rank(query, options = {}) {
+        return rankNotes(this.scopedNotes(await this.load()), query, options);
+    }
+    /** Scored search across summaries, bodies and tags, falling back to plain substring matching. */
     async search(query) {
+        const ranked = await this.rank(query);
+        if (ranked.length)
+            return ranked.map((entry) => entry.note.entry);
         const needle = query.toLowerCase();
         return (await this.load()).filter((entry) => entry.summary.toLowerCase().includes(needle) ||
             entry.body.toLowerCase().includes(needle) ||
             entry.tags.some((tag) => tag.toLowerCase().includes(needle)));
     }
-    /**
-     * The index that goes into the system prompt: summaries only.
-     *
-     * Same reasoning as skills — putting every note's body in the prompt would
-     * grow without bound and crowd out the actual conversation. The model reads
-     * a summary, then asks for the body if it matters.
-     */
-    async promptSection() {
-        const loaded = await this.load();
-        if (loaded.length === 0)
-            return undefined;
-        /*
-         * Most recently touched first, which is not the order the notes are stored
-         * in.
-         *
-         * The budget below drops whatever does not fit, so this line decides which
-         * notes stop being visible once there are more than about fifty. Ordered by
-         * creation — the order load() returns, and the right one for a list someone
-         * is reading — the first to fall out is the oldest note, whether or not it
-         * is the one being re-learned every week. A note written a year ago and
-         * corrected on Tuesday is the more useful of the two, and updatedAt is the
-         * only thing here that knows that.
-         *
-         * Nothing is lost, only unlisted: the line at the end says how many, and
-         * the tool searches every note whether or not it is in the index.
-         */
-        const entries = [...loaded].sort((a, b) => (b.updatedAt ?? b.createdAt) - (a.updatedAt ?? a.createdAt));
-        const lines = [
+    /** The index for this store alone. See `memoryIndexSection`. */
+    async promptSection(indexChars = DEFAULT_MEMORY_POLICY.indexChars) {
+        return memoryIndexSection(this.scopedNotes(await this.load()), indexChars, { showScope: false });
+    }
+}
+async function renameWithRetry(from, to) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            await rename(from, to);
+            return;
+        }
+        catch (error) {
+            // On Windows a rename over a file an editor, indexer or antivirus has
+            // open fails for a moment with EPERM, EBUSY or EACCES and then succeeds.
+            const code = error.code ?? "";
+            if (process.platform !== "win32" || attempt >= 5 || !["EPERM", "EBUSY", "EACCES"].includes(code))
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, 25 * (attempt + 1)));
+        }
+    }
+}
+const scopedCache = new WeakMap();
+/**
+ * Both scopes loaded as one list, project notes first, with links resolved
+ * across the two: a note in either may link to a note in the other.
+ */
+export async function loadScoped(stores) {
+    const project = await stores.project.snapshot();
+    const user = stores.user ? await stores.user.snapshot() : undefined;
+    const cached = scopedCache.get(stores);
+    if (cached && cached.project === project && cached.user === user)
+        return cached.value;
+    const notes = [...stores.project.scopedNotes(project.entries), ...(stores.user && user ? stores.user.scopedNotes(user.entries) : [])];
+    const value = { notes, links: buildLinkGraph(notes), omitted: project.omitted + (user?.omitted ?? 0) };
+    scopedCache.set(stores, { project, ...(user ? { user } : {}), value });
+    return value;
+}
+/** A note by id, project scope first. */
+export function findScoped(notes, id) {
+    return notes.find((note) => note.id === id && note.scope === "project") ?? notes.find((note) => note.id === id);
+}
+export function storeFor(stores, scope) {
+    if (scope === "user") {
+        if (!stores.user)
+            throw new Error("User-level memory is unavailable on this machine");
+        return stores.user;
+    }
+    return stores.project;
+}
+export const MEMORY_GUIDANCE = [
+    "Record with `remember` when:",
+    "- the user corrects you, or confirms an approach that was not obvious;",
+    "- the user states a preference about how to work;",
+    "- you learn something about the project that the code and git history do not record: a decision and its reason, a constraint, where something external lives.",
+    "Do not record what the code or git history already says, what only matters to the current task, or any credential.",
+    "Tag each note with the words someone might use instead of the summary's: synonyms, and the term in the other language in use (for example border, 边框, 描边). Recall matches words, not meaning.",
+    "Before adding a note, look at the related notes `remember` returns: update an existing note by passing its `id` rather than adding a near-duplicate, and link related notes in the body as [[note-id]].",
+    "A note that names a file, function or setting may be out of date. Confirm it still holds before acting on it, and update or `forget` a note that turns out to be wrong.",
+    "Scope defaults to `project`, and to `user` only for notes of type `user`. Put a correction or preference in scope `user` only when it plainly holds in every project; one about how this codebase is worked on stays in `project`.",
+].join("\n");
+/**
+ * The index that goes into the system prompt: one line per note, summaries only.
+ *
+ * Same reasoning as skills — putting every note's body in the prompt would
+ * grow without bound and crowd out the actual conversation. The model reads a
+ * summary, then asks for the body if it matters; notes that match a message
+ * are attached to it without being asked for.
+ *
+ * Most recently touched first, which is not the order the notes are stored in.
+ * The budget drops whatever does not fit, so this ordering decides which notes
+ * stop being listed once there are more than about fifty. A note written a year
+ * ago and corrected on Tuesday is the more useful of the two, and updatedAt is
+ * the only thing here that knows that. Nothing is lost, only unlisted: the line
+ * at the end says how many, and the tool searches every note.
+ */
+export function memoryIndexSection(notes, indexChars, options) {
+    if (!notes.length) {
+        // With nothing to list, the full guidance would be paid for on every
+        // request to repeat what the tool descriptions say. Enough to know when to write.
+        return [
             "## Memory",
             "",
-            "Lessons recorded in earlier sessions. Read the full note with the `memory` tool",
-            "before acting on one — these are summaries, not the whole story.",
-            "",
-        ];
-        let budget = MAX_PROMPT_CHARS;
-        let omitted = 0;
-        for (const entry of entries) {
-            const line = `- \`${entry.id}\` — ${entry.summary}`;
-            if (line.length > budget) {
-                omitted++;
-                continue;
-            }
-            lines.push(line);
-            budget -= line.length;
+            "No notes recorded yet. Use `remember` when the user corrects you, states a preference, or tells you something about the project that the code does not show. Never record credentials.",
+        ].join("\n");
+    }
+    const lines = [
+        "## Memory",
+        "",
+        "Notes recorded in earlier sessions. These are summaries: read a note with the `memory` tool",
+        "before acting on it. Notes that match a user message are also attached to that message",
+        "inside <recalled-memory>.",
+        "",
+        MEMORY_GUIDANCE,
+        "",
+    ];
+    const ordered = [...notes].sort((a, b) => (b.updatedAt ?? b.createdAt) - (a.updatedAt ?? a.createdAt));
+    let budget = indexChars;
+    let omitted = 0;
+    for (const note of ordered) {
+        const labels = [options.showScope ? note.scope : undefined, note.type].filter(Boolean);
+        const line = `- \`${note.id}\`${labels.length ? ` (${labels.join(" · ")})` : ""} — ${note.summary}`;
+        if (line.length > budget) {
+            omitted++;
+            continue;
         }
-        if (omitted > 0)
-            lines.push(`- … ${omitted} older notes; search them with the \`memory\` tool.`);
-        return lines.join("\n");
+        lines.push(line);
+        budget -= line.length;
     }
+    if (omitted > 0)
+        lines.push(`- … ${omitted} older notes; search them with the \`memory\` tool.`);
+    return lines.join("\n");
+}
+/** Recall across both scopes, rendered for attaching to a user message. */
+export async function recallFromStores(stores, input, policy, usage) {
+    if (!policy.enabled || policy.perTurn <= 0)
+        return undefined;
+    const { notes, links } = await loadScoped(stores);
+    if (!notes.length)
+        return undefined;
+    const byId = new Map();
+    for (const note of [...notes].reverse())
+        byId.set(note.id, note);
+    const ranked = rankNotes(notes, recallQuery(input.prompt, input.context), {
+        exclude: input.exclude,
+        usage: (id) => (byId.get(id)?.scope === "user" ? usage?.user : usage?.project)?.get(id),
+    });
+    const chosen = selectRecall(ranked, policy);
+    if (!chosen.length)
+        return undefined;
+    const chosenIds = new Set(chosen.map((entry) => entry.note.id));
+    const items = chosen.map(({ note }) => ({
+        note,
+        related: (links.outgoing.get(note.id) ?? [])
+            .filter((id) => !chosenIds.has(id) && !input.exclude.has(id))
+            .map((id) => byId.get(id))
+            .filter((entry) => entry !== undefined)
+            .slice(0, 5)
+            .map((entry) => ({ id: entry.id, summary: entry.summary })),
+    }));
+    usage?.project?.record(chosen.filter((entry) => entry.note.scope === "project").map((entry) => entry.note.id));
+    usage?.user?.record(chosen.filter((entry) => entry.note.scope === "user").map((entry) => entry.note.id));
+    return {
+        text: renderRecall(items, policy.budgetChars),
+        items: chosen.map(({ note }) => ({ id: note.id, summary: note.summary, scope: note.scope })),
+    };
 }
 function encodeNote(note) {
-    const metadata = { id: note.id, summary: note.summary, tags: note.tags, createdAt: note.createdAt, updatedAt: note.updatedAt ?? Date.now() };
+    const metadata = {
+        id: note.id, summary: note.summary, ...(note.type ? { type: note.type } : {}), tags: note.tags,
+        createdAt: note.createdAt, updatedAt: note.updatedAt ?? Date.now(),
+    };
     return "---\n" + JSON.stringify(metadata) + "\n---\n" + note.body + "\n";
 }
 function slug(value) {