mocode-ai 0.1.3 → 0.1.4

package/dist/repl/index.js

@@ -6,12 +6,13 @@ import { runAgent } from '../agent/index.js';
 import { ui } from '../ui/theme.js';
 import { bannerString, displayWidth, padEndDisplay, summarizeToolCall, summarizeToolResult } from '../ui/render.js';
 import * as layout from '../ui/layout.js';
-import { promptWithSlashMenu, promptTurnPicker } from '../ui/prompt.js';
+import { promptWithSlashMenu, promptTurnPicker, promptSessionPicker, } from '../ui/prompt.js';
 import { tools } from '../tools/registry.js';
 import { estimateMessagesTokens, estimateToolSchemaTokens, } from '../llm/index.js';
 import { compactHistory, contextState, newSessionId, saveSession, loadSession, listSessions, } from '../session/index.js';
 import { listTurns, planRollback, applyRollback, persistSnapshots, loadSnapshots, rebuildFromHistory, resetState, } from '../rollback/index.js';
 import { listSkills, effectiveSystemPrompt } from '../skills/index.js';
+import { buildMemorySection, buildMemoryIndexSection, kickoffReflection, drainMemoryBackground, getLastReflectResult, clearLastReflectResult, snapshotTranscript, formatReflectResult, loadAll, } from '../memory/index.js';
 /**
  * readline 的 prompt 必须是纯文本(无 ANSI):readline 按字符数算光标位置,
  * 颜色码会让光标错位、编辑时漂移。颜色只用在直接 stdout.write 的横幅 / 工具行 / 回复。
@@ -27,7 +28,39 @@ const SLASH_COMMANDS = [
     { name: '/resume', desc: '续接已保存的会话' },
     { name: '/think', desc: '展开折叠思考段(/think N)' },
     { name: '/rollback', desc: '菜单选轮次回滚(↑↓·Enter)' },
+    { name: '/memory', desc: '记忆库:条目计数与近期索引' },
+    { name: '/reflect', desc: '手动触发后台记忆反思 pass' },
+    { name: '/init', desc: '扫描项目生成 MOCODE.md 项目记忆' },
 ];
+/**
+ * /init 指令:发给 agent 扫描项目并生成 MOCODE.md(对标 Claude Code /init 生成 CLAUDE.md,
+ * 但 mocode 读 MOCODE.md)。已存在则让 agent 读后更新(不丢失事实)。写完供 memory 子系统下轮加载。
+ */
+const INIT_PROMPT = `分析当前项目(process.cwd()),生成 MOCODE.md 项目记忆文件,供 mocode 后续会话自动加载——目标是让后续会话无需重新摸索就能上手。
+
+先探查(尽量少调用拿全貌):
+- read_file package.json(或 Cargo.toml/pyproject.toml/go.mod 等):scripts、依赖、入口、模块类型。
+- glob 顶层目录;read_file 入口文件 + 各子系统 index.ts/README。
+- 若有 .codegraph/:run_command codegraph explore "<架构或入口符号>" 一次拿相关源码+调用路径,别逐文件读。
+- 若 MOCODE.md 已存在:read_file 读它,在其基础上更新(补缺、修正过时),不丢已有准确事实。
+
+MOCODE.md 按以下结构写(每节简短,只写稳定、非显然的事实):
+## 项目
+一两句:是什么、技术栈、运行环境。
+## 命令
+install / dev / build / test / typecheck / lint 等——从 package.json scripts 提炼,写原样命令行(如 \`npm run typecheck\`);没有的注明"无测试"/"无 lint"。
+## 目录结构
+顶层各目录与子系统职责,一句话/个;不逐文件列。
+## 约定
+从代码与现有文档提炼的硬约定:模块系统(ESM?)、命名、错误处理、工具/函数契约、易踩坑点。只写非显然、会让人踩坑的;不写"保持简洁"这种正确废话。
+## 扩展点
+加工具/命令/provider/模块的接缝(改哪个文件、加在哪)。
+
+硬要求:
+- 从实际代码提炼,引用具体文件名/命令/符号;不编造、不泛泛。
+- 总长 ≤ 1500 字;只写后续会话有用的稳定事实,不写易变项(当前 bug、临时文件、未决 TODO)。
+- 用 write_file 写入项目根 MOCODE.md。
+- 写完简述:写了哪几节 + 从代码里发现的 2-3 条非显然关键约定(供用户校验)。`;
 /** 临时 readline 读一行(cooked,用于子提问;主输入走 promptWithSlashMenu)。 */
 async function askLine(prompt) {
     const rl = readline.createInterface({ input: stdin, output: stdout });
@@ -84,10 +117,14 @@ function runningStateFor(cmd) {
             return { status: '续接', placeholder: '选择会话…' };
         case '/rollback':
             return { status: '回滚', placeholder: '选择轮次…' };
+        case '/init':
+            return { status: '初始化', placeholder: '生成 MOCODE.md…' };
         case '/clear':
             return { status: '清空', placeholder: '…' };
         default:
-            return { status: '处理', placeholder: '思考中… Ctrl+C 中断' };
+            // 输入框留空(运行中可 typeahead 打字,dim 回显);运行状态由状态行 spinner 承载,
+            // 不再把「思考中… Ctrl+C 中断」塞进输入框占位——避免看起来像已有输入、妨碍正常输入。
+            return { status: '处理', placeholder: '' };
     }
 }
 const emitter = stdin;
@@ -265,7 +302,7 @@ export function renderHistory(history) {
 export async function startRepl(initialHistory, sessionId, updateNotice = null) {
     // 有预加载(--resume)则用它,并把 history[0] 刷成当前 system prompt(config 可能已变);
     // 否则新会话只塞 system 提示。
-    const systemPrompt = effectiveSystemPrompt(config.systemPrompt);
+    const systemPrompt = effectiveSystemPrompt(config.systemPrompt + buildMemorySection() + buildMemoryIndexSection());
     const history = initialHistory && initialHistory.length
         ? initialHistory
         : [{ role: 'system', content: systemPrompt }];
@@ -280,6 +317,8 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null)
             rebuildFromHistory(history);
     }
     let currentSessionId = sessionId;
+    // 反思 cadence 计数:每 reflectEveryN 轮 fire-and-forget 一次后台反思 pass。
+    let turnCount = 0;
     // 本会话累积的折叠思考段,供 /think N 重打原文。
     const collapsedThinkings = [];
     const toolsLine = tools.map((t) => t.name).join(' · ');
@@ -381,6 +420,13 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null)
     while (true) {
         // INPUT 态:画底栏输入框 + 状态行,光标入输入框
         refreshStatusBase(history);
+        // 后台反思若已完成(上轮 fire-and-forget),在安全点 flush 一行 dim 摘要:
+        // 不在 RUNNING 态写——防与正在跑的 agent 争屏(contentWrite / 状态行)。
+        const reflectRes = getLastReflectResult();
+        if (reflectRes) {
+            layout.contentWrite(`  ${ui.gray}↳ ${formatReflectResult(reflectRes)}${ui.reset}\n`);
+            clearLastReflectResult();
+        }
         layout.enterInputMode('空闲');
         let input = null;
         try {
@@ -402,7 +448,7 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null)
         runningInput = ''; // 预填已消费,清空(下轮运行态从空开始)
         if (input === null)
             break; // 空 prompt Ctrl+D
-        const joined = input.join('\n');
+        let joined = input.join('\n');
         const line = joined.trim();
         if (!line)
             continue;
@@ -414,11 +460,16 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null)
         const { status, placeholder } = runningStateFor(cmd);
         refreshStatusBase(history);
         layout.enterRunningMode(status, placeholder);
+        if (line === '/init') {
+            // /init:把 init 指令当 user 输入发给 agent(扫描项目 + 生成 MOCODE.md),fall through 走 runAgent
+            joined = INIT_PROMPT;
+        }
         if (line === '/clear') {
             history.length = 1; // 保留 system 提示
             collapsedThinkings.length = 0; // 同步清空折叠的思考段
             resetState(); // 同步清空回滚轮次/快照
             currentSessionId = undefined; // 下轮起新会话文件
+            turnCount = 0; // 反思 cadence 重新计数
             contextState.lastUsage = undefined;
             layout.clearContent();
             layout.contentWrite(bannerString(banner()));
@@ -429,6 +480,35 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null)
             layout.contentWrite(`  ${renderContextBar(history)}\n`);
             continue;
         }
+        if (line === '/memory') {
+            // 记忆库概览:计数 + 近期 active 索引(详情用 memory_search)。
+            const all = loadAll();
+            const active = all.filter((e) => e.status === 'active');
+            const archived = all.filter((e) => e.status === 'archived').length;
+            const byType = {};
+            for (const e of active)
+                byType[e.type] = (byType[e.type] || 0) + 1;
+            layout.contentWrite(`${ui.dim}记忆库:active ${active.length}${archived ? ` · archived ${archived}` : ''}${ui.reset}\n`);
+            if (Object.keys(byType).length) {
+                layout.contentWrite(`${ui.dim}按类:${Object.entries(byType).map(([t, n]) => `${t} ${n}`).join('  ')}${ui.reset}\n`);
+            }
+            const recent = [...active]
+                .sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || ''))
+                .slice(0, 10);
+            for (const e of recent) {
+                layout.contentWrite(`  ${ui.cyan}${e.id}${ui.reset}  ${ui.dim}${e.name} — ${e.summary}${ui.reset}\n`);
+            }
+            if (active.length === 0)
+                layout.contentWrite(`${ui.dim}(无 active 记忆;用 memory_save 存,或 /init 生成 MOCODE.md)${ui.reset}\n`);
+            layout.contentWrite(`${ui.dim}(详情用 memory_search;启动索引已注入 systemPrompt)${ui.reset}\n`);
+            continue;
+        }
+        if (line === '/reflect') {
+            // 手动触发后台反思 pass(不等;完成后下次 INPUT 态显摘要)。
+            kickoffReflection(snapshotTranscript(history, 20));
+            layout.contentWrite(`${ui.dim}(反思已触发,后台进行;完成后下次输入态显示摘要。日志见 .mocode/memory.log)${ui.reset}\n`);
+            continue;
+        }
         if (line === '/skills') {
             const skills = listSkills();
             if (skills.length === 0) {
@@ -458,25 +538,28 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null)
             continue;
         }
         if (line === '/resume') {
+            // /resume:打开会话菜单(↑/↓ 选,Enter 续接,Esc 取消)。默认仅最近 10 条,按 a 展开全部。
+            // 仿 /rollback 菜单化(promptSessionPicker);选中项 cyan+bold + ▸ 高亮。
             const sessions = listSessions();
             if (sessions.length === 0) {
                 layout.contentWrite(`${ui.dim}(没有已保存的会话)${ui.reset}\n`);
                 continue;
             }
-            sessions.forEach((s, i) => {
-                layout.contentWrite(`  ${ui.dim}${i + 1}${ui.reset}  ${s.id}  ${ui.cyan}${s.firstUser || '(无)'}${ui.reset}  ${ui.dim}${s.model}${ui.reset}\n`);
-            });
-            let pick = '';
+            const items = sessions.map((s) => ({
+                id: s.id,
+                title: s.firstUser || '(无)',
+                subtitle: `${s.id}  ${s.model}`,
+            }));
+            let pick;
             try {
-                pick = (await askLine('序号(回车取消): ')).trim();
+                pick = await promptSessionPicker(items);
             }
             catch {
-                continue;
+                continue; // Ctrl+C(SIGINT)→ 取消
             }
-            const idx = Number(pick);
-            if (!pick || !Number.isInteger(idx) || idx < 1 || idx > sessions.length)
-                continue;
-            const loaded = loadSession(sessions[idx - 1].id);
+            if (!pick)
+                continue; // Esc / Ctrl+D 取消
+            const loaded = loadSession(pick.id);
             if (!loaded || !loaded.history.length) {
                 layout.contentWrite(`${ui.yellow}(加载失败)${ui.reset}\n`);
                 continue;
@@ -539,6 +622,12 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null)
                 // 落盘失败不阻断 REPL
             }
             persistSnapshots(currentSessionId); // 随会话落盘回滚快照(/resume 后仍可撤销)
+            // 后台反思:每 reflectEveryN 轮 fire-and-forget 一次(与下一轮 agent 并发,不阻塞)。
+            // 已有在飞任务 / autoReflect 关 → kickoff 内部自守卫。快照同步取(避免下一轮 mutate history 竞态)。
+            turnCount++;
+            if (turnCount % config.reflectEveryN === 0) {
+                kickoffReflection(snapshotTranscript(history, 20));
+            }
         }
         catch (e) {
             layout.contentWrite(`${ui.red}[错误]${ui.reset} ${e instanceof Error ? e.message : String(e)}\n`);
@@ -548,5 +637,7 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null)
         }
         layout.contentWrite('\n'); // 轮次之间空行
     }
+    // 退出前等在飞反思收尾(Ctrl+C 走 SIGINT 直退不等;fire-and-forget 不承诺中断时完成)。
+    await drainMemoryBackground();
     layout.exitAltScreen();
 }

package/dist/session/compact.js

@@ -1,6 +1,6 @@
 import { chat, estimateMessagesTokens, estimateToolSchemaTokens, estimateTokens, } from '../llm/index.js';
 import { config } from '../config/index.js';
-import { MAX_HISTORY_RESULT, MAX_OLD_TOOL_STUB, MAX_SKILL_RESULT } from '../tools/constants.js';
+import { MAX_HISTORY_RESULT, MAX_MEMORY_RESULT, MAX_OLD_TOOL_STUB, MAX_SKILL_RESULT } from '../tools/constants.js';
 import { ui } from '../ui/theme.js';
 import { Spinner } from '../ui/spinner.js';
 import * as layout from '../ui/layout.js';
@@ -40,6 +40,17 @@ export function capToolResultForHistory(name, output) {
             return marker.slice(0, MAX_SKILL_RESULT);
         return output.slice(0, remain) + marker;
     }
+    if (name === 'memory_search') {
+        // 召回的记忆正文是高价值事实/指令,中截会劈断语义;同 use_skill 走尾截(保头部、弃尾部)。
+        if (output.length <= MAX_MEMORY_RESULT)
+            return output;
+        const removed = output.length - MAX_MEMORY_RESULT;
+        const marker = `…[记忆结果过长,已截断尾部 ${removed} 字符]…`;
+        const remain = MAX_MEMORY_RESULT - marker.length;
+        if (remain <= 0)
+            return marker.slice(0, MAX_MEMORY_RESULT);
+        return output.slice(0, remain) + marker;
+    }
     if (output.length <= MAX_HISTORY_RESULT)
         return output;
     return truncateMid(output, MAX_HISTORY_RESULT);
@@ -194,7 +205,12 @@ export async function compactHistory(history, opts) {
         }
         return noop;
     }
-    // 第一层:微压缩——旧区 tool 结果原地截短(保 tool_call_id,无 LLM 调用)
+    // 第一层:微压缩——旧区原地截短(保 tool_call_id,无 LLM 调用)
+    // 覆盖三类大字段,均只裁模型/工具产物,不动 user 原话与 system(摘要):
+    //   ① tool 结果 content;
+    //   ② 旧 assistant 的 tool_calls.arguments —— 保 JSON 合法:整体超长才进,
+    //     逐字段值裁中截后重新 stringify(不裸中截会劈断 JSON、严格后端 400);parse 失败跳过;
+    //   ③ 旧 assistant 正文 content(模型长解释,回看价值低)。
     let microcompactDone = false;
     for (const g of oldGroups) {
         for (const t of g.tools) {
@@ -204,6 +220,38 @@ export async function compactHistory(history, opts) {
                 microcompactDone = true;
             }
         }
+        const as = g.assistant;
+        if (as && as.role === 'assistant') {
+            // ③ 旧正文 content
+            if (typeof as.content === 'string' && as.content.length > MAX_OLD_TOOL_STUB) {
+                as.content = truncateMid(as.content, MAX_OLD_TOOL_STUB);
+                microcompactDone = true;
+            }
+            // ② tool_calls 参数:整体超长才进,逐字段裁值,保 JSON 合法
+            if (Array.isArray(as.tool_calls)) {
+                for (const tc of as.tool_calls) {
+                    const args = tc?.function?.arguments;
+                    if (typeof args !== 'string' || args.length <= MAX_OLD_TOOL_STUB)
+                        continue;
+                    try {
+                        const parsed = JSON.parse(args);
+                        if (parsed && typeof parsed === 'object') {
+                            for (const k of Object.keys(parsed)) {
+                                const v = parsed[k];
+                                if (typeof v === 'string' && v.length > MAX_OLD_TOOL_STUB) {
+                                    parsed[k] = truncateMid(v, MAX_OLD_TOOL_STUB);
+                                }
+                            }
+                            tc.function.arguments = JSON.stringify(parsed);
+                            microcompactDone = true;
+                        }
+                    }
+                    catch {
+                        // arguments 非合法 JSON(模型偶发):不裁,沿用「调度器永不抛错」
+                    }
+                }
+            }
+        }
     }
     // 第二层:摘要——把旧区(微压缩后)压成一条 system 摘要
     const older = flattenGroups(oldGroups);

package/dist/tools/builtins/ask-human.js

@@ -0,0 +1,50 @@
+import { promptIntervention } from '../../ui/intervention.js';
+// ---------- ask_human ----------
+export const askHumanTool = {
+    name: 'ask_human',
+    description: [
+        '当你在执行任务中遇到需要人类做决策的岔路时调用此工具,在终端弹出问题面板让用户选择。',
+        '适用:多种实现方案需要用户拍板、不确定用户意图需要澄清、需要用户提供额外信息才能继续。',
+        '调用后阻塞等待用户响应;用户可挑预设选项,也可选"自定义输入"自由作答,结果作为工具返回值返回。',
+        '不要在任务明确、可自行决定时频繁调用——会打断用户。options 省略或为空时改为自由文本输入。',
+    ].join(''),
+    parameters: {
+        type: 'object',
+        properties: {
+            question: {
+                type: 'string',
+                description: '要问用户的问题,简明扼要(显示为面板标题)',
+            },
+            options: {
+                type: 'array',
+                items: { type: 'string' },
+                description: '供用户选择的选项(2~6 个)。可省略——省略或为空时改为自由文本输入',
+            },
+            context: {
+                type: 'string',
+                description: '问题的背景说明(可选,帮助用户理解为何需要他决策;显示在标题下,可多行)',
+            },
+        },
+        required: ['question'],
+    },
+    async execute(args) {
+        const question = String(args.question ?? '');
+        const options = Array.isArray(args.options)
+            ? args.options.map((o) => String(o))
+            : [];
+        const context = args.context ? String(args.context) : undefined;
+        const result = await promptIntervention({
+            type: options.length > 0 ? 'choice' : 'input',
+            title: question,
+            options: options.length > 0 ? options : undefined,
+            detail: context,
+        });
+        if (result.action === 'cancelled') {
+            return '用户取消了选择。请考虑是否有不依赖用户输入的替代方案,或换个角度重新提问。';
+        }
+        if (result.action === 'submitted') {
+            return `用户回答:${result.value ?? ''}`;
+        }
+        return `用户选择:${result.value ?? ''}`;
+    },
+};

package/dist/tools/builtins/index.js

@@ -7,6 +7,12 @@ import { grepTool } from './grep.js';
 import { webSearchTool } from './web-search.js';
 import { webFetchTool } from './web-fetch.js';
 import { useSkillTool } from './use-skill.js';
+import { askHumanTool } from './ask-human.js';
+import { memorySaveTool } from './memory-save.js';
+import { memorySearchTool } from './memory-search.js';
+import { memoryListTool } from './memory-list.js';
+import { memoryUpdateTool } from './memory-update.js';
+import { memoryForgetTool } from './memory-forget.js';
 /**
  * 所有内置工具,按注册顺序排列。
  * 加新工具:在本目录新建 `xxx.ts` 导出一个 Tool,再在下面数组里加一行。
@@ -21,4 +27,10 @@ export const builtinTools = [
     webSearchTool,
     webFetchTool,
     useSkillTool,
+    askHumanTool,
+    memorySaveTool,
+    memorySearchTool,
+    memoryListTool,
+    memoryUpdateTool,
+    memoryForgetTool,
 ];

package/dist/tools/builtins/memory-forget.js

@@ -0,0 +1,32 @@
+import { forgetEntry } from '../../memory/store.js';
+// ---------- memory_forget ----------
+// 遗忘:默认归档(archived,从索引/默认搜索隐藏,可复活);mode=delete 硬删。pinned 拒删。
+export const memoryForgetTool = {
+    name: 'memory_forget',
+    description: '遗忘一条记忆:默认归档(archived,从索引/默认搜索隐藏,可经 memory_update 复活);mode=delete 硬删。pinned 条目拒删(先 memory_update pinned=false 解钉)。',
+    parameters: {
+        type: 'object',
+        properties: {
+            id: { type: 'string' },
+            mode: {
+                type: 'string',
+                enum: ['archive', 'delete'],
+                description: '默认 archive',
+            },
+        },
+        required: ['id'],
+    },
+    async execute(args) {
+        const id = String(args.id ?? '').trim();
+        if (!id)
+            return '错误:缺少 id。';
+        const mode = args.mode === 'delete' ? 'delete' : 'archive';
+        const r = forgetEntry(id, mode);
+        if (r.ok)
+            return `已${mode === 'delete' ? '硬删' : '归档'}记忆 [${id}]。`;
+        if ('notFound' in r)
+            return `错误:找不到记忆 id="${id}"。`;
+        // pinned
+        return `错误:[${id}] 已钉住,拒绝遗忘。先 memory_update(id="${id}", pinned=false) 解钉。`;
+    },
+};

package/dist/tools/builtins/memory-list.js

@@ -0,0 +1,34 @@
+import { listEntries } from '../../memory/store.js';
+// ---------- memory_list ----------
+// 列索引(id/name/summary,无正文、不 bump recall)。用于浏览有哪些、拿 id 再 memory_search 取正文。
+export const memoryListTool = {
+    name: 'memory_list',
+    description: '列出记忆索引(id/name/summary,不含正文)。默认列 active。拿 id 再 memory_search 取正文。',
+    parameters: {
+        type: 'object',
+        properties: {
+            type: {
+                type: 'string',
+                enum: ['decision', 'fact', 'pitfall', 'reference', 'feedback'],
+            },
+            status: {
+                type: 'string',
+                enum: ['active', 'superseded', 'archived', 'any'],
+                description: '默认 active',
+            },
+        },
+    },
+    async execute(args) {
+        const items = listEntries({
+            type: typeof args.type === 'string' ? args.type : undefined,
+            status: typeof args.status === 'string'
+                ? args.status
+                : undefined,
+        });
+        if (items.length === 0)
+            return '(无记忆条目)';
+        return items
+            .map((i) => `- ${i.id}: ${i.name} — ${i.summary} (${i.type}, ${i.status})`)
+            .join('\n');
+    },
+};

package/dist/tools/builtins/memory-save.js

@@ -0,0 +1,51 @@
+import { saveEntry } from '../../memory/store.js';
+// ---------- memory_save ----------
+// 存一条长期记忆(跨会话)。启动只把标题/摘要注入索引(几百 token);详情按需 memory_search 取。
+// 撞库(name→id 已存在)拒绝,引导用 memory_update。
+export const memorySaveTool = {
+    name: 'memory_save',
+    description: '保存一条长期记忆(跨会话)。只存非显然、长期有用的事实/决策/坑。启动时标题进索引,详情按需 memory_search 取。',
+    parameters: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: '简短唯一标题(转成 id,撞库会拒绝)' },
+            summary: { type: 'string', description: '一句话摘要(进索引,尽量短)' },
+            body: { type: 'string', description: '完整内容(细节/上下文/证据)' },
+            type: {
+                type: 'string',
+                enum: ['decision', 'fact', 'pitfall', 'reference', 'feedback'],
+                description: '分类,默认 fact',
+            },
+            pinned: { type: 'boolean', description: '钉住(豁免自动遗忘衰减),默认 false' },
+            scope: {
+                type: 'string',
+                enum: ['project', 'global'],
+                description: '存到项目级(<cwd>/.mocode/)还是全局(~/.mocode/),默认 project',
+            },
+        },
+        required: ['name', 'summary', 'body'],
+    },
+    async execute(args) {
+        const name = String(args.name ?? '').trim();
+        const summary = String(args.summary ?? '').trim();
+        const body = String(args.body ?? '').trim();
+        if (!name)
+            return '错误:缺少 name。';
+        if (!summary)
+            return '错误:缺少 summary。';
+        if (!body)
+            return '错误:缺少 body。';
+        const type = typeof args.type === 'string' ? args.type : undefined;
+        const r = saveEntry({
+            name,
+            summary,
+            body,
+            type,
+            pinned: args.pinned === true,
+            scope: args.scope === 'global' ? 'global' : 'project',
+        });
+        if (r.ok)
+            return `已保存记忆 [${r.id}] "${name}"(下次启动进索引)。`;
+        return `已存在同名记忆 [${r.exists}]。改用 memory_update(id="${r.exists}", …) 更新,或换一个 name。`;
+    },
+};

package/dist/tools/builtins/memory-search.js

@@ -0,0 +1,42 @@
+import { searchEntries } from '../../memory/store.js';
+// ---------- memory_search ----------
+// 关键词搜记忆正文(多词子串匹配,name 权重最高)。命中即 bump recallCount(遗忘衰减依据)。
+// 结果走 capToolResultForHistory 的放宽上限(同 use_skill,保正文完整)。
+export const memorySearchTool = {
+    name: 'memory_search',
+    description: '按关键词搜索记忆正文(多词子串匹配,按相关度排),返回匹配条目全文。命中记一次召回(影响遗忘衰减)。',
+    parameters: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: '关键词(id 或 name 里的词效果最好)' },
+            type: {
+                type: 'string',
+                enum: ['decision', 'fact', 'pitfall', 'reference', 'feedback'],
+            },
+            status: {
+                type: 'string',
+                enum: ['active', 'superseded', 'archived', 'any'],
+                description: '默认 active(只搜活的)',
+            },
+            limit: { type: 'integer', description: '返回条数,默认 5,上限 20' },
+        },
+        required: ['query'],
+    },
+    async execute(args) {
+        const query = String(args.query ?? '').trim();
+        if (!query)
+            return '错误:缺少 query。';
+        const r = searchEntries(query, {
+            type: typeof args.type === 'string' ? args.type : undefined,
+            status: typeof args.status === 'string'
+                ? args.status
+                : undefined,
+            limit: typeof args.limit === 'number' ? args.limit : undefined,
+        });
+        if (r.length === 0)
+            return `(无匹配记忆:query="${query}")`;
+        return r
+            .map((e) => `# [${e.id}] ${e.name} (${e.type}, recalled ${e.recallCount})\nsummary: ${e.summary}\n\n${e.body}`)
+            .join('\n\n---\n\n');
+    },
+};

package/dist/tools/builtins/memory-update.js

@@ -0,0 +1,41 @@
+import { updateEntry } from '../../memory/store.js';
+// ---------- memory_update ----------
+// 原地改一条记忆(id 不变)。反思的弱意义:干活时发现事实变了/过时即纠正。
+export const memoryUpdateTool = {
+    name: 'memory_update',
+    description: '更新一条记忆(id 不变)。用于事实变了/纠正过时/补 summary 或 body/切换 pinned。id 从 memory_list 或 memory_search 拿。',
+    parameters: {
+        type: 'object',
+        properties: {
+            id: { type: 'string' },
+            summary: { type: 'string', description: '新摘要(只传要改的字段)' },
+            body: { type: 'string', description: '新正文(只传要改的字段)' },
+            name: { type: 'string', description: '新标题(id 不随 name 变)' },
+            pinned: { type: 'boolean', description: '切换钉住状态(true 钉住豁免衰减 / false 解钉)' },
+            reason: { type: 'string', description: '更新理由(记入 lastUpdateReason,便于追溯)' },
+        },
+        required: ['id'],
+    },
+    async execute(args) {
+        const id = String(args.id ?? '').trim();
+        if (!id)
+            return '错误:缺少 id。';
+        const patch = {};
+        if (typeof args.summary === 'string')
+            patch.summary = args.summary;
+        if (typeof args.body === 'string')
+            patch.body = args.body;
+        if (typeof args.name === 'string')
+            patch.name = args.name;
+        if (typeof args.reason === 'string')
+            patch.reason = args.reason;
+        if (typeof args.pinned === 'boolean')
+            patch.pinned = args.pinned;
+        if (Object.keys(patch).length === 0)
+            return '错误:至少传一个要改的字段(summary/body/name/pinned/reason)。';
+        const r = updateEntry(id, patch);
+        if (r.ok)
+            return `已更新记忆 [${id}]。`;
+        return `错误:找不到记忆 id="${id}"。用 memory_list 查可用 id。`;
+    },
+};

package/dist/tools/builtins/use-skill.js

@@ -4,7 +4,7 @@ import { getSkillBody } from '../../skills/index.js';
 // 系统提示里已列出可用 skill 的 name + description(何时用),模型据此决定调用。
 export const useSkillTool = {
     name: 'use_skill',
-    description: '加载并返回某个 skill 的完整 SKILL.md 指令。系统提示里列出了可用 skill(name + 何时用的 description)。只在任务相关时调用本工具传 skill 的 name,拿到完整指令后据此行动;不要无脑批量加载。',
+    description: '加载并返回某个 skill 的完整 SKILL.md 指令(传 name)。何时用见系统提示的 skill 列表。',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/web-fetch.js

@@ -4,7 +4,7 @@ const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML,
 // ---------- web_fetch ----------
 export const webFetchTool = {
     name: 'web_fetch',
-    description: '抓取指定 URL 的网页内容并清洗成纯文本(去 HTML 标签/脚本/样式,保留正文)。用于读取搜索结果里的某个链接、或用户给出的具体 URL。注意:只能抓静态 HTML,JS 渲染的页面(正文靠脚本填充)可能拿不到内容——那种情况改用 web_search(其结果自带清洗后的 content)。',
+    description: '抓取指定 URL 的网页内容并清洗成纯文本(去 HTML 标签/脚本/样式,保留正文)。用于读取搜索结果里的某个链接、或用户给出的具体 URL。',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/builtins/web-search.js

@@ -6,7 +6,7 @@ const MAX_CONTENT_CHARS = 800;
 // ---------- web_search ----------
 export const webSearchTool = {
     name: 'web_search',
-    description: '联网搜索(AnySearch)。返回每条结果的标题/URL/摘要/正文,用于查模型训练数据之外的最新信息(新版本发布、新闻、实时数据、最新 API 文档等)。可选 tag 切换子域:general.general(默认通用网页)/ code.doc(开发文档,须配 params.library)/ code.snippet(代码片段)。',
+    description: '联网搜索(AnySearch)。返回每条结果的标题/URL/摘要/正文。可选 tag 切换子域(见 tag 参数)。',
     parameters: {
         type: 'object',
         properties: {

package/dist/tools/constants.js

@@ -8,4 +8,17 @@ export const MAX_HISTORY_RESULT = 8000;
 export const MAX_SKILL_RESULT = 64000;
 /** 微压缩时旧工具结果截到的存根长度(字符)。 */
 export const MAX_OLD_TOOL_STUB = 600;
+// ── 记忆(Tier-2 JSONL 工具库)──────────────────────────────────────────────
+/** 单条记忆 body 上限(字符)。进 history 前 memory_search 结果另有 MAX_MEMORY_RESULT 兜底。 */
+export const MAX_MEMORY_ENTRY = 4000;
+/** 启动注入 systemPrompt 的索引条目上限(遗忘封顶后 active 条目 ≤ MAX_ACTIVE,索引再封一层)。 */
+export const MAX_INDEX_ENTRIES = 50;
+/** active 记忆封顶:超则按 recallCount 低 × lastRecalledAt 老 淘汰到 archived。 */
+export const MAX_ACTIVE = 100;
+/** 衰减:active + !pinned + (lastRecalledAt|createdAt) 早于 DECAY_DAYS → archived。 */
+export const DECAY_DAYS = 30;
+/** GC:archived 超 GC_DAYS → 硬删。 */
+export const GC_DAYS = 90;
+/** memory_search 结果(召回的记忆正文)的放宽上限:指令性内容,中截破坏语义,对齐 use_skill。 */
+export const MAX_MEMORY_RESULT = 64000;
 export const IGNORE = ['**/node_modules/**', '**/.git/**'];