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目录 vs _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/云同步（跨设备访问）

{
  "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: "张三",
    entityType: "人物",
    observations: ["在会议中结识"]
  }]
})

// 工作数据库
aim_memory_store({
  context: "work",
  entities: [{
    name: "第四季度项目",
    entityType: "项目",
    observations: ["2024年12月截止"]
  }]
})

// 强制使用全局存储
aim_memory_store({
  location: "global",
  entities: [{
    name: "重要信息",
    entityType: "参考资料",
    observations: ["存储在全局主数据库"]
  }]
})

文件结构

全局配置：

/Users/yourusername/.aim/
├── memory.jsonl           # 主数据库
├── memory-work.jsonl      # 工作数据库
└── memory-personal.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（可选）- 指定命名数据库（默认为主数据库）
• location（可选）- 强制使用project或global存储位置

数据库发现

使用aim_memory_list_stores查看所有数据库：

{
  "project_databases": ["default", "project-work"],
  "global_databases": ["default", "work", "personal"],
  "current_location": "project (.aim目录已检测)"
}

要点说明：

• **"default"**表示各位置的主数据库
• current_location显示当前使用的存储位置
• 主数据库始终存在，命名数据库为可选扩展

配置示例

重要： 必须通过--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目录的项目中（使用项目本地存储）
• 否则使用全局--memory-path目录
• 使用aim_memory_list_stores查看当前存储位置
• 通过ls命令查看记忆文件

数据库过多：

• AI模型可能创建名称相似的数据库
• 可手动删除不需要的数据库文件
• 建议AI使用简单一致的命名
• 注意：主数据库始终作为默认选项存在

系统要求

• Node.js 18+
• 支持MCP协议的AI平台

开源协议

MIT