mocode-ai 1.2.4 → 1.2.6

package/dist/session/notes.js

@@ -105,3 +105,236 @@ export function writePlanToNotes(plan, sessionId = getCurrentSessionId()) {
     }
     return { path: p, settled: plan.steps.length > 0 && plan.steps.every((s) => s.status === 'completed') };
 }
+// ── Session notes(单会话永久记忆):note_append 写入,reinject 常驻 system ──────
+// 设计:notes.md 不止放 Plan。note_append 往预设笔记段追加一条 finding/decision/
+// open_question/risk;extractActiveNotesSections 读出活跃笔记段正文(排除 Plan/Done),
+// 按 5k token 预算裁剪后由 reinjectSessionStateIntoSystem 注入 system prompt——compact
+// 后仍能恢复,让 agent 始终记得本会话做过什么、发现过什么(单会话永久记忆)。
+/** note_append 接受的预设段 key → 渲染标题。 */
+const NOTE_SECTION_TITLES = {
+    findings: 'Findings',
+    decisions: 'Decisions',
+    open_questions: 'Open Questions',
+    risks: 'Risks',
+};
+/** 预设段 key 列表(供工具 schema enum 与校验用)。 */
+export const NOTE_SECTION_KEYS = Object.keys(NOTE_SECTION_TITLES);
+/** 段注入优先级:数值越大越先占预算、越后丢弃正文。Risks 最重要。 */
+const SECTION_PRIORITY = {
+    risks: 4, findings: 3, decisions: 2, open_questions: 1,
+};
+/** 常驻笔记正文总预算(token)。5k:占百万级 context 的 0.5%,可常驻相当量笔记。 */
+const NOTES_INJECT_BUDGET_TOKENS = 5000;
+/** 单段正文上限(token):防单段独占预算。 */
+const NOTES_PER_SECTION_TOKENS = 2000;
+/** 单条笔记上限(token):防一条过长吃掉整段预算。 */
+const NOTES_PER_ENTRY_TOKENS = 800;
+/**
+ * 轻量 token 估算(启发式,不依赖 tokenizer):CJK ≈ 0.6 token/字,
+ * ASCII ≈ 0.25 token/字。对 GLM/DeepSeek/Qwen 等中文偏多的后端略偏保守
+ * (估算略高于实际 → 注入实际 token 略低于预算 → 安全侧)。仅供笔记 cap 用,
+ * 不替换 llm/estimatePromptTokens 的主口径。
+ */
+function estimateTokens(text) {
+    let cjk = 0;
+    let other = 0;
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        if ((c >= 0x3000 && c <= 0x9fff) || (c >= 0xff00 && c <= 0xffef))
+            cjk++;
+        else
+            other++;
+    }
+    return Math.ceil(cjk * 0.6 + other * 0.25);
+}
+/** 把标题映射回预设 key(非预设段返 '',优先级 0,最后注入)。 */
+function matchSectionKey(title) {
+    const t = title.trim().toLowerCase();
+    for (const [k, v] of Object.entries(NOTE_SECTION_TITLES)) {
+        if (v.toLowerCase() === t)
+            return k;
+    }
+    return '';
+}
+/**
+ * 往 notes.md 的指定笔记段追加一条。段存在则在其末尾追加(保留其它段不动);
+ * 段不存在则在文件末新建。返回 { path } 或 { error }。
+ */
+export function appendNoteToSection(section, entry, tag, sessionId = getCurrentSessionId()) {
+    const title = NOTE_SECTION_TITLES[section];
+    if (!title)
+        return { error: `unknown note section "${section}"` };
+    const p = getNotesFilePath(sessionId);
+    if (!p)
+        return { error: 'no active session' };
+    const line = tag ? `- **[${tag}]** ${entry}` : `- ${entry}`;
+    let existing = '';
+    try {
+        existing = fs.readFileSync(p, 'utf8').replace(/\r\n?/g, '\n');
+    }
+    catch {
+        existing = '';
+    }
+    const header = `## ${title}`;
+    const lines = existing.split('\n');
+    const start = lines.findIndex((l) => l.trim() === header);
+    let next;
+    if (start >= 0) {
+        // 段末 = 下一个 ## 或文件末
+        let end = lines.length;
+        for (let k = start + 1; k < lines.length; k++) {
+            if (/^##\s/.test(lines[k])) {
+                end = k;
+                break;
+            }
+        }
+        const before = lines.slice(0, start).join('\n').replace(/\s+$/, '');
+        const sectionLines = lines.slice(start, end);
+        // 去段尾空行后追加新条目
+        while (sectionLines.length && sectionLines[sectionLines.length - 1].trim() === '')
+            sectionLines.pop();
+        sectionLines.push(line);
+        const section = sectionLines.join('\n');
+        const after = lines.slice(end).join('\n').replace(/^\s+/, '');
+        next = [before, section, after].filter((s) => s.length > 0).join('\n\n') + '\n';
+    }
+    else {
+        // 新建段:放文件末,与已有内容以空行分隔
+        const rest = existing.trim();
+        const newSection = `${header}\n${line}`;
+        next = rest ? `${rest}\n\n${newSection}\n` : `${newSection}\n`;
+    }
+    try {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, next, 'utf8');
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+    return { path: p };
+}
+/** 按字符二分截断条目到 token 上限,加省略标记。条目不长,线性二分足够。 */
+function truncateEntry(entry, maxTokens) {
+    if (estimateTokens(entry) <= maxTokens)
+        return entry;
+    let lo = 0;
+    let hi = entry.length;
+    while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        if (estimateTokens(entry.slice(0, mid)) <= maxTokens)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return entry.slice(0, lo).replace(/\s+$/, '') + ' …[truncated]';
+}
+/** 把单段正文按条目分割,从末尾(最近)保留,丢最旧,裁到 token 预算内。 */
+function trimSectionToBudget(body, budgetTokens) {
+    if (budgetTokens <= 0)
+        return null;
+    const bodyLines = body.split('\n');
+    const header = bodyLines[0] ?? '';
+    const rest = bodyLines.slice(1);
+    // 分条目:以 "- " 开头为一条起始,后续非 "- " 行归入该条
+    const entries = [];
+    let cur = [];
+    for (const ln of rest) {
+        if (/^-\s+/.test(ln)) {
+            if (cur.length)
+                entries.push(cur.join('\n'));
+            cur = [ln];
+        }
+        else {
+            cur.push(ln);
+        }
+    }
+    if (cur.length)
+        entries.push(cur.join('\n'));
+    const kept = [];
+    let used = estimateTokens(header);
+    for (let k = entries.length - 1; k >= 0; k--) {
+        let e = entries[k];
+        if (estimateTokens(e) > NOTES_PER_ENTRY_TOKENS) {
+            e = truncateEntry(e, NOTES_PER_ENTRY_TOKENS);
+        }
+        const t = estimateTokens(e);
+        if (used + t > budgetTokens)
+            break;
+        kept.unshift(e);
+        used += t;
+    }
+    if (kept.length === 0)
+        return null;
+    return `${header}\n${kept.join('\n')}`;
+}
+/**
+ * 读 notes.md,提取所有活跃笔记段正文(排除 `## Plan:` 与 `## Done:`),
+ * 按 NOTES_INJECT_BUDGET_TOKENS 裁剪后返回——供 reinject 注入 system prompt。
+ * 裁剪策略:段按优先级排序(Risks>Findings>Decisions>Open Questions>自定义),
+ * 逐段注入累计 token;单段超 per-section 则段内从最近条目保留丢最旧;
+ * 总预算用尽则后续段不注入正文(其标题仍由 buildNotepadSection 索引常驻,
+ * agent 可 read_file 取细节)。这样 5k 预算内"写了就常驻",超出降级为索引+按需 read。
+ */
+export function extractActiveNotesSections(budget = NOTES_INJECT_BUDGET_TOKENS, sessionId = getCurrentSessionId()) {
+    const p = getNotesFilePath(sessionId);
+    if (!p)
+        return '';
+    let content = '';
+    try {
+        content = fs.readFileSync(p, 'utf8').replace(/\r\n?/g, '\n');
+    }
+    catch {
+        return '';
+    }
+    const lines = content.split('\n');
+    const sections = [];
+    let i = 0;
+    while (i < lines.length) {
+        const m = lines[i].match(/^##\s+(.+?)\s*$/);
+        if (!m) {
+            i++;
+            continue;
+        }
+        const title = m[1];
+        // 跳过 Plan/Done 段(Plan 有专属 ACTIVE_PLAN_MARKER 重注入;Done 是归档不常驻)
+        if (/^Plan:/.test(title) || /^Done:/.test(title)) {
+            i++;
+            while (i < lines.length && !/^##\s/.test(lines[i]))
+                i++;
+            continue;
+        }
+        const start = i;
+        i++;
+        while (i < lines.length && !/^##\s/.test(lines[i]))
+            i++;
+        const body = lines.slice(start, i).join('\n').trim();
+        if (body)
+            sections.push({ key: matchSectionKey(title), body });
+    }
+    // 按优先级降序(优先级高的先占预算)
+    sections.sort((a, b) => (SECTION_PRIORITY[b.key] ?? 0) - (SECTION_PRIORITY[a.key] ?? 0));
+    let used = 0;
+    const out = [];
+    for (const s of sections) {
+        const remaining = budget - used;
+        if (remaining <= 0)
+            break;
+        const bodyTokens = estimateTokens(s.body);
+        if (bodyTokens <= Math.min(remaining, NOTES_PER_SECTION_TOKENS)) {
+            out.push(s.body);
+            used += bodyTokens;
+            continue;
+        }
+        // 段超预算:段内裁条目(从最近保留)
+        const cap = Math.min(remaining, NOTES_PER_SECTION_TOKENS);
+        const trimmed = trimSectionToBudget(s.body, cap);
+        if (trimmed) {
+            out.push(trimmed);
+            used += estimateTokens(trimmed);
+        }
+        // 预算用尽则后续段不再注入正文(降级为索引)
+        if (used >= budget)
+            break;
+    }
+    return out.join('\n\n');
+}

package/dist/skills/runner.js

@@ -144,7 +144,6 @@ const WRITE_TOOLS = new Set(['write_file', 'edit_file', 'run_command']);
  * fork 子 agent 模式:`agent:` 显式声明优先;否则按工具面推断——
  * 未声明 allowed-tools(完整工具集)或白名单含写工具 → 'write',纯只读白名单 → 'read'。
  * 避免写类 skill 因缺省字段被静默降级为只读。
- * 导出仅供 scripts/check-skills.ts 离线断言。
  */
 export function resolveSpawnMode(skill, tools) {
     if (skill.agentMode)

package/dist/tools/builtins/index.js

@@ -14,17 +14,19 @@ import { useSkillTool } from './use-skill.js';
 import { runSkillTool } from './run-skill.js';
 import { askHumanTool } from './ask-human.js';
 import { planUpdateTool } from './plan-update.js';
+import { noteAppendTool } from './note-append.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';
+import { memoryGraphTool } from './memory-graph.js';
 import { subAgentTool } from './task.js';
 /**
  * 所有内置工具,按注册顺序排列。
  * 加新工具:在本目录新建 `xxx.ts` 导出一个 Tool,再在下面数组里加一行。无需改 agent / llm。
  *
- * 记忆子系统总开关(MEMORY_ENABLED !== 'true'):5 个 memory_* 工具整体不进 builtinTools,
+ * 记忆子系统总开关(MEMORY_ENABLED !== 'true'):6 个 memory_* 工具整体不进 builtinTools,
  * 进而不进 LLM 的工具表(模型根本看不到、也不会想着去调)。运行时通过 /memory_switch 切;
  * 切换对当前会话的 tool list 不重算(取的是模块初始化时的快照),所以需要重启 REPL 才生效
  * —— 这是有意为之,避免切开关瞬间把已发出请求的工具列表打乱。
@@ -41,6 +43,7 @@ const _memoryTools = _memoryEnabledAtBoot
         memoryListTool,
         memoryUpdateTool,
         memoryForgetTool,
+        memoryGraphTool,
     ]
     : [];
 const pathResource = (args) => typeof args.path === 'string' && args.path ? [`file:${args.path}`] : ['workspace'];
@@ -66,11 +69,15 @@ const CAPABILITIES = {
     // plan_update 只写内部 notes.md(session 工作面),不作为用户代码 mutation 追踪/回滚/diff;
     // 串行即可(调用不频繁),固定资源键让并发调用排队。
     plan_update: { effect: 'write', concurrency: 'serial', resources: () => ['session-notepad'] },
+    // note_append 与 plan_update 同款:只写内部 notes.md 笔记段,不作 project mutation 追踪/diff/回滚;串行 + 固定资源键排队。
+    note_append: { effect: 'write', concurrency: 'serial', resources: () => ['session-notepad'] },
     memory_save: { effect: 'write', concurrency: 'serial', resources: memoryResource },
     memory_search: { effect: 'write', concurrency: 'serial', resources: memoryResource },
     memory_list: { effect: 'read', concurrency: 'serial', resources: memoryResource },
     memory_update: { effect: 'write', concurrency: 'serial', resources: memoryResource },
     memory_forget: { effect: 'write', concurrency: 'serial', resources: memoryResource },
+    // memory_graph:search/neighbors/stats 只读、add 写,统一按写处理走串行(调用不频繁,简化)。
+    memory_graph: { effect: 'write', concurrency: 'serial', resources: memoryResource },
     // sub-agent 动态协调：只读任务无锁并行；写任务在 overlay 中执行，merge 时由 ChangeSet 持 canonical lock。
     'sub-agent': {
         effect: 'write',
@@ -99,6 +106,7 @@ const rawBuiltinTools = [
     runSkillTool,
     askHumanTool,
     planUpdateTool,
+    noteAppendTool,
     ..._memoryTools,
     subAgentTool,
 ];

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

@@ -0,0 +1,118 @@
+import { addTriple, graphStats, neighborsOf, pathBetween, } from '../../memory/graph.js';
+// ---------- memory_graph ----------
+// 知识图谱维护工具:邻居遍历(1-3 跳,可 relation 过滤)、两点最短路径、手工加三元组、看图统计。
+// 关键词搜索已并入 memory_search(条目 + 图谱事实一次返回),本工具不再提供 search。
+// 底层 memory-graph.json(Graphiti 式时序边:新事实取代旧边时旧边置 invalidAt,不删)。
+// neighbors/path/stats 只读;add 写。
+function fmtEdges(edges) {
+    if (edges.length === 0)
+        return '(无边)';
+    return edges
+        .map((e) => `${e.src} --[${e.relation}]--> ${e.dst}${e.fact ? ` (${e.fact})` : ''}`)
+        .join('\n');
+}
+function fmtEntities(entities) {
+    if (entities.length === 0)
+        return '(无实体)';
+    return entities
+        .map((e) => `- ${e.id}: ${e.name}${e.summary ? ` — ${e.summary}` : ''} [${e.scope}]`)
+        .join('\n');
+}
+export const memoryGraphTool = {
+    name: 'memory_graph',
+    description: 'Maintain/explore the knowledge-graph memory layer (entities + temporal triples). Keyword search lives in memory_search. ' +
+        'action=neighbors: BFS 1-3 hops around an entity (optional relation filter to follow one edge type); ' +
+        'action=path: shortest path between two entities (bidirectional BFS, max 6 hops); ' +
+        'action=add: add a triple (src --relation--> dst); existing edges with same src/relation/dst are temporally invalidated, not deleted; ' +
+        'action=stats: graph size overview.',
+    parameters: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['neighbors', 'path', 'add', 'stats'],
+                description: 'What to do',
+            },
+            query: { type: 'string', description: 'neighbors: entity name or id; path: start entity' },
+            depth: { type: 'integer', description: 'neighbors: hops, 1-3, default 1' },
+            src: { type: 'string', description: 'add: source entity name' },
+            relation: {
+                type: 'string',
+                description: 'add: relation in snake_case, e.g. depends_on / decided_by. neighbors: optional edge-type filter to follow only that relation',
+            },
+            dst: { type: 'string', description: 'add: target entity name; path: end entity' },
+            fact: { type: 'string', description: 'add: optional one-line statement for the edge' },
+            scope: {
+                type: 'string',
+                enum: ['project', 'global'],
+                description: 'add: which graph file to write, default project',
+            },
+        },
+        required: ['action'],
+    },
+    async execute(args) {
+        const action = String(args.action ?? '').trim();
+        if (action === 'stats') {
+            const s = graphStats();
+            return [
+                `实体 ${s.entities} 条边(active ${s.edgesActive} / 已失效 ${s.edgesInvalid})`,
+                `project: ${s.byScope.project.entities} 实体, ${s.byScope.project.edges} 边`,
+                `global:  ${s.byScope.global.entities} 实体, ${s.byScope.global.edges} 边`,
+            ].join('\n');
+        }
+        if (action === 'neighbors') {
+            const query = String(args.query ?? '').trim();
+            if (!query)
+                return '错误:neighbors 需要 query(实体名或 id)。';
+            const depth = typeof args.depth === 'number' ? args.depth : 1;
+            const rel = typeof args.relation === 'string' ? args.relation.trim() : '';
+            const r = neighborsOf(query, depth, rel || undefined);
+            if (!r.center)
+                return `(图中没有实体 "${query}")`;
+            const relNote = rel ? `,仅 ${rel} 边` : '';
+            const lines = [
+                `## ${r.center.name} (${r.center.id})${r.center.summary ? ` — ${r.center.summary}` : ''}`,
+                r.entities.length > 0 ? `\n## 邻居实体\n${fmtEntities(r.entities)}` : '',
+                `\n## 边(${r.edges.length}${relNote}${r.truncated ? ',已截断' : ''})\n${fmtEdges(r.edges)}`,
+            ].filter(Boolean);
+            return lines.join('\n');
+        }
+        if (action === 'path') {
+            const from = String(args.query ?? '').trim();
+            const to = String(args.dst ?? '').trim();
+            if (!from || !to)
+                return '错误:path 需要 query(起点实体)和 dst(终点实体)。';
+            const r = pathBetween(from, to);
+            if (!r)
+                return `(无 active 路径:${from} ⇸ ${to},或端点实体不存在)`;
+            const chain = r.path.map((e) => e.name).join(' → ');
+            const lines = [
+                `## ${r.from.name} ⇢ ${r.to.name}(${r.edges.length} 跳)`,
+                `路径:${chain}`,
+                `\n## 边\n${fmtEdges(r.edges)}`,
+            ];
+            return lines.join('\n');
+        }
+        if (action === 'add') {
+            const src = String(args.src ?? '').trim();
+            const relation = String(args.relation ?? '').trim();
+            const dst = String(args.dst ?? '').trim();
+            if (!src || !relation || !dst)
+                return '错误:add 需要 src、relation、dst。';
+            const r = addTriple({
+                src,
+                relation,
+                dst,
+                fact: typeof args.fact === 'string' ? args.fact : undefined,
+                scope: args.scope === 'global' ? 'global' : 'project',
+            });
+            if (!r.ok)
+                return `错误:三元组未写入 (${r.reason})。`;
+            if (r.duplicate)
+                return `已存在相同三元组 (${r.edgeId}),幂等跳过。`;
+            const sup = r.superseded > 0 ? `;旧边已时序失效(${r.superseded} 条)` : '';
+            return `已写入三元组 ${src} --[${relation.toLowerCase().replace(/\s+/g, '_')}]--> ${dst} [${r.edgeId}]${sup}。`;
+        }
+        return `错误:未知 action "${action}",可用 neighbors/path/add/stats(关键词搜索请用 memory_search)。`;
+    },
+};

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

@@ -1,10 +1,12 @@
 import { saveEntry } from '../../memory/store.js';
+import { addTriple } from '../../memory/graph.js';
 // ---------- memory_save ----------
 // 存一条长期记忆(跨会话)。启动只把标题/摘要注入索引(几百 token);详情按需 memory_search 取。
 // 撞库(name→id 已存在)拒绝,引导用 memory_update。
+// 可选 links:把本条记忆挂进知识图谱(memory-graph.json)——src 省略时默认以记忆 name 为主实体。
 export const memorySaveTool = {
     name: 'memory_save',
-    description: 'Save a cross-session long-term memory entry. Store only non-obvious, useful facts/decisions/pitfalls. Title enters the startup index; retrieve body via memory_search.',
+    description: 'Save a cross-session long-term memory entry. Store only non-obvious, useful facts/decisions/pitfalls. Title enters the startup index; retrieve body via memory_search. Optionally attach knowledge-graph links (triples) to relate this memory to entities.',
     risk: 'confirm',
     parameters: {
         type: 'object',
@@ -23,6 +25,20 @@ export const memorySaveTool = {
                 enum: ['project', 'global'],
                 description: 'Store at project level (<cwd>/.mocode/) or global (~/.mocode/), default project',
             },
+            links: {
+                type: 'array',
+                description: 'Optional knowledge-graph triples relating this memory to entities, e.g. [{"src":"mocode","relation":"depends_on","dst":"JSONL store"}]. src defaults to the memory name when omitted.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        src: { type: 'string', description: 'Source entity name (defaults to the memory name)' },
+                        relation: { type: 'string', description: 'Relation, snake_case, e.g. depends_on / decided_by / conflicts_with' },
+                        dst: { type: 'string', description: 'Target entity name' },
+                        fact: { type: 'string', description: 'Optional one-line statement for the edge' },
+                    },
+                    required: ['relation', 'dst'],
+                },
+            },
         },
         required: ['name', 'summary', 'body'],
     },
@@ -37,16 +53,37 @@ export const memorySaveTool = {
         if (!body)
             return '错误:缺少 body。';
         const type = typeof args.type === 'string' ? args.type : undefined;
+        const scope = args.scope === 'global' ? 'global' : 'project';
         const r = saveEntry({
             name,
             summary,
             body,
             type,
             pinned: args.pinned === true,
-            scope: args.scope === 'global' ? 'global' : 'project',
+            scope,
         });
-        if (r.ok)
-            return `已保存记忆 [${r.id}] "${name}"(下次启动进索引)。`;
-        return `已存在同名记忆 [${r.exists}]。改用 memory_update(id="${r.exists}", …) 更新,或换一个 name。`;
+        if (!r.ok) {
+            return `已存在同名记忆 [${r.exists}]。改用 memory_update(id="${r.exists}", …) 更新,或换一个 name。`;
+        }
+        // 知识图谱挂边:容错——图失败不影响记忆保存结果
+        const links = Array.isArray(args.links) ? args.links : [];
+        let linked = 0;
+        for (const l of links) {
+            if (!l || typeof l !== 'object')
+                continue;
+            const link = l;
+            const tr = addTriple({
+                src: typeof link.src === 'string' && link.src.trim() ? link.src : name,
+                relation: typeof link.relation === 'string' ? link.relation : '',
+                dst: typeof link.dst === 'string' ? link.dst : '',
+                fact: typeof link.fact === 'string' ? link.fact : undefined,
+                sourceEntry: r.id,
+                scope,
+            });
+            if (tr.ok)
+                linked++;
+        }
+        const linkNote = links.length > 0 ? `;知识图谱挂边 ${linked}/${links.length}` : '';
+        return `已保存记忆 [${r.id}] "${name}"(下次启动进索引)${linkNote}。`;
     },
 };

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

@@ -1,10 +1,13 @@
 import { searchEntries } from '../../memory/store.js';
+import { searchGraph } from '../../memory/graph.js';
 // ---------- memory_search ----------
-// 关键词搜记忆正文(多词子串匹配,name 权重最高)。命中即 bump recallCount(遗忘衰减依据)。
+// 唯一记忆搜索入口:关键词搜记忆正文(多词子串匹配,name 权重最高)+ 知识图谱事实段
+// (命中实体的 active 边)。命中条目即 bump recallCount(遗忘衰减依据)。
 // 结果走 capToolResultForHistory 的放宽上限(同 use_skill,保正文完整)。
+const GRAPH_FACTS_LIMIT = 10;
 export const memorySearchTool = {
     name: 'memory_search',
-    description: 'Search memory entries by keyword (substring match), returning full body.',
+    description: 'Search memory entries by keyword (substring match), returning full body. Also surfaces knowledge-graph facts (active edges) for entities matching the query.',
     parameters: {
         type: 'object',
         properties: {
@@ -33,10 +36,28 @@ export const memorySearchTool = {
                 : undefined,
             limit: typeof args.limit === 'number' ? args.limit : undefined,
         });
-        if (r.length === 0)
-            return `(无匹配记忆:query="${query}")`;
-        return r
+        const entryText = r
             .map((e) => `# [${e.id}] ${e.name} (${e.type}, recalled ${e.recallCount})\nsummary: ${e.summary}\n\n${e.body}`)
             .join('\n\n---\n\n');
+        // 知识图谱事实段:命中实体的 active 边(容错:图坏了不连累条目搜索)。
+        let graphText = '';
+        try {
+            const g = searchGraph(query, 8);
+            if (g.edges.length > 0) {
+                const lines = g.edges
+                    .slice(0, GRAPH_FACTS_LIMIT)
+                    .map((e) => `${e.src} --[${e.relation}]--> ${e.dst}${e.fact ? ` (${e.fact})` : ''}`);
+                const more = g.edges.length > GRAPH_FACTS_LIMIT ? `\n…(共 ${g.edges.length} 条,其余用 memory_graph action=neighbors 展开)` : '';
+                graphText = `\n\n## 知识图谱事实\n${lines.join('\n')}${more}`;
+            }
+        }
+        catch {
+            // 静默:图谱段是增强,失败只降级为纯条目结果
+        }
+        if (!entryText && !graphText)
+            return `(无匹配记忆:query="${query}")`;
+        if (!entryText)
+            return `(无匹配记忆条目,但图谱有命中)\n${graphText.trimStart()}`;
+        return entryText + graphText;
     },
 };

package/dist/tools/builtins/note-append.js

@@ -0,0 +1,103 @@
+import { appendNoteToSection, NOTE_SECTION_KEYS } from '../../session/notes.js';
+/**
+ * note_append:往会话笔记 notes.md 的预设笔记段追加一条 finding/decision/
+ * open_question/risk。与 plan_update 的边界:
+ *  - plan_update 维护执行计划(步骤进度),写 `## Plan:` 段;
+ *  - note_append 记发现/决策/问题/风险,写 `## Findings` 等笔记段。
+ * 写入的笔记正文会由 reinject 注入 system prompt 并常驻(5k token 预算内),
+ * compact 后仍可恢复——构成单会话永久记忆。与 memory_* 的边界:
+ *  - note_append 记本会话内、抗 compact 的笔记;
+ *  - memory_* 记跨会话稳定事实(另一系统,默认关)。
+ *
+ * 仿 plan_update:risk=safe,免权限/免 diff/免回滚;capabilities 由 builtins/index.ts
+ * 声明为 session-notepad 资源串行(与 plan_update 同款)。
+ */
+function err(message) {
+    return { status: 'error', code: 'INVALID_ARGUMENTS', retryable: false, output: `错误:${message}` };
+}
+/** 归一化 section:兼容单复数、下划线/空格/连字符、大小写偏差。 */
+function normalizeSection(raw) {
+    const s = String(raw ?? '').trim().toLowerCase().replace(/[-\s]+/g, '_');
+    if (NOTE_SECTION_KEYS.includes(s))
+        return s;
+    // 单数/别名归一
+    if (['finding', 'find', 'insight', 'insights'].includes(s))
+        return 'findings';
+    if (['decision', 'decide', 'choice', 'choices'].includes(s))
+        return 'decisions';
+    if (['open_question', 'question', 'questions', 'openquestion', 'openquestions'].includes(s))
+        return 'open_questions';
+    if (['risk', 'hazard', 'caveat', 'caveats'].includes(s))
+        return 'risks';
+    return null;
+}
+export const noteAppendTool = {
+    name: 'note_append',
+    description: 'Append a decision-grade note (a finding, decision, open question, or risk) to the session notepad ' +
+        '(`.mocode/sessions/<id>/notes.md`) so it survives context compaction and stays resident in the prompt. ' +
+        'Use this for NON-OBVIOUS, lasting-value discoveries — subtle constraints, decisions with downstream impact, ' +
+        'open questions that block a choice, or risks that affect later steps. Do NOT use it for routine progress ' +
+        '(that is the plan via `plan_update`) or for stable cross-session facts (that is `memory_save`). ' +
+        'Notes you write here persist across compaction within this session and are re-injected into the prompt ' +
+        'automatically, so the agent keeps remembering what it found/decided. Call it the moment you make the ' +
+        'discovery or decision — do not batch to the end.',
+    risk: 'safe',
+    parameters: {
+        type: 'object',
+        properties: {
+            section: {
+                type: 'string',
+                enum: NOTE_SECTION_KEYS,
+                description: 'Note category: findings (a non-obvious discovery/constraint), decisions (a choice with ' +
+                    'lasting impact), open_questions (a blocker needing resolution), risks (a hazard affecting later work).',
+            },
+            entry: {
+                type: 'string',
+                description: 'The note text. One concise, self-contained item: what was found/decided and why it matters. ' +
+                    'Keep each call to one item — call again for a second item.',
+            },
+            tag: {
+                type: 'string',
+                description: 'Optional short label for grouping (e.g. "parser-bug", "api-shape"). Rendered as **[tag]**.',
+            },
+        },
+        required: ['section', 'entry'],
+        additionalProperties: false,
+    },
+    // 兼容模型的 section 命名偏差:单复数/分隔符/别名归一到预设 key。
+    normalizeArguments(args) {
+        const s = normalizeSection(args.section);
+        if (s)
+            args.section = s;
+        if (typeof args.tag === 'string')
+            args.tag = args.tag.trim();
+    },
+    async execute(args) {
+        const section = normalizeSection(args.section);
+        if (!section) {
+            return err(`section 非法:"${String(args.section ?? '')}"(仅 ${NOTE_SECTION_KEYS.join('/')} 或常见别名)。`);
+        }
+        const entry = String(args.entry ?? '').trim();
+        if (!entry)
+            return err('entry 不能为空。');
+        if (entry.length > 2000) {
+            return err(`entry 过长(${entry.length} 字符,上限 2000)——拆成多条 note_append 或精简。`);
+        }
+        const tag = typeof args.tag === 'string' && args.tag.trim() ? args.tag.trim() : undefined;
+        const result = appendNoteToSection(section, entry, tag);
+        if ('error' in result) {
+            return { status: 'error', code: 'EXECUTION_ERROR', retryable: false, output: `错误:写入 notes.md 失败: ${result.error}` };
+        }
+        // note_append 写内部 notes.md,不作为用户代码 mutation 上报 changedFiles(与 plan_update 一致)。
+        const titleMap = {
+            findings: 'Findings', decisions: 'Decisions', open_questions: 'Open Questions', risks: 'Risks',
+        };
+        const rendered = tag ? `- **[${tag}]** ${entry}` : `- ${entry}`;
+        return {
+            status: 'success',
+            code: 'OK',
+            retryable: false,
+            output: `已追加笔记到 ## ${titleMap[section]} 段(将常驻 prompt,抗 compact):\n${rendered}`,
+        };
+    },
+};

package/dist/tools/constants.js

@@ -23,6 +23,11 @@ export const DECAY_DAYS = 30;
 export const GC_DAYS = 90;
 /** memory_search 结果(召回的记忆正文)的放宽上限:指令性内容,中截破坏语义,对齐 use_skill。 */
 export const MAX_MEMORY_RESULT = 64000;
+// ── 知识图谱层(memory-graph.json,单 scope 容量)──────────────────────────
+/** 单 scope 实体封顶:超限先清孤儿实体(无 active 边相连),仍超则拒绝新建。 */
+export const MAX_GRAPH_ENTITIES = 500;
+/** 单 scope 边封顶:超限先清已失效边,仍超则拒绝新边。 */
+export const MAX_GRAPH_EDGES = 2000;
 // .codegraph:codegraph 索引目录(codegraph.db 是 SQLite 二进制 + daemon.log),
 // grep/glob 扫它无意义且会产出数 KB 的超长「行」,污染 TUI 展开渲染。
 export const IGNORE = ['**/node_modules/**', '**/.git/**', '**/.codegraph/**'];
@@ -56,6 +61,7 @@ export const PLAN_DISABLED_TOOLS = new Set([
     'memory_save',
     'memory_update',
     'memory_forget',
+    'memory_graph', // 混合工具(add 写图),plan 只读模式整体屏蔽
     'sub-agent',
     'run_skill', // fork 子 agent 执行面;plan 模式不应派生子工作流
 ]);