-
-
Notifications
You must be signed in to change notification settings - Fork 2
Architecture
Back to Home
This page describes the full technical design of the Neurodivergent Memory MCP Server: the district model, memory archetypes, canonical tag schema, tools, resources, prompts, retrieval, emotional metadata, and persistence.
Memories are partitioned into five cognitive districts that provide intentional context boundaries while still permitting cross-district graph connections.
| District | Archetype | Purpose |
|---|---|---|
logical_analysis |
Scholar | Structured thinking, problem solving, analytical processes |
emotional_processing |
Mystic | Feelings, emotional responses, affective states |
practical_execution |
Merchant | Action-oriented thoughts, tasks, implementation |
vigilant_monitoring |
Guard | Awareness, safety concerns, protective thinking |
creative_synthesis |
Mystic | Novel connections, creative insights, innovative thinking |
The district model is inspired by how neurodivergent cognition naturally partitions attention across parallel, non-linear contexts. Rather than flattening all memories into a single namespace, districts let agents — and humans — scope recall intentionally.
Cross-district connections are fully supported via the graph layer.
Each memory is automatically assigned a narrative archetype based on its district:
| Archetype | Districts | Role |
|---|---|---|
| Scholar | logical_analysis |
Diagnoses problems, structured reasoning |
| Merchant | practical_execution |
Proposes solutions, action-oriented |
| Mystic |
emotional_processing, creative_synthesis
|
Acknowledges experience, cross-domain insight |
| Guard | vigilant_monitoring |
Identifies threats, monitors risks |
This provides an elegant narrative framing for organizing thoughts across different cognitive modes.
All memories use structured tags in four namespaces to improve consistency, discoverability, and retrieval quality.
| Namespace | Purpose | Examples |
|---|---|---|
topic:X |
Subject matter of the memory |
topic:adhd-executive-function, topic:release
|
scope:X |
Breadth or boundary |
scope:concept, scope:project, scope:session, scope:global
|
kind:X |
Type of cognitive entry |
kind:insight, kind:pattern, kind:decision, kind:task, kind:reference
|
layer:X |
Abstraction level |
layer:architecture, layer:implementation, layer:debugging, layer:research
|
This schema applies to both human-authored and agent-authored entries.
Each memory can optionally carry emotional metadata:
| Field | Range | Description |
|---|---|---|
emotional_valence |
-1.0 to 1.0 | Emotional charge or affective tone (negative to positive) |
intensity |
0.0 to 1.0 | Mental energy or importance weight |
These fields are optional but enable emotional-context filtering in search queries.
| Tool | Description |
|---|---|
store_memory |
Create new memory nodes with optional emotional valence and intensity |
retrieve_memory |
Fetch a specific memory by ID and increment access count |
update_memory |
Modify content, tags, district, emotional_valence, or intensity |
delete_memory |
Remove a memory and all its connections |
connect_memories |
Create bidirectional edges between memory nodes |
search_memories |
BM25-ranked search with optional filters (district, tags, 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 |
list_memories |
Paginated listing with optional district/archetype filters |
memory_stats |
Aggregate statistics (totals, per-district counts, most-accessed, orphans) |
import_memories |
Bulk-seed memories from JSON array |
Memories are accessible as MCP resources via memory:// URIs.
- Explore memory districts and individual memories
- Each resource includes content, tags, emotional metadata, and connection information
- Access memories as JSON resources with full metadata
| Prompt | Description |
|---|---|
explore_memory_city |
Guided exploration of districts and memory organization |
synthesize_memories |
Create new insights by connecting existing memories |
The system uses Okapi BM25 (k1=1.5, b=0.75) for ranked lexical search over memory content. No embeddings or cloud calls are required. Results are normalized to a 0–1 score range.
Memories are connected via explicit typed relationships. Graph traversal allows the server to:
- Surface associatively linked memories during retrieval
- Trace chains of related context across districts
- Support future goal-aware and orchestration-aware retrieval strategies
The related_to tool uses a hybrid ranking approach:
- Hop proximity — directly connected memories score higher
- BM25 semantic relevance — distant memories scored by content match
- Blend creates a natural associative recall pattern
The memory_stats tool exposes aggregate health data: total counts, per-district breakdown, most-accessed memories, orphan detection, and connected subgraph analysis.
Memories are automatically persisted to:
~/.neurodivergent-memory/memories.json
The graph is restored on server startup. Every write operation updates the JSON snapshot immediately.
Current limitations (tracked in Roadmap):
- Single-file persistence — no journal/WAL pattern
- No concurrency control — unsafe for simultaneous writes from multiple agents
- Unbounded memory growth potential
The architecture is explicitly built for non-linear cognition. Rather than assuming a single flat thread of recall, it:
- Partitions context into districts with intentional boundaries
- Applies structured metadata so any entry is independently navigable
- Uses graph relationships to honor associative, non-sequential memory patterns
- Ranks retrieval by relevance rather than insertion order
- Carries emotional metadata so affective context is preserved alongside factual content
This makes the system natural for neurodivergent users and well-suited for multi-agent workflows where different agents operate in different cognitive modes simultaneously.
See also: Getting Started · Release Notes · Roadmap · White Paper