convez.ai
MCP Server
danielsimonjr

memory-mcp

danielsimonjr/memory-mcp

Ver no GitHub
BomPluginScore · de 0 a 100

Enhanced Model Context Protocol memory server with timestamps, tags, importance, search, and export capabilities

Instalação

$npx convez-ai danielsimonjr/memory-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
2
Acompanhando
0
Saúde
100%
Último commit
há 2 dias
Versão
v12.10.0
Issues abertas
0
Contribuidores
936

README

A tradução para o português deste README ainda está na fila.

Memory MCP Server

Version NPM License MCP TypeScript Coverage

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.

Table of Contents

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

CategoryToolsDescription
Hierarchical Nesting9Parent-child relationships for organizing tree structures
Graph Algorithms4Path finding, connected components, centrality metrics
Intelligent Search3Hybrid multi-layer search with query analysis and reflection
Semantic Search3Embedding-based similarity search with OpenAI or local models
Memory Compression4Intelligent duplicate detection and merging with similarity scoring
Advanced Search7TF-IDF ranking, boolean queries, fuzzy matching, auto-select
Observation Normalization1Coreference resolution and temporal anchoring
Tag Management6Tags, bulk operations, importance scores
Tag Aliases5Tag synonym/alias management
Saved Searches5Store and execute frequent queries
Import/Export27 export formats (incl. W3C Linked Data: Turtle / JSON-LD / RDF/XML) with brotli + PII redaction; 3 import formats
Graph Analytics2Statistics, validation, integrity checks
Ref Index4Cross-session symbolic reference registration and resolution
Artifacts3Named versioned content blobs attached to entities
Temporal Search1Time-window filtered search across the knowledge graph
Distillation1Configure automated observation distillation pipelines
Freshness5Staleness tracking, expiry detection, and freshness reporting
LLM Query1Natural-language question answering over the graph
Governance4Transactional audit trail, history, and rollback
Role Profiles2Per-agent role assignment and profile listing
Entropy2Entropy-based noise filtering and information density scoring
Consolidation3Background memory consolidation scheduling and control
Formatter1Salience-budget-aware context formatting
Collaborative1Multi-agent context synthesis
Failure Handling2Session failure distillation and graceful session end
Cognitive Load2Working-memory load analysis and adaptive reduction
Dream Engine3Background memory maintenance: 8-phase sleep-cycle consolidation
Project Scoping1List and filter entities by project
Memory Versioning2Entity version chains and per-entity version history
Semantic Forget1Two-tier deletion: exact match → semantic similarity fallback
Profiles2User/agent profile get and update
Temporal KG3Temporal relation invalidation, time-travel queries, relation timeline
Ingestion1Format-agnostic conversation/document ingestion pipeline
Agent Diary2Per-agent persistent journal write and read
Session & Working Memory9Session lifecycle, working memory CRUD, TTL, promotion, context wake-up (Phase 14)
Auto-Enhancement3Auto-link entity mentions, fact extraction, contradiction detection (Phase 14)
Context Compression1N-gram text abbreviation with legend for token savings (Phase 14)
Consolidation Pipeline3Session consolidation, pattern detection, entity summarization (Phase 14)
Decay & Salience5Time-based decay, importance scoring, weak memory cleanup, reinforcement (Phase 14)
Multi-Agent5Agent registration, cross-agent search, visibility, conflict resolution (Phase 14)
Observability4D3.js graph visualization, transcript splitting, query cost estimation (Phase 14)
Dedup1Priority-based smart deduplication (Phase 14)
Entity Bitemporal5Time-travel queries: invalidate entities/observations, entity_as_of, timelines (Phase 15 / η.4.4)
Optimistic Concurrency1update_entity with expectedVersion → VersionConflictError on stale (Phase 15 / η.5.5.c)
RBAC4Role-based access control: assign/revoke/check/list reader/writer/admin/owner permissions (Phase 15 / η.6.1)
Procedural Memory5Executable how-to sequences with EWMA-refined success rate (Phase 15 / 3B.4)
Active Retrieval1Iterative query rewriting until coverage threshold met (Phase 15 / 3B.5)
Causal Reasoning4Chain discovery, counterfactual queries, cycle detection (Phase 15 / 3B.6)
World Model3Graph snapshots, fact validation, outcome prediction (Phase 15 / 3B.7)

Comparison with Official Memory Server

FeatureOfficialEnhanced (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 Tools11160
Code StructureMonolithicModular (5 src files in this repo; core graph in @danielsimonjr/memoryjs)

Quick Start

1. Install from NPM

npm install -g @danielsimonjr/memory-mcp

Or use with npx (no installation required):

npx @danielsimonjr/memory-mcp

2. Configure Claude Desktop

Add to claude_desktop_config.json:

Using NPM Global Install:

{
  "mcpServers": {
    "memory": {
      "command": "mcp-server-memory"
    }
  }
}

Using NPX:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@danielsimonjr/memory-mcp"]
    }
  }
}

3. Restart Claude Desktop

Restart Claude Desktop to load the enhanced memory server.

4. Start Using

Tell Claude:

Please remember that I prefer TypeScript over JavaScript.
Tag this as "preferences" with importance 8.
Create a parent entity called "Development Preferences" and nest this under it.

Installation

Local Build

# Clone repository
git clone https://github.com/danielsimonjr/memory-mcp.git
cd memory-mcp

# Install and build
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):

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["<PATH_TO>/memory-mcp/dist/index.js"],
      "env": {
        "MEMORY_FILE_PATH": "<PATH_TO>/memory.jsonl"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

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

Core Concepts

Entities

Primary nodes in the knowledge graph.

interface Entity {
  name: string;           // Unique identifier
  entityType: string;     // Classification
  observations: string[]; // Facts about the entity
  parentId?: string;      // Parent entity name for hierarchical nesting
  tags?: string[];        // Lowercase tags for categorization
  importance?: number;    // 0-10 scale for prioritization
  createdAt?: string;     // ISO 8601 timestamp
  lastModified?: string;  // ISO 8601 timestamp
}

Relations

Directed connections between entities.

interface Relation {
  from: string;           // Source entity name
  to: string;             // Target entity name
  relationType: string;   // Relationship type (active voice)
  createdAt?: string;     // ISO 8601 timestamp
  lastModified?: string;  // ISO 8601 timestamp
}

Observations

Discrete facts about entities. Each observation should be atomic and independently manageable.

API Reference

Complete Tool List (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.

Entity Operations (4 tools)

ToolDescription
create_entitiesCreate multiple new entities
delete_entitiesRemove entities and their relations
read_graphRead entire knowledge graph
open_nodesRetrieve specific nodes by name

Relation Operations (2 tools)

ToolDescription
create_relationsCreate relations between entities
delete_relationsRemove specific relations

Observation Management (3 tools)

ToolDescription
add_observationsAdd observations to entities
delete_observationsRemove specific observations
normalize_observationsNormalize observations (resolve pronouns, anchor dates)

Search (7 tools)

ToolDescription
search_nodesSearch with filters (tags, importance)
search_by_date_rangeFilter by date range
search_nodes_rankedTF-IDF relevance ranking
boolean_searchBoolean queries (AND/OR/NOT)
fuzzy_searchTypo-tolerant search
get_search_suggestions"Did you mean?" suggestions
search_autoAuto-select best search method

Intelligent Search (3 tools)

ToolDescription
hybrid_searchMulti-layer search combining semantic, lexical, and symbolic signals
analyze_queryExtract entities, temporal references, and classify query complexity
smart_searchReflection-based iterative search until results meet adequacy threshold

Semantic Search (3 tools)

ToolDescription
semantic_searchSearch by semantic similarity using embeddings
find_similar_entitiesFind entities similar to a reference entity
index_embeddingsBuild or rebuild the semantic search index

Saved Searches (5 tools)

ToolDescription
save_searchSave search query for reuse
execute_saved_searchExecute a saved search
list_saved_searchesList all saved searches
delete_saved_searchDelete a saved search
update_saved_searchUpdate saved search parameters

Tag Management (6 tools)

ToolDescription
add_tagsAdd tags to an entity
remove_tagsRemove tags from an entity
set_importanceSet entity importance (0-10)
add_tags_to_multiple_entitiesBulk tag operation
replace_tagReplace tag globally
merge_tagsMerge two tags into one

Tag Aliases (5 tools)

ToolDescription
add_tag_aliasCreate tag synonym
list_tag_aliasesList all aliases
remove_tag_aliasRemove an alias
get_aliases_for_tagGet aliases for canonical tag
resolve_tagResolve alias to canonical form

Hierarchical Nesting (9 tools)

ToolDescription
set_entity_parentSet/remove parent relationship
get_childrenGet immediate children
get_parentGet parent entity
get_ancestorsGet all ancestors (parent chain)
get_descendantsGet all descendants (recursive)
get_subtreeGet entity + descendants with relations
get_root_entitiesGet entities with no parent
get_entity_depthGet depth in hierarchy
move_entityMove entity to new parent

Graph Algorithms (4 tools)

ToolDescription
find_shortest_pathShortest path between entities (BFS)
find_all_pathsAll paths with max depth limit
get_connected_componentsDetect isolated subgraphs
get_centralityCalculate centrality metrics (degree, betweenness, PageRank)

Graph Analytics (2 tools)

ToolDescription
get_graph_statsComprehensive graph statistics
validate_graphValidate graph integrity

Compression & Archiving (4 tools)

ToolDescription
find_duplicatesFind similar entities by threshold
merge_entitiesMerge multiple entities into one
compress_graphAuto compression with dry-run
archive_entitiesArchive by age, importance, or tags

Import & Export (2 tools)

ToolDescription
export_graphExport in 7 formats (JSON, CSV, GraphML, GEXF, DOT, Markdown, Mermaid) with compression
import_graphImport from JSON/CSV/GraphML with merge strategies

Ref Index (4 tools)

ToolDescription
register_refRegister a symbolic reference pointing to an entity
resolve_refResolve a symbolic reference to its target entity
deregister_refRemove a registered symbolic reference
list_refsList all registered symbolic references

Artifacts (3 tools)

ToolDescription
create_artifactCreate a named versioned content blob attached to an entity
get_artifactRetrieve an artifact by name and optional version
list_artifactsList all artifacts, optionally filtered by entity

Temporal Search (1 tool)

ToolDescription
search_by_timeSearch entities and observations within a time window

Distillation (1 tool)

ToolDescription
configure_distillationConfigure automated observation distillation pipelines

Freshness (5 tools)

ToolDescription
check_freshnessCheck freshness status of a specific entity
get_stale_entitiesList entities that have exceeded their staleness threshold
get_expired_entitiesList entities past their explicit expiry date
refresh_entityReset the freshness timestamp on an entity
freshness_reportGenerate a full freshness report across the graph

LLM Query (1 tool)

ToolDescription
query_natural_languageAnswer natural-language questions over the knowledge graph

Governance (4 tools)

ToolDescription
governance_transactionExecute a governed, audited graph transaction
audit_queryQuery the audit log with filters
audit_historyRetrieve full audit history for an entity
rollback_operationRoll back a previously recorded operation

Role Profiles (2 tools)

ToolDescription
set_agent_roleAssign a role profile to the current agent context
list_role_profilesList all available agent role profiles

Entropy (2 tools)

ToolDescription
enable_entropy_filterEnable entropy-based noise filtering for search results
compute_entropyCompute information-density entropy score for an entity

Consolidation (3 tools)

ToolDescription
start_consolidationStart the background memory consolidation service
stop_consolidationStop the background memory consolidation service
run_consolidation_nowTrigger an immediate consolidation pass

Formatter (1 tool)

ToolDescription
format_with_salience_budgetFormat context output respecting a token salience budget

Collaborative (1 tool)

ToolDescription
synthesize_collaborative_contextSynthesize a unified context view from multiple agent memory spaces

Failure Handling (2 tools)

ToolDescription
distill_failureDistill and store key observations from a failed session
end_sessionGracefully end a session and persist in-flight state

Cognitive Load (2 tools)

ToolDescription
analyze_cognitive_loadAnalyze working-memory load in the current context
adaptive_reduce_memoriesAdaptively reduce memory set to fit cognitive load target

Project Scoping (1 tool)

ToolDescription
list_projectsList all project IDs present in the graph and filter entities by project

Memory Versioning (2 tools)

ToolDescription
get_entity_versionsRetrieve all versions of a versioned entity by name
get_version_chainGet the full version chain from root to latest for an entity

Semantic Forget (1 tool)

ToolDescription
forget_memoryDelete an entity by exact name, falling back to semantic similarity if no exact match found

Profiles (2 tools)

ToolDescription
get_profileRetrieve a user or agent profile entity
update_profileUpdate observations and metadata on a profile entity

Temporal KG (3 tools)

ToolDescription
invalidate_relationMark a relation as ended by setting its temporal validity end date
query_as_ofRetrieve all relations for an entity that were valid at a given point in time
timelineReturn a chronological list of relation events for an entity

Ingestion (1 tool)

ToolDescription
ingestIngest a conversation, document, or free-form text into the knowledge graph

Agent Diary (2 tools)

ToolDescription
diary_writeAppend an entry to the agent's persistent diary
diary_readRead diary entries for an agent, optionally filtered by date range

Entity Bitemporal Validity (5 tools) — Phase 15 / memoryjs η.4.4

ToolDescription
invalidate_entityStamp validUntil on an entity (idempotent; entity remains queryable for past timestamps via entity_as_of)
entity_as_ofTime-travel query: returns entity state at a given ISO 8601 timestamp, or null if invalidated then
entity_timelineAll temporal versions of an entity in chronological order; integrates the v1.8 supersession chain
invalidate_observationPer-observation invalidation via parallel observationMeta[] entry on the entity
observations_as_ofFilter observations valid at a given timestamp; observations without meta are treated as unbounded

Optimistic Concurrency Control (1 tool) — Phase 15 / memoryjs η.5.5.c

ToolDescription
update_entityUpdate 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

ToolDescription
rbac_assign_roleGrant reader / writer / admin / owner (or custom) role to an agent; optional resourceType, scope prefix, validFrom / validUntil window
rbac_revoke_roleRemove a specific role assignment matched by agentId + role + resourceType
rbac_check_permissionCheck whether an agent can perform read / write / delete / manage on a resource type; falls back to defaultRole=reader for unassigned agents
rbac_list_assignmentsList all role assignments for an agent; optional activeOnly filter

Procedural Memory (5 tools) — Phase 15 / memoryjs 3B.4

ToolDescription
add_procedurePersist an executable how-to sequence: 1-indexed steps with optional fallback chains and free-form trigger phrases
get_procedureLoad a procedure by id
match_procedureToken-overlap match a context description against stored procedures; returns ranked Jaccard-like scores
refine_procedureApply caller feedback after execution; updates successRate via EWMA (α=0.2)
get_procedure_stepLoad step by 1-indexed order, or get the next step relative to currentOrder

Active Retrieval (1 tool) — Phase 15 / memoryjs 3B.5

ToolDescription
adaptive_retrieveIterative 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

ToolDescription
find_causesCausal chains ending at the named effect; sorted by product-of-edge causalStrength
find_effectsSymmetric 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_cyclesDetect cycles in the causal subgraph rooted at seed

World Model (3 tools) — Phase 15 / memoryjs 3B.7

ToolDescription
get_world_stateCapture a fresh snapshot of the live graph (capped at 1000 entities; over-cap prefers high-importance)
validate_fact_against_worldValidate 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_outcomePredict 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

VariableDescriptionDefault
MEMORY_FILE_PATHPath to storage filememory.jsonl (current directory)
MEMORY_STORAGE_TYPEStorage backend: jsonl or sqlitejsonl
MEMORY_EMBEDDING_PROVIDEREmbedding provider: openai, local, or nonenone
MEMORY_OPENAI_API_KEYOpenAI API key (required if provider is openai)-
MEMORY_EMBEDDING_MODELEmbedding model to usetext-embedding-3-small (OpenAI) / Xenova/all-MiniLM-L6-v2 (local)
MEMORY_AUTO_INDEX_EMBEDDINGSAuto-index entities on creationfalse

Storage Backends

FeatureJSONL (Default)SQLite (better-sqlite3)
FormatHuman-readable textNative binary database
TransactionsBasicFull ACID with WAL mode
Full-Text SearchBasicFTS5 with BM25 ranking
PerformanceGood3-10x faster
ConcurrencySingle-threadedThread-safe with async-mutex
Best ForSmall graphs, debuggingLarge graphs (10k+ entities)

Using SQLite:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/memory-mcp/dist/index.js"],
      "env": {
        "MEMORY_STORAGE_TYPE": "sqlite",
        "MEMORY_FILE_PATH": "/path/to/data/memory.db"
      }
    }
  }
}

Storage Files

When you set MEMORY_FILE_PATH, the server automatically creates related files:

/your/data/directory/
├── memory.jsonl                    # Main knowledge graph
├── memory-saved-searches.jsonl     # Saved search queries
├── memory-tag-aliases.jsonl        # Tag synonym mappings
└── .backups/                       # Timestamped backups
    ├── backup_2026-01-08_10-30-00-123.jsonl
    └── backup_2026-01-08_10-30-00-123.jsonl.meta.json

Migration Tool

Convert between JSONL and SQLite formats:

cd tools/migrate-from-jsonl-to-sqlite
npm install && npm run build

# JSONL to SQLite
node dist/migrate-from-jsonl-to-sqlite.js --from memory.jsonl --to memory.db

# SQLite to JSONL
node dist/migrate-from-jsonl-to-sqlite.js --from memory.db --to memory.jsonl

Development

Prerequisites

  • 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).

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
LayerLives inFiles
MCP protocol (stdio transport, tool registration, dispatch)memory-mcp5
Tool schemas (160 tools across 51 categories)memory-mcp (toolDefinitions.ts)1
Handler registry + Zod validation + response compressionmemory-mcp (toolHandlers.ts + responseCompressor.ts)2
Managers (Entity / Relation / Search / IO / Tag / Hierarchy / Analytics / Compression / Archive / GraphTraversal / SemanticSearch / RankedSearch / etc.)memoryjs100+
Storage (JSONL + SQLite with FTS5 + StorageFactory + TransactionManager)memoryjs—
Embedding providers (OpenAI / local / none) + VectorStorememoryjs—

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

User Guides

Development

Contributing

We welcome contributions!

See:

Ways to Help:

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

Changelog

All notable changes are documented in CHANGELOG.md.

Current version: v12.3.0 - View full changelog

Recent highlights:

  • 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

MIT License - see LICENSE

Acknowledgments

Original Project

Enhanced fork of Model Context Protocol memory server by Anthropic.

Developer

Daniel Simon Jr.

Major Enhancements

  • Hierarchical nesting with parent-child relationships
  • Graph algorithms: path finding, centrality, connected components
  • Semantic search with embedding-based similarity
  • Brotli compression for backups, exports, and responses
  • Memory compression with intelligent duplicate detection
  • Smart archiving with criteria-based filtering
  • Advanced search: TF-IDF, boolean, and fuzzy matching
  • Multi-format import/export with merge strategies
  • SQLite backend with better-sqlite3 (3-10x faster)
  • Transaction support with ACID guarantees
  • Comprehensive test suite (665 tests, 26 test files in this wrapper repo; 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

Ver o original no GitHub

Bom para

Relacionados