Multi-Memory MCP Server
A multi-category knowledge graph memory server using SQLite for persistent storage. Organize memories into isolated contexts for different purposes (work, personal, projects, etc.).
Based on @modelcontextprotocol/server-memory with enhancements:
- SQLite database storage with proper indexing and transactions
- Multi-category support with isolated memory contexts
- LRU connection cache (prevents memory leaks)
- ID-based operations - all objects have unique IDs for precise operations
- Dual identification - use ID or name/type composite key
- Custom properties - JSON properties on entities, observations, and relations (searchable)
- Override mode - update existing records instead of skipping duplicates
- SQL injection protection
- Full test coverage (141 tests)
Quick Start
Run Directly with npx (No Installation Required)
The fastest way to use multi-memory-mcp is to run it directly from GitHub using npx:
npx github:DanNsk/multi-memory-mcp
This will download, build, and run the server automatically. Perfect for trying it out or using in Claude Desktop config:
{
"mcpServers": {
"multi-memory": {
"command": "npx",
"args": ["github:DanNsk/multi-memory-mcp"],
"env": {
"MEMORY_BASE_DIR": "/path/to/.memory",
"DEFAULT_CATEGORY": "default"
}
}
}
}
Installation (Local Development)
git clone https://github.com/DanNsk/multi-memory-mcp
cd multi-memory-mcp
npm install
npm run build
Configuration
Add to Claude Desktop config:
Config file locations:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Using npx (recommended):
{
"mcpServers": {
"multi-memory": {
"command": "npx",
"args": ["github:DanNsk/multi-memory-mcp"],
"env": {
"MEMORY_BASE_DIR": "/Users/yourname/.memory",
"DEFAULT_CATEGORY": "default"
}
}
}
}
Using local installation (macOS/Linux):
{
"mcpServers": {
"multi-memory": {
"command": "node",
"args": ["/absolute/path/to/multi-memory-mcp/dist/index.js"],
"env": {
"MEMORY_BASE_DIR": "/Users/yourname/.memory",
"DEFAULT_CATEGORY": "default"
}
}
}
}
Using local installation (Windows):
{
"mcpServers": {
"multi-memory": {
"command": "node",
"args": ["C:\\path\\to\\multi-memory-mcp\\dist\\index.js"],
"env": {
"MEMORY_BASE_DIR": "C:\\Users\\yourname\\.memory",
"DEFAULT_CATEGORY": "default"
}
}
}
}
Environment Variables
MEMORY_BASE_DIR: Base directory for all memory categories (default:.aimin current working directory)DEFAULT_CATEGORY: Default category when none specified (default:"default")SERIALIZATION_FORMAT: Output format for tool responses (default:"json")json- Standard JSON with 2-space indentationtoon- TOON (Token-Oriented Object Notation) - compact format optimized for LLMs with 30-60% fewer tokens
TOON Format
When SERIALIZATION_FORMAT=toon, responses use TOON format which is more token-efficient for LLM contexts.
Structure:
- Objects:
key: valuewith 2-space indentation for nesting - Arrays:
name[count]{field1,field2}:followed by comma-separated rows - Primitives: unquoted unless containing special characters
Escaping rules (only these escape sequences are valid):
\\- backslash\"- double quote\n- newline\r- carriage return\t- tab
Quoting required when: empty string, leading/trailing spaces, matches true/false/null, numeric, or contains : " \ [ ] { } ,
Example JSON vs TOON:
JSON (standard):
{
"entities": [
{"id": "1", "name": "AuthService", "entityType": "module", "observations": []}
]
}
TOON (compact):
entities[1]{id,name,entityType,observations}:
1,AuthService,module,[]
See TOON specification for full format details.
Database Schema
Each category stores data in a separate SQLite database with the following schema:
Tables
entities
Primary storage for graph nodes.
| Column | Type | Description |
|---|---|---|
id | INTEGER PRIMARY KEY AUTOINCREMENT | Unique entity identifier |
name | TEXT NOT NULL | Entity name |
entity_type | TEXT NOT NULL | Entity classification type |
properties | TEXT | JSON properties (searchable) |
created_at | INTEGER | Unix timestamp of creation |
updated_at | INTEGER | Unix timestamp of last update |
Unique Constraint: (name, entity_type) - entities are identified by name+type combination
observations
Facts and notes associated with entities.
| Column | Type | Description |
|---|---|---|
id | INTEGER PRIMARY KEY AUTOINCREMENT | Unique observation identifier |
entity_id | INTEGER NOT NULL | Foreign key to entities(id) |
observation_type | TEXT NOT NULL DEFAULT '' | Type/category of observation |
content | TEXT NOT NULL | Observation text |
timestamp | TEXT | ISO 8601 timestamp |
source | TEXT NOT NULL DEFAULT '' | Origin of observation |
properties | TEXT | JSON properties (searchable) |
created_at | INTEGER | Unix timestamp of creation |
Foreign Key: entity_id → entities(id) ON DELETE CASCADE
Unique Constraint: (entity_id, observation_type, source) - one observation per type+source per entity
relations
Directed connections between entities.
| Column | Type | Description |
|---|---|---|
id | INTEGER PRIMARY KEY AUTOINCREMENT | Unique relation identifier |
from_entity_id | INTEGER NOT NULL | Foreign key to entities(id) - source entity |
to_entity_id | INTEGER NOT NULL | Foreign key to entities(id) - target entity |
relation_type | TEXT NOT NULL | Type of relationship |
properties | TEXT | JSON properties |
created_at | INTEGER | Unix timestamp of creation |
Foreign Keys:
from_entity_id→entities(id)ON DELETE CASCADEto_entity_id→entities(id)ON DELETE CASCADE
Unique Constraint: (from_entity_id, to_entity_id, relation_type)
Indexes
idx_entities_name- Fast lookup by entity nameidx_entities_type- Fast lookup by entity typeidx_entities_name_type- Fast lookup by name+type combinationidx_observations_entity- Fast lookup of observations by entityidx_relations_from- Fast lookup by source entityidx_relations_to- Fast lookup by target entityidx_relations_type- Fast lookup by relation type
Entity Relationship Diagram
┌─────────────────┐
│ entities │
├─────────────────┤
│ id (PK) │◄─────────────┬──────────────┐
│ name │ │ │
│ entity_type │ │ │
│ created_at │ │ │
│ updated_at │ │ │
└─────────────────┘ │ │
│ │
┌─────────────────┐ │ │
│ observations │ │ │
├─────────────────┤ │ │
│ id (PK) │ │ │
│ entity_id (FK) │──────────────┘ │
│ content │ (ON DELETE CASCADE) │
│ timestamp │ │
│ source │ │
│ created_at │ │
└─────────────────┘ │
│
┌─────────────────┐ │
│ relations │ │
├─────────────────┤ │
│ id (PK) │ │
│ from_entity_id │─────────────────────────────┤
│ to_entity_id │─────────────────────────────┘
│ relation_type │ (Both FK: ON DELETE CASCADE)
│ created_at │
└─────────────────┘
Notes:
- All IDs are auto-generated integers
- Deleting an entity cascades to delete all its observations and relations
- Relations store entity IDs, but API accepts name/type which is resolved to IDs
Core Concepts
Categories
Organize memories into separate isolated databases. Each category has its own SQLite database file.
Category naming rules:
- Lowercase letters, numbers, hyphens, underscores only
- Cannot start with dots
- Examples:
work,personal,project-alpha,dependencies
Directory structure:
.memory/
├── work.db
├── personal.db
└── project-alpha.db
Entities
Nodes in the knowledge graph with:
- id - Unique numeric identifier (auto-generated)
- name - Human-readable identifier
- entityType - Classification (e.g., "module", "class", "person", "project")
- observations - List of facts with metadata
{
"id": "1",
"name": "AuthService",
"entityType": "module",
"observations": [
{
"id": "1",
"observationType": "description",
"text": "Handles authentication",
"timestamp": "2025-11-19T10:30:00Z",
"source": "code-analysis"
},
{
"id": "2",
"observationType": "location",
"text": "Located in src/auth/",
"timestamp": "2025-11-19T10:31:00Z",
"source": "code-analysis"
}
]
}
Relations
Directed connections between entities with their own IDs:
{
"id": "1",
"from": "APIController",
"fromType": "controller",
"to": "AuthService",
"toType": "module",
"relationType": "depends_on"
}
Dual Identification
All operations support identifying objects by either:
- ID - Fast, precise, unambiguous
- Name/Type - Human-friendly composite key
This allows flexibility when you have the ID (e.g., from a previous response) or need to reference by name.
API Tools
All tools accept optional category parameter (defaults to DEFAULT_CATEGORY).
create_entities
Create new entities in the knowledge graph.
Input:
{
"category": "work",
"override": false,
"entities": [
{
"name": "UserService",
"entityType": "service",
"properties": {
"filePath": "/src/services/user.ts",
"tags": ["core", "authentication"]
},
"observations": [
{
"observationType": "description",
"text": "Manages user data",
"timestamp": "2025-11-19T10:00:00Z",
"source": "code-analysis",
"properties": {
"confidence": 0.95,
"lineNumber": 42
}
}
]
}
]
}
Notes:
entityTypedefaults to empty string- Observations are unique by (entity, observationType, source)
propertiesis optional JSON for custom metadata (searchable)override: truereplaces existing entities instead of skipping them
Output:
[
{
"id": "1",
"name": "UserService",
"entityType": "service",
"properties": {
"filePath": "/src/services/user.ts",
"tags": ["core", "authentication"]
},
"observations": [
{
"id": "1",
"observationType": "description",
"text": "Manages user data",
"timestamp": "2025-11-19T10:00:00Z",
"source": "code-analysis",
"properties": {
"confidence": 0.95,
"lineNumber": 42
}
}
]
}
]
create_relations
Create relationships between entities. Each endpoint can be specified by ID or name/type.
Input (using name/type):
{
"category": "work",
"override": false,
"relations": [
{
"from": {
"name": "APIController",
"type": "controller"
},
"to": {
"name": "UserService",
"type": "service"
},
"relationType": "uses",
"properties": {
"weight": 0.8,
"since": "2024-01-01"
}
}
]
}
Notes:
typedefaults to empty string if not providedpropertiesis optional JSON for custom metadataoverride: trueupdates existing relations instead of skipping them
Input (using IDs):
{
"category": "work",
"relations": [
{
"from": { "id": "1" },
"to": { "id": "2" },
"relationType": "uses"
}
]
}
Note: You can mix ID and name/type - e.g., from by ID and to by name/type.
Output:
[
{
"id": "1",
"from": "APIController",
"fromType": "controller",
"to": "UserService",
"toType": "service",
"relationType": "uses",
"properties": {
"weight": 0.8,
"since": "2024-01-01"
}
}
]
add_observations
Add observations to existing entities. Entity can be identified by ID or name/type.
Input (using name/type):
{
"category": "work",
"override": false,
"observations": [
{
"entityName": "UserService",
"entityType": "service",
"contents": [
{
"observationType": "version",
"text": "Updated to v2.0",
"timestamp": "2025-11-19T14:30:00Z",
"source": "changelog",
"properties": {
"semver": "2.0.0",
"breaking": true
}
},
{
"observationType": "feature",
"text": "Added caching",
"source": "changelog"
}
]
}
]
}
Note: override: true updates existing observations (matched by observationType+source) instead of skipping them.
Input (using entity ID):
{
"category": "work",
"observations": [
{
"entityId": "1",
"contents": [
{
"observationType": "version",
"text": "Updated to v2.0",
"timestamp": "2025-11-19T14:30:00Z",
"source": "release-notes"
}
]
}
]
}
Output:
[
{
"entityId": "1",
"entityName": "UserService",
"entityType": "service",
"addedObservations": [
{
"id": "3",
"observationType": "version",
"text": "Updated to v2.0",
"timestamp": "2025-11-19T14:30:00Z",
"source": "changelog",
"properties": {
"semver": "2.0.0",
"breaking": true
}
},
{
"id": "4",
"observationType": "feature",
"text": "Added caching",
"timestamp": "2025-11-19T14:30:01Z",
"source": "changelog"
}
]
}
]
delete_entities
Delete entities and their relations. Identify by ID or name/type.
Input (using name/type):
{
"category": "work",
"entities": [
{
"name": "UserService",
"entityType": "service"
}
]
}
Input (using ID):
{
"category": "work",
"entities": [
{ "id": "1" }
]
}
Output:
"Entities deleted successfully"
delete_observations
Delete specific observations. Identify by observation ID or by entity + observationType + source.
Input (using observation ID):
{
"category": "work",
"deletions": [
{ "id": "3" }
]
}
Input (using entity name + observationType + source):
{
"category": "work",
"deletions": [
{
"entityName": "UserService",
"entityType": "service",
"observationType": "version",
"source": "changelog"
}
]
}
Input (using entity ID + observationType + source):
{
"category": "work",
"deletions": [
{
"entityId": "1",
"observationType": "version",
"source": "changelog"
}
]
}
Output:
"Observations deleted successfully"
delete_relations
Delete relations. Identify by relation ID or composite key.
Input (using relation ID):
{
"category": "work",
"relations": [
{ "id": "1" }
]
}
Input (using composite key):
{
"category": "work",
"relations": [
{
"from": "APIController",
"fromType": "controller",
"to": "UserService",
"toType": "service",
"relationType": "uses"
}
]
}
Output:
"Relations deleted successfully"
read_graph
Get entire knowledge graph for a category.
Input:
{
"category": "work"
}
Output:
{
"entities": [
{
"id": "1",
"name": "UserService",
"entityType": "service",
"observations": [
{
"id": "1",
"text": "Manages user data",
"timestamp": "2025-11-19T10:00:00Z"
}
]
}
],
"relations": [
{
"id": "1",
"from": "APIController",
"fromType": "controller",
"to": "UserService",
"toType": "service",
"relationType": "uses"
}
]
}
search_nodes
Search by name, type, observation content, or properties (all searchable via FTS5).
Input:
{
"category": "work",
"query": "authentication"
}
Output:
{
"entities": [
{
"id": "2",
"name": "AuthService",
"entityType": "service",
"observations": [
{
"id": "5",
"text": "Handles authentication",
"timestamp": "2025-11-19T10:30:00Z"
}
]
}
],
"relations": [
{
"id": "3",
"from": "APIController",
"fromType": "controller",
"to": "AuthService",
"toType": "service",
"relationType": "uses"
}
]
}
open_nodes
Get specific entities. Identify by ID or name/type.
Input (using name/type):
{
"category": "work",
"entities": [
{
"name": "UserService",
"entityType": "service"
},
{
"name": "AuthService",
"entityType": "service"
}
]
}
Input (using IDs):
{
"category": "work",
"entities": [
{ "id": "1" },
{ "id": "2" }
]
}
Output:
{
"entities": [
{
"id": "1",
"name": "UserService",
"entityType": "service",
"observations": [...]
},
{
"id": "2",
"name": "AuthService",
"entityType": "service",
"observations": [...]
}
],
"relations": [
{
"id": "2",
"from": "UserService",
"fromType": "service",
"to": "AuthService",
"toType": "service",
"relationType": "depends_on"
}
]
}
list_categories
Get all available category names.
Input:
{}
Output:
["work", "personal", "project-alpha"]
delete_category
Delete entire category and its database.
Input:
{
"category": "old-project"
}
Output:
"Category 'old-project' deleted successfully"
Use Cases
Code Dependency Tracking
Track module dependencies per project:
{
"category": "backend-service",
"entities": [
{
"name": "AuthModule",
"entityType": "module",
"observations": [
{
"text": "Exports login, logout",
"source": "code-analysis"
}
]
},
{
"name": "UserModule",
"entityType": "module",
"observations": [
{
"text": "User CRUD operations",
"source": "documentation"
}
]
},
{
"name": "Database",
"entityType": "library",
"observations": [
{
"text": "PostgreSQL client"
}
]
}
]
}
Then create relations:
{
"category": "backend-service",
"relations": [
{
"from": { "name": "AuthModule", "type": "module" },
"to": { "name": "UserModule", "type": "module" },
"relationType": "imports"
},
{
"from": { "name": "AuthModule", "type": "module" },
"to": { "name": "Database", "type": "library" },
"relationType": "uses"
}
]
}
Query dependencies:
{"category": "backend-service", "query": "AuthModule"}
Multi-Project Organization
Separate categories per project:
project-frontend- Frontend dependenciesproject-backend- Backend dependenciesproject-mobile- Mobile app dependencies
Work/Personal Separation
Keep contexts isolated:
work- Professional contacts and projectspersonal- Personal notes and relationshipslearning- Study notes and resources
Development
Build
npm run build # Compile TypeScript
npm run watch # Watch mode
Testing
npm test # Run all tests (141 tests)
Coverage: SQLiteStorage 98%, CategoryManager 87%, KnowledgeGraphManager 100%
Project Structure
src/
├── index.ts # MCP server
├── storage/
│ └── SQLiteStorage.ts # Database operations
├── managers/
│ ├── CategoryManager.ts # Category lifecycle & LRU cache
│ └── KnowledgeGraphManager.ts # Graph operations
└── types/
└── graph.ts # Type definitions
tests/
├── storage/ # Storage layer tests
├── managers/ # Manager tests
├── integration/ # End-to-end tests
└── benchmarks/ # Performance benchmarks
Technical Details
Storage
- Database: SQLite 3 with WAL mode
- Schema: Single version, clean slate
- Indexes: On entity names, types, relations
- Transactions: ACID-compliant operations
- Connection Limit: Max 50 concurrent (LRU eviction)
Security
- Parameterized queries (SQL injection protection)
- Category name validation (path traversal prevention)
- Foreign key constraints
- Cascading deletes
Performance
- Indexed queries for fast lookups
- WAL mode for concurrent reads
- Connection caching with LRU eviction
- Batch operations via transactions
Troubleshooting
Database locked error
SQLite uses WAL mode which allows concurrent reads. If you get lock errors:
- Ensure no other process is writing to the database
- Check file permissions on the database directory
Memory growing over time
CategoryManager implements LRU cache with default 50 connection limit. Oldest connections automatically closed when limit reached.
License
MIT License
Original work Copyright (c) 2025 Anthropic, PBC Modified work Copyright (c) 2025 DanNsk
Based on @modelcontextprotocol/server-memory
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.