Skip to main content
Glama

mcp-knowledge-graph

MCP Knowledge Graph

Persistent memory for AI models through a local knowledge graph.

Store and retrieve information across conversations using entities, relations, and observations. Works with Claude Code/Desktop and any MCP-compatible AI platform.

Why ".aim" and "aim_" prefixes?

AIM stands for AI Memory - the core concept of this knowledge graph system. The three AIM elements provide clear organization and safety:

  • .aim directories: Keep AI memory files organized and easily identifiable
  • aim_ tool prefixes: Group related memory functions together in multi-tool setups
  • _aim safety markers: Each memory file starts with {"type":"_aim","source":"mcp-knowledge-graph"} to prevent accidental overwrites of unrelated JSONL files

This consistent AIM naming makes it obvious which directories, tools, and files belong to our AI memory system.

Storage Logic

File Location Priority:

  1. Project with .aim - Uses .aim/memory.jsonl (project-local)
  2. No project/no .aim - Uses configured global directory
  3. Contexts - Adds suffix: memory-work.jsonl, memory-personal.jsonl

Safety System:

  • Every memory file starts with {"type":"_aim","source":"mcp-knowledge-graph"}
  • System refuses to write to files without this marker
  • Prevents accidental overwrite of unrelated JSONL files

Master Database Concept

The master database is your primary memory store - used by default when no specific database is requested. It's always named default in listings and stored as memory.jsonl.

  • Default Behavior: All memory operations use the master database unless you specify a different one
  • Always Available: Exists in both project-local and global locations
  • Primary Storage: Your main knowledge graph that persists across all conversations
  • Named Databases: Optional additional databases (work, personal, health) for organizing specific topics

Key Features

  • Master Database: Primary memory store used by default for all operations
  • Multiple Databases: Optional named databases for organizing memories by topic
  • Project Detection: Automatic project-local memory using .aim directories
  • Location Override: Force operations to use project or global storage
  • Safe Operations: Built-in protection against overwriting unrelated files
  • Database Discovery: List all available databases in both locations

Quick Start

Add to your claude_desktop_config.json or .claude.json:

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

This creates memory files in your specified directory:

  • memory.jsonl - Master Database (default for all operations)
  • memory-work.jsonl - Work database
  • memory-personal.jsonl - Personal database
  • etc.

Project-Local Memory

In any project, create a .aim directory:

mkdir .aim

Now memory tools automatically use .aim/memory.jsonl (project-local master database) instead of global storage when run from this project.

How AI Uses Databases

Once configured, AI models use the master database by default or can specify named databases with a context parameter. New databases are created automatically - no setup required:

// Master Database (default - no context needed) aim_create_entities({ entities: [{ name: "John_Doe", entityType: "person", observations: ["Met at conference"] }] }) // Work database aim_create_entities({ context: "work", entities: [{ name: "Q4_Project", entityType: "project", observations: ["Due December 2024"] }] }) // Personal database aim_create_entities({ context: "personal", entities: [{ name: "Mom", entityType: "person", observations: ["Birthday March 15th"] }] }) // Master database in specific location aim_create_entities({ location: "global", entities: [{ name: "Important_Info", entityType: "reference", observations: ["Stored in global master database"] }] })

File Organization

Global Setup:

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

Project Setup:

my-project/ ├── .aim/ │ ├── memory.jsonl # Project Master Database (default) │ └── memory-work.jsonl # Project Work database └── src/

Available Tools

  • aim_create_entities - Add new people, projects, events
  • aim_create_relations - Link entities together
  • aim_add_observations - Add facts to existing entities
  • aim_search_nodes - Find information by keyword
  • aim_read_graph - View entire memory
  • aim_open_nodes - Retrieve specific entities by name
  • aim_list_databases - Show all available databases and current location
  • aim_delete_entities - Remove entities
  • aim_delete_observations - Remove specific facts
  • aim_delete_relations - Remove connections

Parameters

  • context (optional) - Specify named database (work, personal, etc.). Defaults to master database
  • location (optional) - Force project or global storage location. Defaults to auto-detection

Database Discovery

Use aim_list_databases to see all available databases:

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

Key Points:

  • "default" = Master Database in both locations
  • Current location shows whether you're using project or global storage
  • Master database exists everywhere - it's your primary memory store
  • Named databases are optional additions for specific topics

Configuration Examples

Important: Always specify --memory-path to control where your memory files are stored.

Home directory:

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

Custom location (e.g., Dropbox):

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

Auto-approve all operations:

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

Troubleshooting

"File does not contain required _aim safety marker" error:

  • The file may not belong to this system
  • Manual JSONL files need {"type":"_aim","source":"mcp-knowledge-graph"} as first line
  • If you created the file manually, add the _aim marker or delete and let the system recreate it

Memories going to unexpected locations:

  • Check if you're in a project directory with .aim folder (uses project-local storage)
  • Otherwise uses the configured global --memory-path directory
  • Use aim_list_databases to see all available databases and current location
  • Use ls .aim/ or ls /Users/yourusername/.aim/ to see your memory files

Too many similar databases:

  • AI models try to use consistent names, but may create variations
  • Manually delete unwanted database files if needed
  • Encourage AI to use simple, consistent database names
  • Remember: Master database is always available as the default - named databases are optional

Requirements

  • Node.js 18+
  • MCP-compatible AI platform

License

MIT

Deploy Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

持久内存的改进实现,使用具有可自定义 --memory-path 的本地知识图谱。这使得 Claude 能够在聊天过程中记住用户的相关信息。

  1. 服务器名称
    1. 核心概念
      1. 实体
      2. 关系
      3. 观察
    2. API
      1. 工具
    3. 与 MCP 兼容平台一起使用
      1. 使用 Claude Desktop 进行设置
      2. 与其他 AI 平台的设置
      3. 自定义内存路径
      4. 系统提示
    4. 与其他AI模型的集成
      1. 执照

        Related MCP Servers

        • A
          security
          A
          license
          A
          quality
          A basic implementation of persistent memory using a local knowledge graph. This lets Claude remember information about the user across chats.
          Last updated -
          9
          60,930
          66,283
          MIT License
          • Apple
          • Linux
        • A
          security
          A
          license
          A
          quality
          Enhances user interaction through a persistent memory system that remembers information across chats and learns from past errors by utilizing a local knowledge graph and lesson management.
          Last updated -
          13
          60,930
          51
          MIT License
        • -
          security
          A
          license
          -
          quality
          A persistent memory implementation using a local knowledge graph that lets Claude remember information about users across conversations.
          Last updated -
          6
          MIT License
        • A
          security
          A
          license
          A
          quality
          An implementation of persistent memory for Claude using a local knowledge graph, allowing the AI to remember information about users across conversations with customizable storage location.
          Last updated -
          11
          459
          54
          JavaScript
          MIT License
          • Apple

        View all related MCP servers

        MCP directory API

        We provide all the information about MCP servers via our MCP API.

        curl -X GET 'https://glama.ai/api/mcp/v1/servers/shaneholloman/mcp-knowledge-graph'

        If you have feedback or need assistance with the MCP directory API, please join our Discord server