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 identifiableaim_
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:
- Project with
.aim
- Uses.aim/memory.jsonl
(project-local) - No project/no .aim - Uses configured global directory
- 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
:
This creates memory files in your specified directory:
memory.jsonl
- Master Database (default for all operations)memory-work.jsonl
- Work databasememory-personal.jsonl
- Personal database- etc.
Project-Local Memory
In any project, create a .aim
directory:
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:
File Organization
Global Setup:
Project Setup:
Available Tools
aim_create_entities
- Add new people, projects, eventsaim_create_relations
- Link entities togetheraim_add_observations
- Add facts to existing entitiesaim_search_nodes
- Find information by keywordaim_read_graph
- View entire memoryaim_open_nodes
- Retrieve specific entities by nameaim_list_databases
- Show all available databases and current locationaim_delete_entities
- Remove entitiesaim_delete_observations
- Remove specific factsaim_delete_relations
- Remove connections
Parameters
context
(optional) - Specify named database (work
,personal
, etc.). Defaults to master databaselocation
(optional) - Forceproject
orglobal
storage location. Defaults to auto-detection
Database Discovery
Use aim_list_databases
to see all available databases:
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:
Custom location (e.g., Dropbox):
Auto-approve all operations:
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/
orls /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
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
持久内存的改进实现,使用具有可自定义 --memory-path 的本地知识图谱。这使得 Claude 能够在聊天过程中记住用户的相关信息。
Related MCP Servers
- AsecurityAlicenseAqualityA basic implementation of persistent memory using a local knowledge graph. This lets Claude remember information about the user across chats.Last updated -960,93066,283MIT License
- AsecurityAlicenseAqualityEnhances 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 -1360,93051MIT License
- -securityAlicense-qualityA persistent memory implementation using a local knowledge graph that lets Claude remember information about users across conversations.Last updated -6MIT License
- AsecurityAlicenseAqualityAn 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 -1145954JavaScriptMIT License