MCP 知识图谱

通过本地知识图谱为 AI 模型提供持久化内存。

使用实体、关系和观察，在多轮对话中存储和检索信息。兼容 Claude Code/Desktop 以及任何与 MCP 兼容的 AI 平台。

为什么使用 .aim 和 aim_ 前缀？

AIM 代表 AI 内存——这是本系统的核心概念。三个 AIM 元素提供了清晰的组织结构和安全性：

• .aim 目录：使 AI 内存文件井然有序且易于识别
• aim_ 工具前缀：在多工具设置中将相关内存功能归类在一起
• _aim 安全标记：每个内存文件都以 {"type":"_aim","source":"mcp-knowledge-graph"} 开头，以防止意外覆盖无关的 JSONL 文件

这种一致的 AIM 命名方式，使得哪些目录、工具和文件属于 AI 内存系统一目了然。

重要提示：理解 .aim 目录与 _aim 文件标记的区别

两个名称相似但用途不同的概念：

• .aim = 项目本地目录名称（必须精确命名为 .aim，项目检测才能生效）
• _aim = 文件安全标记（出现在 JSONL 文件内部：{"type":"_aim","source":"mcp-knowledge-graph"}）

对于项目本地存储：

• 目录必须命名为项目根目录下的 .aim
• 示例：my-project/.aim/memory.jsonl
• 系统会专门查找这个确切的名称

对于全局存储 (--memory-path)：

• 可以是您希望的任意目录
• 示例：~/yourusername/.aim/、~/memories/、~/Dropbox/ai-memory/、~/Documents/ai-data/
• 完全灵活——选择适合您的位置即可

存储逻辑

文件位置优先级：

1. 有 .aim 的项目——使用 .aim/memory.jsonl（项目本地）
2. 无项目或无 .aim——使用配置的全局目录
3. 上下文区分——添加后缀：memory-work.jsonl、memory-personal.jsonl

安全机制：

• 每个内存文件都以 {"type":"_aim","source":"mcp-knowledge-graph"} 开头
• 系统拒绝写入没有此标记的文件
• 防止意外覆盖无关的 JSONL 文件

主数据库概念

主数据库是您的主要内存存储——在未指定特定数据库时默认使用。它在列表中始终名为 default，并以 memory.jsonl 的形式存储。

• 默认行为：所有内存操作都会使用主数据库，除非您指定其他数据库
• 始终可用：存在于项目本地和全局位置
• 主要存储：您跨所有对话持续存在的主要知识图谱
• 命名数据库：可选的附加数据库（work、personal、health），用于按主题组织内容

核心功能

• 主数据库：默认用于所有操作的主要内存存储
• 多数据库：可选的命名数据库，用于按主题组织记忆
• 项目检测：自动使用 .aim 目录进行项目本地内存管理
• 位置覆盖：强制操作使用项目或全局存储
• 安全操作：内置保护机制，防止覆盖无关文件
• 数据库发现：列出两地的所有可用数据库

快速入门

全局内存（推荐）

将以下内容添加到您的 claude_desktop_config.json 或 .claude.json 中。两种常见方法：

选项 1：默认 .aim 目录（简单）

{
  "mcpServers": {
    "Aim-Memory-Bank": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-knowledge-graph",
        "--memory-path",
        "/Users/yourusername/.aim"
      ]
    }
  }
}

选项 2：Dropbox/云同步（便携式）

若需在多台设备上访问记忆，可以使用同步文件夹。这就是本 MCP 服务器作者保存自己记忆的方式：

{
  "mcpServers": {
    "Aim-Memory-Bank": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-knowledge-graph",
        "--memory-path",
        "/Users/yourusername/Dropbox/ai-memory"
      ]
    }
  }
}

这会在您指定的目录中创建内存文件：

• memory.jsonl——主数据库（所有操作的默认数据库）
• memory-work.jsonl——工作数据库
• memory-personal.jsonl——个人数据库
• 等等。

项目本地内存

在任何项目中，创建一个 .aim 目录：

mkdir .aim

现在，内存工具从该项目运行时，会自动使用 .aim/memory.jsonl（项目本地的主数据库），而不是全局存储。

AI 如何使用数据库

配置完成后，AI 模型会默认使用主数据库，也可以通过 context 参数指定命名数据库。新数据库会自动创建——无需额外设置：

// 主数据库（默认——无需上下文）
aim_memory_store({
  entities: [{
    name: "John_Doe",
    entityType: "person",
    observations: ["在会议上见过"]
  }]
})

// 工作数据库
aim_memory_store({
  context: "work",
  entities: [{
    name: "Q4_Project",
    entityType: "project",
    observations: ["截止日期为 2024 年 12 月"]
  }]
})

// 个人数据库
aim_memory_store({
  context: "personal",
  entities: [{
    name: "Mom",
    entityType: "person",
    observations: ["生日是 3 月 15 日"]
  }]
})

// 在特定位置的主数据库
aim_memory_store({
  location: "global",
  entities: [{
    name: "Important_Info",
    entityType: "reference",
    observations: ["存储于全局主数据库"]
  }]
})

文件组织

全局设置：

/Users/yourusername/.aim/
├── memory.jsonl           # 主数据库（默认）
├── memory-work.jsonl      # 工作数据库
├── memory-personal.jsonl  # 个人数据库
└── memory-health.jsonl    # 健康数据库

项目设置：

my-project/
├── .aim/
│   ├── memory.jsonl       # 项目主数据库（默认）
│   └── memory-work.jsonl  # 项目工作数据库
└── src/

可用工具

• aim_memory_store——存储新记忆（人物、项目、概念）
• aim_memory_add_facts——向现有记忆添加事实
• aim_memory_link——连接两条记忆
• aim_memory_search——按关键词搜索记忆
• aim_memory_get——按精确名称检索特定记忆
• aim_memory_read_all——读取某个数据库中的所有记忆
• aim_memory_list_stores——列出可用数据库
• aim_memory_forget——遗忘记忆
• aim_memory_remove_facts——从记忆中移除特定事实
• aim_memory_unlink——移除记忆之间的链接

参数

• context（可选）——指定命名数据库（work、personal 等）。默认为主数据库
• location（可选）——强制使用“project”或“global”存储位置。默认为自动检测

数据库发现

使用 aim_memory_list_stores 可查看所有可用的数据库：

{
  "project_databases": [
    "default",      // 主数据库（项目本地）
    "project-work"  // 命名数据库
  ],
  "global_databases": [
    "default",      // 主数据库（全局）
    "work",
    "personal",
    "health"
  ],
  "current_location": "project (.aim 目录已检测到)"
}

要点：

• “default” = 在两个位置都是主数据库
• 当前位置 显示您正在使用项目存储还是全局存储
• 主数据库在任何地方都存在——它是您的主要记忆存储
• 命名数据库 是针对特定主题的可选补充

配置示例

重要提示： 始终指定 --memory-path 来控制您的记忆文件存储位置。

自动批准读取操作（推荐）：

{
  "mcpServers": {
    "Aim-Memory-Bank": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-knowledge-graph",
        "--memory-path",
        "/Users/yourusername/.aim"
      ],
      "autoapprove": [
        "aim_memory_search",
        "aim_memory_get",
        "aim_memory_read_all",
        "aim_memory_list_stores"
      ]
    }
  }
}

故障排除

“文件不包含所需的 _aim 安全标记”错误：

• 该文件可能不属于本系统
• 手动创建的 JSONL 文件需要以 {"type":"_aim","source":"mcp-knowledge-graph"} 作为第一行
• 如果您是手动创建的文件，请添加 _aim 标记，或删除后让系统重新创建

记忆存储到意外位置：

• 检查您是否位于包含 .aim 文件夹的项目目录中（使用项目本地存储）
• 否则将使用配置的全局 --memory-path 目录
• 使用 aim_memory_list_stores 查看所有可用数据库及当前位置
• 使用 ls .aim/ 或 ls /Users/yourusername/.aim/ 查看您的记忆文件

相似数据库过多：

• AI 模型会尝试使用一致的名称，但可能会产生变体
• 如有需要，可手动删除不需要的数据库文件
• 鼓励 AI 使用简单、一致的数据库名称
• 请记住：主数据库始终作为默认可用——命名数据库是可选的

系统要求

• Node.js 18+
• 兼容 MCP 的 AI 平台

许可证

MIT

mcp-knowledge-graph 快速上手指南

mcp-knowledge-graph 是一个通过本地知识图谱为 AI 模型提供持久化记忆的工具。它支持实体、关系和观察值的存储与检索，适用于 Claude Code/Desktop 及任何兼容 MCP 的 AI 平台。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 版本 18 或更高 (node -v 检查)
• MCP 兼容平台: 如 Claude Desktop、Claude Code 或其他支持 MCP 协议的 AI 客户端
• 包管理器: 确保 npx 可用（随 Node.js 安装）

安装步骤

该工具无需全局安装，可直接通过 npx 在 MCP 配置中运行。您需要编辑 AI 客户端的配置文件来注册此服务。

1. 选择存储路径

您可以选择两种存储模式：

• 全局记忆（推荐）：所有项目共享同一套记忆库，适合个人知识库。
• 项目本地记忆：记忆仅保存在当前项目的 .aim 目录中，适合隔离不同项目的上下文。

2. 配置 MCP 服务器

编辑您的 claude_desktop_config.json (Mac/Windows) 或 .claude.json 文件，添加以下配置。

方案 A：全局记忆（使用默认目录）

将记忆存储在用户主目录下的 .aim 文件夹中。

{
  "mcpServers": {
    "Aim-Memory-Bank": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-knowledge-graph",
        "--memory-path",
        "/Users/yourusername/.aim" 
      ]
    }
  }
}

注意：请将 /Users/yourusername/.aim 替换为您实际的系统路径。

• Windows 示例：C:\\Users\\YourName\\.aim
• Linux 示例：/home/yourusername/.aim

方案 B：云同步记忆（跨设备使用）

如果您希望在多台设备间同步记忆，可将路径指向 Dropbox、iCloud Drive 或坚果云等同步文件夹。

{
  "mcpServers": {
    "Aim-Memory-Bank": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-knowledge-graph",
        "--memory-path",
        "/Users/yourusername/Dropbox/ai-memory"
      ]
    }
  }
}

方案 C：启用自动批准（可选但推荐）

为了减少 AI 读取记忆时的确认弹窗，建议在配置中添加 autoapprove 字段：

{
  "mcpServers": {
    "Aim-Memory-Bank": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-knowledge-graph",
        "--memory-path",
        "/Users/yourusername/.aim"
      ],
      "autoapprove": [
        "aim_memory_search",
        "aim_memory_get",
        "aim_memory_read_all",
        "aim_memory_list_stores"
      ]
    }
  }
}

3. 项目本地记忆设置（可选）

如果您希望特定项目拥有独立的记忆库，只需在项目根目录下创建名为 .aim 的文件夹：

mkdir .aim

当 AI 在该目录下运行时，会自动优先使用 .aim/memory.jsonl 作为主数据库，而不会写入全局路径。

基本使用

配置完成后，重启您的 AI 客户端。AI 将自动调用以下工具来管理记忆。您也可以通过自然语言直接指令 AI 进行操作。

核心概念

• Master Database (默认): 所有操作默认使用名为 default 的主数据库（对应文件 memory.jsonl）。
• Context (上下文): 可通过 context 参数指定命名数据库（如 work, personal），系统会自动创建对应的 memory-work.jsonl 等文件。

使用示例

1. 存储新记忆

告诉 AI 记住某个事实，它会自动调用 aim_memory_store。

用户指令：

“请记住 John Doe 是我在会议上认识的人。”

底层调用示例（供参考）：

aim_memory_store({
  entities: [{
    name: "John_Doe",
    entityType: "person",
    observations: ["Met at conference"]
  }]
})

2. 分类存储记忆

您可以指定上下文将记忆存入特定数据库。

用户指令：

“在工作记忆中记下 Q4 项目截止日期是 2024 年 12 月。”

底层调用示例：

aim_memory_store({
  context: "work",
  entities: [{
    name: "Q4_Project",
    entityType: "project",
    observations: ["Due December 2024"]
  }]
})

3. 检索记忆

直接询问 AI 之前存储的信息。

用户指令：

“我关于妈妈的生日记了什么？”

底层调用示例：

aim_memory_get({
  context: "personal",
  name: "Mom"
})

4. 查看可用数据库

如果您想确认当前有哪些记忆库可用。

用户指令：

“列出所有可用的记忆数据库。”

底层调用示例：

aim_memory_list_stores()

常用工具列表

AI 可根据需求自动调用以下工具：

• aim_memory_store: 存储新实体（人、项目、概念）。
• aim_memory_add_facts: 向现有实体添加新事实。
• aim_memory_link: 建立两个实体间的关联。
• aim_memory_search: 通过关键词搜索记忆。
• aim_memory_forget: 删除指定的记忆。