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记忆系统一目了然。

存储逻辑

文件位置优先级：

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：

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

这会在你指定的目录中创建记忆文件：

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

项目本地记忆

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

mkdir .aim

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

AI如何使用数据库

一旦配置好，AI模型默认使用主数据库，或者可以通过context参数指定命名数据库。新数据库会自动创建，无需设置：

// 主数据库（默认 - 不需要上下文）
aim_create_entities({
  entities: [{
    name: "John_Doe",
    entityType: "person",
    observations: ["在会议上遇到"]
  }]
})

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

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

// 特定位置的主数据库
aim_create_entities({
  location: "global",
  entities: [{
    name: "重要信息",
    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_create_entities - 添加新人物、项目、事件
• aim_create_relations - 将实体链接在一起
• aim_add_observations - 向现有实体添加事实
• aim_search_nodes - 通过关键词查找信息
• aim_read_graph - 查看整个记忆
• aim_open_nodes - 根据名称检索特定实体
• aim_list_databases - 显示所有可用数据库及其当前位置
• aim_delete_entities - 删除实体
• aim_delete__observations - 删除特定事实
• aim_delete_relations - 删除连接

参数

• context（可选） - 指定命名数据库（如work，personal等）。默认为主数据库
• location（可选） - 强制project或global存储位置。默认为自动检测

数据库发现

使用aim_list_databases查看所有可用数据库：

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

关键点：

• "default" = 在两个位置的主数据库
• 当前位置显示你是使用项目还是全局存储
• 主数据库存在于任何地方 - 它是你主要的记忆存储
• 命名数据库是特定主题的可选补充

配置示例

重要：始终指定--memory-path来控制你的记忆文件存储在哪里。

家目录：

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

自定义位置（例如Dropbox）：

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

自动批准所有操作：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-knowledge-graph",
        "--memory-path",
        "/Users/yourusername/.aim"
      ],
      "autoapprove": [
        "aim_create_entities",
        "aim_create_relations",
        "aim_add_observations",
        "aim_search_nodes",
        "aim_read_graph",
        "aim_open_nodes",
        "aim_list_databases"
      ]
    }
  }
}

故障排除

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

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

记忆文件出现在意外的位置：

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

太多相似的数据库：

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

要求

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

许可证

MIT