# https://github.com/danielsimonjr/memory-mcp 项目说明书
生成时间：2026-05-16 08:51:38 UTC
## 目录
- [项目介绍](#page-introduction)
- [快速开始](#page-quick-start)
- [系统架构](#page-architecture)
- [数据流处理](#page-data-flow)
- [实体与关系模型](#page-entities-relations)
- [存储后端](#page-storage-backends)
- [层级嵌套](#page-hierarchical-nesting)
- [搜索能力](#page-search-capabilities)
- [高级功能](#page-advanced-features)
- [工具参考手册](#page-tool-reference)
## 项目介绍
### 相关页面
相关主题：[系统架构](#page-architecture), [快速开始](#page-quick-start)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/danielsimonjr/memory-mcp/blob/main/README.md)
- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
- [CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)
- [package.json](https://github.com/danielsimonjr/memory-mcp/blob/main/package.json)
- [src/index.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/index.ts)
- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)
- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)
# 项目介绍
## 概述
Memory MCP 是一个基于 **Model Context Protocol (MCP)** 的增强型记忆管理服务器，通过 MCP 协议为 AI 代理提供持久化记忆能力。该项目作为 MCP 服务器运行，封装了 `@danielsimonjr/memoryjs` 核心库的所有功能，向 AI 代理暴露 213 个工具函数，覆盖 58 个功能类别。资料来源：[README.md](https://github.com/danielsimonjr/memory-mcp/blob/main/README.md)
### 核心定位
Memory MCP 的设计目标是为 AI 代理提供类似于人类记忆的长期记忆存储与检索能力。通过知识图谱结构，代理可以：
- **持久化存储** - 将重要信息写入长期记忆
- **智能检索** - 根据语义、关键词、时间等多种维度检索记忆
- **层级管理** - 支持父子关系的层级记忆结构
- **衰减机制** - 自动对低价值记忆进行时间衰减
- **协同推理** - 支持多代理协作式的记忆综合分析
资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
## 技术架构
### 分层架构设计
Memory MCP 采用清晰的分层架构，核心层由 `memoryjs` 库提供，MCP 层负责协议适配与工具暴露。
```mermaid
graph TD
subgraph "Memory MCP (本项目)"
A[src/index.ts] --> B[MCPServer]
B --> C[toolDefinitions.ts]
B --> D[toolHandlers.ts]
C --> D
end
subgraph "@danielsimonjr/memoryjs"
E[ManagerContext] --> F[EntityManager]
E --> G[RelationManager]
E --> H[ObservationManager]
E --> I[SearchManager]
E --> J[TagManager]
E --> K[HierarchyManager]
E --> L[CompressionManager]
E --> M[AnalyticsManager]
E --> N[GraphStorage]
end
D --> E
```
资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
### ManagerContext 核心组件
`ManagerContext` 是 memoryjs 库的核心类，采用懒加载模式初始化所有管理器实例。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
| 管理器组件 | 访问方式 | 功能说明 |
|-----------|---------|---------|
| EntityManager | `ctx.entityManager` | 图节点（实体）的增删改查 |
| RelationManager | `ctx.relationManager` | 有向边管理，连接实体间关系 |
| ObservationManager | `ctx.observationManager` | 附加到实体的观察事实，支持归一化 |
| SearchManager | `ctx.searchManager` | 基础搜索、布尔搜索、模糊搜索 |
| TagManager | `ctx.tagManager` | 标签管理与重要性评分 |
| HierarchyManager | `ctx.hierarchyManager` | 父子树结构与子树遍历 |
| AnalyticsManager | `ctx.analyticsManager` | 图统计与完整性验证 |
| CompressionManager | `ctx.compressionManager` | 去重、合并、自动压缩、归档 |
| ArchiveManager | `ctx.archiveManager` | 记忆归档管理 |
| IOManager | `ctx.ioManager` | 数据导入导出 |
| SemanticSearch | `ctx.semanticSearch` | OpenAI 或本地模型的语义搜索 |
| RankedSearch | `ctx.rankedSearch` | TF-IDF 排序搜索 |
### 向后兼容性
`src/index.ts` 将 `ManagerContext` 重新导出为 `KnowledgeGraphManager` 别名，同时导出核心类型定义，确保与旧版 API 的兼容性。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
## 工具体系
### 工具分类总览
Memory MCP 提供 213 个工具函数，覆盖 58 个功能类别。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
| 类别 | 工具数量 | 核心功能 |
|------|---------|---------|
| Entity | 4 | 图节点的创建、读取、更新、删除 |
| Relation | 2 | 实体间的有向边管理 |
| Observation | 3 | 附加事实的增删改查，支持归一化 |
| Search | 7 | 基础搜索、排序搜索、布尔搜索、模糊搜索、自动选择 |
| Intelligent Search | 3 | 混合多层搜索、查询分析、基于反思的搜索 |
| Semantic Search | 3 | 通过 OpenAI 或本地模型的嵌入相似度搜索 |
| Saved Searches | 5 | 存储和重新执行常用查询 |
| Tag Management | 6 | 标签管理、批量操作、重要性评分 |
| Tag Aliases | 5 | 标签同义词/别名管理 |
| Hierarchy | 9 | 父子树结构、子树遍历 |
| Graph Algorithms | 4 | BFS/DFS 路径查找、中心性、连通分量 |
| Analytics | 2 | 图统计和完整性验证 |
| Compression | 4 | 去重检测、合并、自动压缩、归档 |
| Import/Export | 2 | 7 种导出格式 |
### 工具处理流程
```mermaid
sequenceDiagram
participant MCP as MCP 客户端
participant Server as MCPServer
participant Handler as toolHandlers.ts
participant Manager as ManagerContext
MCP->>Server: 工具调用请求
Server->>Handler: 路由到对应 handler
Handler->>Manager: 调用 ManagerContext 方法
Manager->>Manager: 执行业务逻辑
Manager-->>Handler: 返回结果
Handler-->>Server: 格式化响应
Server-->>MCP: MCP 格式响应
```
资料来源：[src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)
## 存储方案
### 存储类型
Memory MCP 支持两种存储后端，数据文件位于**项目根目录**（非 `dist/` 目录）。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
| 存储类型 | 文件 | 环境变量 |
|---------|------|---------|
| JSONL (默认) | `memory.jsonl`, `memory-saved-searches.jsonl`, `memory-tag-aliases.jsonl` | - |
| SQLite | `memory.db` | `MEMORY_STORAGE_TYPE=sqlite` |
### 数据迁移工具
`tools/migrate-from-jsonl-to-sqlite` 目录提供了独立的迁移工具，支持 JSONL 与 SQLite 格式之间的双向转换。资料来源：[tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts)
```bash
# 基本用法
migrate-from-jsonl-to-sqlite --from --to
# 显示详细进度
migrate-from-jsonl-to-sqlite --from memory.jsonl --to memory.db --verbose
```
## 依赖管理
### 核心依赖
| 依赖包 | 版本 | 用途 |
|-------|------|------|
| @modelcontextprotocol/sdk | ^1.0.0 | MCP 协议实现 |
| @danielsimonjr/memoryjs | ^2.1.0 | 核心记忆管理库 |
| zod | ^3.23.8 | Schema 验证 |
| better-sqlite3 | ^11.7.0 | SQLite 存储后端 |
### 开发依赖
| 依赖包 | 版本 | 用途 |
|-------|------|------|
| typescript | ^5.7.0 | TypeScript 编译 |
| @types/node | ^22.0.0 | Node.js 类型定义 |
| vitest | ^2.0.0 | 单元测试框架 |
## 版本演进
### 版本历史要点
| 阶段 | 版本 | 主要内容 |
|------|------|---------|
| Phase 13 | 初始版本 | 仅保留 5 个 TypeScript 源文件，核心逻辑移至 memoryjs |
| Phase 15 | v12.2.0 | 新增 23 个工具，暴露 memoryjs v1.14+ 功能 |
| Phase 16 | v12.3.0 | 新增 53 个工具，暴露 memoryjs v2.1.0 功能 |
Phase 16 (v12.3.0) 新增的功能包括：排除规则 (5)、决策理由与 ADR markdown 双写 (10)、结构化项目上下文 (12)、启发式指南 (10)、工具能力与观察管道 (11)、观察去重 (2)、拼写纠正 (3)。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
## 安装与使用
### npm 包信息
```bash
# 安装
npm install @danielsimonjr/memory-mcp
# 或使用最新版本
npm install @danielsimonjr/memory-mcp@latest
```
资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
### 构建与发布
项目使用 `prepare` 脚本在安装时自动构建，因此发布前无需单独执行构建命令。资料来源：[CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)
```bash
# 发布到 npm
# 需要具有绕过 2FA 权限的 token
npm config set //registry.npmjs.org/:_authToken=$(cat ~/.npm_token)
npm publish --access public
# 发布前验证 tarball 内容
npm pack --dry-run
```
## 独立工具集
`tools/` 目录包含可独立运行的工具，每个工具拥有自己的 `package.json`，可通过 `pkg` 编译为 Windows 可执行文件。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
| 工具目录 | 用途 |
|---------|------|
| `chunking-for-files` | 将大文件拆分为小块以适应上下文限制 |
| `compress-for-context` | CTON 压缩以适应 LLM 上下文窗口 |
| `create-dependency-graph` | 生成 TypeScript 项目依赖图 |
| `migrate-from-jsonl-to-sqlite` | JSONL 与 SQLite 格式转换 |
## 开发指南
### 代码规范
- 遵循 TypeScript 最佳实践
- 使用有意义的变量命名
- 为公共方法添加 JSDoc 注释
- 保持函数专注于小而简洁
- 统一使用 2 空格缩进
### 测试要求
- 全面测试新功能
- 包含边界情况测试
- 测试向后兼容性
- 验证导出格式有效性
- 测试空图和大图场景
### 提交流程
1. **创建功能分支**: `git checkout -b feature/your-feature-name`
2. **提交更改**: `git add . && git commit -m "Description"`
3. **推送并创建 PR**: `git push origin feature/your-feature-name`
4. PR 应包含：标题、描述、测试结果、文档更新、向后兼容性确认
资料来源：[CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)
## 配置选项
### 环境变量
| 环境变量 | 说明 | 默认值 |
|---------|------|-------|
| `MEMORY_STORAGE_TYPE` | 存储类型选择 | `jsonl` |
| `MEMORY_DB_PATH` | SQLite 数据库路径 | `memory.db` |
### TypeScript 配置
- 编译目标: ES2022
- 模块解析: Node16
## 相关资源
- **npm 包**: [@danielsimonjr/memory-mcp](https://www.npmjs.com/package/@danielsimonjr/memory-mcp)
- **核心库**: [@danielsimonjr/memoryjs](https://www.npmjs.com/package/@danielsimonjr/memoryjs)
- **MCP 协议**: [Model Context Protocol](https://modelcontextprotocol.io/)
- **社区指南**: [MCP Community Guidelines](https://modelcontextprotocol.io/community/communication)
---
## 快速开始
### 相关页面
相关主题：[项目介绍](#page-introduction)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/danielsimonjr/memory-mcp/blob/main/README.md)
- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
- [CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)
- [src/index.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/index.ts)
- [src/server/MCPServer.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/MCPServer.ts)
# 快速开始
本文档帮助你在 5 分钟内完成 memory-mcp 的安装、配置和首次使用。
## 项目概述
memory-mcp 是一个基于 Model Context Protocol (MCP) 的知识图谱记忆管理服务器。它为 AI 助手提供持久化记忆存储、语义搜索和层次化组织能力。
**核心依赖：**
- **npm 包**：`@danielsimonjr/memory-mcp`
- **核心库**：`@danielsimonjr/memoryjs`
- **协议层**：Model Context Protocol
- **存储后端**：JSONL 文件或 SQLite 数据库
资料来源：[README.md:1-15]()
## 系统架构
```
┌─────────────────────────────────────────────────────────────┐
│ memory-mcp (本仓库) │
├─────────────────────────────────────────────────────────────┤
│ src/index.ts │ 入口文件，导出公共 API │
│ src/server/MCPServer │ MCP 服务器实现 │
│ src/server/toolDefs │ 工具定义 (213 个工具，58 个类别) │
│ src/server/toolHandlers│ 工具处理逻辑 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ @danielsimonjr/memoryjs (npm 依赖) │
├─────────────────────────────────────────────────────────────┤
│ ManagerContext │ 懒加载管理器上下文 │
│ EntityManager │ 实体/节点管理 │
│ RelationManager │ 关系/边管理 │
│ SearchManager │ 搜索管理 │
│ IOManager │ 导入/导出管理 │
│ GraphStorage/SQLiteStorage │ 图存储/SQLite 存储后端 │
└─────────────────────────────────────────────────────────────┘
```
资料来源：[CLAUDE.md:1-30]()
## 前置要求
| 要求 | 最低版本 | 说明 |
|------|----------|------|
| Node.js | 18.0.0 | 推荐使用 LTS 版本 |
| npm | 9.0.0 | 用于安装依赖 |
| 操作系统 | Windows/macOS/Linux | 跨平台支持 |
| 磁盘空间 | 50MB | 基础安装占用 |
## 安装步骤
### 1. 全局安装
```bash
npm install -g @danielsimonjr/memory-mcp
```
### 2. 验证安装
安装完成后，系统会创建以下组件：
| 组件 | 位置 | 说明 |
|------|------|------|
| 构建产物 | `dist/index.js` | 编译后的入口文件 |
| CLI 二进制文件 | `mcp-server-memory` | 命令行工具 |
| 源码入口 | `src/index.ts` | TypeScript 源码 |
安装过程中 `prepare` 脚本会自动运行 `npm run build` 进行构建。 资料来源：[CLAUDE.md:40-45]()
## 存储配置
memory-mcp 支持两种存储后端，在项目根目录创建配置文件即可：
### JSONL 存储（默认）
默认使用 JSONL 格式存储，数据文件位于**项目根目录**（不是 `dist/`）：
```
├── memory.jsonl # 主记忆数据
├── memory-saved-searches.jsonl # 保存的搜索
├── memory-tag-aliases.jsonl # 标签别名
└── memory.db # (可选) SQLite 数据库
```
### SQLite 存储
设置环境变量切换到 SQLite 存储：
```bash
export MEMORY_STORAGE_TYPE=sqlite
```
使用 SQLite 时，所有数据存储在 `memory.db` 文件中。 资料来源：[CLAUDE.md:30-35]()
## 工具类别总览
memory-mcp 提供 **213 个工具**，分为 **58 个类别**：
| 类别 | 工具数量 | 核心功能 |
|------|----------|----------|
| 实体 (Entity) | 4 | 图节点的基础增删改查 |
| 关系 (Relation) | 2 | 实体间的有向边管理 |
| 观察 (Observation) | 3 | 附加到实体的属性和事实 |
| 搜索 (Search) | 7 | 基础、布尔、模糊搜索 |
| 智能搜索 (Intelligent Search) | 3 | 混合多层、查询分析 |
| 语义搜索 (Semantic Search) | 3 | OpenAI 或本地模型嵌入 |
| 标签管理 (Tag Management) | 6 | 标签及重要性评分 |
| 层级管理 (Hierarchy) | 9 | 父子树和子树遍历 |
| 图算法 (Graph Algorithms) | 4 | BFS/DFS、中心性计算 |
| 分析 (Analytics) | 2 | 图统计和完整性验证 |
| 压缩 (Compression) | 4 | 去重、合并、自动压缩 |
| 导入/导出 (Import/Export) | 2 | 7 种导出格式 |
资料来源：[CLAUDE.md:15-25]()
## 首次使用
### 1. 启动服务器
在支持 MCP 的客户端（如 Claude Desktop）中配置服务器连接。服务器通过 Model Context Protocol 暴露所有工具。
### 2. 创建第一个实体
使用 `create_entity` 工具创建记忆节点：
```
工具：create_entity
参数：
- name: "我的第一个记忆"
- entityType: "memory"
```
### 3. 添加观察数据
使用 `create_observation` 为实体添加属性：
```
工具：create_observation
参数：
- entityName: "我的第一个记忆"
- content: "这是一个测试记忆"
- importance: 0.8
```
### 4. 执行搜索
使用 `search` 或 `semantic_search` 查找记忆：
```
工具：search
参数：
- query: "测试"
- limit: 10
```
## 数据流图
```mermaid
graph TD
A[用户请求] --> B[MCP 客户端]
B --> C[MCPServer]
C --> D[ToolHandlers]
D --> E[memoryjs ManagerContext]
E --> F{存储类型判断}
F -->|JSONL| G[GraphStorage]
F -->|SQLite| H[SQLiteStorage]
G --> I[memory.jsonl]
H --> J[memory.db]
J --> K[结果返回]
I --> K
K --> C
C --> B
B --> L[用户响应]
```
## 常见操作示例
### 层级组织
创建实体间的父子关系：
```
工具：set_entity_parent
参数：
- entityName: "项目A"
- parentName: "工作"
```
### 标签管理
为实体添加标签：
```
工具：add_tag
参数：
- entityName: "项目A"
- tag: "重要"
- importance: 0.9
```
### 导入导出
导出记忆为指定格式：
```
工具：export_graph
参数：
- format: "json"
- includeObservations: true
```
## 开发指南
如果你想为 memory-mcp 做贡献：
```bash
# 克隆仓库
cd c:/mcp-servers/memory-mcp
# 创建功能分支
git checkout -b feature/your-feature-name
# 安装依赖
npm install
# 编写代码，遵循以下规范：
# - TypeScript 最佳实践
# - 使用有意义的变量名
# - 为公共方法添加 JSDoc 注释
# - 保持函数小而专注
# - 使用 2 空格缩进
# 运行类型检查
npm run typecheck
# 提交更改
git add .
git commit -m "Description of your changes"
# 推送并创建 PR
git push origin feature/your-feature-name
```
资料来源：[CONTRIBUTING.md:1-25]()
## 独立工具
`tools/` 目录包含独立工具，每个都有独立的 `package.json`：
| 工具 | 用途 |
|------|------|
| `chunking-for-files` | 拆分/合并大文件以适应上下文限制 |
| `compress-for-context` | CTON 压缩以适应 LLM 上下文窗口 |
| `create-dependency-graph` | 生成 TypeScript 项目依赖图 |
| `migrate-from-jsonl-to-sqlite` | 在 JSONL 和 SQLite 格式间转换 |
资料来源：[CLAUDE.md:50-55]()
## 下一步
- 阅读 [架构文档](./ARCHITECTURE.md) 深入了解系统设计
- 查看 [工具参考](./TOOLS.md) 完整工具列表
- 参考 [迁移指南](./MIGRATION.md) 从旧版本升级
---
## 系统架构
### 相关页面
相关主题：[项目介绍](#page-introduction), [数据流处理](#page-data-flow), [实体与关系模型](#page-entities-relations)
相关源码文件
以下源码文件用于生成本页说明：
- [src/index.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/index.ts)
- [src/server/MCPServer.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/MCPServer.ts)
- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)
- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)
- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
- [tools/create-dependency-graph/create-dependency-graph.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/create-dependency-graph/create-dependency-graph.ts)
# 系统架构
## 概述
memory-mcp 是一个基于 Model Context Protocol (MCP) 的知识图谱管理服务器，为 AI 代理提供持久化记忆能力。该项目采用分层架构设计，核心逻辑委托给 `@danielsimonjr/memoryjs` 库处理，而本仓库专注于 MCP 协议适配层、工具定义和请求处理。
**核心职责：**
- 将 memoryjs 的知识图谱能力暴露为 MCP 工具（当前版本共 213 个工具，覆盖 58 个类别）
- 处理 MCP 协议的请求/响应生命周期
- 提供多格式存储支持（JSONL 和 SQLite）
- 支持语义搜索、嵌入向量、权限控制等高级功能
资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
---
## 架构分层
### 整体架构图
```mermaid
graph TB
subgraph "MCP 客户端层"
CLIENT[AI 代理 / Claude Desktop]
end
subgraph "memory-mcp 服务层"
INDEX[src/index.ts
入口点]
SERVER[MCPServer.ts
服务器核心]
TOOL_DEFS[toolDefinitions.ts
工具定义]
HANDLERS[toolHandlers.ts
工具处理器]
end
subgraph "memoryjs 核心库"
CTX[ManagerContext
管理器上下文]
EM[EntityManager]
RM[RelationManager]
SM[SearchManager]
IOM[IOManager]
STORAGE[(GraphStorage
存储层)]
end
subgraph "存储层"
JSONL[(memory.jsonl)]
SQLITE[(memory.db)]
end
CLIENT <--> INDEX
INDEX --> SERVER
SERVER --> TOOL_DEFS
SERVER --> HANDLERS
HANDLERS <--> CTX
CTX --> EM
CTX --> RM
CTX --> SM
CTX --> IOM
CTX --> STORAGE
STORAGE --> JSONL
STORAGE --> SQLITE
```
### 层级说明
| 层级 | 组件 | 职责 | 资料来源 |
|------|------|------|----------|
| **协议层** | MCP 客户端 | 与 AI 代理通信，发送 JSON-RPC 请求 | — |
| **适配层** | `MCPServer.ts` | 初始化服务器、注册工具、处理 MCP 生命周期 | [MCPServer.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/MCPServer.ts) |
| **定义层** | `toolDefinitions.ts` | 定义每个工具的输入模式（Zod schema） | [toolDefinitions.ts:1-50](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts) |
| **处理层** | `toolHandlers.ts` | 实现工具业务逻辑，调用 memoryjs | [toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts) |
| **核心层** | `memoryjs` | 管理器上下文、图谱操作、搜索算法 | [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md) |
| **存储层** | GraphStorage | 多格式数据持久化 | — |
资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
---
## 核心组件详解
### 1. 入口点 (src/index.ts)
`src/index.ts` 是整个应用的入口文件，负责导出核心类型和初始化逻辑。
**主要导出：**
```typescript
// ManagerContext 作为 KnowledgeGraphManager 别名导出
export { ManagerContext as KnowledgeGraphManager } from '@danielsimonjr/memoryjs';
// 核心类型重导出
export type { Entity, Relation, Observation, SearchResult } from '@danielsimonjr/memoryjs';
```
该模块采用延迟初始化模式，仅在需要时才创建 ManagerContext 实例，以优化冷启动性能。
资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
### 2. 服务器核心 (MCPServer.ts)
`MCPServer.ts` 是 MCP 服务器的核心实现，负责：
- 初始化 MCP 服务器实例
- 注册所有工具定义
- 绑定工具处理器到对应工具
- 处理请求生命周期
**架构特点：**
```mermaid
sequenceDiagram
participant CLIENT as MCP 客户端
participant SERVER as MCPServer
participant HANDLER as ToolHandler
participant MEMORYJS as memoryjs
CLIENT->>SERVER: JSON-RPC 请求
SERVER->>SERVER: 解析工具名称和参数
SERVER->>HANDLER: 调用对应处理器
HANDLER->>MEMORYJS: 调用 ManagerContext 方法
MEMORYJS-->>HANDLER: 返回结果
HANDLER-->>SERVER: 格式化响应
SERVER-->>CLIENT: JSON-RPC 响应
```
### 3. 工具定义 (toolDefinitions.ts)
`toolDefinitions.ts` 使用 JSON Schema 风格的定义来描述每个 MCP 工具的接口。
**工具类别统计：**
| 类别 | 工具数量 | 主要功能 |
|------|----------|----------|
| Entity | 4 | 图谱节点 CRUD |
| Relation | 2 | 有向边管理 |
| Observation | 3 | 实体事实附加 |
| Search | 7 | 基础/排名/模糊搜索 |
| Intelligent Search | 3 | 混合多层搜索 |
| Semantic Search | 3 | 嵌入向量相似度 |
| Saved Searches | 5 | 搜索存储与重执行 |
| Tag Management | 6 | 标签和重要性评分 |
| Hierarchy | 9 | 父子树遍历 |
| Graph Algorithms | 4 | BFS/DFS/中心性 |
| Analytics | 2 | 图谱统计 |
| Compression | 4 | 去重和压缩 |
资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
**工具定义结构示例：**
```typescript
{
name: 'compress_for_context',
description: '使用 CTON 格式压缩文本以适应 LLM 上下文窗口',
inputSchema: {
type: 'object',
properties: {
text: { type: 'string', description: '要压缩的文本' },
level: {
type: 'string',
enum: ['light', 'medium', 'aggressive'],
description: '压缩级别'
},
},
required: ['text'],
},
}
```
资料来源：[toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)
### 4. 工具处理器 (toolHandlers.ts)
`toolHandlers.ts` 是工具的业务逻辑实现层，采用注册表模式管理所有处理函数。
**处理器模式：**
```typescript
// 典型处理器结构
工具名称: async (ctx, args) => {
// 1. 参数验证（使用 Zod schema）
const validatedArg = validateWithSchema(args.param, z.string(), '错误信息');
// 2. 调用 memoryjs 管理器方法
const result = await getManager(ctx).someMethod(validatedArg);
// 3. 格式化响应
return formatToolResponse(result);
}
```
**关键处理器示例：**
| 处理器 | 功能 | 调用管理器 |
|--------|------|----------|
| `create_artifact` | 创建工具输出工件 | `getArtifactManager()` |
| `get_artifact` | 获取工件引用 | `getArtifactManager()` |
| `set_governance_policy` | 设置权限策略 | `getGovernance()` |
| `audit_query` | 查询审计日志 | `getAuditLog()` |
| `run_decay_cycle` | 运行重要性衰减 | 核心引擎 |
资料来源：[toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)
---
## ManagerContext 管理器上下文
`ManagerContext` 是与 memoryjs 核心库交互的主要接口，提供对各功能管理器的访问。
### 可用管理器
```mermaid
graph LR
CTX[ManagerContext] --> EM[EntityManager]
CTX --> RM[RelationManager]
CTX --> OM[ObservationManager]
CTX --> SM[SearchManager]
CTX --> TM[TagManager]
CTX --> HM[HierarchyManager]
CTX --> AM[AnalyticsManager]
CTX --> CM[CompressionManager]
CTX --> IOM[IOManager]
CTX --> GT[GraphTraversal]
CTX --> SS[SemanticSearch]
CTX --> RS[RankedSearch]
CTX --> ST[(Storage)]
```
### 管理器功能表
| 管理器 | 方法 | 功能描述 |
|--------|------|----------|
| **EntityManager** | `create`, `get`, `update`, `delete`, `merge` | 图谱节点操作 |
| **RelationManager** | `create`, `get`, `delete` | 有向边管理 |
| **ObservationManager** | `add`, `get`, `normalize` | 实体事实附加 |
| **SearchManager** | `basic`, `ranked`, `boolean`, `fuzzy` | 多种搜索模式 |
| **SemanticSearch** | `similarity`, `hybrid` | 嵌入向量搜索 |
| **TagManager** | `add`, `remove`, `bulk`, `score` | 标签管理 |
| **HierarchyManager** | `parent`, `children`, `subtree` | 层级结构遍历 |
| **AuditLog** | `query`, `record` | 操作审计 |
资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
---
## 存储架构
### 存储类型
memory-mcp 支持两种存储后端，通过环境变量 `MEMORY_STORAGE_TYPE` 切换：
| 存储类型 | 文件 | 配置值 | 适用场景 |
|----------|------|--------|----------|
| **JSONL** | `memory.jsonl` | `jsonl` | 小规模数据、开发环境 |
| **SQLite** | `memory.db` | `sqlite` | 生产环境、大规模数据 |
### 数据文件位置
数据文件位于**项目根目录**（而非 `dist/` 构建目录）：
```
project-root/
├── memory.jsonl # JSONL 存储
├── memory-saved-searches.jsonl # 保存的搜索
├── memory-tag-aliases.jsonl # 标签别名
├── memory.db # SQLite 数据库
├── dist/ # 构建输出
│ └── index.js
└── src/ # 源代码
└── index.ts
```
### 存储层抽象
```mermaid
graph TB
subgraph "应用层"
HANDLERS[工具处理器]
end
subgraph "存储抽象层"
GS[GraphStorage]
end
subgraph "后端实现"
JSONL[JSONLStorage]
SQLITE[SQLiteStorage]
end
HANDLERS --> GS
GS --> JSONL
GS --> SQLITE
```
---
## 工具处理流程
### 完整请求生命周期
```mermaid
sequenceDiagram
participant CLI as MCP 客户端
participant SERVER as MCPServer
participant DEF as ToolDefinitions
participant HANDLER as ToolHandler
participant CTX as ManagerContext
participant DB as 存储层
CLI->>SERVER: list_tools 请求
SERVER->>DEF: 获取所有工具定义
DEF-->>SERVER: 返回工具 schema 数组
SERVER-->>CLI: 工具列表
CLI->>SERVER: call_tool 请求
SERVER->>HANDLER: 分派到对应处理器
HANDLER->>HANDLER: 参数验证
HANDLER->>CTX: 调用管理器方法
CTX->>DB: 持久化操作
DB-->>CTX: 返回数据
CTX-->>HANDLER: 业务结果
HANDLER-->>SERVER: 格式化响应
SERVER-->>CLI: JSON-RPC 响应
```
### 参数验证模式
所有工具处理器统一使用 Zod 进行参数验证：
```typescript
// 标准验证模式
const validated = validateWithSchema(
args.paramName, // 待验证值
z.string().min(1), // Zod schema
'错误提示信息' // 验证失败消息
);
// 枚举验证
z.enum(['option1', 'option2', 'option3']);
// 数字范围验证
z.number().int().min(1).max(1000);
```
资料来源：[toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)
---
## 独立工具集
除 MCP 服务器外，`tools/` 目录还包含独立的命令行工具：
### 工具列表
| 工具 | 文件 | 功能 |
|------|------|------|
| **chunking-for-files** | `chunking-for-files.ts` | 将大文件拆分为可编辑的区块 |
| **compress-for-context** | `compress-for-context.ts` | CTON 格式压缩以适应 LLM 上下文 |
| **create-dependency-graph** | `create-dependency-graph.ts` | 生成 TypeScript 项目依赖图 |
| **migrate-from-jsonl-to-sqlite** | `migrate-from-jsonl-to-sqlite.ts` | JSONL 与 SQLite 格式互转 |
### 独立工具架构
```mermaid
graph LR
subgraph "tools/ 目录"
CHUNK[chunking-for-files]
COMPRESS[compress-for-context]
DEPS[create-dependency-graph]
MIGRATE[migrate-from-jsonl-to-sqlite]
end
CHUNK --> FS[文件系统]
COMPRESS --> FS
DEPS --> TS[TypeScript AST]
MIGRATE --> JSONL[JSONL 解析]
MIGRATE --> SQL[SQLite]
```
资料来源：[tools/create-dependency-graph/create-dependency-graph.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/create-dependency-graph/create-dependency-graph.ts)
---
## 环境配置
### 配置变量表
| 变量名 | 描述 | 默认值 | 资料来源 |
|--------|------|--------|----------|
| `MEMORY_FILE_PATH` | 存储文件路径 | `memory.jsonl` | [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md) |
| `MEMORY_STORAGE_TYPE` | 存储类型 | `jsonl` | 同上 |
| `MEMORY_EMBEDDING_PROVIDER` | 嵌入提供商 | `none` | 同上 |
| `MEMORY_OPENAI_API_KEY` | OpenAI API 密钥 | — | 同上 |
| `MEMORY_EMBEDDING_MODEL` | 嵌入模型名 | `text-embedding-3-small` | 同上 |
| `MEMORY_AUTO_INDEX_EMBEDDINGS` | 创建时自动索引 | `false` | 同上 |
---
## 编译与发布
### 构建输出
| 输出物 | 路径 | 说明 |
|--------|------|------|
| **构建产物** | `dist/index.js` | TypeScript 编译输出 |
| **CLI 二进制** | `mcp-server-memory` | package.json 中定义 |
### 发布流程
```bash
# 1. 设置 npm token
npm config set //registry.npmjs.org/:_authToken=$(cat c:\mcp-servers\npm_key.txt)
# 2. 发布（prepare 脚本会自动构建）
npm publish --access public
# 3. 验证 tarball 内容
npm pack --dry-run 2>&1 | grep -E "jsonl|\.db|total files|package size"
```
**注意：** 发布前必须更新 `package.json` 中的版本号，npm 不会重新发布相同版本。
资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
---
## 版本演进
| 版本 | 阶段 | 主要内容 |
|------|------|----------|
| **v12.3.0** (最新) | Phase 16 | 53 个新工具：排除规则、ADR 双写、结构化上下文、启发式指南、工具调用观察管道、拼写纠正 |
| **v12.2.0** | Phase 15 | 23 个工具：双时间有效性、OCC、RBAC、程序记忆、主动检索、因果推理、世界模型 |
| **v2.1.0** | — | memoryjs 核心库升级 |
---
## 扩展指南
### 添加新工具流程
```mermaid
graph LR
A[定义 schema] --> B[添加处理器]
B --> C[添加 e2e 测试]
C --> D[更新文档]
subgraph "步骤 1"
A[toolDefinitions.ts]
end
subgraph "步骤 2"
B[toolHandlers.ts]
end
subgraph "步骤 3"
C[tests/e2e/tools/]
end
```
1. **定义 Schema**：在 `toolDefinitions.ts` 相应类别区域添加 JSON Schema
2. **实现处理器**：在 `toolHandlers.ts` 注册表中添加处理函数
3. **编写测试**：在 `tests/e2e/tools/` 添加端到端测试
### 处理器最佳实践
- 使用 `validateWithSchema()` 进行参数验证
- 大响应使用 `withCompression()` 包装
- 返回 `formatToolResponse()` 或 `formatTextResponse()`
资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
---
## 总结
memory-mcp 采用清晰的**分层架构**：
1. **协议适配层**处理 MCP 通信
2. **工具定义层**声明接口契约
3. **处理层**实现业务逻辑
4. **核心库层**执行图谱操作
5. **存储层**管理数据持久化
这种设计使得核心图谱逻辑与 MCP 协议解耦，便于独立演进和测试。通过 213 个精心设计的工具，AI 代理能够高效地存储、检索和管理持久化记忆。
---
## 数据流处理
### 相关页面
相关主题：[系统架构](#page-architecture), [存储后端](#page-storage-backends), [工具参考手册](#page-tool-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)
- [src/server/responseCompressor.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/responseCompressor.ts)
- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
- [CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)
- [tools/compress-for-context/compress-for-context.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/compress-for-context/compress-for-context.ts)
# 数据流处理
## 概述
数据流处理是 memory-mcp 架构的核心机制，负责将 MCP（Model Context Protocol）工具调用转化为底层知识图谱操作，并确保大规模响应的有效传输。该系统采用分层架构，上层为 MCP 服务器，下层为核心库 `@danielsimonjr/memoryjs`，两者通过 `ManagerContext` 进行解耦通信。
**核心职责：**
- 接收并验证工具调用参数
- 路由至对应的 Manager 处理器
- 管理知识图谱实体的 CRUD 操作
- 对超过 256KB 的大规模响应自动压缩
- 支持多种存储后端（JSONL / SQLite）
资料来源：[CLAUDE.md:1-5]()
## 系统架构
### 分层架构图
```mermaid
graph TD
subgraph "memory-mcp (本仓库)"
A["src/index.ts
入口点"] --> B["MCPServer.ts
MCP服务器"]
B --> C["toolHandlers.ts
工具处理器"]
C --> D["responseCompressor.ts
响应压缩器"]
end
subgraph "@danielsimonjr/memoryjs (npm依赖)"
E["ManagerContext
管理器上下文"]
E --> F["EntityManager
实体管理器"]
E --> G["RelationManager
关系管理器"]
E --> H["SearchManager
搜索管理器"]
E --> I["ObservationManager
观察管理器"]
E --> J["IOManager
IO管理器"]
end
D --> E
F --> K["GraphStorage
图存储"]
G --> K
H --> K
I --> K
J --> K
K --> L["JSONL / SQLite
存储后端"]
```
资料来源：[CLAUDE.md:10-18]()
### 组件职责表
| 组件 | 文件位置 | 职责 |
|------|----------|------|
| 入口点 | `src/index.ts` | 初始化 MCP 服务器，导出 ManagerContext 别名 |
| MCP 服务器 | `src/server/MCPServer.ts` | 处理协议握手、工具定义分发 |
| 工具处理器 | `src/server/toolHandlers.ts` | 工具业务逻辑、参数验证、响应格式化 |
| 响应压缩器 | `src/server/responseCompressor.ts` | 检测并压缩大规模响应 |
| ManagerContext | memoryjs 内部 | 懒加载初始化所有管理器实例 |
资料来源：[CLAUDE.md:22-25]()
## 工具处理流程
### 标准处理管道
```mermaid
sequenceDiagram
participant Client as MCP客户端
participant Server as MCPServer
participant Handler as toolHandlers
participant Compressor as withCompression
participant Manager as ManagerContext
participant Storage as GraphStorage
Client->>Server: 工具调用请求
Server->>Handler: 路由至对应handler
Handler->>Handler: 参数验证 (zod schemas)
Handler->>Handler: 数据预处理
Handler->>Manager: 调用manager方法
Manager->>Storage: 持久化/查询
Storage-->>Manager: 返回结果
Manager-->>Handler: 格式化响应
Handler->>Compressor: 包装响应
Compressor->>Compressor: 检查大小 >256KB?
alt 响应过大
Compressor->>Compressor: CTON压缩
Compressor-->>Server: 压缩后的JSON
else 响应正常
Compressor-->>Server: 原始响应
end
Server-->>Client: ToolResponse
```
### 工具处理器模式
所有工具处理器遵循统一模式：`参数验证 → 调用管理器 → 格式化响应` 资料来源：[CLAUDE.md:33-34]()
```typescript
// 标准处理器示例 - create_artifact
create_artifact: async (ctx, args) => {
// 1. 参数验证
const content = validateWithSchema(args.content, z.string().min(1), 'Invalid content');
const toolName = validateWithSchema(args.toolName, z.string().min(1), 'Invalid toolName');
const artifactType = validateWithSchema(
args.artifactType,
z.enum(['tool_output', 'code_snippet', 'api_response', 'search_result', 'file_content', 'user_input']),
'Invalid artifactType'
);
// 2. 调用管理器
const artifact = await getArtifactManager(ctx).createArtifact({
content,
toolName,
artifactType,
description: args.description,
sessionId: args.sessionId,
});
// 3. 格式化响应
return formatToolResponse(artifact);
},
```
资料来源：[src/server/toolHandlers.ts:1-25]()
### 参数验证机制
系统使用 `zod` 进行参数模式验证，支持类型约束和错误消息自定义：
```typescript
function validateWithSchema(
value: unknown,
schema: z.ZodType,
errorMessage: string
): T
```
验证失败时抛出错误，中断处理流程。 资料来源：[src/server/toolHandlers.ts:3-5]()
### 过滤参数验证
对于可选的过滤参数，采用宽松验证策略——单个无效字段不会导致整个请求失败，而是使用管理器默认值：
```typescript
function parseObservationDedupFilter(args: Record): {
entityType?: string | string[];
projectId?: string;
sessionId?: string;
minOccurrences?: number;
maxGroups?: number;
}
```
资料来源：[src/server/toolHandlers.ts:85-93]()
## 响应压缩机制
### 压缩触发条件
| 条件 | 阈值 | 处理方式 |
|------|------|----------|
| 文本响应大小 | > 256KB | CTON 压缩 |
| 非文本响应 | 任何大小 | 直接返回 |
资料来源：[src/server/toolHandlers.ts:95-97]()
### 压缩工作流
```mermaid
graph TD
A["handler返回ToolResponse"] --> B{"textContent?.type
=== 'text'?"}
B -->|是| C{"text.length
> 256KB?"}
B -->|否| Z["直接返回原始响应"]
C -->|是| D["maybeCompressResponse"]
C -->|否| Z
D --> E{"compressed?"}
E -->|是| F["包装为JSON.stringify
{compressed: true, data}"]
E -->|否| Z
F --> G["返回压缩后的响应"]
Z --> H["返回给客户端"]
G --> H
```
### 压缩配置参数
| 参数 | 类型 | 说明 |
|------|------|------|
| `MEMORY_AUTO_INDEX_EMBEDDINGS` | boolean | 实体创建时自动索引嵌入向量 |
| `MEMORY_EMBEDDING_PROVIDER` | `openai` \| `local` \| `none` | 嵌入向量生成提供者 |
| `MEMORY_EMBEDDING_MODEL` | string | 嵌入模型名称 |
资料来源：[CLAUDE.md:42-48]()
## 存储层数据流
### 存储类型支持
| 存储类型 | 默认路径 | 环境变量 |
|----------|----------|----------|
| JSONL | `memory.jsonl` | `MEMORY_STORAGE_TYPE=jsonl` |
| SQLite | `memory.db` | `MEMORY_STORAGE_TYPE=sqlite` |
存储文件位于**项目根目录**，而非 `dist/` 构建目录。 资料来源：[CLAUDE.md:54-56]()
### 数据流层级
```mermaid
graph LR
subgraph "访问接口层"
A["ManagerContext
入口"]
end
subgraph "管理器层"
B["EntityManager"]
C["RelationManager"]
D["SearchManager"]
E["ObservationManager"]
F["TagManager"]
G["HierarchyManager"]
end
subgraph "存储抽象层"
H["GraphStorage
统一接口"]
end
subgraph "存储实现层"
I["JSONLStorage"]
J["SQLiteStorage"]
end
A --> B
A --> C
A --> D
A --> E
A --> F
A --> G
B --> H
C --> H
D --> H
E --> H
F --> H
G --> H
H --> I
H --> J
```
### 可用管理器接口
`ManagerContext` 提供以下管理器访问：
| 管理器 | 访问方式 | 主要功能 |
|--------|----------|----------|
| 实体管理 | `ctx.entityManager` | 创建、读取、更新、删除图节点 |
| 关系管理 | `ctx.relationManager` | 管理有向边 |
| 观察管理 | `ctx.observationManager` | 附加到实体的观察/事实 |
| 搜索管理 | `ctx.searchManager` | 基础和高级搜索 |
| 标签管理 | `ctx.tagManager` | 标签 CRUD 和批量操作 |
| 层级管理 | `ctx.hierarchyManager` | 父子树结构 |
| 分析管理 | `ctx.analyticsManager` | 图统计和完整性验证 |
| 压缩管理 | `ctx.compressionManager` | 去重和自动压缩 |
| IO 管理 | `ctx.ioManager` | 导入导出操作 |
| 图遍历 | `ctx.graphTraversal` | BFS/DFS 路径查找 |
| 语义搜索 | `ctx.semanticSearch` | 嵌入相似度搜索 |
| 排名搜索 | `ctx.rankedSearch` | TF-IDF 排名搜索 |
| 存储 | `ctx.storage` | 直接访问 GraphStorage |
资料来源：[CLAUDE.md:25-30]()
## 工具分类数据流
### 按功能分类的处理器组
系统包含 **213 个工具**，分布在 **58 个类别**中：
| 类别 | 数量 | 数据流特点 |
|------|------|------------|
| Entity | 4 | 直接写入存储，可能触发自动嵌入索引 |
| Relation | 2 | 边创建涉及关系完整性验证 |
| Observation | 3 | 支持规范化处理和去重检测 |
| Search | 7 | 查询密集型，结果可能超过 256KB 阈值 |
| Semantic Search | 3 | 嵌入向量计算，延迟较高 |
| Import/Export | 2 | IO 密集型，大文件处理 |
| Compression | 4 | 涉及存储重写和数据压缩 |
资料来源：[CLAUDE.md:31-46]()
### 大数据量工具处理
以下工具因可能返回无界结果集而被标记为需要压缩处理：
| 工具名 | 潜在问题 |
|--------|----------|
| `read_graph` | 全图数据可能极大 |
| `search_nodes` | 匹配结果无明确上界 |
| `get_subtree` | 子树深度不可预测 |
| `open_nodes` | 展开节点可能指数增长 |
资料来源：[src/server/toolHandlers.ts:98-101]()
## 响应格式化
### 格式化函数
系统提供两种响应格式化函数：
```typescript
// 结构化响应 - 用于成功操作的 JSON 结构
function formatToolResponse(data: unknown): ToolResponse
// 文本响应 - 用于简单消息或未找到结果
function formatTextResponse(message: string): ToolResponse
```
### ToolResponse 结构
```typescript
interface ToolResponse {
content: Array<{
type: 'text';
text: string | CompressedPayload;
}>;
}
interface CompressedPayload {
compressed: true;
originalSize: number;
compressedSize: number;
algorithm: 'cton';
data: string;
}
```
资料来源：[src/server/toolHandlers.ts:108-120]()
## 独立压缩工具
除了 MCP 服务器内置的压缩机制，项目还提供独立的命令行压缩工具 `compress-for-context`： 资料来源：[tools/compress-for-context/compress-for-context.ts:1-50]()
### 功能特性
| 功能 | 说明 |
|------|------|
| 批量压缩 | 支持批量处理多个文件 |
| 递归压缩 | 可递归处理子目录 |
| 格式支持 | JSON、YAML、Markdown、CSV、TSV、Text、Log、TypeScript、JavaScript、XML、HTML |
| 压缩级别 | light（轻度）、medium（中度）、aggressive（激进） |
| 解压缩 | 支持从 `.compact` 文件恢复原始内容 |
### 命令行用法
```bash
# 单文件压缩
node compress-for-context.js data.json
node compress-for-context.js README.md -l aggressive
# 批量递归压缩
node compress-for-context.js -b -r -p "*.md" ./docs
# 预览压缩（不写入文件）
node compress-for-context.js log.txt --dry-run
# 解压缩
node compress-for-context.js -d data.json.compact
```
资料来源：[tools/compress-for-context/compress-for-context.ts:15-40]()
## 数据迁移工具
### JSONL 与 SQLite 互转
独立工具 `migrate-from-jsonl-to-sqlite` 支持存储格式间的迁移：
```bash
migrate-from-jsonl-to-sqlite --from --to [--verbose]
```
使用 `better-sqlite3` 实现原生 SQLite 性能。 资料来源：[tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts:1-30]()
## 测试覆盖
### 测试统计
| 指标 | 数值 |
|------|------|
| 测试文件数 | 26 |
| 测试用例数 | ~665 |
| 语句覆盖率 | 80.7% |
| 行覆盖率 | 81.4% |
| 函数覆盖率 | 79% |
资料来源：[CLAUDE.md:58-59]()
### 数据流相关测试
新增工具应按以下流程添加测试：
1. 在 `tests/e2e/tools/` 目录添加端到端测试
2. 测试空图和大图场景
3. 验证导出格式正确性
4. 验证压缩机制触发条件
资料来源：[CONTRIBUTING.md:25-30]()
## 扩展新工具数据流
### 添加新工具的标准流程
```mermaid
graph TD
A["定义工具schema"] --> B["添加handler函数"]
B --> C["注册到handler映射表"]
C --> D["添加端到端测试"]
D --> E["更新文档"]
subgraph "步骤1: toolDefinitions.ts"
A
end
subgraph "步骤2: toolHandlers.ts"
B
end
subgraph "步骤3: 注册"
C
end
```
### Handler 注册模式
```typescript
// 在 toolHandlers.ts 中
export const toolHandlers = {
[TOOL_NAME]: async (ctx, args) => {
// 1. 参数验证
// 2. 调用 manager
// 3. 格式化响应
},
};
```
资料来源：[CLAUDE.md:33-37]()
## 最佳实践
### 性能优化建议
| 场景 | 建议 |
|------|------|
| 大结果集查询 | 使用分页参数限制返回量 |
| 频繁搜索 | 利用 `saved_searches` 缓存查询 |
| 批量操作 | 优先使用 bulk API 而非循环单条 |
| 嵌入搜索 | 设置 `MEMORY_AUTO_INDEX_EMBEDDINGS=true` |
### 错误处理
- 参数验证失败：抛出包含具体字段名的错误
- 存储操作失败：向上传递错误，不做静默处理
- 网络相关：内存 MCP 无外部网络依赖，此项不适用
### 压缩策略选择
| 压缩级别 | 适用场景 |
|----------|----------|
| light | 需要保留可读性的配置文件、日志 |
| medium | 日常开发文档和中等复杂度数据（默认） |
| aggressive | 传输给 LLM 的上下文、极限压缩场景 |
资料来源：[tools/compress-for-context/compress-for-context.ts:18-22]()
---
*最后更新：基于 v12.3.0 版本*
---
## 实体与关系模型
### 相关页面
相关主题：[系统架构](#page-architecture), [存储后端](#page-storage-backends), [层级嵌套](#page-hierarchical-nesting)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)
- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)
- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
- [CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)
# 实体与关系模型
memory-mcp 是一个基于 Model Context Protocol 的记忆管理服务器，其核心数据模型采用**属性图模型（Property Graph Model）**。系统以实体（Entity）作为图节点，以关系（Relation）作为有向边，通过观察（Observation）附加事实信息，构建具有语义关联的知识图谱。
资料来源：[CLAUDE.md:1-10]()
## 1. 架构概述
memory-mcp 的实体与关系模型构建在 `@danielsimonjr/memoryjs` 库之上，通过分层架构提供服务能力。
```mermaid
graph TD
subgraph "memory-mcp (本仓库)"
A[MCPServer] --> B[toolHandlers]
B --> C[ManagerContext]
C --> D[memoryjs 核心库]
end
subgraph "@danielsimonjr/memoryjs"
E[EntityManager]
F[RelationManager]
G[ObservationManager]
H[GraphStorage]
end
C --> E
C --> F
C --> G
H --> I[(SQLite/JSONL)]
D --> E
D --> F
D --> G
D --> H
```
### 1.1 核心管理器
| 管理器 | 职责 | 存储后端 |
|--------|------|----------|
| EntityManager | 实体 CRUD 操作 | GraphStorage |
| RelationManager | 关系创建、查询、删除 | GraphStorage |
| ObservationManager | 观察事实的添加与检索 | GraphStorage |
| SearchManager | 全文与语义搜索 | 索引层 |
| TagManager | 标签分类管理 | GraphStorage |
| HierarchyManager | 层级结构管理 | GraphStorage |
资料来源：[CLAUDE.md:18-28]()
## 2. 实体模型
实体是知识图谱中的核心节点，代表现实世界中的概念对象。
### 2.1 实体数据结构
```typescript
interface Entity {
id: string; // 唯一标识符（UUID）
name: string; // 实体名称
entityType?: string; // 实体类型（如 "person", "project"）
observations: string[]; // 关联的观察 ID 列表
tags: string[]; // 标签数组
metadata?: Record; // 扩展元数据
importance?: number; // 重要性评分 (0-10)
createdAt: string; // ISO 时间戳
updatedAt: string; // ISO 时间戳
archived?: boolean; // 归档状态
}
```
### 2.2 实体操作工具
| 工具名称 | 功能 | 核心参数 |
|----------|------|----------|
| create_entity | 创建新实体 | name, entityType, metadata, tags |
| get_entity | 获取实体详情 | name 或 id |
| update_entity | 更新实体属性 | name/id, updates |
| delete_entity | 删除实体 | name 或 id |
| list_entities | 列出实体 | filter, limit, offset |
| merge_entities | 合并实体 | sourceIds, targetName |
| archive_entities | 批量归档 | filter |
资料来源：[src/server/toolDefinitions.ts:1-150]()
### 2.3 实体创建示例
```typescript
// 工具调用示例：create_entity
{
name: "create_entity",
arguments: {
name: "Alice Developer",
entityType: "person",
metadata: {
role: "software_engineer",
company: "TechCorp"
},
tags: ["developer", "ai-expert"],
importance: 8
}
}
```
## 3. 关系模型
关系是有向边，连接两个实体并携带语义信息。
### 3.1 关系数据结构
```typescript
interface Relation {
id: string; // 唯一标识符
from: string; // 源实体 ID 或名称
to: string; // 目标实体 ID 或名称
relationType: string; // 关系类型（如 "works_for", "knows"）
metadata?: Record; // 关系属性
bidirectional?: boolean; // 是否双向关系
createdAt: string;
}
```
### 3.2 关系类型示例
| 关系类型 | 语义 | 示例 |
|----------|------|------|
| works_for | 雇佣关系 | Alice → TechCorp |
| knows | 社交关系 | Alice → Bob |
| created | 创建关系 | Alice → ProjectX |
| depends_on | 依赖关系 | ModuleA → ModuleB |
| part_of | 包含关系 | Chapter1 → Book |
### 3.3 关系操作工具
| 工具名称 | 功能 | 核心参数 |
|----------|------|----------|
| create_relation | 创建关系 | from, to, relationType, bidirectional |
| get_relation | 获取关系 | from, to, relationType |
| delete_relation | 删除关系 | from, to, relationType |
| list_relations | 列出关系 | filter, entityName, limit |
资料来源：[src/server/toolHandlers.ts:1-100]()
## 4. 观察模型
观察（Observation）是附加在实体上的事实片段，是知识图谱的信息载体。
### 4.1 观察数据结构
```typescript
interface Observation {
id: string; // 唯一标识符
entityId: string; // 关联实体
content: string; // 事实内容
normalizedContent?: string; // 规范化后的内容
source?: string; // 信息来源
importance?: number; // 重要性评分
tags?: string[]; // 观察标签
metadata?: Record;
createdAt: string;
updatedAt: string;
}
```
### 4.2 观察操作工具
| 工具名称 | 功能 | 核心参数 |
|----------|------|----------|
| create_observation | 添加观察 | entityName/id, content, source, tags |
| get_observations | 获取观察 | entityName/id, limit |
| update_observation | 更新观察 | observationId, updates |
| delete_observation | 删除观察 | observationId |
| normalize_observation | 规范化文本 | observationId |
| create_observation_ref | 创建观察引用 | observationId, entityName, relationType |
资料来源：[src/server/toolDefinitions.ts:200-350]()
### 4.3 观察流程图
```mermaid
graph LR
A[实体] -->|关联| B[观察]
B -->|内容| C[规范化处理]
C -->|索引| D[SearchManager]
D -->|检索| E[全文搜索]
D -->|检索| F[语义搜索]
B --> G[重要性评分]
G --> H[衰减引擎]
H --> I[遗忘决策]
```
## 5. 存储模型
### 5.1 存储类型
memory-mcp 支持两种存储后端，通过环境变量 `MEMORY_STORAGE_TYPE` 配置。
| 存储类型 | 环境变量 | 文件位置 | 适用场景 |
|----------|----------|----------|----------|
| JSONL | `MEMORY_STORAGE_TYPE=jsonl` | memory.jsonl | 小规模数据、开发测试 |
| SQLite | `MEMORY_STORAGE_TYPE=sqlite` | memory.db | 生产环境、大规模数据 |
资料来源：[CLAUDE.md:50-55]()
### 5.2 数据文件
```bash
# 项目根目录下的数据文件
memory.jsonl # 主数据（JSONL 格式）
memory-saved-searches.jsonl # 保存的搜索查询
memory-tag-aliases.jsonl # 标签别名映射
memory.db # SQLite 数据库
```
### 5.3 环境变量配置
| 变量名 | 描述 | 默认值 |
|--------|------|--------|
| MEMORY_FILE_PATH | 存储文件路径 | memory.jsonl |
| MEMORY_STORAGE_TYPE | 存储类型 | jsonl |
| MEMORY_EMBEDDING_PROVIDER | 向量化 provider | none |
| MEMORY_OPENAI_API_KEY | OpenAI API 密钥 | — |
| MEMORY_EMBEDDING_MODEL | 向量化模型 | text-embedding-3-small |
| MEMORY_AUTO_INDEX_EMBEDDINGS | 自动索引嵌入 | false |
资料来源：[CLAUDE.md:45-49]()
## 6. 图遍历与算法
### 6.1 图遍历管理器
`ctx.graphTraversal` 提供图结构遍历能力：
```typescript
// 可用的遍历方法
ctx.graphTraversal.bfs(from, to); // 广度优先搜索
ctx.graphTraversal.dfs(from, to); // 深度优先搜索
ctx.graphTraversal.findPath(from, to); // 最短路径
ctx.graphTraversal.findAllPaths(from, to); // 所有路径
```
### 6.2 图算法工具
| 工具名称 | 功能 | 描述 |
|----------|------|------|
| find_path | 路径查找 | BFS/DFS 查找两实体间路径 |
| find_shortest_path | 最短路径 | 实体间的最短关系路径 |
| find_connected_entities | 连通分量 | 查找所有连通的实体群组 |
| compute_centrality | 中心性计算 | 计算实体的图中心性指标 |
### 6.3 图遍历示例
```mermaid
graph TD
A[Alice] -->|works_for| B[TechCorp]
A -->|knows| C[Bob]
C -->|works_for| B
A -->|knows| D[Carol]
D -->|created| E[ProjectX]
B -->|created| E
style A fill:#e1f5fe
style B fill:#fff3e0
style E fill:#e8f5e8
```
查询 Alice 到 ProjectX 的路径：
- Alice → TechCorp → ProjectX（2跳）
- Alice → Carol → ProjectX（2跳）
## 7. 标签与层级
### 7.1 标签系统
```typescript
// 标签操作
ctx.tagManager.add(entityId, tag); // 添加标签
ctx.tagManager.remove(entityId, tag); // 移除标签
ctx.tagManager.findByTag(tag); // 按标签查询
ctx.tagManager.setImportance(entityId, score); // 设置重要性
```
### 7.2 层级结构
```typescript
// 层级操作
ctx.hierarchyManager.setParent(childId, parentId); // 设置父节点
ctx.hierarchyManager.getChildren(parentId); // 获取子节点
ctx.hierarchyManager.getSubtree(nodeId); // 获取子树
ctx.hierarchyManager.getAncestors(nodeId); // 获取祖先链
```
## 8. 搜索功能
### 8.1 搜索类型
| 搜索类型 | 工具 | 描述 |
|----------|------|------|
| 基础搜索 | search_entities | 关键词全文搜索 |
| 布尔搜索 | boolean_search | AND/OR/NOT 逻辑组合 |
| 模糊搜索 | fuzzy_search | 容错匹配 |
| 语义搜索 | semantic_search | 向量相似度检索 |
| 排名搜索 | ranked_search | TF-IDF 加权排序 |
| 自动选择 | auto_select_search | 自适应最佳搜索策略 |
### 8.2 语义搜索配置
启用语义搜索需要配置嵌入模型：
```bash
# OpenAI 嵌入
MEMORY_EMBEDDING_PROVIDER=openai
MEMORY_OPENAI_API_KEY=sk-...
MEMORY_EMBEDDING_MODEL=text-embedding-3-small
MEMORY_AUTO_INDEX_EMBEDDINGS=true
# 本地嵌入
MEMORY_EMBEDDING_PROVIDER=local
MEMORY_EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2
```
## 9. 数据导出
### 9.1 导出格式
| 格式 | 工具 | 用途 |
|------|------|------|
| JSON | export_graph | 通用数据交换 |
| CSV | export_graph | 电子表格分析 |
| Markdown | export_graph | 文档生成 |
| XML | export_graph | 企业系统集成 |
| JSON-LD | export_graph | 语义网应用 |
| GraphML | export_graph | 图可视化工具 |
### 9.2 导出工具
```typescript
// 导出图数据
export_graph({
format: "json", // json|csv|markdown|xml|json-ld
includeArchived: false,
redactPii: true // PII 脱敏
})
```
资料来源：[CLAUDE.md:30-35]()
## 10. 完整工作流示例
```mermaid
sequenceDiagram
participant Client
participant MCPServer
participant ToolHandlers
participant EntityManager
participant GraphStorage
Client->>MCPServer: create_entity
MCPServer->>ToolHandlers: route to create_entity handler
ToolHandlers->>EntityManager: createEntity(data)
EntityManager->>GraphStorage: persist
GraphStorage-->>EntityManager: entity with id
EntityManager-->>ToolHandlers: result
ToolHandlers-->>MCPServer: formatted response
MCPServer-->>Client: MCP response
Note over Client,GraphStorage: 创建实体后添加观察
Client->>MCPServer: create_observation
MCPServer->>ToolHandlers: route to create_observation handler
ToolHandlers->>EntityManager: getEntity(name)
EntityManager-->>ToolHandlers: entity
ToolHandlers->>ObservationManager: createObservation(data)
ObservationManager->>GraphStorage: persist
GraphStorage-->>ObservationManager: observation with id
ObservationManager-->>ToolHandlers: result
ToolHandlers-->>MCPServer: formatted response
MCPServer-->>Client: MCP response
```
## 11. 相关资源
- **核心库文档**: [@danielsimonjr/memoryjs](https://www.npmjs.com/package/@danielsimonjr/memoryjs)
- **项目地址**: https://github.com/danielsimonjr/memory-mcp
- **npm 包**: @danielsimonjr/memory-mcp
---
## 存储后端
### 相关页面
相关主题：[实体与关系模型](#page-entities-relations), [数据流处理](#page-data-flow)
相关源码文件
以下源码文件用于生成本页说明：
- [tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts)
- [tools/migrate-from-jsonl-to-sqlite/README.md](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/migrate-from-jsonl-to-sqlite/README.md)
- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)
- [SECURITY.md](https://github.com/danielsimonjr/memory-mcp/blob/main/SECURITY.md)
- [package.json](https://github.com/danielsimonjr/memory-mcp/blob/main/package.json)
# 存储后端
## 概述
Memory MCP 的存储后端是整个系统的核心基础设施，负责持久化知识图谱数据。系统支持两种存储格式：**JSONL**（基于文本行的 JSON 格式）和 **SQLite**（关系型数据库）。存储后端通过 `@danielsimonjr/memoryjs` 库提供统一的访问接口，实现了数据的抽象化存储，使得上层业务逻辑无需关心底层存储细节。
项目的存储架构采用分层设计，memory-mcp 作为前端封装，通过 ManagerContext 访问 memoryjs 核心库提供的各种管理器，这些管理器再与底层存储层（GraphStorage 或 SQLiteStorage）进行交互。资料来源：[CLAUDE.md]()
## 支持的存储格式
Memory MCP 支持两种存储后端格式，开发者可根据数据规模、性能需求和使用场景选择合适的格式。
| 格式 | 文件扩展名 | 适用场景 | 性能特点 |
|------|------------|----------|----------|
| JSONL | `.jsonl`, `.json` | 小规模数据、简单部署、调试 | 易于阅读和编辑，人类可读 |
| SQLite | `.db`, `.sqlite`, `.sqlite3` | 大规模数据、生产环境 | 原生 C++ 实现，性能提升 3-10 倍 |
SQLite 后端通过 `better-sqlite3` 原生绑定实现，比 WASM 实现快 3-10 倍。资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()
## 存储文件布局
根据架构规范，数据文件位于**项目根目录**（而非 `dist/` 输出目录）。这种设计确保了数据文件的独立性和可移植性。
### JSONL 格式文件
```
项目根目录/
├── memory.jsonl # 实体和关系数据
├── memory-saved-searches.jsonl # 保存的搜索查询
└── memory-tag-aliases.jsonl # 标签别名映射
```
### SQLite 格式文件
```
项目根目录/
└── memory.db # 单一数据库文件（所有数据）
```
配置环境变量 `MEMORY_STORAGE_TYPE=sqlite` 可启用 SQLite 存储模式。资料来源：[CLAUDE.md]()
## 架构分层
```
┌─────────────────────────────────────────────────────────────┐
│ memory-mcp (本项目) │
├─────────────────────────────────────────────────────────────┤
│ src/index.ts │ 入口点，重新导出核心类型 │
│ src/server/MCPServer.ts │ MCP 服务器实现 │
│ src/server/toolDefs.ts │ 工具定义 │
│ src/server/toolHandlers │ 工具处理器 │
└───────────────────────────┼─────────────────────────────────┘
│ 依赖导入
▼
┌─────────────────────────────────────────────────────────────┐
│ @danielsimonjr/memoryjs (npm 依赖) │
├─────────────────────────────────────────────────────────────┤
│ ManagerContext (延迟初始化) │
│ ├── EntityManager │ 实体管理器 │
│ ├── RelationManager │ 关系管理器 │
│ ├── ObservationManager │ 观察数据管理器 │
│ ├── SearchManager │ 搜索管理器 │
│ ├── TagManager │ 标签管理器 │
│ ├── HierarchyManager │ 层级管理器 │
│ ├── AnalyticsManager │ 分析管理器 │
│ ├── CompressionManager │ 压缩管理器 │
│ ├── ArchiveManager │ 归档管理器 │
│ ├── IOManager │ IO 管理器 │
│ ├── GraphTraversal │ 图遍历 │
│ ├── SemanticSearch │ 语义搜索 │
│ ├── RankedSearch │ 排名搜索 │
│ └── Storage │ 直接访问 GraphStorage │
├─────────────────────────────────────────────────────────────┤
│ 存储层 (GraphStorage) │
│ ├── SQLiteStorage │ SQLite 原生实现 │
│ └── JsonlStorage │ JSONL 文件实现 │
└─────────────────────────────────────────────────────────────┘
```
资料来源：[CLAUDE.md]()
## SQLite 存储特性
SQLite 后端实现了多项企业级特性，以提供高性能和可靠的数据存储。
### 自动全文搜索索引
SQLite 后端会自动创建 **FTS5**（Full-Text Search version 5）索引，启用高级全文搜索功能。这使得系统能够支持复杂的文本搜索查询，无需额外的搜索基础设施。资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()
### WAL 模式
SQLite 数据库启用 **WAL（Write-Ahead Logging）模式**，该模式允许读写操作并发进行，显著提升多客户端访问场景下的性能。WAL 模式相比传统的回滚日志模式，在大多数场景下提供更好的并发性能。资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()
### 原子事务
所有数据写入操作都使用**原子事务**包装，确保在系统崩溃或异常断电情况下的数据完整性。原子事务保证要么所有操作成功提交，要么全部回滚，不会出现部分写入的损坏状态。资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()
## 存储迁移工具
项目提供了独立的迁移工具 `migrate-from-jsonl-to-sqlite`，支持在两种存储格式之间双向转换。
### 工具位置
```
tools/
└── migrate-from-jsonl-to-sqlite/
├── migrate-from-jsonl-to-sqlite.ts # TypeScript 源码
├── package.json # 工具依赖配置
└── README.md # 使用文档
```
### 安装与构建
```bash
cd tools/migrate-from-jsonl-to-sqlite
npm install
npm run build
```
构建完成后可生成 Windows 可执行文件 `migrate-from-jsonl-to-sqlite.exe`。资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()
### 命令行参数
| 参数 | 简写 | 描述 | 示例 |
|------|------|------|------|
| `--from` | `-f` | 源文件路径（JSONL 或 SQLite） | `--from memory.jsonl` |
| `--to` | `-t` | 目标文件路径（JSONL 或 SQLite） | `--to memory.db` |
| `--verbose` | `-v` | 显示详细进度信息 | `--verbose` |
| `--help` | `-h` | 显示帮助信息 | `--help` |
### 使用示例
```bash
# JSONL 转换为 SQLite
migrate-from-jsonl-to-sqlite --from memory.jsonl --to memory.db
# SQLite 转换为 JSONL
migrate-from-jsonl-to-sqlite --from memory.db --to memory.jsonl
# 使用位置参数
migrate-from-jsonl-to-sqlite memory.jsonl memory.db
# 详细输出模式
migrate-from-jsonl-to-sqlite -f memory.jsonl -t memory.db -v
```
资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()
### 迁移流程
```mermaid
graph TD
A[开始迁移] --> B{检测源文件类型}
B -->|JSONL| C[loadFromJsonl]
B -->|SQLite| D[loadFromSqlite]
C --> E[加载数据到内存]
D --> E
E --> F{实体数=0 且 关系数=0?}
F -->|是| G[输出警告，终止]
F -->|否| H[写入目标文件]
H --> I{目标类型}
I -->|SQLite| J[创建数据库 + FTS5 索引 + WAL 模式]
I -->|JSONL| K[逐行写入 JSONL]
J --> L[使用原子事务提交]
K --> L
L --> M[迁移完成]
```
### 注意事项
- 目标文件不存在时会自动创建
- 目标文件已存在时会**覆盖**原有数据
- 迁移会保留所有实体、关系和元数据
- 缺失的时间戳会被设置为迁移时间并输出警告
- **已保存的搜索**和**标签别名**不会迁移到 SQLite 格式
- 迁移工具使用 `better-sqlite3` 原生绑定，性能优于 WASM 实现
资料来源：[tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts]()
## 核心数据模型
Memory MCP 的存储后端管理以下核心数据结构：
### 实体 (Entity)
实体是知识图谱中的节点，代表独立的概念、对象或事物。
| 字段 | 类型 | 描述 |
|------|------|------|
| id | string | 唯一标识符 |
| name | string | 实体名称 |
| observation | string | 主要观察/描述数据 |
| metadata | object | 附加元数据 |
| createdAt | timestamp | 创建时间 |
| updatedAt | timestamp | 更新时间 |
### 关系 (Relation)
关系是连接两个实体的有向边，定义实体间的关联。
| 字段 | 类型 | 描述 |
|------|------|------|
| id | string | 唯一标识符 |
| from | string | 源实体 ID |
| to | string | 目标实体 ID |
| relationType | string | 关系类型 |
### 观察数据 (Observation)
观察数据是附加到实体的客观事实，支持数据归一化。
| 字段 | 类型 | 描述 |
|------|------|------|
| id | string | 唯一标识符 |
| entityId | string | 所属实体 ID |
| content | string | 观察内容 |
| normalized | object | 归一化后的数据 |
### 产物 (Artifact)
产物是工具输出、代码片段、API 响应等内容的存储容器。
| 字段 | 类型 | 描述 |
|------|------|------|
| ref | string | 稳定的引用标识符 |
| content | string | 产物内容 |
| toolName | string | 产生该产物的工具名 |
| artifactType | enum | 产物类型 |
| sessionId | string | 会话上下文（可选） |
产物类型枚举值包括：`tool_output`、`code_snippet`、`api_response`、`search_result`、`file_content`、`user_input`。资料来源：[src/server/toolDefinitions.ts]()
## 存储配置
### 环境变量
| 变量名 | 值 | 描述 |
|--------|-----|------|
| `MEMORY_STORAGE_TYPE` | `sqlite` | 启用 SQLite 存储 |
| `MEMORY_FILE_PATH` | 文件路径 | 指定自定义存储路径 |
### 安全配置示例
在容器化环境中，建议通过环境变量或 Kubernetes Secret 管理存储路径：
```yaml
apiVersion: v1
kind: Pod
spec:
containers:
- name: memory-mcp
env:
- name: MEMORY_FILE_PATH
value: "/secure/path/memory.jsonl"
```
资料来源：[SECURITY.md]()
## 安全考量
存储后端的安全性直接影响整体系统的数据保护能力。
### 静态数据安全
| 风险 | 描述 | 缓解措施 |
|------|------|----------|
| 文件可读性 | 本地文件可被任何有权限的进程读取 | 限制文件权限，使用专用存储路径 |
| 无内置加密 | 存储文件未加密 | 依赖文件系统加密或全磁盘加密 |
| 无访问控制 | 无用户认证授权机制 | 通过系统权限和网络隔离实现 |
### 导出安全
CSV 和 JSON 导出包含完整的实体数据，在分享前应检查敏感信息。GraphML 格式需要正确的 XML 实体转义处理。资料来源：[SECURITY.md]()
### 备份建议
```bash
# 备份存储文件
cp memory.jsonl memory.jsonl.backup
# 或对于 SQLite
cp memory.db memory.db.backup
```
## 性能优化
### SQLite 性能特性
| 特性 | 作用 | 性能影响 |
|------|------|----------|
| better-sqlite3 原生绑定 | 直接调用 SQLite C 库 | 比 WASM 快 3-10x |
| WAL 模式 | 支持读写并发 | 提升多客户端性能 |
| FTS5 全文索引 | 自动创建的全文搜索索引 | 加速文本搜索 |
| 原子事务 | 保证数据一致性 | 防止数据损坏 |
### 压缩管理
存储后端集成压缩管理器，支持以下操作：
- **重复检测**：识别知识图谱中的重复实体
- **智能合并**：合并重复数据，保留最新信息
- **自动压缩**：根据配置阈值自动触发压缩
- **归档**：将历史数据归档以优化活跃数据访问
资料来源：[CLAUDE.md]()
## 依赖配置
### npm 依赖
```json
{
"dependencies": {
"@danielsimonjr/memoryjs": "^2.1.0",
"@modelcontextprotocol/sdk": "^1.21.1",
"zod": "^3.24.1"
}
}
```
### 迁移工具依赖
```json
{
"dependencies": {
"better-sqlite3": "^11.7.0"
},
"devDependencies": {
"@types/better-sqlite3": "^7.6.12",
"@yao-pkg/pkg": "^6.11.0",
"typescript": "^5.6.2"
}
}
```
资料来源：[package.json]()
## 工具构建
项目提供了便捷的脚本用于构建所有独立工具：
```bash
# 安装所有工具依赖
npm run tools:install
# 构建所有工具（包括迁移工具）
npm run tools:build
```
构建后的迁移工具位于 `tools/migrate-from-jsonl-to-sqlite/` 目录，可生成独立的 Windows 可执行文件。资料来源：[package.json]()
## 总结
Memory MCP 的存储后端提供了灵活、高效、可靠的数据持久化能力。通过支持 JSONL 和 SQLite 两种格式，开发者可以根据实际需求选择合适的存储方案。SQLite 后端凭借原生绑定、WAL 模式、FTS5 索引等特性，在生产环境中提供卓越的性能表现。独立的迁移工具简化了格式转换过程，而分层架构则确保了系统的可维护性和扩展性。
---
## 层级嵌套
### 相关页面
相关主题：[实体与关系模型](#page-entities-relations), [搜索能力](#page-search-capabilities)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts) — 层级工具处理器实现
- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts) — 层级工具定义
- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md) — 项目架构文档
# 层级嵌套
## 概述
层级嵌套（Hieararchy）是 memory-mcp 知识图谱系统中用于管理实体间父子关系和树形结构的核心功能模块。该模块通过 `ctx.hierarchyManager` 提供9个专用工具，支持实体间的父子树构建和子树遍历操作。
层级管理是知识图谱组织结构化信息的重要手段，允许用户将实体组织成树形层级关系，便于表达分类、归属、继承等概念。资料来源：[CLAUDE.md:1]()。
## 架构设计
### 访问方式
层级管理器通过 `ManagerContext` 实例访问：
```typescript
ctx.hierarchyManager
```
可用的层级操作方法包括：
| 方法 | 功能描述 |
|------|----------|
| `setEntityParent(entityName, parentName)` | 设置实体的父节点 |
| `getChildren(entityName)` | 获取直接子节点 |
| `getParent(entityName)` | 获取父节点 |
| `getAncestors(entityName)` | 获取所有祖先节点 |
| `getDescendants(entityName)` | 获取所有后代节点 |
| `getSubtree(entityName)` | 获取完整子树结构 |
资料来源：[src/server/toolHandlers.ts:1]()
### 与其他模块的关系
```
┌─────────────────────────────────────────────┐
│ ManagerContext │
├─────────────────────────────────────────────┤
│ hierarchyManager ──────────────────────────▶│
│ ├── setEntityParent() │
│ ├── getChildren() │
│ ├── getParent() │
│ ├── getAncestors() │
│ ├── getDescendants() │
│ └── getSubtree() │
└─────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ @danielsimonjr/memoryjs │
│ (底层存储: EntityManager + 层级索引) │
└─────────────────────────────────────────────┘
```
## 工具清单
### 工具分类：Hierarchy（共9个）
| 工具名称 | 功能描述 | 核心参数 |
|----------|----------|----------|
| `set_entity_parent` | 设置实体的父节点 | `entityName`, `parentName` |
| `get_children` | 获取实体的直接子节点 | `entityName` |
| `get_parent` | 获取实体的直接父节点 | `entityName` |
| `get_ancestors` | 获取实体的所有祖先节点 | `entityName` |
| `get_descendants` | 获取实体的所有后代节点 | `entityName` |
| `get_subtree` | 获取实体的完整子树 | `entityName` |
资料来源：[CLAUDE.md:1]()
## API 详细说明
### set_entity_parent
设置或更新实体的父节点关系。
**输入参数：**
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `entityName` | `string` | 是 | 要设置父节点的实体名称 |
| `parentName` | `string \| null` | 否 | 父实体名称，设为 `null` 可移除父子关系 |
**处理器实现：**
```typescript
set_entity_parent: async (ctx, args) => {
const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entity name');
const parentName = args.parentName !== undefined
? validateWithSchema(args.parentName, z.string().min(1).nullable(), 'Invalid parent name')
: null;
return formatToolResponse(await ctx.hierarchyManager.setEntityParent(entityName, parentName));
}
```
资料来源：[src/server/toolHandlers.ts:1]()
### get_children
获取指定实体的所有直接子节点。
**输入参数：**
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `entityName` | `string` | 是 | 目标实体名称 |
**处理器实现：**
```typescript
get_children: async (ctx, args) => {
const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entity name');
return formatToolResponse(await ctx.hierarchyManager.getChildren(entityName));
}
```
### get_parent
获取指定实体的直接父节点。
**输入参数：**
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `entityName` | `string` | 是 | 目标实体名称 |
**处理器实现：**
```typescript
get_parent: async (ctx, args) => {
const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entity name');
return formatToolResponse(await ctx.hierarchyManager.getParent(entityName));
}
```
### get_ancestors
获取指定实体的所有祖先节点（从直接父节点到根节点）。
**输入参数：**
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `entityName` | `string` | 是 | 目标实体名称 |
**处理器实现：**
```typescript
get_ancestors: async (ctx, args) => {
const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entity name');
return formatToolResponse(await ctx.hierarchyManager.getAncestors(entityName));
}
```
### get_descendants
获取指定实体的所有后代节点（所有子节点、孙节点等）。
**输入参数：**
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `entityName` | `string` | 是 | 目标实体名称 |
**处理器实现：**
```typescript
get_descendants: async (ctx, args) => {
const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entity name');
return formatToolResponse(await ctx.hierarchyManager.getDescendants(entityName));
}
```
### get_subtree
获取指定实体及其所有后代组成的完整子树结构。
**输入参数：**
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `entityName` | `string` | 是 | 子树根节点实体名称 |
**处理器实现：**
```typescript
get_subtree: async (ctx, args) => {
// 处理器定义（截断显示）
return formatToolResponse(await ctx.hierarchyManager.getSubtree(entityName));
}
```
## 使用流程
### 典型操作流程
```mermaid
graph TD
A[开始] --> B[创建或获取实体]
B --> C{是否需要设置父子关系}
C -->|是| D[调用 set_entity_parent]
C -->|否| E[直接进行层级查询]
D --> F[关联层级索引]
F --> G[查询层级关系]
E --> G
G --> H{查询类型}
H -->|直接子节点| I[get_children]
H -->|父节点| J[get_parent]
H -->|所有祖先| K[get_ancestors]
H -->|所有后代| L[get_descendants]
H -->|完整子树| M[get_subtree]
I --> N[返回结果]
J --> N
K --> N
L --> N
M --> N
N --> O[结束]
```
### 使用示例
**1. 构建组织层级结构：**
```json
// 设置公司 -> 部门 -> 团队的层级关系
{
"entityName": "后端团队",
"parentName": "技术部"
}
```
```json
{
"entityName": "技术部",
"parentName": "XX公司"
}
```
**2. 查询实体信息：**
```json
// 获取某实体的所有祖先
{
"entityName": "后端团队"
}
```
**3. 遍历子树：**
```json
// 获取完整子树结构
{
"entityName": "XX公司"
}
```
## 层级遍历算法
### 树形结构示意
```
┌─────────────┐
│ 根节点 │
│ (Root) │
└──────┬──────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 节点A │ │ 节点B │ │ 节点C │
│ (Child 1) │ │ (Child 2) │ │ (Child 3) │
└──────┬─────┘ └──────┬─────┘ └─────────────┘
│
▼
┌─────────────┐
│ 节点D │
│ (Grandchild)│
└─────────────┘
```
### 各方法返回范围
| 方法 | 返回内容 | 说明 |
|------|----------|------|
| `get_parent` | `[A]` | 仅返回直接父节点 |
| `get_children` | `[A, B, C]` | 仅返回直接子节点 |
| `get_ancestors` | `[A]` → `[Root]` | 从父到根的完整路径 |
| `get_descendants` | `[D]` → `[D]` | 所有后代节点的扁平列表 |
| `get_subtree` | 完整树结构 | 包含根节点及其所有后代 |
## 存储机制
层级关系数据存储于项目的存储文件中，支持两种存储格式：
| 存储类型 | 文件路径 | 说明 |
|----------|----------|------|
| JSONL | `memory.jsonl` | 默认存储格式 |
| SQLite | `memory.db` | 设置 `MEMORY_STORAGE_TYPE=sqlite` 启用 |
层级数据以实体属性的形式存储，由 `memoryjs` 库的底层存储系统管理。资料来源：[CLAUDE.md:1]()
## 错误处理
工具处理器使用 `validateWithSchema` 进行参数校验：
| 错误类型 | 校验规则 | 处理方式 |
|----------|----------|----------|
| 空字符串 | `z.string().min(1)` | 返回验证错误信息 |
| 类型错误 | Zod schema | 返回类型不匹配提示 |
| 层级不存在 | 运行时检查 | 返回空结果或 `not found` 提示 |
## 最佳实践
### 1. 避免循环引用
设置父子关系时，应避免创建环形结构：
```mermaid
graph LR
A --> B
B --> C
C --> A
```
系统不会自动检测循环引用，创建时请确保层级结构的有效性。
### 2. 合理设置层级深度
过深的层级会增加查询复杂度，建议：
- 保持层级深度在合理范围内（建议 ≤ 10 层）
- 对于过深的结构，考虑拆分为多个独立树
### 3. 批量操作优化
如需创建多个层级关系，建议按拓扑顺序执行，确保父节点先于子节点存在。
## 相关文档
| 文档 | 路径 | 说明 |
|------|------|------|
| 工具定义 | `src/server/toolDefinitions.ts` | 层级工具的 MCP schema 定义 |
| 工具处理器 | `src/server/toolHandlers.ts` | 层级工具的业务逻辑实现 |
| 核心架构 | `CLAUDE.md` | 项目整体架构说明 |
## 更新日志
| 版本 | 更新内容 |
|------|----------|
| v12.2.0 | 基础层级管理工具集（6个） |
| v12.3.0 | 扩展层级操作，新增子树查询能力 |
---
## 搜索能力
### 相关页面
相关主题：[高级功能](#page-advanced-features), [工具参考手册](#page-tool-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)
- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)
- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
# 搜索能力
## 概述
memory-mcp 的搜索能力是该知识图谱系统的核心功能之一，通过多层架构提供从基础关键词匹配到高级语义理解的全面搜索能力。系统支持超过 20 种搜索工具，涵盖基础搜索、智能搜索、语义搜索三大类别，并提供保存搜索和定时搜索等高级功能。
搜索功能由 `ManagerContext` 中的多个管理器协同工作实现，包括 `SearchManager`（基础和高级搜索）、`semanticSearch`（语义向量搜索）和 `rankedSearch`（TF-IDF 排名搜索）。
## 搜索架构
### 分层搜索模型
```mermaid
graph TD
A[用户查询] --> B[搜索路由层]
B --> C{查询类型判断}
C -->|基础关键词| D[SearchManager
基础搜索]
C -->|TF-IDF排名| E[rankedSearch
排名搜索]
C -->|向量相似度| F[semanticSearch
语义搜索]
C -->|时间范围| G[temporalSearch
时序搜索]
C -->|复合条件| H[IntelligentSearch
智能搜索]
D --> I[GraphStorage
数据存储]
E --> I
F --> I
G --> I
H --> I
I --> J[结果聚合]
J --> K[排序与去重]
K --> L[返回结果]
```
### 核心组件
| 组件名称 | 类型 | 功能描述 |
|----------|------|----------|
| `SearchManager` | 管理器 | 基础搜索、布尔搜索、模糊搜索的入口 |
| `semanticSearch` | 访问器 | 基于嵌入向量的语义相似度搜索 |
| `rankedSearch` | 访问器 | TF-IDF 算法的排名搜索 |
| `SearchByTimeHandler` | 处理器 | 基于时间范围的时序搜索 |
| `GraphStorage` | 存储层 | 底层图数据库查询接口 |
## 搜索工具分类
### 1. 基础搜索（7 个工具）
基础搜索提供最常用的关键词和模式匹配功能。
| 工具名称 | 功能 | 关键参数 |
|----------|------|----------|
| `search_entities` | 基础实体搜索 | `query`, `limit` |
| `search_by_time` | 时间范围搜索 | `query`, `field`, `since`, `until` |
| `search_by_relation` | 关系路径搜索 | `entity`, `relationType`, `depth` |
| `search_by_tag` | 标签关联搜索 | `tags`, `matchAll` |
| `fuzzy_search` | 模糊匹配搜索 | `query`, `threshold` |
| `auto_search` | 自动选择最佳搜索 | `query` |
| `boolean_search` | 布尔逻辑搜索 | `query`, `operators` |
#### 时间范围搜索
`search_by_time` 工具支持时序查询，允许用户限定搜索结果的时间范围：
```typescript
// toolHandlers.ts 中的实现
search_by_time: async (ctx, args) => {
const query = validateWithSchema(args.query, z.string().min(1), 'Invalid query');
const options: { field: string; since?: Date; until?: Date } = {};
// 支持 since/until 参数进行时间过滤
}
```
资料来源：[src/server/toolHandlers.ts:1-50]()
#### 模糊搜索
模糊搜索通过编辑距离算法容忍拼写错误，支持配置相似度阈值：
- `threshold`：相似度阈值（0-1 之间）
- 自动纠错和建议
### 2. 智能搜索（3 个工具）
智能搜索提供更高级的查询理解和结果优化能力。
| 工具名称 | 功能描述 |
|----------|----------|
| `intelligent_search` | 多层混合搜索，结合多种搜索策略 |
| `analyze_query` | 查询分析，理解用户意图 |
| `reflected_search` | 基于反思的搜索优化 |
```mermaid
graph LR
A[原始查询] --> B[analyze_query
查询分析]
B --> C[查询重写]
C --> D[intelligent_search
智能搜索]
D --> E[reflected_search
反思优化]
E --> F[最终结果]
```
### 3. 语义搜索（3 个工具）
语义搜索基于嵌入向量（embeddings）实现语义级别的相似度匹配。
| 工具名称 | 功能描述 | 嵌入提供者 |
|----------|----------|------------|
| `semantic_search` | 向量相似度搜索 | OpenAI / 本地模型 |
| `hybrid_search` | 混合向量+关键词搜索 | 两者结合 |
| `semantic_filter` | 基于语义的过滤 | 两者结合 |
#### 环境配置
```bash
# 环境变量配置
MEMORY_EMBEDDING_PROVIDER=openai|local|none # 嵌入提供者
MEMORY_OPENAI_API_KEY=sk-xxx # OpenAI API 密钥
MEMORY_EMBEDDING_MODEL=text-embedding-3-small # OpenAI 模型
# 本地默认: Xenova/all-MiniLM-L6-v2
MEMORY_AUTO_INDEX_EMBEDDINGS=false # 是否自动索引
```
资料来源：[CLAUDE.md:95-100]()
### 4. 保存搜索（5 个工具）
保存搜索允许用户存储和重用常用查询。
| 工具名称 | 功能描述 |
|----------|----------|
| `save_search` | 保存当前搜索条件 |
| `list_saved_searches` | 列出所有保存的搜索 |
| `execute_saved_search` | 执行已保存的搜索 |
| `update_saved_search` | 更新保存的搜索 |
| `delete_saved_search` | 删除保存的搜索 |
保存的搜索存储在 `memory-saved-searches.jsonl` 文件中。
## 搜索 API
### 核心参数
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `query` | string | 是 | 搜索查询字符串 |
| `limit` | number | 否 | 返回结果数量限制（默认 50） |
| `offset` | number | 否 | 结果偏移量 |
| `since` | string | 否 | ISO 8601 格式起始时间 |
| `until` | string | 否 | ISO 8601 格式结束时间 |
### 搜索工具定义示例
```typescript
// toolDefinitions.ts 中的时间搜索定义
{
name: 'search_by_time',
description: 'Search for entities by time range and query string',
inputSchema: {
type: 'object',
properties: {
query: { type: 'string', description: 'Search query' },
field: { type: 'string', description: 'Time field to search' },
since: { type: 'string', description: 'Start time (ISO 8601)' },
until: { type: 'string', description: 'End time (ISO 8601)' },
},
required: ['query'],
},
}
```
资料来源：[src/server/toolDefinitions.ts:200-220]()
## 搜索流程
### 完整搜索流程
```mermaid
sequenceDiagram
participant U as 用户
participant H as ToolHandler
participant SM as SearchManager
participant SS as SemanticSearch
participant RS as RankedSearch
participant G as GraphStorage
U->>H: search_entities(query)
H->>SM: 路由到基础搜索
alt 语义搜索模式
SM->>SS: 执行向量搜索
SS->>G: 查询嵌入向量
G-->>SS: 相似度结果
SS-->>SM: 语义匹配结果
end
alt 排名搜索模式
SM->>RS: 执行TF-IDF排名
RS->>G: 词频统计
G-->>RS: 排名结果
RS-->>SM: 排名匹配结果
end
SM->>SM: 结果聚合去重
SM-->>H: 排序后结果
H-->>U: 返回最终结果
```
### 查询验证流程
所有搜索请求都经过以下验证流程：
1. **参数校验**：使用 `validateWithSchema` 验证输入参数
2. **类型检查**：确保数据类型符合 schema 定义
3. **边界处理**：限制 `limit` 在 1-1000 范围内
4. **错误处理**：返回格式化的错误信息
```typescript
// toolHandlers.ts 中的查询验证
const limit = args.limit !== undefined
? validateWithSchema(args.limit, z.number().int().min(1).max(1000), 'Invalid limit')
: 50;
```
## 存储与索引
### 存储位置
搜索索引和数据文件位于项目根目录：
| 文件类型 | 文件路径 | 描述 |
|----------|----------|------|
| 主数据 | `memory.jsonl` | 实体和关系数据 |
| 保存搜索 | `memory-saved-searches.jsonl` | 预设查询 |
| 标签别名 | `memory-tag-aliases.jsonl` | 标签同义词 |
| SQLite | `memory.db` | 结构化查询（需配置） |
### 索引策略
| 索引类型 | 触发条件 | 配置项 |
|----------|----------|--------|
| 全文索引 | 实体创建时 | `MEMORY_AUTO_INDEX_EMBEDDINGS` |
| 向量索引 | 嵌入生成后 | 自动 |
| 标签索引 | 标签赋值时 | 自动 |
| 时间索引 | 时间字段更新时 | 自动 |
## 最佳实践
### 1. 搜索策略选择
```mermaid
graph TD
A[开始搜索] --> B{知道确切实体名?}
B -->|是| C{需要语义匹配?}
B -->|否| D{需要模糊匹配?}
C -->|是| E[semantic_search
语义搜索]
C -->|否| F{需要排名?}
D -->|是| G[fuzzy_search
模糊搜索]
D -->|否| H{需要布尔逻辑?}
F -->|是| I[ranked_search
排名搜索]
F -->|否| J[search_entities
基础搜索]
H -->|是| K[boolean_search
布尔搜索]
H -->|否| L[auto_search
自动选择]
```
### 2. 性能优化建议
- **批量搜索**：使用 `list_saved_searches` 预加载常用查询
- **时间过滤**：在有明确时间范围时使用 `search_by_time`
- **限制结果**：合理设置 `limit` 参数避免返回过多结果
- **选择存储**：大数据量场景使用 SQLite 存储
### 3. 常见查询模式
| 场景 | 推荐工具 | 示例 |
|------|----------|------|
| 快速查找 | `auto_search` | 未知最佳搜索方式时 |
| 精确匹配 | `search_entities` | 知道实体名称 |
| 容忍错别字 | `fuzzy_search` | 用户输入可能有误 |
| 学术研究 | `semantic_search` | 概念相似但表述不同 |
| 时间追溯 | `search_by_time` | 查看某时间段的记忆 |
## 总结
memory-mcp 的搜索能力通过分层架构实现了从基础到高级的完整搜索覆盖。基础搜索满足日常查询需求，智能搜索提供查询理解和优化，语义搜索实现深度的语义理解能力。开发者应根据具体使用场景选择合适的搜索工具，以获得最佳的用户体验和性能表现。
---
## 高级功能
### 相关页面
相关主题：[搜索能力](#page-search-capabilities), [工具参考手册](#page-tool-reference), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)
- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)
- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
- [CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)
- [tools/compress-for-context/compress-for-context.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/compress-for-context/compress-for-context.ts)
# 高级功能
memory-mcp 是一个基于 Model Context Protocol 的知识图谱管理工具，提供超过 213 个工具，分布在 58 个类别中。Phase 15 和 Phase 16 引入的大量高级功能使该系统具备企业级特性，包括双时态有效性、并发控制、访问控制、程序化记忆、因果推理等能力。
## 1. 版本演进与功能概览
memory-mcp 的高级功能通过两个主要版本迭代实现：
| 版本 | 版本号 | 新增工具数 | 核心功能 |
|------|--------|-----------|---------|
| Phase 15 | v12.2.0 | 23 | 双时态有效性、OCC、RBAC、程序化记忆、主动检索、因果推理、世界模型 |
| Phase 16 | v12.3.0 | 53 | do_not_remember 排除、决策理由与 ADR 双写、结构化项目上下文、启发式指南、ToolCallObserver 管道、观察去重、拼写纠正 |
资料来源：[CLAUDE.md:3-10]()
## 2. 记忆衰减与优先级管理
系统提供基于时间的记忆重要性衰减机制，用于自动管理长期记忆的价值。
### 2.1 衰减工具
| 工具名称 | 功能描述 |
|---------|---------|
| `run_decay_cycle` | 对所有 agent 记忆执行单次时间衰减，返回衰减和遗忘的记忆数量 |
| `get_decayed_memories` | 列出重要性降至阈值以下的记忆（不同于 `get_stale_entities` 使用新鲜度时间戳） |
| `forget_weak_memories` | 批量删除低于衰减阈值的记忆（不同于 `forget_memory` 的内容匹配或 `archive_entities` 的条件移动） |
资料来源：[src/server/toolDefinitions.ts:衰减工具定义]()
### 2.2 衰减流程
```mermaid
graph TD
A[运行 run_decay_cycle] --> B{计算记忆重要性}
B --> C{是否低于阈值?}
C -->|是| D[标记为弱记忆]
C -->|否| E[保留记忆]
D --> F[get_decayed_memories 查询]
F --> G{forget_weak_memories}
G -->|dryRun=true| H[预览待删除列表]
G -->|dryRun=false| I[批量删除]
```
### 2.3 阈值配置
- `threshold`：重要性阈值，低于此值将被遗忘（默认 0.1）
- `maxCount`：单次操作最大遗忘数量
- `dryRun`：预览模式，不执行实际删除
资料来源：[src/server/toolDefinitions.ts:衰减工具参数]()
## 3. 访问控制与治理
Phase 15 引入的 RBAC 功能提供细粒度的访问控制。
### 3.1 治理策略
| 操作 | 说明 |
|------|------|
| `set_governance_policy` | 设置全局治理策略，控制创建、更新、删除权限 |
| `audit_query` | 查询审计日志，支持按操作类型、agentId、实体名称、时间范围过滤 |
资料来源：[src/server/toolHandlers.ts:治理处理器]()
### 3.2 审计过滤器
```typescript
interface AuditFilter {
operation?: 'create' | 'update' | 'delete' | 'merge' | 'archive';
agentId?: string;
entityName?: string;
fromTime?: string; // 注意：使用 fromTime/toTime 而非 since/until
toTime?: string;
}
```
### 3.3 治理架构
```mermaid
graph TD
A[MCP Client] --> B[Tool Call]
B --> C{Governance Policy Check}
C -->|canCreate| D[允许创建]
C -->|canUpdate| E[允许更新]
C -->|canDelete| F[允许删除]
C -->|禁止| G[返回权限错误]
D --> H[写入审计日志]
E --> H
F --> H
H --> I[Audit Log]
```
资料来源：[src/server/toolHandlers.ts:audit_query 实现]()
## 4. 工件管理系统
Artifacts 是系统用于存储工具输出、代码片段、API 响应等内容的实体。
### 4.1 工件类型
| 类型标识 | 用途 |
|---------|------|
| `tool_output` | 工具执行输出 |
| `code_snippet` | 代码片段 |
| `api_response` | API 响应数据 |
| `search_result` | 搜索结果 |
| `file_content` | 文件内容 |
| `user_input` | 用户输入 |
资料来源：[src/server/toolDefinitions.ts:工件类型定义]()
### 4.2 工件管理工具
| 工具 | 功能 |
|------|------|
| `create_artifact` | 创建带稳定自动生成 ref 的工件实体 |
| `get_artifact` | 通过 ref 或实体名称检索工件 |
| `list_artifacts` | 列出工件，支持按 toolName、artifactType、sessionId 过滤 |
### 4.3 工件创建参数
```typescript
{
content: string; // 必填：存储为实体观察的内容
toolName: string; // 必填：生成此工件的来源工具名
artifactType: ArtifactType; // 必填：工件分类
description?: string; // 可选：人类可读描述
sessionId?: string; // 可选：会话上下文，用于分组相关工件
}
```
资料来源：[src/server/toolHandlers.ts:工件处理器]()
## 5. 上下文压缩工具
`compress-for-context` 工具用于将大型文件压缩至 LLM 上下文窗口可接受的大小。
### 5.1 压缩级别
| 级别 | 说明 |
|------|------|
| `light` | 最小改动，保持可读性 |
| `medium` | 平衡大小与可读性（默认） |
| `aggressive` | 最大压缩，可能降低可读性 |
资料来源：[tools/compress-for-context/compress-for-context.ts:压缩级别定义]()
### 5.2 支持格式
- JSON、YAML、Markdown、CSV、TSV
- Text、Log、TypeScript、JavaScript
- XML、HTML
### 5.3 使用示例
```bash
# 单文件压缩
node compress-for-context.js data.json
node compress-for-context.js README.md -l aggressive
# 批量压缩
node compress-for-context.js -b -p "*.json" ./src
node compress-for-context.js -b -r -p "*.md" ./docs
# 解压还原
node compress-for-context.js -d input.compact
```
### 5.4 压缩算法
工具使用类 CTON（Concise Textual Notation）风格的压缩：
- 移除多余空白字符
- 缩写键名
- 提取图例（Legend）映射完整名称
- 批量处理时按缩写长度降序替换以避免冲突
资料来源：[tools/compress-for-context/compress-for-context.ts:压缩实现]()
## 6. 文件分块工具
`chunking-for-files` 工具将大型文件分割为可管理的块。
### 6.1 命令
| 命令 | 功能 |
|------|------|
| `split` | 将文件分割为多个块 |
| `merge` | 合并块文件还原原文件 |
| `status` | 显示分块状态 |
### 6.2 分块元数据
```typescript
interface Manifest {
version: '1.1.0';
sourceFile: string; // 原始文件路径
sourceHash: string; // 原始文件哈希
createdAt: string; // ISO 时间戳
fileType: string; // 文件类型
splitLevel: string; // 分割级别
chunks: Chunk[]; // 块信息数组
}
interface Chunk {
index: number;
filename: string;
title: string;
startLine: number;
endLine: number;
lineCount: number;
hash: string;
modified: boolean;
}
```
资料来源：[tools/chunking-for-files/chunking-for-files.ts:分块实现]()
### 6.3 分块流程
```mermaid
graph TD
A[输入文件] --> B[解析文件结构]
B --> C{文件类型}
C -->|Markdown| D[按标题级别分块]
C -->|TypeScript| E[按类型声明/函数分块]
C -->|其他| F[按行数/语义分块]
D --> G[生成 Manifest]
E --> G
F --> G
G --> H[写入块文件]
H --> I[生成 manifest.json]
```
## 7. Phase 16 新增特性 (v12.3.0)
### 7.1 功能分类
| 类别 | 工具数 | 描述 |
|------|--------|------|
| `do_not_remember` 排除 | 5 | 主动排除特定记忆被检索 |
| 决策理由与 ADR 双写 | 10 | 同时生成决策理由和架构决策记录 |
| 结构化项目上下文 | 12 | 提取和管理项目结构化元数据 |
| 启发式指南 | 10 | 基于规则的推荐和指导 |
| ToolCallObserver 管道 | 11 | 工具调用观察和监控 |
| 观察去重 | 2 | 自动去除重复观察 |
| 拼写纠正 | 3 | 搜索和输入的拼写纠正 |
资料来源：[CLAUDE.md:6-10]()
### 7.2 ToolCallObserver 管道
该管道允许观察和记录工具调用模式，支持：
- 工具使用频率统计
- 调用链追踪
- 异常模式检测
- 性能监控
### 7.3 观察去重机制
自动检测并合并语义相同的观察，避免知识图谱中的冗余信息。
### 7.4 拼写纠正
支持三种语言的拼写纠正功能，提升搜索准确性：
- 搜索查询的拼写纠正
- 实体名称的拼写纠正
- 观察内容的拼写纠正
## 8. 依赖图生成工具
`create-dependency-graph` 工具扫描代码库并生成依赖文档。
### 8.1 功能特性
- 扫描 `src/` 下所有 TypeScript 文件
- 解析导入和导出
- 检测循环依赖
- 生成统计信息
- 输出 Markdown 和 JSON 两种格式
### 8.2 生成的文档结构
```markdown
docs/architecture/
├── DEPENDENCY_GRAPH.md # 人类可读文档
└── dependency-graph.json # 机器可读数据
```
### 8.3 输出内容
| 内容 | 说明 |
|------|------|
| 外部依赖 | npm 包依赖 |
| Node.js 内置依赖 | fs, path 等 |
| 内部依赖 | 相对路径导入 |
| 循环依赖分析 | 运行时和类型级别 |
| 导出统计 | 类、接口、函数、常量数量 |
资料来源：[tools/create-dependency-graph/README.md:功能说明]()
## 9. 存储与迁移
### 9.1 存储格式
| 格式 | 文件位置 | 说明 |
|------|---------|------|
| JSONL | `memory.jsonl` | 项目根目录 |
| SQLite | `memory.db` | 设置 `MEMORY_STORAGE_TYPE=sqlite` |
### 9.2 迁移工具
`migrate-from-jsonl-to-sqlite` 工具支持两种格式的双向转换：
```bash
# 基本用法
migrate-from-jsonl-to-sqlite --from --to
# 详细输出
migrate-from-jsonl-to-sqlite --from source.jsonl --to target.db --verbose
```
资料来源：[tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts:迁移实现]()
## 10. 环境变量配置
| 变量 | 描述 | 默认值 |
|------|------|--------|
| `MEMORY_FILE_PATH` | 存储文件路径 | `memory.jsonl` |
| `MEMORY_STORAGE_TYPE` | 存储类型 | `jsonl` |
| `MEMORY_EMBEDDING_PROVIDER` | 向量化提供者 | `none` |
| `MEMORY_OPENAI_API_KEY` | OpenAI API 密钥 | — |
| `MEMORY_EMBEDDING_MODEL` | 向量化模型 | `text-embedding-3-small` |
| `MEMORY_AUTO_INDEX_EMBEDDINGS` | 自动索引 | `false` |
资料来源：[CLAUDE.md:环境变量配置]()
## 11. 贡献与扩展指南
### 11.1 添加新工具流程
```mermaid
graph TD
A[定义工具架构] --> B[添加 schema 到 toolDefinitions.ts]
B --> C[添加处理器到 toolHandlers.ts]
C --> D[验证参数和错误处理]
D --> E[添加端到端测试]
E --> F[更新文档]
```
### 11.2 代码规范
- 遵循 TypeScript 最佳实践
- 使用有意义的变量名
- 公共方法添加 JSDoc 注释
- 保持函数小而专注
- 一致缩进（2 空格）
资料来源：[CONTRIBUTING.md:代码风格指南]()
---
## 工具参考手册
### 相关页面
相关主题：[高级功能](#page-advanced-features), [搜索能力](#page-search-capabilities), [层级嵌套](#page-hierarchical-nesting)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)
- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)
- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)
- [tools/create-dependency-graph/create-dependency-graph.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/create-dependency-graph/create-dependency-graph.ts)
- [tools/chunking-for-files/chunking-for-files.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/chunking-for-files/chunking-for-files.ts)
- [tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts)
- [tools/compress-for-context/compress-for-context.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/compress-for-context/compress-for-context.ts)
# 工具参考手册
本文档是 Memory MCP 项目的完整工具参考手册，详细介绍所有 MCP（Model Context Protocol）工具的定义、参数、返回值以及使用方法。
## 概述
Memory MCP 提供了一套基于 Model Context Protocol 的工具集，用于与知识图谱进行交互。该项目包含 **213 个工具**，分布在 **58 个分类**中，涵盖了知识图谱的创建、查询、更新、压缩、导入导出等完整生命周期管理。
### 工具系统架构
工具系统采用分层架构设计：
```mermaid
graph TD
A[MCP 客户端] --> B[MCPServer]
B --> C[toolHandlers.ts]
C --> D[memoryjs ManagerContext]
D --> E[EntityManager]
D --> F[RelationManager]
D --> G[ObservationManager]
D --> H[SearchManager]
D --> I[TagManager]
D --> J[其他管理器]
J --> K[SQLiteStorage]
J --> L[JSONLStorage]
```
核心组件包括：
| 组件 | 文件路径 | 职责 |
|------|----------|------|
| 工具定义 | `src/server/toolDefinitions.ts` | 定义所有工具的 JSON Schema |
| 工具处理器 | `src/server/toolHandlers.ts` | 实现工具的业务逻辑 |
| 管理器上下文 | `@danielsimonjr/memoryjs` | 提供底层数据操作接口 |
资料来源：[CLAUDE.md:1-10]()
### 工具分类总览
| 分类 | 工具数量 | 核心功能 |
|------|----------|----------|
| 实体 (Entity) | 4 | 图谱节点的 CRUD 操作 |
| 关系 (Relation) | 2 | 实体间的有向边管理 |
| 观察 (Observation) | 3 | 附加到实体的知识事实 |
| 搜索 (Search) | 7 | 基础、排名、布尔、模糊搜索 |
| 智能搜索 (Intelligent Search) | 3 | 混合多层、查询分析、反思搜索 |
| 语义搜索 (Semantic Search) | 3 | OpenAI 或本地模型的嵌入相似度 |
| 保存的搜索 (Saved Searches) | 5 | 存储和重用频繁查询 |
| 标签管理 (Tag Management) | 6 | 标签及其重要性评分 |
| 标签别名 (Tag Aliases) | 5 | 标签同义词管理 |
| 层级结构 (Hierarchy) | 9 | 父子树结构和子树遍历 |
| 图算法 (Graph Algorithms) | 4 | BFS/DFS 路径发现、中心性、连通分量 |
| 分析 (Analytics) | 2 | 图谱统计和完整性验证 |
| 压缩 (Compression) | 4 | 重复检测、合并、自动压缩、归档 |
| 导入/导出 (Import/Export) | 2 | 多种格式的数据交换 |
资料来源：[CLAUDE.md:18-33]()
## 核心实体工具
### 创建实体 (create_entity)
在知识图谱中创建新的实体节点。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| name | string | 是 | 实体名称 |
| entityType | string | 否 | 实体类型，用于分类 |
| observations | string[] | 否 | 初始观察/知识列表 |
| tags | string[] | 否 | 关联标签 |
| importance | number | 否 | 重要性分数 (0-1) |
**返回值：** 创建成功的实体对象，包含自动生成的唯一引用 ID
### 获取实体 (get_entity)
通过名称或引用 ID 检索实体信息。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| ref | string | 是 | 实体引用或名称 |
### 更新实体 (update_entity)
修改现有实体的属性。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| ref | string | 是 | 实体引用 |
| name | string | 否 | 新名称 |
| entityType | string | 否 | 新类型 |
| tags | string[] | 否 | 新的标签列表 |
### 删除实体 (delete_entity)
从知识图谱中移除实体及其关联的关系和观察。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| ref | string | 是 | 要删除的实体引用 |
## 关系工具
### 创建关系 (create_relation)
在两个实体之间创建有向关系边。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| from | string | 是 | 源实体引用 |
| to | string | 是 | 目标实体引用 |
| relationType | string | 是 | 关系类型（如 "depends_on"、"implements"） |
| bidirectional | boolean | 否 | 是否双向关系（默认 false） |
### 获取关系 (get_relations)
查询满足特定条件的实体关系。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| from | string | 否 | 源实体过滤 |
| to | string | 否 | 目标实体过滤 |
| relationType | string | 否 | 关系类型过滤 |
## 搜索工具
### 基础搜索 (search_entities)
在知识图谱中搜索实体。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| query | string | 是 | 搜索查询词 |
| limit | number | 否 | 结果上限（默认 10） |
| entityType | string | 否 | 按类型过滤 |
### 排名搜索 (search_entities_ranked)
基于 TF-IDF 算法的加权排名搜索。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| query | string | 是 | 搜索查询 |
| limit | number | 否 | 结果上限 |
| boostRecent | boolean | 否 | 是否提升近期结果 |
### 模糊搜索 (search_entities_fuzzy)
支持拼写容错的模糊匹配搜索。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| query | string | 是 | 可能包含拼写错误的查询 |
| threshold | number | 否 | 匹配阈值（0-1，默认 0.6） |
### 布尔搜索 (search_entities_boolean)
支持 AND、OR、NOT 运算符的布尔搜索。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| query | string | 是 | 布尔表达式（如 "AI AND (machine OR deep)"） |
### 语义搜索 (semantic_search)
基于向量嵌入的语义相似度搜索。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| query | string | 是 | 自然语言查询 |
| limit | number | 否 | 返回结果数 |
| provider | string | 否 | 嵌入提供者（openai/local/none） |
资料来源：[CLAUDE.md:26-27]()
## 标签管理工具
### 添加标签 (add_tags)
为实体添加一个或多个标签。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| ref | string | 是 | 实体引用 |
| tags | string[] | 是 | 要添加的标签列表 |
### 移除标签 (remove_tags)
从实体移除指定标签。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| ref | string | 是 | 实体引用 |
| tags | string[] | 是 | 要移除的标签列表 |
### 获取标签 (get_tags)
获取实体的所有标签。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| ref | string | 是 | 实体引用 |
### 列出所有标签 (list_tags)
返回知识图谱中的所有标签及其使用统计。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| limit | number | 否 | 返回数量上限 |
### 标签别名管理
用于管理标签的同义词和别名关系。
| 工具名称 | 功能描述 |
|----------|----------|
| create_tag_alias | 创建标签别名映射 |
| get_tag_alias | 获取标签的别名 |
| list_tag_aliases | 列出所有标签别名 |
| delete_tag_alias | 删除标签别名 |
| resolve_tag_alias | 将别名解析为规范标签 |
## 图算法工具
### 路径发现 (find_path)
使用 BFS 或 DFS 算法查找两个实体之间的路径。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| from | string | 是 | 起始实体 |
| to | string | 是 | 目标实体 |
| algorithm | string | 否 | BFS 或 DFS（默认 BFS） |
| maxDepth | number | 否 | 最大深度限制 |
### 连通分量 (get_connected_components)
识别知识图谱中的连通分量。
### 中心性分析 (calculate_centrality)
计算实体的度中心性或介数中心性。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| entityRef | string | 是 | 实体引用 |
| type | string | 否 | 中心性类型（degree/betweenness） |
## 导入导出工具
### 导出图谱 (export_graph)
将知识图谱导出为多种格式。
**支持的格式：**
| 格式 | 描述 |
|------|------|
| json | 标准 JSON 格式 |
| jsonl | JSON Lines 格式 |
| xml | XML 格式 |
| markdown | Markdown 格式 |
| csv | CSV 表格格式 |
| ttl | Turtle RDF 格式 |
| json-ld | JSON-LD 格式 |
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| format | string | 是 | 输出格式 |
| includeObservations | boolean | 否 | 是否包含观察数据 |
| redactPii | boolean | 否 | 是否进行 PII 脱敏 |
资料来源：[CLAUDE.md:32]()
### 导入图谱 (import_graph)
从外部文件导入知识图谱数据。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| source | string | 是 | 导入源（路径或内容） |
| format | string | 是 | 数据格式 |
| mergeStrategy | string | 否 | 合并策略（replace/merge/skip） |
## 压缩与归档工具
### 检测重复 (find_duplicates)
识别知识图谱中的重复或高度相似的实体。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| threshold | number | 否 | 相似度阈值（默认 0.85） |
### 合并实体 (merge_entities)
将多个相似实体合并为一个。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| refs | string[] | 是 | 要合并的实体引用列表 |
| keepRef | string | 否 | 保留的主实体引用 |
### 运行压缩 (run_compression)
自动压缩知识图谱，移除冗余数据。
### 归档旧数据 (archive_old_entities)
将长期未访问的实体移至归档存储。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| daysOld | number | 否 | 天数阈值（默认 90） |
| archiveType | string | 否 | 归档类型标签 |
## 工件管理工具
用于存储和管理工具输出、代码片段、API 响应等工件。
### 创建工件 (create_artifact)
创建工件实体并获取稳定的自动生成引用。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| content | string | 是 | 工件内容 |
| toolName | string | 是 | 生成工件的源工具名称 |
| artifactType | string | 是 | 工件类型枚举 |
| description | string | 否 | 人类可读描述 |
| sessionId | string | 否 | 会话上下文标识 |
**artifactType 枚举值：**
| 类型 | 描述 |
|------|------|
| tool_output | 工具执行输出 |
| code_snippet | 代码片段 |
| api_response | API 响应内容 |
| search_result | 搜索结果 |
| file_content | 文件内容 |
| user_input | 用户输入 |
### 获取工件 (get_artifact)
通过引用或实体名称检索工件。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| ref | string | 是 | 工件引用或实体名称 |
### 列出工件 (list_artifacts)
列出满足过滤条件的工件。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| toolName | string | 否 | 按工具名称过滤 |
| artifactType | string | 否 | 按类型过滤 |
| since | string | 否 | ISO 8601 时间过滤 |
## 治理与审计工具
### 设置治理策略 (set_governance_policy)
配置实体的创建、更新、删除权限策略。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| entityType | string | 否 | 应用策略的实体类型 |
| canCreate | boolean | 是 | 是否允许创建 |
| canUpdate | boolean | 是 | 是否允许更新 |
| canDelete | boolean | 是 | 是否允许删除 |
### 审计查询 (audit_query)
查询实体的操作历史日志。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| operation | string | 否 | 操作类型（create/update/delete/merge/archive） |
| agentId | string | 否 | 代理 ID 过滤 |
| entityName | string | 否 | 实体名称过滤 |
| since | string | 否 | 开始时间 |
| until | string | 否 | 结束时间 |
| limit | number | 否 | 结果上限（默认 50） |
## 衰减与显著性工具
### 运行衰减周期 (run_decay_cycle)
执行基于时间的显著性衰减计算。
### 获取衰减记忆 (get_decayed_memories)
列出重要性已降至阈值以下的记忆。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| threshold | number | 否 | 重要性阈值（默认 0.1） |
### 遗忘弱记忆 (forget_weak_memories)
批量删除重要性低于衰减阈值的记忆。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| threshold | number | 是 | 重要性阈值 |
| maxCount | number | 否 | 最大遗忘数量 |
| dryRun | boolean | 否 | 是否为试运行模式 |
## 时间查询工具
### 按时间搜索 (search_by_time)
基于时间范围查询知识图谱数据。
**输入参数：**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| query | string | 是 | 查询内容 |
| startTime | string | 否 | 开始时间 |
| endTime | string | 否 | 结束时间 |
| field | string | 否 | 查询字段（created/updated/observed） |
## 独立工具集
项目还包含一组独立的命令行工具，位于 `tools/` 目录下。
### 文件分块工具 (chunking-for-files)
用于将大型文件分割为适合编辑的块，或合并已分割的文件块。
```bash
# 分割文件
chunker split [options]
# 合并块
chunker merge [options]
# 查看状态
chunker status
```
**分割选项：**
| 选项 | 描述 |
|------|------|
| -o, --output | 输出目录 |
| -l, --max-lines | 每块最大行数（默认 500） |
| --by-structure | 按代码结构分割（类、函数等） |
| --dry-run | 预览分割结果 |
资料来源：[tools/chunking-for-files/chunking-for-files.ts:1-50]()
### 上下文压缩工具 (compress-for-context)
使用 CTON（Context-optimized Notation）压缩格式压缩文件以适应 LLM 上下文窗口。
```bash
# 单文件压缩
node compress-for-context.js data.json
# 批量压缩
node compress-for-context.js -b -p "*.json" ./src
# 解压缩
node compress-for-context.js -d file.compact.json
```
**压缩级别：**
| 级别 | 描述 |
|------|------|
| light | 最小化改动，保留可读性 |
| medium | 平衡压缩率和可读性（默认） |
| aggressive | 最大压缩，可能降低可读性 |
资料来源：[tools/compress-for-context/compress-for-context.ts:1-40]()
### 存储迁移工具 (migrate-from-jsonl-to-sqlite)
在 JSONL 和 SQLite 存储格式之间迁移数据。
```bash
# 从 JSONL 迁移到 SQLite
migrate-from-jsonl-to-sqlite --from memory.jsonl --to memory.db
# 从 SQLite 迁移到 JSONL
migrate-from-jsonl-to-sqlite --from memory.db --to memory.jsonl
# 详细输出模式
migrate-from-jsonl-to-sqlite -f source.jsonl -t target.db -v
```
资料来源：[tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts:1-30]()
### 依赖图生成工具 (create-dependency-graph)
分析 TypeScript 项目并生成依赖关系文档。
```bash
# 通过 npm 脚本运行（推荐）
npm run docs:deps
# 直接使用 tsx 运行
npx tsx tools/create-dependency-graph.ts
```
**输出文件：**
- `docs/architecture/DEPENDENCY_GRAPH.md` - Markdown 格式文档
- `docs/architecture/dependency-graph.json` - JSON 数据结构
**生成内容包括：**
- 外部依赖（npm 包）
- Node.js 内置依赖
- 内部依赖（相对导入）
- 导出的类、接口、函数、常量
- 循环依赖分析
- Mermaid 可视化图表
- 统计摘要
资料来源：[tools/create-dependency-graph/README.md:1-50]()
## 环境变量配置
工具行为可通过以下环境变量配置：
| 变量 | 描述 | 默认值 |
|------|------|--------|
| `MEMORY_FILE_PATH` | 存储文件路径 | `memory.jsonl`（当前目录） |
| `MEMORY_STORAGE_TYPE` | 存储类型 | `jsonl` |
| `MEMORY_EMBEDDING_PROVIDER` | 嵌入提供者 | `none` |
| `MEMORY_OPENAI_API_KEY` | OpenAI API 密钥 | — |
| `MEMORY_EMBEDDING_MODEL` | 嵌入模型名称 | `text-embedding-3-small` / `Xenova/all-MiniLM-L6-v2` |
| `MEMORY_AUTO_INDEX_EMBEDDINGS` | 自动索引嵌入 | `false` |
资料来源：[CLAUDE.md:45-52]()
## 添加工具流程
在项目中添加新的 MCP 工具需要以下步骤：
```mermaid
graph LR
A[定义工具 Schema] --> B[实现工具处理器]
B --> C[添加 E2E 测试]
C --> D[更新文档]
A1[toolDefinitions.ts] --> |同一分类区域| A
B1[toolHandlers.ts] --> |handler 逻辑| B
```
### 步骤 1：定义工具 Schema
在 `src/server/toolDefinitions.ts` 的适当分类区域添加 JSON Schema 定义：
```typescript
{
name: 'tool_name',
description: '工具功能描述',
inputSchema: {
type: 'object',
properties: {
paramName: { type: 'string', description: '参数描述' }
},
required: ['paramName'],
additionalProperties: false,
},
},
```
### 步骤 2：实现工具处理器
在 `src/server/toolHandlers.ts` 中添加工具处理器：
```typescript
tool_name: async (ctx, args) => {
// 1. 验证参数
const param = validateWithSchema(args.paramName, z.string(), 'Invalid param');
// 2. 调用管理器方法
const result = await getManager(ctx).method(param);
// 3. 返回格式化响应
return formatToolResponse(result);
},
```
### 步骤 3：添加测试
在 `tests/e2e/tools/` 目录下添加端到端测试。
资料来源：[CLAUDE.md:35-44]()
## 工具响应格式
所有工具返回遵循 MCP 协议的统一响应格式：
```typescript
// 成功响应
{
content: [{ type: 'text', text: JSON.stringify(result) }]
}
// 错误响应
{
isError: true,
content: [{ type: 'text', text: errorMessage }]
}
```
### 格式化辅助函数
| 函数 | 用途 |
|------|------|
| `formatToolResponse()` | 格式化工具返回数据为 MCP 响应 |
| `formatTextResponse()` | 格式化纯文本响应 |
| `validateWithSchema()` | 使用 Zod schema 验证输入参数 |
## 错误处理
工具调度采用统一的错误处理机制：
```mermaid
graph TD
A[工具调用] --> B[handleToolCall]
B --> C{执行中异常?}
C -->|是| D[捕获异常]
D --> E[返回 MCP 错误响应]
C -->|否| F[返回正常响应]
E --> G{isError 字段}
F --> G
```
`handleToolCall` 会捕获处理器中的所有异常，并将其作为 MCP 格式的错误响应返回。调试时可检查响应的 `isError` 字段。
资料来源：[CLAUDE.md:57-59]()
## 存储后端
工具支持两种存储后端：
### JSONL 存储
- 数据文件：`memory.jsonl`、`memory-saved-searches.jsonl`、`memory-tag-aliases.jsonl`
- 位于项目根目录
- 适合小型部署和版本控制
### SQLite 存储
- 数据文件：`memory.db`
- 设置 `MEMORY_STORAGE_TYPE=sqlite` 启用
- 使用 `better-sqlite3` 实现原生性能
- 适合生产环境和大规模数据
资料来源：[CLAUDE.md:12-16]()
## 版本历史
| 版本 | 描述 |
|------|------|
| v12.3.0 (Phase 16) | 添加 53 个工具，涵盖 do_not_remember、决策理由、工具能力等 |
| v12.2.0 (Phase 15) | 添加 23 个工具，支持双时态有效性、OCC、RBAC、程序性记忆等 |
| v2.1.0 | memoryjs 核心库版本，支持完整工具集 |
资料来源：[CLAUDE.md:3-7]()
---
本参考手册涵盖了 Memory MCP 的所有工具定义和使用方法。如需更多信息，请参考项目文档或查看源代码。
---
---
## Doramagic 踩坑日志
项目：danielsimonjr/memory-mcp
摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。
## 1. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | README/documentation is current enough for a first validation pass.
## 2. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | last_activity_observed missing
## 3. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | no_demo; severity=medium
## 4. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | No sandbox install has been executed yet; downstream must verify before user use.
## 5. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | no_demo; severity=medium
## 6. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | issue_or_pr_quality=unknown
## 7. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | release_recency=unknown