mcp-knowledge-graph

The system uses a hierarchical storage model based on a Master Database and optional Named Databases (Contexts).

• Master Database: The primary store, always named default and stored as memory.jsonl. It is used by default if no context is specified.
• Named Databases (Contexts): Used to organize memories by topic (e.g., work, personal). These are stored as memory-{context}.jsonl (e.g., memory-work.jsonl).
• Storage Priority: The system first looks for a .aim directory in the current project. If not found, it falls back to the directory configured via --memory-path in your MCP settings.

New databases are created automatically when a new context is used; no manual setup is required.

To use memory that is specific to a single project, create a directory named exactly .aim in your project root. When the MCP server runs within this project context, it will automatically prioritize .aim/memory.jsonl as the master database instead of using the global storage path.

mkdir .aim

To set up a persistent global memory that is accessible across all conversations, add the server to your claude_desktop_config.json or .claude.json. You must specify a --memory-path to define where your memory files will reside.

Option 1: Standard local directory Use a hidden directory in your user home folder.

Option 2: Cloud-synced directory Use a folder within Dropbox or another cloud service to sync your AI memory across multiple machines.

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

If you encounter the error "File does not contain required _aim safety marker", it means the system is refusing to write to a JSONL file because it lacks the required safety header.

To fix this:

1. Manual Files: If you created a JSONL file manually, you must add {"type":"_aim","source":"mcp-knowledge-graph"} as the very first line.
2. Corrupted Files: Delete the file and let the system recreate it automatically.

This marker prevents the system from accidentally overwriting unrelated JSONL files.

Use aim_memory_list_stores to discover which databases exist in both your project-local and global storage locations, and to identify the current active storage location.

{
  "project_databases": [
    "default",
    "project-work"
  ],
  "global_databases": [
    "default",
    "work",
    "personal",
    "health"
  ],
  "current_location": "project (.aim directory detected)"
}

Use aim_memory_store to create new entities, relations, or observations. You can specify a context to route the information to a specific named database, or use the location parameter to force global or project storage.

// Store in the default Master Database
aim_memory_store({
  entities: [{ name: "John_Doe", entityType: "person", observations: ["Met at conference"] }]
})

// Store in the 'work' database
aim_memory_store({
  context: "work",
  entities: [{ name: "Q4_Project", entityType: "project", observations: ["Due December 2024"] }]
})

// Force storage to the global location
aim_memory_store({
  location: "global",
  entities: [{ name: "Important_Info", entityType: "reference", observations: ["Stored in global master database"] }]
})

The following tools are available for managing the knowledge graph. Most tools accept an optional context (to specify a named database) and an optional location (project or global).

- 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

The following tools allow for removing data from the knowledge graph:

aim_memory_forget

Removes entire entities and all their associated relations. Use this to completely erase a memory.

• Input: entityNames (array of strings).

aim_memory_remove_facts

Removes specific observations from an entity but keeps the entity itself in the graph.

• Input: deletions (array of { entityName, observations }).

aim_memory_unlink

Removes the connections (relations) between entities but keeps the entities themselves.

• Input: relations (array of { from, to, relationType }).

Use aim_memory_add_facts to append new observations to an entity that is already stored in the database.

Important

• The entity must already exist. This tool will throw an error if the entity is not found.

Examples

• Add to master database:

{ "observations": [{ "entityName": "John", "contents": ["Lives in Seattle", "Works in tech"] }] }

• Add to work context:

{ "context": "work", "observations": [{ "entityName": "Q4_Project", "contents": ["Behind schedule"] }] }

aim_memory_add_facts({
  context: "work",
  observations: [{ entityName: "Q4_Project", contents: ["Behind schedule"] }]
})

Use aim_memory_search for fuzzy, keyword-based searching when you don't know the exact name of an entity.

Search Scope

The query (case-insensitive) matches against:

• Entity names
• Entity types
• Observation contents

Parameters

• query: (Required) The search text.
• context: (Optional) The specific database to search within.
• format: (Optional) 'json' (default) or 'pretty' (human-readable text).

Example

{ "query": "Seattle", "format": "pretty" }

aim_memory_search({
  query: "Seattle",
  format: "pretty"
})

Use aim_memory_get when you know the exact names of the entities you want to retrieve. This is more efficient than aim_memory_search for direct lookups.

Parameters

• names: (Required) An array of exact entity names.
• context: (Optional) The database to query.
• format: (Optional) 'json' (default) or 'pretty' (human-readable text).

Example

{ "names": ["John", "TechConf2024"], "format": "pretty" }

aim_memory_get({
  names: ["John", "TechConf2024"],
  format: "pretty"
})