You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
An enhanced fork of the official Model Context Protocol memory server with advanced features for hierarchical nesting, intelligent compression, semantic search, graph algorithms, archiving, advanced search, and multi-format import/export.
Enterprise-grade knowledge graph with 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.
Restart Claude Desktop to load the enhanced memory server.
4. Start Using
Tell Claude:
Please remember that I prefer TypeScript over JavaScript.
Tag this as "preferences" with importance 8.
Create a parent entity called "Development Preferences" and nest this under it.
Installation
Local Build
# Clone repository
git clone https://github.com/danielsimonjr/memory-mcp.git
cd memory-mcp
# Install and build
npm install
npm run build
# Run tests (665 tests, >80% statement coverage)
npm test# Type check
npm run typecheck
Claude Desktop Configuration
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
interfaceEntity{name: string;// Unique identifierentityType: string;// Classificationobservations: string[];// Facts about the entityparentId?: string;// Parent entity name for hierarchical nestingtags?: string[];// Lowercase tags for categorizationimportance?: number;// 0-10 scale for prioritizationcreatedAt?: string;// ISO 8601 timestamplastModified?: string;// ISO 8601 timestamp}
Relations
Directed connections between entities.
interfaceRelation{from: string;// Source entity nameto: string;// Target entity namerelationType: string;// Relationship type (active voice)createdAt?: string;// ISO 8601 timestamplastModified?: string;// ISO 8601 timestamp}
Observations
Discrete facts about entities. Each observation should be atomic and independently manageable.
API Reference
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.
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
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.
cd tools/migrate-from-jsonl-to-sqlite
npm install && npm run build
# JSONL to SQLite
node dist/migrate-from-jsonl-to-sqlite.js --from memory.jsonl --to memory.db
# SQLite to JSONL
node dist/migrate-from-jsonl-to-sqlite.js --from memory.db --to memory.jsonl
Development
Prerequisites
Node.js 18+
npm 9+
TypeScript 5.6+
Build Commands
npm install # Install dependencies
npm run build # Build TypeScript
npm test# Run tests (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
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 (currently ^1.15.0).
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
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 - Complete API documentation for all 160 tools
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+).
