neurodivergent-memory MCP Server

📽️ Click to preview

Project Preview This is a Model Context Protocol server for knowledge graphs designed around neurodivergent thinking patterns. This TypeScript-based MCP server implements a memory system inspired by neurodivergent cognitive styles. It organizes thoughts into five districts (knowledge domains), ranks search results using BM25 semantic ranking, and stores memories as a persistent knowledge graph with bidirectional connections. Design note: The district model is rooted in FractalSemantics (FractalStat) addressing, where every entity inherits ancestry from a single anchor point called LUCA (Last Universal Common Ancestor). These concepts are also used in Warbler-CDA and the seed. The five canonical districts are the five direct children of LUCA in the default schema. Custom districts in later milestones must declare a valid LUCA-derived address, making ancestry explicit and traceable rather than assumed.

Quick-start

Windows

# Download and install Chocolatey:
powershell -c "irm https://community.chocolatey.org/install.ps1|iex"

# Download and install Node.js:
choco install nodejs --version="24.14.1"

# Verify the Node.js version:
node -v # Should print a Node.js 24.x version.

# Verify npm version:
npm -v # Should print an npm 11.x version.

# Run the packaged neurodivergent-memory CLI without a global install
npx neurodivergent-memory@latest init-agent-kit

Linux/macOS

# Download and install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

# in lieu of restarting the shell
. "$HOME/.nvm/nvm.sh"

# Download and install Node.js:
nvm install 24

# Verify the Node.js version:
node -v # Should print a Node.js 24.x version.

# Verify npm version:
npm -v # Should print an npm 11.x version.

# Run the packaged neurodivergent-memory CLI without a global install
npx neurodivergent-memory@latest init-agent-kit

Model Flow

flowchart LR
  A[Client MCP Request] --> B[MCP Server Stdio Transport]
  B --> C{Request Type}
  C -->|Tools| D[Tool Handler]
  C -->|Resources| E[Resource Handler]
  C -->|Prompts| F[Prompt Handler]

  D --> G[NeurodivergentMemory Core]
  E --> G
  F --> G

  G --> H[Memory Graph Store]
  G --> I[BM25 Index]
  H --> J[Persisted JSON Snapshot]

  D --> K[MCP JSON Response]
  E --> K
  F --> K
  K --> A

Flow notes:

• Memory operations update both graph state and BM25 index.
• Persistence writes to the local snapshot file for restart continuity.
• All MCP responses return through stdio transport.

Features

Five Memory Districts

Memories are organized by cognitive domain:

• logical_analysis — Structured thinking, problem solving, and analytical processes
• emotional_processing — Feelings, emotional responses, and affective states
• practical_execution — Action-oriented thoughts, tasks, and implementation
• vigilant_monitoring — Awareness, safety concerns, and protective thinking
• creative_synthesis — Novel connections, creative insights, and innovative thinking

Resources

• Explore memory districts and individual memories via memory:// URIs
• Each memory includes content, tags, emotional metadata, and connection information
• Access memories as JSON resources with full metadata

Tools

• store_memory — Create new memory nodes with optional emotional valence and intensity
• retrieve_memory — Fetch a specific memory by ID
• update_memory — Modify content, tags, district, emotional_valence, intensity, or project attribution
• delete_memory — Remove a memory and all its connections
• connect_memories — Create bidirectional edges between memory nodes
• search_memories — BM25-ranked semantic search with optional goal context, recency bias, and filters (district, project_id, tags, epistemic status, emotional valence, intensity, min_score)
• traverse_from — Graph traversal up to N hops from a starting memory
• related_to — Find memories by graph proximity + BM25 semantic blend, with optional goal context and epistemic-status filters
• list_memories — Paginated listing with optional district/archetype/project_id/epistemic-status filters
• memory_stats — Aggregate statistics (totals, per-district/per-project counts, most-accessed, orphans) with optional project scope
• server_handshake — Return runtime server identity/version details for explicit client-side version confirmation
• storage_diagnostics — Show the resolved snapshot path, WAL path, and effective persistence source in one response
• import_memories — Bulk-import from inline JSON entries or a snapshot file_path, with dry_run, dedupe policies, and explicit snapshot migration flags
• prepare_memory_city_context — Tool mirror of explore_memory_city for clients that support tools but do not invoke MCP prompts
• prepare_synthesis_context — Tool mirror of synthesize_memories for prompt-limited clients
• prepare_packetized_synthesis_context — Tool mirror of synthesize_memory_packets for prompt-limited or attachment-constrained clients

Prompts

• explore_memory_city — Guided exploration of districts and memory organization
• synthesize_memories — Create new insights by connecting existing memories
• synthesize_memory_packets — Packetized synthesis prompt for attachment-constrained clients; emits one coverage manifest plus bounded memory slices that summarize the broader graph

Use synthesize_memories when the MCP client can comfortably consume many raw memory resources. Use synthesize_memory_packets when the caller path is attachment-constrained or when you need broader graph coverage in a small number of structured resources.

For maximum interoperability across MCP clients, the server exposes the same synthesis/exploration context in two forms:

• Prompts via prompts/list + prompts/get for clients that implement MCP prompt invocation.
• Tools via the prepare_*_context tools for clients that support MCP tools but ignore or under-support prompts.

Some clients, such as Cline, expose MCP prompts as namespaced slash commands in the form /mcp:<server-name>:<prompt-name> rather than /<prompt-name>.

Core Concepts

Memory Archetypes

Each memory is assigned an archetype tied to its district:

• scholar — logical_analysis
• merchant — practical_execution
• mystic — emotional_processing and creative_synthesis
• guard — vigilant_monitoring

Semantic Ranking

Search uses Okapi BM25 ranking (k1=1.5, b=0.75) without requiring embeddings or cloud calls. Results are normalized to 0–1 score range.

Emotional Metadata

Each memory can optionally carry:

• emotional_valence (-1 to 1) — Emotional charge or affective tone
• intensity (0–1) — Mental energy or importance weight

Epistemic Status

Memories can optionally carry epistemic_status to distinguish tentative planning from validated knowledge.

• draft — provisional or planning-oriented
• validated — confirmed and safe to treat as established
• outdated — superseded but retained for history

When store_memory or import_memories creates a new practical_execution memory without an explicit epistemic_status, the server defaults it to draft if the memory has a task tag. The canonical task tag is kind:task, and the server also accepts the compatibility synonyms type:task and bare task. This keeps planning notes from silently presenting as settled fact.

Project Attribution and Scoped Retrieval

Memories can optionally include a first-class project_id for attribution and scoped retrieval across multi-project graphs.