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. ## CRITICAL: Understanding `.aim` dir vs `_aim` file marker **Two different things with similar names:** - `.aim` = **Project-local directory name** (MUST be named exactly `.aim` for project detection to work) - `_aim` = **File safety marker** (appears inside JSONL files: `{"type":"_aim","source":"mcp-knowledge-graph"}`) **For project-local storage:** - Directory MUST be named `.aim` in your project root - Example: `my-project/.aim/memory.jsonl` - The system specifically looks for this exact name **For global storage (--memory-path):** - Can be ANY directory you want - Examples: `~/yourusername/.aim/`, `~/memories/`, `~/Dropbox/ai-memory/`, `~/Documents/ai-data/` - Complete flexibility - choose whatever location works for you ## 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 ### Global Memory (Recommended) Add to your `claude_desktop_config.json` or `.claude.json`: ```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: ```bash 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: ```json // 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:** ```tree /Users/youruse