@danielsimonjr/memory-mcp 12.2.3 → 12.7.0

package/README.md

@@ -1,15 +1,15 @@
 # Memory MCP Server
 
-[![Version](https://img.shields.io/badge/version-12.2.0-blue.svg)](https://github.com/danielsimonjr/memory-mcp)
+[![Version](https://img.shields.io/badge/version-12.7.0-blue.svg)](https://github.com/danielsimonjr/memory-mcp)
 [![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/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)
-[![Coverage](https://img.shields.io/badge/coverage-96.6%25-brightgreen.svg)](docs/architecture/TEST_COVERAGE.md)
+[![Coverage](https://img.shields.io/badge/coverage-84.8%25-yellowgreen.svg)](docs/architecture/TEST_COVERAGE.md)
 
 An **enhanced fork** of the official [Model Context Protocol](https://modelcontextprotocol.io) 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 **160 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 (η.4.4)**, **optimistic concurrency control (η.5.5.c)**, **role-based access control (η.6.1)**, **W3C Linked Data exports** (Turtle / JSON-LD / RDF/XML — η.5.4), **PII redaction on export** (η.6.3), **procedural memory (3B.4)**, **active retrieval (3B.5)**, **causal reasoning (3B.6)**, and **world model (3B.7)** for long-term memory management.
+> **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 (η.4.4)**, **optimistic concurrency control (η.5.5.c)**, **role-based access control (η.6.1)**, **W3C Linked Data exports** (Turtle / JSON-LD / RDF/XML — η.5.4), **PII redaction on export** (η.6.3), **procedural memory (3B.4)**, **active retrieval (3B.5)**, **causal reasoning (3B.6)**, **world model (3B.7)**, **`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** (memoryjs v2.1.0 — Phase 16), **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** (memoryjs v3.0.0 — v12.7.0) for long-term memory management.
 
 ## Table of Contents
 
@@ -21,6 +21,7 @@ An **enhanced fork** of the official [Model Context Protocol](https://modelconte
 - [Configuration](#configuration)
 - [Development](#development)
 - [Documentation](#documentation)
+- [Companion Skill](#companion-skill)
 - [Contributing](#contributing)
 - [Changelog](#changelog)
 - [License](#license)
@@ -46,9 +47,10 @@ An **enhanced fork** of the official [Model Context Protocol](https://modelconte
 | **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** | 11 | Tags, aliases, bulk operations, importance scores |
+| **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 with brotli compression, 3 import formats |
+| **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 |
@@ -64,6 +66,7 @@ An **enhanced fork** of the official [Model Context Protocol](https://modelconte
 | **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 |
@@ -71,6 +74,21 @@ An **enhanced fork** of the official [Model Context Protocol](https://modelconte
 | **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 *(Phase 14)* |
+| **Auto-Enhancement** | 3 | Auto-link entity mentions, fact extraction, contradiction detection *(Phase 14)* |
+| **Context Compression** | 1 | N-gram text abbreviation with legend for token savings *(Phase 14)* |
+| **Consolidation Pipeline** | 3 | Session consolidation, pattern detection, entity summarization *(Phase 14)* |
+| **Decay & Salience** | 5 | Time-based decay, importance scoring, weak memory cleanup, reinforcement *(Phase 14)* |
+| **Multi-Agent** | 5 | Agent registration, cross-agent search, visibility, conflict resolution *(Phase 14)* |
+| **Observability** | 4 | D3.js graph visualization, transcript splitting, query cost estimation *(Phase 14)* |
+| **Dedup** | 1 | Priority-based smart deduplication *(Phase 14)* |
+| **Entity Bitemporal** | 5 | Time-travel queries: invalidate entities/observations, entity_as_of, timelines *(Phase 15 / η.4.4)* |
+| **Optimistic Concurrency** | 1 | `update_entity` with `expectedVersion` → `VersionConflictError` on stale *(Phase 15 / η.5.5.c)* |
+| **RBAC** | 4 | Role-based access control: assign/revoke/check/list reader/writer/admin/owner permissions *(Phase 15 / η.6.1)* |
+| **Procedural Memory** | 5 | Executable how-to sequences with EWMA-refined success rate *(Phase 15 / 3B.4)* |
+| **Active Retrieval** | 1 | Iterative query rewriting until coverage threshold met *(Phase 15 / 3B.5)* |
+| **Causal Reasoning** | 4 | Chain discovery, counterfactual queries, cycle detection *(Phase 15 / 3B.6)* |
+| **World Model** | 3 | Graph snapshots, fact validation, outcome prediction *(Phase 15 / 3B.7)* |
 
 ### Comparison with Official Memory Server
 
@@ -93,8 +111,8 @@ An **enhanced fork** of the official [Model Context Protocol](https://modelconte
 | **Backup & Restore** | ❌ | ✅ Compressed snapshots |
 | **Intelligent Search** | ❌ | ✅ Hybrid + Query Analysis + Reflection |
 | **Observation Normalization** | ❌ | ✅ Coreference resolution + temporal anchoring |
-| **Total Tools** | 11 | **106** |
-| **Code Structure** | Monolithic | **Modular** (77 files) |
+| **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
 
@@ -163,7 +181,7 @@ cd memory-mcp
 npm install
 npm run build
 
-# Run tests (2800+ tests)
+# Run tests (791 tests, ~85% statement coverage)
 npm test
 
 # Type check
@@ -242,9 +260,9 @@ Discrete facts about entities. Each observation should be atomic and independent
 
 ## API Reference
 
-### Complete Tool List (160 Tools)
+### Complete Tool List (241 Tools)
 
-> Tool count: 160 tools across 51 categories. The 23 newest tools (Phase 15 / memoryjs v1.14+) are documented at the end under **Phase 15** sections. For full per-tool schemas see [docs/architecture/API.md](docs/architecture/API.md).
+> Tool count: 241 tools across 65 categories. The newest tools are documented at the end under the **Phase 15**, **Phase 16 (memoryjs v2.1.0)**, **v12.3.2 / v12.5.0**, and **v12.7.0 (memoryjs v3.0.0)** sections. 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 |
@@ -545,6 +563,142 @@ Discrete facts about entities. Each observation should be atomic and independent
 - **`create_entities`** — Now accepts v1.6 freshness fields (`ttl`, `confidence`), v1.8 project scope (`projectId`), and η.4.4 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 η.5.5.b extensions (`allowedRoles`, `visibleFrom`, `visibleUntil`).
 
+#### Tool Affordance (11 tools) — Phase 16 / memoryjs v2.1.0
+| 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) — Phase 16 / memoryjs v2.1.0
+| 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) — Phase 16 / memoryjs v2.1.0
+| 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) — Phase 16 / memoryjs v2.1.0
+| 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) — Phase 16 / memoryjs v2.1.0
+| 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) — Phase 16 / memoryjs v2.1.0
+| Tool | Description |
+|------|-------------|
+| `find_duplicate_observations` | Exact duplicate observations across entities |
+| `find_jaccard_duplicate_observations` | Near-duplicates via Jaccard token similarity |
+
+#### Spell Correction (3 tools) — Phase 16 / memoryjs v2.1.0
+| 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) — v12.3.2
+| 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) — v12.5.0
+| 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) — v12.7.0 / memoryjs v3.0.0
+| 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) — v12.7.0 / memoryjs v3.0.0
+| 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) — v12.7.0 / memoryjs v3.0.0
+| 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) — v12.7.0 / memoryjs v3.0.0
+| 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 |
+
+#### v12.7.0 enhancements to existing tools
+- **`hybrid_search`** — Now accepts memoryjs v3's additive options: `graphWeight` (graph-connectivity channel via normalized PageRank), `expandNeighbors` (one-hop expansion of top results with damped scores), `explain` (annotate results with evidence paths from query anchors), and `lookFor` (rank expansion neighbors by a free-text connection description).
+
 ## Configuration
 
 ### Environment Variables
@@ -628,7 +782,7 @@ node dist/migrate-from-jsonl-to-sqlite.js --from memory.db --to memory.jsonl
 ```bash
 npm install           # Install dependencies
 npm run build         # Build TypeScript
-npm test              # Run tests (2800+ tests)
+npm test              # Run tests (791 tests across 36 files; ~85% coverage)
 npm run typecheck     # Strict type checking
 npm run watch         # Development watch mode
 npm run clean         # Remove dist/ directory
@@ -637,120 +791,85 @@ npm run docs:deps     # Generate dependency graph
 
 ### Architecture
 
+After the **Phase 13 extraction**, this repo is a thin MCP wrapper. All graph logic, managers, and storage live in [`@danielsimonjr/memoryjs`](https://www.npmjs.com/package/@danielsimonjr/memoryjs) (currently `^3.0.0`).
+
 ```
-┌─────────────────────────────────────────────────────┐
-│  Layer 1: MCP Protocol Layer                        │
-│  server/MCPServer.ts + toolDefinitions (160 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)         │
-└─────────────────────────────────────────────────────┘
+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 (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          # 160 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
+├── 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 (36 files, 791 tests, ~85% statement coverage)
+│   ├── unit/                               # Unit tests (response compressor, tool defs, validate-fact handler)
+│   ├── 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:**
-- `@modelcontextprotocol/sdk`: ^1.21.1
-- `better-sqlite3`: ^11.7.0
-- `zod`: ^4.1.13
-- `async-mutex`: ^0.5.0
-- `@danielsimonjr/workerpool`: ^10.0.1
+**Production** (3 direct deps — everything else is transitive via memoryjs):
+- `@danielsimonjr/memoryjs`: ^1.15.0 — knowledge graph engine (storage, managers, search, embeddings, RBAC, OCC, bitemporal, causal, etc.)
+- `@modelcontextprotocol/sdk`: ^1.21.1 — MCP protocol implementation
+- `zod`: ^3.24.1 — runtime input validation (schemas re-exported from memoryjs)
 
 **Development:**
 - `typescript`: ^5.6.2
 - `vitest`: ^4.0.13
 - `@vitest/coverage-v8`: ^4.0.13
-- `@types/better-sqlite3`: ^7.6.12
+- `shx`: ^0.4.0 — cross-platform shell commands for `clean` script
+- `@types/node`: ^22
+
+> Note: `better-sqlite3`, `async-mutex`, `@danielsimonjr/workerpool`, and the embedding providers (OpenAI / `@xenova/transformers`) are **transitive deps via `@danielsimonjr/memoryjs`** since the Phase 13 extraction. 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 160 tools
+- [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
@@ -766,6 +885,10 @@ Comprehensive documentation in `docs/`:
 - [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!
@@ -785,9 +908,16 @@ We welcome contributions!
 
 All notable changes are documented in **[CHANGELOG.md](CHANGELOG.md)**.
 
-**Current version**: v12.2.0 - [View full changelog](CHANGELOG.md)
+**Current version**: v12.7.0 - [View full changelog](CHANGELOG.md)
 
 Recent highlights:
+- **v12.7.0** (241 tools): Upgraded `@danielsimonjr/memoryjs` `^2.8.1` → `^3.0.0` and surfaced its new features as 16 tools — event memory (5), reconstructive Cue–Tag–Content memory + snapshot persistence (5), relation consolidation (2), agent reflection (4) — plus v3 graph-channel / evidence-path options on `hybrid_search`. Refactored handlers onto the new `ManagerContext` accessors (`hybridSearchManager`, `governanceManager`, `eventManager`, `reflectionManager`, `reconstructiveMemory()`, `close()`).
+- **v12.5.0** (225 tools): 10 engineering / diagnostic tools mirroring the memoryjs CLI surface (`diag`, `health`, `check_graph`, `reindex`, cache stats/clear, `graph_size`, `inspect_entity`, `hierarchy_tree`, `entity_neighbors`).
+- **v12.3.2** (215 tools): Backport of the deferred `set_project_scope` / `get_project_scope` pair.
+- **v12.3.0** (213 tools): **Phase 16** — 53 new tools surfacing memoryjs v2.1.0 across seven new manager surfaces: `do_not_remember` exclusion rules (5), decision rationale + ADR markdown dual-write (10), structured project context (12), heuristic guidelines (10), tool affordance + `ToolCallObserver` producer pipeline (11), observation dedup (2), spell correction (3). Bumped `@danielsimonjr/memoryjs` dep `^1.15.0` → `^2.1.0`.
+- **v12.2.3**: Publishability — switched `@danielsimonjr/memoryjs` dep from local `file:` link to published `^1.15.0` (npm rejects `file:` deps for published packages).
+- **v12.2.2**: Doc-only — roadmap completion audit grading Phase 6-15 status against current code.
+- **v12.2.1**: Doc-only — comprehensive consistency pass across 68 markdown documents to align with v12.2.0's 160-tool surface.
 - **v12.2.0** (160 tools): 23 new tools — entity bitemporal validity (η.4.4), OCC update (η.5.5.c), RBAC (η.6.1), procedural memory (3B.4), active retrieval (3B.5), causal reasoning (3B.6), world model (3B.7), plus W3C Linked Data exports (η.5.4) and PII redaction (η.6.3) wired into existing `export_graph`. Plus four pre-publish fixes from end-to-end MCP smoke testing (memoryjs v1.14+).
 - **v12.1.0** (106 tools): 12 new tools — Project Scoping, Memory Versioning, Semantic Forget, Profiles, Temporal KG, Ingestion, Agent Diary (memoryjs v1.8.0/v1.9.0)
 - **v12.0.0** (94 tools): 32 new tools — Ref Index, Artifacts, Temporal Search, Distillation, Freshness, LLM Query, Governance, Role Profiles, Entropy, Consolidation, Formatter, Collaborative, Failure Handling, Cognitive Load
@@ -820,7 +950,7 @@ Enhanced fork of [Model Context Protocol memory server](https://github.com/model
 - 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)
+- Comprehensive test suite (791 tests, 36 test files in this wrapper repo; full-coverage core graph tests live in `@danielsimonjr/memoryjs`)
 
 ---
 

package/dist/index.js

@@ -16,6 +16,18 @@ export { ManagerContext };
 // Backward compatibility alias
 export { ManagerContext as KnowledgeGraphManager };
 let managerContext;
+// Exit cleanly when our stdio pipe closes (e.g., Claude Code's /reload-plugins
+// tearing down the connection). Without this, other event-loop refs — file
+// watchers, the embeddings pool, the consolidation timer — can keep the
+// process alive as an orphan until manually killed.
+// ctx.close() (memoryjs v3) releases storage handles before exit; it is a
+// no-op for JSONL but closes the SQLite handle when MEMORY_STORAGE_TYPE=sqlite.
+function shutdown() {
+    managerContext?.close();
+    process.exit(0);
+}
+process.stdin.on("end", shutdown);
+process.stdin.on("close", shutdown);
 async function main() {
     // Initialize memory file path with backward compatibility
     const memoryFilePath = await ensureMemoryFilePath();

package/dist/server/MCPServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MCPServer.d.ts","sourceRoot":"","sources":["../../src/server/MCPServer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,OAAO,EAAU,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAOtE;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,GAAG,CAAiB;gBAEhB,GAAG,EAAE,cAAc;IAiB/B,OAAO,CAAC,oBAAoB;IAetB,KAAK;CAKZ"}
+{"version":3,"file":"MCPServer.d.ts","sourceRoot":"","sources":["../../src/server/MCPServer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,OAAO,EAAU,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAOtE;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,GAAG,CAAiB;IAE5B,YAAY,GAAG,EAAE,cAAc,EAe9B;IAED,OAAO,CAAC,oBAAoB;IAetB,KAAK,kBAIV;CACF"}

package/dist/server/toolDefinitions.d.ts

@@ -2,7 +2,7 @@
  * MCP Tool Definitions
  *
  * Extracted from MCPServer.ts to reduce file size and improve maintainability.
- * Contains all 106 tool schemas for the Knowledge Graph MCP Server.
+ * Contains all 241 tool schemas for the Knowledge Graph MCP Server.
  *
  * @module server/toolDefinitions
  */

package/dist/server/toolDefinitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolDefinitions.d.ts","sourceRoot":"","sources":["../../src/server/toolDefinitions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;CACH;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,cAAc,EAqlF3C,CAAC"}
+{"version":3,"file":"toolDefinitions.d.ts","sourceRoot":"","sources":["../../src/server/toolDefinitions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;CACH;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,cAAc,EAokH3C,CAAC"}