@datafrog-io/n2n-memory 1.2.1 → 1.2.2

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`。
+
+说明：
+
+- 绝对路径会被拒绝。
+- 试图逃逸项目根目录的相对路径会被拒绝。

package/docs/CHANGELOG_zh.md

@@ -0,0 +1,108 @@
+# 变更日志 (Changelog)
+
+[English](../CHANGELOG.md)
+
+---
+
+本项目的所有重大变更都将记录在此文件中。
+
+## [未发布]
+
+### 修复 (Fixed)
+- 普通读取现在会在底层 `.mcp` 文件变化时刷新已缓存的图谱/上下文 snapshot。
+- 已存在但无法读取的 `memory.json` 或 `context.json` 现在会抛出数据完整性错误，不再被当成空状态。
+- `n2n_create_relations` 现在会拒绝指向不存在实体的关系。
+- `n2n_export_markdown` 现在会拒绝绝对输出路径，以及试图逃逸项目根目录的相对路径。
+- `projectPath` 校验现在会在路径解析前拒绝相对路径。
+- 生产依赖与开发依赖审计现在均可达到 0 漏洞。
+
+### 变更 (Changed)
+- 明确 `projectPath` 必须指向项目根目录或工作区顶级目录。
+- 将 JSON 存储写入收敛到共享的原子写入路径，并在持久化前规范化图谱副本。
+- 测试框架从 Mocha 切换到 Vitest，以保持开发依赖树干净。
+- 工具发现现在会暴露由 Zod Schema 生成的具体 JSON 输入 Schema。
+- 只有 README 的目录会被视为弱根目录，并在项目识别时被拒绝。
+- 服务日志默认隐藏完整本地路径，除非设置 `N2N_LOG_LEVEL=debug`。
+- 更新英文与中文文档，反映当前工具集、存储契约、路径边界和图谱完整性行为。
+
+### 新增 (Added)
+- 新增用于 PR 和 `main` 分支推送的 GitHub CI workflow。
+- 发布 workflow 现在会在 `npm publish` 前运行完整检查。
+- 新增 npm 包 `files` 白名单和更完整的 package metadata。
+- 新增开源治理文件：贡献指南、安全策略、行为准则、issue 模板和 PR 模板。
+
+## [1.2.1] - 2026-01-12
+
+### 新增 (Added)
+- **结构化 JSON 工具响应**：
+  - 将工具响应从纯文本升级为结构化 JSON。
+  - 新增 `status`、`message` 和 `_protocol` 元数据字段，提高机器可读性。
+- **动态 N2N-SYNC 协议提醒**：
+  - 自动向 `nextSteps` 注入 `[N2N-SYNC]` 协议提醒。
+  - 在工具元数据中嵌入协议提示，引导 AI 助手形成更好的同步习惯。
+- **基于相似度的观察去重**：
+  - 新增 `similarity.ts` 工具模块，包含 Jaccard 相似度、Levenshtein 编辑距离和包含检测算法。
+  - `addEntities()` 和 `addObservations()` 现在使用智能去重替代精确匹配的 `Set` 去重。
+  - 检测到重复时自动保留更详细（更长）的观察记录。
+  - 防止 "version 2.4.1" 和 "version 2.4.1 is the current release" 等冗余条目同时存在。
+
+- **支持模糊搜索与相关度排序**：
+  - `n2n_search` 工具现默认支持模糊匹配。
+  - 新增可选参数：`fuzzy`（布尔值）和 `minScore`（0-1 阈值）。
+  - 搜索结果按相关度评分排序（最相关的在前）。
+  - 通过 Levenshtein 相似度处理拼写错误。
+  - 支持词级别的部分匹配和基于 Jaccard 指数的语义相似度。
+
+- **新增单元测试**：
+  - 为所有相似度函数新增完整测试套件 (`similarity.test.ts`)。
+  - 共 99 个测试全部通过。
+
+## [1.1.0] - 2024-12-19
+
+### 新增 (Added)
+- 双语 README 支持：分为 `README.md`（英文）和 `docs/README_zh.md`（中文）。
+- 初始化 `CHANGELOG.md` 以追踪项目演进和技术发现。
+- **全文档双语化**：包括 API 参考、设计方案和开发指南，均已实现中英双语关联。
+- **基础设施强化**：
+  - 更新 `package.json` 中的 `engines` 字段，要求 Node.js >= 20 和 npm >= 10（与 MCP SDK 保持一致）。
+  - 在 MCP Server 启动时增加了环境检查逻辑，主动提醒版本不匹配风险。
+- **依赖维护**：
+  - 将所有依赖项升级至最新的稳定版本（包括 `sinon`, `typescript`, `eslint` 等）。
+  - 验证当前依赖为 0 漏洞且全部为最新。
+- **高可靠架构演进**：
+  - 实现了 **双缓存服务 (Dual-Buffer Service)**：
+    - **Snapshot Buffer**：内存级快照，提供瞬时读取响应。
+    - **Write Queue**：串行写入队列，并集成 `proper-lockfile` 解决多进程冲突。
+  - **原子化持久化**：采用临时文件交换（Atomic Rename）机制，确保 JSON 文件完整性。
+  - **AI 引导路径定位**：优化工具描述，通过 AI 助手主动报告项目路径实现“启动即加载”。
+- **模块化重构与 SDK 现代化 (Clean Architecture & Modernization)**：
+  - 迁移至最新的 `@modelcontextprotocol/sdk` 高级 `McpServer` API。
+  - 彻底解决了 `Server` 类被弃用的警告 (TS6385)。
+  - 将庞大的 `index.ts` 按照功能拆分为清晰的目录结构：
+    - `/core`：核心领域逻辑（MemoryService, MemoryManager）。
+    - `/tools`：工具元数据定义与 Zod Schema 校验。
+    - `/handlers`：通过 `registerAll` 实现纯粹的请求分发。
+    - `/utils`：环境检查等系统工具。
+    - **冷热数据分离 (Project Context)**：
+      - 引入 `context.json` 专门存储高频变动的“热状态”（当前任务、状态、后续步骤）。
+      - 将架构级的“冷知识”隔离在 `memory.json` 中，减少数据污染。
+      - 为 `context.json` 配置了独立的物理锁 (`proper-lockfile`) 和内存互斥锁 (`Mutex`)。
+      - 新增工具 `n2n_update_context` 并集成了强制性的 Git 同步协议。
+      - `n2n_read_graph` 现在支持“一站式读取”，同时返回知识图谱与当前上下文。
+    - **N2N-SYNC 协议强制约束**：
+      - 在 MCP 工具元数据中硬编码了强制性的同步约束。
+      - 会话启动（`n2n_read_graph`）现在会自动绑定 AI 执行“Git 提交前更新记忆”的策略。
+      - 在所有写入工具中增加了 `[MANDATORY PROTOCOL]` 和 `[HARD CONSTRAINT]` 标签，有效防止重构过程中的上下文漂移。
+  - 优化了测试套件兼容性，修复了模块化后的路径引用问题。
+
+### 修复 (Fixed)
+- **NPM 发布兼容性**：识别并记录了 Trusted Publishing (OIDC) 的要求。
+  - **发现**：NPM CLI 10.x 版本在 OIDC 发布时可能存在问题。
+  - **建议**：使用 Node.js 20+ LTS 配合 npm 10+ 以确保发布稳定性。
+
+## [1.0.0] - 2024-12-19 之前
+
+### 新增 (Added)
+- 项目本地记忆隔离的核心 MCP 功能。
+- 认知碎片持久化于 `[项目根目录]/.mcp/memory.json`。
+- 工具集：`n2n_add_entities`, `n2n_add_observations`, `n2n_create_relations`, `n2n_read_graph`, `n2n_search`。