MCP Server Memory

An MCP server for enabling persistent memory for Claude through a knowledge graph with entity-note relations.

Version 0.7.0 Update: From Observations to Notes

Version 0.7.0 introduces a significant change to the data model: "observations" have been replaced with "notes". Notes are now separate entities in the knowledge graph, linked to other entities via relationships, instead of being embedded as arrays within entities.

Benefits of the New Model

• More Flexible Representation: Notes are first-class citizens in the graph
• Better Performance: Easier to query and update individual notes
• Enhanced Relationships: Notes can have their own properties and relationships
• Improved Scalability: More efficient storage and retrieval for entities with many notes

Version 0.8.0 Update: Task Management

Version 0.8.0 introduces a comprehensive task management system, allowing you to create and manage hierarchical tasks with notes and references.

Task Management Features

• Hierarchical Tasks: Create complex task trees with parent-child relationships
• Sibling Ordering: Tasks maintain a specific order among siblings at the same level
• Task Notes: Add notes to tasks for additional context
• Entity References: Link tasks to any other entity in the knowledge graph
• Task Completion: Mark tasks as complete or incomplete
• Markdown Visualization: Generate structured representations of task hierarchies

Installation

npm install -g @modelcontextprotocol/server-memory

Or install locally in your project:

npm install @modelcontextprotocol/server-memory

Usage

Running the Server

mcp-server-memory

By default, this will store memory in a memory.json file in the same directory as the script.

Environment Variables

• MEMORY_FILE_PATH: Specify a custom path for the memory file (default: memory.json in the server directory)

Project-Specific Memory

You can create project-specific memory graphs by passing the projectName parameter to the MCP tools. This will automatically create separate memory files for each project.

Migrating from Observations to Notes

If you have existing data using the old format (with observations embedded in entities), you can use the included migration script to convert to the new format:

node migrate-observations-to-notes.js [memory-file-path]

This script will:

1. Back up your original file with a .bak extension
2. Convert all observations to note entities
3. Create "has_note" relationships connecting entities to their notes

API Overview

The server exposes the following tools through the MCP protocol:

Entity Management

• create_entities: Create multiple entities in the knowledge graph
• delete_entities: Delete entities and their associated relations

Note Management

• add_notes: Add notes to an entity
• delete_notes: Delete specific notes from entities
• get_entity_notes: Get all notes associated with an entity

Relation Management

• create_relations: Create relationships between entities
• delete_relations: Delete relationships

Task Management

• create_task: Create a standalone task
• create_tasklist: Create a task with multiple subtasks (accepts tasklistName and list of task strings)
• add_subtask: Add a single subtask to an existing task
• add_subtask_list: Add multiple subtasks to an existing task (accepts parentTaskId and list of task strings)
• complete_task: Mark a task as completed
• uncomplete_task: Mark a task as uncompleted
• add_task_note: Add a note to a task
• add_task_reference: Add a reference from a task to another entity
• visualize_tasks: Generate a markdown representation of the task hierarchy

Graph Operations

• read_graph: Read the entire knowledge graph in slim format (with note counts)
• read_full_graph: Read the entire graph including all notes (may be large)
• search_nodes: Search for nodes by name, type, or note content
• open_nodes: Open specific nodes by name
• find_paths: Find paths between two nodes
• get_subgraph: Extract a subgraph around a specific node
• analyze_graph: Get metrics and insights about the graph
• visualize_graph: Generate a DOT format visualization of the graph

Data Model

The knowledge graph uses the following primary elements:

• Entities: Named objects with a type (e.g., Person, Project, Technology)
• Notes: Content associated with entities
• Tasks: Structured work items organized in a hierarchy
• Relations: Directed connections between entities with a type

Task Management Examples

Creating a Task with Subtasks (Simplified API)

const result = await client.callTool("create_tasklist", {
  projectName: "my-project",
  tasklistName: "Project Migration",
  tasks: [
    "Research",
    "Planning",
    "Execution",
    "Testing"
  ]
});

// Get the main task ID from the returned array (first element)
const mainTaskId = result[0].id;

Adding Subtasks to an Existing Task (Simplified API)

await client.callTool("add_subtask_list", {
  projectName: "my-project",
  parentTaskId: "task_1234567890",
  tasks: [
    "Unit Tests",
    "Integration Tests",
    "Performance Tests"
  ]
});

Marking a Task as Complete

await client.callTool("complete_task", {
  projectName: "my-project",
  taskId: "task_1234567890"
});

Adding a Note to a Task

await client.callTool("add_task_note", {
  projectName: "my-project",
  taskId: "task_1234567890",
  content: "This task is blocked by the database migration"
});

Visualizing the Task Hierarchy

const markdown = await client.callTool("visualize_tasks", {
  projectName: "my-project",
  includeNotes: true,
  includeReferences: true
});

console.log(markdown);

This will generate a markdown representation like:

# Task List

- [ ] **Project Migration**: Migrate the application to the new platform (ID: task_1234567890)
  - 📝 _Note: This task is blocked by the database migration_
  - [ ] **Research**: Evaluate migration options (ID: task_0987654321)
  - [ ] **Planning**: Create detailed plan (ID: task_1122334455)
  - [ ] **Execution**: Perform the migration (ID: task_5566778899)
  - [x] **Testing**: Verify the migration (ID: task_9900112233)
    - [ ] **Unit Tests** (ID: task_5544332211)
    - [ ] **Integration Tests** (ID: task_6677889900)
    - [ ] **Performance Tests** (ID: task_1122334455)

License

MIT