README.md•4.09 kB
# 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 `context`s. 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:**
```tree
/path/to/memory/folder/
├── memory.jsonl # The 'main' Database (Core Index)
├── memory-work.jsonl # Work Context
└── memory-personal.jsonl # Personal Context
```