知识图谱记忆服务器

Memory MCP Server

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

Enterprise-grade knowledge graph with 241 tools including hierarchical organization, semantic search with embeddings, graph traversal algorithms, duplicate detection, smart archiving, project scoping, temporal knowledge graph, semantic forget, agent diary, entity bitemporal validity, optimistic concurrency control, role-based access control, W3C Linked Data exports (Turtle / JSON-LD / RDF/XML), PII redaction on export, procedural memory, active retrieval, causal reasoning, world model, do_not_remember exclusions, decision rationale (ADR memory + markdown dual-write), structured project context (facts / conventions / commands / glossary), heuristic guidelines, tool affordance + ToolCallObserver pipeline (with MCP shim), observation dedup, spell correction, n-ary event memory, reconstructive (Cue–Tag–Content) memory with snapshot persistence, relation consolidation, agent reflections, and a graph-connectivity hybrid-search channel with evidence-path explanations for long-term memory management.

Table of Contents

• Features
• Quick Start
• Installation
• Core Concepts
• API Reference
• Configuration
• Development
• Documentation
• Companion Skill
• 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
bun install
bun run build

# Run tests
bun run test

# Type check
bun 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 (241 Tools)

Tool count: 241 tools across 65 categories. The sections Extended Tools and Hybrid Search Options list the options that existing tools accept. For full per-tool schemas see docs/architecture/API.md or src/server/toolDefinitions.ts.

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)

Ref Index (4 tools)

Artifacts (3 tools)

Temporal Search (1 tool)

Distillation (1 tool)

Freshness (5 tools)

LLM Query (1 tool)

Governance (4 tools)

Role Profiles (2 tools)

Entropy (2 tools)

Consolidation (3 tools)

Formatter (1 tool)

Collaborative (1 tool)

Failure Handling (2 tools)

Cognitive Load (2 tools)

Project Scoping (1 tool)

Memory Versioning (2 tools)

Semantic Forget (1 tool)

Profiles (2 tools)

Temporal KG (3 tools)

Ingestion (1 tool)

Agent Diary (2 tools)

Entity Bitemporal Validity (5 tools)

Optimistic Concurrency Control (1 tool)

RBAC (4 tools)

Procedural Memory (5 tools)

Active Retrieval (1 tool)

Causal Reasoning (4 tools)

World Model (3 tools)

Extended Tools

• export_graph — Accepts format: 'turtle' | 'rdf-xml' | 'json-ld' for W3C Linked Data exports. Accepts redactPii: true to scrub PII (email / SSN / credit-card / phone / IPv4) from observations with the PiiRedactor.
• create_entities — Accepts freshness fields (ttl, confidence), project scope (projectId), and bitemporal fields (validFrom, validUntil, observationMeta) per entity.
• set_memory_visibility — Auto-promotes plain entities to AgentEntity (stamps agentId / memoryType / confidence) instead of silently returning null. Supports a time window and a role gate (allowedRoles, visibleFrom, visibleUntil).

Tool Affordance (11 tools)

Heuristic Guidelines (10 tools)

Project Context (12 tools)

Decision Rationale (10 tools)

Exclusion / do_not_remember (5 tools)

Observation Dedup (2 tools)

Spell Correction (3 tools)

Active Project Scope (2 tools)

Engineering / Diagnostics (10 tools)

Event Memory (5 tools)

Reconstructive Memory (5 tools)

Relation Consolidation (2 tools)

Agent Reflection (4 tools)

Hybrid Search Options

• hybrid_search — Accepts four additive options:
  • graphWeight: a graph-connectivity channel through normalized PageRank.
  • expandNeighbors: a one-hop expansion of the top results with damped scores.
  • explain: annotates results with evidence paths from the query anchors.
  • lookFor: ranks the expansion neighbors by a free-text connection description.

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

• Bun 1.4+ (install + scripts; bun.lock is authoritative)
• Node.js 22+ (shipped runtime — CI smokes dist/ under Node)
• TypeScript 7+

Build Commands

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

Architecture

This repo is a thin MCP wrapper. All graph logic, managers, and storage live in @danielsimonjr/memoryjs. The version range is in package.json.

memory-mcp (this repo)              @danielsimonjr/memoryjs (npm dep)
┌──────────────────────────┐        ┌──────────────────────────────────┐
│  src/index.ts            │        │  ManagerContext (lazy init)      │
│  src/server/MCPServer.ts │───────▶│  EntityManager, RelationManager  │
│  src/server/toolDefs.ts  │imports │  SearchManager, IOManager, etc.  │
│  src/server/toolHandlers │        │  GraphStorage / SQLiteStorage    │
│  src/server/responseComp.│        │  StorageFactory + 100+ modules   │
└──────────────────────────┘        └──────────────────────────────────┘
       5 source files                  77+ source files (extracted)
       MCP protocol + dispatch         All graph + search + storage

Project Structure

memory-mcp/
├── src/                                    # Source (5 TypeScript files)
│   ├── index.ts                            # Entry point: ManagerContext + start MCPServer; re-exports memoryjs types
│   └── server/
│       ├── MCPServer.ts                    # MCP Server setup, stdio transport, request handlers
│       ├── toolDefinitions.ts              # 241 tool schemas (name, description, inputSchema)
│       ├── toolHandlers.ts                 # Handler registry: validate args → call manager → format response
│       └── responseCompressor.ts           # Brotli + base64 wrapper for >256KB payloads
├── tests/                                  # Test suite
│   ├── unit/                               # Unit tests (response compressor, tool defs, validate-fact handler, API.md Returns gate)
│   ├── integration/                        # MCP server lifecycle
│   ├── e2e/tools/                          # Per-category tool tests + handler-smoke broad coverage
│   ├── knowledge-graph.test.ts             # Core graph operations (smoke against memoryjs)
│   └── file-path.test.ts                   # Storage path resolution
├── dist/                                   # Compiled output (rebuilt on `npm install` via `prepare`)
├── docs/                                   # Documentation
│   ├── architecture/                       # API.md, ARCHITECTURE.md, COMPONENTS.md, OVERVIEW.md, TEST_COVERAGE.md
│   ├── guides/                             # HIERARCHY.md, COMPRESSION.md, ARCHIVING.md, QUERY_LANGUAGE.md
│   ├── development/                        # WORKFLOW.md
│   ├── roadmap/                            # FUTURE_FEATURES.md, PERFORMANCE_AND_CAPABILITIES.md
│   └── reports/                            # Historical sprint reports
├── tools/                                  # Standalone utilities (each builds independently)
│   ├── chunking-for-files/                 # File splitting
│   ├── compress-for-context/               # CTON compression
│   ├── create-dependency-graph/            # Dependency analyzer
│   └── migrate-from-jsonl-to-sqlite/       # Storage backend converter
├── CHANGELOG.md                            # Version history
└── README.md                               # This file

Dependencies

Production (3 direct deps — everything else is transitive via memoryjs):

• @danielsimonjr/memoryjs: ^4.2.0 — knowledge graph engine (storage, managers, search, embeddings, RBAC, OCC, bitemporal, causal, etc.)
• @modelcontextprotocol/server: ^2.0.0 — MCP protocol implementation (Server and the stdio transport)
• zod: ^4.6.5 — runtime input validation (schemas re-exported from memoryjs)

Development:

• typescript: ^7.0.2
• typescript6: npm:typescript@6.0.3 — the createProgram API for the API.md Returns gate (version 7 of typescript has none)
• vitest: ^5.0.5
• @vitest/coverage-v8: ^5.0.5
• esbuild: ^0.28.2 — builds the plugin bundle (scripts/build-bundle.mjs)
• shx: ^0.4.0 — cross-platform shell commands for clean script
• @types/node: ^26

Note: better-sqlite3, async-mutex, @danielsimonjr/workerpool, and the embedding providers (OpenAI / @xenova/transformers) are transitive deps via @danielsimonjr/memoryjs. They are not listed in this repo's package.json.

Documentation

Comprehensive documentation in docs/:

Architecture

• API.md - Complete API documentation for all 241 tools
• ARCHITECTURE.md - Technical architecture and system design
• COMPONENTS.md - Component breakdown and responsibilities
• OVERVIEW.md - High-level project overview
• DEPENDENCY_GRAPH.md - Module dependencies

User Guides

• HIERARCHY.md - Parent-child relationships (9 tools)
• COMPRESSION.md - Duplicate detection and merging
• ARCHIVING.md - Memory lifecycle and archiving
• QUERY_LANGUAGE.md - Boolean search syntax

Development

• WORKFLOW.md - Development procedures
• MIGRATION.md - Version upgrade guide

Companion skill

This plugin ships a memory skill (memory-mcp:memory, /memory) — a playbook over the knowledge-graph tools covering graph CRUD/search/maintenance, project indexing, and storage migration. See skills/memory/SKILL.md.

Contributing

We welcome contributions!

See:

• CONTRIBUTING.md - Contribution guidelines
• CODE_OF_CONDUCT.md - Community standards

Ways to Help:

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

Changelog

All notable changes, with the version of each, are documented in CHANGELOG.md.

License

MIT License - see LICENSE

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 (this wrapper repo has its own tests; full-coverage core graph tests live in @danielsimonjr/memoryjs)

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