@datafrog-io/n2n-memory 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025, James
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# N2N 记忆 (N2N Memory) MCP 服务
+
+这是一个专为解决 AI 跨项目开发时“记忆污染”而设计的 MCP 服务。它将 AI 的认知碎片持久化在每个项目自己的目录下。
+
+## 核心亮点
+- **项目级物理隔离**: 记忆文件存储在 `[项目根目录]/.mcp/memory.json`。
+- **Git 版本可控**: 自动对 JSON 数据进行字典序排序，生成清晰的 `git diff`。
+- **工具中立**: 使用 `.mcp` 命名，不绑定任何特定 AI 品牌或 IDE 插件。
+- **资产化**: 记忆随代码走，团队成员拉取仓库即可共享 AI 对架构的理解。
+
+## 快速配置
+
+### 1. JSON 配置 (IDE / Claude Desktop)
+
+根据您使用的客户端，在相应的 MCP 配置文件中添加以下内容：
+
+#### Claude Desktop
+配置文件路径: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "n2n-memory": {
+      "command": "node",
+      "args": ["D:/DevSpace/MCP_N2N_Memory/build/index.js"]
+    }
+  }
+}
+```
+
+#### Cursor / VSCode (MCP 插件)
+在 MCP 设置面板中添加：
+- **Name**: `n2n-memory`
+- **Type**: `command`
+- **Command**: `node D:/DevSpace/MCP_N2N_Memory/build/index.js`
+
+### 2. 使用指南 (Usage Guide)
+
+本服务完全由路径驱动，AI 助手在调用工具时需要关注以下几点：
+
+1. **绝对路径**: 调用任何 `n2n_*` 工具时，必须传入当前项目根目录的**绝对路径**（`projectPath`）。
+2. **自动存储**: 记忆将自动保存在 `[项目路径]/.mcp/memory.json`。
+3. **协作共享**: 建议将 `.mcp/memory.json` 提交至 Git 仓库，以便团队成员共享 AI 对代码架构的理解。
+
+#### 常用场景指令示例：
+- `n2n_add_entities`: 创建新实体。
+- `n2n_add_observations`: 追加观测事实。
+- `n2n_create_relations`: 建立实体间联系。
+- `n2n_read_graph`: 读取完整图谱。
+- `n2n_search`: 关键词搜索图谱（支持实体名、类型、观测事实）。
+- *"将这个新发现的 Bug 记录到内存中"* -> AI 将调用 `n2n_add_observations`。
+
+## 文档指引 (Docs)
+
+- **[设计方案](./docs/DESIGN.md)**: 了解为什么要进行物理隔离以及核心架构设计。
+- **[API 参考手册](./docs/API_REFERENCE.md)**: 详细描述了可用的 Tool 及其参数结构。
+- **[开发与维护](./docs/DEVELOPMENT.md)**: 指导如何构建、测试和扩展本项目。
+
+## 许可证
+本项目采用 [ISC 许可证](./LICENSE)。

package/build/index.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { MemoryManager } from "./memory-manager.js";
+import { EntitySchema, RelationSchema } from "./types.js";
+// Input Schemas for validation
+const AddEntitiesSchema = z.object({
+    projectPath: z.string(),
+    entities: z.array(EntitySchema),
+});
+const AddObservationsSchema = z.object({
+    projectPath: z.string(),
+    observations: z.array(z.object({
+        entityName: z.string(),
+        contents: z.array(z.string()),
+    })),
+});
+const CreateRelationsSchema = z.object({
+    projectPath: z.string(),
+    relations: z.array(RelationSchema),
+});
+const ReadGraphSchema = z.object({
+    projectPath: z.string(),
+});
+const SearchSchema = z.object({
+    projectPath: z.string(),
+    query: z.string().describe("Search keywords for entities, types, or observations"),
+});
+export const server = new Server({
+    name: "n2n-memory",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+        resources: {},
+    },
+});
+// --- Handler Logic Extensions (Exported for Testing) ---
+export const Handlers = {
+    async listTools() {
+        return {
+            tools: [
+                {
+                    name: "n2n_add_entities",
+                    description: "Add new entities (concepts, components, nodes) to the project-local knowledge graph. Use this when you discover a new significant part of the project architecture or a core concept.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            projectPath: { type: "string", description: "Absolute path to the project root" },
+                            entities: {
+                                type: "array",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        name: { type: "string", description: "Unique name of the entity" },
+                                        entityType: { type: "string", description: "Category of the entity (e.g., CLASS, FUNCTION, MODULE, UI_COMPONENT)" },
+                                        observations: { type: "array", items: { type: "string" }, description: "Initial facts or documentation fragments about this entity" },
+                                    },
+                                    required: ["name", "entityType", "observations"],
+                                },
+                            },
+                        },
+                        required: ["projectPath", "entities"],
+                    },
+                },
+                {
+                    name: "n2n_add_observations",
+                    description: "Append new facts or discovery details to existing entities. Use this as you explore the code and learn more about how specific parts work.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            projectPath: { type: "string", description: "Absolute path to the project root" },
+                            observations: {
+                                type: "array",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        entityName: { type: "string", description: "The name of the existing entity to update" },
+                                        contents: { type: "array", items: { type: "string" }, description: "New specific facts or insights to add" },
+                                    },
+                                    required: ["entityName", "contents"],
+                                },
+                            },
+                        },
+                        required: ["projectPath", "observations"],
+                    },
+                },
+                {
+                    name: "n2n_create_relations",
+                    description: "Define relationships between existing entities. Use this to map out dependencies, implementation details, or data flows (e.g., 'AuthService' IMPLEMENTS 'IAuth').",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            projectPath: { type: "string", description: "Absolute path to the project root" },
+                            relations: {
+                                type: "array",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        from: { type: "string", description: "Source entity name" },
+                                        to: { type: "string", description: "Target entity name" },
+                                        relationType: { type: "string", description: "The nature of the link (e.g., CALLS, EXTENDS, USES, CONTAINS)" },
+                                    },
+                                    required: ["from", "to", "relationType"],
+                                },
+                            },
+                        },
+                        required: ["projectPath", "relations"],
+                    },
+                },
+                {
+                    name: "n2n_read_graph",
+                    description: "Fetch the entire knowledge graph for the current project. Use this to get an overview of the system architecture and previously stored context.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            projectPath: { type: "string", description: "Absolute path to the project root" },
+                        },
+                        required: ["projectPath"],
+                    },
+                },
+                {
+                    name: "n2n_search",
+                    description: "Search for specific entities, relations, or observations within the project knowledge graph using keywords. Useful for large projects where the full graph is too big to browse.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            projectPath: { type: "string", description: "Absolute path to the project root" },
+                            query: { type: "string", description: "Keywords to search for in names, types, and observations" },
+                        },
+                        required: ["projectPath", "query"],
+                    },
+                },
+            ],
+        };
+    },
+    async callTool(name, args) {
+        try {
+            switch (name) {
+                case "n2n_add_entities": {
+                    const parsed = AddEntitiesSchema.parse(args);
+                    await MemoryManager.addEntities(parsed.projectPath, parsed.entities);
+                    return { content: [{ type: "text", text: `Success: Added ${parsed.entities.length} entities.` }] };
+                }
+                case "n2n_add_observations": {
+                    const parsed = AddObservationsSchema.parse(args);
+                    const addedCount = await MemoryManager.addObservations(parsed.projectPath, parsed.observations);
+                    return { content: [{ type: "text", text: `Success: Added ${addedCount} observation fragments.` }] };
+                }
+                case "n2n_create_relations": {
+                    const parsed = CreateRelationsSchema.parse(args);
+                    await MemoryManager.createRelations(parsed.projectPath, parsed.relations);
+                    return { content: [{ type: "text", text: `Success: Created ${parsed.relations.length} relations.` }] };
+                }
+                case "n2n_read_graph": {
+                    const parsed = ReadGraphSchema.parse(args);
+                    const graph = await MemoryManager.readGraph(parsed.projectPath);
+                    return { content: [{ type: "text", text: JSON.stringify(graph, null, 2) }] };
+                }
+                case "n2n_search": {
+                    const parsed = SearchSchema.parse(args);
+                    const result = await MemoryManager.search(parsed.projectPath, parsed.query);
+                    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+                }
+                default:
+                    throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Validation Error: ${error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join(', ')}`
+                        }],
+                    isError: true,
+                };
+            }
+            return {
+                content: [{ type: "text", text: `Execution Error: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true,
+            };
+        }
+    },
+    async listResources() {
+        return {
+            resources: [
+                {
+                    uri: "mcp://memory/graph",
+                    name: "Project Knowledge Graph",
+                    description: "The complete knowledge graph stored in .mcp/memory.json",
+                    mimeType: "application/json",
+                }
+            ]
+        };
+    },
+    async readResource(uriString) {
+        const uri = new URL(uriString);
+        if (uri.protocol !== "mcp:" || uri.host !== "memory") {
+            throw new McpError(ErrorCode.InvalidRequest, `Unknown resource URI: ${uriString}`);
+        }
+        const projectPath = uri.searchParams.get("path");
+        if (!projectPath) {
+            throw new McpError(ErrorCode.InvalidParams, "projectPath query parameter 'path' is required");
+        }
+        try {
+            const graph = await MemoryManager.readGraph(projectPath);
+            return {
+                contents: [
+                    {
+                        uri: uriString,
+                        mimeType: "application/json",
+                        text: JSON.stringify(graph, null, 2),
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Failed to read memory: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+};
+// --- Resources ---
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return Handlers.listResources();
+});
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    return Handlers.readResource(request.params.uri);
+});
+// --- Tools ---
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return Handlers.listTools();
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    return Handlers.callTool(request.params.name, request.params.arguments);
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("N2N Memory MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal Server Error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/build/index.js.map

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

package/build/memory-manager.js

@@ -0,0 +1,102 @@
+import fs from "fs-extra";
+import path from "path";
+import { KnowledgeGraphSchema } from "./types.js";
+export const MEMORY_FILE_PATH = ".mcp/memory.json";
+export class MemoryManager {
+    static async readGraph(projectPath) {
+        const filePath = path.resolve(projectPath, MEMORY_FILE_PATH);
+        try {
+            if (await fs.pathExists(filePath)) {
+                const data = await fs.readJson(filePath);
+                return KnowledgeGraphSchema.parse(data);
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to read memory file at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return { entities: [], relations: [] };
+    }
+    static async writeGraph(projectPath, graph) {
+        const filePath = path.resolve(projectPath, MEMORY_FILE_PATH);
+        const dirPath = path.dirname(filePath);
+        try {
+            // Git-friendly sorting
+            graph.entities.sort((a, b) => a.name.localeCompare(b.name));
+            graph.entities.forEach(entity => {
+                if (entity.observations) {
+                    entity.observations.sort();
+                }
+                else {
+                    entity.observations = [];
+                }
+            });
+            graph.relations.sort((a, b) => {
+                const fromComp = a.from.localeCompare(b.from);
+                if (fromComp !== 0)
+                    return fromComp;
+                const toComp = a.to.localeCompare(b.to);
+                if (toComp !== 0)
+                    return toComp;
+                return a.relationType.localeCompare(b.relationType);
+            });
+            await fs.ensureDir(dirPath);
+            await fs.writeJson(filePath, graph, { spaces: 2 });
+        }
+        catch (error) {
+            throw new Error(`Failed to write memory file at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    static async addEntities(projectPath, newEntities) {
+        const graph = await this.readGraph(projectPath);
+        newEntities.forEach(newEntity => {
+            const existing = graph.entities.find(e => e.name === newEntity.name);
+            if (existing) {
+                existing.observations = Array.from(new Set([...existing.observations, ...newEntity.observations]));
+            }
+            else {
+                graph.entities.push(newEntity);
+            }
+        });
+        await this.writeGraph(projectPath, graph);
+    }
+    static async addObservations(projectPath, observations) {
+        const graph = await this.readGraph(projectPath);
+        let addedCount = 0;
+        observations.forEach(obs => {
+            const entity = graph.entities.find(e => e.name === obs.entityName);
+            if (entity) {
+                entity.observations = Array.from(new Set([...entity.observations, ...obs.contents]));
+                addedCount += obs.contents.length;
+            }
+        });
+        await this.writeGraph(projectPath, graph);
+        return addedCount;
+    }
+    static async createRelations(projectPath, newRelations) {
+        const graph = await this.readGraph(projectPath);
+        newRelations.forEach(newRel => {
+            const exists = graph.relations.some(r => r.from === newRel.from && r.to === newRel.to && r.relationType === newRel.relationType);
+            if (!exists) {
+                graph.relations.push(newRel);
+            }
+        });
+        await this.writeGraph(projectPath, graph);
+    }
+    static async search(projectPath, query) {
+        const graph = await this.readGraph(projectPath);
+        const lowerQuery = query.toLowerCase();
+        const filteredEntities = graph.entities.filter(e => e.name.toLowerCase().includes(lowerQuery) ||
+            e.entityType.toLowerCase().includes(lowerQuery) ||
+            e.observations.some(o => o.toLowerCase().includes(lowerQuery)));
+        const entityNames = new Set(filteredEntities.map(e => e.name));
+        const filteredRelations = graph.relations.filter(r => r.from.toLowerCase().includes(lowerQuery) ||
+            r.to.toLowerCase().includes(lowerQuery) ||
+            r.relationType.toLowerCase().includes(lowerQuery) ||
+            (entityNames.has(r.from) || entityNames.has(r.to)));
+        return {
+            entities: filteredEntities,
+            relations: filteredRelations
+        };
+    }
+}
+//# sourceMappingURL=memory-manager.js.map

package/build/memory-manager.js.map

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

package/build/types.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+export const EntitySchema = z.object({
+    name: z.string().describe("Unique name of the entity"),
+    entityType: z.string().describe("Type of entity (e.g. COMPONENT, CONCEPT, BUG)"),
+    observations: z.array(z.string()).describe("A list of observations or facts about the entity"),
+});
+export const RelationSchema = z.object({
+    from: z.string().describe("Name of the source entity"),
+    to: z.string().describe("Name of the target entity"),
+    relationType: z.string().describe("The type of relationship (e.g. DEPENDS_ON, IMPLEMENTS)"),
+});
+export const KnowledgeGraphSchema = z.object({
+    entities: z.array(EntitySchema).default([]),
+    relations: z.array(RelationSchema).default([]),
+});
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;IACtD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;IAChF,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,kDAAkD,CAAC;CACjG,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;IACtD,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;IACpD,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wDAAwD,CAAC;CAC9F,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAC3C,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACjD,CAAC,CAAC"}

package/docs/API_REFERENCE.md

@@ -0,0 +1,70 @@
+# N2N Memory API 参数参考手册
+
+本项目提供了一套基于项目本地路径的知识图谱管理工具。所有工具均要求传入 `projectPath` 以确保记忆的物理隔离。
+
+## 核心工具集
+
+### 1. `project_add_entities`
+向项目的知识图谱中添加新的实体（名词/概念）。
+
+**输入参数:**
+- `projectPath` (string): 项目根目录的绝对路径。
+- `entities` (Array): 实体对象列表。
+    - `name` (string): 实体名称（唯一标识）。
+    - `entityType` (string): 实体类型（如：CONCEPT, COMPONENT, BUG）。
+    - `observations` (string[]): 关于该实体的观测事实。
+
+**逻辑描述:**
+- 如果实体名称已存在，将合并 `observations` 并自动去重。
+- 写入前会对实体名称进行字典序排序。
+
+---
+
+### 2. `project_add_observations`
+为已存在的实体追加新的发现或事实。
+
+**输入参数:**
+- `projectPath` (string): 项目根目录的绝对路径。
+- `observations` (Array):
+    - `entityName` (string): 目标实体名称。
+    - `contents` (string[]): 要追加的事实列表。
+
+**逻辑描述:**
+- 仅当实体存在时才会添加。
+- 自动对 observation 内容执行字典序排序及去重。
+
+---
+
+### 3. `project_create_relations`
+在实体之间建立逻辑关系（谓词）。
+
+**输入参数:**
+- `projectPath` (string): 项目根目录的绝对路径。
+- `relations` (Array):
+    - `from` (string): 源实体名称。
+    - `to` (string): 目标实体名称。
+    - `relationType` (string): 关系类型（如：DEPENDS_ON, IMPLEMENTS）。
+
+**逻辑描述:**
+- 自动过滤完全重复的关系定义，防止数据冗余。
+
+---
+
+### 4. `project_read_graph`
+读取指定项目的完整知识图谱。
+
+**输入参数:**
+- `projectPath` (string): 项目根目录的绝对路径。
+
+**返回:**
+- 包含 `entities` 和 `relations` 的标准 JSON 对象。
+
+---
+
+## 数据存储规范
+- **路径**: `.mcp/memory.json`
+- **格式**: 2 空格缩进的 JSON。
+- **排序策略**: 
+    - 实体：按 `name` 排序。
+    - 关系：按 `from` -> `to` -> `type` 排序。
+    - 观测：按字母序排序。

package/docs/DESIGN.md

@@ -0,0 +1,52 @@
+# N2N Memory (N2N 记忆) 开发方案
+
+## 1. 背景与目标
+解决全局 MCP Memory Server 导致的跨项目“记忆污染”与幻觉问题。通过将 AI 的认知碎片直接持久化在项目源码目录下，实现项目级的物理隔离与知识共享。
+
+本项目旨在开发一个高度简约、工具中立、且对版本管理友好的 N2N 记忆服务。
+
+## 2. 核心架构设计
+
+### 2.1 存储逻辑
+- **存储位置**: `[项目根目录]/.mcp/memory.json`
+- **中立性**: 采用 `.mcp` 命名以脱离特定 AI 助手或 IDE 插件的品牌绑定。
+- **物理隔离**: 一个项目一个文件，互不干扰，完全随项目代码同步。
+
+### 2.2 交互规范
+- **寻址方式**: AI 助理在调用工具时，必须传递当前工作区的**绝对路径 (Absolute Path)**。
+- **无状态设计**: MCP Server 进程本身不维护任何路径状态，仅作为由路径驱动的存取器。
+- **自动初始化**: 若目标路径下的 `.mcp/memory.json` 不存在，Server 应自动创建标准的空图谱结构。
+
+## 3. 数据结构与检索
+
+### 3.1 极简数据格式
+JSON 内部**不包含**版本号、元数据、作者信息或时间戳。仅保留核心知识图谱数据（Entities & Relations），通过 Git 记录实现版本审计。
+
+### 3.2 Git 友好型保存策略
+为确保 `git diff` 可读：
+1. **强制排序**: 对 `entities` 和 `relations` 执行字典序排序。
+2. **规范缩进**: 统一使用 2 空格缩进。
+
+### 3.3 分级检索机制 (Tiered Retrieval)
+- **一级：精准检索**: 基于实体 ID 的 O(1) 匹配，保证逻辑严密性。
+- **二级：语义理解**: AI 助手加载全量 JSON 后，利用模型自身的长上下文理解力处理模糊匹配，无需引入向量数据库。
+
+## 4. 开发语言效率分析 (Go vs. Node.js vs. Python)
+
+### 4.1 Node.js (TypeScript) - [默认推荐]
+- **效率**: 开发效率极高，官方 SDK 最成熟。
+- **性能**: 处理单个项目的 JSON（通常 < 10MB）绰绰有余。
+- **分发**: 通过 `npx` 可实现免安装运行。
+
+### 4.2 Go - [极致性能选型]
+- **效率**: 运行效率最高，内存占用极低（仅需几 MB）。
+- **分发**: 编译为单一二进制文件（Single Binary），部署最干净，适合对 IDE 性能有极致要求的用户。
+- **场景**: 若未来需要处理拥有数万个节点的超大型知识图谱，Go 是唯一选择。
+
+### 4.3 Python - [不推荐]
+- **缺点**: 环境依赖重，分发困难，对于简单的、非 AI 计算密集的 I/O 任务显得过于沉重。
+
+## 5. 优势总结
+- **资产化**: 记忆即源码，可审计、可共享。
+- **零漂移**: 物理隔离，杜绝跨项目污染。
+- **确定性**: 结构化数据比高性能向量数据库更适合高精度的编码决策场景。

package/docs/DEVELOPMENT.md

@@ -0,0 +1,54 @@
+# 开发与维护手册
+
+本手册记录了 N2N Memory MCP Server 的日常开发、测试及构建流程。
+
+## 开发环境
+- **Runtime**: Node.js v22.x+
+- **Language**: TypeScript
+- **Package Manager**: npm
+
+## 常用指令
+
+### 1. 安装依赖
+```bash
+npm install
+```
+
+### 2. 运行测试
+本项目使用 `mocha` + `sinon` 执行单元测试。
+```bash
+npm test
+```
+> **注意**: 在 Windows 环境下，测试脚本已配置为使用 `tsx --import` 以正确处理 ESM 路径兼容性。
+
+### 3. 开发模式 (热更新)
+```bash
+npm run dev
+```
+
+### 4. 生产构建
+将 TypeScript 编译为原生 JavaScript（输出到 `build/` 目录）。
+```bash
+npm run build
+```
+
+### 5. 启动服务
+```bash
+npm start
+```
+
+## 核心架构说明
+
+### 逻辑分层
+1. **`index.ts`**: MCP 协议层。负责处理 JSON-RPC、Resources 接口，并使用 **Zod** 进行输入校验。
+2. **`memory-manager.ts`**: 业务逻辑层。负责文件 I/O、数据排序、实体合并等核心算法。
+3. **`types.ts`**: 类型与 Schema 定义。包含 Zod 校验规则，是整个项目的类型基准。
+
+### 关键算法：Git 友好排序
+每当执行写操作（Update/Create）时，`MemoryManager.writeGraph` 会被触发：
+- 它会递归地对数组进行 `localeCompare` 排序。
+- 这样做的目的是保证即使 AI 乱序生成了记忆片段，存入 Git 的文件 diff 依然是稳定且可读的。
+
+## 贡献指南
+- 所有的逻辑变更必须附带相应的单元测试。
+- 修改存储结构前，请先更新 `docs/DESIGN.md`。

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@datafrog-io/n2n-memory",
+  "version": "1.0.0",
+  "description": "",
+  "main": "build/index.js",
+  "bin": {
+    "n2n-memory": "build/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "mocha --node-option import=tsx src/test/**/*.test.ts",
+    "lint": "eslint src/**/*.ts"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "fs-extra": "^11.3.3",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/chai": "^5.2.3",
+    "@types/fs-extra": "^11.0.4",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^25.0.3",
+    "@types/sinon": "^21.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.50.0",
+    "@typescript-eslint/parser": "^8.50.0",
+    "chai": "^6.2.1",
+    "eslint": "^9.39.2",
+    "mocha": "^11.7.5",
+    "sinon": "^21.0.0",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.0"
+  }
+}