mcp-probe-kit 3.0.18 → 3.0.21

package/build/lib/agents-md-template.js

@@ -0,0 +1,57 @@
+import { relativeLink } from "./project-context-layout.js";
+function link(layout, targetRel) {
+    return relativeLink(layout.indexPath, targetRel);
+}
+function memorySection(locale) {
+    if (locale === "zh-CN") {
+        return `
+记忆（需 MEMORY_QDRANT_URL 等已配置）：
+- 检索：\`start_*\` 命中后**自动注入**历史经验全文；中途补查可用 \`search_memory\`；单条精读仍可用 \`read_memory_asset\`
+- 沉淀：跨仓库共享**勿填** source_project/source_path；路径写进 content；summary 写检索关键词
+- Bug 修完验证通过 → **必须** \`memorize_asset\` type=\`bugfix\` tags=\`bugfix,root-cause\`（content 含【现象】【根因】【修复】【验证】）
+- 功能/UI 可复用产出 → \`memorize_asset\` type=\`pattern\`/\`component\``;
+    }
+    return `
+Memory (requires MEMORY_* env):
+- Search: \`start_*\` auto-injects full memory hits; use \`search_memory\` mid-task; \`read_memory_asset\` for a specific id
+- Store: do NOT use source_project/source_path for cross-repo pools; put paths in content; write keyword-rich summary
+- After verified bugfix → MUST \`memorize_asset\` type=\`bugfix\` (sections: symptom, root cause, fix, verification)
+- Reusable feature/UI → \`memorize_asset\` type=\`pattern\`/\`component\``;
+}
+/**
+ * Ultra-compact AGENTS.md body (inside mcp-probe block).
+ */
+export function generateAgentsMdInner(input) {
+    const { layout, locale } = input;
+    const graph = link(layout, layout.latestMarkdownPath);
+    const ctxIndex = link(layout, layout.legacyIndexPath);
+    if (locale === "zh-CN") {
+        return `## MCP（必须先调）
+需已配置 mcp-probe-kit。\`start_*\` 若返回 delegated plan，逐步执行完再结束。
+
+- 新功能 → \`start_feature\`（会先搜记忆）
+- Bug → \`start_bugfix\`（会先搜记忆）
+- UI → \`start_ui\`（会先搜记忆）
+- 不熟代码 / 影响面 → \`code_insight\`（context / impact / auto）
+- 缺上下文 → \`init_project_context\`
+- 提交 → \`gencommit\`
+
+上下文：写代码前先读 [project-context](${ctxIndex})（链到 \`${layout.modularDir}/\` 各文档）
+图谱：大改前读 [latest](${graph})；过期 \`code_insight\` mode=auto save_to_docs=true${memorySection(locale)}`;
+    }
+    return `## MCP (call first)
+Requires mcp-probe-kit. Complete every \`start_*\` delegated plan step before done.
+
+- Feature → \`start_feature\` (searches memory first)
+- Bug → \`start_bugfix\` (searches memory first)
+- UI → \`start_ui\` (searches memory first)
+- Unfamiliar code / impact → \`code_insight\` (context / impact / auto)
+- Missing context → \`init_project_context\`
+- Commit → \`gencommit\`
+
+Context: before coding read [project-context](${ctxIndex}) (links to \`${layout.modularDir}/\`)
+Graph: read [latest](${graph}) before large changes; refresh \`code_insight\` mode=auto save_to_docs=true${memorySection(locale)}`;
+}
+export function generateAgentsMdTemplate(input) {
+    return generateAgentsMdInner(input);
+}

package/build/lib/memory-client.d.ts

@@ -24,8 +24,15 @@ export interface MemorySearchResult {
     description: string;
     summary: string;
     tags: string[];
+    sourceProject?: string;
     sourcePath?: string;
 }
+export interface MemorySearchOptions {
+    limit?: number;
+    minScore?: number;
+    preferTypes?: string[];
+    preferTags?: string[];
+}
 export declare function normalizeContentForHash(content: string): string;
 export declare function sha256Hex(value: string): string;
 export declare function buildMemoryContentHashes(content: string): {
@@ -55,7 +62,7 @@ export declare class MemoryClient {
         sourcePath?: string;
         usage?: string;
     }): Promise<MemoryAsset>;
-    search(query: string, limit?: number): Promise<MemorySearchResult[]>;
+    search(query: string, options?: MemorySearchOptions): Promise<MemorySearchResult[]>;
     getAsset(assetId: string): Promise<MemoryAsset | null>;
 }
 export declare function createMemoryClient(): MemoryClient;

package/build/lib/memory-client.js

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { getMemoryConfig, isMemoryEnabled, isMemoryReadEnabled } from './memory-config.js';
+import { normalizeMemoryPayload, payloadToMemoryFields } from './memory-payload.js';
 function truncate(value, maxChars) {
     if (value.length <= maxChars) {
         return value;
@@ -155,26 +156,14 @@ export class MemoryClient {
                 },
             }),
         });
-        const payload = data.result?.points?.[0]?.payload;
-        if (!payload) {
+        const rawPayload = data.result?.points?.[0]?.payload;
+        if (!rawPayload) {
             return null;
         }
+        const fields = payloadToMemoryFields(rawPayload);
         return {
-            id: String(payload.id || ''),
-            name: String(payload.name || ''),
-            type: String(payload.type || ''),
-            description: String(payload.description || ''),
-            summary: String(payload.summary || ''),
-            content: String(payload.content || ''),
-            tags: ensureArray(payload.tags),
-            confidence: numberOr(payload.confidence, 0.5),
-            sourceProject: typeof payload.sourceProject === 'string' ? payload.sourceProject : undefined,
-            sourcePath: typeof payload.sourcePath === 'string' ? payload.sourcePath : undefined,
-            usage: typeof payload.usage === 'string' ? payload.usage : undefined,
-            contentHash: typeof payload.contentHash === 'string' ? payload.contentHash : undefined,
-            normalizedContentHash: typeof payload.normalizedContentHash === 'string' ? payload.normalizedContentHash : undefined,
-            createdAt: String(payload.createdAt || ''),
-            updatedAt: String(payload.updatedAt || ''),
+            ...fields,
+            id: fields.id || String(rawPayload.id || ''),
         };
     }
     async upsertAsset(input) {
@@ -229,33 +218,41 @@ export class MemoryClient {
         });
         return asset;
     }
-    async search(query, limit = this.config.searchLimit) {
+    async search(query, options = {}) {
         if (!this.isEnabled()) {
             return [];
         }
+        const limit = options.limit ?? this.config.searchLimit;
+        const minScore = options.minScore ?? this.config.searchMinScore;
+        const fetchLimit = Math.min(Math.max(limit * 4, limit), 50);
         const vector = await this.embed(query);
         const data = await this.requestJson(`${this.config.qdrantUrl}/collections/${encodeURIComponent(this.config.qdrantCollection)}/points/search`, {
             method: 'POST',
             headers: this.buildHeaders(),
             body: JSON.stringify({
                 vector,
-                limit,
+                limit: fetchLimit,
                 with_payload: true,
             }),
         });
-        return (data.result || []).map((point) => {
-            const payload = point.payload || {};
+        const mapped = (data.result || []).map((point) => {
+            const payload = normalizeMemoryPayload(point.payload || {});
+            const fields = payloadToMemoryFields(payload);
             return {
                 id: String(point.id),
                 score: numberOr(point.score, 0),
-                name: String(payload.name || ''),
-                type: String(payload.type || ''),
-                description: String(payload.description || ''),
-                summary: truncate(String(payload.summary || ''), this.config.summaryMaxChars),
-                tags: ensureArray(payload.tags),
-                sourcePath: typeof payload.sourcePath === 'string' ? payload.sourcePath : undefined,
+                name: fields.name,
+                type: fields.type,
+                description: fields.description,
+                summary: truncate(fields.summary, this.config.summaryMaxChars),
+                tags: fields.tags,
+                sourceProject: fields.sourceProject,
+                sourcePath: fields.sourcePath,
             };
         });
+        const ranked = rankSearchResults(mapped, options.preferTypes, options.preferTags);
+        const filtered = minScore > 0 ? ranked.filter((item) => item.score >= minScore) : ranked;
+        return filtered.slice(0, limit);
     }
     async getAsset(assetId) {
         if (!this.isReadEnabled()) {
@@ -265,29 +262,41 @@ export class MemoryClient {
             method: 'GET',
             headers: this.buildHeaders(false),
         });
-        const payload = data.result?.payload;
-        if (!payload) {
+        const rawPayload = data.result?.payload;
+        if (!rawPayload) {
             return null;
         }
+        const fields = payloadToMemoryFields(rawPayload);
         return {
-            id: String(payload.id || assetId),
-            name: String(payload.name || ''),
-            type: String(payload.type || ''),
-            description: String(payload.description || ''),
-            summary: String(payload.summary || ''),
-            content: String(payload.content || ''),
-            tags: ensureArray(payload.tags),
-            confidence: numberOr(payload.confidence, 0.5),
-            sourceProject: typeof payload.sourceProject === 'string' ? payload.sourceProject : undefined,
-            sourcePath: typeof payload.sourcePath === 'string' ? payload.sourcePath : undefined,
-            usage: typeof payload.usage === 'string' ? payload.usage : undefined,
-            contentHash: typeof payload.contentHash === 'string' ? payload.contentHash : undefined,
-            normalizedContentHash: typeof payload.normalizedContentHash === 'string' ? payload.normalizedContentHash : undefined,
-            createdAt: String(payload.createdAt || ''),
-            updatedAt: String(payload.updatedAt || ''),
+            ...fields,
+            id: fields.id || assetId,
         };
     }
 }
+function rankSearchResults(results, preferTypes = [], preferTags = []) {
+    if (preferTypes.length === 0 && preferTags.length === 0) {
+        return [...results].sort((a, b) => b.score - a.score);
+    }
+    const preferredTypes = new Set(preferTypes.map((item) => item.toLowerCase()));
+    const preferredTags = new Set(preferTags.map((item) => item.toLowerCase()));
+    const scoreBoost = (item) => {
+        let boost = 0;
+        if (preferredTypes.has(item.type.toLowerCase())) {
+            boost += 2;
+        }
+        if (item.tags.some((tag) => preferredTags.has(tag.toLowerCase()))) {
+            boost += 1;
+        }
+        return boost;
+    };
+    return [...results].sort((a, b) => {
+        const boostDiff = scoreBoost(b) - scoreBoost(a);
+        if (boostDiff !== 0) {
+            return boostDiff;
+        }
+        return b.score - a.score;
+    });
+}
 export function createMemoryClient() {
     return new MemoryClient();
 }

package/build/lib/memory-config.d.ts

@@ -8,6 +8,14 @@ export interface MemoryConfig {
     embeddingProvider: 'ollama' | 'openai-compatible';
     searchLimit: number;
     summaryMaxChars: number;
+    /** Show sourcePath in search injection (default false for cross-repo pools) */
+    searchShowSource: boolean;
+    /** Minimum cosine score to include in search results; 0 = disabled */
+    searchMinScore: number;
+    /** When set, show sourcePath only if payload.sourceProject matches */
+    repoId: string;
+    /** Max chars of each asset content injected into start_* guides */
+    injectionContentMaxChars: number;
 }
 export declare function getMemoryConfig(): MemoryConfig;
 export declare function isMemoryEnabled(config?: MemoryConfig): boolean;

package/build/lib/memory-config.js

@@ -9,6 +9,21 @@ function getNumberEnv(name, fallback) {
     const parsed = Number(raw);
     return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
+function getOptionalNumberEnv(name, fallback) {
+    const raw = process.env[name]?.trim();
+    if (!raw) {
+        return fallback;
+    }
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+function getBooleanEnv(name, fallback) {
+    const raw = process.env[name]?.trim().toLowerCase();
+    if (!raw) {
+        return fallback;
+    }
+    return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
+}
 export function getMemoryConfig() {
     const provider = (process.env.MEMORY_EMBEDDING_PROVIDER || 'ollama').trim().toLowerCase();
     return {
@@ -21,6 +36,10 @@ export function getMemoryConfig() {
         embeddingProvider: provider === 'openai-compatible' ? 'openai-compatible' : 'ollama',
         searchLimit: getNumberEnv('MEMORY_SEARCH_LIMIT', 3),
         summaryMaxChars: getNumberEnv('MEMORY_SUMMARY_MAX_CHARS', 280),
+        searchShowSource: getBooleanEnv('MEMORY_SEARCH_SHOW_SOURCE', false),
+        searchMinScore: getOptionalNumberEnv('MEMORY_SEARCH_MIN_SCORE', 0),
+        repoId: (process.env.MEMORY_REPO_ID || '').trim(),
+        injectionContentMaxChars: getNumberEnv('MEMORY_INJECTION_CONTENT_MAX_CHARS', 1500),
     };
 }
 export function isMemoryEnabled(config = getMemoryConfig()) {

package/build/lib/memory-orchestration.d.ts

@@ -1,15 +1,21 @@
-import type { MemorySearchResult } from './memory-client.js';
+import type { MemoryAsset, MemorySearchResult } from './memory-client.js';
+import { type MemoryConfig } from './memory-config.js';
+export type MemoryPlanKind = 'feature' | 'bugfix' | 'ui' | 'default';
 export interface MemoryInjectionContext {
     enabled: boolean;
     available: boolean;
     degraded: boolean;
     query: string;
     results: MemorySearchResult[];
+    /** Full assets keyed by search hit id (auto-loaded for start_* injection) */
+    assetsById: Record<string, MemoryAsset>;
     error?: string;
 }
-export declare function loadMemoryInjectionContext(query: string): Promise<MemoryInjectionContext>;
+export declare function truncateInjectionText(value: string, maxChars: number): string;
+export declare function loadMemoryInjectionContext(query: string, kind?: MemoryPlanKind): Promise<MemoryInjectionContext>;
+export declare function shouldShowSourceInSearch(item: MemorySearchResult, config?: MemoryConfig): boolean;
 export declare function renderMemoryGuideSection(context: MemoryInjectionContext): string;
-export declare function buildMemoryPlanStep(): {
+export declare function buildMemoryPlanStep(kind?: MemoryPlanKind): {
     id: string;
     tool: string;
     when: string;
@@ -20,6 +26,7 @@ export declare function buildMemoryPlanStep(): {
         summary: string;
         content: string;
         usage: string;
+        tags: string[];
         confidence: number;
     };
     outputs: never[];

package/build/lib/memory-orchestration.js

@@ -1,5 +1,35 @@
 import { createMemoryClient } from './memory-client.js';
-export async function loadMemoryInjectionContext(query) {
+import { getMemoryConfig } from './memory-config.js';
+function kindSearchPreferences(kind) {
+    switch (kind) {
+        case 'bugfix':
+            return { preferTypes: ['bugfix'], preferTags: ['bugfix', 'root-cause'] };
+        case 'ui':
+            return { preferTypes: ['component', 'pattern'], preferTags: ['ui', 'pattern'] };
+        case 'feature':
+            return { preferTypes: ['pattern', 'code'], preferTags: ['feature', 'pattern'] };
+        default:
+            return { preferTypes: [], preferTags: [] };
+    }
+}
+export function truncateInjectionText(value, maxChars) {
+    if (value.length <= maxChars) {
+        return value;
+    }
+    return `${value.slice(0, Math.max(0, maxChars - 3))}...`;
+}
+async function loadFullAssets(results) {
+    const client = createMemoryClient();
+    if (!client.isReadEnabled() || results.length === 0) {
+        return {};
+    }
+    const entries = await Promise.all(results.map(async (item) => {
+        const asset = await client.getAsset(item.id);
+        return asset ? [item.id, asset] : null;
+    }));
+    return Object.fromEntries(entries.filter((entry) => entry !== null));
+}
+export async function loadMemoryInjectionContext(query, kind = 'default') {
     const client = createMemoryClient();
     if (!client.isEnabled()) {
         return {
@@ -8,16 +38,23 @@ export async function loadMemoryInjectionContext(query) {
             degraded: false,
             query,
             results: [],
+            assetsById: {},
         };
     }
     try {
-        const results = await client.search(query);
+        const prefs = kindSearchPreferences(kind);
+        const results = await client.search(query, {
+            preferTypes: prefs.preferTypes,
+            preferTags: prefs.preferTags,
+        });
+        const assetsById = await loadFullAssets(results);
         return {
             enabled: true,
             available: true,
             degraded: false,
             query,
             results,
+            assetsById,
         };
     }
     catch (error) {
@@ -27,11 +64,57 @@ export async function loadMemoryInjectionContext(query) {
             degraded: true,
             query,
             results: [],
+            assetsById: {},
             error: error instanceof Error ? error.message : String(error),
         };
     }
 }
+function formatMemoryResultLabel(item) {
+    const kind = item.type === 'bugfix' || item.tags.includes('bugfix')
+        ? '历史 Bug 修复'
+        : item.type === 'pattern' || item.type === 'component'
+            ? '可复用模式'
+            : '历史资产';
+    return `${item.name} [${item.type}] (${kind})`;
+}
+export function shouldShowSourceInSearch(item, config = getMemoryConfig()) {
+    if (config.searchShowSource) {
+        return Boolean(item.sourcePath);
+    }
+    if (!config.repoId || !item.sourceProject || !item.sourcePath) {
+        return false;
+    }
+    return item.sourceProject === config.repoId;
+}
+function formatSourceHint(item, config) {
+    if (!shouldShowSourceInSearch(item, config)) {
+        return '';
+    }
+    return `\n   - 来源: ${item.sourcePath}`;
+}
+function formatAssetBody(asset, config) {
+    const lines = [
+        `### ${asset.name}`,
+        `- asset_id: ${asset.id}`,
+        asset.description ? `- 描述: ${asset.description}` : '',
+        asset.usage ? `- 适用: ${asset.usage}` : '',
+        asset.tags.length > 0 ? `- 标签: ${asset.tags.join(', ')}` : '',
+        '',
+        truncateInjectionText(asset.content, config.injectionContentMaxChars),
+    ].filter(Boolean);
+    return lines.join('\n');
+}
+function formatResultBlock(item, index, context, config) {
+    const label = formatMemoryResultLabel(item);
+    const asset = context.assetsById[item.id];
+    const header = `${index + 1}. ${label} score=${item.score.toFixed(3)}\n   - 摘要: ${item.summary}${formatSourceHint(item, config)}`;
+    if (asset?.content) {
+        return `${header}\n\n${formatAssetBody(asset, config)}\n`;
+    }
+    return `${header}\n   - 全文加载失败，可手动: read_memory_asset {"asset_id": "${item.id}"}\n`;
+}
 export function renderMemoryGuideSection(context) {
+    const config = getMemoryConfig();
     if (!context.enabled) {
         return '';
     }
@@ -39,25 +122,81 @@ export function renderMemoryGuideSection(context) {
         return `\n\n## 🧠 记忆系统\n- 状态: 已配置但本次检索降级\n- 原因: ${context.error || '未知错误'}\n- 处理: 忽略记忆注入，继续主流程\n`;
     }
     if (context.results.length === 0) {
-        return `\n\n## 🧠 记忆系统\n- 状态: 已启用\n- 检索结果: 未找到高相关历史资产\n- 处理: 继续主流程；若本次产出存在高价值通用资产，结束后调用 \`memorize_asset\` 沉淀\n`;
+        return `\n\n## 🧠 记忆系统\n- 状态: 已启用\n- 检索结果: 未找到高相关记录（含历史 Bug 修复与可复用模式）\n- 处理: 继续主流程；Bug 修复验证通过后必须 \`memorize_asset\` 沉淀；功能/UI 有可复用产出再沉淀\n`;
     }
+    const loadedCount = context.results.filter((item) => context.assetsById[item.id]?.content).length;
     const items = context.results
-        .map((item, index) => `${index + 1}. ${item.name} [${item.type}] score=${item.score.toFixed(3)}\n   - 摘要: ${item.summary}\n   - 读取: read_memory_asset {\"asset_id\": \"${item.id}\"}${item.sourcePath ? `\n   - 来源: ${item.sourcePath}` : ''}`)
+        .map((item, index) => formatResultBlock(item, index, context, config))
         .join('\n');
-    return `\n\n## 🧠 记忆系统\n- 状态: 已启用\n- 指令: 优先复用以下历史成功经验；如果某条相关，再用 \`read_memory_asset\` 拉取完整内容，不要直接重写\n- 检索结果:\n${items}\n`;
+    return `\n\n## 🧠 记忆系统\n- 状态: 已启用\n- 指令: 下列为已自动加载的历史经验全文（${loadedCount}/${context.results.length} 条）；开干前直接复用，无需再调 \`read_memory_asset\`\n- 检索结果:\n${items}`;
 }
-export function buildMemoryPlanStep() {
+export function buildMemoryPlanStep(kind = 'default') {
+    if (kind === 'bugfix') {
+        return {
+            id: 'memorize-bugfix',
+            tool: 'memorize_asset',
+            when: 'Bug 已修复且验证通过后（必须沉淀，便于下次同类问题检索）',
+            args: {
+                name: '[问题简述，如 登录超时-Redis连接池]',
+                type: 'bugfix',
+                description: '[现象、报错信息、复现条件]',
+                summary: '[检索用：关键词 + 根因 + 修复要点，一句话]',
+                content: '【现象】...\n【根因】...\n【修复】具体改动与关键代码/配置\n【验证】如何确认已修好',
+                usage: '[再次遇到何种症状时可参考]',
+                tags: ['bugfix', 'root-cause'],
+                confidence: 0.85,
+            },
+            outputs: [],
+        };
+    }
+    if (kind === 'ui') {
+        return {
+            id: 'memorize-ui',
+            tool: 'memorize_asset',
+            when: 'UI 实现完成且存在可复用组件/布局/交互模式',
+            args: {
+                name: '[UI 资产名称]',
+                type: 'component',
+                description: '[该 UI 模式解决什么问题]',
+                summary: '[检索用摘要]',
+                content: '[组件结构、样式约定或可复用片段]',
+                usage: '[适用页面/场景]',
+                tags: ['ui', 'pattern'],
+                confidence: 0.75,
+            },
+            outputs: [],
+        };
+    }
+    if (kind === 'feature') {
+        return {
+            id: 'memorize-feature',
+            tool: 'memorize_asset',
+            when: '功能完成且存在可复用实现/规范',
+            args: {
+                name: '[功能/模式名称]',
+                type: 'pattern',
+                description: '[该资产解决什么问题]',
+                summary: '[检索用摘要]',
+                content: '[可复用代码或流程]',
+                usage: '[适用场景与限制]',
+                tags: ['feature', 'pattern'],
+                confidence: 0.75,
+            },
+            outputs: [],
+        };
+    }
     return {
         id: 'memorize',
         tool: 'memorize_asset',
         when: '本次实现完成且确认存在可复用资产',
         args: {
             name: '[资产名称]',
-            type: 'code',
+            type: 'pattern',
             description: '[该资产解决了什么问题]',
             summary: '[用于后续检索的简洁摘要]',
             content: '[可复用代码或规范内容]',
             usage: '[适用场景与限制]',
+            tags: ['pattern'],
             confidence: 0.7,
         },
         outputs: [],

package/build/lib/memory-payload.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Unify legacy Qdrant payloads (kind/title/source) with the current asset schema.
+ */
+export declare function normalizeMemoryPayload(payload: Record<string, unknown>): Record<string, unknown>;
+export declare function payloadToMemoryFields(payload: Record<string, unknown>): {
+    id: string;
+    name: string;
+    type: string;
+    description: string;
+    summary: string;
+    content: string;
+    tags: string[];
+    confidence: number;
+    sourceProject?: string;
+    sourcePath?: string;
+    usage?: string;
+    contentHash?: string;
+    normalizedContentHash?: string;
+    createdAt: string;
+    updatedAt: string;
+};

package/build/lib/memory-payload.js

@@ -0,0 +1,65 @@
+function truncate(value, maxChars) {
+    if (value.length <= maxChars) {
+        return value;
+    }
+    return `${value.slice(0, Math.max(0, maxChars - 3))}...`;
+}
+/**
+ * Unify legacy Qdrant payloads (kind/title/source) with the current asset schema.
+ */
+export function normalizeMemoryPayload(payload) {
+    const normalized = { ...payload };
+    if (!normalized.name && typeof normalized.title === 'string') {
+        normalized.name = normalized.title;
+    }
+    if (!normalized.type && typeof normalized.kind === 'string') {
+        const kind = normalized.kind;
+        normalized.type = kind === 'extracted_pattern' ? 'pattern' : kind;
+    }
+    if (!normalized.description) {
+        if (typeof normalized.title === 'string') {
+            normalized.description = normalized.title;
+        }
+        else if (typeof normalized.source === 'string') {
+            normalized.description = `Legacy memory from ${normalized.source}`;
+        }
+    }
+    if (!normalized.summary && typeof normalized.content === 'string') {
+        normalized.summary = truncate(normalized.content, 280);
+    }
+    if (!normalized.createdAt && typeof normalized.created_at === 'string') {
+        normalized.createdAt = normalized.created_at;
+    }
+    if (!normalized.updatedAt) {
+        if (typeof normalized.updated_at === 'string') {
+            normalized.updatedAt = normalized.updated_at;
+        }
+        else if (typeof normalized.createdAt === 'string') {
+            normalized.updatedAt = normalized.createdAt;
+        }
+    }
+    return normalized;
+}
+export function payloadToMemoryFields(payload) {
+    const p = normalizeMemoryPayload(payload);
+    const tags = Array.isArray(p.tags)
+        ? p.tags.filter((item) => typeof item === 'string' && item.trim().length > 0)
+        : [];
+    return {
+        id: String(p.id || ''),
+        name: String(p.name || ''),
+        type: String(p.type || ''),
+        description: String(p.description || ''),
+        summary: String(p.summary || ''),
+        content: String(p.content || ''),
+        tags,
+        confidence: typeof p.confidence === 'number' && Number.isFinite(p.confidence) ? p.confidence : 0.5,
+        sourceProject: typeof p.sourceProject === 'string' ? p.sourceProject : undefined,
+        sourcePath: typeof p.sourcePath === 'string' ? p.sourcePath : undefined,
+        usage: typeof p.usage === 'string' ? p.usage : undefined,
+        contentHash: typeof p.contentHash === 'string' ? p.contentHash : undefined,
+        normalizedContentHash: typeof p.normalizedContentHash === 'string' ? p.normalizedContentHash : undefined,
+        createdAt: String(p.createdAt || ''),
+        updatedAt: String(p.updatedAt || ''),
+    };
+}

package/build/lib/merge-agents-md.d.ts

@@ -0,0 +1,6 @@
+export type AgentsMdMergeMode = "created" | "prepended" | "replaced-and-moved-to-top" | "skipped-empty";
+export declare function wrapMcpProbeBlock(innerMarkdown: string): string;
+export declare function mergeAgentsMdBlock(existingContent: string | null | undefined, generatedInner: string): {
+    content: string;
+    mergeMode: AgentsMdMergeMode;
+};

package/build/lib/merge-agents-md.js

@@ -0,0 +1,51 @@
+const BLOCK_BEGIN = "<!-- mcp-probe:context begin — auto-generated; re-run init_project_context updates this block only -->";
+const BLOCK_END = "<!-- mcp-probe:context end -->";
+export function wrapMcpProbeBlock(innerMarkdown) {
+    return `${BLOCK_BEGIN}\n${innerMarkdown.trim()}\n${BLOCK_END}`;
+}
+function stripExistingBlock(content) {
+    const beginIdx = content.indexOf(BLOCK_BEGIN);
+    if (beginIdx === -1) {
+        const legacyBegin = content.indexOf("<!-- mcp-probe:context begin");
+        if (legacyBegin === -1) {
+            return content.trim();
+        }
+        const legacyEnd = content.indexOf(BLOCK_END);
+        if (legacyEnd === -1) {
+            return content.trim();
+        }
+        const legacyLineEnd = content.indexOf("-->", legacyBegin);
+        const blockStart = legacyLineEnd === -1 ? legacyBegin : legacyLineEnd + 3;
+        const before = content.slice(0, legacyBegin).trimEnd();
+        const after = content.slice(legacyEnd + BLOCK_END.length).trimStart();
+        return [before, after].filter(Boolean).join("\n\n").trim();
+    }
+    const endIdx = content.indexOf(BLOCK_END);
+    if (endIdx === -1) {
+        return content.trim();
+    }
+    const before = content.slice(0, beginIdx).trimEnd();
+    const after = content.slice(endIdx + BLOCK_END.length).trimStart();
+    return [before, after].filter(Boolean).join("\n\n").trim();
+}
+export function mergeAgentsMdBlock(existingContent, generatedInner) {
+    const block = wrapMcpProbeBlock(generatedInner);
+    if (!existingContent?.trim()) {
+        return { content: `${block}\n`, mergeMode: "created" };
+    }
+    const userBody = stripExistingBlock(existingContent);
+    const hadBlock = existingContent.includes(BLOCK_BEGIN) || existingContent.includes("<!-- mcp-probe:context begin");
+    if (!userBody) {
+        return { content: `${block}\n`, mergeMode: hadBlock ? "replaced-and-moved-to-top" : "created" };
+    }
+    if (!hadBlock) {
+        return {
+            content: `${block}\n\n${userBody}\n`,
+            mergeMode: "prepended",
+        };
+    }
+    return {
+        content: `${block}\n\n${userBody}\n`,
+        mergeMode: "replaced-and-moved-to-top",
+    };
+}