mocode-ai 0.1.2 → 0.1.4

package/dist/repl/index.js

@@ -4,14 +4,15 @@ import { stdin, stdout } from 'node:process';
 import { config } from '../config/index.js';
 import { runAgent } from '../agent/index.js';
 import { ui } from '../ui/theme.js';
-import { bannerString, displayWidth, summarizeToolCall, summarizeToolResult } from '../ui/render.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;
@@ -173,14 +210,30 @@ function stopRunningListener() {
     emitter.off('keypress', onRunningKey);
     currentAbort = null;
 }
+/**
+ * 把用户消息格式化为带满宽背景色的文本(上滑时易辨认用户消息)。
+ * 每行用 padEndDisplay 填充到终端宽度(含 ❯ / 缩进),背景色 SGR 包裹整行 + 行末 reset。
+ * 满宽 pad 使终端背景色覆盖整行(含行尾空单元格),上滑滚动时用户消息呈连续色块、与 assistant 正文区分。
+ */
+function formatUserMessage(lines) {
+    const cols = layout.getGeo().cols;
+    const promptW = displayWidth(PROMPT);
+    const indent = ' '.repeat(promptW);
+    const { userBg, reset } = ui;
+    return (lines
+        .map((l, i) => {
+        const prefix = i === 0 ? PROMPT : indent;
+        const full = prefix + l;
+        const padded = padEndDisplay(full, cols);
+        return `${userBg}${padded}${reset}`;
+    })
+        .join('\n') + '\n');
+}
 /** 把多行提交输入回显进内容区(❯ 首行,续行按 prompt 宽度缩进)。仅 TUI 态回显(非 TTY 由 readline 自带回显)。 */
 function echoInput(lines) {
     if (!layout.isActive())
         return;
-    const indent = ' '.repeat(displayWidth(PROMPT));
-    const echo = lines.map((l, i) => (i === 0 ? `${PROMPT}${l}` : `${indent}${l}`)).join('\n') +
-        '\n';
-    layout.contentWrite(echo);
+    layout.contentWrite(formatUserMessage(lines));
 }
 /** 把任意消息 content 拍平成字符串(OpenAI 可能 string / null / 多模态数组)。 */
 function textOf(c) {
@@ -202,16 +255,13 @@ function textOf(c) {
  * 内容长于屏时 viewport 显尾(最近轮次),PgUp 可看更早——与流式态一致。
  */
 export function renderHistory(history) {
-    const indent = ' '.repeat(displayWidth(PROMPT));
     const idToName = new Map();
     for (const m of history) {
         if (m.role === 'system')
             continue;
         if (m.role === 'user') {
             const lines = textOf(m.content).split('\n');
-            layout.contentWrite(lines
-                .map((l, i) => (i === 0 ? `${PROMPT}${l}` : `${indent}${l}`))
-                .join('\n') + '\n');
+            layout.contentWrite(formatUserMessage(lines));
             continue;
         }
         if (m.role === 'assistant') {
@@ -252,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 }];
@@ -267,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(' · ');
@@ -368,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 {
@@ -389,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;
@@ -401,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()));
@@ -416,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) {
@@ -445,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;
@@ -510,7 +606,12 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null)
         }
         try {
             const signal = startRunningListener(placeholder);
-            await runAgent(history, joined, collapsedThinkings, signal);
+            // 运行中每步 chat() 返回后刷新状态行 context 用量条(用 fresh lastUsage / 估算),
+            // 否则整轮冻结在轮首 refreshStatusBase 的值,「执行 grep」时 2k/1000k 不动。
+            await runAgent(history, joined, collapsedThinkings, signal, () => {
+                refreshStatusBase(history);
+                layout.drawStatusBar();
+            });
             // 成功轮次自动落盘(崩溃也保住上一轮);新会话首轮分配 id
             if (!currentSessionId)
                 currentSessionId = newSessionId();
@@ -521,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`);
@@ -530,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。`;
+    },
+};