Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@neurodivergent-memory Store a memory about my new hobby with tags creative and emotional."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
# 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# 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-kitRelated MCP server: KG Memory
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 --> AFlow 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.
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
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
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
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>.
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
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.
Each memory can optionally carry:
emotional_valence (-1 to 1) — Emotional charge or affective tone
intensity (0–1) — Mental energy or importance weight
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.
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][A-Za-z0-9._:-]{0,63}$ (max length 64).
Invalid values return stable error code NM_E020 with recovery guidance.
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.
If validation failures are present, the non-dry-run import is rejected as a whole. Run dry_run: true first to inspect the failure list before retrying.
Memories are persisted with a write-ahead journal (WAL) plus snapshot model:
Every mutating operation appends to memories.json.wal.jsonl first.
The in-memory graph is then updated and periodically snapshotted to memories.json.
On startup, the server loads memories.json, replays WAL entries, compacts to a fresh snapshot, then truncates the WAL.
This improves crash recovery behavior compared to snapshot-only persistence.
For explicit control, set one of these environment variables:
NEURODIVERGENT_MEMORY_DIR to choose the directory that contains memories.json
NEURODIVERGENT_MEMORY_FILE to point at a specific snapshot file
NEURODIVERGENT_MEMORY_MAX to cap total memories (integer; default unlimited)
NEURODIVERGENT_MEMORY_EVICTION to choose eviction policy when max is reached:
lru (default)
access_frequency
district_priority
Mounts at /home/node/.neurodivergent-memory continue to work without any env override — that is the container's node user home and is checked automatically.
⚠️ Breaking change (v0.2.0): The image runs as the
nodeuser and cannot read/root, so previous mounts at/root/.neurodivergent-memoryare silently skipped. Agents may appear to have lost all memories. See Recovering memories after upgrade below.
If you previously mounted data at /root/.neurodivergent-memory, your snapshot is still intact on the host volume. Re-mount it using one of these options:
Option A — explicit /data mount (recommended):
"-e", "NEURODIVERGENT_MEMORY_DIR=/data",
"-v", "mydata:/data"Option B — mount at the path the node user already owns:
"-v", "mydata:/home/node/.neurodivergent-memory"No NEURODIVERGENT_MEMORY_DIR override is needed for option B — the server finds the existing snapshot automatically.
For agents: if memories appear missing after upgrading the container, use import_memories to reload from a backup export, or ask your AI assistant to re-run memory_stats after the volume is remounted correctly to confirm restoration.
The server supports a three-tier memory architecture for agents that work across multiple projects. Each tier lives in its own directory and can be synced independently.
Tier | Purpose | Typical path | Env var |
project | Repo-scoped memories — ephemeral, CI-friendly |
|
|
user | Cross-project personal knowledge — durable, per-developer |
|
|
org | Shared organisational knowledge — optional, team-wide | any shared mount |
|
The primary server still reads its active snapshot from NEURODIVERGENT_MEMORY_DIR (or the auto-discovered
default). Tier variables are used exclusively by the sync-memories helper.
Add a persistence:durable tag to any memory that should be promoted to the user or org tier. Memories
without this tag are treated as ephemeral and stay in the project tier.
["topic:typescript", "scope:global", "kind:pattern", "layer:architecture", "persistence:durable"]Use persistence:ephemeral as an explicit opt-out for memories you never want promoted.
After a build, milestone, or session — promote durable memories from the project tier to the user tier:
NEURODIVERGENT_MEMORY_PROJECT_DIR=.github/agent-kit/memories \
NEURODIVERGENT_MEMORY_USER_DIR=~/.neurodivergent-memory \
npm run sync-memories -- --from project --to userOr use explicit paths:
node build/scripts/sync-memories.js \
--from .github/agent-kit/memories \
--to ~/.neurodivergent-memoryFull option reference:
--from <path|tier> Source snapshot directory, or tier name: project | user | org
--to <path|tier> Target snapshot directory, or tier name: project | user | org
--tags <tag1,tag2,...> Promote only memories matching ALL listed tags (default: persistence:durable)
--any-tag Match memories that have ANY of the listed tags (OR logic)
--dry-run Report counts without writing any dataSafety note: stop the MCP server for the target tier before running sync — the script writes directly to the snapshot file and will warn if it detects an open WAL for the target directory.
GitHub Actions runs on Node.js 24 LTS for CI and release automation
npm publishes use OIDC provenance with npm publish --provenance --access public
Docker images are built with Buildx, published to Docker Hub, and emitted with SBOM and provenance metadata
GitHub Actions generates artifact attestations for the npm tarball and the pushed container image digest
Tagged releases upload the npm tarball, checksums, and attestation bundles as release assets
Pushes to the development branch publish release candidates using the same npm package name (neurodivergent-memory) and container repositories.
npm prereleases are published as 0.x.x-rc.N with npm dist-tag rc.
npm prerelease suffix N uses run_number.run_attempt to avoid collisions on workflow re-runs.
Docker images are published with immutable rc-0.x.x-rc.N tags only, where N is derived from run_number.run_attempt.
GitHub releases for RC builds are marked as pre-release.
These builds are intentionally less stable than the research preview line and should be used only for validation and early integration testing.
Use the deterministic live smoke harness to validate project_id attribution/scoped retrieval end-to-end:
Local build target:
npm run smoke:project-idLatest Docker RC target (PowerShell):
$rc = (Invoke-RestMethod -Uri "https://hub.docker.com/v2/repositories/twgbellok/neurodivergent-memory/tags?page_size=25").results |
Where-Object { $_.name -match '^rc-' } |
Sort-Object { $_.last_updated } -Descending |
Select-Object -First 1 -ExpandProperty name
node test/live-project-id-smoke.mjs "docker run --rm -i twgbellok/neurodivergent-memory:$rc"The smoke harness exits non-zero on failed assertions and is suitable as a release-readiness gate.
Mutating and lookup tool failures are returned with a stable operator-facing shape embedded in the text response:
❌ <summary>
Code: NM_EXXX
Message: Human-readable failure summary
Recovery: Suggested next actionThe leading summary line is contextual, while the Code/Message/Recovery block remains stable for operators to parse and search. This keeps MCP responses readable in chat clients while giving operators a stable code they can search in logs and release notes. Structured logs are written with Pino to stderr and include the same code field on known failure paths.
Mutating tools are serialized through an async mutex to prevent concurrent write races when multiple agents call the server at the same time.
Write queue behavior:
Pending write operations are bounded by NEURODIVERGENT_MEMORY_QUEUE_DEPTH (default: 50).
When the queue is full, mutating tools return NM_E010 with a retry-oriented recovery message.
Queue high-water/clear transitions are logged with structured Pino warnings.
WIP guardrail behavior:
store_memory checks practical in-progress task saturation per agent_id when task tags include in-progress markers.
The cap is controlled by NEURODIVERGENT_MEMORY_WIP_LIMIT (default: 1; set 0 to disable).
Exceeding the cap emits a warning line in the tool response and logs NM_E011 for operator visibility.
The server tracks loop signals and can surface targeted guardrail responses:
Repetition detection on store_memory compares incoming content against the 10 most recent memories (same agent_id when provided) using tokenizer-consistent token-overlap scoring with an exact-match fast path.
Stores that meet the repeat threshold set repeat_detected: true, increment repeat_write_count on the matched memory, and add a No net-new info warning to the tool response.
Repeated logical_analysis reads of emotional_processing memories add a distill_memory suggestion once the configured threshold is crossed.
Read/write ping-pong transitions are tracked in a rolling operation window, increment ping_pong_counter when threshold conditions are met, and can optionally start a temporary cross-district write cooldown.
memory_stats now includes a loop_telemetry block with:
repeat_write_candidates (top 5)
ping_pong_candidates (top 5)
recent_high_similarity_writes (last 5)
Configuration:
NEURODIVERGENT_MEMORY_REPEAT_THRESHOLD (default: 0.85)
NEURODIVERGENT_MEMORY_LOOP_WINDOW (default: 20)
NEURODIVERGENT_MEMORY_PING_PONG_THRESHOLD (default: 3)
NEURODIVERGENT_MEMORY_DISTILL_SUGGEST_THRESHOLD (default: 3)
NEURODIVERGENT_MEMORY_CROSS_DISTRICT_COOLDOWN_MS (default: 0, disabled)
Issue #19 adds a deterministic benchmark harness for end-to-end MCP stdio measurements against the built server.
Run it with:
npm run benchmarkThe benchmark:
Uses an isolated temp persistence directory so it does not mutate your local memory graph.
Seeds each dataset tier, then measures store_memory throughput across 100 writes at the target tier.
Measures search_memories and list_memories latency over 100 iterations at 1k, 5k, and 10k memories.
Measures traverse_from latency at depths 2, 3, and 5 on a connected graph of 500 memories.
Prints the structured JSON report to stdout for automation-friendly capture.
Writes run-specific outputs to timestamped files under benchmark-results/.
Also writes rolling latest aliases:
benchmark-results/memory-benchmark-latest.json
benchmark-results/memory-benchmark-latest.md
There is also a convenience alias:
npm run benchThe committed baseline is intended as a relative regression reference for RC vs stable comparisons, not as a universal absolute performance guarantee across machines.
To intentionally refresh the committed baseline files in place:
npm run benchmark -- --update-baselineInstall dependencies:
npm installBuild the server:
npm run buildFor development with auto-rebuild:
npm run watchTo use with Claude Desktop, add the server config:
On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json
For npm:
{
"mcpServers": {
"neurodivergent-memory": {
"command": "npx",
"args": ["neurodivergent-memory"]
}
}
}For Docker:
{
"mcpServers": {
"neurodivergent-memory": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"NEURODIVERGENT_MEMORY_DIR=/data",
"-v",
"neurodivergent-memory-data:/data",
"docker.io/twgbellok/neurodivergent-memory:0.3.0"
]
}
}
}Fully auto-approved tools:
{
"mcpServers": {
"neurodivergent-memory": {
"autoApprove": [
"store_memory",
"retrieve_memory",
"connect_memories",
"search_memories",
"update_memory",
"delete_memory",
"traverse_from",
"related_to",
"list_memories",
"memory_stats",
"storage_diagnostics",
"import_memories",
"distill_memory",
"prepare_memory_city_context",
"prepare_synthesis_context",
"prepare_packetized_synthesis_context",
"register_district"
],
"disabled": false,
"timeout": 120,
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"NEURODIVERGENT_MEMORY_DIR=/data",
"-v",
"neurodivergent-memory-data:/data",
"docker.io/twgbellok/neurodivergent-memory:0.3.0"
],
"env": {}
}
}
}If you want to use the mcp server in Github Copilot Agent Workflows (github spins up a new VM every time, so cross-workflow memory is non-existent. Session memory is working, but is wiped upon job completion.):
{
"mcpServers": {
"neurodivergent-memory": {
"type": "stdio",
"command": "npx",
"args": [
"neurodivergent-memory@0.3.0"
],
"env": {
"NEURODIVERGENT_MEMORY_DIR": ".neurodivergent-memory"
},
"tools": [
"retrieve_memory",
"connect_memories",
"update_memory",
"delete_memory",
"traverse_from",
"related_to",
"import_memories",
"storage_diagnostics",
"distill_memory",
"prepare_memory_city_context",
"prepare_synthesis_context",
"prepare_packetized_synthesis_context",
"register_district",
"list_memories",
"store_memory",
"search_memories",
"memory_stats"
]
}
}
}If you want per-project isolation instead of a shared global memory file, mount a project-specific host directory and keep the same container-side target. Use the path separator for your OS:
Windows: ${workspaceFolder}\.neurodivergent-memory:/data
macOS / Linux: ${workspaceFolder}/.neurodivergent-memory:/data
{
"mcpServers": {
"neurodivergent-memory": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"NEURODIVERGENT_MEMORY_DIR=/data",
"-v",
"${workspaceFolder}/.neurodivergent-memory:/data",
"docker.io/twgbellok/neurodivergent-memory:0.3.0"
]
}
}
}Note: Replace
/with\on Windows:${workspaceFolder}\.neurodivergent-memory:/data
Use an explicit version tag. The published Docker images intentionally do not maintain a floating latest tag.
You can also run the packaged server image directly:
docker run --rm -i twgbellok/neurodivergent-memory:0.3.0Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:
npm run inspectorThe Inspector will provide a URL to access debugging tools in your browser.
This repository ships a reusable agent customization kit whose authoring source lives at .github/agent-kit/.
Use the packaged installer to materialize those templates into a consumer repository's .github/... folders instead of tracking a live generated agent file in this repo.
File | Purpose |
| Full-featured Memory-Driven Development Coordinator agent. Five-phase workflow: pull context → research → improve memories → plan → act & hand off. |
| Minimal generic agent template — a lighter starting point if you want to build your own workflow on top. |
| Shared instruction file that reinforces memory-driven habits in day-to-day coding sessions without requiring explicit agent invocation. |
| Guided setup prompt that asks the user to choose an install policy before anything is installed. |
| Bootstrap reference for GitHub Copilot sessions — tag schema, district table, tool quick-reference, and session checklist in one file. |
| Prompt for guided exploration of memory districts and graph structure. |
| Prompt for executing a tracked issue with full memory-driven context (pull → plan → act → update). |
Install the current packaged kit into the repo you are standing in:
npx neurodivergent-memory@latest init-agent-kitUseful options:
--target <path> installs into a different repository root.
--dry-run shows what would be copied without writing files.
--force overwrites existing destination files.
--mode prompt-first|auto-setup records the intended install policy in command output while leaving template wording unchanged.
The installer copies templates into standard customization locations such as .github/agents/, .github/instructions/, .github/prompts/, and .github/copilot-instructions.md.
The source of truth remains under .github/agent-kit/templates/. The installed live agent file .github/agents/neurodivergent-agent.agent.md is intentionally treated as generated consumer state rather than a tracked repo artifact, so remote Copilot updates cannot keep wiping it out in this repository.
Copy the files you need into your project's standard customization locations — do not move them, so the originals remain available as a reference for future agents or contributors.
The right target directories vary by agent platform. Use whatever location your agent natively reads from. Common examples:
.github/agents/ for agent definitions
.github/instructions/ for shared instructions
.github/prompts/ for prompts
.github/ root for copilot-instructions.md
Before installing neurodivergent-memory MCP in any project, ask the user which policy to apply:
prompt-first (default) — Ask for explicit approval before installing.
auto-setup — Install automatically without prompting.
Update the imported agent file's installation section to reflect the chosen policy. If no preference is stated, default to prompt-first.
Here is an example copilot-instructions.md
# neurodivergent-memory — Agent Bootstrap Instructions
This file is automatically read by GitHub Copilot and compatible agents at the start of every session.
It replaces the need to fetch the governance memory (`memory_11`) before working with this MCP server.
---
## What this server is
`neurodivergent-memory` is a **Model Context Protocol (MCP) server** that stores and retrieves memories as a
knowledge graph. It is designed for neurodivergent thinking patterns: non-linear, associative, tag-rich.
Memories are organised into five **districts** (knowledge domains) and connected via bidirectional edges.
Search uses **BM25 semantic ranking** — no embedding model or cloud LLM required.
---
## Canonical Tag Schema
Always apply tags from the five namespaces below when calling `store_memory`.
Multiple tags from different namespaces are expected on every memory.
When storing execution-heavy memories, include the reasoning behind the action and, when possible, connect the entry to a durable principle in `logical_analysis` or `creative_synthesis` so retrieval preserves understanding and not just activity.
| Namespace | Purpose | Examples |
|---|---|---|
| `topic:X` | Subject matter / domain | `topic:unity-ecs`, `topic:adhd-strategies`, `topic:rust-async` |
| `scope:X` | Breadth of the memory | `scope:concept`, `scope:project`, `scope:session`, `scope:global` |
| `kind:X` | Type of knowledge | `kind:insight`, `kind:decision`, `kind:pattern`, `kind:reference`, `kind:task` |
| `layer:X` | Abstraction level | `layer:architecture`, `layer:implementation`, `layer:debugging`, `layer:research` |
| `persistence:X` | Sync-tier eligibility | `persistence:durable`, `persistence:ephemeral` |
**Example tag set for a Unity ECS memory:**
```json
["topic:unity-ecs", "topic:dots", "scope:project", "kind:pattern", "layer:architecture"]Example tag set for a durable cross-project memory:
["topic:typescript", "scope:global", "kind:pattern", "layer:architecture", "persistence:durable"]Key | Purpose |
| Structured thinking, analysis, research findings |
| Feelings, emotional states, affective responses |
| Tasks, plans, implementations, action items |
| Risks, warnings, constraints, safety concerns |
| Novel connections, creative ideas, cross-domain insights |
Tool | Purpose |
| Create a new memory node |
| Fetch one memory by ID |
| Modify content, tags, district, valence, or intensity |
| Remove a memory and all its connections |
| Add an edge between two memory nodes |
| BM25-ranked search with optional |
| BFS graph walk from a node up to N hops |
| Hop-proximity + BM25 blend for a given memory ID, with optional goal-context boost |
| Paginated enumeration of all stored memories |
| Totals, per-district/per-project counts, most-accessed, and orphans |
| Resolved snapshot path, WAL path, and effective persistence source |
| Bulk import from inline entries or a snapshot file with dry-run and migration controls |
| Translate an |
| Tool mirror of |
| Tool mirror of |
| Tool mirror of |
| Register a custom district with LUCA ancestry validation |
Memories are automatically saved to ~/.neurodivergent-memory/memories.json on every write.
The graph is restored on server startup — no data is lost between restarts.
Do not stop at "what happened". Important memories should capture why the action was taken, what tradeoff or principle drove it, and whether the insight is reusable.
Treat practical_execution as the action log, then pair it with logical_analysis or creative_synthesis when the deeper rationale should survive longer than the implementation details.
When a debug trail, handoff, or emotional/raw memory is noisy, use distill_memory or an explicit follow-up memory to preserve the signal while stripping incidental detail.
Prefer connective synthesis over isolated task logs: link implementation memories back to durable principles such as explicit state over implicit state, bounded growth, or environment-aware validation.
Call memory_stats to see how many memories exist.
Use search_memories with a broad query to locate relevant prior context.
Check whether recent memories already explain the rationale or durable principle behind the task, not just the last execution step.
Apply the canonical tag schema when calling store_memory.
Connect new memories to related existing ones with connect_memories.
Use traverse_from or related_to for associative retrieval rather than repeated searches.
No Quick Task exemption: any file edit, decision, or finding in this repo is memory-worthy — write the memory before moving on. If you catch yourself thinking "this is too small" — that is the trigger, not a bypass.
No execution-only memory exemption: if a memory says what changed, it should also say why it changed or link to a memory that does.
Create connections between memories (like neural pathways)
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id_1 | Yes | First memory ID | |
| memory_id_2 | Yes | Second memory ID | |
| bidirectional | No | Whether connection goes both ways | |
| agent_id | No | Optional agent identifier performing the connection |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description lacks details on effects, idempotency, authentication requirements, or error states. Only a vague metaphor is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with a metaphor is very concise and front-loaded. However, it may be too brief, lacking important details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no description of return values or side effects. For a tool with 4 parameters, more context on what happens after creation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already explained in the schema. Description adds no additional parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool creates connections between memories, using a helpful metaphor ('like neural pathways'). It distinguishes from sibling tools like 'related_to' which likely retrieves existing connections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'related_to' or 'store_memory'. Does not specify prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a memory and remove all its connections
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes | ID of the memory to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that deletion is permanent and removes all connections, which is key behavior. However, with no annotations, more detail (e.g., cascading effects, required permissions) would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, clear sentence with no unnecessary words. Every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with one parameter and no output schema, the description covers the essential behavior. However, it could mention if there are any side effects on linked memories beyond connections.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description does not add extra meaning beyond the schema's 'ID of the memory to delete'. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (permanently delete) and the resource (memory), and adds that connections are removed, distinguishing it from sibling tools like update_memory or retrieve_memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like update_memory or store_memory. The description does not include when-not-to-use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Translate an emotional_processing memory into a structured logical artifact (signals, triggers, constraints, next_actions, risk_flags). Creates a distilled memory in logical_analysis district with reduced intensity and neutral valence for efficient consumption by planning agents. Only operates on emotional_processing memories.
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes | ID of the emotional_processing memory to distill | |
| agent_id | No | Optional agent identifier for the distilled memory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions creating a distilled memory with reduced intensity and neutral valence, but does not disclose whether the original memory is altered or destroyed, a critical behavioral gap for a transformation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words. First sentence states action and output, second adds behavioral detail, third adds constraint. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the input constraint and lists output components (signals, triggers, etc.), providing good context for planning agents. However, it does not indicate the return value (e.g., new memory ID) since there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are adequately described in the schema. The description adds no new parameter-level detail, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Translate' and resource 'emotional_processing memory' and specifies the structured artifact output. It distinguishes from sibling tools like store_memory and delete_memory by focusing on transformation, not CRUD.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the prerequisite that the tool only operates on emotional_processing memories, which gives clear context. However, it does not mention when not to use it or suggest alternatives, leaving some ambiguity compared to other memory tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk-import memories from inline entries or from a snapshot file. Supports dry-run validation, dedupe policies, and explicit snapshot migration flags.
| Name | Required | Description | Default |
|---|---|---|---|
| entries | No | Array of memory entries to import. Required if file_path is not provided. | |
| file_path | No | Absolute path to a server snapshot JSON file (typically a memories.json snapshot generated by this server). Required if entries is not provided. | |
| dry_run | No | Validate the import and return would_import / would_skip / would_fail counts without writing any data | |
| dedupe | No | Optional dedupe policy: none, content_hash, or content_plus_tags | |
| preserve_ids | No | Snapshot-import only. Preserve source memory IDs; conflicting IDs are rejected deterministically | |
| merge_connections | No | Snapshot-import only. Merge the imported connection graph after validating all referenced IDs | |
| agent_id | No | Optional default agent identifier applied to entries without agent_id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions dry-run, dedupe policies, and snapshot flags, but does not disclose side effects (e.g., whether duplicates are skipped or updated) or the overall behavioral impact beyond 'import'. The behavior for conflict resolution is implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two sentences, with the first stating the core action and sources, and the second listing key features. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's complexity (7 parameters, two input modes, no output schema), the description omits return values, success/failure behavior, and details on how import conflicts are handled. For a batch import tool with potential side effects, this leaves significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all 7 parameters. The tool description adds little beyond the schema: 'Bulk-import' is generic, and the features listed (dry-run, dedupe, snapshot flags) are already reflected in the schema's parameter descriptions. No additional context is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: bulk-importing memories from inline entries or snapshot files. It distinguishes from sibling tools like store_memory (single) by specifying 'bulk-import' and listing supported features.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool does but does not provide explicit guidance on when to use it versus alternatives like store_memory or search_memories. There is no mention of prerequisites, constraints, or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List stored memories with optional pagination and filters
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default 1) | |
| page_size | No | Results per page (default 20) | |
| district | No | Optional district filter | |
| archetype | No | Optional archetype filter | |
| project_id | No | Optional project_id filter | |
| epistemic_statuses | No | Optional epistemic status filters |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears the burden of behavioral disclosure. It states 'list' implying read-only, but does not confirm safety, idempotency, or clarify if data is modified. Basic transparency is present but could be more explicit (e.g., read-only hint).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence of 6 words, fitting the minimal viable. It front-loads the action and key features. While efficient, it lacks some structure (e.g., separate sections) but earns points for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 optional parameters and 17 sibling tools, the description is adequate but not thorough. It omits details like default sorting, total count behavior, and does not hint at output format (no output schema). More completeness would benefit agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions, so baseline is 3. The description mentions 'pagination and filters' but adds no new semantic detail beyond the schema. Parameters like 'district' and 'archetype' are already well-described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List stored memories with optional pagination and filters', specifying the action (list), resource (memories), and key features. It distinguishes itself from sibling tools like 'search_memories' and 'retrieve_memory' by focusing on listing with filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'search_memories' or 'memory_stats'. The description implies it's for paginated filtered lists but does not mention exclusions or preferred scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return aggregate statistics: total count, per-district counts, connection count, most-accessed nodes, and orphan nodes
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Optional project_id scope for filtered stats |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the return content but does not mention behavioral traits like idempotency, authorization needs, or performance impact. The read-only nature is implied but not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently lists all returned statistics without unnecessary words. Information is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists the components of the aggregate statistics but does not specify the output format (e.g., map for per-district counts, list for most-accessed nodes). With no output schema, more detail would be beneficial for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a well-described parameter. The description adds no extra meaning beyond the schema's 'Optional project_id scope for filtered stats'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool returns aggregate statistics and lists all components (total count, per-district counts, connection count, most-accessed nodes, orphan nodes). It clearly distinguishes from siblings like list_memories and search_memories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. It implies statistical overview context but lacks explicit 'when not' or alternative tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the same exploration context exposed by the explore_memory_city prompt, packaged as a tool result for clients that support tools but not MCP prompts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It does not mention any side effects, safety traits, or required permissions. The tool likely is read-only but this is not stated, leaving the agent guessing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with zero waste. It is front-loaded with the core purpose and use case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description is mostly complete. It explains the return value context and use case. However, it could mention the format or content of the context to be more helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters with 100% coverage. The description adds no parameter information, but none is needed. A baseline of 4 is appropriate since the schema already fully documents the inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns exploration context from a specific prompt, packaged as a tool result. The verb 'return' and resource 'exploration context' are specific. However, it does not differentiate from similar sibling tools like 'prepare_packetized_synthesis_context' or 'prepare_synthesis_context'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the use case: for clients that support tools but not MCP prompts. This provides clear context for when to use. However, it does not mention when not to use or suggest alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the same context exposed by the synthesize_memory_packets prompt, packaged as a tool result for prompt-limited or attachment-constrained clients.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states the tool returns context but does not describe side effects, required permissions, rate limits, or any other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the tool's purpose without any superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, and no annotations, the description could be more complete by mentioning the result format or linking to the referenced prompt. The current description leaves some ambiguity about the content and structure of the returned context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description does not need to add parameter information. Baseline score of 4 is appropriate as the tool has no parameters to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: returning the context from a specific prompt, packaged for constrained clients. It is specific about the verb and resource, and references the underlying prompt, but does not explicitly distinguish it from similar siblings like 'prepare_synthesis_context'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use (for prompt-limited or attachment-constrained clients) but does not specify when not to use or mention alternatives. The usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the same context exposed by the synthesize_memories prompt, packaged as a tool result for prompt-limited clients.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates that the tool is read-only and returns existing context, but does not disclose details about the context structure, potential side effects, or authentication requirements. With no annotations, the description carries the burden and is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no unnecessary words. It is front-loaded and efficiently communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple (no parameters), the lack of an output schema means the description should explain what the returned context contains. It only says 'same context exposed by the synthesize_memories prompt,' which is vague and relies on the agent's prior knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so schema coverage is 100%. The description does not need to add parameter information. Per the guidelines, 0 parameters gives a baseline of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns the context from the synthesize_memories prompt, packaged as a tool result. This is specific and distinguishes it from siblings by name, but does not explicitly differentiate from similar context-retrieval tools like prepare_memory_city_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that this tool is for 'prompt-limited clients,' which gives some context for use, but provides no guidance on when to use this tool over its siblings such as prepare_memory_city_context or prepare_packetized_synthesis_context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register a custom district with LUCA ancestry validation. Custom districts must declare a valid parent that traces back to one of the 5 canonical districts (logical_analysis, emotional_processing, practical_execution, vigilant_monitoring, creative_synthesis). The custom district inherits its archetype from the canonical ancestor.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Snake_case district identifier (e.g. project_build_pipeline) | |
| name | Yes | Human-readable district name | |
| description | Yes | District description explaining its purpose | |
| luca_parent | Yes | Parent district key. Must be an existing district that traces back to a canonical district. | |
| activities | No | Optional list of activities for this district. Inherits parent activities if omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description explains ancestry validation and archetype inheritance, but does not disclose return values, potential side effects, or restrictions beyond what is stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the main purpose and key constraint, with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (5 parameters, 4 required), the description adequately covers validation and inheritance, though it could mention the return value for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds value beyond the schema, especially for 'luca_parent' by detailing the ancestry requirement and inheritance behavior, complementing the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool registers a custom district with LUCA ancestry validation, distinguishing it from sibling memory tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It specifies the prerequisite that the parent must trace back to a canonical district, providing clear context for use, though it does not explicitly mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific memory by ID
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes | ID of the memory to retrieve | |
| district | No | Optional caller district for loop telemetry attribution | |
| agent_id | No | Optional caller agent identifier for loop telemetry attribution |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, yet description only states retrieve by ID. Missing critical details: what happens if memory not found (error vs null?), return format, permissions, or side effects. For a simple read, more transparency expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise single sentence, front-loaded with key action and resource. Could benefit from brief addition without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and 17 sibling tools, description lacks details on return value, error handling, and relationship to other memory operations. Incomplete for reliable autonomous use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter. Description adds no new meaning beyond paraphrasing the schema, meriting baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states verb 'retrieve' with resource 'memory' and identifier 'by ID'. Clearly distinguishes from siblings like store_memory (create) or search_memories (query).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., search_memories), no prerequisites mentioned (e.g., memory must exist), and no exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search memories using BM25 semantic ranking with optional goal-context blending, recency bias, and filters. Returns results sorted by relevance score (0-1).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query | |
| district | No | Optional district filter | |
| project_id | No | Optional project_id filter | |
| tags | No | Optional tag filters (OR logic) | |
| epistemic_statuses | No | Optional epistemic status filters | |
| min_score | No | Minimum relevance score (0-1). Only return results at or above this threshold. | |
| context | No | Optional short goal/context string blended into ranking as a lightweight BM25 boost. | |
| recency_weight | No | Optional recency boost strength from 0 (off) to 1 (strongest). Recent memories receive more weight without replacing semantic relevance. | |
| emotional_valence_min | No | Minimum emotional valence filter (-1 to 1) | |
| emotional_valence_max | No | Maximum emotional valence filter (-1 to 1) | |
| intensity_min | No | Minimum intensity filter (0-1). Deprecated alias for min_intensity. | |
| intensity_max | No | Maximum intensity filter (0-1). Deprecated alias for max_intensity. | |
| min_intensity | No | Minimum intensity filter (0-1). Preferred name for new callers. | |
| max_intensity | No | Maximum intensity filter (0-1). Preferred name for new callers. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It explains the ranking algorithm, optional blending, and output sorting, which adds value beyond the schema. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loads key action, includes optional features and output format. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 14 parameters and no output schema, the description covers the core purpose and output. It could mention result limits or filter interactions, but the schema fills in details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description summarizes key features but does not add new meaning per parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool does semantic search using BM25 with optional features and returns sorted results. It distinguishes from siblings by specifying the search method and output format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly compare to sibling tools like retrieve_memory or list_memories, but the purpose is implied. No guidance on when to use or not use is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return runtime server identity and version details so clients can confirm the active build.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool returns information, implying no side effects, but does not elaborate on behavior (e.g., that it is safe and idempotent). Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no waste. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description sufficiently states its purpose and return content. Could optionally mention specific fields, but not necessary for this simple identity check.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%. The description does not need to add parameter information, so it is fine. Baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'runtime server identity and version details', which is a specific verb+resource. This distinguishes it from sibling tools that focus on memory operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for clients to 'confirm the active build', which provides context. However, it does not explicitly state when not to use it or mention alternatives, so guidance is limited.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the resolved snapshot path, WAL path, and the effective environment/config source used for persistence.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. The word 'Show' implies a read-only operation, but there is no explicit mention of whether the tool has side effects, requires permissions, or is safe to call multiple times.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 18 words, front-loading the action ('Show') and listing the outputs. No unnecessary information, perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description provides the essential information. It could be slightly more specific about what 'resolved' means, but overall it is complete enough for a diagnostic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so schema coverage is 100%. The description adds no parameter info (none needed). With 0 parameters, baseline is 4, and the description meets expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: showing resolved snapshot path, WAL path, and config source. It uses a specific verb 'Show' and identifies distinct resources, distinguishing it from sibling tools which are all about memories or handshake.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative guidance is provided. However, since the tool is a simple diagnostic with no parameters and no similar sibling tools, the absence of guidelines is less critical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a new memory in a specific district of the neurodivergent mind
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The memory content/thought to store | |
| district | Yes | Memory district to store in | |
| tags | No | Optional tags for categorization | |
| emotional_valence | No | Emotional charge (-1 to 1) | |
| intensity | No | Mental energy/importance (0-1) | |
| agent_id | No | Optional creator agent identifier | |
| project_id | No | Optional project identifier for attribution and scoped retrieval | |
| epistemic_status | No | Optional epistemic status for planning memories |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states 'store a new memory' but does not mention side effects (e.g., overwriting), permissions, or any nuances beyond the basic operation. The agent cannot infer safety or implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb, and contains no extraneous information. It is efficiently concise, though a little more structure could help for an 8-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, no output schema, no annotations), the description is incomplete. It does not mention return values, error conditions, or typical usage patterns for optional parameters like tags or emotional_valence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters already have descriptions. The tool description adds no additional meaning or context beyond what the schema provides. A baseline of 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Store'), the resource ('a new memory'), and the location ('in a specific district of the neurodivergent mind'). It distinguishes the tool from siblings such as delete_memory or connect_memories by focusing on creation in a specific district.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like import_memories or search_memories. It lacks any 'when to use', 'when not to use', or suggestions for related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Walk the memory graph from a starting node up to N hops deep, returning all reachable memories
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes | Starting memory ID | |
| depth | No | Maximum hops to traverse (default 2) | |
| district | No | Optional district filter for results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The disclosure includes key behavior (hops limit, graph traversal) but lacks details on cycle handling, performance, or precise definition of reachable. With no annotations, some gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, no wasted words, immediately communicates the tool's function. Model of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description lacks output specification (format, contents, pagination) and doesn't mention default depth behavior. Without an output schema, this is a significant gap for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds no new parameter semantics. It focuses on tool purpose, which is acceptable given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool walks the memory graph from a starting node up to N hops, returning reachable memories. It uses specific verb and resource, distinguishing it from related tools like related_to or search_memories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives such as related_to or list_memories. The agent must infer usage from the name and description, which is insufficient for optimal tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing memory's content, tags, district, emotional_valence, intensity, or epistemic_status
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes | ID of the memory to update | |
| content | No | New content (optional) | |
| district | No | New district (optional) | |
| tags | No | New tags (optional, replaces existing) | |
| emotional_valence | No | New emotional charge (optional) | |
| intensity | No | New intensity (optional) | |
| actor_district | No | Optional caller district for loop telemetry attribution | |
| agent_id | No | Optional caller agent identifier for loop telemetry attribution | |
| project_id | No | New project identifier (optional); pass null to clear existing project attribution | |
| epistemic_status | No | New epistemic status (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It states that it updates an existing memory but does not describe side effects, such as whether unspecified fields remain unchanged, whether updates are destructive, or any authorization requirements. The schema notes that tags replace existing, but this is not in the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently states the action and lists the fields. It is front-loaded with the purpose. While concise, it could benefit from separating optional fields and required ID for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 10 parameters, no output schema, and many sibling tools, the description is too brief. It lacks information about return values, error behavior, and when to use this tool over others. Completeness is insufficient for an agent to safely invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all parameters. The description lists the fields but adds no additional meaning beyond the schema. Baseline 3 is appropriate as the description confirms the schema but does not enhance it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates an existing memory and lists the specific fields that can be updated (content, tags, district, emotional_valence, intensity, epistemic_status). This distinguishes it from siblings like delete_memory, store_memory, and retrieve_memory, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as distill_memory or connect_memories. There is no mention of prerequisites, restrictions, or scenarios where this tool is not appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tools have largely distinct purposes (CRUD, connections, search, stats, etc.), but some overlap exists between related_to and search_memories in terms of finding related memories; however, descriptions clarify the difference (ID-based vs. query-based). No major ambiguity.
All tools use a consistent verb_noun pattern in snake_case (e.g., store_memory, list_memories, delete_memory, register_district). Deviations like prepare_memory_city_context still follow the pattern. No mixed conventions.
18 tools is on the higher side, but each serves a specific purpose in a complex memory system (CRUD, search, graph traversal, statistics, import, context preparation). The count is justified and does not feel excessive.
The tool set covers the full lifecycle of memories: create, read (by ID, list, search, related), update, delete. Additionally supports connections, distillation, import, statistics, district registration, and context preparation. No obvious gaps for the stated domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Personal knowledge graph as an AI memory layer over MCP - read, save, and link your memories.
Persistent, portable memory for AI assistants — your private memory graph, from any MCP client.
Cloud-hosted MCP server for durable AI memory
An MCP memory server. One memory your agents share — across models, devices and apps.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jmeyer1980/neurodivergent-memory'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
