mocode-ai 1.7.10 → 1.8.0

package/dist/memory/graph.js

@@ -93,7 +93,7 @@ function writeGraphForScope(scope, g) {
     writeGraphAtomic(p, { entities: g.entities, edges: g.edges });
 }
 /** 单 scope 的完整图(读文件,scope 归一化)。 */
-function loadScopeGraph(scope) {
+export function loadScopeGraph(scope) {
     const g = readGraphFile(graphPathForScope(scope));
     for (const e of g.entities)
         e.scope = scope;
@@ -125,6 +125,7 @@ export function upsertEntity(name, opts = {}) {
     const trimmed = name.trim();
     if (!trimmed)
         return { id: '', created: false, rejected: 'empty-name' };
+    const nextType = opts.type?.trim() || undefined;
     const g = loadScopeGraph(scope);
     const hit = findEntityIn(g, trimmed);
     if (hit) {
@@ -137,6 +138,10 @@ export function upsertEntity(name, opts = {}) {
             hit.summary = opts.summary.trim();
             dirty = true;
         }
+        if (nextType && (hit.type ?? '') !== nextType) {
+            hit.type = nextType;
+            dirty = true;
+        }
         if (dirty) {
             hit.updatedAt = nowIso();
             writeGraphForScope(scope, g);
@@ -163,6 +168,7 @@ export function upsertEntity(name, opts = {}) {
         name: trimmed,
         aliases: opts.alias && norm(opts.alias) !== norm(trimmed) ? [opts.alias.trim()] : [],
         summary: opts.summary?.trim() ?? '',
+        type: nextType,
         createdAt: now,
         updatedAt: now,
         scope,
@@ -257,6 +263,95 @@ export function searchGraph(query, limit = 8) {
     const edges = g.edges.filter((e) => !e.invalidAt && (hitIds.has(e.src) || hitIds.has(e.dst)));
     return { entities: scored.map((x) => x.e), edges };
 }
+// ── 边(事实)级词面检索:供 memory_search 的图谱事实段 ─────────────────────
+// searchGraph 是实体名/别名子串匹配,中文整句 fact 与多词 query 召回弱。这里用
+// context/text-search 的 CJK 分词(unigram+bigram)对「端点实体名/别名 + relation +
+// fact」做加权词面打分,再做一跳邻接扩展(命中实体相连的其它 active 边,降权补全)。
+import { tokenize } from '../context/text-search.js';
+const FIELD_WEIGHTS = { name: 6, alias: 4, fact: 2, relation: 2 };
+/** 统计 query terms 在一段文本里的命中次数。 */
+function termHits(terms, text) {
+    if (!text)
+        return 0;
+    const lower = text.toLowerCase();
+    let hits = 0;
+    for (const t of terms)
+        if (lower.includes(t))
+            hits++;
+    return hits;
+}
+/**
+ * 边级相关度检索。仅 active 边;按 scope 过滤。排序:score 降序、其次边 id(稳定)。
+ * 要求至少一个 query term 直接命中才返回(邻接边依附于直接命中,不会凭空出现)。
+ */
+export function searchGraphFacts(query, opts = {}) {
+    const terms = [...new Set(tokenize(query))];
+    if (terms.length === 0)
+        return [];
+    const scope = opts.scope ?? 'all';
+    const limit = Math.max(1, opts.limit ?? 8);
+    const neighborCap = Math.max(0, opts.neighbors ?? 4);
+    const g = loadAllGraph();
+    const inScope = (s) => scope === 'all' || s === scope;
+    const byId = new Map(g.entities.map((e) => [e.id, e]));
+    const activeEdges = g.edges.filter((e) => !e.invalidAt && inScope(e.scope));
+    const scoreEdge = (e) => {
+        const src = byId.get(e.src);
+        const dst = byId.get(e.dst);
+        let score = 0;
+        if (src) {
+            score += termHits(terms, src.name) * FIELD_WEIGHTS.name;
+            for (const a of src.aliases)
+                score += termHits(terms, a) * FIELD_WEIGHTS.alias;
+        }
+        if (dst) {
+            score += termHits(terms, dst.name) * FIELD_WEIGHTS.name;
+            for (const a of dst.aliases)
+                score += termHits(terms, a) * FIELD_WEIGHTS.alias;
+        }
+        score += termHits(terms, e.relation) * FIELD_WEIGHTS.relation;
+        score += termHits(terms, e.fact) * FIELD_WEIGHTS.fact;
+        return score;
+    };
+    const direct = activeEdges
+        .map((edge) => ({ edge, score: scoreEdge(edge) }))
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score || a.edge.id.localeCompare(b.edge.id));
+    const chosen = [];
+    const chosenIds = new Set();
+    const hitEndpoints = new Set();
+    for (const { edge, score } of direct.slice(0, limit)) {
+        chosen.push({
+            edge,
+            srcEntity: byId.get(edge.src) ?? null,
+            dstEntity: byId.get(edge.dst) ?? null,
+            score,
+            viaNeighbor: false,
+        });
+        chosenIds.add(edge.id);
+        hitEndpoints.add(edge.src);
+        hitEndpoints.add(edge.dst);
+    }
+    // 一跳邻接:命中实体相连的其它 active 边,固定降权(0.45× 直接边的保底分),补足上下文。
+    if (neighborCap > 0 && chosen.length > 0) {
+        const directTop = direct[0]?.score ?? 1;
+        const neighborScore = Math.max(1, Math.round(directTop * 0.45));
+        const extras = activeEdges
+            .filter((e) => !chosenIds.has(e.id) && (hitEndpoints.has(e.src) || hitEndpoints.has(e.dst)))
+            .sort((a, b) => a.id.localeCompare(b.id))
+            .slice(0, neighborCap);
+        for (const edge of extras) {
+            chosen.push({
+                edge,
+                srcEntity: byId.get(edge.src) ?? null,
+                dstEntity: byId.get(edge.dst) ?? null,
+                score: neighborScore,
+                viaNeighbor: true,
+            });
+        }
+    }
+    return chosen;
+}
 function buildAdjacency(g, relation) {
     const adj = new Map();
     for (const e of g.edges) {
@@ -407,3 +502,169 @@ export function graphStats() {
         byScope: { project: count('project'), global: count('global') },
     };
 }
+// ── 规范用户画像实体(G0 身份归一)──────────────────────────────────────────
+//
+// 全局图里历史上反思自由起名,把同一个用户碎成多个实体(实测:mocode user / 万 /
+// user-name-wanjizhu / user-role-… 互不相连)。这里固定一个主键实体,所有"关于人"
+// 的属性都挂到它身上;角色值(user-role-*)是属性的**值**不是人,不并入。
+/** 全局规范用户实体的固定 id(概念名 person:primary,实现用文件安全 slug)。 */
+export const PRIMARY_PERSON_ID = 'person-primary';
+/** 规范用户实体的轻量类型标记。 */
+export const PERSON_TYPE = 'Person';
+/** 未分型实体的占位类型(历史数据无 type 字段时按此处理,不参与跨类型守卫)。 */
+export const UNKNOWN_TYPE = 'unknown';
+/** 实体有效类型(缺省/空串视为 unknown)。 */
+function entityType(e) {
+    const t = (e.type ?? '').trim();
+    return t || UNKNOWN_TYPE;
+}
+/** 判定一个全局实体是否"用户指称碎片"(应并入 primary),角色值实体除外。 */
+function isPersonFragment(e, selfNameHints) {
+    const id = e.id.toLowerCase();
+    const name = e.name.trim().toLowerCase();
+    if (id === PRIMARY_PERSON_ID)
+        return false;
+    if (id.startsWith('user-role-'))
+        return false; // 角色值,不是人
+    if (id === 'mocode-user' || name === 'mocode user')
+        return true;
+    if (id.startsWith('user-name-'))
+        return true;
+    // 经 named 边收集到的自称(如"万")
+    if (selfNameHints.has(name))
+        return true;
+    return false;
+}
+/** 确保全局规范用户实体存在(固定 id,绕过自由 slug);返回其最新内容。 */
+export function ensurePrimaryPerson(displayName) {
+    const scope = 'global';
+    const g = loadScopeGraph(scope);
+    let p = g.entities.find((e) => e.id === PRIMARY_PERSON_ID);
+    if (!p) {
+        const now = nowIso();
+        p = {
+            id: PRIMARY_PERSON_ID,
+            name: (displayName ?? 'user').trim() || 'user',
+            aliases: [],
+            summary: '规范用户实体(所有跨项目的用户画像属性挂这里)',
+            type: PERSON_TYPE,
+            createdAt: now,
+            updatedAt: now,
+            scope,
+        };
+        g.entities.push(p);
+        writeGraphForScope(scope, g);
+        return p;
+    }
+    let dirty = false;
+    if (entityType(p) !== PERSON_TYPE) {
+        p.type = PERSON_TYPE; // 历史库回填:G0 已建的 primary 当时无 type
+        dirty = true;
+    }
+    if (displayName && displayName.trim() && displayName.trim() !== p.name) {
+        if (!p.aliases.includes(p.name))
+            p.aliases.push(p.name);
+        p.name = displayName.trim();
+        dirty = true;
+    }
+    if (!p.summary) {
+        p.summary = '规范用户实体(所有跨项目的用户画像属性挂这里)';
+        dirty = true;
+    }
+    if (dirty) {
+        p.updatedAt = nowIso();
+        writeGraphForScope(scope, g);
+    }
+    return p;
+}
+/**
+ * 把同一 scope 内 source 实体并入 target:
+ *  - source 的 active 边 endpoint 改写为 target;改写后与 target 现有 active 边
+ *    (src,relation,dst) 全等的重复边置 invalidAt(时序失效,不删);
+ *  - source 名字/别名并入 target.aliases;source 标 mergedInto 保留(可追溯、可被别名词命中)。
+ * 类型守卫(轻量本体):双方都已明确分型(非 unknown)且类型不同 → 拒绝,防止把
+ * Port/Hobby 等异类实体误并进 Person;任一方 unknown(历史未分型)则照常允许。
+ * 幂等:source===target 或不存在则 no-op(null)。
+ */
+export function mergeEntities(targetId, sourceId, scope = 'global') {
+    if (targetId === sourceId)
+        return null;
+    const g = loadScopeGraph(scope);
+    const target = g.entities.find((e) => e.id === targetId);
+    const source = g.entities.find((e) => e.id === sourceId);
+    if (!target || !source)
+        return null;
+    const tt = entityType(target);
+    const st = entityType(source);
+    if (tt !== UNKNOWN_TYPE && st !== UNKNOWN_TYPE && tt !== st) {
+        return { target: targetId, merged: [], dedupedEdges: 0, rejected: `type-mismatch: ${st} != ${tt}` };
+    }
+    const activeOf = (id) => g.edges.filter((e) => !e.invalidAt && (e.src === id || e.dst === id));
+    const existsActive = (src, relation, dst) => g.edges.some((e) => !e.invalidAt && e.src === src && e.relation === relation && e.dst === dst);
+    let dedupedEdges = 0;
+    for (const edge of activeOf(sourceId)) {
+        const nextSrc = edge.src === sourceId ? targetId : edge.src;
+        const nextDst = edge.dst === sourceId ? targetId : edge.dst;
+        if (nextSrc === nextDst) {
+            edge.invalidAt = nowIso(); // 自指环(并入自己)无意义,失效
+            dedupedEdges++;
+            continue;
+        }
+        if (existsActive(nextSrc, edge.relation, nextDst) && (nextSrc !== edge.src || nextDst !== edge.dst)) {
+            edge.invalidAt = nowIso(); // target 已有等价 active 边,去重
+            dedupedEdges++;
+            continue;
+        }
+        edge.src = nextSrc;
+        edge.dst = nextDst;
+    }
+    const addAlias = (a) => {
+        const v = a.trim();
+        if (v && v !== target.name && !target.aliases.includes(v))
+            target.aliases.push(v);
+    };
+    addAlias(source.name);
+    for (const a of source.aliases)
+        addAlias(a);
+    source.mergedInto = targetId;
+    source.updatedAt = nowIso();
+    target.updatedAt = nowIso();
+    writeGraphForScope(scope, g);
+    return { target: targetId, merged: [sourceId], dedupedEdges };
+}
+/**
+ * 一次性身份归一(幂等):确保 person-primary 存在,把全局图里的用户指称碎片
+ * (mocode-user / user-name-* / 沿 named 边找到的自称,如"万")并入它。
+ * 角色值实体(user-role-*)、兴趣、地点、项目/工具实体不碰。返回合并报告(无操作时 merged 为空)。
+ */
+export function canonicalizePrimaryPerson() {
+    const scope = 'global';
+    const g = loadScopeGraph(scope);
+    // 沿 named 边收集自称:X --named--> N,则 N.name 是用户的名字。
+    const selfNameHints = new Set();
+    for (const e of g.edges) {
+        if (e.invalidAt || e.relation !== 'named')
+            continue;
+        const src = g.entities.find((x) => x.id === e.src);
+        const dst = g.entities.find((x) => x.id === e.dst);
+        if (src && dst && (src.id === 'mocode-user' || src.id.startsWith('user-name-') || /user/i.test(src.name))) {
+            selfNameHints.add(dst.name.trim().toLowerCase());
+        }
+    }
+    const fragments = g.entities.filter((e) => isPersonFragment(e, selfNameHints));
+    // 显示名:优先最短的中文/字母自称(通常是"万"),退回已存在 primary 的名字。
+    const existing = g.entities.find((e) => e.id === PRIMARY_PERSON_ID);
+    const nameCandidates = [...selfNameHints].filter((n) => n && !/^user/.test(n));
+    const displayName = nameCandidates.sort((a, b) => a.length - b.length)[0] ?? existing?.name ?? null;
+    ensurePrimaryPerson(displayName ?? undefined);
+    let deduped = 0;
+    const merged = [];
+    for (const f of fragments) {
+        const r = mergeEntities(PRIMARY_PERSON_ID, f.id, scope);
+        if (r && !r.rejected) {
+            merged.push(f.id);
+            deduped += r.dedupedEdges;
+        }
+    }
+    return { primary: PRIMARY_PERSON_ID, displayName, merged, dedupedEdges: deduped };
+}

package/dist/memory/index.js

@@ -3,5 +3,7 @@
 // (buildAgentsImportSection) auto-imports the workspace-root AGENTS.md body into the
 // system prompt — independent of the memory switch — truncating it when it exceeds the cap.
 export { buildMemoryIndexSection, loadAll, gcMemories, } from './store.js';
-export { addTriple, upsertEntity, findEntity, searchGraph, neighborsOf, pathBetween, graphStats, } from './graph.js';
+export { addTriple, upsertEntity, findEntity, searchGraph, searchGraphFacts, neighborsOf, pathBetween, graphStats, ensurePrimaryPerson, mergeEntities, canonicalizePrimaryPerson, PRIMARY_PERSON_ID, } from './graph.js';
+export { buildAboutYouSection, initPersona, __resetPersonaInitForTests, ABOUT_YOU_MAX_CHARS } from './persona.js';
+export { buildProjectGraphHint, GRAPH_HINT_MAX_CHARS } from './recall.js';
 export { kickoffReflection, drainMemoryBackground, getLastReflectResult, clearLastReflectResult, snapshotTranscript, formatReflectResult, runReflection, } from './reflect.js';

package/dist/memory/persona.js

@@ -0,0 +1,142 @@
+// persona.ts —— 全局「用户画像」内化层(Memory 2.1 双轨的 global 轨)。
+//
+// 与 buildMemoryIndexSection(条目摘要、按需召回、会衰减)不同,这里产出的
+// `## About you` 是**高等级(L2)画像**:锚定在全局规范实体 person-primary 的
+// active 图谱边上,每个会话无条件常驻 system prompt,体量硬封顶以保护 prompt cache。
+// 身份类事实用图谱时序边表达(换工作/搬家时旧边 invalidAt),天然不受 memory 条目
+// 30 天衰减影响——这是"越用越懂用户"那条易失通道之外的确定性内化通道。
+//
+// 纯读、不建实体(建实体/归一走 graph.canonicalizePrimaryPerson,在启动期显式做)。
+import { loadScopeGraph, canonicalizePrimaryPerson, PRIMARY_PERSON_ID, } from './graph.js';
+/** About you 段硬预算(字符):只放高等级画像,超了按置信/顺序截断。 */
+export const ABOUT_YOU_MAX_CHARS = 800;
+/** 关系 → 人类可读标签(画像白名单;不在表内的关系用 fact 原文,仍可展示)。 */
+const RELATION_LABEL = {
+    named: '称呼',
+    has_role: '角色',
+    works_at: '就职于',
+    located_in: '所在地',
+    speaks: '语言',
+    verbosity: '回复详略',
+    communication_style: '沟通风格',
+    current_goal: '当前目标',
+    constraint: '约束',
+    prefers: '偏好',
+    avoids: '避免',
+    travel_preference: '旅行偏好',
+    has_hobby: '兴趣',
+    skill_level: '擅长',
+    related_to: '相关',
+};
+function displayName(name) {
+    // 图谱里部分历史实体名是 snake_case(leisure_travel / hangzhou),展示时松绑。
+    if (/[\u4e00-\u9fff]/.test(name))
+        return name;
+    return name.replace(/[_-]+/g, ' ').trim();
+}
+/**
+ * 渲染全局 L2 画像段。无 person-primary / 无 active 画像边 → 空串(零注入)。
+ * 优先用边上的中文 fact 原文;没有 fact 时用「关系标签 + 目标实体名」。
+ * 同名去重;has_hobby 合并为一行;整体截断到 ABOUT_YOU_MAX_CHARS。
+ */
+export function buildAboutYouSection(memoryEnabled = true) {
+    if (!memoryEnabled)
+        return '';
+    const g = loadScopeGraph('global');
+    const me = g.entities.find((e) => e.id === PRIMARY_PERSON_ID);
+    if (!me)
+        return '';
+    const byId = new Map(g.entities.map((e) => [e.id, e]));
+    const outgoing = g.edges.filter((e) => !e.invalidAt && e.src === PRIMARY_PERSON_ID && e.dst !== PRIMARY_PERSON_ID);
+    if (outgoing.length === 0)
+        return '';
+    const hobbies = [];
+    const lines = [];
+    const seen = new Set();
+    const push = (text, relation) => {
+        const key = text.trim();
+        if (!key || seen.has(key))
+            return;
+        seen.add(key);
+        lines.push({ text: key, relation });
+    };
+    for (const e of outgoing) {
+        const dst = byId.get(e.dst);
+        const target = dst ? displayName(dst.name) : displayName(e.dst);
+        if (e.relation === 'has_hobby') {
+            if (target && !hobbies.includes(target))
+                hobbies.push(target);
+            continue;
+        }
+        if (e.fact && e.fact.trim()) {
+            push(e.fact.trim(), e.relation);
+        }
+        else {
+            const label = RELATION_LABEL[e.relation] ?? e.relation.replace(/_/g, ' ');
+            push(`${label}:${target}`, e.relation);
+        }
+    }
+    if (hobbies.length)
+        push(`兴趣:${hobbies.join('、')}`, 'has_hobby');
+    if (lines.length === 0)
+        return '';
+    // 稳定排序:白名单关系按预定义优先级,其余按文本;让输出跨会话稳定(护 cache)。
+    const order = Object.keys(RELATION_LABEL);
+    lines.sort((a, b) => {
+        const ia = order.indexOf(a.relation);
+        const ib = order.indexOf(b.relation);
+        if (ia !== ib)
+            return (ia === -1 ? 999 : ia) - (ib === -1 ? 999 : ib);
+        return a.text.localeCompare(b.text);
+    });
+    const header = `## About you(长期用户画像,跨项目始终生效)`;
+    // 内部 slug 实体名(mocode user / user-name-* 归一后留下的别名)不作为"又称"展示。
+    const visibleAliases = me.aliases
+        .map(displayName)
+        .filter((a) => a && a !== displayName(me.name) && !/^(mocode user|user name)\b/i.test(a));
+    const nameLine = `- 用户:${displayName(me.name)}${visibleAliases.length ? `(又称 ${visibleAliases.join('、')})` : ''}`;
+    const body = ['', header, nameLine, ...lines.map((l) => `- ${l.text}`)].join('\n');
+    if (body.length <= ABOUT_YOU_MAX_CHARS)
+        return body;
+    // 截断:从低优先级行往前丢,保住身份/地点/目标等高等级项。
+    const kept = [header, nameLine];
+    let budget = ABOUT_YOU_MAX_CHARS - kept.join('\n').length;
+    for (const l of lines) {
+        const piece = `- ${l.text}`;
+        if (piece.length + 1 > budget)
+            continue;
+        kept.push(piece);
+        budget -= piece.length + 1;
+    }
+    return kept.join('\n');
+}
+/** 仅供测试/调试:列出 person-primary 当前 active 画像边(原始结构)。 */
+export function inspectPrimaryProfile() {
+    const g = loadScopeGraph('global');
+    const me = g.entities.find((e) => e.id === PRIMARY_PERSON_ID) ?? null;
+    const edges = g.edges.filter((e) => !e.invalidAt && (e.src === PRIMARY_PERSON_ID || e.dst === PRIMARY_PERSON_ID));
+    return { me, edges };
+}
+let personaInitialized = false;
+/**
+ * 启动期幂等初始化:做一次全局身份归一(把 mocode-user / user-name-* / 自称等碎片
+ * 并入 person-primary)。每进程至多一次;记忆开关关闭时不碰图谱。best-effort——
+ * 归一失败不应影响 REPL 启动(调用方自行 catch)。
+ */
+export function initPersona(memoryEnabled = true) {
+    if (personaInitialized)
+        return;
+    personaInitialized = true;
+    if (!memoryEnabled)
+        return;
+    try {
+        canonicalizePrimaryPerson();
+    }
+    catch {
+        // 归一只是增强(图谱损坏/IO 异常),绝不能拖垮 REPL 启动。
+    }
+}
+/** 测试专用:重置进程内初始化标记。 */
+export function __resetPersonaInitForTests() {
+    personaInitialized = false;
+}

package/dist/memory/recall-stats.js

@@ -0,0 +1,61 @@
+// recall-stats.ts —— 项目图谱 pull 召回的轻量埋点。
+//
+// 目的(memory-2.2 决策):项目图谱曾"只写不读"。pull 通道(常驻 hint + memory_search
+// 强化)上线后,用零依赖计数器回答"模型到底有没有在用图谱":搜了几次、图谱段有几次命中。
+// 数据只存项目 <cwd>/.mocode/memory-recall-stats.json,供 memory_graph stats 展示,据此
+// 决定要不要再加"turn 起步阈值注入"的安全网。全部静默容错、tmp+rename 原子写。
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+const EMPTY = { searches: 0, graphHits: 0, graphEmpty: 0, lastSearchedAt: null };
+function statsPath() {
+    return path.join(process.cwd(), '.mocode', 'memory-recall-stats.json');
+}
+/** 读取项目召回统计;文件缺失/损坏一律返回零值(不抛错)。 */
+export function readRecallStats() {
+    try {
+        const p = statsPath();
+        if (!existsSync(p))
+            return { ...EMPTY };
+        const obj = JSON.parse(readFileSync(p, 'utf8'));
+        return {
+            searches: Number.isFinite(obj.searches) ? Number(obj.searches) : 0,
+            graphHits: Number.isFinite(obj.graphHits) ? Number(obj.graphHits) : 0,
+            graphEmpty: Number.isFinite(obj.graphEmpty) ? Number(obj.graphEmpty) : 0,
+            lastSearchedAt: typeof obj.lastSearchedAt === 'string' ? obj.lastSearchedAt : null,
+        };
+    }
+    catch {
+        return { ...EMPTY };
+    }
+}
+/**
+ * 记录一次 memory_search。graphHit=true 表示图谱事实段非空。
+ * 返回更新后的统计;写盘失败静默(埋点绝不影响检索主流程)。
+ */
+export function recordRecallSearch(graphHit) {
+    const s = readRecallStats();
+    s.searches += 1;
+    if (graphHit)
+        s.graphHits += 1;
+    else
+        s.graphEmpty += 1;
+    s.lastSearchedAt = new Date().toISOString();
+    try {
+        const p = statsPath();
+        mkdirSync(path.dirname(p), { recursive: true });
+        const tmp = p + '.tmp';
+        writeFileSync(tmp, JSON.stringify(s, null, 2), 'utf8');
+        renameSync(tmp, p);
+    }
+    catch {
+        // 静默:埋点不可写不影响功能
+    }
+    return s;
+}
+/** 一行人类可读摘要(供 memory_graph stats)。 */
+export function formatRecallStats(s = readRecallStats()) {
+    if (s.searches === 0)
+        return '图谱召回:尚无 memory_search 调用(pull 通道未被使用)';
+    const rate = Math.round((s.graphHits / s.searches) * 100);
+    return `图谱召回:memory_search ${s.searches} 次,图谱命中 ${s.graphHits}(${rate}%) / 空 ${s.graphEmpty}`;
+}

package/dist/memory/recall.js

@@ -0,0 +1,47 @@
+// recall.ts —— 项目知识图谱的「可检索性」提示(pull 召回的触发器)。
+//
+// 问题:项目 triples 写入 memory-graph.json 后,常驻上下文里没有任何线索告诉模型
+// "仓库里存了这些事实",模型不知道要搜 → 85 条事实近乎只写不读。这里产出一小段
+// 稳定的项目图谱提示(主要主题实体 + 检索指引),拼进 system prompt,让模型在相关时
+// 主动 memory_search / memory_graph。只给"地图"不给正文,正文仍走按需 pull(零空转成本)。
+//
+// 与 About you(global、内化画像)对称:这是 project 轨、可检索的仓库事实索引。
+// 纯读、叶子依赖(graph)。内容只依赖图文件,会话内不随每步变化(同 Memory Index 的启动快照语义)。
+import { loadScopeGraph } from './graph.js';
+/** 图谱提示段硬预算(字符)。 */
+export const GRAPH_HINT_MAX_CHARS = 600;
+/** 列出的主题实体上限。 */
+const GRAPH_HINT_TOP_ENTITIES = 12;
+/**
+ * 项目图谱常驻提示:无 active 边 → 空串(零注入)。
+ * 主题实体按 active 度数(参与的 active 边数)降序、再按名字排序,取前 N。
+ */
+export function buildProjectGraphHint(memoryEnabled = true, scope = 'project') {
+    if (!memoryEnabled)
+        return '';
+    const g = loadScopeGraph(scope);
+    const activeEdges = g.edges.filter((e) => !e.invalidAt);
+    if (activeEdges.length === 0)
+        return '';
+    const degree = new Map();
+    for (const e of activeEdges) {
+        degree.set(e.src, (degree.get(e.src) ?? 0) + 1);
+        degree.set(e.dst, (degree.get(e.dst) ?? 0) + 1);
+    }
+    const named = g.entities.filter((x) => !!x && typeof x.name === 'string' && x.name.length > 0);
+    const top = named
+        .map((e) => ({ e, d: degree.get(e.id) ?? 0 }))
+        .filter((x) => x.d > 0)
+        .sort((a, b) => b.d - a.d || a.e.name.localeCompare(b.e.name))
+        .slice(0, GRAPH_HINT_TOP_ENTITIES)
+        .map((x) => x.e.name);
+    const header = `## Project knowledge graph (query on demand, not auto-loaded)`;
+    const body = `This repo has a memory graph with ${g.entities.length} entities / ${activeEdges.length} facts ` +
+        `(modules, tools, configs, decisions, pitfalls…). When relevant to the current task, query it before re-deriving: ` +
+        `memory_search("keywords") also returns matching graph facts (CJK-aware, with one-hop neighbors); ` +
+        `memory_graph action=neighbors|path expands connections. Main subjects: ${top.join('、')}.`;
+    const out = ['', header, body].join('\n');
+    return out.length <= GRAPH_HINT_MAX_CHARS
+        ? out
+        : out.slice(0, GRAPH_HINT_MAX_CHARS).replace(/[、,]\s*[^、,]*$/, ' …');
+}