@co-engram/core 0.1.0

package/dist/perspectives/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/perspectives/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,iBAAiB,CAAC"}

package/dist/perspectives/index.js

@@ -0,0 +1,7 @@
+/**
+ * Perspectives 模块 barrel（P3 4.4）
+ *
+ * @module @co-engram/core/perspectives
+ */
+export * from "./multi-view.js";
+//# sourceMappingURL=index.js.map

package/dist/perspectives/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/perspectives/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,iBAAiB,CAAC"}

package/dist/perspectives/multi-view.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 多视角保留（spec §5.3 机制 3，P3 4.4）
+ *
+ * 抗认知失调：矛盾 engram 并存且都可检索，不强制消除矛盾。
+ *
+ * 设计原则：
+ *   - 检索时主动展示 contradicts 关系（双方都被返回）
+ *   - 不主动排除任一方（避免单视角确认偏误）
+ *   - 标注 resolutionState（pending/escalated/contested/...）
+ *   - perspective 字段记录 engram 所属视角（"team-a"、"expert-yang"）
+ *
+ * @module @co-engram/core/perspectives
+ */
+import type { EngramRepository } from "../storage/repository.js";
+import type { EngramKind, EngramId } from "../types/engram.js";
+import type { SynapseResolutionState } from "../types/synapse.js";
+/** 单条 contradicts 视图 */
+export interface ContradictingView {
+    readonly engramId: EngramId;
+    readonly title: string;
+    readonly kind: EngramKind;
+    readonly perspective?: string;
+    /** outgoing = center 主动反驳 other；incoming = other 反驳 center */
+    readonly direction: "outgoing" | "incoming";
+    readonly resolutionState?: SynapseResolutionState;
+    readonly synapseId: string;
+}
+/** 单个 engram 的多视角包 */
+export interface MultiViewBundle {
+    readonly centerId: EngramId;
+    readonly contradictions: readonly ContradictingView[];
+}
+/** 检索结果 + 附加视图 */
+export interface EnrichedResult {
+    readonly engramId: EngramId;
+    readonly contradictsViews: readonly ContradictingView[];
+}
+/** contradiction cluster（视角群） */
+export interface ContradictionCluster {
+    readonly clusterId: string;
+    readonly memberIds: readonly EngramId[];
+}
+/**
+ * 收集单个 engram 的所有 contradicts 视图（双向）
+ *
+ * outgoing: center 的 synapses.outgoing 中 kind=contradicts
+ * incoming: 其他 engram 的 outgoing 指向 center 且 kind=contradicts
+ */
+export declare function gatherContradictingViews(repo: EngramRepository, engramId: EngramId): MultiViewBundle;
+/**
+ * 检索结果后处理：对每个结果附加 contradicts 视图
+ *
+ * 关键设计：本函数**不会从结果中移除任何 engram**，只附加 contradicts 元信息。
+ * 即使 other 的 resolutionState=resolved 或 refuted，也仍然返回（保留审计痕迹）。
+ *
+ * @param resultIds 检索返回的 engram ID 列表
+ * @param options.maxViewsPerResult 每个结果最多附加多少个视图（默认 5）
+ */
+export declare function enrichWithContradictingViews(repo: EngramRepository, resultIds: readonly EngramId[], options?: {
+    readonly maxViewsPerResult?: number;
+}): EnrichedResult[];
+/**
+ * 找出整个仓库的 contradiction clusters（视角群）
+ *
+ * 算法：把 contradicts synapse 视为无向边，做 Union-Find 找连通分量。
+ * 每个 cluster 是一组互相矛盾的 engram（视角群）。
+ */
+export declare function findContradictionClusters(repo: EngramRepository): ContradictionCluster[];
+/**
+ * 统计：仓库中 multi-view 相关指标
+ */
+export interface MultiViewStats {
+    readonly totalContradictsEdges: number;
+    readonly activeContradictions: number;
+    readonly resolvedContradictions: number;
+    readonly clusters: number;
+    readonly largestClusterSize: number;
+    readonly distinctPerspectives: number;
+}
+export declare function computeMultiViewStats(repo: EngramRepository): MultiViewStats;
+//# sourceMappingURL=multi-view.d.ts.map

package/dist/perspectives/multi-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-view.d.ts","sourceRoot":"","sources":["../../src/perspectives/multi-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAElE,wBAAwB;AACxB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC;IAC5C,QAAQ,CAAC,eAAe,CAAC,EAAE,sBAAsB,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,sBAAsB;AACtB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACvD;AAED,kBAAkB;AAClB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACzD;AAED,iCAAiC;AACjC,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;CACzC;AAID;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,QAAQ,GACjB,eAAe,CA+DjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,gBAAgB,EACtB,SAAS,EAAE,SAAS,QAAQ,EAAE,EAC9B,OAAO,GAAE;IACP,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAChC,GACL,cAAc,EAAE,CAalB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,gBAAgB,GACrB,oBAAoB,EAAE,CAyExB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,gBAAgB,GAAG,cAAc,CAiC5E"}

package/dist/perspectives/multi-view.js

@@ -0,0 +1,221 @@
+/**
+ * 多视角保留（spec §5.3 机制 3，P3 4.4）
+ *
+ * 抗认知失调：矛盾 engram 并存且都可检索，不强制消除矛盾。
+ *
+ * 设计原则：
+ *   - 检索时主动展示 contradicts 关系（双方都被返回）
+ *   - 不主动排除任一方（避免单视角确认偏误）
+ *   - 标注 resolutionState（pending/escalated/contested/...）
+ *   - perspective 字段记录 engram 所属视角（"team-a"、"expert-yang"）
+ *
+ * @module @co-engram/core/perspectives
+ */
+const DEFAULT_MAX_VIEWS_PER_RESULT = 5;
+/**
+ * 收集单个 engram 的所有 contradicts 视图（双向）
+ *
+ * outgoing: center 的 synapses.outgoing 中 kind=contradicts
+ * incoming: 其他 engram 的 outgoing 指向 center 且 kind=contradicts
+ */
+export function gatherContradictingViews(repo, engramId) {
+    if (!repo.exists(engramId)) {
+        throw new Error(`Engram not found: ${engramId}`);
+    }
+    const views = [];
+    const seen = new Set();
+    // === outgoing：center 反驳别人 ===
+    const outgoing = repo.readSynapses(engramId).outgoing;
+    for (const syn of outgoing) {
+        if (syn.kind !== "contradicts")
+            continue;
+        if (!repo.exists(syn.to))
+            continue; // 跳过 dangling
+        const other = repo.readEngram(syn.to);
+        const key = `out:${syn.to}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        views.push({
+            engramId: other.id,
+            title: other.title,
+            kind: other.kind,
+            perspective: other.perspective,
+            direction: "outgoing",
+            resolutionState: syn.resolutionState,
+            synapseId: syn.id,
+        });
+    }
+    // === incoming：别人反驳 center ===
+    for (const entry of repo.listEngrams()) {
+        if (entry.id === engramId)
+            continue;
+        const file = repo.readSynapses(entry.id);
+        for (const syn of file.outgoing) {
+            if (syn.kind !== "contradicts")
+                continue;
+            if (syn.to !== engramId)
+                continue;
+            const other = repo.readEngram(entry.id);
+            const key = `in:${entry.id}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            views.push({
+                engramId: other.id,
+                title: other.title,
+                kind: other.kind,
+                perspective: other.perspective,
+                direction: "incoming",
+                resolutionState: syn.resolutionState,
+                synapseId: syn.id,
+            });
+        }
+    }
+    // 排序：incoming 优先（外部挑战更值得关注），然后按 engramId 字典序
+    views.sort((a, b) => {
+        if (a.direction !== b.direction) {
+            return a.direction === "incoming" ? -1 : 1;
+        }
+        return a.engramId < b.engramId ? -1 : 1;
+    });
+    return {
+        centerId: engramId,
+        contradictions: views,
+    };
+}
+/**
+ * 检索结果后处理：对每个结果附加 contradicts 视图
+ *
+ * 关键设计：本函数**不会从结果中移除任何 engram**，只附加 contradicts 元信息。
+ * 即使 other 的 resolutionState=resolved 或 refuted，也仍然返回（保留审计痕迹）。
+ *
+ * @param resultIds 检索返回的 engram ID 列表
+ * @param options.maxViewsPerResult 每个结果最多附加多少个视图（默认 5）
+ */
+export function enrichWithContradictingViews(repo, resultIds, options = {}) {
+    const maxViews = options.maxViewsPerResult ?? DEFAULT_MAX_VIEWS_PER_RESULT;
+    return resultIds.map((id) => {
+        if (!repo.exists(id)) {
+            return { engramId: id, contradictsViews: [] };
+        }
+        const bundle = gatherContradictingViews(repo, id);
+        return {
+            engramId: id,
+            contradictsViews: bundle.contradictions.slice(0, maxViews),
+        };
+    });
+}
+/**
+ * 找出整个仓库的 contradiction clusters（视角群）
+ *
+ * 算法：把 contradicts synapse 视为无向边，做 Union-Find 找连通分量。
+ * 每个 cluster 是一组互相矛盾的 engram（视角群）。
+ */
+export function findContradictionClusters(repo) {
+    // 收集所有 contradicts 边
+    const edges = [];
+    const allEngrams = new Set();
+    for (const entry of repo.listEngrams()) {
+        allEngrams.add(entry.id);
+        const file = repo.readSynapses(entry.id);
+        for (const syn of file.outgoing) {
+            if (syn.kind !== "contradicts")
+                continue;
+            if (!repo.exists(syn.to))
+                continue;
+            edges.push({ a: entry.id, b: syn.to });
+            allEngrams.add(syn.to);
+        }
+    }
+    // Union-Find
+    const parent = new Map();
+    function find(x) {
+        if (!parent.has(x))
+            parent.set(x, x);
+        let root = x;
+        while (parent.get(root) !== root) {
+            root = parent.get(root);
+        }
+        // path compression
+        let cur = x;
+        while (parent.get(cur) !== root) {
+            const next = parent.get(cur);
+            parent.set(cur, root);
+            cur = next;
+        }
+        return root;
+    }
+    function union(a, b) {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra !== rb) {
+            parent.set(ra, rb);
+        }
+    }
+    for (const e of edges) {
+        union(e.a, e.b);
+    }
+    // 收集每个 root 下的成员
+    const clusters = new Map();
+    for (const id of allEngrams) {
+        const root = find(id);
+        const arr = clusters.get(root) ?? [];
+        arr.push(id);
+        clusters.set(root, arr);
+    }
+    // 过滤：只保留 ≥ 2 个成员的 cluster（孤立节点不算 cluster）
+    const result = [];
+    for (const [, members] of clusters) {
+        if (members.length < 2)
+            continue;
+        const sorted = [...members].sort();
+        result.push({
+            clusterId: `cluster-${sorted[0].replace(/\//g, "_")}`,
+            memberIds: sorted,
+        });
+    }
+    // 排序：成员数多的优先；同 size 按 clusterId 字典序
+    result.sort((a, b) => {
+        if (b.memberIds.length !== a.memberIds.length) {
+            return b.memberIds.length - a.memberIds.length;
+        }
+        return a.clusterId < b.clusterId ? -1 : 1;
+    });
+    return result;
+}
+export function computeMultiViewStats(repo) {
+    let totalEdges = 0;
+    let active = 0;
+    let resolved = 0;
+    const perspectives = new Set();
+    for (const entry of repo.listEngrams()) {
+        const engram = repo.readEngram(entry.id);
+        if (engram.perspective)
+            perspectives.add(engram.perspective);
+        const file = repo.readSynapses(entry.id);
+        for (const syn of file.outgoing) {
+            if (syn.kind !== "contradicts")
+                continue;
+            totalEdges += 1;
+            const status = syn.resolutionState?.status;
+            if (status === "resolved" || status === "auto_resolved") {
+                resolved += 1;
+            }
+            else {
+                active += 1;
+            }
+        }
+    }
+    const clusters = findContradictionClusters(repo);
+    const largest = clusters.reduce((m, c) => Math.max(m, c.memberIds.length), 0);
+    return {
+        totalContradictsEdges: totalEdges,
+        activeContradictions: active,
+        resolvedContradictions: resolved,
+        clusters: clusters.length,
+        largestClusterSize: largest,
+        distinctPerspectives: perspectives.size,
+    };
+}
+//# sourceMappingURL=multi-view.js.map

package/dist/perspectives/multi-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-view.js","sourceRoot":"","sources":["../../src/perspectives/multi-view.ts"],"names":[],"mappings":"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"}

package/dist/prompt-builder/builder.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Co-Engram memory prompt builder(host-agnostic)
+ *
+ * 生成注入到 LLM 系统提示的 "## Memory Recall" section。
+ *
+ * 三层设计(可独立启用/禁用):
+ *
+ *   1. 基础引导(常驻)——何时调用 memory_search / 何时跳过 / 如何解读结果
+ *   2. Proposal 提醒(条件性)——count > 0 时注入
+ *   3. 自进化信号(条件性)——基于 prompt-signals.json:
+ *      - topTags(高频 engram 领域)
+ *      - lowConfidenceTopics(RPE false negative 检测)
+ *
+ * 所有文字走 i18n(en/zh)。
+ *
+ * 宿主集成:
+ *   - OpenClaw:`registerMemoryCapability.promptBuilder`
+ *   - Claude Code MCP:`serverInfo.instructions`(静态)+ hook(动态)
+ *
+ * @module @co-engram/core/prompt-builder
+ */
+import type { Language } from "../i18n/index.js";
+import type { BuildPromptInput, PromptBuilder, PromptSignals } from "./types.js";
+export type { BuildPromptInput, PromptBuilder, PromptSignals };
+/**
+ * 主构建函数:组装所有部分
+ *
+ * 返回 string[](宿主期望的 prompt lines 格式)。
+ * 每个 element 是一段,宿主用换行连接。
+ *
+ * 工具未注册时返回空(没有任何 memory 工具就不需要 memory section)。
+ */
+export declare function buildCoEngramMemoryPrompt(input: BuildPromptInput): readonly string[];
+/**
+ * 工厂:创建闭包绑定的 prompt builder
+ *
+ * 额外参数通过闭包注入:
+ *   - language:固定(adapter 注册时确定)
+ *   - signals:固定 snapshot(adapter 注册时读取,下次重启刷新)
+ *   - proposalCount:动态(每次调用时通过 provider 获取)
+ */
+export declare function createPromptBuilder(options: {
+    readonly language?: Language;
+    readonly signals?: PromptSignals;
+    readonly proposalCountProvider?: () => number;
+}): PromptBuilder;
+//# sourceMappingURL=builder.d.ts.map

package/dist/prompt-builder/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/prompt-builder/builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC;AAqG/D;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,gBAAgB,GACtB,SAAS,MAAM,EAAE,CAgBnB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,MAAM,CAAC;CAC/C,GAAG,aAAa,CAQhB"}

package/dist/prompt-builder/builder.js

@@ -0,0 +1,136 @@
+/**
+ * Co-Engram memory prompt builder(host-agnostic)
+ *
+ * 生成注入到 LLM 系统提示的 "## Memory Recall" section。
+ *
+ * 三层设计(可独立启用/禁用):
+ *
+ *   1. 基础引导(常驻)——何时调用 memory_search / 何时跳过 / 如何解读结果
+ *   2. Proposal 提醒(条件性)——count > 0 时注入
+ *   3. 自进化信号(条件性)——基于 prompt-signals.json:
+ *      - topTags(高频 engram 领域)
+ *      - lowConfidenceTopics(RPE false negative 检测)
+ *
+ * 所有文字走 i18n(en/zh)。
+ *
+ * 宿主集成:
+ *   - OpenClaw:`registerMemoryCapability.promptBuilder`
+ *   - Claude Code MCP:`serverInfo.instructions`(静态)+ hook(动态)
+ *
+ * @module @co-engram/core/prompt-builder
+ */
+import { DEFAULT_LANGUAGE, translatePrompt } from "../i18n/index.js";
+/**
+ * 构建基础 memory section(常驻部分)
+ *
+ * 包含:
+ *   - section header
+ *   - 何时调用 memory_search(语义检索场景)
+ *   - 何时调用 engram_list(列举场景,仅当 engram_list 可用时注入)
+ *   - 何时跳过(负向引导)
+ *   - 如何解读结果(truthScore + 低分处理)
+ *   - 创建/更新引导(条件性)
+ *   - 强化闭环引导(条件性,仅当 engram_reinforce 可用时注入)
+ */
+function buildBaseSection(language, availableTools) {
+    const lines = [
+        translatePrompt(language, "prompt.memory.section_header"),
+        translatePrompt(language, "prompt.memory.when_to_search"),
+    ];
+    // 仅当 engram_list 在可用工具集时才注入列举场景引导
+    // (避免对未注册 engram_list 的 host adapter 误导 agent)
+    if (availableTools.has("engram_list")) {
+        lines.push(translatePrompt(language, "prompt.memory.when_to_list"));
+    }
+    lines.push(translatePrompt(language, "prompt.memory.when_not_to_search"), translatePrompt(language, "prompt.memory.reading_results"));
+    // 写入引导:仅当 engram_create 或 engram_update 可用时注入
+    // 避免 agent 在 createdBy 填通用词(AIOS/openclaw/assistant)
+    if (availableTools.has("engram_create") ||
+        availableTools.has("engram_update")) {
+        lines.push(translatePrompt(language, "prompt.memory.writing"));
+    }
+    // 强化闭环引导:仅当 engram_reinforce 可用时注入
+    // 引导 agent 在用户明确确认后主动调 engram_reinforce(避免 importance 评分污染)
+    if (availableTools.has("engram_reinforce")) {
+        lines.push(translatePrompt(language, "prompt.memory.when_to_reinforce"));
+    }
+    return lines;
+}
+/**
+ * 构建 proposal 提醒(条件性)
+ *
+ * 仅当 count > 0 时返回非空数组。
+ */
+function buildProposalSection(count, language) {
+    if (count <= 0)
+        return [];
+    return [
+        translatePrompt(language, "prompt.memory.proposal_reminder", { count }),
+    ];
+}
+/**
+ * 构建自进化 signals 提示(条件性)
+ *
+ * 仅当 signals 存在且对应字段非空时注入。
+ */
+function buildSignalsSection(signals, language) {
+    if (!signals)
+        return [];
+    const lines = [];
+    if (signals.topTags.length > 0) {
+        lines.push(translatePrompt(language, "prompt.memory.frequent_topics", {
+            tags: signals.topTags.join(", "),
+        }));
+    }
+    if (signals.missedTopics && signals.missedTopics.length > 0) {
+        lines.push(translatePrompt(language, "prompt.memory.missed_topics", {
+            topics: signals.missedTopics.join(", "),
+        }));
+    }
+    if (signals.lowConfidenceTopics && signals.lowConfidenceTopics.length > 0) {
+        lines.push(translatePrompt(language, "prompt.memory.low_confidence_topics", {
+            topics: signals.lowConfidenceTopics.join(", "),
+        }));
+    }
+    return lines;
+}
+/**
+ * 主构建函数:组装所有部分
+ *
+ * 返回 string[](宿主期望的 prompt lines 格式)。
+ * 每个 element 是一段,宿主用换行连接。
+ *
+ * 工具未注册时返回空(没有任何 memory 工具就不需要 memory section)。
+ */
+export function buildCoEngramMemoryPrompt(input) {
+    const language = input.language ?? DEFAULT_LANGUAGE;
+    const hasSearch = input.availableTools.has("memory_search");
+    const hasGet = input.availableTools.has("memory_get");
+    const hasEngramSearch = input.availableTools.has("engram_search");
+    const hasEngramGet = input.availableTools.has("engram_get");
+    if (!hasSearch && !hasGet && !hasEngramSearch && !hasEngramGet)
+        return [];
+    const sections = [
+        buildBaseSection(language, input.availableTools),
+        buildSignalsSection(input.signals, language),
+        buildProposalSection(input.proposalCount ?? 0, language),
+    ];
+    return sections.flat();
+}
+/**
+ * 工厂:创建闭包绑定的 prompt builder
+ *
+ * 额外参数通过闭包注入:
+ *   - language:固定(adapter 注册时确定)
+ *   - signals:固定 snapshot(adapter 注册时读取,下次重启刷新)
+ *   - proposalCount:动态(每次调用时通过 provider 获取)
+ */
+export function createPromptBuilder(options) {
+    return (input) => buildCoEngramMemoryPrompt({
+        ...input,
+        language: options.language,
+        signals: options.signals,
+        proposalCount: options.proposalCountProvider?.() ?? 0,
+    });
+}
+//# sourceMappingURL=builder.js.map

package/dist/prompt-builder/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../src/prompt-builder/builder.ts"],"names":[],"mappings":"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"}

package/dist/prompt-builder/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Prompt builder barrel
+ *
+ * @module @co-engram/core/prompt-builder
+ */
+export * from "./types.js";
+export * from "./builder.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/prompt-builder/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/prompt-builder/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}

package/dist/prompt-builder/index.js

@@ -0,0 +1,8 @@
+/**
+ * Prompt builder barrel
+ *
+ * @module @co-engram/core/prompt-builder
+ */
+export * from "./types.js";
+export * from "./builder.js";
+//# sourceMappingURL=index.js.map

package/dist/prompt-builder/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/prompt-builder/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}

package/dist/prompt-builder/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Prompt builder 类型定义(host-agnostic)
+ *
+ * 与 OpenClaw / MCP 等具体宿主解耦 — 宿主 adapter 负责把各自的协议参数
+ * 适配为 BuildPromptInput,再调用 buildCoEngramMemoryPrompt。
+ *
+ * @module @co-engram/core/prompt-builder
+ */
+import type { Language } from "../i18n/index.js";
+import type { PromptSignalSnapshot } from "../prompt-signals/types.js";
+/**
+ * 自进化信号(从 PromptSignalSnapshot 派生)
+ *
+ * 完整 snapshot 由 maintenance light stage 生成,
+ * 缓存在 `<dataRoot>/.co-engram/prompt-signals.json`。
+ *
+ * promptBuilder 只读取 snapshot 的字符串字段,不关心 stats 元数据。
+ */
+export type PromptSignals = PromptSignalSnapshot;
+/**
+ * Prompt builder 的完整输入(base + 动态状态)
+ *
+ * Host-agnostic:不依赖 OpenClaw MemoryPromptBuilderParams 等宿主协议类型。
+ * 宿主 adapter 负责在自己的类型和此类型之间转换。
+ */
+export interface BuildPromptInput {
+    /** 当前会话可用的工具名集合(决定是否注入提示) */
+    readonly availableTools: ReadonlySet<string>;
+    /** 引用模式(目前实现忽略,预留扩展) */
+    readonly citationsMode?: "off" | "compact" | "full";
+    /** 自进化 signals;undefined 时跳过动态部分 */
+    readonly language?: Language;
+    /** 自进化 signals;undefined 时跳过动态部分 */
+    readonly signals?: PromptSignals;
+    /** 待处理 proposal 数量;0 时不注入 proposal 提醒 */
+    readonly proposalCount?: number;
+}
+/**
+ * Prompt builder 函数签名
+ */
+export type PromptBuilder = (input: BuildPromptInput) => readonly string[];
+//# sourceMappingURL=types.d.ts.map

package/dist/prompt-builder/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/prompt-builder/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAEvE;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,oBAAoB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7C,wBAAwB;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,KAAK,GAAG,SAAS,GAAG,MAAM,CAAC;IACpD,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,oCAAoC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,yCAAyC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,SAAS,MAAM,EAAE,CAAC"}

package/dist/prompt-builder/types.js

@@ -0,0 +1,10 @@
+/**
+ * Prompt builder 类型定义(host-agnostic)
+ *
+ * 与 OpenClaw / MCP 等具体宿主解耦 — 宿主 adapter 负责把各自的协议参数
+ * 适配为 BuildPromptInput,再调用 buildCoEngramMemoryPrompt。
+ *
+ * @module @co-engram/core/prompt-builder
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/prompt-builder/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/prompt-builder/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/prompt-signals/cache.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Prompt signals 缓存文件读写
+ *
+ * 路径:`<dataRoot>/.co-engram/prompt-signals.json`
+ *
+ * 与 team-memory/config.json 同目录,但语义不同:
+ *   - config.json:用户首次选择(语言/作者),很少变
+ *   - prompt-signals.json:light stage 周期性生成,频繁变
+ *
+ * 失败策略:
+ *   - read: 文件不存在或解析失败 → 返回 undefined(首次启动/损坏降级)
+ *   - write: 失败抛错(light stage 会捕获并记 log)
+ *
+ * @module @co-engram/core/prompt-signals
+ */
+import type { PromptSignalSnapshot } from "./types.js";
+/**
+ * 缓存文件名
+ */
+export declare const PROMPT_SIGNALS_FILENAME = "prompt-signals.json";
+/**
+ * 读取 prompt signals 缓存
+ *
+ * @param dataRoot team-memory 根目录
+ * @param fsRead 可选的自定义读取函数(测试注入)
+ */
+export declare function readPromptSignals(dataRoot: string, fsRead?: (path: string) => Promise<string>): Promise<PromptSignalSnapshot | undefined>;
+/**
+ * 写入 prompt signals 缓存
+ *
+ * @param dataRoot team-memory 根目录
+ * @param signals 完整 snapshot
+ * @param fsWrite 可选的自定义写入函数(测试注入)
+ */
+export declare function writePromptSignals(dataRoot: string, signals: PromptSignalSnapshot, fsWrite?: (path: string, content: string) => Promise<void>): Promise<void>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/prompt-signals/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/prompt-signals/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAE7D;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GACzC,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAY3C;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,oBAAoB,EAC7B,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACzD,OAAO,CAAC,IAAI,CAAC,CAQf"}