danielsimonjr/memory-mcp

Memory MCP Server

An enhanced fork of the official Model Context Protocol memory server with advanced features for hierarchical nesting, intelligent compression, semantic search, graph algorithms, archiving, advanced search, and multi-format import/export.

Enterprise-grade knowledge graph with 59 tools, hierarchical organization, semantic search with embeddings, graph traversal algorithms, duplicate detection, smart archiving, and sophisticated search capabilities for long-term memory management.

Table of Contents

• Features
• Quick Start
• Installation
• Core Concepts
• API Reference
• Configuration
• Development
• Documentation
• Contributing
• Changelog
• License

Features

Core Memory Capabilities

• Knowledge Graph Storage: Entity-Relation-Observation model for structured memory
• Persistent Memory: Information persists across chat sessions with JSONL or SQLite storage
• Dual Storage Backends: JSONL (human-readable) or SQLite with better-sqlite3 (3-10x faster, FTS5 search)
• Full CRUD Operations: Create, read, update, delete entities and relations
• Flexible Search: Text-based, fuzzy, boolean, semantic, and TF-IDF ranked search

Advanced Features

Comparison with Official Memory Server

Quick Start

1. Install from NPM

npm install -g @danielsimonjr/memory-mcp

Or use with npx (no installation required):

npx @danielsimonjr/memory-mcp

2. Configure Claude Desktop

Add to claude_desktop_config.json:

Using NPM Global Install:

{
  "mcpServers": {
    "memory": {
      "command": "mcp-server-memory"
    }
  }
}

Using NPX:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@danielsimonjr/memory-mcp"]
    }
  }
}

3. Restart Claude Desktop

Restart Claude Desktop to load the enhanced memory server.

4. Start Using

Tell Claude:

Please remember that I prefer TypeScript over JavaScript.
Tag this as "preferences" with importance 8.
Create a parent entity called "Development Preferences" and nest this under it.

Installation

Local Build

# Clone repository
git clone https://github.com/danielsimonjr/memory-mcp.git
cd memory-mcp

# Install and build
npm install
npm run build

# Run tests (2800+ tests)
npm test

# Type check
npm run typecheck

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["<PATH_TO>/memory-mcp/dist/index.js"],
      "env": {
        "MEMORY_FILE_PATH": "<PATH_TO>/memory.jsonl"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/memory-mcp/dist/index.js"]
    }
  }
}

Core Concepts

Entities

Primary nodes in the knowledge graph.

interface Entity {
  name: string;           // Unique identifier
  entityType: string;     // Classification
  observations: string[]; // Facts about the entity
  parentId?: string;      // Parent entity name for hierarchical nesting
  tags?: string[];        // Lowercase tags for categorization
  importance?: number;    // 0-10 scale for prioritization
  createdAt?: string;     // ISO 8601 timestamp
  lastModified?: string;  // ISO 8601 timestamp
}

Relations

Directed connections between entities.

interface Relation {
  from: string;           // Source entity name
  to: string;             // Target entity name
  relationType: string;   // Relationship type (active voice)
  createdAt?: string;     // ISO 8601 timestamp
  lastModified?: string;  // ISO 8601 timestamp
}

Observations

Discrete facts about entities. Each observation should be atomic and independently manageable.

API Reference

Complete Tool List (59 Tools)

Entity Operations (4 tools)

Relation Operations (2 tools)

Observation Management (3 tools)

Search (7 tools)

Intelligent Search (3 tools)

Semantic Search (3 tools)

Saved Searches (5 tools)

Tag Management (6 tools)

Tag Aliases (5 tools)

Hierarchical Nesting (9 tools)

Graph Algorithms (4 tools)

Graph Analytics (2 tools)

Compression & Archiving (4 tools)

Import & Export (2 tools)

Configuration

Environment Variables

Storage Backends

Using SQLite:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/memory-mcp/dist/index.js"],
      "env": {
        "MEMORY_STORAGE_TYPE": "sqlite",
        "MEMORY_FILE_PATH": "/path/to/data/memory.db"
      }
    }
  }
}

Storage Files

When you set MEMORY_FILE_PATH, the server automatically creates related files:

/your/data/directory/
├── memory.jsonl                    # Main knowledge graph
├── memory-saved-searches.jsonl     # Saved search queries
├── memory-tag-aliases.jsonl        # Tag synonym mappings
└── .backups/                       # Timestamped backups
    ├── backup_2026-01-08_10-30-00-123.jsonl
    └── backup_2026-01-08_10-30-00-123.jsonl.meta.json

Migration Tool

Convert between JSONL and SQLite formats:

cd tools/migrate-from-jsonl-to-sqlite
npm install && npm run build

# JSONL to SQLite
node dist/migrate-from-jsonl-to-sqlite.js --from memory.jsonl --to memory.db

# SQLite to JSONL
node dist/migrate-from-jsonl-to-sqlite.js --from memory.db --to memory.jsonl

Development

Prerequisites

• Node.js 18+
• npm 9+
• TypeScript 5.6+

Build Commands

npm install           # Install dependencies
npm run build         # Build TypeScript
npm test              # Run tests (2800+ tests)
npm run typecheck     # Strict type checking
npm run watch         # Development watch mode
npm run clean         # Remove dist/ directory
npm run docs:deps     # Generate dependency graph

Architecture

┌─────────────────────────────────────────────────────┐
│  Layer 1: MCP Protocol Layer                        │
│  server/MCPServer.ts + toolDefinitions (59 tools)   │
│  + toolHandlers + responseCompressor                │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────┴──────────────────────────────┐
│  Layer 2: Managers + Context (Lazy Initialization)  │
│  ManagerContext (aliased as KnowledgeGraphManager)  │
│  • EntityManager   (CRUD + hierarchy + archive)     │
│  • RelationManager (relation CRUD)                  │
│  • SearchManager   (search + compression + stats)   │
│  • IOManager       (import + export + backup)       │
│  • TagManager      (tag aliases)                    │
│  • GraphTraversal  (path finding, centrality)       │
│  • SemanticSearch  (embeddings, similarity)         │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────┴──────────────────────────────┐
│  Layer 3: Storage Layer                             │
│  core/GraphStorage.ts (JSONL + in-memory cache)     │
│  core/SQLiteStorage.ts (better-sqlite3 + FTS5)      │
│  core/StorageFactory.ts (backend selection)         │
└─────────────────────────────────────────────────────┘

Project Structure

memory-mcp/
├── src/                            # Source (77 TypeScript files)
│   ├── index.ts                    # Entry point
│   ├── core/                       # Core managers (12 files)
│   │   ├── ManagerContext.ts           # Context holder (lazy init)
│   │   ├── EntityManager.ts            # Entity CRUD + hierarchy
│   │   ├── RelationManager.ts          # Relation CRUD
│   │   ├── GraphStorage.ts             # JSONL I/O + caching
│   │   ├── SQLiteStorage.ts            # SQLite with better-sqlite3
│   │   ├── TransactionManager.ts       # ACID transactions
│   │   ├── StorageFactory.ts           # Storage backend factory
│   │   ├── HierarchyManager.ts         # Tree operations
│   │   ├── ObservationManager.ts       # Observation CRUD
│   │   ├── GraphTraversal.ts           # Path finding, centrality
│   │   ├── GraphEventEmitter.ts        # Event system
│   │   └── index.ts
│   ├── server/                     # MCP protocol (4 files)
│   │   ├── MCPServer.ts                # Server setup
│   │   ├── toolDefinitions.ts          # 59 tool schemas
│   │   ├── toolHandlers.ts             # Handler registry
│   │   └── responseCompressor.ts       # Brotli compression
│   ├── search/                     # Search implementations (29 files)
│   │   ├── SearchManager.ts            # Search orchestrator
│   │   ├── BasicSearch.ts              # Text matching
│   │   ├── RankedSearch.ts             # TF-IDF scoring
│   │   ├── BooleanSearch.ts            # AND/OR/NOT logic
│   │   ├── FuzzySearch.ts              # Typo tolerance
│   │   ├── SemanticSearch.ts           # Embedding-based
│   │   ├── EmbeddingService.ts         # Provider abstraction
│   │   ├── VectorStore.ts              # Vector storage
│   │   └── ...                         # + 12 more
│   ├── features/                   # Advanced capabilities (9 files)
│   │   ├── IOManager.ts                # Import/export/backup
│   │   ├── TagManager.ts               # Tag aliases
│   │   ├── AnalyticsManager.ts         # Graph stats
│   │   ├── ArchiveManager.ts           # Entity archival
│   │   ├── CompressionManager.ts       # Duplicate detection
│   │   ├── StreamingExporter.ts        # Large graph exports
│   │   ├── ObservationNormalizer.ts    # Coreference resolution
│   │   ├── KeywordExtractor.ts         # Keyword extraction
│   │   └── index.ts
│   ├── types/                      # TypeScript definitions (2 files)
│   ├── utils/                      # Shared utilities (18 files)
│   └── workers/                    # Worker pool (2 files)
├── tests/                          # Test suite (97 files, 2800+ tests)
│   ├── unit/                       # Unit tests
│   ├── integration/                # Integration tests
│   ├── e2e/                        # End-to-end tests
│   └── performance/                # Benchmarks
├── dist/                           # Compiled output
├── docs/                           # Documentation
│   ├── architecture/               # Architecture docs
│   ├── guides/                     # User guides
│   └── reports/                    # Sprint reports
├── tools/                          # Standalone utilities
│   ├── chunking-for-files/         # File splitting
│   ├── compress-for-context/       # CTON compression
│   ├── create-dependency-graph/    # Dependency analyzer
│   └── migrate-from-jsonl-to-sqlite/
├── CHANGELOG.md                    # Version history
└── README.md                       # This file

Dependencies

Production:

• @modelcontextprotocol/sdk: ^1.21.1
• better-sqlite3: ^11.7.0
• zod: ^4.1.13
• async-mutex: ^0.5.0
• @danielsimonjr/workerpool: ^10.0.1

Development:

• typescript: ^5.6.2
• vitest: ^4.0.13
• @vitest/coverage-v8: ^4.0.13
• @types/better-sqlite3: ^7.6.12

Documentation

Comprehensive documentation in docs/:

Architecture

• - Complete API documentation for all 59 tools
• - Technical architecture and system design
• - Component breakdown and responsibilities
• - High-level project overview
• - Module dependencies

User Guides

• - Parent-child relationships (9 tools)
• - Duplicate detection and merging
• - Memory lifecycle and archiving
• - Boolean search syntax

Development

• - Development procedures
• - Version upgrade guide

Contributing

We welcome contributions!

See:

• - Contribution guidelines
• - Community standards

Ways to Help:

• Report bugs
• Request features
• Submit pull requests
• Improve documentation
• Add tests

Changelog

All notable changes are documented in .

Current version: v10.1.0 -

Recent highlights:

• v10.1.0: Documentation updates, 5 missing Phase 12 test files, architecture docs refresh
• v10.0.0: Phase 12 Performance Optimization - BM25 search, parallel execution, query plan caching, embedding cache, incremental indexing
• v9.8.3: SQLite storage support fix, JSON-RPC communication fix

License

MIT License - see

Acknowledgments

Original Project

Enhanced fork of Model Context Protocol memory server by Anthropic.

Developer

Daniel Simon Jr.

Major Enhancements

• Hierarchical nesting with parent-child relationships
• Graph algorithms: path finding, centrality, connected components
• Semantic search with embedding-based similarity
• Brotli compression for backups, exports, and responses
• Memory compression with intelligent duplicate detection
• Smart archiving with criteria-based filtering
• Advanced search: TF-IDF, boolean, and fuzzy matching
• Multi-format import/export with merge strategies
• SQLite backend with better-sqlite3 (3-10x faster)
• Transaction support with ACID guarantees
• Comprehensive test suite (2800+ tests, 97 test files)

Repository: https://github.com/danielsimonjr/memory-mcp NPM: https://www.npmjs.com/package/@danielsimonjr/memory-mcp Issues: https://github.com/danielsimonjr/memory-mcp/issues