Calyx MCP

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).

Why "Calyx"?

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.

Overview

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.

Architectural Principles

+-----------------------------------------------------------------------+
|                             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)  |
+-----------------------------------------------------------------------+

1. Fly-LSH Projection: Projects token distributions into a 2,048-dimensional space using deterministic hashing, mimicking the projection neuron to Kenyon cell expansion.
2. Winner-Take-All (WTA) Sparsity: Retains only the top $k=102$ activations (~4.98% sparsity) via inhibitory feedback (APL neuron equivalent).
3. Dopamine Synaptic Plasticity: Adjusts synaptic weights based on coding execution outcomes (success/failure), enabling rapid aversion to bug patterns and attraction to proven implementations.
4. Local Atomic Persistence: Synaptic states and associative memory records persist locally in compressed .npz and JSON formats (~/.calyx/).

Benchmark and Token Savings

The following performance metrics were measured on a Windows x86_64 host running Python 3.13 with native NumPy operations:

Test Execution Log

============================================================================
        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% of LLM tokens saved on learned code anti-patterns

============================================================================
              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:       C:\Users\EricM\.calyx
============================================================================

Performance Summary

MCP Tools Reference

Calyx registers the following tools conforming to the MCP JSON-RPC 2.0 specification:

1. check_code_reflex

Evaluates a code snippet against synaptic valence weights and stored experiences.

• Parameters:
  • code_snippet (string, required): Source code to evaluate.
  • language (string, optional): Programming language (e.g. python, javascript).
• Returns: status (neutral, aversion, attraction), valence, similarity_with_past_bugs, warning, recommendation.

2. remember_code_outcome

Applies dopamine-driven synaptic updates based on test execution or runtime results.

• Parameters:
  • code_snippet (string, required): Code associated with the outcome.
  • language (string, required): Programming language.
  • outcome (string, required): success or failure.
  • lesson (string, required): Summary of the bug or successful pattern.
  • reward_score (number, optional): Value between -1.0 (punishment) and +1.0 (reward). Default -1.0 for failure, +1.0 for success.

3. query_associative_memory

Performs approximate nearest-neighbor search across stored code experiences using Fly-LSH similarity.

• Parameters:
  • query_code (string, required): Code snippet to match.
  • top_k (integer, optional): Maximum results to return (default: 5).
  • language (string, optional): Language filter.

4. inspect_memory_state

Returns operational metrics and synaptic weight distribution of the Mushroom Body.

• Parameters: None.
• Returns: Active sparsity percentage, total Kenyon cells, weight distribution stats, and storage location.

5. reset_memory

Resets synaptic weights to neutral baseline and purges stored experiences.

• Parameters:
  • confirm (boolean, required): Confirmation flag (true).

Installation

Prerequisites

• Python 3.10 or higher
• NumPy >= 1.24.0

Install via pip (Editable Mode)

git clone https://github.com/ericmaddox/calyx-mcp.git
cd calyx-mcp
pip install -e .

Configuration

Add Calyx to your MCP configuration file (e.g., ~/.gemini/config/mcp_config.json, Claude Desktop config, or Cursor configuration):

{
  "mcpServers": {
    "calyx": {
      "command": "python",
      "args": [
        "-m",
        "calyx_mcp.server",
        "--transport",
        "stdio"
      ]
    }
  }
}

Running Tests

Execute the comprehensive test suite:

python -m unittest discover -s tests -p "test_*.py" -v

Test Coverage

• test_hasher.py: Verifies deterministic hashing, projection dimensions, and Winner-Take-All sparsity.
• test_memory.py: Verifies associative retrieval, dopamine-mediated plasticity, weight bounds, and file persistence.
• test_reflex.py: Verifies rapid aversion on bug patterns and attraction on reinforced patterns.
• test_server.py: Verifies JSON-RPC 2.0 tool registration, protocol initialization, and execution handlers.

License

This project is licensed under the MIT License. See the LICENSE file for details.