@datafrog-io/n2n-memory 1.2.0 → 1.2.2

package/build/utils/logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../../src/utils/logging.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,MAAM,UAAU,cAAc;IAC1B,OAAO,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,WAAW,EAAE,KAAK,OAAO,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,WAAmB;IACjD,IAAI,cAAc,EAAE,EAAE,CAAC;QACnB,OAAO,WAAW,CAAC;IACvB,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC5C,OAAO,QAAQ,IAAI,WAAW,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,OAAe;IACnC,IAAI,cAAc,EAAE,EAAE,CAAC;QACnB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;AACL,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAe;IACtC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,KAAe;IACrD,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;QAC3C,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACvB,OAAO;IACX,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AAClC,CAAC"}

package/build/utils/path-utils.js

@@ -1,9 +1,9 @@
 import path from "path";
 import fs from "fs-extra";
 /**
- * Common markers that define a project root.
+ * Strong markers that define a project root.
  */
-const ROOT_MARKERS = [
+const STRONG_ROOT_MARKERS = [
     ".git",
     ".mcp",
     "package.json",
@@ -12,11 +12,13 @@ const ROOT_MARKERS = [
     "requirements.txt",
     "pom.xml",
     "composer.json",
-    "README.md",
     ".vscode",
     "tsconfig.json",
     ".gitignore"
 ];
+const WEAK_ROOT_MARKERS = [
+    "README.md"
+];
 /**
  * Recursively finds the project root.
  * NOTE: For N2N-Memory, we now strictly only check the provided path or its immediate markers
@@ -24,12 +26,12 @@ const ROOT_MARKERS = [
  * @param startPath The path to start searching from.
  */
 export async function findProjectRoot(startPath) {
-    const absoluteStart = path.resolve(startPath);
+    const absoluteStart = validateAbsolutePath(startPath);
     const current = absoluteStart;
     const foundMarkers = [];
     let hasMcp = false;
-    // Check current directory for markers
-    for (const marker of ROOT_MARKERS) {
+    // Check current directory for strong markers.
+    for (const marker of STRONG_ROOT_MARKERS) {
         const markerPath = path.join(current, marker);
         if (await fs.pathExists(markerPath)) {
             foundMarkers.push(marker);
@@ -40,7 +42,15 @@ export async function findProjectRoot(startPath) {
     if (foundMarkers.length > 0) {
         return { rootPath: current, hasMcp, markersFound: foundMarkers };
     }
-    throw new Error(`Directory Not Recognized as a Project Root: No project markers (.git, package.json, README.md, etc.) found in "${absoluteStart}". ` +
+    const weakMarkersFound = [];
+    for (const marker of WEAK_ROOT_MARKERS) {
+        const markerPath = path.join(current, marker);
+        if (await fs.pathExists(markerPath)) {
+            weakMarkersFound.push(marker);
+        }
+    }
+    throw new Error(`Directory Not Recognized as a Project Root: No strong project markers (.git, package.json, tsconfig.json, etc.) found in "${absoluteStart}". ` +
+        `${weakMarkersFound.length > 0 ? `Weak markers found (${weakMarkersFound.join(", ")}), but they are not sufficient for initialization. ` : ""}` +
         `N2N-Memory strictly requires you to open the IDE at the project root or use a workspace top-level directory. ` +
         `Memory initialization is refused for generic or sub-directories to prevent context pollution.`);
 }
@@ -50,9 +60,11 @@ export async function findProjectRoot(startPath) {
 export function validateAbsolutePath(projectPath) {
     if (!projectPath)
         throw new Error("Project path is required.");
-    const resolved = path.resolve(projectPath);
-    if (!path.isAbsolute(resolved))
+    if (projectPath.includes('\0'))
+        throw new Error("Invalid path detected.");
+    if (!path.isAbsolute(projectPath))
         throw new Error(`Path must be absolute: ${projectPath}`);
+    const resolved = path.resolve(projectPath);
     if (resolved.includes('\0'))
         throw new Error("Invalid path detected.");
     return resolved;

package/build/utils/path-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../../src/utils/path-utils.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,MAAM,UAAU,CAAC;AAE1B;;GAEG;AACH,MAAM,YAAY,GAAG;IACjB,MAAM;IACN,MAAM;IACN,cAAc;IACd,QAAQ;IACR,YAAY;IACZ,kBAAkB;IAClB,SAAS;IACT,eAAe;IACf,WAAW;IACX,SAAS;IACT,eAAe;IACf,YAAY;CACf,CAAC;AAcF;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,SAAiB;IACnD,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,aAAa,CAAC;IAE9B,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,sCAAsC;IACtC,KAAK,MAAM,MAAM,IAAI,YAAY,EAAE,CAAC;QAChC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC9C,IAAI,MAAM,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAClC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC1B,IAAI,MAAM,KAAK,MAAM;gBAAE,MAAM,GAAG,IAAI,CAAC;QACzC,CAAC;IACL,CAAC;IAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;IACrE,CAAC;IAED,MAAM,IAAI,KAAK,CACX,kHAAkH,aAAa,KAAK;QACpI,+GAA+G;QAC/G,+FAA+F,CAClG,CAAC;AACN,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACpD,IAAI,CAAC,WAAW;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/D,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3C,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,WAAW,EAAE,CAAC,CAAC;IACzF,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IACvE,OAAO,QAAQ,CAAC;AACpB,CAAC"}
+{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../../src/utils/path-utils.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,MAAM,UAAU,CAAC;AAE1B;;GAEG;AACH,MAAM,mBAAmB,GAAG;IACxB,MAAM;IACN,MAAM;IACN,cAAc;IACd,QAAQ;IACR,YAAY;IACZ,kBAAkB;IAClB,SAAS;IACT,eAAe;IACf,SAAS;IACT,eAAe;IACf,YAAY;CACf,CAAC;AAEF,MAAM,iBAAiB,GAAG;IACtB,WAAW;CACd,CAAC;AAcF;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,SAAiB;IACnD,MAAM,aAAa,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG,aAAa,CAAC;IAE9B,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,8CAA8C;IAC9C,KAAK,MAAM,MAAM,IAAI,mBAAmB,EAAE,CAAC;QACvC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC9C,IAAI,MAAM,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAClC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC1B,IAAI,MAAM,KAAK,MAAM;gBAAE,MAAM,GAAG,IAAI,CAAC;QACzC,CAAC;IACL,CAAC;IAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;IACrE,CAAC;IAED,MAAM,gBAAgB,GAAa,EAAE,CAAC;IACtC,KAAK,MAAM,MAAM,IAAI,iBAAiB,EAAE,CAAC;QACrC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC9C,IAAI,MAAM,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAClC,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,KAAK,CACX,6HAA6H,aAAa,KAAK;QAC/I,GAAG,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,uBAAuB,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,qDAAqD,CAAC,CAAC,CAAC,EAAE,EAAE;QAC/I,+GAA+G;QAC/G,+FAA+F,CAClG,CAAC;AACN,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACpD,IAAI,CAAC,WAAW;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/D,IAAI,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC1E,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,WAAW,EAAE,CAAC,CAAC;IAC5F,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3C,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IACvE,OAAO,QAAQ,CAAC;AACpB,CAAC"}

package/docs/API_REFERENCE.md

@@ -0,0 +1,283 @@
+# n2n-memory API Reference
+
+[中文版](./API_REFERENCE_zh.md)
+
+---
+
+N2N-Memory provides project-local knowledge graph tools over MCP. Every tool requires `projectPath`, the absolute path of the project root or workspace top-level directory. The server does not recursively search parent directories; this is intentional to prevent cross-project memory pollution.
+
+Project recognition requires a strong marker such as `.git`, `.mcp`, `package.json`, `tsconfig.json`, or a language-specific build file. README-only directories are treated as weak roots and rejected.
+
+## SEO and discoverability notes
+
+- Recommended labels: **project-local MCP memory**, **AI coding memory graph**, **local-first AI context storage**.
+- Primary user intent: repository context recovery, deterministic project memory, and safe AI coding assistant handoff.
+- This API is designed for local-first agents and does not depend on cloud infrastructure.
+
+## Shared Parameters
+
+All tools include:
+
+- `projectPath` (`string`, required): Absolute project root or workspace top-level path.
+- `confirmNewProjectRoot` (`string`, optional): Required only when initializing a project that does not yet have `.mcp`. Use the `detectedRoot` value returned by the handshake response.
+
+If the server recognizes a project root but `.mcp` is missing, it returns an `AWAITING_CONFIRMATION` error response. Call the same tool again with `confirmNewProjectRoot` set to the detected root.
+
+## Data Storage
+
+- Cold graph: `.mcp/memory.json`
+- Hot context: `.mcp/context.json`
+- Atomic writes: JSON is written to a temporary file and then moved into place.
+- Stable diffs: entities, observations, and relations are sorted before graph writes.
+- Data integrity: existing but unreadable JSON files raise an error instead of being treated as empty memory.
+- Path containment: exported files must stay inside the project root.
+- Logging: full local paths are hidden from server logs by default. Set `N2N_LOG_LEVEL=debug` to include complete paths while troubleshooting.
+
+## Data Model
+
+### Entity
+```json
+{
+  "name": "MemoryService",
+  "entityType": "CLASS",
+  "observations": ["Coordinates graph and context reads"]
+}
+```
+
+### Relation
+```json
+{
+  "from": "MemoryService",
+  "to": "MemoryManager",
+  "relationType": "USES"
+}
+```
+
+Relations must reference existing entities. Orphan relations are rejected.
+
+### Project Context
+```json
+{
+  "activeTask": "Refactor storage layer",
+  "status": "IN_PROGRESS",
+  "reason": "Optional status reason",
+  "nextSteps": ["Run tests"],
+  "lastCommit": "abc123 or message",
+  "updatedAt": "2026-06-14T00:00:00.000Z"
+}
+```
+
+`updatedAt` is managed by the server when context is written.
+
+## Resources & Templates
+
+### Static Resource
+- **URI**: `mcp://memory/graph`
+- **Note**: Requires the client to manage project path context or use the template below.
+
+### Resource Template
+- **Template**: `mcp://memory/graph?path={path}`
+- **Example**: `mcp://memory/graph?path=/home/deploy/projects/n2n-memory`
+- **Behavior**: Returns the complete graph and active context for established projects. New projects must be initialized through tools because resources cannot perform the confirmation handshake.
+
+## Tool Responses & Metadata
+
+Most mutating tools return structured JSON:
+
+```json
+{
+  "status": "success",
+  "message": "Human-readable description of the operation.",
+  "_protocol": {
+    "action": "MEMORY_UPDATED",
+    "reminder": "Remember to call n2n_update_context before 'git commit'."
+  }
+}
+```
+
+The `_protocol` field guides AI assistants during development cycles:
+
+- `action`: Logical state change, such as `MEMORY_LOADED`, `MEMORY_UPDATED`, or `CONTEXT_SYNCED`.
+- `reminder`: Synchronization hint for AI assistants.
+- `policy` / `tip`: Context-specific behavior guidance when present.
+
+## Common usage patterns
+
+1. Start each session by calling `n2n_read_graph` with `summaryMode: true` to inspect the project index.
+2. Add durable facts with `n2n_add_entities` and `n2n_add_observations`.
+3. Link facts with `n2n_create_relations`.
+4. Track daily work in `n2n_update_context` before major refactors.
+5. Before commit, call `n2n_read_graph` again so the context reminder is refreshed.
+
+Example `n2n_update_context` payload:
+
+```json
+{
+  "projectPath": "/absolute/path/to/repo",
+  "activeTask": "Refactor MCP error handling",
+  "status": "IN_PROGRESS",
+  "nextSteps": ["Run tests", "Update docs"],
+  "reason": "Refactor without changing public API"
+}
+```
+
+## Tools
+
+### `n2n_add_entities`
+
+Create new entities or merge observations into existing entities with the same name.
+
+Additional input:
+
+- `entities` (`Entity[]`, required)
+
+Notes:
+
+- Existing entity type is preserved.
+- Observations are deduplicated with lightweight similarity checks.
+
+### `n2n_add_observations`
+
+Append observations to existing entities.
+
+Additional input:
+
+- `observations` (`Array<{ entityName: string; contents: string[] }>`, required)
+
+Notes:
+
+- Observations for missing entities are skipped.
+- The response reports how many observation fragments were actually added after deduplication.
+
+### `n2n_create_relations`
+
+Create directed relations between existing entities.
+
+Additional input:
+
+- `relations` (`Relation[]`, required)
+
+Notes:
+
+- Duplicate relations are ignored.
+- Relations pointing to missing entities are rejected.
+
+### `n2n_read_graph`
+
+Read project graph and active context together.
+
+Additional input:
+
+- `summaryMode` (`boolean`, optional): Return entity names and types without observations.
+- `limit` (`number`, optional): Maximum entities to return.
+- `offset` (`number`, optional): Number of entities to skip.
+
+Output includes:
+
+- `graph`
+- `context`
+- `totalEntityCount`
+- `isTruncated`
+- `_protocol`
+
+When paginated, relations are included only when both endpoints are present in the current page.
+
+### `n2n_get_graph_summary`
+
+Return a lightweight entity index plus total relation count.
+
+Additional input:
+
+- `limit` (`number`, optional)
+- `offset` (`number`, optional)
+
+Output includes:
+
+- `entities`: `{ name, type }[]`
+- `relationCount`
+- `totalEntityCount`
+- `isTruncated`
+
+### `n2n_update_context`
+
+Update hot project context.
+
+Additional input:
+
+- `activeTask` (`string`, optional)
+- `status` (`"IN_PROGRESS" | "COMPLETED" | "BLOCKED" | "PLANNING"`, optional)
+- `reason` (`string`, optional)
+- `nextSteps` (`string[]`, optional)
+- `lastCommit` (`string`, optional)
+
+Notes:
+
+- Updates are merged with the current context.
+- `updatedAt` is set automatically.
+
+### `n2n_search`
+
+Search entities by name, type, and observations. Fuzzy matching is enabled by default.
+
+Additional input:
+
+- `query` (`string`, required)
+- `limit` (`number`, optional)
+- `offset` (`number`, optional)
+- `fuzzy` (`boolean`, optional, default `true`)
+- `minScore` (`number`, optional, default `0.3`)
+
+Output includes matching entities, related relations, `totalResults`, and `isTruncated`.
+
+### `n2n_delete_entities`
+
+Delete entities and all relations attached to them.
+
+Additional input:
+
+- `entityNames` (`string[]`, required)
+
+Output reports the number of deleted entities.
+
+### `n2n_delete_observations`
+
+Delete exact observation strings from entities.
+
+Additional input:
+
+- `deletions` (`Array<{ entityName: string; observations: string[] }>`, required)
+
+Output reports the number of deleted observations.
+
+### `n2n_delete_relations`
+
+Delete exact relation triples.
+
+Additional input:
+
+- `relations` (`Relation[]`, required)
+
+Output reports the number of deleted relations.
+
+### `n2n_open_nodes`
+
+Retrieve specific entities by name.
+
+Additional input:
+
+- `names` (`string[]`, required)
+
+Output includes matching entities and relations where both endpoints are among the returned entities.
+
+### `n2n_export_markdown`
+
+Export the graph to Markdown for review or documentation.
+
+Additional input:
+
+- `outputPath` (`string`, optional): Relative output path inside the project root. Defaults to `KNOWLEDGE_GRAPH.md`.
+
+Notes:
+
+- Absolute paths are rejected.
+- Relative paths that escape the project root are rejected.

package/docs/API_REFERENCE_zh.md

@@ -0,0 +1,283 @@
+# n2n-memory API 参考手册
+
+[English](./API_REFERENCE.md)
+
+---
+
+N2N-Memory 通过 MCP 提供项目本地知识图谱工具。所有工具都要求传入 `projectPath`，即项目根目录或工作区顶级目录的绝对路径。服务不会递归向上搜索父目录，这是为了避免跨项目记忆污染。
+
+项目识别要求存在 `.git`、`.mcp`、`package.json`、`tsconfig.json` 或语言构建文件等强标记。只有 README 的目录会被视为弱根目录并被拒绝。
+
+## SEO 与可发现性说明
+
+- 推荐检索词：**项目级 MCP memory**、**AI 编码记忆图谱**、**本地优先 AI 上下文存储**。
+- 主要使用意图：仓库上下文恢复、确定性的项目记忆、与 AI 编码助手的安全交接。
+- 本 API 采用本地优先设计，不依赖云端服务。
+
+## 共享参数
+
+所有工具都包含：
+
+- `projectPath`（`string`，必填）：项目根目录或工作区顶级目录的绝对路径。
+- `confirmNewProjectRoot`（`string`，可选）：仅在初始化尚未创建 `.mcp` 的项目时使用。取值应为握手响应中的 `detectedRoot`。
+
+如果服务识别到项目根目录，但 `.mcp` 尚不存在，会返回 `AWAITING_CONFIRMATION` 错误响应。此时使用同一个工具再次调用，并将 `confirmNewProjectRoot` 设置为返回的 `detectedRoot`。
+
+## 数据存储
+
+- 冷知识图谱：`.mcp/memory.json`
+- 热任务上下文：`.mcp/context.json`
+- 原子写入：JSON 先写入临时文件，再移动到目标位置。
+- 稳定 diff：写入图谱前会对实体、观测事实、关系执行排序。
+- 数据完整性：已存在但无法读取的 JSON 文件会抛错，不会被当成空记忆。
+- 路径边界：导出文件必须保留在项目根目录内部。
+- 日志：服务日志默认隐藏完整本地路径。排查问题时可设置 `N2N_LOG_LEVEL=debug` 输出完整路径。
+
+## 数据模型
+
+### Entity
+```json
+{
+  "name": "MemoryService",
+  "entityType": "CLASS",
+  "observations": ["Coordinates graph and context reads"]
+}
+```
+
+### Relation
+```json
+{
+  "from": "MemoryService",
+  "to": "MemoryManager",
+  "relationType": "USES"
+}
+```
+
+关系必须指向已存在实体。指向不存在实体的孤儿关系会被拒绝。
+
+### Project Context
+```json
+{
+  "activeTask": "Refactor storage layer",
+  "status": "IN_PROGRESS",
+  "reason": "Optional status reason",
+  "nextSteps": ["Run tests"],
+  "lastCommit": "abc123 or message",
+  "updatedAt": "2026-06-14T00:00:00.000Z"
+}
+```
+
+`updatedAt` 由服务在写入上下文时自动维护。
+
+## 资源与模板
+
+### 静态资源
+- **URI**: `mcp://memory/graph`
+- **注意**: 要求客户端手动管理项目路径上下文，或使用下方的资源模板。
+
+### 资源模板
+- **模板**: `mcp://memory/graph?path={path}`
+- **示例**: `mcp://memory/graph?path=/home/deploy/projects/n2n-memory`
+- **行为**: 对已初始化项目返回完整图谱与活跃上下文。新项目必须通过工具完成确认握手，因为资源读取无法携带初始化确认参数。
+
+## 工具响应与元数据
+
+多数写入工具返回结构化 JSON：
+
+```json
+{
+  "status": "success",
+  "message": "操作的人类可读描述。",
+  "_protocol": {
+    "action": "MEMORY_UPDATED",
+    "reminder": "Remember to call n2n_update_context before 'git commit'."
+  }
+}
+```
+
+`_protocol` 字段用于在开发周期内引导 AI 助手：
+
+- `action`：逻辑状态变更，例如 `MEMORY_LOADED`、`MEMORY_UPDATED` 或 `CONTEXT_SYNCED`。
+- `reminder`：给 AI 助手的同步提醒。
+- `policy` / `tip`：存在时表示特定上下文下的行为提示。
+
+## 常见使用流程
+
+1. 会话开始时先调用 `n2n_read_graph`，可用 `summaryMode: true` 获取项目实体索引。
+2. 用 `n2n_add_entities`、`n2n_add_observations` 写入长期事实。
+3. 用 `n2n_create_relations` 建立关系。
+4. 在关键阶段用 `n2n_update_context` 记录任务进展。
+5. 提交前再次调用 `n2n_read_graph`，让上下文同步提醒保持最新。
+
+`n2n_update_context` 示例：
+
+```json
+{
+  "projectPath": "/absolute/path/to/repo",
+  "activeTask": "重构 MCP 错误处理",
+  "status": "IN_PROGRESS",
+  "nextSteps": ["运行测试", "更新文档"],
+  "reason": "在不改动外部行为的前提下优化上下文"
+}
+```
+
+## 工具
+
+### `n2n_add_entities`
+
+创建新实体，或将观测事实合并到同名实体。
+
+额外输入：
+
+- `entities`（`Entity[]`，必填）
+
+说明：
+
+- 已存在实体的 `entityType` 会保留。
+- 观测事实会通过轻量相似度规则去重。
+
+### `n2n_add_observations`
+
+向已存在实体追加观测事实。
+
+额外输入：
+
+- `observations`（`Array<{ entityName: string; contents: string[] }>`，必填）
+
+说明：
+
+- 指向不存在实体的观测事实会被跳过。
+- 响应会报告去重后实际新增的观测事实数量。
+
+### `n2n_create_relations`
+
+在已存在实体之间创建有向关系。
+
+额外输入：
+
+- `relations`（`Relation[]`，必填）
+
+说明：
+
+- 重复关系会被忽略。
+- 指向不存在实体的关系会被拒绝。
+
+### `n2n_read_graph`
+
+同时读取项目知识图谱和活跃上下文。
+
+额外输入：
+
+- `summaryMode`（`boolean`，可选）：只返回实体名称和类型，不返回观测事实。
+- `limit`（`number`，可选）：最多返回多少个实体。
+- `offset`（`number`，可选）：跳过多少个实体。
+
+输出包含：
+
+- `graph`
+- `context`
+- `totalEntityCount`
+- `isTruncated`
+- `_protocol`
+
+分页读取时，只有当关系两端实体都在当前页中，该关系才会返回。
+
+### `n2n_get_graph_summary`
+
+返回轻量实体索引和关系总数。
+
+额外输入：
+
+- `limit`（`number`，可选）
+- `offset`（`number`，可选）
+
+输出包含：
+
+- `entities`：`{ name, type }[]`
+- `relationCount`
+- `totalEntityCount`
+- `isTruncated`
+
+### `n2n_update_context`
+
+更新热任务上下文。
+
+额外输入：
+
+- `activeTask`（`string`，可选）
+- `status`（`"IN_PROGRESS" | "COMPLETED" | "BLOCKED" | "PLANNING"`，可选）
+- `reason`（`string`，可选）
+- `nextSteps`（`string[]`，可选）
+- `lastCommit`（`string`，可选）
+
+说明：
+
+- 更新会与当前上下文合并。
+- `updatedAt` 会自动写入。
+
+### `n2n_search`
+
+按实体名称、类型、观测事实搜索图谱。默认启用模糊匹配。
+
+额外输入：
+
+- `query`（`string`，必填）
+- `limit`（`number`，可选）
+- `offset`（`number`，可选）
+- `fuzzy`（`boolean`，可选，默认 `true`）
+- `minScore`（`number`，可选，默认 `0.3`）
+
+输出包含匹配实体、相关关系、`totalResults` 与 `isTruncated`。
+
+### `n2n_delete_entities`
+
+删除实体及其关联关系。
+
+额外输入：
+
+- `entityNames`（`string[]`，必填）
+
+输出会报告删除的实体数量。
+
+### `n2n_delete_observations`
+
+从实体中删除精确匹配的观测事实字符串。
+
+额外输入：
+
+- `deletions`（`Array<{ entityName: string; observations: string[] }>`，必填）
+
+输出会报告删除的观测事实数量。
+
+### `n2n_delete_relations`
+
+删除精确匹配的关系三元组。
+
+额外输入：
+
+- `relations`（`Relation[]`，必填）
+
+输出会报告删除的关系数量。
+
+### `n2n_open_nodes`
+
+按名称读取指定实体。
+
+额外输入：
+
+- `names`（`string[]`，必填）
+
+输出包含匹配实体，以及两端都在返回实体集合内的关系。
+
+### `n2n_export_markdown`
+
+将图谱导出为 Markdown，便于审阅或生成文档。
+
+额外输入：
+
+- `outputPath`（`string`，可选）：项目根目录内的相对输出路径，默认 `KNOWLEDGE_GRAPH.md`。
+
+说明：
+
+- 绝对路径会被拒绝。
+- 试图逃逸项目根目录的相对路径会被拒绝。