This server provides a local, zero-LLM-token associative memory system for AI coding agents, modeled after the Drosophila mushroom body, to instantly recognize code patterns, learn from past outcomes, and alert agents to risky or buggy code.
Instant code reflex check: Call check_code_reflex with a code snippet to get an immediate (<1ms) verdict of avoid, safe, or neutral, along with valence, confidence, and similarity to past bug patterns.
One-shot learning from outcomes: Call remember_code_outcome with code and either success or failure to reward or punish the underlying neural weights, optionally attaching tags and error messages.
Associative memory search: Call query_associative_memory with a code snippet to retrieve the nearest stored patterns ranked by Fly-LSH sparse Hamming similarity, with configurable top_k and compact output.
Inspect memory state: Call inspect_memory_state to view total memories stored, Kenyon cell dimensions, sparsity, synaptic weight statistics, and storage location.
Reset memory: Call reset_memory with confirmation to wipe learned weights and memories back to baseline, optionally creating a backup first.
Integrate with MCP clients: The server exposes these tools over Model Context Protocol (MCP), with configured tool annotations (readOnlyHint, destructiveHint, etc.) for proper agent behavior.
Run entirely locally: All operations execute in-process with no LLM API calls, keeping token usage at zero and latency in the sub-millisecond range.
Click on "Deploy 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., "@Calyx MCP evaluate this code snippet for bugs and remember the outcome"
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.
Bio-inspired associative memory and instant code reflex server for AI coding agents, implementing the Drosophila Mushroom Body circuit and Fly-LSH sparse projection algorithm over the Model Context Protocol (MCP).
The Problem: AI coding agents repeatedly consume thousands of LLM prompt tokens and multi-second roundtrip latency diagnosing recurring bugs, antipatterns, and project constraints.
The Solution: Calyx brings the Drosophila Mushroom Body (fruit fly brain) circuit to AI agents—using Fly-LSH sparse Kenyon Cell projection ($D=2048, k=102$) and dopaminergic synaptic plasticity to give agents instant, zero-overhead associative memory without internal LLM calls.
The Proof (Benchmark):
Latency: 0.400 ms (vs ~1,450 ms LLM API roundtrip — >3,600x faster)
Token Cost: 0 tokens (100% local Mushroom Body execution; zero LLM inference calls)
Related MCP server: BrainBox
In insect neuroanatomy, the Calyx (plural: calyces) is the primary input neuropil of the Mushroom Body (Corpora Pedunculata)—the learning and memory center of the Drosophila melanogaster brain. Within the calyx, olfactory and sensory Projection Neurons (PNs) synapse directly onto the clawed dendritic arborizations of thousands of Kenyon Cells (KCs).
It is inside the calyx that dense, low-dimensional sensory signals undergo high-dimensional sparse expansion, turning raw input into a distinct neural fingerprint that dopaminergic circuits can reinforce or suppress.
The name Calyx was chosen because this MCP server functions as that exact input and associative expansion layer for AI coding agents: converting raw code AST tokens into high-dimensional, ultra-sparse Kenyon Cell representations that drive instantaneous (<0.5 ms) reflexes, pattern recognition, and persistent synaptic memory without LLM inference costs.
Traditional AI coding workflows incur substantial token overhead and multi-second latency by repeatedly sending multi-thousand-token prompt context to Large Language Models (LLMs) to detect recurring bugs, antipatterns, or architectural guidelines.
Calyx provides local, zero-token associative memory modeled after the Drosophila melanogaster (fruit fly) Mushroom Body circuit. Code snippets and AST structures are expanded into high-dimensional, ultra-sparse Kenyon Cell representations ($D=2048, k=102$). Synaptic plasticity between Kenyon Cells and Mushroom Body Output Neurons (MBONs) is modulated by reward and punishment signals (dopamine), delivering sub-millisecond pattern recognition without LLM inference costs.
+-----------------------------------------------------------------------+
| Calyx MCP |
+-----------------------------------------------------------------------+
| Input Code Snippet / AST Tokens |
| | |
| v |
| Fly-LSH Hash Projection (Projection Dimension = 2048) |
| | |
| v |
| Winner-Take-All Sparsification (k = 102 active Kenyon Cells, ~5%) |
| | |
| v |
| Mushroom Body Output Neuron (MBON) Synaptic Weight Matrix |
| | |
| +----+------------------------------------------------------------+ |
| | Dopaminergic Modulation: dW = eta * Dopamine * (KC (x) MBON) | |
| +-----------------------------------------------------------------+ |
| | |
| v |
| Reflex Output: Neutral / Attraction / Aversion (< 0.5 ms, 0 Tokens) |
+-----------------------------------------------------------------------+Fly-LSH Projection: Projects token distributions into a 2,048-dimensional space using deterministic hashing, mimicking the projection neuron to Kenyon cell expansion.
Winner-Take-All (WTA) Sparsity: Retains only the top $k=102$ activations (~4.98% sparsity) via inhibitory feedback (APL neuron equivalent).
Dopamine Synaptic Plasticity: Adjusts synaptic weights based on coding execution outcomes (success/failure), enabling rapid aversion to bug patterns and attraction to proven implementations.
Local Atomic Persistence: Synaptic states and associative memory records persist locally in compressed .npz and JSON formats (~/.calyx/).
An actual v1.0.5 agent-usage pilot records six fresh Luna sessions against 100 synthetic lessons. Only one pair met the retrieval protocol in both arms; it used 43,591 more tokens with Calyx. Failed attempts are retained. This bounded pilot does not demonstrate end-to-end token savings; zero internal LLM calls and agent usage are different measurements.
The performance metrics below were measured on a Windows x86_64 host running Python 3.13 with native NumPy operations. Because Fly-LSH sparse projection and synaptic valence calculations execute locally in memory, pattern recognition requires zero external LLM inference calls:
============================================================================
CALYX MCP: LIVE TOOL EXECUTION & TOKEN SAVINGS BENCHMARK
============================================================================
[Step 1] Initial Code Reflex Check (Zero Prior Training):
* Latency: 0.729 ms
* Reflex Status: NEUTRAL
* Valence: 1.000
* Recommendation: Novel or unverified code pattern. Proceed normally.
* LLM Tokens Used: 0 tokens (Zero API overhead)
[Step 2] Dopamine Reinforcement (Negative Dopamine Delivery):
* Plasticity Latency: 4.040 ms
* Status: recorded
* Valence Type: punishment (Dopaminergic depression signal)
* Active Synapses: 102 Kenyon Cells updated
* Persistent State: Saved to ~/.calyx/mushroom_body_weights.npz
[Step 3] Fast Bio-Reflex on Novel Code Variant:
* Latency: 0.400 ms
* Reflex Status: AVOID (AVERSION TRIGGERED)
* Valence Score: 0.775 (Aversive)
* Bug Similarity: 100.0%
* Warning: High resemblance (100%) to a previously punished bug pattern.
* Recommendation: Review code logic, check edge cases, or adopt alternative.
============================================================================
TOKEN SAVINGS & SPEEDUP
============================================================================
Traditional LLM Querying Loop:
* Latency per review: ~1450 ms
* Inspection Cost: ~650 prompt tokens per check
* Debugging Loop: ~2400 tokens per repeated bug
Calyx Mushroom Body Reflex:
* Latency per review: 0.400 ms (~3,628x speedup)
* Token Cost: 0 tokens (Local Fly-LSH sparse projection)
* Token Efficiency: 100% local execution (Zero LLM inference overhead)
============================================================================
MUSHROOM BODY NEURAL ARCHITECTURE STATE
============================================================================
* Kenyon Cells Dimension: 2048
* Sparsity Active Ratio: 4.98% active neurons
* Total Memories Stored: 1
* Depressed Synapses (W): 102
* Weights Min / Avg / Max: 0.775 / 0.9888 / 1.0
* Storage Directory: ~/.calyx
============================================================================Metric | Traditional LLM Inspection | Calyx Mushroom Body | Improvement |
Latency | ~1,450 ms | 0.400 ms | 3,628x faster |
Token Consumption | 650 - 2,400 tokens per loop | 0 tokens (Local Fly-LSH) | 100% local execution (Zero LLM calls) |
Memory Footprint | External API | < 15 MB RAM | Local execution |
Pattern Match Type | Full prompt parsing | Sparse Kenyon Cell overlap | Deterministic associative recall |
Calyx was benchmarked against real-world vulnerability and resource management patterns to test generalization across altered variable names, structural shifts, and function signatures:
Scenario | Anti-Pattern Trained | Novel Variant Evaluated | Reflex Outcome | Latency | Tokens |
SQL Injection (CWE-89) |
| Concatenation in | AVOID (Valence: 0.775) | 0.630 ms | 0 tokens |
Resource Descriptor Leak |
|
| AVOID (Valence: 0.550) | 0.662 ms | 0 tokens |
CPU Spinlock Lockup |
| Unbounded message loop polling | AVOID (Valence: 0.775) | 0.400 ms | 0 tokens |
Calyx registers the following tools conforming to the MCP JSON-RPC 2.0 specification (2024-11-05):
check_code_reflexEvaluates a code snippet against synaptic valence weights and stored experiences in <0.5ms with 0 LLM prompt tokens.
Annotations: readOnlyHint: true, openWorldHint: false
Parameters:
code (string, required): The proposed code snippet, function, or diff to evaluate (aliases: code_snippet, query_code, query).
context (string, optional): Optional context or filename describing the task.
Returns: status (avoid, safe, neutral), valence, confidence, similarity_with_past_bugs, warning, recommendation.
remember_code_outcomeApplies one-shot dopamine reward (test passed) or punishment (test failed/bug) to Mushroom Body synaptic weights.
Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false
Parameters:
code (string, required): The code snippet that was executed or tested (aliases: code_snippet, query_code).
outcome (string, required): "success" (rewards synapses) or "failure" (punishes synapses).
error_message (string, optional): Error trace or description if outcome was "failure".
tags (array of strings, optional): Categorical tags (e.g. ["auth", "database", "deadlock"]).
Returns: status, outcome, valence_type, pattern_valence, active_synapses_updated, total_memories_stored.
query_associative_memorySearches stored code patterns using Fly-LSH sparse binary Hamming similarity.
Annotations: readOnlyHint: true, openWorldHint: false
Parameters:
query_code (string, required): Code snippet to search against associative memory (aliases: query, code, code_snippet).
top_k (integer, optional): Number of nearest neighbors to return (default: 5, clamped $[1, 50]$).
compact (boolean, optional): Whether to return compact match objects to reduce prompt token footprint (default: false).
Returns: query, matches_count, matches (array of nearest records with similarity scores).
inspect_memory_stateReturns operational metrics, weight distribution, and health statistics of the Mushroom Body.
Annotations: readOnlyHint: true, openWorldHint: false
Parameters: None.
Returns: total_memories_stored, total_kenyon_cells, active_sparsity_pct, weights_avg, weights_min, weights_max, depressed_synapses_count, potentiated_synapses_count, storage_location.
reset_memoryResets synaptic weights to neutral baseline (1.0) and purges stored experiences with automatic backup creation.
Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false
Parameters:
confirm (boolean, required): Must be set to true to confirm reset.
backup (boolean, optional): Whether to create a backup file before resetting (default: true).
Returns: status, backup_created, backup_path.
Calyx includes built-in auto-discovery to configure your IDE's MCP settings automatically without manually editing JSON files:
# 1. Install Calyx
pip install calyx-mcp
# 2. Check which IDEs are detected on your machine
calyx-mcp install --status
# 3. Automatically configure all detected IDEs
calyx-mcp install --all
# Or configure a specific IDE:
calyx-mcp install --target claude # Claude Desktop
calyx-mcp install --target cursor # Cursor
calyx-mcp install --target antigravity # Google Antigravity / Gemini (alias: gemini)
calyx-mcp install --target windsurf # Windsurf / Codeium (alias: codeium)
calyx-mcp install --target roo # Roo Code (VS Code) (alias: vscode)
calyx-mcp install --target cline # Cline (VS Code)
calyx-mcp install --target zed # Zed Editor
# Optional: Explicitly specify a custom Python interpreter path
calyx-mcp install --all --python-path /path/to/python
# 4. Initialize AGENTS.md in your current workspace
calyx-mcp initpip install calyx-mcpuvx calyx-mcpAdd Calyx to your MCP client configuration file (e.g. ~/.gemini/config/mcp_config.json, Claude Desktop, or Cursor):
{
"mcpServers": {
"calyx": {
"command": "python",
"args": [
"-m",
"calyx_mcp.server"
]
}
}
}AGENTS.md / .cursorrules / CLAUDE.md)To ensure AI coding agents consistently leverage Calyx before applying code changes and reinforce synapses after testing, add this policy to your project's AGENTS.md, GEMINI.md, CLAUDE.md, or .cursorrules:
## Calyx Associative Memory Policy
1. **Pre-Flight Reflex Check (Before Modifying Code)**:
- Before writing or modifying functions, call `check_code_reflex(code=...)`.
- If `status: "avoid"`, do not proceed with that pattern. Review the past bug warning and choose an alternative approach.
2. **Post-Execution Learning (After Testing)**:
- If tests fail, call `remember_code_outcome(code=..., outcome="failure", error_message=...)`.
- If tests pass, call `remember_code_outcome(code=..., outcome="success")`.Execute the 78-test suite:
python -m pytest tests/ -vTest Suite | Scope & Invariants Tested | Test Count | Status |
| Failure Override Rule (recent failure overrides positive history), recency tie-breaking, state transitions | 3 | PASSED |
| Empty/whitespace rejection, 150KB code blocks, polyglot resilience (Rust, TypeScript, Go, SQL, JSON), unicode | 4 | PASSED |
| 500-record ring buffer bounds, corrupt file baseline recovery, passive synaptic weight decay | 3 | PASSED |
| Fly-LSH $D=2048, k=102$ top-k sparsity, deterministic random projection, AST token extraction | 4 | PASSED |
| Dopaminergic PAM reward / PPL1 punishment updates, synaptic weight bounds $[0.0, 5.0]$ | 2 | PASSED |
| MBON decision thresholds across | 1 | PASSED |
| Multi-OS paths, safe JSON merging, aliases, backup creation, Zed context_servers, interpreter resolution | 10 | PASSED |
| Deserialization guards ( | 6 | PASSED |
| Input validation, parameter clamping, aliases ( | 7 | PASSED |
| Async lock correctness and state integrity under 50 concurrent agent coroutines | 1 | PASSED |
| 15 parametrized valid and invalid input formats (rejects arbitrary strings, booleans, empty strings) | 15 | PASSED |
| MCP protocol annotations ( | 2 | PASSED |
| End-to-end MCP JSON-RPC 2.0 stdio initialization, tool listing, and tool dispatch | 1 | PASSED |
| CLI subcommands: | 3 | PASSED |
| Atomic synaptic weight save/reload and persistent reflex evaluation across instances | 1 | PASSED |
| Hidden-failure recall across insertion orders, disk write error propagation, and stdio subprocess restart | 5 | PASSED |
| Schema token budget (<800 tokens), reflex response footprint (<80 tokens), and mathematical ROI modeling | 3 | PASSED |
| Synthetic corpus integrity and repair validation, including hardcoded-value rejection | 4 | PASSED |
| Negative savings, cache accounting, invalid telemetry and ineligible pairs | 3 | PASSED |
Total | 78 passing test cases | 78 | 100% PASS |
Persistence & Error Handling: Synaptic weights and associative records persist locally in ~/.calyx/. File writes use atomic replacements (.tmp to target). In the event of an I/O or filesystem error during disk persistence, an OSError is raised and propagated to the MCP caller with actionable diagnostics rather than falsely acknowledging successful recording.
Reflex Evaluation Invariant: The reflex engine inspects qualifying failure records ($\ge 0.65$ similarity) before candidate truncation, ensuring previously identified bug patterns reliably trigger the avoid reflex even if multiple subsequent successes have been recorded for related code. Ordinary associative memory queries continue to return the nearest records across all outcomes.
This project is licensed under the MIT License. See the LICENSE file for details.
Instant (<1ms) associative memory check of proposed code against past rewarded or punished bug patterns. Returns 'avoid', 'safe', or 'neutral'.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The proposed code snippet, function, or diff to evaluate. | |
| context | No | Optional context or filename describing the task. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as readOnly, and the description adds meaningful behavioral detail beyond that: the operation is instantaneous (<1ms), memory-based, and returns one of three classification tokens. This gives the agent a clear picture of what happens during invocation without contradicting the annotations.
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 one tight sentence that front-loads the core action, adds a performance guarantee, and finishes with the exact output vocabulary. Every word earns its place; there is no fluff or 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?
Given the simple two-parameter schema with full descriptions Hubbard, the readOnly annotation, and the absence of an output schema, the description is complete: it names the input type, the behavior, and all possible return values. An agent has enough information to invoke the tool correctly.
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 covers both parameters fully (100% coverage) with descriptions for 'code' and 'context'. The tool description does not add new parameter-level semantics beyond what the schema already provides, so a 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 uses a specific verb ('check') and a specific resource ('proposed code against past rewarded or punished bug patterns'), and clearly distinguishes this from the sibling memory-management tools by emphasizing the reflexive, instant associative-memory evaluation. It also states the exact return values ('avoid', 'safe', or 'neutral'), making the tool's purpose immediately unambiguous.
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 the tool is for checking proposed code before using it, but it does not explicitly state when to prefer this over query_associative_memory or other siblings. There are no exclusion criteria or alternative routing cues, so the agent must infer usage context from the tool name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns total active memories, synaptic weight distribution, and health statistics of the Mushroom Body.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes that this is a non-mutating operation. The description adds meaningful context by naming exactly what is returned, going beyond the annotation. However, it does not clarify the format or granularity of the health statistics, though this is a minor gap.
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 entire description is a single well-structured sentence. It leads with the action and immediately lists the key returned data, with no filler or redundant 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?
For a parameterless read-only inspection tool, the description adequately covers purpose and key return values. It lacks an explicit output schema or detailed return format, but given the simplicity of the tool, the description is sufficiently complete for an agent to invoke it correctly.
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, so there is nothing for the description to explain about parameter usage. The schema coverage is effectively complete, and the description focuses on outputs rather than inputs, which 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 states a specific verb ('Returns') and identifies the resource ('Mushroom Body') along with concrete outputs: total active memories, synaptic weight distribution, and health statistics. This clearly distinguishes it from sibling tools that perform different actions like remembering or resetting.
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 about when to use this tool versus alternatives such as query_associative_memory or check_code_reflex. The description implies a read-only inspection use case, but it does not explicitly state conditions or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches stored code patterns using Fly-LSH sparse binary Hamming similarity.
| Name | Required | Description | Default |
|---|---|---|---|
| top_k | No | Number of nearest neighbors to return. | |
| compact | No | Whether to return compact match objects to reduce prompt token footprint. | |
| query_code | Yes | The code query to search against associative memory (accepts 'query_code', 'query', or 'code'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so no behavioral contradiction exists. The description adds useful context by naming the similarity technique, which implies approximate nearest-neighbor search behavior, but it does not disclose output shape, ordering, or exactness properties beyond what the schema and annotations imply.
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, well-structured sentence with no filler. It front-loads the core action and object before adding the algorithmic detail, and every word earns its place.
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 read-only search tool with fully documented parameters, this is mostly sufficient for invocation. However, there is no output schema and no explicit return-shape guidance, and the lack of sibling differentiation leaves a real gap in the agent's ability to confidently select this tool over inspect_memory_state.
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 parameters are already well documented in the schema. The tool description itself adds no extra parameter context, which is acceptable given the schema baseline of 3.
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 names a specific verb ('searches') and resource ('stored code patterns'), and adds the distinctive Fly-LSH sparse binary Hamming similarity approach. It is clear and not tautological, though it does not explicitly differentiate itself from similar-looking siblings like inspect_memory_state.
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 given about when to use this tool versus check_code_reflex, inspect_memory_state, remember_code_outcome, or reset_memory. The description states what the tool does but leaves the agent to infer selection criteria from the tool name and sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Applies one-shot dopamine reward (test passed) or punishment (test failed/bug) to Mushroom Body synaptic weights.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The code snippet that was executed or tested. | |
| tags | No | Optional tags (e.g. ['auth', 'database', 'typerror']). | |
| outcome | Yes | The outcome of testing the code: 'success' (rewards synapses) or 'failure' (punishes synapses). | |
| error_message | No | Optional error trace or description if the outcome was 'failure'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond annotations by mentioning 'one-shot' and the reward/punishment mechanism. Annotations already declare destructiveHint=true and idempotentHint=false, so the description does not contradict and slightly elaborates, but it omits longer-term effects or how this interacts with memory state.
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 redundant text. It is concise, though the heavy use of biological jargon ('Mushroom Body', 'dopamine') may reduce immediate comprehensibility for some agents.
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 is adequate for a destructive mutation with no output schema, but it does not specify return values, side effects beyond 'one-shot', or how this operation fits with sibling memory tools. Annotations cover the safety profile, but the description could better explain the learning mechanism's implications.
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 baseline is 3. The description adds minimal parameter meaning beyond the schema; it maps 'test passed' to success and 'test failed/bug' to failure, which is already captured in the outcome enum description. No extra clarity for tags or error_message.
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 states a specific verb ('Applies'), a resource ('Mushroom Body synaptic weights'), and the reward/punishment behavior based on test outcome. This clearly distinguishes it from sibling read/reset tools, though the biological metaphor ('dopamine reward', 'Mushroom Body') adds a layer of abstraction.
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?
Usage is implied: the tool records test outcomes into memory. However, there is no explicit guidance about when to use it versus alternatives like check_code_reflex or query_associative_memory, and no exclusions or conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resets or prunes the synaptic weights and associative memory back to baseline.
| Name | Required | Description | Default |
|---|---|---|---|
| backup | No | Whether to create a backup file before resetting. | |
| confirm | Yes | Must be set to true to confirm reset. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive, and the description adds context about what is affected ('synaptic weights and associative memory') and the goal ('back to baseline'). It does not fully clarify the 'reset vs. prune' ambiguity or backup behavior, but the schema covers the backup parameter.
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, focused sentence with no filler. It states the action and target immediately, making it easy for an agent to parse quickly.
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 destructive tool, the essential call contract is covered by the annotations and 100% schema coverage. The description could be more complete by clarifying whether the operation is a full reset or a selective prune, but overall the agent has enough to invoke it correctly.
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%: both 'backup' and 'confirm' are documented structurally. The description adds no parameter-level detail, which is acceptable given the complete 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 uses specific verbs ('resets or prunes') and identifies the exact resource ('synaptic weights and associative memory'). It clearly communicates a mutating operation that is distinct from the sibling query/inspection 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?
The description implies when to use the tool: when memory should be returned to baseline. However, it does not explicitly state when not to use it or contrast it with alternatives like inspect_memory_state or query_associative_memory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.7query_associative_memory2 fields changedInput schema / properties / compactAdded value: +{
+ "default": false,
+ "description": "Whether to return compact match objects to reduce prompt token footprint.",
+ "type": "boolean"
+}Input schema / properties / query_code / descriptionPrevious value: -"The code query to search against associative memory."New value: +"The code query to search against associative memory (accepts 'query_code', 'query', or 'code')."v1.0.0check_code_reflexinspect_memory_statequery_associative_memoryremember_code_outcomereset_memoryScored across 5 tools
Each tool has a distinct role: querying memory, checking code reflexes, inspecting state, learning outcomes, and resetting. The only mild overlap is between query_associative_memory and check_code_reflex, since both access stored patterns, but their purposes are clearly separated by general search versus instant classification.
All tool names follow a consistent verb_noun snake_case pattern: query_, check_, inspect_, remember_, and reset_. The naming clearly communicates the action and target for every tool.
Five tools is well-scoped for a memory system server. Each tool covers a necessary operation without redundancy or bloat.
The tool set covers the full lifecycle of associative memory: querying, fast checking, inspecting state, learning from outcomes, and resetting/pruning. No obvious dead ends or missing critical operations exist for the stated purpose.
Collective memory for AI agents. One agent solves a bug — every agent gets the fix instantly.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Shared debugging memory for AI coding agents
Experience memory for coding agents: validated traps, fixes and dead-ends at decision time.
