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

At a Glance

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

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

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:

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

Performance Summary

Real-World Bug & Vulnerability Verification

Calyx was benchmarked against real-world vulnerability and resource management patterns to test generalization across altered variable names, structural shifts, and function signatures:

MCP Tools Reference

Calyx registers the following tools conforming to the MCP JSON-RPC 2.0 specification (2024-11-05):

1. check_code_reflex

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

2. remember_code_outcome

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

3. query_associative_memory

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

4. inspect_memory_state

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

5. reset_memory

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

Installation

Option 1: Standard Installation via pip or uv (Recommended)

# Using pip
pip install calyx-mcp

# Using uv
uv pip install calyx-mcp

Option 2: Run Without Installation via uvx

You can run Calyx MCP instantly without installing it into a local environment using uvx:

uvx calyx-mcp

Option 3: Development Mode (from source)

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

Configuration

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

Using uvx (Zero-Install, Recommended)

{
  "mcpServers": {
    "calyx": {
      "command": "uvx",
      "args": ["calyx-mcp"]
    }
  }
}

Using Installed Python / CLI Command

{
  "mcpServers": {
    "calyx": {
      "command": "calyx-mcp"
    }
  }
}

Running Tests

Execute the 59-test suite:

python -m pytest tests/ -v

Test Suite Results (59 / 59 Passing)

License

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