mcp-probe-kit 3.0.18 → 3.0.21

package/README.md

@@ -15,7 +15,7 @@
 
 > **Talk is cheap, show me the Context.**
 > 
-> mcp-probe-kit is a protocol-level toolkit designed for developers who want AI to truly understand their project's intent. It's not just a collection of 28 tools—it's a context-aware system that helps AI agents grasp what you're building.
+> mcp-probe-kit is a protocol-level toolkit designed for developers who want AI to truly understand their project's intent. It's not just a collection of 29 tools—it's a context-aware system that helps AI agents grasp what you're building.
 
 **Languages**: [English](README.md) | [简体中文](i18n/README.zh-CN.md) | [日本語](i18n/README.ja-JP.md) | [한국어](i18n/README.ko-KR.md) | [Español](i18n/README.es-ES.md) | [Français](i18n/README.fr-FR.md) | [Deutsch](i18n/README.de-DE.md) | [Português (BR)](i18n/README.pt-BR.md)
 
@@ -26,7 +26,7 @@
 
 > 🚀 AI-Powered Complete Development Toolkit - Covering the Entire Development Lifecycle
 
-A powerful MCP (Model Context Protocol) server providing **28 tools** covering the complete workflow from product analysis to final release (Requirements → Design → Development → Quality → Release), all tools support **structured output**.
+A powerful MCP (Model Context Protocol) server providing **29 tools** covering the complete workflow from product analysis to final release (Requirements → Design → Development → Quality → Release), all tools support **structured output**.
 
 **🎉 v3.0 Major Update**: Streamlined tool count, focus on core competencies, eliminate choice paralysis, let AI do more native work
 
@@ -41,7 +41,8 @@ A powerful MCP (Model Context Protocol) server providing **28 tools** covering t
 **👉 [https://mcp-probe-kit.bytezonex.com](https://mcp-probe-kit.bytezonex.com/)**
 
 - [Quick Start](https://mcp-probe-kit.bytezonex.com/pages/getting-started.html) - Setup in 5 minutes
-- [All Tools](https://mcp-probe-kit.bytezonex.com/pages/all-tools.html) - Complete list of 28 tools
+- [Local Memory Stack (Qdrant + Nomic Embed)](docs/memory-local-setup.md) - Docker Compose, ports `50008` / `50012`, MCP env
+- [All Tools](https://mcp-probe-kit.bytezonex.com/pages/all-tools.html) - Complete list of 29 tools
 - [Best Practices](https://mcp-probe-kit.bytezonex.com/pages/examples.html) - Full development workflow guide
 - [v3.0 Migration Guide](https://mcp-probe-kit.bytezonex.com/pages/migration.html) - Upgrade from v2.x to v3.0
 
@@ -63,8 +64,8 @@ A powerful MCP (Model Context Protocol) server providing **28 tools** covering t
   - `init_project`, `init_project_context`, `add_feature`, `estimate`, `interview`, `ask_user`
 - **🎨 UI/UX Utilities** (3 tools) - Design systems and UI data synchronization
   - `ui_design_system`, `ui_search`, `sync_ui_data`
-- **🧠 Memory & Cursor History** (6 tools) - Reusable asset memory and local Cursor conversation retrieval
-  - `read_memory_asset`, `memorize_asset`, `scan_and_extract_patterns`, `cursor_list_conversations`, `cursor_search_conversations`, `cursor_read_conversation`
+- **🧠 Memory & Cursor History** (7 tools) - Reusable asset memory and local Cursor conversation retrieval
+  - `search_memory`, `read_memory_asset`, `memorize_asset`, `scan_and_extract_patterns`, `cursor_list_conversations`, `cursor_search_conversations`, `cursor_read_conversation`
 
 ### 🧠 Code Graph Bridge (GitNexus)
 
@@ -99,16 +100,19 @@ A powerful MCP (Model Context Protocol) server providing **28 tools** covering t
   - Linux: `~/.config/Cursor/User/globalStorage/state.vscdb`
 
 **Memory tools:**
+- `search_memory` - Semantic search across the shared memory pool (optionally prefer `type` / `tags`)
 - `memorize_asset` - Persist reusable code/spec/pattern assets into vector memory
 - `read_memory_asset` - Read full asset content by `asset_id`
 - `scan_and_extract_patterns` - Extract reusable patterns from code/file/directory before deciding whether to persist
 
+**Cross-repo memory pools:** do not rely on `source_project` / `source_path` for shared retrieval; put file paths in `content` instead. Search injection hides foreign `sourcePath` unless `MEMORY_REPO_ID` matches or `MEMORY_SEARCH_SHOW_SOURCE=true`.
+
 **Memory backend and embedding configuration:**
 - Vector database: **Qdrant**
-- Recommended local setup: `Qdrant + Ollama`
+- **Recommended local setup:** `Qdrant (port 50008) + Infinity / nomic-embed (port 50012)` — lighter than Ollama; see **[Local Memory Stack guide](docs/memory-local-setup.md)** (中文: [memory-local-setup.zh-CN.md](docs/memory-local-setup.zh-CN.md))
 - Supported embedding providers:
   - `ollama`
-  - `openai-compatible`
+  - `openai-compatible` (Infinity, OpenAI, etc.)
 - Required environment variables for memory write/search:
   - `MEMORY_QDRANT_URL`
   - `MEMORY_EMBEDDING_URL`
@@ -120,16 +124,18 @@ A powerful MCP (Model Context Protocol) server providing **28 tools** covering t
   - `MEMORY_EMBEDDING_PROVIDER` (`ollama` by default)
   - `MEMORY_SEARCH_LIMIT` (default: `3`)
   - `MEMORY_SUMMARY_MAX_CHARS` (default: `280`)
+  - `MEMORY_SEARCH_MIN_SCORE` (default: `0` = disabled; try `0.72` for noisy pools)
+  - `MEMORY_SEARCH_SHOW_SOURCE` (default: `false`)
+  - `MEMORY_REPO_ID` (optional; show `sourcePath` only when `sourceProject` matches)
+  - `MEMORY_INJECTION_CONTENT_MAX_CHARS` (default: `1500`; max content per hit injected into `start_*` guides)
 - Behavior notes:
   - Read-only memory access only requires `MEMORY_QDRANT_URL`
   - Memory write is enabled only when `MEMORY_QDRANT_URL`, `MEMORY_EMBEDDING_URL`, and `MEMORY_EMBEDDING_MODEL` are all configured
   - The Qdrant collection is auto-created on first write, and vector dimension is inferred from the first embedding response
 
-**Recommended local memory setup (Qdrant + Ollama):**
-```bash
-docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
-ollama pull nomic-embed-text
-```
+**Recommended local memory setup (Qdrant + Nomic Embed / Infinity):**
+
+Full Docker Compose, ports, and troubleshooting: **[docs/memory-local-setup.md](docs/memory-local-setup.md)**
 
 ```json
 {
@@ -138,11 +144,13 @@ ollama pull nomic-embed-text
       "command": "npx",
       "args": ["-y", "mcp-probe-kit@latest"],
       "env": {
-        "MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
+        "MEMORY_QDRANT_URL": "http://127.0.0.1:50008",
+        "MEMORY_QDRANT_API_KEY": "your-qdrant-api-key",
         "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
-        "MEMORY_EMBEDDING_PROVIDER": "ollama",
-        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
-        "MEMORY_EMBEDDING_MODEL": "nomic-embed-text",
+        "MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
+        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:50012/embeddings",
+        "MEMORY_EMBEDDING_MODEL": "nomic-ai/nomic-embed-text-v1.5",
+        "MEMORY_EMBEDDING_API_KEY": "your-infinity-api-key",
         "MEMORY_SEARCH_LIMIT": "3",
         "MEMORY_SUMMARY_MAX_CHARS": "280"
       }
@@ -151,7 +159,21 @@ ollama pull nomic-embed-text
 }
 ```
 
-**OpenAI-compatible embedding setup:**
+**Alternative: Qdrant + Ollama** (if you already run Ollama):
+
+```bash
+docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
+ollama pull nomic-embed-text
+```
+
+```json
+"MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
+"MEMORY_EMBEDDING_PROVIDER": "ollama",
+"MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
+"MEMORY_EMBEDDING_MODEL": "nomic-embed-text"
+```
+
+**OpenAI-compatible embedding (hosted API):**
 ```json
 {
   "mcpServers": {
@@ -416,6 +438,27 @@ No installation needed, use the latest version directly.
 }
 ```
 
+#### OpenCode Configuration
+
+**Config file location:**
+- Project-level: `opencode.json` (in project root)
+- Global: `~/.config/opencode/opencode.json`
+
+**Config content:**
+```json
+{
+  "mcp": {
+    "mcp-probe-kit": {
+      "type": "local",
+      "command": ["npx", "-y", "mcp-probe-kit@latest"],
+      "enabled": true
+    }
+  }
+}
+```
+
+> **Note:** OpenCode uses `opencode.json` with a different schema from Cursor/Claude Desktop. The key `mcp` replaces `mcpServers`, `command` is an array, `type: "local"` is required, and environment variables use `environment` instead of `env`. See [OpenCode MCP docs](https://opencode.ai/docs/mcp) for details.
+
 ### Method 2: Global Installation
 
 ```bash
@@ -440,21 +483,14 @@ If you want to use `memorize_asset`, `read_memory_asset`, and `scan_and_extract_
 1. A **Qdrant** vector database
 2. An **embedding service** in either `ollama` or `openai-compatible` mode
 
-#### Option A: Qdrant + Ollama
+**Full guide (Docker Compose for Qdrant + Infinity, ports `50008` / `50012`, MCP env, smoke tests):**
 
-Start Qdrant with Docker:
+- English: [docs/memory-local-setup.md](docs/memory-local-setup.md)
+- 中文: [docs/memory-local-setup.zh-CN.md](docs/memory-local-setup.zh-CN.md)
 
-```bash
-docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
-```
-
-Start Ollama and pull the default embedding model:
-
-```bash
-ollama pull nomic-embed-text
-```
+#### Option A: Qdrant + Nomic Embed / Infinity (recommended)
 
-Recommended MCP config env:
+Lightweight local stack; no Ollama. Deploy Qdrant and `nomic-embed` via Docker Compose (see guide), then:
 
 ```json
 {
@@ -463,11 +499,13 @@ Recommended MCP config env:
       "command": "npx",
       "args": ["-y", "mcp-probe-kit@latest"],
       "env": {
-        "MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
+        "MEMORY_QDRANT_URL": "http://127.0.0.1:50008",
+        "MEMORY_QDRANT_API_KEY": "your-qdrant-api-key",
         "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
-        "MEMORY_EMBEDDING_PROVIDER": "ollama",
-        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
-        "MEMORY_EMBEDDING_MODEL": "nomic-embed-text",
+        "MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
+        "MEMORY_EMBEDDING_URL": "http://127.0.0.1:50012/embeddings",
+        "MEMORY_EMBEDDING_MODEL": "nomic-ai/nomic-embed-text-v1.5",
+        "MEMORY_EMBEDDING_API_KEY": "your-infinity-api-key",
         "MEMORY_SEARCH_LIMIT": "3",
         "MEMORY_SUMMARY_MAX_CHARS": "280"
       }
@@ -476,36 +514,30 @@ Recommended MCP config env:
 }
 ```
 
-#### Option B: Qdrant + OpenAI-Compatible Embedding API
+> Embedding URL must be `/embeddings` (not `/v1/embeddings`). Qdrant requires `api-key` when `QDRANT__SERVICE__API_KEY` is set.
 
-Start Qdrant with Docker:
+#### Option B: Qdrant + Ollama
 
 ```bash
 docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
+ollama pull nomic-embed-text
+```
+
+```json
+"MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
+"MEMORY_EMBEDDING_PROVIDER": "ollama",
+"MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
+"MEMORY_EMBEDDING_MODEL": "nomic-embed-text"
 ```
 
-Then point the embedding config to an OpenAI-compatible `/embeddings` endpoint:
+#### Option C: Qdrant + hosted OpenAI-compatible API
 
 ```json
-{
-  "mcpServers": {
-    "mcp-probe-kit": {
-      "command": "npx",
-      "args": ["-y", "mcp-probe-kit@latest"],
-      "env": {
-        "MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
-        "MEMORY_QDRANT_COLLECTION": "mcp_probe_memory",
-        "MEMORY_QDRANT_API_KEY": "",
-        "MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
-        "MEMORY_EMBEDDING_URL": "https://your-embedding-endpoint/v1/embeddings",
-        "MEMORY_EMBEDDING_API_KEY": "your-api-key",
-        "MEMORY_EMBEDDING_MODEL": "text-embedding-3-small",
-        "MEMORY_SEARCH_LIMIT": "3",
-        "MEMORY_SUMMARY_MAX_CHARS": "280"
-      }
-    }
-  }
-}
+"MEMORY_QDRANT_URL": "http://127.0.0.1:50008",
+"MEMORY_EMBEDDING_PROVIDER": "openai-compatible",
+"MEMORY_EMBEDDING_URL": "https://your-embedding-endpoint/v1/embeddings",
+"MEMORY_EMBEDDING_API_KEY": "your-api-key",
+"MEMORY_EMBEDDING_MODEL": "text-embedding-3-small"
 ```
 
 #### Memory Environment Variables

package/build/index.js

@@ -5,7 +5,7 @@ import { InMemoryTaskMessageQueue, InMemoryTaskStore, } from "@modelcontextproto
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ProgressNotificationSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { initProject, gencommit, codeReview, codeInsight, gentest, refactor, initProjectContext, addFeature, fixBug, estimate, startFeature, startBugfix, startOnboard, startRalph, interview, askUser, uiDesignSystem, uiSearch, syncUiData, startUi, startProduct, gitWorkReport, readMemoryAsset, memorizeAsset, scanAndExtractPatterns, cursorListConversations, cursorSearchConversations, cursorReadConversation } from "./tools/index.js";
+import { initProject, gencommit, codeReview, codeInsight, gentest, refactor, initProjectContext, addFeature, fixBug, estimate, startFeature, startBugfix, startOnboard, startRalph, interview, askUser, uiDesignSystem, uiSearch, syncUiData, startUi, startProduct, gitWorkReport, searchMemory, readMemoryAsset, memorizeAsset, scanAndExtractPatterns, cursorListConversations, cursorSearchConversations, cursorReadConversation } from "./tools/index.js";
 import { VERSION, NAME } from "./version.js";
 import { allToolSchemas } from "./schemas/index.js";
 import { filterTools, getToolsetFromEnv } from "./lib/toolset-manager.js";
@@ -459,6 +459,8 @@ async function executeTool(name, args, context) {
             return await startProduct((args ?? {}), context);
         case "git_work_report":
             return await gitWorkReport(args);
+        case "search_memory":
+            return await searchMemory(args);
         case "read_memory_asset":
             return await readMemoryAsset(args);
         case "memorize_asset":

package/build/lib/__tests__/agents-md-template.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/lib/__tests__/agents-md-template.unit.test.js

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { generateAgentsMdInner } from '../agents-md-template.js';
+import { resolveProjectContextLayout } from '../project-context-layout.js';
+const layout = resolveProjectContextLayout(process.cwd());
+const baseInput = {
+    layout,
+    locale: 'zh-CN',
+    projectName: 'demo',
+    projectVersion: '1.0.0',
+    description: 'test',
+    language: 'TypeScript',
+    category: 'library',
+    docs: [],
+    projectRootPosix: '/repo',
+    graphReady: false,
+};
+describe('generateAgentsMdInner', () => {
+    it('includes memory workflow in zh-CN template', () => {
+        const md = generateAgentsMdInner({ ...baseInput });
+        expect(md).toContain('记忆');
+        expect(md).toContain('start_bugfix');
+        expect(md).toContain('memorize_asset');
+        expect(md).toContain('bugfix');
+        expect(md).toContain('search_memory');
+        expect(md).toContain('自动注入');
+    });
+});

package/build/lib/__tests__/memory-config.unit.test.js

@@ -30,4 +30,13 @@ describe('memory-config 单元测试', () => {
         expect(isMemoryReadEnabled(config)).toBe(true);
         expect(isMemoryEnabled(config)).toBe(true);
     });
+    test('记忆检索展示与阈值环境变量', () => {
+        vi.stubEnv('MEMORY_SEARCH_SHOW_SOURCE', 'true');
+        vi.stubEnv('MEMORY_SEARCH_MIN_SCORE', '0.72');
+        vi.stubEnv('MEMORY_REPO_ID', 'my-org/my-repo');
+        const config = getMemoryConfig();
+        expect(config.searchShowSource).toBe(true);
+        expect(config.searchMinScore).toBe(0.72);
+        expect(config.repoId).toBe('my-org/my-repo');
+    });
 });

package/build/lib/__tests__/memory-injection.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/lib/__tests__/memory-injection.unit.test.js

@@ -0,0 +1,51 @@
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import { renderMemoryGuideSection, truncateInjectionText, } from '../memory-orchestration.js';
+afterEach(() => {
+    vi.unstubAllEnvs();
+});
+describe('memory injection auto-load', () => {
+    test('renders full asset content without asking for read_memory_asset', () => {
+        vi.stubEnv('MEMORY_SEARCH_SHOW_SOURCE', '');
+        vi.stubEnv('MEMORY_REPO_ID', '');
+        const section = renderMemoryGuideSection({
+            enabled: true,
+            available: true,
+            degraded: false,
+            query: 'proxy 400',
+            results: [
+                {
+                    id: 'asset-1',
+                    score: 0.88,
+                    name: 'feishu-proxy-bug',
+                    type: 'bugfix',
+                    description: 'Feishu proxy mismatch',
+                    summary: 'proxy caused 400 on HTTPS',
+                    tags: ['bugfix', 'proxy'],
+                },
+            ],
+            assetsById: {
+                'asset-1': {
+                    id: 'asset-1',
+                    name: 'feishu-proxy-bug',
+                    type: 'bugfix',
+                    description: 'Feishu proxy mismatch',
+                    summary: 'proxy caused 400 on HTTPS',
+                    content: '【现象】submit 成功但 sync_failed\n【根因】HTTP_PROXY 污染\n【修复】proxy:false',
+                    tags: ['bugfix'],
+                    confidence: 0.9,
+                    createdAt: '2026-01-01T00:00:00.000Z',
+                    updatedAt: '2026-01-01T00:00:00.000Z',
+                },
+            },
+        });
+        expect(section).toContain('已自动加载的历史经验全文');
+        expect(section).toContain('【现象】submit 成功但 sync_failed');
+        expect(section).toContain('【根因】HTTP_PROXY 污染');
+        expect(section).toContain('无需再调 `read_memory_asset`');
+        expect(section).not.toMatch(/读取: read_memory_asset/);
+    });
+    test('truncateInjectionText limits long content', () => {
+        expect(truncateInjectionText('abcdef', 4)).toBe('a...');
+        expect(truncateInjectionText('abc', 10)).toBe('abc');
+    });
+});

package/build/lib/__tests__/memory-orchestration.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/lib/__tests__/memory-orchestration.unit.test.js

@@ -0,0 +1,84 @@
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import { renderMemoryGuideSection, shouldShowSourceInSearch, } from '../memory-orchestration.js';
+afterEach(() => {
+    vi.unstubAllEnvs();
+});
+describe('memory-orchestration', () => {
+    test('does not show source path by default', () => {
+        vi.stubEnv('MEMORY_SEARCH_SHOW_SOURCE', '');
+        vi.stubEnv('MEMORY_REPO_ID', '');
+        const section = renderMemoryGuideSection({
+            enabled: true,
+            available: true,
+            degraded: false,
+            query: '404 submit',
+            results: [
+                {
+                    id: '1',
+                    score: 0.91,
+                    name: 'purchase-create-submit-404',
+                    type: 'bugfix',
+                    description: 'desc',
+                    summary: 'summary',
+                    tags: ['bugfix'],
+                    sourceProject: 'zhixing/gongyingshang',
+                    sourcePath: 'admin-api/app.js',
+                },
+            ],
+            assetsById: {},
+        });
+        expect(section).toContain('purchase-create-submit-404');
+        expect(section).not.toContain('admin-api/app.js');
+        expect(section).not.toContain('来源:');
+    });
+    test('shows source path when MEMORY_REPO_ID matches', () => {
+        vi.stubEnv('MEMORY_SEARCH_SHOW_SOURCE', '');
+        vi.stubEnv('MEMORY_REPO_ID', 'zhixing/gongyingshang');
+        expect(shouldShowSourceInSearch({
+            id: '1',
+            score: 0.9,
+            name: 'x',
+            type: 'bugfix',
+            description: '',
+            summary: '',
+            tags: [],
+            sourceProject: 'zhixing/gongyingshang',
+            sourcePath: 'admin-api/app.js',
+        })).toBe(true);
+        expect(shouldShowSourceInSearch({
+            id: '2',
+            score: 0.9,
+            name: 'y',
+            type: 'bugfix',
+            description: '',
+            summary: '',
+            tags: [],
+            sourceProject: 'other/repo',
+            sourcePath: 'src/index.ts',
+        })).toBe(false);
+    });
+    test('MEMORY_SEARCH_SHOW_SOURCE=true always shows source', () => {
+        vi.stubEnv('MEMORY_SEARCH_SHOW_SOURCE', 'true');
+        vi.stubEnv('MEMORY_REPO_ID', '');
+        const section = renderMemoryGuideSection({
+            enabled: true,
+            available: true,
+            degraded: false,
+            query: 'q',
+            results: [
+                {
+                    id: '1',
+                    score: 0.8,
+                    name: 'n',
+                    type: 'bugfix',
+                    description: '',
+                    summary: 's',
+                    tags: [],
+                    sourcePath: 'admin-api/app.js',
+                },
+            ],
+            assetsById: {},
+        });
+        expect(section).toContain('来源: admin-api/app.js');
+    });
+});

package/build/lib/__tests__/memory-payload.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/lib/__tests__/memory-payload.unit.test.js

@@ -0,0 +1,35 @@
+import { describe, expect, test } from 'vitest';
+import { normalizeMemoryPayload, payloadToMemoryFields } from '../memory-payload.js';
+describe('memory-payload', () => {
+    test('maps legacy kind/title/source fields to current schema', () => {
+        const normalized = normalizeMemoryPayload({
+            kind: 'extracted_pattern',
+            title: 'Feishu submit success but sync_failed',
+            source: 'scan_and_extract_patterns-fallback',
+            content: 'Pattern: proxy mismatch',
+            tags: ['feishu', 'pattern'],
+            created_at: '2026-05-25T11:20:06.705Z',
+        });
+        expect(normalized.name).toBe('Feishu submit success but sync_failed');
+        expect(normalized.type).toBe('pattern');
+        expect(normalized.summary).toContain('Pattern');
+        expect(normalized.createdAt).toBe('2026-05-25T11:20:06.705Z');
+    });
+    test('payloadToMemoryFields preserves standard asset fields', () => {
+        const fields = payloadToMemoryFields({
+            id: 'asset-1',
+            name: 'purchase-create-submit-404',
+            type: 'bugfix',
+            description: '送审 404',
+            summary: 'res.data.purchase.id',
+            content: '【现象】404',
+            tags: ['bugfix'],
+            confidence: 0.95,
+            createdAt: '2026-05-27T04:28:04.684Z',
+            updatedAt: '2026-05-27T04:28:04.684Z',
+        });
+        expect(fields.name).toBe('purchase-create-submit-404');
+        expect(fields.type).toBe('bugfix');
+        expect(fields.tags).toEqual(['bugfix']);
+    });
+});

package/build/lib/__tests__/project-context-layout.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/lib/__tests__/project-context-layout.unit.test.js

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, test } from "vitest";
+import { detectDocumentLocale, discoverProjectRootFromLayout, layoutAbsPath, readLayoutManifest, relativeLink, resolveProjectContextLayout, writeLayoutManifest, } from "../project-context-layout.js";
+import { mergeAgentsMdBlock } from "../merge-agents-md.js";
+describe("project-context-layout", () => {
+    test("relativeLink from AGENTS.md to docs paths", () => {
+        const link = relativeLink("AGENTS.md", "docs/project-context/tech-stack.md");
+        expect(link === "docs/project-context/tech-stack.md" || link === "./docs/project-context/tech-stack.md").toBe(true);
+    });
+    test("default layout uses AGENTS.md and docs/", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "layout-"));
+        const layout = resolveProjectContextLayout(root, {});
+        expect(layout.indexPath).toBe("AGENTS.md");
+        expect(layout.contextRoot).toBe("docs");
+        expect(layout.modularDir).toBe("docs/project-context");
+        expect(layout.latestMarkdownPath).toBe("docs/graph-insights/latest.md");
+    });
+    test("writeLayoutManifest is portable (no absolute projectRoot)", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "layout-manifest-"));
+        const layout = resolveProjectContextLayout(root, {});
+        const rel = writeLayoutManifest(root, layout);
+        expect(rel).toBe("docs/.mcp-probe/layout.json");
+        const manifest = readLayoutManifest(root);
+        expect(manifest?.indexPath).toBe("AGENTS.md");
+        expect(manifest?.projectRoot).toBeUndefined();
+        expect(manifest?.projectRootEnv).toBe("MCP_PROJECT_ROOT");
+        expect(discoverProjectRootFromLayout(root)).toBe(path.resolve(root));
+    });
+    test("ignores stale absolute projectRoot in manifest", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "layout-stale-root-"));
+        const layout = resolveProjectContextLayout(root, {});
+        writeLayoutManifest(root, layout);
+        const manifestPath = path.join(root, "docs", ".mcp-probe", "layout.json");
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+        manifest.projectRoot = "Z:/nonexistent/wrong-root";
+        fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+        expect(discoverProjectRootFromLayout(path.join(root, "src"))).toBe(path.resolve(root));
+    });
+    test("infers root for custom contextRoot manifest path", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "layout-custom-docs-"));
+        const layout = resolveProjectContextLayout(root, { docs_dir: "documentation" });
+        writeLayoutManifest(root, layout);
+        expect(fs.existsSync(path.join(root, "documentation", ".mcp-probe", "layout.json"))).toBe(true);
+        const fromSub = resolveProjectContextLayout(path.join(root, "src"), {});
+        expect(fromSub.projectRoot).toBe(path.resolve(root));
+        expect(fromSub.contextRoot).toBe("documentation");
+    });
+    test("discovers projectRoot from layout.json when cwd is subdirectory", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "layout-discover-"));
+        const layout = resolveProjectContextLayout(root, {});
+        writeLayoutManifest(root, layout);
+        const subDir = path.join(root, "src", "tools");
+        fs.mkdirSync(subDir, { recursive: true });
+        expect(discoverProjectRootFromLayout(subDir)).toBe(path.resolve(root));
+        const fromSub = resolveProjectContextLayout(subDir, {});
+        expect(fromSub.projectRoot).toBe(path.resolve(root));
+        expect(layoutAbsPath(fromSub, "docs/project-context.md")).toBe(path.join(root, "docs", "project-context.md"));
+    });
+    test("detectDocumentLocale zh from README", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "layout-zh-"));
+        fs.writeFileSync(path.join(root, "README.md"), "# 测试项目\n\n这是一个中文项目说明，用于单元测试。\n".repeat(5), "utf8");
+        expect(detectDocumentLocale(root)).toBe("zh-CN");
+    });
+});
+describe("mergeAgentsMdBlock", () => {
+    test("prepends block when no marker exists", () => {
+        const { content, mergeMode } = mergeAgentsMdBlock("# User rules\n", "## MCP block");
+        expect(mergeMode).toBe("prepended");
+        expect(content.startsWith("<!-- mcp-probe:context begin")).toBe(true);
+        expect(content).toContain("# User rules");
+    });
+    test("replaces and moves block to top", () => {
+        const existing = "# Footer\n\n<!-- mcp-probe:context begin -->\nold\n<!-- mcp-probe:context end -->\n";
+        const { content, mergeMode } = mergeAgentsMdBlock(existing, "new inner");
+        expect(mergeMode).toBe("replaced-and-moved-to-top");
+        expect(content.indexOf("new inner")).toBeLessThan(content.indexOf("# Footer"));
+    });
+});

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

@@ -0,0 +1,25 @@
+import type { DocumentLocale, ProjectContextLayout } from "./project-context-layout.js";
+export interface AgentsMdTemplateInput {
+    layout: ProjectContextLayout;
+    locale: DocumentLocale;
+    projectName: string;
+    projectVersion: string;
+    description: string;
+    language: string;
+    framework?: string;
+    category: string;
+    docs: Array<{
+        file: string;
+        title: string;
+        purpose: string;
+    }>;
+    projectRootPosix: string;
+    graphReady: boolean;
+    /** @deprecated kept for callers; memory rules are always included in AGENTS.md */
+    memoryEnabled?: boolean;
+}
+/**
+ * Ultra-compact AGENTS.md body (inside mcp-probe block).
+ */
+export declare function generateAgentsMdInner(input: AgentsMdTemplateInput): string;
+export declare function generateAgentsMdTemplate(input: AgentsMdTemplateInput): string;