# Memory MCP Server

[![NPM](https://img.shields.io/npm/v/@danielsimonjr/memory-mcp.svg)](https://www.npmjs.com/package/@danielsimonjr/memory-mcp)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-1.0-purple.svg)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/github/package-json/dependency-version/danielsimonjr/memory-mcp/dev/typescript?label=TypeScript&color=blue)](https://www.typescriptlang.org/)

An **enhanced fork** of the official [Model Context Protocol](https://modelcontextprotocol.io) 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](#features)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Core Concepts](#core-concepts)
- [API Reference](#api-reference)
- [Configuration](#configuration)
- [Development](#development)
- [Documentation](#documentation)
- [Companion Skill](#companion-skill)
- [Contributing](#contributing)
- [Changelog](#changelog)
- [License](#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

| Category | Tools | Description |
|----------|-------|-------------|
| **Hierarchical Nesting** | 9 | Parent-child relationships for organizing tree structures |
| **Graph Algorithms** | 4 | Path finding, connected components, centrality metrics |
| **Intelligent Search** | 3 | Hybrid multi-layer search with query analysis and reflection |
| **Semantic Search** | 3 | Embedding-based similarity search with OpenAI or local models |
| **Memory Compression** | 4 | Intelligent duplicate detection and merging with similarity scoring |
| **Advanced Search** | 7 | TF-IDF ranking, boolean queries, fuzzy matching, auto-select |
| **Observation Normalization** | 1 | Coreference resolution and temporal anchoring |
| **Tag Management** | 6 | Tags, bulk operations, importance scores |
| **Tag Aliases** | 5 | Tag synonym/alias management |
| **Saved Searches** | 5 | Store and execute frequent queries |
| **Import/Export** | 2 | 7 export formats (incl. W3C Linked Data: Turtle / JSON-LD / RDF/XML) with brotli + PII redaction; 3 import formats |
| **Graph Analytics** | 2 | Statistics, validation, integrity checks |
| **Ref Index** | 4 | Cross-session symbolic reference registration and resolution |
| **Artifacts** | 3 | Named versioned content blobs attached to entities |
| **Temporal Search** | 1 | Time-window filtered search across the knowledge graph |
| **Distillation** | 1 | Configure automated observation distillation pipelines |
| **Freshness** | 5 | Staleness tracking, expiry detection, and freshness reporting |
| **LLM Query** | 1 | Natural-language question answering over the graph |
| **Governance** | 4 | Transactional audit trail, history, and rollback |
| **Role Profiles** | 2 | Per-agent role assignment and profile listing |
| **Entropy** | 2 | Entropy-based noise filtering and information density scoring |
| **Consolidation** | 3 | Background memory consolidation scheduling and control |
| **Formatter** | 1 | Salience-budget-aware context formatting |
| **Collaborative** | 1 | Multi-agent context synthesis |
| **Failure Handling** | 2 | Session failure distillation and graceful session end |
| **Cognitive Load** | 2 | Working-memory load analysis and adaptive reduction |
| **Dream Engine** | 3 | Background memory maintenance: 8-phase sleep-cycle consolidation |
| **Project Scoping** | 1 | List and filter entities by project |
| **Memory Versioning** | 2 | Entity version chains and per-entity version history |
| **Semantic Forget** | 1 | Two-tier deletion: exact match → semantic similarity fallback |
| **Profiles** | 2 | User/agent profile get and update |
| **Temporal KG** | 3 | Temporal relation invalidation, time-travel queries, relation timeline |
| **Ingestion** | 1 | Format-agnostic conversation/document ingestion pipeline |
| **Agent Diary** | 2 | Per-agent persistent journal write and read |
| **Session & Working Memory** | 9 | Session lifecycle, working memory CRUD, TTL, promotion, context wake-up |
| **Auto-Enhancement** | 3 | Auto-link entity mentions, fact extraction, contradiction detection |
| **Context Compression** | 1 | N-gram text abbreviation with legend for token savings |
| **Consolidation Pipeline** | 3 | Session consolidation, pattern detection, entity summarization |
| **Decay & Salience** | 5 | Time-based decay, importance scoring, weak memory cleanup, reinforcement |
| **Multi-Agent** | 5 | Agent registration, cross-agent search, visibility, conflict resolution |
| **Observability** | 4 | D3.js graph visualization, transcript splitting, query cost estimation |
| **Dedup** | 1 | Priority-based smart deduplication |
| **Entity Bitemporal** | 5 | Time-travel queries: invalidate entities/observations, entity_as_of, timelines |
| **Optimistic Concurrency** | 1 | `update_entity` with `expectedVersion` → `VersionConflictError` on stale |
| **RBAC** | 4 | Role-based access control: assign/revoke/check/list reader/writer/admin/owner permissions |
| **Procedural Memory** | 5 | Executable how-to sequences with EWMA-refined success rate |
| **Active Retrieval** | 1 | Iterative query rewriting until coverage threshold met |
| **Causal Reasoning** | 4 | Chain discovery, counterfactual queries, cycle detection |
| **World Model** | 3 | Graph snapshots, fact validation, outcome prediction |

### Comparison with Official Memory Server

| Feature | Official | Enhanced (This Fork) |
|---------|----------|----------------------|
| Entity/Relation/Observation Management | ✅ | ✅ |
| Basic Search | ✅ | ✅ |
| **Hierarchical Nesting** | ❌ | ✅ Parent-child trees |
| **Graph Algorithms** | ❌ | ✅ Path finding, centrality |
| **Semantic Search** | ❌ | ✅ Embedding-based similarity |
| **Memory Compression** | ❌ | ✅ Duplicate detection |
| **Brotli Compression** | ❌ | ✅ Backups, exports, responses |
| **Smart Archiving** | ❌ | ✅ Criteria-based |
| **Advanced Search** | ❌ | ✅ TF-IDF + Boolean + Fuzzy |
| **SQLite Backend** | ❌ | ✅ better-sqlite3 (3-10x faster) |
| **Full-Text Search** | ❌ | ✅ FTS5 with BM25 ranking |
| **Timestamps** | ❌ | ✅ createdAt + lastModified |
| **Import/Export Formats** | ❌ | ✅ 7 export / 3 import |
| **Input Validation** | ❌ | ✅ Zod schemas |
| **Backup & Restore** | ❌ | ✅ Compressed snapshots |
| **Intelligent Search** | ❌ | ✅ Hybrid + Query Analysis + Reflection |
| **Observation Normalization** | ❌ | ✅ Coreference resolution + temporal anchoring |
| **Total Tools** | 11 | **160** |
| **Code Structure** | Monolithic | **Modular** (5 src files in this repo; core graph in [`@danielsimonjr/memoryjs`](https://www.npmjs.com/package/@danielsimonjr/memoryjs)) |

## Quick Start

### 1. Install from NPM

```bash
npm install -g @danielsimonjr/memory-mcp
```

Or use with npx (no installation required):

```bash
npx @danielsimonjr/memory-mcp
```

### 2. Configure Claude Desktop

Add to `claude_desktop_config.json`:

**Using NPM Global Install:**
```json
{
  "mcpServers": {
    "memory": {
      "command": "mcp-server-memory"
    }
  }
}
```

**Using NPX:**
```json
{
  "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

```bash
# 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):

```json
{
  "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`:

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

## Core Concepts

### Entities

Primary nodes in the knowledge graph.

```typescript
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.

```typescript
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](docs/architecture/API.md) or `src/server/toolDefinitions.ts`.

#### Entity Operations (4 tools)
| Tool | Description |
|------|-------------|
| `create_entities` | Create multiple new entities |
| `delete_entities` | Remove entities and their relations |
| `read_graph` | Read entire knowledge graph |
| `open_nodes` | Retrieve specific nodes by name |

#### Relation Operations (2 tools)
| Tool | Description |
|------|-------------|
| `create_relations` | Create relations between entities |
| `delete_relations` | Remove specific relations |

#### Observation Management (3 tools)
| Tool | Description |
|------|-------------|
| `add_observations` | Add observations to entities |
| `delete_observations` | Remove specific observations |
| `normalize_observations` | Normalize observations (resolve pronouns, anchor dates) |

#### Search (7 tools)
| Tool | Description |
|------|-------------|
| `search_nodes` | Search with filters (tags, importance) |
| `search_by_date_range` | Filter by date range |
| `search_nodes_ranked` | TF-IDF relevance ranking |
| `boolean_search` | Boolean queries (AND/OR/NOT) |
| `fuzzy_search` | Typo-tolerant search |
| `get_search_suggestions` | "Did you mean?" suggestions |
| `search_auto` | Auto-select best search method |

#### Intelligent Search (3 tools)
| Tool | Description |
|------|-------------|
| `hybrid_search` | Multi-layer search combining semantic, lexical, and symbolic signals |
| `analyze_query` | Extract entities, temporal references, and classify query complexity |
| `smart_search` | Reflection-based iterative search until results meet adequacy threshold |

#### Semantic Search (3 tools)
| Tool | Description |
|------|-------------|
| `semantic_search` | Search by semantic similarity using embeddings |
| `find_similar_entities` | Find entities similar to a reference entity |
| `index_embeddings` | Build or rebuild the semantic search index |

#### Saved Searches (5 tools)
| Tool | Description |
|------|-------------|
| `save_search` | Save search query for reuse |
| `execute_saved_search` | Execute a saved search |
| `list_saved_searches` | List all saved searches |
| `delete_saved_search` | Delete a saved search |
| `update_saved_search` | Update saved search parameters |

#### Tag Management (6 tools)
| Tool | Description |
|------|-------------|
| `add_tags` | Add tags to an entity |
| `remove_tags` | Remove tags from an entity |
| `set_importance` | Set entity importance (0-10) |
| `add_tags_to_multiple_entities` | Bulk tag operation |
| `replace_tag` | Replace tag globally |
| `merge_tags` | Merge two tags into one |

#### Tag Aliases (5 tools)
| Tool | Description |
|------|-------------|
| `add_tag_alias` | Create tag synonym |
| `list_tag_aliases` | List all aliases |
| `remove_tag_alias` | Remove an alias |
| `get_aliases_for_tag` | Get aliases for canonical tag |
| `resolve_tag` | Resolve alias to canonical form |

#### Hierarchical Nesting (9 tools)
| Tool | Description |
|------|-------------|
| `set_entity_parent` | Set/remove parent relationship |
| `get_children` | Get immediate children |
| `get_parent` | Get parent entity |
| `get_ancestors` | Get all ancestors (parent chain) |
| `get_descendants` | Get all descendants (recursive) |
| `get_subtree` | Get entity + descendants with relations |
| `get_root_entities` | Get entities with no parent |
| `get_entity_depth` | Get depth in hierarchy |
| `move_entity` | Move entity to new parent |

#### Graph Algorithms (4 tools)
| Tool | Description |
|------|-------------|
| `find_shortest_path` | Shortest path between entities (BFS) |
| `find_all_paths` | All paths with max depth limit |
| `get_connected_components` | Detect isolated subgraphs |
| `get_centrality` | Calculate centrality metrics (degree, betweenness, PageRank) |

#### Graph Analytics (2 tools)
| Tool | Description |
|------|-------------|
| `get_graph_stats` | Comprehensive graph statistics |
| `validate_graph` | Validate graph integrity |

#### Compression & Archiving (4 tools)
| Tool | Description |
|------|-------------|
| `find_duplicates` | Find similar entities by threshold |
| `merge_entities` | Merge multiple entities into one |
| `compress_graph` | Auto compression with dry-run |
| `archive_entities` | Archive by age, importance, or tags |

#### Import & Export (2 tools)
| Tool | Description |
|------|-------------|
| `export_graph` | Export in 7 formats (JSON, CSV, GraphML, GEXF, DOT, Markdown, Mermaid) with compression |
| `import_graph` | Import from JSON/CSV/GraphML with merge strategies |

#### Ref Index (4 tools)
| Tool | Description |
|------|-------------|
| `register_ref` | Register a symbolic reference pointing to an entity |
| `resolve_ref` | Resolve a symbolic reference to its target entity |
| `deregister_ref` | Remove a registered symbolic reference |
| `list_refs` | List all registered symbolic references |

#### Artifacts (3 tools)
| Tool | Description |
|------|-------------|
| `create_artifact` | Create a named versioned content blob attached to an entity |
| `get_artifact` | Retrieve an artifact by name and optional version |
| `list_artifacts` | List all artifacts, optionally filtered by entity |

#### Temporal Search (1 tool)
| Tool | Description |
|------|-------------|
| `search_by_time` | Search entities and observations within a time window |

#### Distillation (1 tool)
| Tool | Description |
|------|-------------|
| `configure_distillation` | Configure automated observation distillation pipelines |

#### Freshness (5 tools)
| Tool | Description |
|------|-------------|
| `check_freshness` | Check freshness status of a specific entity |
| `get_stale_entities` | List entities that have exceeded their staleness threshold |
| `get_expired_entities` | List entities past their explicit expiry date |
| `refresh_entity` | Reset the freshness timestamp on an entity |
| `freshness_report` | Generate a full freshness report across the graph |

#### LLM Query (1 tool)
| Tool | Description |
|------|-------------|
| `query_natural_language` | Answer natural-language questions over the knowledge graph |

#### Governance (4 tools)
| Tool | Description |
|------|-------------|
| `governance_transaction` | Execute a governed, audited graph transaction |
| `audit_query` | Query the audit log with filters |
| `audit_history` | Retrieve full audit history for an entity |
| `rollback_operation` | Roll back a previously recorded operation |

#### Role Profiles (2 tools)
| Tool | Description |
|------|-------------|
| `set_agent_role` | Assign a role profile to the current agent context |
| `list_role_profiles` | List all available agent role profiles |

#### Entropy (2 tools)
| Tool | Description |
|------|-------------|
| `enable_entropy_filter` | Enable entropy-based noise filtering for search results |
| `compute_entropy` | Compute information-density entropy score for an entity |

#### Consolidation (3 tools)
| Tool | Description |
|------|-------------|
| `start_consolidation` | Start the background memory consolidation service |
| `stop_consolidation` | Stop the background memory consolidation service |
| `run_consolidation_now` | Trigger an immediate consolidation pass |

#### Formatter (1 tool)
| Tool | Description |
|------|-------------|
| `format_with_salience_budget` | Format context output respecting a token salience budget |

#### Collaborative (1 tool)
| Tool | Description |
|------|-------------|
| `synthesize_collaborative_context` | Synthesize a unified context view from multiple agent memory spaces |

#### Failure Handling (2 tools)
| Tool | Description |
|------|-------------|
| `distill_failure` | Distill and store key observations from a failed session |
| `end_session` | Gracefully end a session and persist in-flight state |

#### Cognitive Load (2 tools)
| Tool | Description |
|------|-------------|
| `analyze_cognitive_load` | Analyze working-memory load in the current context |
| `adaptive_reduce_memories` | Adaptively reduce memory set to fit cognitive load target |

#### Project Scoping (1 tool)
| Tool | Description |
|------|-------------|
| `list_projects` | List all project IDs present in the graph and filter entities by project |

#### Memory Versioning (2 tools)
| Tool | Description |
|------|-------------|
| `get_entity_versions` | Retrieve all versions of a versioned entity by name |
| `get_version_chain` | Get the full version chain from root to latest for an entity |

#### Semantic Forget (1 tool)
| Tool | Description |
|------|-------------|
| `forget_memory` | Delete an entity by exact name, falling back to semantic similarity if no exact match found |

#### Profiles (2 tools)
| Tool | Description |
|------|-------------|
| `get_profile` | Retrieve a user or agent profile entity |
| `update_profile` | Update observations and metadata on a profile entity |

#### Temporal KG (3 tools)
| Tool | Description |
|------|-------------|
| `invalidate_relation` | Mark a relation as ended by setting its temporal validity end date |
| `query_as_of` | Retrieve all relations for an entity that were valid at a given point in time |
| `timeline` | Return a chronological list of relation events for an entity |

#### Ingestion (1 tool)
| Tool | Description |
|------|-------------|
| `ingest` | Ingest a conversation, document, or free-form text into the knowledge graph |

#### Agent Diary (2 tools)
| Tool | Description |
|------|-------------|
| `diary_write` | Append an entry to the agent's persistent diary |
| `diary_read` | Read diary entries for an agent, optionally filtered by date range |

#### Entity Bitemporal Validity (5 tools)
| Tool | Description |
|------|-------------|
| `invalidate_entity` | Stamp `validUntil` on an entity (idempotent; entity remains queryable for past timestamps via `entity_as_of`) |
| `entity_as_of` | Time-travel query: returns entity state at a given ISO 8601 timestamp, or `null` if invalidated then |
| `entity_timeline` | All temporal versions of an entity in chronological order; integrates the supersession chain |
| `invalidate_observation` | Per-observation invalidation via parallel `observationMeta[]` entry on the entity |
| `observations_as_of` | Filter observations valid at a given timestamp; observations without meta are treated as unbounded |

#### Optimistic Concurrency Control (1 tool)
| Tool | Description |
|------|-------------|
| `update_entity` | Update an entity with optional `expectedVersion`; throws `VersionConflictError` on stale version. OCC-guarded writes auto-increment `version`. Omit `expectedVersion` for legacy last-write-wins. |

#### RBAC (4 tools)
| Tool | Description |
|------|-------------|
| `rbac_assign_role` | Grant `reader` / `writer` / `admin` / `owner` (or custom) role to an agent; optional `resourceType`, `scope` prefix, `validFrom` / `validUntil` window |
| `rbac_revoke_role` | Remove a specific role assignment matched by `agentId + role + resourceType` |
| `rbac_check_permission` | Check whether an agent can perform `read` / `write` / `delete` / `manage` on a resource type; falls back to `defaultRole=reader` for unassigned agents |
| `rbac_list_assignments` | List all role assignments for an agent; optional `activeOnly` filter |

#### Procedural Memory (5 tools)
| Tool | Description |
|------|-------------|
| `add_procedure` | Persist an executable how-to sequence: 1-indexed steps with optional fallback chains and free-form trigger phrases |
| `get_procedure` | Load a procedure by id |
| `match_procedure` | Token-overlap match a context description against stored procedures; returns ranked Jaccard-like scores |
| `refine_procedure` | Apply caller feedback after execution; updates `successRate` via EWMA (α=0.2) |
| `get_procedure_step` | Load step by 1-indexed `order`, or get the next step relative to `currentOrder` |

#### Active Retrieval (1 tool)
| Tool | Description |
|------|-------------|
| `adaptive_retrieve` | Iterative query-rewriting retrieval (search → score coverage → rewrite); up to 3 rounds, and it stops early when the coverage reaches 0.6. Pure symbolic — no LLM provider required. |

#### Causal Reasoning (4 tools)
| Tool | Description |
|------|-------------|
| `find_causes` | Causal chains ending at the named effect; sorted by product-of-edge causalStrength |
| `find_effects` | Symmetric counterpart starting at the named cause |
| `counterfactual_query` | "If we remove edge (removeFrom → removeTo), is `predict` still reachable from `seed`?" Returns surviving chains. Pure: does not mutate the graph. |
| `detect_causal_cycles` | Detect cycles in the causal subgraph rooted at `seed` |

#### World Model (3 tools)
| Tool | Description |
|------|-------------|
| `get_world_state` | Capture a fresh snapshot of the live graph (capped at 1000 entities; over-cap prefers high-importance) |
| `validate_fact_against_world` | Validate a candidate observation against a target entity via `MemoryValidator.validateConsistency`. Returns `{result: null, reason: 'embedding_provider_unavailable'}` when the local embedding provider is selected without `@xenova/transformers` installed. |
| `predict_outcome` | Predict downstream effects of an action by walking the causal subgraph (delegates to `find_effects`) |

#### 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)
| Tool | Description |
|------|-------------|
| `record_tool_outcome` | Record a tool call outcome (success/failure) into affordance stats |
| `get_tool_affordance_stats` | Per-tool success-rate and usage statistics |
| `suggest_tool` | Suggest the best tool for a task based on recorded affordances |
| `list_tool_affordances` | List all recorded tool affordances |
| `remove_tool_affordance` | Remove one tool's affordance record |
| `observe_tool_start` | `ToolCallObserver` lifecycle: mark a tool call started |
| `observe_tool_complete` | Mark an observed tool call completed successfully |
| `observe_tool_error` | Mark an observed tool call failed |
| `observe_tool_partial` | Mark an observed tool call partially successful |
| `observe_tool_cancel` | Cancel an in-flight tool observation |
| `tool_observer_in_flight_count` | Count of currently in-flight observed tool calls |

#### Heuristic Guidelines (10 tools)
| Tool | Description |
|------|-------------|
| `add_heuristic` | Store a heuristic guideline ("when X, prefer Y") |
| `get_heuristic` | Fetch one heuristic by id |
| `list_heuristics` | List stored heuristics |
| `heuristic_count` | Count of stored heuristics |
| `match_heuristics` | Heuristics matching a context string |
| `reinforce_heuristic` | Strengthen a heuristic after successful application |
| `record_heuristic_contradiction` | Record evidence contradicting a heuristic |
| `detect_heuristic_conflicts` | Detect mutually contradictory heuristics |
| `remove_heuristic` | Remove one heuristic |
| `clear_heuristics` | Remove all heuristics |

#### Project Context (12 tools)
| Tool | Description |
|------|-------------|
| `upsert_project_context` | Create/replace a project's structured context record |
| `get_project_context` | Fetch a project's context record |
| `append_project_fact` | Append a fact to a project context |
| `append_project_convention` | Append a coding/workflow convention |
| `append_project_command` | Append a named command (e.g. build/test invocations) |
| `append_project_glossary_term` | Append a glossary term + definition |
| `remove_project_fact` | Remove a fact by index/value |
| `remove_project_convention` | Remove a convention |
| `remove_project_command` | Remove a command |
| `remove_project_glossary_term` | Remove a glossary term |
| `clear_project_context` | Delete a project's context record |
| `format_project_context_for_llm` | Render the context as LLM-ready markdown |

#### Decision Rationale (10 tools)
| Tool | Description |
|------|-------------|
| `propose_decision` | Record a proposed decision with rationale |
| `accept_decision` | Mark a decision accepted |
| `reject_decision` | Mark a decision rejected |
| `supersede_decision` | Supersede a decision with a newer one |
| `find_decisions_by_context` | Decisions matching a context string |
| `get_decision_chain` | Follow a decision's supersession chain |
| `list_decisions` | List decisions (filterable by status) |
| `get_decision` | Fetch one decision by id |
| `export_decision_as_adr_markdown` | Render a decision as ADR markdown |
| `parse_adr_markdown` | Parse ADR markdown back into a decision record |

#### Exclusion / `do_not_remember` (5 tools)
| Tool | Description |
|------|-------------|
| `add_exclusion_rule` | Add a rule for content that must not be remembered |
| `list_exclusion_rules` | List exclusion rules |
| `remove_exclusion_rule` | Remove one exclusion rule |
| `check_exclusion` | Check whether a text would be excluded |
| `find_matching_memories_for_rule` | Existing memories matching an exclusion rule |

#### Observation Dedup (2 tools)
| Tool | Description |
|------|-------------|
| `find_duplicate_observations` | Exact duplicate observations across entities |
| `find_jaccard_duplicate_observations` | Near-duplicates via Jaccard token similarity |

#### Spell Correction (3 tools)
| Tool | Description |
|------|-------------|
| `spell_suggest` | "Did you mean?" suggestions for a query term |
| `spell_rebuild_vocabulary` | Rebuild the spell-check vocabulary from the graph |
| `spell_vocabulary_size` | Current vocabulary size |

#### Active Project Scope (2 tools)
| Tool | Description |
|------|-------------|
| `set_project_scope` | Set the server's active project-scope filter (per-session mutable state) |
| `get_project_scope` | Get the active project scope (`{ projectId }`, null when unscoped) |

#### Engineering / Diagnostics (10 tools)
| Tool | Description |
|------|-------------|
| `diag` | Server + storage diagnostic snapshot |
| `health` | Quick health check |
| `check_graph` | Graph integrity check |
| `reindex` | Rebuild search indexes |
| `cache_stats` | Stats for the global search caches |
| `cache_clear` | Bust all global search caches |
| `graph_size` | Entity/relation/observation counts + on-disk footprint |
| `inspect_entity` | Verbose single-entity snapshot (observations, relations, hierarchy) |
| `hierarchy_tree` | Hierarchy as nested JSON |
| `entity_neighbors` | Incoming/outgoing relations + degree counts for one entity |

#### Event Memory (5 tools)
| Tool | Description |
|------|-------------|
| `record_event` | Reify an action as an event hub entity with role-typed relations (`actor_of` / `targeted` / `occurred_in` / `participant_in`) and optional `flow:<key>` grouping |
| `get_event` | Load one event with its resolved role endpoints |
| `query_events` | Query by actor / target / action / flowKey / time range, chronologically ordered |
| `get_event_flow` | Full timeline of a named flow (e.g. a release or incident) |
| `who_did_what` | "Who did what (to target / in context / within range)?" join over events |

#### Reconstructive Memory (5 tools)
| Tool | Description |
|------|-------------|
| `ingest_dialogue` | Distill dialogue turns into the Cue–Tag–Content associative graph (also persisted into the live knowledge graph) |
| `reconstruct_memory` | Answer a query via active multi-step traversal; returns evidence + trajectory |
| `reconstructive_memory_stats` | CTC graph size statistics |
| `save_reconstructive_memory` | Serialize the CTC graph to a `<basename>-reconstructive.json` sidecar |
| `load_reconstructive_memory` | Restore the CTC graph from the sidecar (survives restarts) |

#### Relation Consolidation (2 tools)
| Tool | Description |
|------|-------------|
| `analyze_relation_duplicates` | Dry-run the three-tier relation janitor: spelling variants, inverse duplicates, semantic duplicates (with embeddings) |
| `consolidate_relations` | Apply tier 1+2 merges (`apply: true`) or dry-run (default) |

#### Agent Reflection (4 tools)
| Tool | Description |
|------|-------------|
| `create_reflection` | Persist an evidence-backed generalized lesson (scope: session / project / global) |
| `list_reflections` | List reflections, filterable by scope / source / confidence |
| `get_relevant_reflections` | Reflections relevant to a session (sourceSessionId + evidence overlap) |
| `archive_reflection` | Soft-delete a reflection out of default listings |

#### 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

| Variable | Description | Default |
|----------|-------------|---------|
| `MEMORY_FILE_PATH` | Path to storage file | `memory.jsonl` (current directory) |
| `MEMORY_STORAGE_TYPE` | Storage backend: `jsonl` or `sqlite` | `jsonl` |
| `MEMORY_EMBEDDING_PROVIDER` | Embedding provider: `openai`, `local`, `llamacpp`, or `none` | `none` |
| `MEMORY_OPENAI_API_KEY` | OpenAI API key (required if provider is `openai`) | - |
| `MEMORY_EMBEDDING_MODEL` | Embedding model to use | `text-embedding-3-small` (OpenAI) / `Xenova/all-MiniLM-L6-v2` (local) / `llamacpp-local` (llamacpp) |
| `MEMORY_EMBEDDING_BASE_URL` | Base URL of a local `llama-server` (used when provider is `llamacpp`) | `http://127.0.0.1:8080` |
| `MEMORY_AUTO_INDEX_EMBEDDINGS` | Auto-index entities on creation | `false` |

### Storage Backends

| Feature | JSONL (Default) | SQLite (better-sqlite3) |
|---------|-----------------|-------------------------|
| Format | Human-readable text | Native binary database |
| Transactions | Basic | Full ACID with WAL mode |
| Full-Text Search | Basic | FTS5 with BM25 ranking |
| Performance | Good | 3-10x faster |
| Concurrency | Single-threaded | Thread-safe with async-mutex |
| Best For | Small graphs, debugging | Large graphs (10k+ entities) |

**Using SQLite:**

```json
{
  "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:

```bash
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

```bash
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`](https://www.npmjs.com/package/@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
```

| Layer | Lives in | Files |
|-------|----------|-------|
| MCP protocol (stdio transport, tool registration, dispatch) | `memory-mcp` | 5 |
| Tool schemas (241 tools across 65 categories) | `memory-mcp` (`toolDefinitions.ts`) | 1 |
| Handler registry + Zod validation + response compression | `memory-mcp` (`toolHandlers.ts` + `responseCompressor.ts`) | 2 |
| Managers (Entity / Relation / Search / IO / Tag / Hierarchy / Analytics / Compression / Archive / GraphTraversal / SemanticSearch / RankedSearch / etc.) | `memoryjs` | 100+ |
| Storage (JSONL + SQLite with FTS5 + StorageFactory + TransactionManager) | `memoryjs` | — |
| Embedding providers (OpenAI / local / none) + VectorStore | `memoryjs` | — |

### 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](docs/architecture/API.md) - Complete API documentation for all 241 tools
- [ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md) - Technical architecture and system design
- [COMPONENTS.md](docs/architecture/COMPONENTS.md) - Component breakdown and responsibilities
- [OVERVIEW.md](docs/architecture/OVERVIEW.md) - High-level project overview
- [DEPENDENCY_GRAPH.md](docs/architecture/DEPENDENCY_GRAPH.md) - Module dependencies

**User Guides**
- [HIERARCHY.md](docs/guides/HIERARCHY.md) - Parent-child relationships (9 tools)
- [COMPRESSION.md](docs/guides/COMPRESSION.md) - Duplicate detection and merging
- [ARCHIVING.md](docs/guides/ARCHIVING.md) - Memory lifecycle and archiving
- [QUERY_LANGUAGE.md](docs/guides/QUERY_LANGUAGE.md) - Boolean search syntax

**Development**
- [WORKFLOW.md](docs/development/WORKFLOW.md) - Development procedures
- [MIGRATION.md](docs/guides/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](skills/memory/SKILL.md).

## Contributing

We welcome contributions!

**See:**
- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines
- [CODE_OF_CONDUCT.md](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](CHANGELOG.md)**.

## License

**MIT License** - see [LICENSE](LICENSE)

## Acknowledgments

### Original Project

Enhanced fork of [Model Context Protocol memory server](https://github.com/modelcontextprotocol/servers) by [Anthropic](https://www.anthropic.com/).

### Developer

**[Daniel Simon Jr.](https://github.com/danielsimonjr)**

### 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