@datafrog-io/n2n-memory 1.2.1 → 1.2.2

package/docs/DESIGN.md

@@ -0,0 +1,72 @@
+# n2n-memory Design Solution
+
+[中文版](./DESIGN_zh.md)
+
+---
+
+## 1. Context & Objectives
+To solve the "memory pollution" and hallucination issues caused by global MCP Memory Servers. By persisting AI cognitive fragments directly within the project source directory, we achieve project-level physical isolation and shared knowledge.
+
+This project aims to develop a minimalist, tool-agnostic, and version-control-friendly memory service.
+
+## 2. Core Architecture
+
+### 2.1 Storage Logic
+- **Cold Memory Location**: `[Project Root]/.mcp/memory.json`
+- **Hot Context Location**: `[Project Root]/.mcp/context.json`
+- **Agnosticism**: Uses the `.mcp` naming convention to avoid branding ties to specific AI assistants or IDE plugins.
+- **Physical Isolation**: One `.mcp` workspace per project, synchronized with project code.
+
+### 2.2 Interaction & Security
+- **Strict Root Enforcement**: Cancels recursive parent searches. AI must operate from the recognized project root or workspace top-level.
+- **Strong Root Markers**: Initialization requires strong markers such as `.git`, `package.json`, `tsconfig.json`, or language-specific build files. README-only directories are rejected as weak roots.
+- **Handshake Protocol**: Requires explicit confirmation (`confirmNewProjectRoot`) for new project initialization to prevent directory pollution.
+- **Path Containment**: Export and generated files must stay inside the project root.
+- **Private Logs by Default**: Full local paths are hidden from server logs unless `N2N_LOG_LEVEL=debug` is set.
+- **Dual-Buffer Architecture**:
+    - **Hot State (`context.json`)**: Volatile, high-frequency updates (tasks, status).
+    - **Cold State (`memory.json`)**: Durable, structured knowledge graph (entities, relations).
+
+## 3. Data Structure & Retrieval
+
+### 3.1 Minimalist Data Format
+`memory.json` does **not** include version numbers, metadata, author info, or timestamps. Only core knowledge graph data (Entities & Relations) is kept, with auditing achieved via Git history.
+
+`context.json` is a separate hot-state buffer. It may include operational fields such as `activeTask`, `status`, `nextSteps`, and `updatedAt` because this state changes frequently and is not part of the durable knowledge graph contract.
+
+### 3.2 Git-Friendly Saving Strategy
+To ensure readable `git diff`:
+1. **Mandatory Sorting**: Lexicographical sorting for `entities` and `relations`.
+2. **Standard Indentation**: Uniform use of 2-space indentation.
+3. **Safe Writes**: JSON writes use a temporary file followed by an atomic move.
+
+Existing but unreadable JSON files are treated as data integrity errors, not as empty memory. This prevents a corrupted file from being accidentally overwritten by a new empty graph.
+
+### 3.3 Graph Integrity
+- **Entity Uniqueness**: Entity names are the stable identifiers within a project graph.
+- **Relation Integrity**: Relations must point to existing entities. Orphan edges are rejected by default.
+
+### 3.4 Scalable Retrieval Mechanism
+- **Pagination (Limit/Offset)**: Supports chunked reading for massive graphs to stay within token limits.
+- **Summary Mode**: Optional retrieval of entity indexes without detailed observations.
+- **Precise Open**: `open_nodes` for fetching specific high-detail context.
+
+## 4. Language Efficiency Analysis (Go vs. Node.js vs. Python)
+
+### 4.1 Node.js (TypeScript) - [Default Recommendation]
+- **Efficiency**: Rapid development, most mature official SDK.
+- **Performance**: More than sufficient for per-project JSON files (typically < 10MB).
+- **Distribution**: Zero-install execution via `npx`.
+
+### 4.2 Go - [Performance Selection]
+- **Efficiency**: Highest runtime efficiency, minimal memory footprint (only a few MBs).
+- **Distribution**: Single binary compilation for clean deployment, ideal for power users.
+- **Scenario**: The only choice if future scalability requires handling ultra-large graphs with tens of thousands of nodes.
+
+### 4.3 Python - [Not Recommended]
+- **Cons**: Heavy dependencies, difficult distribution, too cumbersome for simple I/O tasks.
+
+## 5. Summary of Benefits
+- **Assetization**: Memory is source code—auditable and shareable.
+- **Zero Drift**: Physical isolation eliminates cross-project pollution.
+- **Determinism**: Structured data is better suited for high-precision coding decisions than vector databases.

package/docs/DESIGN_zh.md

@@ -0,0 +1,72 @@
+# n2n-memory 开发方案
+
+[English](./DESIGN.md)
+
+---
+
+## 1. 背景与目标
+解决全局 MCP Memory Server 导致的跨项目“记忆污染”与幻觉问题。通过将 AI 的认知碎片直接持久化在项目源码目录下，实现项目级的物理隔离与知识共享。
+
+本项目旨在开发一个高度简约、工具中立、且对版本管理友好的 N2N 记忆服务。
+
+## 2. 核心架构设计
+
+### 2.1 存储逻辑
+- **冷记忆位置**: `[项目根目录]/.mcp/memory.json`
+- **热上下文位置**: `[项目根目录]/.mcp/context.json`
+- **中立性**: 采用 `.mcp` 命名以脱离特定 AI 助手或 IDE 插件的品牌绑定。
+- **物理隔离**: 一个项目一个 `.mcp` 工作区，互不干扰，完全随项目代码同步。
+
+### 2.2 交互规范与安全性
+- **严格根目录校验**: 取消向上递归搜索。AI 必须在识别到的项目根目录或工作区顶级目录操作。
+- **强项目标记**: 初始化要求存在 `.git`、`package.json`、`tsconfig.json` 或语言构建文件等强标记。只有 README 的目录会被视为弱根目录并被拒绝。
+- **握手协议 (Handshake)**: 新项目初始化需显式确认 (`confirmNewProjectRoot`)，防止目录污染。
+- **路径边界**: 导出文件与生成文件必须保留在项目根目录内部。
+- **默认隐私日志**: 服务日志默认隐藏完整本地路径，仅在设置 `N2N_LOG_LEVEL=debug` 时输出完整路径。
+- **双缓冲架构 (Dual-Buffer)**:
+    - **热数据 (`context.json`)**: 存储高频更新的状态、任务、下一步计划。
+    - **冷数据 (`memory.json`)**: 存储结构化的长效知识图谱（实体与关系）。
+
+## 3. 数据结构与检索
+
+### 3.1 极简数据格式
+`memory.json` 内部**不包含**版本号、元数据、作者信息或时间戳。仅保留核心知识图谱数据（Entities & Relations），通过 Git 记录实现版本审计。
+
+`context.json` 是独立的热状态缓冲区，可包含 `activeTask`、`status`、`nextSteps`、`updatedAt` 等操作性字段，因为这些状态更新频繁，不属于长效知识图谱的数据契约。
+
+### 3.2 Git 友好型保存策略
+为确保 `git diff` 可读：
+1. **强制排序**: 对 `entities` 和 `relations` 执行字典序排序。
+2. **规范缩进**: 统一使用 2 空格缩进。
+3. **安全写入**: JSON 写入先落临时文件，再执行原子移动。
+
+已存在但无法读取的 JSON 文件会被视为数据完整性错误，而不是空记忆。这样可以避免损坏文件被新的空图谱意外覆盖。
+
+### 3.3 图谱完整性
+- **实体唯一性**: 实体名称是项目图谱内的稳定标识。
+- **关系完整性**: 关系必须指向已存在的实体，默认拒绝孤儿边。
+
+### 3.4 高效检索机制
+- **分页支持 (Limit/Offset)**: 针对超大型图谱，支持分批读取，确保 Token 消耗在可控范围。
+- **索引摘要模式**: 可选仅读取实体索引而不加载冗余的观测事实。
+- **精确节点检索**: 通过 `open_nodes` 精确获取高价值上下文。
+
+## 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,98 @@
+# n2n-memory Development Guide
+
+[中文版](./DEVELOPMENT_zh.md)
+
+---
+
+This guide documents the daily development, testing, and build processes for the N2N Memory MCP Server.
+
+## Development Environment
+- **Runtime**: Node.js v20+ (LTS recommended)
+- **Language**: TypeScript
+- **Package Manager**: npm
+
+## Common Commands
+
+### 1. Install Dependencies
+```bash
+npm install
+```
+
+### 2. Run Tests
+This project uses Vitest with global test APIs for unit testing.
+```bash
+npm test
+```
+
+### 3. Development Mode (Hot Reload)
+```bash
+npm run dev
+```
+
+### 4. Production Build
+Compiles TypeScript into native JavaScript (outputs to `build/` directory).
+```bash
+npm run build
+```
+
+### 5. Start Service
+```bash
+npm start
+```
+
+### 6. Full Local Check
+```bash
+npm run check
+```
+
+This runs linting, tests, TypeScript build, dependency audit, and `npm pack --dry-run`.
+
+## Core Architecture
+
+### Logical Layers
+1. **`index.ts`**: Server bootstrap. Creates the MCP server, registers handlers, connects stdio transport, and releases locks on shutdown.
+2. **`handlers/mcp-handlers.ts`**: MCP boundary. Parses Zod schemas, performs the project-root handshake, formats tool responses, and exposes resources.
+3. **`core/memory-service.ts`**: Business service. Coordinates graph/context operations, in-process mutexes, cross-process locks, cache refresh, search, merging, deletes, and relation integrity checks.
+4. **`core/memory-manager.ts`**: Storage repository. Handles JSON read/write, schema validation, graph normalization, atomic writes, Markdown export, and project-root output containment.
+5. **`tools/schemas.ts`**: MCP input schemas for each tool.
+6. **`types.ts`**: Stored data schemas and TypeScript types.
+
+### Storage Contract
+- `memory.json` stores durable graph data: entities, observations, and relations.
+- `context.json` stores hot task state: active task, status, reason, next steps, last commit, and server-managed `updatedAt`.
+- Missing storage files are treated as empty/default state.
+- Existing but unreadable storage files throw errors. This prevents corrupted data from being overwritten by an empty graph.
+- Export paths must be relative to the project root and cannot escape it.
+- Project root discovery requires strong markers such as `.git`, `.mcp`, `package.json`, `tsconfig.json`, or language-specific build files. README-only directories are rejected.
+- Full local paths are hidden from logs by default. Set `N2N_LOG_LEVEL=debug` for complete path diagnostics.
+
+### Key Algorithm: Git-Friendly Sorting
+Whenever the graph is written, `MemoryManager` normalizes a copy of the graph before persisting it:
+- Entities are sorted by name.
+- Observations are sorted inside each entity.
+- Relations are sorted by `from`, then `to`, then `relationType`.
+- JSON is written with 2-space indentation.
+
+This ensures that even if fragments are generated out of order, Git diffs remain stable and readable.
+
+### Concurrency and Cache Behavior
+- `MemoryService` uses one in-process `Mutex` per project for graph writes and a separate mutex for context writes.
+- `proper-lockfile` protects writes across processes.
+- Graph and context snapshots are cached by project path, but normal reads check file mtimes so external edits, Git pulls, or other MCP processes are observed.
+- Writes use a temporary JSON file followed by an atomic move.
+
+### Graph Integrity
+- Entity names are the stable identifiers within a project graph.
+- `n2n_create_relations` rejects relations whose `from` or `to` endpoint is missing.
+- Deleting entities also deletes relations attached to those entities.
+
+### CI and Publishing
+- Pull requests and pushes to `main` run `.github/workflows/ci.yml` on Node.js 20 and 22.
+- Tag pushes run `.github/workflows/publish.yml`, which executes `npm run check` before publishing.
+- `package.json` uses a `files` whitelist so npm packages contain only `build/`, `docs/`, `README.md`, `CHANGELOG.md`, and `LICENSE`.
+
+## Contribution Guidelines
+- All logic changes must be accompanied by corresponding unit tests.
+- Update `docs/DESIGN.md` before making changes to the storage structure.
+- Update `docs/API_REFERENCE.md` and `docs/API_REFERENCE_zh.md` when tool schemas or behavior change.
+- Run `npm run check` before publishing or opening a PR.

package/docs/DEVELOPMENT_zh.md

@@ -0,0 +1,98 @@
+# n2n-memory 开发指南
+
+[English](./DEVELOPMENT.md)
+
+---
+
+本手册记录了 N2N Memory MCP Server 的日常开发、测试及构建流程。
+
+## 开发环境
+- **Runtime**: Node.js v20+ (推荐 LTS 版本)
+- **Language**: TypeScript
+- **Package Manager**: npm
+
+## 常用指令
+
+### 1. 安装依赖
+```bash
+npm install
+```
+
+### 2. 运行测试
+本项目使用 Vitest 和全局测试 API 执行单元测试。
+```bash
+npm test
+```
+
+### 3. 开发模式 (热更新)
+```bash
+npm run dev
+```
+
+### 4. 生产构建
+将 TypeScript 编译为原生 JavaScript（输出到 `build/` 目录）。
+```bash
+npm run build
+```
+
+### 5. 启动服务
+```bash
+npm start
+```
+
+### 6. 完整本地检查
+```bash
+npm run check
+```
+
+该命令会依次执行 lint、测试、TypeScript 构建、依赖审计和 `npm pack --dry-run`。
+
+## 核心架构说明
+
+### 逻辑分层
+1. **`index.ts`**: 服务启动层。创建 MCP Server，注册 handlers，连接 stdio transport，并在关闭时释放锁。
+2. **`handlers/mcp-handlers.ts`**: MCP 边界层。解析 Zod Schema，执行项目根目录握手，格式化工具响应，并暴露资源。
+3. **`core/memory-service.ts`**: 业务服务层。负责编排图谱/上下文操作、进程内互斥锁、跨进程文件锁、缓存刷新、搜索、合并、删除和关系完整性校验。
+4. **`core/memory-manager.ts`**: 存储仓储层。负责 JSON 读写、Schema 校验、图谱规范化、原子写入、Markdown 导出和项目根目录输出边界。
+5. **`tools/schemas.ts`**: 每个 MCP 工具的输入 Schema。
+6. **`types.ts`**: 持久化数据 Schema 与 TypeScript 类型。
+
+### 存储契约
+- `memory.json` 存储长效图谱数据：实体、观测事实和关系。
+- `context.json` 存储热任务状态：当前任务、状态、原因、下一步、最近提交，以及服务自动维护的 `updatedAt`。
+- 存储文件不存在时视为空图谱或默认上下文。
+- 已存在但无法读取的存储文件会抛错，避免损坏数据被空图谱覆盖。
+- 导出路径必须是相对项目根目录的路径，且不能逃逸项目根目录。
+- 项目根目录识别要求存在 `.git`、`.mcp`、`package.json`、`tsconfig.json` 或语言构建文件等强标记。只有 README 的目录会被拒绝。
+- 日志默认隐藏完整本地路径。设置 `N2N_LOG_LEVEL=debug` 可输出完整路径用于诊断。
+
+### 关键算法：Git 友好排序
+每当写入图谱时，`MemoryManager` 会先规范化图谱副本：
+- 实体按名称排序。
+- 每个实体内的观测事实排序。
+- 关系按 `from`、`to`、`relationType` 依次排序。
+- JSON 统一使用 2 空格缩进。
+
+这样做的目的是保证即使 AI 乱序生成了记忆片段，存入 Git 的文件 diff 依然稳定且可读。
+
+### 并发与缓存行为
+- `MemoryService` 为每个项目的图谱写入维护一个进程内 `Mutex`，并为上下文写入维护独立 `Mutex`。
+- `proper-lockfile` 负责跨进程写入保护。
+- 图谱与上下文会按项目路径缓存 snapshot，但普通读取会检查文件 mtime，因此能够感知外部编辑、Git pull 或其他 MCP 进程的修改。
+- 写入 JSON 时先写临时文件，再执行原子移动。
+
+### 图谱完整性
+- 实体名称是项目图谱内的稳定标识。
+- `n2n_create_relations` 会拒绝 `from` 或 `to` 端点不存在的关系。
+- 删除实体时也会删除所有关联关系。
+
+### CI 与发布
+- Pull Request 和推送到 `main` 会通过 `.github/workflows/ci.yml` 在 Node.js 20 与 22 上运行检查。
+- 推送 tag 会触发 `.github/workflows/publish.yml`，发布前会执行 `npm run check`。
+- `package.json` 使用 `files` 白名单，npm 包只包含 `build/`、`docs/`、`README.md`、`CHANGELOG.md` 和 `LICENSE`。
+
+## 贡献指南
+- 所有的逻辑变更必须附带相应的单元测试。
+- 修改存储结构前，请先更新 `docs/DESIGN.md`。
+- 修改工具 Schema 或行为时，请同步更新 `docs/API_REFERENCE.md` 与 `docs/API_REFERENCE_zh.md`。
+- 发布或提交 PR 前请运行 `npm run check`。

package/docs/README_zh.md

@@ -0,0 +1,195 @@
+# n2n-memory
+
+面向 AI 编程代理的项目本地记忆 MCP Server。
+
+[![npm version](https://img.shields.io/npm/v/@datafrog-io/n2n-memory)](https://www.npmjs.com/package/@datafrog-io/n2n-memory)
+[![npm total downloads](https://img.shields.io/npm/dt/@datafrog-io/n2n-memory)](https://www.npmjs.com/package/@datafrog-io/n2n-memory)
+[![license](https://img.shields.io/github/license/n2ns/n2n-memory)](https://github.com/n2ns/n2n-memory/blob/main/LICENSE)
+[![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-blue)](https://modelcontextprotocol.io)
+[![node version](https://img.shields.io/node/v/@datafrog-io/n2n-memory)](https://nodejs.org)
+[![N2N Synthetics](https://datafrog.io/badges/n2n-synthetics.svg)](https://github.com/n2ns)
+[![DataFrog.io](https://datafrog.io/badges/datafrog.svg)](https://datafrog.io)
+
+[English](../README.md)
+
+---
+
+> **上下文即代码，记忆即资产。**
+
+n2n-memory 是一个开源、local-first 的 Model Context Protocol (MCP) 记忆服务，面向 AI 编程助手和 AI coding agents。它通过把长效项目知识存储在 `.mcp/memory.json`，把活跃任务上下文存储在 `.mcp/context.json`，避免跨项目记忆污染。
+
+### SEO 友好定位
+
+如果你在搜索：
+- AI 编码记忆
+- 项目级 MCP memory
+- coding agent 的本地上下文记忆
+- 适配 Claude/Cursor/VS Code 的仓库隔离记忆
+
+本项目聚焦于：可审计的 JSON、仓库隔离、以及可读的 Git diff。
+
+## n2n-memory 是什么？
+
+n2n-memory 为 AI 编程工具提供一个可通过 MCP 读写的项目本地知识图谱。它适合经常在多个仓库之间切换、希望记忆跟随代码仓库而不是跟随全局助手账户的开发者和团队。
+
+**快速摘要**
+- **安装**: `npx -y @datafrog-io/n2n-memory`
+- **协议**: Model Context Protocol (MCP)，stdio transport
+- **存储**: `.mcp/memory.json` 保存长效记忆，`.mcp/context.json` 保存活跃任务状态
+- **适合**: AI 编程助手记忆、项目架构笔记、团队共享上下文
+- **不适合**: 云同步、全局个人记忆、源码索引替代、向量数据库替代
+
+### 🌟 核心亮点
+- **项目级物理隔离**: 记忆与活跃上下文都存储在 `[项目根目录]/.mcp/` 下。
+- **Git 版本可控**: 自动对 JSON 数据进行字典序排序，生成清晰的 `git diff`。
+- **冷热双缓冲**: 长效知识图谱存储在 `memory.json`，高频任务状态存储在 `context.json`。
+- **工具中立**: 使用 `.mcp` 命名，不绑定任何特定 AI 品牌或 IDE 插件。
+- **知识资产化**: 记忆随代码走，团队成员拉取仓库即可共享 AI 对架构的理解。
+- **通用兼容**: 适配支持 stdio MCP Server 的 MCP 客户端与 AI 编程工具。
+- **隐私设计**: 隐私保护是核心原则，采用物理隔离确保数据安全。
+
+## 典型场景
+
+- 在 AI 编程会话开始时恢复项目上下文。
+- 保存架构决策、实现说明、踩坑记录和当前任务状态。
+- 通过 Git 与团队共享长效项目记忆。
+- 在多个客户项目、产品项目或开源项目之间工作时保持记忆隔离。
+- 不引入数据库或云服务，也能查询项目本地知识图谱。
+
+## 与其他方案的区别
+
+| 方案 | 适合场景 | 取舍 |
+| --- | --- | --- |
+| n2n-memory | 面向 AI 编程代理的项目本地 MCP 记忆 | 需要助手按工作流主动调用 MCP 工具 |
+| 全局 MCP memory | 跨聊天或跨项目的个人记忆 | 容易混入无关项目上下文 |
+| Markdown memory bank | 人类可读的项目笔记 | 对图谱查询和工具化更新不够结构化 |
+| 向量数据库记忆 | 大规模语义检索 | 基础设施更重，Git diff 不够确定 |
+| IDE 专属规则 | 在单个 IDE 中约束助手行为 | 跨 MCP 客户端的可移植性较弱 |
+
+### 🚀 快速配置
+
+#### 1. JSON 配置 (IDE / Claude Desktop)
+
+推荐使用 `npx` 模式直接运行：
+
+##### Claude Desktop
+配置文件路径: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "n2n-memory": {
+      "command": "npx",
+      "args": ["-y", "@datafrog-io/n2n-memory"]
+    }
+  }
+}
+```
+
+##### Cursor / VSCode (MCP 插件)
+在 MCP 设置面板中添加：
+- **Name**: `n2n-memory`
+- **Type**: `command`
+- **Command**: `npx -y @datafrog-io/n2n-memory`
+
+##### 其他 MCP 客户端
+- 本服务使用 stdio MCP 协议，可接入任何支持本地命令启动 MCP 的客户端。
+- 排查路径问题时，可在客户端环境中设置 `N2N_LOG_LEVEL=debug`。
+
+#### 2. 使用指南 (Usage Guide)
+
+本服务完全由路径驱动，AI 助手在调用工具时需要关注以下几点：
+
+1. **项目根目录绝对路径**: 调用任何 `n2n_*` 工具时，必须传入当前项目根目录或工作区顶级目录的**绝对路径**（`projectPath`）。
+2. **初始化握手**: 如果 `.mcp` 尚不存在，需要按服务返回的 `detectedRoot` 再次调用工具，并传入 `confirmNewProjectRoot`。
+3. **自动存储**: 长效记忆保存在 `[项目路径]/.mcp/memory.json`，活跃任务上下文保存在 `[项目路径]/.mcp/context.json`。
+4. **协作共享**: 建议在需要共享知识图谱时提交 `.mcp/memory.json`。是否提交 `context.json` 取决于团队是否希望共享当前任务状态。
+
+如果团队希望共享长效记忆，推荐使用以下 `.gitignore` 策略：
+
+```gitignore
+.mcp/context.json
+!.mcp/
+!.mcp/memory.json
+```
+
+如果项目记忆可能包含私有实现细节，请继续忽略整个 `.mcp/` 目录。
+
+##### 常用工具示例：
+- `n2n_add_entities`: 创建新实体。
+- `n2n_add_observations`: 追加观测事实。
+- `n2n_create_relations`: 在已存在实体之间建立联系。
+- `n2n_read_graph`: 读取项目图谱及活跃上下文（支持 `summaryMode` 及分页）。
+- `n2n_get_graph_summary`: 快速获取实体索引摘要（支持分页）。
+- `n2n_update_context`: 更新当前任务状态及后续计划。
+- `n2n_search`: 关键词或模糊搜索图谱（支持分页）。
+- `n2n_delete_entities`: 删除实体及其关联关系。
+- `n2n_delete_observations`: 删除实体中的指定观测事实。
+- `n2n_delete_relations`: 删除指定关系。
+- `n2n_open_nodes`: 按名称精确检索特定节点。
+- `n2n_export_markdown`: 将图谱导出为项目根目录内的 Markdown 文件。
+
+##### 安全说明：
+- 已存在但无法读取的 JSON 文件会被视为数据完整性错误，而不是空记忆。
+- 导出路径必须是相对路径，并且必须保留在项目根目录内部。
+- 指向不存在实体的关系会被拒绝。
+- 只有 README 的普通目录不会被识别为项目根目录；请使用 `.git`、`package.json` 或语言构建文件等真实项目标记。
+- 服务日志默认隐藏完整本地路径。排查路径问题时可设置 `N2N_LOG_LEVEL=debug`。
+
+### 🗺️ 未来蓝图
+- **语义搜索**: 集成极简向量嵌入 (Vector Embeddings)，实现模糊记忆检索。
+- **本体校验**: 可选的关系类型 Schema，确保知识图谱一致性。
+- **时间旅行**: 内存版本快照，支持误操作回滚。
+
+## 安全与治理说明
+
+- `n2n_delete_entities`、`n2n_delete_observations`、`n2n_delete_relations` 会修改或清理持久化记忆，请结合 CI 或人工流程进行保护。
+- 默认建议将 `context.json` 保持未提交；只有在需要共享活跃任务状态时再提交。
+- 遵循 [SECURITY.md](../SECURITY.md) 的安全问题提交流程。
+
+### 搜索歧义说明
+
+`n2n-memory` 与网络层 `n2n` 工具链无关，核心是面向 AI 代码助手的 MCP 记忆服务。
+
+## FAQ
+
+### n2n-memory 是向量数据库吗？
+
+不是。n2n-memory 存储的是确定性的 JSON 知识图谱。未来可能加入语义检索，但核心设计是结构化、Git 友好的项目记忆。
+
+### 应该提交 `.mcp/memory.json` 吗？
+
+当知识图谱对团队有价值时，可以提交 `.mcp/memory.json`。如果其中可能包含私有实现细节，则应继续忽略。`context.json` 是活跃任务状态，通常更适合保持未提交。
+
+### n2n-memory 会把数据发送到云端吗？
+
+不会。n2n-memory 是本地 MCP server，只读写项目目录下的文件。
+
+### 它和全局 memory 有什么不同？
+
+全局 memory 跟随助手或用户账号，容易跨项目混用。n2n-memory 跟随代码仓库，让不同项目的记忆保持隔离。
+
+### 它能和 Claude Desktop、Cursor、VS Code 一起用吗？
+
+可以，只要客户端支持 stdio MCP server。本 README 提供了 Claude Desktop 和 Cursor / VS Code MCP 配置示例。
+
+### 和全局 memory 有什么不同？
+
+不是同一类。它按仓库作用域隔离记忆，适合多个项目切换的团队场景。
+
+---
+
+## 📖 相关文档
+
+- **[设计方案](./DESIGN_zh.md)**: 为什么需要项目级隔离？
+- **[API 参考手册](./API_REFERENCE_zh.md)**: 工具描述和 Schema。
+- **[开发指南](./DEVELOPMENT_zh.md)**: 如何构建、测试和扩展。
+- **[变更日志](./CHANGELOG_zh.md)**: 版本演进与故障记录。
+- **[llms.txt](../llms.txt)**: 面向 AI 编程代理和回答引擎的简短项目摘要。
+
+## 📄 许可证
+本项目采用 [MIT 许可证](../LICENSE)。
+
+---
+
+Built by N2NS Lab, the open-source lab from Datafrog, focused on practical AI developer tools.

package/llms.txt

@@ -0,0 +1,83 @@
+# n2n-memory
+
+> Project-local MCP memory server for AI coding agents.
+
+n2n-memory is an open-source Model Context Protocol (MCP) server that stores AI coding memory inside each project repository. It prevents cross-project memory pollution by keeping durable project knowledge in `.mcp/memory.json` and active task context in `.mcp/context.json`.
+
+## Search intent coverage
+
+- AI coding memory server
+- project-local memory graph
+- MCP server for AI coding agents
+- local-first context storage
+- repository-scoped memory for Claude/Cursor/VS Code
+
+## What it is
+
+- A local-first MCP memory server for AI coding assistants.
+- A Git-friendly project knowledge graph stored as JSON.
+- A tool-agnostic memory layer for Claude Desktop, Cursor, VS Code MCP clients, and other stdio MCP-compatible tools.
+- A practical AI developer tool built for multi-project software development.
+
+## Use cases
+
+- Restore project context at the start of an AI coding session.
+- Preserve architecture decisions, implementation notes, pitfalls, and active task state.
+- Share durable AI project memory with a team through Git.
+- Avoid memory pollution from global AI assistant memory stores.
+- Query a project-local knowledge graph through MCP tools.
+
+## Not for
+
+- Cloud memory synchronization.
+- Global personal memory across unrelated projects.
+- Replacing source code search, static analysis, or repository maps.
+- Replacing a vector database or semantic retrieval platform.
+
+## Disambiguation
+
+This project is an MCP memory server. It is not related to any network/VPN software named `n2n`.
+
+## Storage model
+
+- `.mcp/memory.json`: durable knowledge graph with entities, observations, and relations.
+- `.mcp/context.json`: hot task context with active task, status, next steps, and update time.
+- Existing unreadable JSON files are treated as data integrity errors.
+- Exported files must stay inside the project root.
+
+## Install
+
+```bash
+npx -y @datafrog-io/n2n-memory
+```
+
+## Primary MCP tools
+
+- `n2n_read_graph`
+- `n2n_get_graph_summary`
+- `n2n_add_entities`
+- `n2n_add_observations`
+- `n2n_create_relations`
+- `n2n_update_context`
+- `n2n_search`
+- `n2n_open_nodes`
+- `n2n_delete_entities`
+- `n2n_delete_observations`
+- `n2n_delete_relations`
+- `n2n_export_markdown`
+
+## Key docs
+
+- `README.md`: overview, setup, workflow, FAQ.
+- `docs/API_REFERENCE.md`: full MCP tool reference.
+- `docs/DESIGN.md`: architecture and storage design.
+- `docs/DEVELOPMENT.md`: development, testing, CI, publishing.
+- `CHANGELOG.md`: release history.
+
+## Package and repository
+
+- npm: `@datafrog-io/n2n-memory`
+- GitHub: `https://github.com/n2ns/n2n-memory`
+- License: MIT
+
+Built by N2NS Lab, the open-source lab from Datafrog, focused on practical AI developer tools.