mocode-ai 0.1.3 → 0.1.5

package/dist/memory/reflect.js

@@ -0,0 +1,265 @@
+// memory 反思 pass:后台异步复盘近期会话 + 现有记忆,产出 saves/updates/forgets 落地。
+// 依赖 llm(chat)——同 session/compact.ts 模式,非环(llm 不反向依赖 memory)。
+// store.ts 仍是叶子;本模块是 memory 子系统里唯一调 LLM 的部分。
+//
+// 异步与静默:kickoffReflection fire-and-forget(repl 轮末调),与下一轮 agent 并发跑;
+// 期间不碰 contentWrite / 状态行(否则与 RUNNING 态 agent 争屏)。结果缓存到 lastReflectResult,
+// repl 在下次进 INPUT 态的安全点 flush 一行 dim 摘要。错误写 <cwd>/.mocode/memory.log。
+//
+// 并发安全:store 读写全同步(单 tick 原子),本模块里唯一让出事件循环的是 await chat();
+// 其前后的 store 调用不会与 agent 的 store 调用交错(单线程 + await 间不重叠)→ 无竞态。
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { chat } from '../llm/index.js';
+import { config } from '../config/index.js';
+import { saveEntry, updateEntry, forgetEntry, loadAll, gcMemories, } from './store.js';
+// ── 日志(静默容错,裁尾保最近)─────────────────────────────────────────────
+function logPath() {
+    return path.join(process.cwd(), '.mocode', 'memory.log');
+}
+function appendLog(line) {
+    try {
+        const p = logPath();
+        const dir = path.dirname(p);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        let content = '';
+        if (existsSync(p))
+            content = readFileSync(p, 'utf8');
+        content = (content + '\n' + line).slice(-20000);
+        writeFileSync(p, content, 'utf8');
+    }
+    catch {
+        // 静默:日志失败不阻断
+    }
+}
+// ── 转录快照(同步,避免下一轮 mutate history 的竞态)─────────────────────────
+function textOf(c) {
+    if (typeof c === 'string')
+        return c;
+    if (c == null)
+        return '';
+    if (Array.isArray(c)) {
+        return c
+            .map((p) => (typeof p === 'string' ? p : p?.text ?? ''))
+            .join('');
+    }
+    return String(c);
+}
+/**
+ * 同步拍平最近 K 条对话(跳过 history[0] 大系统提示)。每条裁到 600 字符、总体裁到 6000,
+ * 控制反思 prompt 体积。在 kickoff 调用前同步取快照,异步 pass 用这份文本,不再读 history。
+ */
+export function snapshotTranscript(history, K) {
+    const convo = history.slice(1).slice(-K);
+    const lines = convo.map((m) => {
+        const role = m.role ?? '?';
+        let line = `${role}: ${textOf(m.content)}`;
+        const tcs = m
+            .tool_calls;
+        if (Array.isArray(tcs)) {
+            for (const tc of tcs) {
+                line += `\n  [tool_call ${tc?.function?.name ?? ''}] ${tc?.function?.arguments ?? ''}`;
+            }
+        }
+        if (line.length > 600)
+            line = line.slice(0, 586) + '…[截断]';
+        return line;
+    });
+    const joined = lines.join('\n');
+    if (joined.length <= 6000)
+        return joined;
+    return joined.slice(0, 5980) + '\n…[转录已截断]';
+}
+// ── 记忆样本(供 LLM 判断 update/forget)──────────────────────────────────────
+function buildMemorySample() {
+    const all = loadAll().filter((e) => e.status === 'active');
+    if (all.length === 0)
+        return '(无)';
+    const byCreated = [...all].sort((a, b) => (a.createdAt || '').localeCompare(b.createdAt || ''));
+    const byRecall = [...all].sort((a, b) => a.recallCount - b.recallCount);
+    const picked = new Map();
+    for (const e of byCreated.slice(0, 10))
+        picked.set(e.id, e);
+    for (const e of byRecall.slice(0, 10))
+        picked.set(e.id, e);
+    const list = [...picked.values()].slice(0, 20);
+    return list
+        .map((e) => {
+        const body = e.body.length > 600 ? e.body.slice(0, 586) + '…[截断]' : e.body;
+        return `[${e.id}] ${e.name} (${e.type}, recalled ${e.recallCount})\nsummary: ${e.summary}\nbody: ${body}`;
+    })
+        .join('\n---\n');
+}
+const TYPES = 'decision | fact | pitfall | reference | feedback';
+const REFLECT_SYS = `You are mocode's memory reflector. Review the recent session and existing memories, producing **only** updates worth remembering long-term.
+Output strictly JSON (no markdown code blocks, no explanatory text): {"saves":[{"type":"...","name":"...","summary":"...","body":"..."}],"updates":[{"id":"...","reason":"...","summary":"...","body":"..."}],"forgets":[{"id":"...","reason":"..."}]}
+Empty arrays are valid (if nothing is worth saving, all three arrays are empty).
+Rules:
+① Only store non-obvious, cross-session-useful facts/decisions/pitfalls; do not store current bugs, temp files, undecided TODOs, or volatile items;
+② Better to store less than to store trivially correct info (e.g. "keep it concise");
+③ ids in updates/forgets must come from the "existing memories" list below; do not fabricate ids not listed there;
+④ names in saves must be concise and not collide with existing ones; type ∈ {${TYPES}};
+⑤ If an existing memory contradicts new facts or is outdated, update the old entry (modify summary/body) rather than creating a duplicate;
+⑥ forgets are for memories clearly stale / superseded by a new entry (archive, not hard-delete).`;
+const REFLECT_USER = (transcript, sample) => `## Recent session\n${transcript}\n\n## Existing memories\n${sample}\n\nProduce JSON:`;
+function parsePlan(content) {
+    if (!content)
+        return null;
+    let s = content.trim();
+    // 去 ```json … ``` 代码块(模型偶发包裹)
+    const fence = s.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (fence)
+        s = fence[1].trim();
+    // 容错:截到首个 { 到末个 }
+    const first = s.indexOf('{');
+    const last = s.lastIndexOf('}');
+    if (first >= 0 && last > first)
+        s = s.slice(first, last + 1);
+    try {
+        const p = JSON.parse(s);
+        if (!p || typeof p !== 'object')
+            return null;
+        return p;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 跑一次反思:chat() 空 handlers(静默)→ 解析 JSON → 经 store 落地 → gcMemories。
+ * 解析失败整 pass 放弃(不部分落地)。store 调用全同步,落地是一个原子块。
+ * 60s 超时(AbortSignal.timeout)防 exit 时 drain 挂死。
+ */
+export async function runReflection(transcript, signal) {
+    const ts = new Date().toISOString();
+    const sample = buildMemorySample();
+    const sys = { role: 'system', content: REFLECT_SYS };
+    const user = { role: 'user', content: REFLECT_USER(transcript, sample) };
+    let result = {
+        ts,
+        saves: 0,
+        updates: 0,
+        forgets: 0,
+        gcDecayed: 0,
+        gcCapped: 0,
+        gcGced: 0,
+    };
+    let content = null;
+    try {
+        const r = await chat([sys, user], {}, signal ?? AbortSignal.timeout(60000));
+        // 推理模型偶发只返 reasoning_content(content null)或幻觉 tool_calls → 视为无产出
+        if (!r.toolCalls.length && r.content)
+            content = r.content;
+    }
+    catch (e) {
+        result.error = e instanceof Error ? e.name + ': ' + e.message : String(e);
+        return result;
+    }
+    const plan = parsePlan(content);
+    if (!plan) {
+        result.error = 'parse-failed';
+        return result;
+    }
+    let saves = 0;
+    let updates = 0;
+    let forgets = 0;
+    if (Array.isArray(plan.saves)) {
+        for (const s of plan.saves) {
+            if (!s?.name || !s?.summary)
+                continue;
+            const r = saveEntry({
+                name: String(s.name),
+                summary: String(s.summary),
+                body: String(s.body ?? s.summary),
+                type: normalizeType(s.type),
+            });
+            if (r.ok)
+                saves++;
+        }
+    }
+    if (Array.isArray(plan.updates)) {
+        for (const u of plan.updates) {
+            if (!u?.id)
+                continue;
+            const r = updateEntry(String(u.id), {
+                summary: u.summary ? String(u.summary) : undefined,
+                body: u.body ? String(u.body) : undefined,
+                reason: u.reason ? String(u.reason) : undefined,
+            });
+            if (r.ok)
+                updates++;
+        }
+    }
+    if (Array.isArray(plan.forgets)) {
+        for (const f of plan.forgets) {
+            if (!f?.id)
+                continue;
+            const r = forgetEntry(String(f.id), 'archive');
+            if (r.ok)
+                forgets++;
+        }
+    }
+    const gc = gcMemories();
+    result = { ...result, saves, updates, forgets, gcDecayed: gc.decayed, gcCapped: gc.capped, gcGced: gc.gced };
+    return result;
+}
+function normalizeType(t) {
+    if (typeof t !== 'string')
+        return undefined;
+    const v = t.trim().toLowerCase();
+    if (v === 'decision' || v === 'fact' || v === 'pitfall' || v === 'reference' || v === 'feedback')
+        return v;
+    return undefined;
+}
+// ── 后台编排:kickoff / drain / 缓存 ─────────────────────────────────────────
+let inflight = null;
+let lastReflectResult = null;
+/** 摘要串(供 repl flush):存N 改N 忘N;有错误附上。 */
+export function formatReflectResult(r) {
+    const parts = [`存${r.saves}`, `改${r.updates}`, `忘${r.forgets}`];
+    if (r.gcDecayed || r.gcCapped || r.gcGced) {
+        parts.push(`遗忘(衰减${r.gcDecayed}/封顶${r.gcCapped}/清除${r.gcGced})`);
+    }
+    return `记忆反思:${parts.join(' ')}${r.error ? ` [${r.error}]` : ''}`;
+}
+/**
+ * fire-and-forget 触发反思。已有在飞任务 / autoReflect 关闭 → 跳过。
+ * repl 轮末调:与下一轮 agent 并发跑,不阻塞。
+ */
+export function kickoffReflection(transcript) {
+    if (inflight)
+        return;
+    if (!config.autoReflect)
+        return;
+    inflight = (async () => {
+        try {
+            const r = await runReflection(transcript);
+            lastReflectResult = r;
+            appendLog(`[${r.ts}] ${formatReflectResult(r)}`);
+        }
+        catch (e) {
+            appendLog(`[${new Date().toISOString()}] 反思异常: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        finally {
+            inflight = null;
+        }
+    })();
+}
+/** 退出前等在飞反思收尾(startRepl 尾调;Ctrl+C 走 SIGINT 直退不等)。 */
+export async function drainMemoryBackground() {
+    if (inflight) {
+        try {
+            await inflight;
+        }
+        catch {
+            // 已在 kickoff 内 log
+        }
+    }
+}
+export function getLastReflectResult() {
+    return lastReflectResult;
+}
+export function clearLastReflectResult() {
+    lastReflectResult = null;
+}

package/dist/memory/store.js

@@ -0,0 +1,339 @@
+// memory 工具库(Tier-2):JSONL 存储 + CRUD + 遗忘 GC + 索引段。
+// 叶子模块:仅依赖 node 标准库 + tools/constants(常量叶子),不反向依赖 agent/llm/skills/config/ui,
+// 避免环(反思 pass 要调 LLM,单独放 reflect.ts,同 session/ 模式)。
+//
+// 约定:一行一条 JSON(JSONL)。突变统一走「整文件读改写 + tmp+rename 原子落盘」(对齐
+// discover.ts/persist.ts 的同步 fs 风格)。所有读写全同步(无 await),单 tick 原子——反思里唯一让出
+// 事件循环的是 chat(),其前后的 store 读写不会与 agent 的 store 调用交错(单线程 + await 间不重叠)→ 无竞态、无锁。
+//
+// 两文件:全局 ~/.mocode/memory.jsonl + 项目 <cwd>/.mocode/memory.jsonl(镜像 resolveMemoryFiles
+// 的 global+cwd 与 sessionDir 的 cwd 习惯)。条目带 scope 字段标识归属,loadAll 时按文件归一化。
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { MAX_ACTIVE, MAX_INDEX_ENTRIES, MAX_MEMORY_ENTRY, DECAY_DAYS, GC_DAYS, } from '../tools/constants.js';
+// ── 路径 ──────────────────────────────────────────────────────────────────
+function globalPath() {
+    return path.join(os.homedir(), '.mocode', 'memory.jsonl');
+}
+function projectPath() {
+    return path.join(process.cwd(), '.mocode', 'memory.jsonl');
+}
+function pathForScope(scope) {
+    return scope === 'global' ? globalPath() : projectPath();
+}
+function ensureDir(p) {
+    const dir = path.dirname(p);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+}
+// ── 原子写 / 同步读 ───────────────────────────────────────────────────────
+/** 整文件原子落盘:写 tmp 再 rename(POSIX 原子;Windows rename 覆盖既有文件)。空数组写空文件。 */
+function writeAtomic(p, entries) {
+    const lines = entries.map((e) => JSON.stringify(e)).join('\n');
+    const tmp = p + '.tmp';
+    writeFileSync(tmp, lines, 'utf8');
+    renameSync(tmp, p);
+}
+/** 读一个文件的条目(静默容错:不存在 / 读失败 / 行非法 → 跳过,不抛)。 */
+function readFileEntries(p) {
+    if (!existsSync(p))
+        return [];
+    let content;
+    try {
+        content = readFileSync(p, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    if (!content.trim())
+        return [];
+    const out = [];
+    for (const line of content.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const e = JSON.parse(line);
+            if (e && typeof e.id === 'string')
+                out.push(e);
+        }
+        catch {
+            continue; // 单行损坏跳过,不连累全文件
+        }
+    }
+    return out;
+}
+/** 加载全部(global + project),按文件归一化 scope(防旧条目缺字段 / 字段错)。 */
+export function loadAll() {
+    const out = [];
+    for (const scope of ['global', 'project']) {
+        for (const e of readFileEntries(pathForScope(scope))) {
+            e.scope = scope; // 归一化:以实际所在文件为准
+            out.push(e);
+        }
+    }
+    return out;
+}
+/** 按 scope 分组写回:仅写有条目或文件已存在的 scope(避免凭空建空文件)。 */
+function writeBackByScope(all) {
+    for (const scope of ['global', 'project']) {
+        const entries = all.filter((e) => e.scope === scope);
+        const p = pathForScope(scope);
+        if (entries.length === 0 && !existsSync(p))
+            continue;
+        ensureDir(p);
+        writeAtomic(p, entries);
+    }
+}
+// ── 工具:slugify / 截断 ───────────────────────────────────────────────────
+let slugCounter = 0;
+/** name → ASCII slug;空(纯 CJK 等)则 m+时间戳+计数防同毫秒碰撞。 */
+function slugify(name) {
+    const s = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (s)
+        return s;
+    slugCounter++;
+    return 'm' + Date.now().toString(36) + slugCounter.toString(36);
+}
+function truncateBody(body) {
+    if (body.length <= MAX_MEMORY_ENTRY)
+        return body;
+    const removed = body.length - MAX_MEMORY_ENTRY;
+    const marker = `…[已截断 ${removed} 字符]…`;
+    return body.slice(0, Math.max(0, MAX_MEMORY_ENTRY - marker.length)) + marker;
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+/** 新建:id 全局唯一(跨两文件),撞库返 exists 让工具层提示用 memory_update。 */
+export function saveEntry(input) {
+    const id = slugify(input.name);
+    const all = loadAll();
+    if (all.some((e) => e.id === id))
+        return { ok: false, exists: id };
+    const scope = input.scope === 'global' ? 'global' : 'project';
+    const now = nowIso();
+    const entry = {
+        id,
+        type: input.type ?? 'fact',
+        name: input.name,
+        summary: input.summary,
+        body: truncateBody(input.body),
+        createdAt: now,
+        updatedAt: now,
+        lastRecalledAt: null,
+        recallCount: 0,
+        status: 'active',
+        supersededBy: null,
+        pinned: !!input.pinned,
+        scope,
+        source: input.source ?? null,
+    };
+    const p = pathForScope(scope);
+    const fileEntries = readFileEntries(p);
+    fileEntries.push(entry);
+    ensureDir(p);
+    writeAtomic(p, fileEntries);
+    return { ok: true, id };
+}
+function scoreEntry(e, terms) {
+    if (terms.length === 0)
+        return 1; // 无关键词:全命中(取前 limit)
+    const id = e.id.toLowerCase();
+    const name = e.name.toLowerCase();
+    const summary = e.summary.toLowerCase();
+    const body = e.body.toLowerCase();
+    let s = 0;
+    for (const t of terms) {
+        if (id.includes(t))
+            s += 8; // 含 id 匹配:模型常按索引里的 id 取详情(slug 带连字符,名字带空格,不单独匹配 id 会漏)
+        if (name.includes(t))
+            s += 10;
+        if (summary.includes(t))
+            s += 5;
+        if (body.includes(t))
+            s += 1;
+    }
+    return s;
+}
+/** 关键词搜索:多词子串匹配(name 权重最高)。命中即 bump recallCount/lastRecalledAt 写回(遗忘衰减依据)。 */
+export function searchEntries(query, opts = {}) {
+    const all = loadAll();
+    const status = opts.status ?? 'active';
+    const pool = all.filter((e) => (status === 'any' ? true : e.status === status))
+        .filter((e) => (opts.type ? e.type === opts.type : true));
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const scored = pool
+        .map((e) => ({ e, s: scoreEntry(e, terms) }))
+        .filter((x) => x.s > 0);
+    scored.sort((a, b) => b.s - a.s);
+    const limit = Math.max(1, Math.min(opts.limit ?? 5, 20));
+    const top = scored.slice(0, limit);
+    if (top.length === 0)
+        return [];
+    // bump recall:只写有命中的 scope 文件
+    const now = nowIso();
+    const hitIds = new Set(top.map((x) => x.e.id));
+    for (const e of all) {
+        if (hitIds.has(e.id)) {
+            e.recallCount++;
+            e.lastRecalledAt = now;
+        }
+    }
+    const hitScopes = new Set(top.map((x) => x.e.scope));
+    for (const scope of hitScopes) {
+        const p = pathForScope(scope);
+        const entries = all.filter((e) => e.scope === scope);
+        ensureDir(p);
+        writeAtomic(p, entries);
+    }
+    return top.map((x) => x.e);
+}
+/** 索引(无 body、不 bump recall)。 */
+export function listEntries(opts = {}) {
+    const status = opts.status ?? 'active';
+    return loadAll()
+        .filter((e) => (status === 'any' ? true : e.status === status))
+        .filter((e) => (opts.type ? e.type === opts.type : true))
+        .map((e) => ({ id: e.id, name: e.name, summary: e.summary, type: e.type, status: e.status }));
+}
+/** 原地改:id 不变(name 可改 → 但 id 仍是旧 slug,故 name 改不会触发重 slug);记 lastUpdateReason;pinned 可切换。 */
+export function updateEntry(id, patch) {
+    const all = loadAll();
+    const e = all.find((x) => x.id === id);
+    if (!e)
+        return { ok: false, notFound: true };
+    if (patch.name)
+        e.name = patch.name;
+    if (patch.summary)
+        e.summary = patch.summary;
+    if (patch.body)
+        e.body = truncateBody(patch.body);
+    if (patch.reason)
+        e.lastUpdateReason = patch.reason;
+    if (patch.pinned !== undefined)
+        e.pinned = patch.pinned;
+    e.updatedAt = nowIso();
+    const p = pathForScope(e.scope);
+    const entries = all.filter((x) => x.scope === e.scope);
+    ensureDir(p);
+    writeAtomic(p, entries);
+    return { ok: true };
+}
+/** 归档(默认,可复活)/ 硬删;pinned 拒删。 */
+export function forgetEntry(id, mode = 'archive') {
+    const all = loadAll();
+    const e = all.find((x) => x.id === id);
+    if (!e)
+        return { ok: false, notFound: true };
+    if (e.pinned)
+        return { ok: false, pinned: true };
+    const p = pathForScope(e.scope);
+    let entries = all.filter((x) => x.scope === e.scope);
+    if (mode === 'delete') {
+        entries = entries.filter((x) => x.id !== id);
+    }
+    else {
+        const t = entries.find((x) => x.id === id);
+        if (t) {
+            t.status = 'archived';
+            t.updatedAt = nowIso();
+        }
+    }
+    ensureDir(p);
+    writeAtomic(p, entries);
+    return { ok: true, mode };
+}
+// ── 遗忘 GC(纯数据,不调 LLM)─────────────────────────────────────────────
+const DAY_MS = 86400000;
+/**
+ * 遗忘策略(全同步,后台调):
+ *  ① archived 超 GC_DAYS → 硬删;
+ *  ② active + !pinned + (lastRecalledAt|createdAt) 早于 DECAY_DAYS → archived;
+ *  ③ active 数 > MAX_ACTIVE → 按 recallCount 低 × 最近未召回久 淘汰到 archived。
+ * pinned 豁免一切自动衰减。写回两文件(均按 scope 过滤)。
+ */
+export function gcMemories() {
+    const all = loadAll();
+    if (all.length === 0)
+        return { decayed: 0, capped: 0, gced: 0 };
+    const now = Date.now();
+    const decayMs = DECAY_DAYS * DAY_MS;
+    const gcMs = GC_DAYS * DAY_MS;
+    const result = { decayed: 0, capped: 0, gced: 0 };
+    const refTs = (e) => {
+        const r = e.lastRecalledAt ? Date.parse(e.lastRecalledAt) : Date.parse(e.createdAt);
+        return Number.isFinite(r) ? r : now;
+    };
+    // ① archived GC
+    for (const e of all) {
+        if (e.status !== 'archived')
+            continue;
+        const u = Date.parse(e.updatedAt || e.createdAt);
+        if (Number.isFinite(u) && now - u > gcMs) {
+            e.status = '__DELETE__'; // 标记硬删(下方过滤)
+            result.gced++;
+        }
+    }
+    // ② decay
+    for (const e of all) {
+        if (e.status !== 'active' || e.pinned)
+            continue;
+        if (now - refTs(e) > decayMs) {
+            e.status = 'archived';
+            e.updatedAt = nowIso();
+            result.decayed++;
+        }
+    }
+    // ③ cap active
+    const active = all
+        .filter((e) => e.status === 'active')
+        .sort((a, b) => a.recallCount - b.recallCount || refTs(a) - refTs(b));
+    const excess = active.length - MAX_ACTIVE;
+    if (excess > 0) {
+        for (let i = 0; i < excess; i++) {
+            const e = active[i];
+            if (e.pinned)
+                continue; // 双保险:排序后仍跳过 pinned
+            e.status = 'archived';
+            e.updatedAt = nowIso();
+            result.capped++;
+        }
+    }
+    // 写回:剔除 __DELETE__ 标记
+    const survivors = all.filter((e) => e.status !== '__DELETE__');
+    // 仅当确有变化才写(避免每次 gc 都重写)
+    if (result.gced === 0 && result.decayed === 0 && result.capped === 0)
+        return result;
+    writeBackByScope(survivors);
+    return result;
+}
+// ── 启动索引段(注入 systemPrompt,同步)────────────────────────────────────
+/**
+ * active 条目按 updatedAt 降序,封顶 MAX_INDEX_ENTRIES,只注 id/name/summary/type。
+ * 无 active 返空串(零行为变化)。body 不注入——按需 memory_search 取。
+ */
+export function buildMemoryIndexSection() {
+    const active = loadAll()
+        .filter((e) => e.status === 'active')
+        .sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || ''));
+    if (active.length === 0)
+        return '';
+    const shown = active.slice(0, MAX_INDEX_ENTRIES);
+    const lines = shown.map((e) => `- ${e.id}: ${e.name} — ${e.summary} (${e.type})`);
+    const tail = active.length > MAX_INDEX_ENTRIES
+        ? `\n\n…(${active.length} total, showing first ${MAX_INDEX_ENTRIES}; use memory_search <id or keyword> for more)`
+        : '';
+    return [
+        '',
+        '',
+        '## Memory Index (retrieve full body via memory_search)',
+        'The following are saved memory entries (title/summary only). Retrieve full body via memory_search (pass id or keyword); use memory_list to see all,'
+            + ' memory_update to modify, memory_forget to archive. This list is a startup snapshot; entries added during the session are not listed here — use memory_list/memory_search to find them.',
+        ...lines,
+        tail,
+    ].join('\n');
+}