概述

Memory MCP 是一个基于 Model Context Protocol (MCP) 的增强型记忆管理服务器，通过 MCP 协议为 AI 代理提供持久化记忆能力。该项目作为 MCP 服务器运行，封装了 @danielsimonjr/memoryjs 核心库的所有功能，向 AI 代理暴露 213 个工具函数，覆盖 58 个功能类别。资料来源：README.md

核心定位

Memory MCP 的设计目标是为 AI 代理提供类似于人类记忆的长期记忆存储与检索能力。通过知识图谱结构，代理可以：

• 持久化存储 - 将重要信息写入长期记忆
• 智能检索 - 根据语义、关键词、时间等多种维度检索记忆
• 层级管理 - 支持父子关系的层级记忆结构
• 衰减机制 - 自动对低价值记忆进行时间衰减
• 协同推理 - 支持多代理协作式的记忆综合分析

资料来源：CLAUDE.md

技术架构

分层架构设计

Memory MCP 采用清晰的分层架构，核心层由 memoryjs 库提供，MCP 层负责协议适配与工具暴露。

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

ManagerContext 核心组件

ManagerContext 是 memoryjs 库的核心类，采用懒加载模式初始化所有管理器实例。资料来源：CLAUDE.md

向后兼容性

src/index.ts 将 ManagerContext 重新导出为 KnowledgeGraphManager 别名，同时导出核心类型定义，确保与旧版 API 的兼容性。资料来源：CLAUDE.md

工具体系

工具分类总览

Memory MCP 提供 213 个工具函数，覆盖 58 个功能类别。资料来源：CLAUDE.md

工具处理流程

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

存储方案

存储类型

Memory MCP 支持两种存储后端，数据文件位于项目根目录（非 dist/ 目录）。资料来源：CLAUDE.md

数据迁移工具

tools/migrate-from-jsonl-to-sqlite 目录提供了独立的迁移工具，支持 JSONL 与 SQLite 格式之间的双向转换。资料来源：tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts

# 基本用法
migrate-from-jsonl-to-sqlite --from <source> --to <target>

# 显示详细进度
migrate-from-jsonl-to-sqlite --from memory.jsonl --to memory.db --verbose

依赖管理

核心依赖

开发依赖

版本演进

版本历史要点

Phase 16 (v12.3.0) 新增的功能包括：排除规则 (5)、决策理由与 ADR markdown 双写 (10)、结构化项目上下文 (12)、启发式指南 (10)、工具能力与观察管道 (11)、观察去重 (2)、拼写纠正 (3)。资料来源：CLAUDE.md

安装与使用

npm 包信息

# 安装
npm install @danielsimonjr/memory-mcp

# 或使用最新版本
npm install @danielsimonjr/memory-mcp@latest

资料来源：CLAUDE.md

构建与发布

项目使用 prepare 脚本在安装时自动构建，因此发布前无需单独执行构建命令。资料来源：CONTRIBUTING.md

# 发布到 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

开发指南

代码规范

• 遵循 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

配置选项

环境变量

TypeScript 配置

• 编译目标: ES2022
• 模块解析: Node16

相关资源

• npm 包: @danielsimonjr/memory-mcp
• 核心库: @danielsimonjr/memoryjs
• MCP 协议: Model Context Protocol
• 社区指南: MCP Community Guidelines

项目概述

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

前置要求

安装步骤

1. 全局安装

npm install -g @danielsimonjr/memory-mcp

2. 验证安装

安装完成后，系统会创建以下组件：

安装过程中 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 存储：

export MEMORY_STORAGE_TYPE=sqlite

使用 SQLite 时，所有数据存储在 memory.db 文件中。 资料来源：CLAUDE.md:30-35

工具类别总览

memory-mcp 提供 213 个工具，分为 58 个类别：

资料来源：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

数据流图

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 做贡献：

# 克隆仓库
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：

资料来源：CLAUDE.md:50-55

下一步

• 阅读 架构文档 深入了解系统设计
• 查看 工具参考 完整工具列表
• 参考 迁移指南 从旧版本升级

概述

memory-mcp 是一个基于 Model Context Protocol (MCP) 的知识图谱管理服务器，为 AI 代理提供持久化记忆能力。该项目采用分层架构设计，核心逻辑委托给 @danielsimonjr/memoryjs 库处理，而本仓库专注于 MCP 协议适配层、工具定义和请求处理。

核心职责：

• 将 memoryjs 的知识图谱能力暴露为 MCP 工具（当前版本共 213 个工具，覆盖 58 个类别）
• 处理 MCP 协议的请求/响应生命周期
• 提供多格式存储支持（JSONL 和 SQLite）
• 支持语义搜索、嵌入向量、权限控制等高级功能

资料来源：CLAUDE.md

概述

数据流处理是 memory-mcp 架构的核心机制，负责将 MCP（Model Context Protocol）工具调用转化为底层知识图谱操作，并确保大规模响应的有效传输。该系统采用分层架构，上层为 MCP 服务器，下层为核心库 @danielsimonjr/memoryjs，两者通过 ManagerContext 进行解耦通信。

核心职责：

• 接收并验证工具调用参数
• 路由至对应的 Manager 处理器
• 管理知识图谱实体的 CRUD 操作
• 对超过 256KB 的大规模响应自动压缩
• 支持多种存储后端（JSONL / SQLite）

资料来源：CLAUDE.md:1-5

系统架构

分层架构图

graph TD
    subgraph "memory-mcp (本仓库)"
        A["src/index.ts<br/>入口点"] --> B["MCPServer.ts<br/>MCP服务器"]
        B --> C["toolHandlers.ts<br/>工具处理器"]
        C --> D["responseCompressor.ts<br/>响应压缩器"]
    end
    
    subgraph "@danielsimonjr/memoryjs (npm依赖)"
        E["ManagerContext<br/>管理器上下文"]
        E --> F["EntityManager<br/>实体管理器"]
        E --> G["RelationManager<br/>关系管理器"]
        E --> H["SearchManager<br/>搜索管理器"]
        E --> I["ObservationManager<br/>观察管理器"]
        E --> J["IOManager<br/>IO管理器"]
    end
    
    D --> E
    F --> K["GraphStorage<br/>图存储"]
    G --> K
    H --> K
    I --> K
    J --> K
    
    K --> L["JSONL / SQLite<br/>存储后端"]

资料来源：CLAUDE.md:10-18

组件职责表

资料来源：CLAUDE.md:22-25

工具处理流程

标准处理管道

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

// 标准处理器示例 - 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 进行参数模式验证，支持类型约束和错误消息自定义：

function validateWithSchema<T>(
  value: unknown,
  schema: z.ZodType<T>,
  errorMessage: string
): T

验证失败时抛出错误，中断处理流程。 资料来源：src/server/toolHandlers.ts:3-5

过滤参数验证

对于可选的过滤参数，采用宽松验证策略——单个无效字段不会导致整个请求失败，而是使用管理器默认值：

function parseObservationDedupFilter(args: Record<string, unknown>): {
  entityType?: string | string[];
  projectId?: string;
  sessionId?: string;
  minOccurrences?: number;
  maxGroups?: number;
}

资料来源：src/server/toolHandlers.ts:85-93

响应压缩机制

压缩触发条件

资料来源：src/server/toolHandlers.ts:95-97

压缩工作流

graph TD
    A["handler返回ToolResponse"] --> B{"textContent?.type<br/>=== 'text'?"}
    
    B -->|是| C{"text.length<br/>> 256KB?"}
    B -->|否| Z["直接返回原始响应"]
    
    C -->|是| D["maybeCompressResponse"]
    C -->|否| Z
    
    D --> E{"compressed?"}
    E -->|是| F["包装为JSON.stringify<br/>{compressed: true, data}"]
    E -->|否| Z
    
    F --> G["返回压缩后的响应"]
    Z --> H["返回给客户端"]
    G --> H

压缩配置参数

资料来源：CLAUDE.md:42-48

存储层数据流

存储类型支持

存储文件位于项目根目录，而非 dist/ 构建目录。 资料来源：CLAUDE.md:54-56

数据流层级

graph LR
    subgraph "访问接口层"
        A["ManagerContext<br/>入口"]
    end
    
    subgraph "管理器层"
        B["EntityManager"]
        C["RelationManager"]
        D["SearchManager"]
        E["ObservationManager"]
        F["TagManager"]
        G["HierarchyManager"]
    end
    
    subgraph "存储抽象层"
        H["GraphStorage<br/>统一接口"]
    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 提供以下管理器访问：

资料来源：CLAUDE.md:25-30

工具分类数据流

按功能分类的处理器组

系统包含 213 个工具，分布在 58 个类别中：

资料来源：CLAUDE.md:31-46

大数据量工具处理

以下工具因可能返回无界结果集而被标记为需要压缩处理：

资料来源：src/server/toolHandlers.ts:98-101

响应格式化

格式化函数

系统提供两种响应格式化函数：

// 结构化响应 - 用于成功操作的 JSON 结构
function formatToolResponse(data: unknown): ToolResponse

// 文本响应 - 用于简单消息或未找到结果
function formatTextResponse(message: string): ToolResponse

ToolResponse 结构

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

功能特性

命令行用法

# 单文件压缩
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 支持存储格式间的迁移：

migrate-from-jsonl-to-sqlite --from <source> --to <target> [--verbose]

使用 better-sqlite3 实现原生 SQLite 性能。 资料来源：tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts:1-30

测试覆盖

测试统计

资料来源：CLAUDE.md:58-59

数据流相关测试

新增工具应按以下流程添加测试：

1. 在 tests/e2e/tools/ 目录添加端到端测试
2. 测试空图和大图场景
3. 验证导出格式正确性
4. 验证压缩机制触发条件

资料来源：CONTRIBUTING.md:25-30

扩展新工具数据流

添加新工具的标准流程

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 注册模式

// 在 toolHandlers.ts 中
export const toolHandlers = {
  [TOOL_NAME]: async (ctx, args) => {
    // 1. 参数验证
    // 2. 调用 manager
    // 3. 格式化响应
  },
};

资料来源：CLAUDE.md:33-37

最佳实践

性能优化建议

错误处理

• 参数验证失败：抛出包含具体字段名的错误
• 存储操作失败：向上传递错误，不做静默处理
• 网络相关：内存 MCP 无外部网络依赖，此项不适用

压缩策略选择

资料来源：tools/compress-for-context/compress-for-context.ts:18-22

资料来源：CLAUDE.md:1-10

1. 架构概述

memory-mcp 的实体与关系模型构建在 @danielsimonjr/memoryjs 库之上，通过分层架构提供服务能力。

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 核心管理器

资料来源：CLAUDE.md:18-28

2. 实体模型

实体是知识图谱中的核心节点，代表现实世界中的概念对象。

2.1 实体数据结构

interface Entity {
  id: string;              // 唯一标识符（UUID）
  name: string;            // 实体名称
  entityType?: string;     // 实体类型（如 "person", "project"）
  observations: string[]; // 关联的观察 ID 列表
  tags: string[];          // 标签数组
  metadata?: Record<string, unknown>; // 扩展元数据
  importance?: number;     // 重要性评分 (0-10)
  createdAt: string;       // ISO 时间戳
  updatedAt: string;       // ISO 时间戳
  archived?: boolean;      // 归档状态
}

2.2 实体操作工具

资料来源：src/server/toolDefinitions.ts:1-150

2.3 实体创建示例

// 工具调用示例：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 关系数据结构

interface Relation {
  id: string;              // 唯一标识符
  from: string;            // 源实体 ID 或名称
  to: string;              // 目标实体 ID 或名称
  relationType: string;    // 关系类型（如 "works_for", "knows"）
  metadata?: Record<string, unknown>; // 关系属性
  bidirectional?: boolean; // 是否双向关系
  createdAt: string;
}

3.2 关系类型示例

3.3 关系操作工具

资料来源：src/server/toolHandlers.ts:1-100

4. 观察模型

观察（Observation）是附加在实体上的事实片段，是知识图谱的信息载体。

4.1 观察数据结构

interface Observation {
  id: string;             // 唯一标识符
  entityId: string;        // 关联实体
  content: string;        // 事实内容
  normalizedContent?: string; // 规范化后的内容
  source?: string;         // 信息来源
  importance?: number;     // 重要性评分
  tags?: string[];         // 观察标签
  metadata?: Record<string, unknown>;
  createdAt: string;
  updatedAt: string;
}

4.2 观察操作工具

资料来源：src/server/toolDefinitions.ts:200-350

4.3 观察流程图

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 配置。

资料来源：CLAUDE.md:50-55

5.2 数据文件

# 项目根目录下的数据文件
memory.jsonl                    # 主数据（JSONL 格式）
memory-saved-searches.jsonl     # 保存的搜索查询
memory-tag-aliases.jsonl        # 标签别名映射
memory.db                       # SQLite 数据库

5.3 环境变量配置

资料来源：CLAUDE.md:45-49

6. 图遍历与算法

6.1 图遍历管理器

ctx.graphTraversal 提供图结构遍历能力：

// 可用的遍历方法
ctx.graphTraversal.bfs(from, to);           // 广度优先搜索
ctx.graphTraversal.dfs(from, to);           // 深度优先搜索
ctx.graphTraversal.findPath(from, to);      // 最短路径
ctx.graphTraversal.findAllPaths(from, to);  // 所有路径

6.2 图算法工具

6.3 图遍历示例

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 标签系统

// 标签操作
ctx.tagManager.add(entityId, tag);      // 添加标签
ctx.tagManager.remove(entityId, tag);   // 移除标签
ctx.tagManager.findByTag(tag);          // 按标签查询
ctx.tagManager.setImportance(entityId, score); // 设置重要性

7.2 层级结构

// 层级操作
ctx.hierarchyManager.setParent(childId, parentId);  // 设置父节点
ctx.hierarchyManager.getChildren(parentId);          // 获取子节点
ctx.hierarchyManager.getSubtree(nodeId);             // 获取子树
ctx.hierarchyManager.getAncestors(nodeId);           // 获取祖先链

8. 搜索功能

8.1 搜索类型

8.2 语义搜索配置

启用语义搜索需要配置嵌入模型：

# 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 导出格式

9.2 导出工具

// 导出图数据
export_graph({
  format: "json",      // json|csv|markdown|xml|json-ld
  includeArchived: false,
  redactPii: true      // PII 脱敏
})

资料来源：CLAUDE.md:30-35

10. 完整工作流示例

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://github.com/danielsimonjr/memory-mcp
• npm 包: @danielsimonjr/memory-mcp

概述

Memory MCP 的存储后端是整个系统的核心基础设施，负责持久化知识图谱数据。系统支持两种存储格式：JSONL（基于文本行的 JSON 格式）和 SQLite（关系型数据库）。存储后端通过 @danielsimonjr/memoryjs 库提供统一的访问接口，实现了数据的抽象化存储，使得上层业务逻辑无需关心底层存储细节。

项目的存储架构采用分层设计，memory-mcp 作为前端封装，通过 ManagerContext 访问 memoryjs 核心库提供的各种管理器，这些管理器再与底层存储层（GraphStorage 或 SQLiteStorage）进行交互。资料来源：CLAUDE.md

支持的存储格式

Memory MCP 支持两种存储后端格式，开发者可根据数据规模、性能需求和使用场景选择合适的格式。

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                        # 使用文档

安装与构建

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

命令行参数

使用示例

# 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

迁移流程

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)

实体是知识图谱中的节点，代表独立的概念、对象或事物。

关系 (Relation)

关系是连接两个实体的有向边，定义实体间的关联。

观察数据 (Observation)

观察数据是附加到实体的客观事实，支持数据归一化。

产物 (Artifact)

产物是工具输出、代码片段、API 响应等内容的存储容器。

产物类型枚举值包括：tool_output、code_snippet、api_response、search_result、file_content、user_input。资料来源：src/server/toolDefinitions.ts

存储配置

环境变量

安全配置示例

在容器化环境中，建议通过环境变量或 Kubernetes Secret 管理存储路径：

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

备份建议

# 备份存储文件
cp memory.jsonl memory.jsonl.backup
# 或对于 SQLite
cp memory.db memory.db.backup

性能优化

SQLite 性能特性

压缩管理

存储后端集成压缩管理器，支持以下操作：

• 重复检测：识别知识图谱中的重复实体
• 智能合并：合并重复数据，保留最新信息
• 自动压缩：根据配置阈值自动触发压缩
• 归档：将历史数据归档以优化活跃数据访问

资料来源：CLAUDE.md

依赖配置

npm 依赖

{
  "dependencies": {
    "@danielsimonjr/memoryjs": "^2.1.0",
    "@modelcontextprotocol/sdk": "^1.21.1",
    "zod": "^3.24.1"
  }
}

迁移工具依赖

{
  "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

工具构建

项目提供了便捷的脚本用于构建所有独立工具：

# 安装所有工具依赖
npm run tools:install

# 构建所有工具（包括迁移工具）
npm run tools:build

构建后的迁移工具位于 tools/migrate-from-jsonl-to-sqlite/ 目录，可生成独立的 Windows 可执行文件。资料来源：package.json

总结

Memory MCP 的存储后端提供了灵活、高效、可靠的数据持久化能力。通过支持 JSONL 和 SQLite 两种格式，开发者可以根据实际需求选择合适的存储方案。SQLite 后端凭借原生绑定、WAL 模式、FTS5 索引等特性，在生产环境中提供卓越的性能表现。独立的迁移工具简化了格式转换过程，而分层架构则确保了系统的可维护性和扩展性。

概述

层级嵌套（Hieararchy）是 memory-mcp 知识图谱系统中用于管理实体间父子关系和树形结构的核心功能模块。该模块通过 ctx.hierarchyManager 提供9个专用工具，支持实体间的父子树构建和子树遍历操作。

层级管理是知识图谱组织结构化信息的重要手段，允许用户将实体组织成树形层级关系，便于表达分类、归属、继承等概念。资料来源：CLAUDE.md:1。

架构设计

访问方式

层级管理器通过 ManagerContext 实例访问：

ctx.hierarchyManager

可用的层级操作方法包括：

资料来源：src/server/toolHandlers.ts:1

与其他模块的关系

┌─────────────────────────────────────────────┐
│           ManagerContext                     │
├─────────────────────────────────────────────┤
│  hierarchyManager ──────────────────────────▶│
│  ├── setEntityParent()                      │
│  ├── getChildren()                          │
│  ├── getParent()                            │
│  ├── getAncestors()                         │
│  ├── getDescendants()                       │
│  └── getSubtree()                           │
└─────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────┐
│        @danielsimonjr/memoryjs               │
│  (底层存储: EntityManager + 层级索引)         │
└─────────────────────────────────────────────┘

工具清单

工具分类：Hierarchy（共9个）

资料来源：CLAUDE.md:1

API 详细说明

set_entity_parent

设置或更新实体的父节点关系。

输入参数：

处理器实现：

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

获取指定实体的所有直接子节点。

输入参数：

处理器实现：

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

获取指定实体的直接父节点。

输入参数：

处理器实现：

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

获取指定实体的所有祖先节点（从直接父节点到根节点）。

输入参数：

处理器实现：

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

获取指定实体的所有后代节点（所有子节点、孙节点等）。

输入参数：

处理器实现：

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

获取指定实体及其所有后代组成的完整子树结构。

输入参数：

处理器实现：

get_subtree: async (ctx, args) => {
  // 处理器定义（截断显示）
  return formatToolResponse(await ctx.hierarchyManager.getSubtree(entityName));
}

使用流程

典型操作流程

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. 构建组织层级结构：

// 设置公司 -> 部门 -> 团队的层级关系
{
  "entityName": "后端团队",
  "parentName": "技术部"
}

{
  "entityName": "技术部",
  "parentName": "XX公司"
}

2. 查询实体信息：

// 获取某实体的所有祖先
{
  "entityName": "后端团队"
}

3. 遍历子树：

// 获取完整子树结构
{
  "entityName": "XX公司"
}

层级遍历算法

树形结构示意

                    ┌─────────────┐
                    │   根节点     │
                    │  (Root)     │
                    └──────┬──────┘
                           │
           ┌───────────────┼───────────────┐
           │               │               │
           ▼               ▼               ▼
    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
    │   节点A     │  │   节点B     │  │   节点C     │
    │ (Child 1)  │  │ (Child 2)   │  │ (Child 3)   │
    └──────┬─────┘  └──────┬─────┘  └─────────────┘
           │
           ▼
    ┌─────────────┐
    │   节点D     │
    │ (Grandchild)│
    └─────────────┘

各方法返回范围

存储机制

层级关系数据存储于项目的存储文件中，支持两种存储格式：

层级数据以实体属性的形式存储，由 memoryjs 库的底层存储系统管理。资料来源：CLAUDE.md:1

错误处理

工具处理器使用 validateWithSchema 进行参数校验：

最佳实践

1. 避免循环引用

设置父子关系时，应避免创建环形结构：

graph LR
    A --> B
    B --> C
    C --> A

系统不会自动检测循环引用，创建时请确保层级结构的有效性。

2. 合理设置层级深度

过深的层级会增加查询复杂度，建议：

• 保持层级深度在合理范围内（建议 ≤ 10 层）
• 对于过深的结构，考虑拆分为多个独立树

3. 批量操作优化

如需创建多个层级关系，建议按拓扑顺序执行，确保父节点先于子节点存在。

相关文档

更新日志

概述

memory-mcp 的搜索能力是该知识图谱系统的核心功能之一，通过多层架构提供从基础关键词匹配到高级语义理解的全面搜索能力。系统支持超过 20 种搜索工具，涵盖基础搜索、智能搜索、语义搜索三大类别，并提供保存搜索和定时搜索等高级功能。

搜索功能由 ManagerContext 中的多个管理器协同工作实现，包括 SearchManager（基础和高级搜索）、semanticSearch（语义向量搜索）和 rankedSearch（TF-IDF 排名搜索）。

搜索架构

分层搜索模型

graph TD
    A[用户查询] --> B[搜索路由层]
    B --> C{查询类型判断}
    C -->|基础关键词| D[SearchManager<br/>基础搜索]
    C -->|TF-IDF排名| E[rankedSearch<br/>排名搜索]
    C -->|向量相似度| F[semanticSearch<br/>语义搜索]
    C -->|时间范围| G[temporalSearch<br/>时序搜索]
    C -->|复合条件| H[IntelligentSearch<br/>智能搜索]
    
    D --> I[GraphStorage<br/>数据存储]
    E --> I
    F --> I
    G --> I
    H --> I
    
    I --> J[结果聚合]
    J --> K[排序与去重]
    K --> L[返回结果]

核心组件

搜索工具分类

1. 基础搜索（7 个工具）

基础搜索提供最常用的关键词和模式匹配功能。

#### 时间范围搜索

search_by_time 工具支持时序查询，允许用户限定搜索结果的时间范围：

// 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 个工具）

智能搜索提供更高级的查询理解和结果优化能力。

graph LR
    A[原始查询] --> B[analyze_query<br/>查询分析]
    B --> C[查询重写]
    C --> D[intelligent_search<br/>智能搜索]
    D --> E[reflected_search<br/>反思优化]
    E --> F[最终结果]

3. 语义搜索（3 个工具）

语义搜索基于嵌入向量（embeddings）实现语义级别的相似度匹配。

#### 环境配置

# 环境变量配置
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 个工具）

保存搜索允许用户存储和重用常用查询。

保存的搜索存储在 memory-saved-searches.jsonl 文件中。

搜索 API

核心参数

搜索工具定义示例

// 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

搜索流程

完整搜索流程

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. 错误处理：返回格式化的错误信息

// toolHandlers.ts 中的查询验证
const limit = args.limit !== undefined
  ? validateWithSchema(args.limit, z.number().int().min(1).max(1000), 'Invalid limit')
  : 50;

存储与索引

存储位置

搜索索引和数据文件位于项目根目录：

索引策略

最佳实践

1. 搜索策略选择

graph TD
    A[开始搜索] --> B{知道确切实体名?}
    B -->|是| C{需要语义匹配?}
    B -->|否| D{需要模糊匹配?}
    
    C -->|是| E[semantic_search<br/>语义搜索]
    C -->|否| F{需要排名?}
    
    D -->|是| G[fuzzy_search<br/>模糊搜索]
    D -->|否| H{需要布尔逻辑?}
    
    F -->|是| I[ranked_search<br/>排名搜索]
    F -->|否| J[search_entities<br/>基础搜索]
    
    H -->|是| K[boolean_search<br/>布尔搜索]
    H -->|否| L[auto_search<br/>自动选择]

2. 性能优化建议

• 批量搜索：使用 list_saved_searches 预加载常用查询
• 时间过滤：在有明确时间范围时使用 search_by_time
• 限制结果：合理设置 limit 参数避免返回过多结果
• 选择存储：大数据量场景使用 SQLite 存储

3. 常见查询模式

总结

memory-mcp 的搜索能力通过分层架构实现了从基础到高级的完整搜索覆盖。基础搜索满足日常查询需求，智能搜索提供查询理解和优化，语义搜索实现深度的语义理解能力。开发者应根据具体使用场景选择合适的搜索工具，以获得最佳的用户体验和性能表现。

1. 版本演进与功能概览

memory-mcp 的高级功能通过两个主要版本迭代实现：

资料来源：CLAUDE.md:3-10

2. 记忆衰减与优先级管理

系统提供基于时间的记忆重要性衰减机制，用于自动管理长期记忆的价值。

2.1 衰减工具

资料来源：src/server/toolDefinitions.ts:衰减工具定义

2.2 衰减流程

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 治理策略

资料来源：src/server/toolHandlers.ts:治理处理器

3.2 审计过滤器

interface AuditFilter {
  operation?: 'create' | 'update' | 'delete' | 'merge' | 'archive';
  agentId?: string;
  entityName?: string;
  fromTime?: string;  // 注意：使用 fromTime/toTime 而非 since/until
  toTime?: string;
}

3.3 治理架构

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 工件类型

资料来源：src/server/toolDefinitions.ts:工件类型定义

4.2 工件管理工具

4.3 工件创建参数

{
  content: string;           // 必填：存储为实体观察的内容
  toolName: string;          // 必填：生成此工件的来源工具名
  artifactType: ArtifactType; // 必填：工件分类
  description?: string;      // 可选：人类可读描述
  sessionId?: string;        // 可选：会话上下文，用于分组相关工件
}

资料来源：src/server/toolHandlers.ts:工件处理器

5. 上下文压缩工具

compress-for-context 工具用于将大型文件压缩至 LLM 上下文窗口可接受的大小。

5.1 压缩级别

资料来源：tools/compress-for-context/compress-for-context.ts:压缩级别定义

5.2 支持格式

• JSON、YAML、Markdown、CSV、TSV
• Text、Log、TypeScript、JavaScript
• XML、HTML

5.3 使用示例

# 单文件压缩
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 命令

6.2 分块元数据

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 分块流程

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 功能分类

资料来源：CLAUDE.md:6-10

7.2 ToolCallObserver 管道

该管道允许观察和记录工具调用模式，支持：

• 工具使用频率统计
• 调用链追踪
• 异常模式检测
• 性能监控

7.3 观察去重机制

自动检测并合并语义相同的观察，避免知识图谱中的冗余信息。

7.4 拼写纠正

支持三种语言的拼写纠正功能，提升搜索准确性：

• 搜索查询的拼写纠正
• 实体名称的拼写纠正
• 观察内容的拼写纠正

8. 依赖图生成工具

create-dependency-graph 工具扫描代码库并生成依赖文档。

8.1 功能特性

• 扫描 src/ 下所有 TypeScript 文件
• 解析导入和导出
• 检测循环依赖
• 生成统计信息
• 输出 Markdown 和 JSON 两种格式

8.2 生成的文档结构

docs/architecture/
├── DEPENDENCY_GRAPH.md      # 人类可读文档
└── dependency-graph.json     # 机器可读数据

8.3 输出内容

资料来源：tools/create-dependency-graph/README.md:功能说明

9. 存储与迁移

9.1 存储格式

9.2 迁移工具

migrate-from-jsonl-to-sqlite 工具支持两种格式的双向转换：

# 基本用法
migrate-from-jsonl-to-sqlite --from <source> --to <target>

# 详细输出
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. 环境变量配置

资料来源：CLAUDE.md:环境变量配置

11. 贡献与扩展指南

11.1 添加新工具流程

graph TD
    A[定义工具架构] --> B[添加 schema 到 toolDefinitions.ts]
    B --> C[添加处理器到 toolHandlers.ts]
    C --> D[验证参数和错误处理]
    D --> E[添加端到端测试]
    E --> F[更新文档]

11.2 代码规范

• 遵循 TypeScript 最佳实践
• 使用有意义的变量名
• 公共方法添加 JSDoc 注释
• 保持函数小而专注
• 一致缩进（2 空格）

资料来源：CONTRIBUTING.md:代码风格指南

概述

Memory MCP 提供了一套基于 Model Context Protocol 的工具集，用于与知识图谱进行交互。该项目包含 213 个工具，分布在 58 个分类中，涵盖了知识图谱的创建、查询、更新、压缩、导入导出等完整生命周期管理。

工具系统架构

工具系统采用分层架构设计：

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]

核心组件包括：

资料来源：CLAUDE.md:1-10

工具分类总览

资料来源：CLAUDE.md:18-33

核心实体工具

创建实体 (create_entity)

在知识图谱中创建新的实体节点。

输入参数：

返回值： 创建成功的实体对象，包含自动生成的唯一引用 ID

获取实体 (get_entity)

通过名称或引用 ID 检索实体信息。

输入参数：

更新实体 (update_entity)

修改现有实体的属性。

输入参数：

删除实体 (delete_entity)

从知识图谱中移除实体及其关联的关系和观察。

输入参数：

关系工具

创建关系 (create_relation)

在两个实体之间创建有向关系边。

输入参数：

获取关系 (get_relations)

查询满足特定条件的实体关系。

输入参数：

搜索工具

基础搜索 (search_entities)

在知识图谱中搜索实体。

输入参数：

排名搜索 (search_entities_ranked)

基于 TF-IDF 算法的加权排名搜索。

输入参数：

模糊搜索 (search_entities_fuzzy)

支持拼写容错的模糊匹配搜索。

输入参数：

布尔搜索 (search_entities_boolean)

支持 AND、OR、NOT 运算符的布尔搜索。

输入参数：

语义搜索 (semantic_search)

基于向量嵌入的语义相似度搜索。

输入参数：

资料来源：CLAUDE.md:26-27

标签管理工具

添加标签 (add_tags)

为实体添加一个或多个标签。

输入参数：

移除标签 (remove_tags)

从实体移除指定标签。

输入参数：

获取标签 (get_tags)

获取实体的所有标签。

输入参数：

列出所有标签 (list_tags)

返回知识图谱中的所有标签及其使用统计。

输入参数：

标签别名管理

用于管理标签的同义词和别名关系。

图算法工具

路径发现 (find_path)

使用 BFS 或 DFS 算法查找两个实体之间的路径。

输入参数：

连通分量 (get_connected_components)

识别知识图谱中的连通分量。

中心性分析 (calculate_centrality)

计算实体的度中心性或介数中心性。

输入参数：

导入导出工具

导出图谱 (export_graph)

将知识图谱导出为多种格式。

支持的格式：

输入参数：

资料来源：CLAUDE.md:32

导入图谱 (import_graph)

从外部文件导入知识图谱数据。

输入参数：

压缩与归档工具

检测重复 (find_duplicates)

识别知识图谱中的重复或高度相似的实体。

输入参数：

合并实体 (merge_entities)

将多个相似实体合并为一个。

输入参数：

运行压缩 (run_compression)

自动压缩知识图谱，移除冗余数据。

归档旧数据 (archive_old_entities)

将长期未访问的实体移至归档存储。

输入参数：

工件管理工具

用于存储和管理工具输出、代码片段、API 响应等工件。

创建工件 (create_artifact)

创建工件实体并获取稳定的自动生成引用。

输入参数：

artifactType 枚举值：

获取工件 (get_artifact)

通过引用或实体名称检索工件。

输入参数：

列出工件 (list_artifacts)

列出满足过滤条件的工件。

输入参数：

治理与审计工具

设置治理策略 (set_governance_policy)

配置实体的创建、更新、删除权限策略。

输入参数：

审计查询 (audit_query)

查询实体的操作历史日志。

输入参数：

衰减与显著性工具

运行衰减周期 (run_decay_cycle)

执行基于时间的显著性衰减计算。

获取衰减记忆 (get_decayed_memories)

列出重要性已降至阈值以下的记忆。

输入参数：

遗忘弱记忆 (forget_weak_memories)

批量删除重要性低于衰减阈值的记忆。

输入参数：

时间查询工具

按时间搜索 (search_by_time)

基于时间范围查询知识图谱数据。

输入参数：

独立工具集

项目还包含一组独立的命令行工具，位于 tools/ 目录下。

文件分块工具 (chunking-for-files)

用于将大型文件分割为适合编辑的块，或合并已分割的文件块。

# 分割文件
chunker split <file> [options]

# 合并块
chunker merge <manifest.json> [options]

# 查看状态
chunker status <manifest.json>

分割选项：

资料来源：tools/chunking-for-files/chunking-for-files.ts:1-50

上下文压缩工具 (compress-for-context)

使用 CTON（Context-optimized Notation）压缩格式压缩文件以适应 LLM 上下文窗口。

# 单文件压缩
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

压缩级别：

资料来源：tools/compress-for-context/compress-for-context.ts:1-40

存储迁移工具 (migrate-from-jsonl-to-sqlite)

在 JSONL 和 SQLite 存储格式之间迁移数据。

# 从 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 项目并生成依赖关系文档。

# 通过 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

环境变量配置

工具行为可通过以下环境变量配置：

资料来源：CLAUDE.md:45-52

添加工具流程

在项目中添加新的 MCP 工具需要以下步骤：

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 定义：

{
  name: 'tool_name',
  description: '工具功能描述',
  inputSchema: {
    type: 'object',
    properties: {
      paramName: { type: 'string', description: '参数描述' }
    },
    required: ['paramName'],
    additionalProperties: false,
  },
},

步骤 2：实现工具处理器

在 src/server/toolHandlers.ts 中添加工具处理器：

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 协议的统一响应格式：

// 成功响应
{
  content: [{ type: 'text', text: JSON.stringify(result) }]
}

// 错误响应
{
  isError: true,
  content: [{ type: 'text', text: errorMessage }]
}

格式化辅助函数

错误处理

工具调度采用统一的错误处理机制：

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

版本历史

资料来源：CLAUDE.md:3-7

Pitfall Log / 踩坑日志

项目：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