@danielsimonjr/memory-mcp 11.1.1 → 12.5.2

package/README.md

@@ -1,15 +1,15 @@
 # Memory MCP Server
 
-[![Version](https://img.shields.io/badge/version-10.1.0-blue.svg)](https://github.com/danielsimonjr/memory-mcp)
+[![Version](https://img.shields.io/badge/version-12.5.1-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-80.7%25-yellow.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 59 tools, hierarchical organization, semantic search with embeddings, graph traversal algorithms, duplicate detection, smart archiving, and sophisticated search capabilities for long-term memory management.
+> **Enterprise-grade knowledge graph** with **213 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**, and **spell correction** (memoryjs v2.1.0 — Phase 16) for long-term memory management.
 
 ## Table of Contents
 
@@ -46,10 +46,48 @@ 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 |
+| **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 *(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
 
@@ -72,8 +110,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 | **59** |
-| **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
 
@@ -142,7 +180,7 @@ cd memory-mcp
 npm install
 npm run build
 
-# Run tests (2800+ tests)
+# Run tests (665 tests, >80% statement coverage)
 npm test
 
 # Type check
@@ -221,7 +259,9 @@ Discrete facts about entities. Each observation should be atomic and independent
 
 ## API Reference
 
-### Complete Tool List (59 Tools)
+### Complete Tool List (160 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).
 
 #### Entity Operations (4 tools)
 | Tool | Description |
@@ -338,6 +378,190 @@ Discrete facts about entities. Each observation should be atomic and independent
 | `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) — Phase 15 / memoryjs η.4.4
+| 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 v1.8 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) — Phase 15 / memoryjs η.5.5.c
+| 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) — Phase 15 / memoryjs η.6.1
+| 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) — Phase 15 / memoryjs 3B.4
+| 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) — Phase 15 / memoryjs 3B.5
+| Tool | Description |
+|------|-------------|
+| `adaptive_retrieve` | Iterative query-rewriting retrieval (search → score coverage → rewrite); stops early when `coverage ≥ minCoverage`. Pure symbolic — no LLM provider required. |
+
+#### Causal Reasoning (4 tools) — Phase 15 / memoryjs 3B.6
+| 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) — Phase 15 / memoryjs 3B.7
+| 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`) |
+
+#### Phase 15 enhancements to existing tools
+- **`export_graph`** — Now accepts `format: 'turtle' | 'rdf-xml' | 'json-ld'` for W3C Linked Data exports (memoryjs η.5.4) and `redactPii: true` to scrub PII (email / SSN / credit-card / phone / IPv4) from observations using the η.6.3 `PiiRedactor`.
+- **`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`).
+
 ## Configuration
 
 ### Environment Variables
@@ -421,7 +645,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 (665 tests across 26 files; >80% coverage)
 npm run typecheck     # Strict type checking
 npm run watch         # Development watch mode
 npm run clean         # Remove dist/ directory
@@ -430,120 +654,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 `^1.15.0`).
+
 ```
-┌─────────────────────────────────────────────────────┐
-│  Layer 1: MCP Protocol Layer                        │
-│  server/MCPServer.ts + toolDefinitions (59 tools)   │
-│  + toolHandlers + responseCompressor                │
-└──────────────────────┬──────────────────────────────┘
-                       │
-┌──────────────────────┴──────────────────────────────┐
-│  Layer 2: Managers + Context (Lazy Initialization)  │
-│  ManagerContext (aliased as KnowledgeGraphManager)  │
-│  • EntityManager   (CRUD + hierarchy + archive)     │
-│  • RelationManager (relation CRUD)                  │
-│  • SearchManager   (search + compression + stats)   │
-│  • IOManager       (import + export + backup)       │
-│  • TagManager      (tag aliases)                    │
-│  • GraphTraversal  (path finding, centrality)       │
-│  • SemanticSearch  (embeddings, similarity)         │
-└──────────────────────┬──────────────────────────────┘
-                       │
-┌──────────────────────┴──────────────────────────────┐
-│  Layer 3: Storage Layer                             │
-│  core/GraphStorage.ts (JSONL + in-memory cache)     │
-│  core/SQLiteStorage.ts (better-sqlite3 + FTS5)      │
-│  core/StorageFactory.ts (backend selection)         │
-└─────────────────────────────────────────────────────┘
+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 (160 tools across 51 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          # 59 tool schemas
-│   │   ├── toolHandlers.ts             # Handler registry
-│   │   └── responseCompressor.ts       # Brotli compression
-│   ├── search/                     # Search implementations (29 files)
-│   │   ├── SearchManager.ts            # Search orchestrator
-│   │   ├── BasicSearch.ts              # Text matching
-│   │   ├── RankedSearch.ts             # TF-IDF scoring
-│   │   ├── BooleanSearch.ts            # AND/OR/NOT logic
-│   │   ├── FuzzySearch.ts              # Typo tolerance
-│   │   ├── SemanticSearch.ts           # Embedding-based
-│   │   ├── EmbeddingService.ts         # Provider abstraction
-│   │   ├── VectorStore.ts              # Vector storage
-│   │   └── ...                         # + 12 more
-│   ├── features/                   # Advanced capabilities (9 files)
-│   │   ├── IOManager.ts                # Import/export/backup
-│   │   ├── TagManager.ts               # Tag aliases
-│   │   ├── AnalyticsManager.ts         # Graph stats
-│   │   ├── ArchiveManager.ts           # Entity archival
-│   │   ├── CompressionManager.ts       # Duplicate detection
-│   │   ├── StreamingExporter.ts        # Large graph exports
-│   │   ├── ObservationNormalizer.ts    # Coreference resolution
-│   │   ├── KeywordExtractor.ts         # Keyword extraction
-│   │   └── index.ts
-│   ├── types/                      # TypeScript definitions (2 files)
-│   ├── utils/                      # Shared utilities (18 files)
-│   └── workers/                    # Worker pool (2 files)
-├── tests/                          # Test suite (97 files, 2800+ tests)
-│   ├── unit/                       # Unit tests
-│   ├── integration/                # Integration tests
-│   ├── e2e/                        # End-to-end tests
-│   └── performance/                # Benchmarks
-├── dist/                           # Compiled output
-├── docs/                           # Documentation
-│   ├── architecture/               # Architecture docs
-│   ├── guides/                     # User guides
-│   └── reports/                    # Sprint reports
-├── tools/                          # Standalone utilities
-│   ├── chunking-for-files/         # File splitting
-│   ├── compress-for-context/       # CTON compression
-│   ├── create-dependency-graph/    # Dependency analyzer
-│   └── migrate-from-jsonl-to-sqlite/
-├── CHANGELOG.md                    # Version history
-└── README.md                       # This file
+├── 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              # 160 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 (26 files, 665 tests, >80% 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 59 tools
+- [API.md](docs/architecture/API.md) - Complete API documentation for all 160 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
@@ -578,12 +767,18 @@ We welcome contributions!
 
 All notable changes are documented in **[CHANGELOG.md](CHANGELOG.md)**.
 
-**Current version**: v10.1.0 - [View full changelog](CHANGELOG.md)
+**Current version**: v12.3.0 - [View full changelog](CHANGELOG.md)
 
 Recent highlights:
-- **v10.1.0**: Documentation updates, 5 missing Phase 12 test files, architecture docs refresh
-- **v10.0.0**: Phase 12 Performance Optimization - BM25 search, parallel execution, query plan caching, embedding cache, incremental indexing
-- **v9.8.3**: SQLite storage support fix, JSON-RPC communication fix
+- **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
+- **v11.1.1**: npm tarball cleanup, excluded data files from published package
+- **v11.1.0**: MCP error framing, dynamic server version, handler smoke tests, response compressor tests
 
 ## License
 
@@ -611,7 +806,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 (665 tests, 26 test files in this wrapper repo; full-coverage core graph tests live in `@danielsimonjr/memoryjs`)
 
 ---
 

package/dist/index.d.ts

@@ -7,9 +7,9 @@
  *
  * @module index
  */
-import { defaultMemoryPath, ensureMemoryFilePath, ManagerContext, type Entity, type Relation, type KnowledgeGraph, type GraphStats, type ValidationReport, type ValidationIssue, type ValidationWarning, type SavedSearch, type TagAlias, type SearchResult, type BooleanQueryNode, type ImportResult, type CompressionResult } from '@danielsimonjr/memoryjs';
+import { defaultMemoryPath, ensureMemoryFilePath, ManagerContext, type Entity, type Relation, type KnowledgeGraph, type GraphStats, type ValidationReport, type ValidationIssue, type ValidationWarning, type SavedSearch, type TagAlias, type SearchResult, type BooleanQueryNode, type ImportResult, type CompressionResult, type ArtifactEntity, type ArtifactType, type ArtifactFilter, type FreshnessReport, type AuditEntry, type AuditOperation, type RefEntry, type RefIndexStats, type AgentRole, type RoleProfile, type CognitiveLoadMetrics, type AdaptiveReductionResult, type SynthesisResult, type FailureDistillationResult, type DistilledLesson } from '@danielsimonjr/memoryjs';
 export { defaultMemoryPath, ensureMemoryFilePath };
-export type { Entity, Relation, KnowledgeGraph, GraphStats, ValidationReport, ValidationIssue, ValidationWarning, SavedSearch, TagAlias, SearchResult, BooleanQueryNode, ImportResult, CompressionResult, };
+export type { Entity, Relation, KnowledgeGraph, GraphStats, ValidationReport, ValidationIssue, ValidationWarning, SavedSearch, TagAlias, SearchResult, BooleanQueryNode, ImportResult, CompressionResult, ArtifactEntity, ArtifactType, ArtifactFilter, FreshnessReport, AuditEntry, AuditOperation, RefEntry, RefIndexStats, AgentRole, RoleProfile, CognitiveLoadMetrics, AdaptiveReductionResult, SynthesisResult, FailureDistillationResult, DistilledLesson, };
 export { ManagerContext };
 export { ManagerContext as KnowledgeGraphManager };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG;AAEH,OAAO,EAEL,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EAEd,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,CAAC;AAGnD,YAAY,EACV,MAAM,EACN,QAAQ,EACR,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,GAClB,CAAC;AAGF,OAAO,EAAE,cAAc,EAAE,CAAC;AAG1B,OAAO,EAAE,cAAc,IAAI,qBAAqB,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG;AAEH,OAAO,EAEL,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EAEd,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EAEtB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,KAAK,eAAe,EACrB,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,CAAC;AAGnD,YAAY,EACV,MAAM,EACN,QAAQ,EACR,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EAEjB,cAAc,EACd,YAAY,EACZ,cAAc,EACd,eAAe,EACf,UAAU,EACV,cAAc,EACd,QAAQ,EACR,aAAa,EACb,SAAS,EACT,WAAW,EACX,oBAAoB,EACpB,uBAAuB,EACvB,eAAe,EACf,yBAAyB,EACzB,eAAe,GAChB,CAAC;AAGF,OAAO,EAAE,cAAc,EAAE,CAAC;AAG1B,OAAO,EAAE,cAAc,IAAI,qBAAqB,EAAE,CAAC"}

package/dist/index.js

@@ -16,6 +16,12 @@ 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.
+process.stdin.on("end", () => process.exit(0));
+process.stdin.on("close", () => process.exit(0));
 async function main() {
     // Initialize memory file path with backward compatibility
     const memoryFilePath = await ensureMemoryFilePath();

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 59 tool schemas for the Knowledge Graph MCP Server.
+ * Contains all 106 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,EA6gC3C,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,EAm0G3C,CAAC"}