Labsco
shaneholloman logo

MCP Knowledge Graph

★ 870

from shaneholloman

Provides persistent memory for AI models using a local knowledge graph.

🔥🔥🔥🔥✓ VerifiedFreeQuick setup
#automation#database#maps#memory

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 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 the 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:

  • 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

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:

Copy & paste — that's it
// 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"]
 }]
})

File Organization

Global Setup:

Copy & paste — that's it
/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:

Copy & paste — that's it
my-project/
├── .aim/
│ ├── memory.jsonl # Project Master Database (default)
│ └── memory-work.jsonl # Project Work database
└── src/

Available Tools

  • aim_memory_store - Store new memories (people, projects, concepts)

  • aim_memory_add_facts - Add facts to existing memories

  • aim_memory_link - Link two memories together

  • aim_memory_search - Search memories by keyword

  • aim_memory_get - Retrieve specific memories by exact name

  • aim_memory_read_all - Read all memories in a database

  • aim_memory_list_stores - List available databases

  • aim_memory_forget - Forget memories

  • aim_memory_remove_facts - Remove specific facts from a memory

  • aim_memory_unlink - Remove links between memories

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_memory_list_stores to see all available databases:

Copy & paste — that's it
{
 "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

License

MIT