Mcp Knowledge Graph

MCP Knowledge Graph

通过本地知识图谱，为 AI 模型提供持久化记忆。

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

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

AIM 代表 AI Memory（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 参数指定命名数据库。新数据库会自动创建，无需设置：

// Master Database (default - no context needed)
aim_memory_store({
  entities: [{
    name: "John_Doe",
    entityType: "person",
    observations: ["Met at conference"]
  }]
})

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

// Personal database
aim_memory_store({
  context: "personal",
  entities: [{
    name: "Mom",
    entityType: "person",
    observations: ["Birthday March 15th"]
  }]
})

// Master database in specific location
aim_memory_store({
  location: "global",
  entities: [{
    name: "Important_Info",
    entityType: "reference",
    observations: ["Stored in global master database"]
  }]
})

文件组织

全局设置：

/Users/yourusername/.aim/
├── memory.jsonl           # Master Database (default)
├── memory-work.jsonl      # Work database
├── memory-personal.jsonl  # Personal database
└── memory-health.jsonl    # Health database

项目设置：

my-project/
├── .aim/
│   ├── memory.jsonl       # Project Master Database (default)
│   └── memory-work.jsonl  # Project Work database
└── 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",      // Master Database (project-local)
    "project-work"  // Named database
  ],
  "global_databases": [
    "default",      // Master Database (global)
    "work",
    "personal",
    "health"
  ],
  "current_location": "project (.aim directory detected)"
}

要点：

• "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"
      ]
    }
  }
}

故障排除

出现“File does not contain required _aim safety marker”错误：

• 该文件可能不属于此系统
• 手动创建的 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 22+
• 兼容 MCP 的 AI 平台

许可证

MIT