Neurodivergent Memory

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: : rather than / .

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.

• project_id is optional on writes (store_memory, update_memory, import_memories).
• update_memory accepts project_id: null to clear existing project attribution.
• search_memories, list_memories, and memory_stats accept an optional project_id filter.
• search_memories, list_memories, and related_to accept optional epistemic_statuses filters so callers can avoid stale planning memories when appropriate.
• search_memories accepts optional context and recency_weight parameters. Context is blended into ranking as a lightweight BM25 boost; recency_weight must be between 0 and 1 and adds a recency boost without replacing semantic relevance.
• search_memories accepts min_intensity / max_intensity as the preferred intensity filter names. The legacy intensity_min / intensity_max aliases remain supported for compatibility.
• related_to accepts an optional context parameter to bias related-memory ranking toward the caller's current goal.
• Stats now include a perProject breakdown.
• Scoped memory_stats reports totalConnections only for edges where both endpoints are in scope.
• list_memories includes a project: ... segment in each line (unset when no project attribution exists).
• Validation contract: project_id must match ^A-Za-z0-9{0,63}$ (max length 64).
• Invalid values return stable error code NM_E020 with recovery guidance.

Import Diagnostics and Migration Semantics

storage_diagnostics reports the resolved snapshot path, the WAL path, and which configuration source won the persistence-path precedence check.

import_memories supports two source modes:

• Inline entries for ordinary bulk seeding.
• file_path for server snapshot imports, avoiding large MCP payloads.

Import validation flags:

• dry_run: true validates the request without writing data and returns deterministic would_import, would_skip, and would_fail counts.
• dedupe accepts none, content_hash, or content_plus_tags.
• Deduplicated rows are reported with stable reason codes: DEDUPE_CONTENT_HASH or DEDUPE_CONTENT_PLUS_TAGS.
• Snapshot file_path imports accept .json files under the resolved persistence directory by default. Set NEURODIVERGENT_MEMORY_IMPORT_ALLOW_EXTERNAL_FILE=true only when importing external snapshot files intentionally.

Snapshot migration flags:

• preserve_ids is only valid with file_path; any ID collision with the live store is rejected deterministically.
• merge_connections is only valid with file_path; every referenced connection target must exist either in the imported snapshot or the live store, or the row fails validation with `INVALID_CONNECTION_TARGET