Skip to content

Architecture

Jump to bottom
Bellok edited this page Apr 4, 2026 · 8 revisions

Architecture

Back to Home

This page describes the current technical design of the Neurodivergent Memory MCP Server in the repository today: the district model, archetypes, canonical tags, prompts, retrieval model, persistence, and the trust-and-telemetry foundation introduced in v0.2.0 and extended by the 0.3.0 release.

District Model

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 rooted in FractalSemantics addressing, where every entity inherits ancestry from a single anchor point called LUCA (Last Universal Common Ancestor). The five canonical districts are the five direct children of LUCA in the default schema.

Cross-district connections are fully supported via the graph layer.

Memory Archetypes

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

Canonical Tag Schema

All memories use structured tags in five 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
persistence:X Sync-tier eligibility persistence:durable, persistence:ephemeral

This schema applies to both human-authored and agent-authored entries.

When authoring memories directly, do not stop at the event log. practical_execution entries should capture why the action was taken and, when the reasoning is reusable, connect or pair with a logical_analysis or creative_synthesis entry that preserves the durable principle.

Memory Quality Guardrails

  • Do not leave execution-only memories behind. A memory that says what changed should also say why it changed or connect to a memory that does.
  • Prefer connective synthesis over isolated task logs: reusable principles belong in logical_analysis or creative_synthesis, even when the triggering work happened in practical_execution.
  • Use distill_memory when a noisy debug or emotional trail contains durable signal that should survive without the surrounding implementation detail.

Emotional Metadata

Each memory can optionally carry emotional metadata:

Field Range Description
emotional_valence -1.0 to 1.0 Emotional charge or affective tone
intensity 0.0 to 1.0 Mental energy or importance weight

These fields remain optional but enable affect-aware filtering during retrieval.

Epistemic Status

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

Status Meaning
draft Provisional, planning-oriented, or not yet validated
validated Confirmed and safe to treat as established
outdated Superseded but retained for historical context

Current defaulting rule: when store_memory or import_memories creates a practical_execution memory tagged kind:task and the caller omits epistemic_status, the server sets it to draft. This keeps planning notes from presenting as settled fact by default.

Tools (17 Operations)

Tool Description
store_memory Create new memory nodes with optional emotional metadata, project_id, and explicit epistemic_status; new practical_execution task memories default to draft when status is omitted
retrieve_memory Fetch a specific memory by ID
update_memory Modify content, tags, district, emotional metadata, and project attribution
delete_memory Remove a memory and all its connections
connect_memories Create bidirectional edges between memory nodes
search_memories BM25-ranked search with optional district, tag, emotional, project_id, and epistemic_statuses filters plus goal-context and recency tuning
traverse_from Graph traversal up to N hops from a starting memory
related_to Find memories by graph proximity plus BM25 semantic blend, with optional goal context and epistemic_statuses filters
list_memories Paginated listing with optional district, archetype, project_id, and epistemic_statuses filters
memory_stats Aggregate statistics with per-district and per-project breakdowns, most-accessed entries, and loop telemetry
storage_diagnostics Reveal resolved snapshot path, WAL path, and effective persistence source
import_memories Bulk-import inline entries or snapshot files with dry-run, dedupe, migration controls, and the same planning-task epistemic-status defaulting used by store_memory
distill_memory Translate emotional_processing signal into a structured logical artifact
prepare_memory_city_context Tool mirror of explore_memory_city for clients that support tools but not prompts
prepare_synthesis_context Tool mirror of synthesize_memories for prompt-limited clients
prepare_packetized_synthesis_context Tool mirror of synthesize_memory_packets for attachment-constrained clients
register_district Register a custom district with LUCA ancestry validation and inherited archetype

Resources

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.
  • District resources pair naturally with the explore_memory_city prompt.

Prompts

Prompt Description
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

Retrieval

BM25 Ranked Lexical Retrieval

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.

Graph Traversal

Memories are connected via explicit 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.

Associative Retrieval (related_to)

The related_to tool uses a hybrid ranking approach:

  • Hop proximity: directly connected memories score higher.
  • BM25 semantic relevance: more distant memories are scored by content match.
  • Goal context: an optional short context string can boost memories that match the caller's current objective.
  • Epistemic filtering: callers can restrict related memories to draft, validated, outdated, or unset entries.
  • The blend creates a natural associative recall pattern.

Retrieval Filter Parity

search_memories, related_to, and list_memories now all accept optional epistemic_statuses filters. This keeps non-search retrieval surfaces aligned when callers want to exclude stale or still-draft planning memories.

Memory Statistics

The memory_stats tool exposes aggregate health data, including total counts, per-district and per-project breakdowns, most-accessed memories, orphan detection, and active loop telemetry counters.

Import Diagnostics

The storage_diagnostics tool provides the resolved snapshot path, WAL path, and the winning environment/config source for persistence resolution.

The import_memories tool now supports:

  • Inline entries for ordinary bulk seeding.
  • Snapshot file_path imports for large migrations.
  • dry_run preflight validation with deterministic would-import / would-skip / would-fail counts.
  • dedupe policies: none, content_hash, and content_plus_tags.
  • Snapshot-only migration flags: preserve_ids and merge_connections.

Safety rules are explicit: ID collisions fail with ID_CONFLICT; invalid connection targets fail with INVALID_CONNECTION_TARGET; non-dry-run imports reject the batch when failures are present.

Persistence

v0.2.0 uses a snapshot plus write-ahead log (WAL) model.

  • Mutating operations append to memories.json.wal.jsonl first.
  • The in-memory graph is updated after the journal write.
  • On startup, the server loads memories.json, replays WAL entries, compacts to a fresh snapshot, then truncates the WAL.

By default, persistence resolves under the user home directory, typically at ~/.neurodivergent-memory/memories.json, but explicit configuration is preferred for cross-client consistency.

Supported environment variables include:

  • NEURODIVERGENT_MEMORY_FILE
  • NEURODIVERGENT_MEMORY_DIR
  • NEURODIVERGENT_MEMORY_MAX
  • NEURODIVERGENT_MEMORY_EVICTION
  • NEURODIVERGENT_MEMORY_QUEUE_DEPTH
  • NEURODIVERGENT_MEMORY_WIP_LIMIT

Current known limit: write serialization is process-local. Shared storage across multiple live server processes is still effectively a single-writer-at-a-time scenario until later roadmap work lands.

Trust & Telemetry Foundation in v0.2.0, Extended in v0.3.0

  • Structured Pino logging on the write path.
  • Stable NM_E error taxonomy for operator-facing failures.
  • Async write mutex plus bounded queue backpressure.
  • Loop telemetry for repetition, similarity, and ping-pong patterns, extended in v0.3.0 with no-net-new-info warnings and distillation suggestions.
  • Published benchmark baseline for 1k, 5k, and 10k memory datasets.

Design Philosophy

The architecture is explicitly built for non-linear cognition. Rather than assuming a single flat thread of recall, it:

  1. Partitions context into districts with intentional boundaries.
  2. Applies structured metadata so any entry is independently navigable.
  3. Uses graph relationships to honor associative, non-sequential memory patterns.
  4. Ranks retrieval by relevance rather than insertion order.
  5. Carries emotional metadata so affective context is preserved alongside factual content.

This makes the system natural for neurodivergent users and well-suited for research workflows, controlled pilots, and emerging multi-agent coordination patterns.

See also: Getting-Started · Release-Notes · Roadmap · White-Paper

Home

Setup

Reference

Reports

v0.3.0 · Research Preview

npm · Docker Hub · GHCR

Clone this wiki locally