bm-graph-memory-mcp

A persistent, indexed knowledge graph for AI agents, designed for MCP-compatible platforms.

This project, Brikerman Graph Memory (bm-graph-memory), provides a persistent memory layer for AI models. It allows an AI to build and query a knowledge graph composed of entities, relationships, and observations. The system is designed around a core "index" database that ensures the AI always has access to its most critical information.

---

Core Concepts

The main Database: The System's Core Index

The entire system revolves around the main database. It is not just a general-purpose memory; it has a specific and critical function.

• Role: The main database acts as the core index and routing table for your entire memory system.
• Contents: It should contain only two types of information:
  1. Routing Information: A manifest of all other contexts that exist (e.g., work, personal). This helps the AI know what other specialized memories it can query.
  2. Critical Data: A very small amount of absolutely essential, high-level information that the AI must always be aware of.
• Constant Visibility: The entire contents of the main database are automatically appended to the results of every search operation. Whether you search globally or within a specific context, you always get the full main database back, ensuring the AI never loses sight of its core index.

Contexts: Specialized Memories

To keep information organized, you can use contexts. A context is a separate memory file for a specific topic.

• Examples: work, personal, project-alpha.
• Primary Use: Store detailed, topic-specific information in a named context. This keeps the main database clean and focused on its core indexing role.

Storage Location

The system determines where to store and retrieve files based on the MEMORY_FOLDER environment variable:

• If MEMORY_FOLDER is set, all memory files will be stored in that location.
• If MEMORY_FOLDER is not set, the system defaults to ~/.bm in the user's home directory.

The bm_gm Safety System

A consistent naming convention ensures clarity and safety. bm_gm stands for Brikerman Graph Memory.

• .bm directories: Identifies a folder as a Brikerman Memory storage location.
• bm_gm_ tool prefixes: Groups all memory functions together for the AI.
• _bm_gm safety marker: The first line of every memory file is {"type":"_bm_gm","source":"brikerman-graph-memory-mcp"}. The system will refuse to write to any file that doesn't start with this marker, preventing data corruption.

Available AI Tools (bm_gm_*)

The AI interacts with its memory using the following tools.

Core Tools

• memory_create_entities: Adds new entities (like people, places, or concepts) to the knowledge graph.
• memory_create_relations: Creates a labeled link between two existing entities.
• memory_add_observations: Adds a new piece of text information to an existing entity.
• memory_search_nodes: Searches for information using keywords. The results will always include the full contents of the main database.
• memory_read_graph: Dumps the entire content of one or more databases. The results will always include the full contents of the main database.

Management & Deletion Tools

• memory_list_databases: Shows all available memory databases (contexts).
• memory_delete_entities: Removes entities from the graph.
• memory_delete_relations: Removes specific relationships between entities.
• memory_delete_observations: Removes specific observations from an entity.

Common Parameters

• context (string): The named database to target (e.g., work). If not provided, the operation targets the main database.

File Organization Example

MEMORY_FOLDER directory:

/path/to/memory/folder/
├── memory.jsonl           # The 'main' Database (Core Index)
├── memory-work.jsonl      # Work Context
└── memory-personal.jsonl  # Personal Context