Calyx MCP
by ericmaddox
README.md
<p align="center">
<img src="https://raw.githubusercontent.com/ericmaddox/calyx-mcp/main/assets/calyx_banner.jpg" alt="Calyx MCP - Bio-Inspired Code Reflex Engine" width="100%" />
</p>
# Calyx MCP
[](https://pypi.org/project/calyx-mcp/)
[](https://pypi.org/project/calyx-mcp/)
[](https://github.com/ericmaddox/calyx-mcp/releases)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
[](tests/)
[](#benchmark-and-token-savings)
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.217 ms (p50) / 0.533 ms (p99)** in-memory (**>6,600x faster**), **2.013 ms (p50) / 3.711 ms (p99)** real-path end-to-end (**>700x faster**) vs ~1,450 ms LLM API roundtrip
* **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 fast reflexes (in-memory: p50 0.217 ms / p99 0.533 ms; real-path: p50 2.013 ms / p99 3.711 ms), 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 fast pattern recognition (p50: 0.217 ms in-memory, 2.013 ms real-path) 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 / Safe / Avoid (p50: 2.01ms, 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](docs/token-trial-v105.md) 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
```text
============================================================================
CALYX MCP: LIVE TOOL EXECUTION & TOKEN SAVINGS BENCHMARK
============================================================================
[Step 1] Initial Code Reflex Check (Zero Prior Training):
* Latency: 2.013 ms (p50 real-path) / 0.217 ms (in-memory)
* 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: 2.450 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 Reintroduced Bug Pattern:
* Latency: 2.013 ms (p50 real-path) / 0.217 ms (in-memory)
* Reflex Status: AVOID (AVERSION TRIGGERED)
* Valence Score: 0.775 (Aversive)
* Bug Similarity: 70.0% (Jaccard: 0.700 >= 0.65 threshold)
* Warning: High resemblance (70%) 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: 2.013 ms p50 real-path / 0.217 ms in-memory (>700x real-path, >6,600x in-memory 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
============================================================================
```
### Performance Summary
| Metric | Traditional LLM Inspection | Calyx Mushroom Body | Improvement |
| :--- | :--- | :--- | :--- |
| **Latency (In-Memory)** | ~1,450 ms | **0.217 ms (p50) / 0.533 ms (p99)** | **> 6,600x faster** |
| **Latency (Real-Path End-to-End)** | ~1,450 ms | **2.013 ms (p50) / 3.711 ms (p99)** | **> 700x faster** (Includes cross-process lock & disk snapshot sync) |
| **Throughput** | 0.5 - 2 req/s | **452 req/s (real-path) / 4,189 req/s (in-memory)** | Zero external network calls |
| **Token Consumption** | 650 - 2,400 tokens per loop | **0 tokens** (Local Fly-LSH) | **100% local execution** |
| **Memory Footprint** | External API | **< 15 MB RAM** | Local execution |
| **Pattern Match Type** | Full prompt parsing | **Sparse Kenyon Cell overlap** | Deterministic associative recall |
> [!NOTE]
> Latency figures are measured across 1,000 iterations using `scripts/bench_reflex.py`. Real-path measurements include full MCP request parsing, inter-process file locking (`msvcrt`/`fcntl`), shared disk state verification, and Kenyon cell projection.
---
### Empirical Generalization & Measured Reflex Verification
Calyx operates as a **deterministic, zero-token associative code memory**. In a pre-registered benchmark across 60 multi-language bug-fix pairs (180 paraphrased variants, 60 fixes, and 120 negative controls in Python, JS, Go, Rust, and SQL), Calyx produced the following measured results:
| Evaluation Dimension | Metric Measured | Result | Details |
| :--- | :--- | :---: | :--- |
| **Unrelated Negative Controls** | False-Positive Rate | **0.00% (0/120)** | Zero false alarms on safe, unrelated code |
| **Fixed Code Contradiction Guard** | False-Positive Rate | **5.00% (3/60)** | Contradiction guard protects fixes from false `avoid` flags |
| **Paraphrased Variant Generalization** | Full-Path Avoid Rate | **4.44% (8/180)** | Measured end-to-end; reordered statements achieve 13.3%, renamed/restructured tokens collapse similarity below 0.65 threshold |
| **Abstracted Tokenizer Experiment** | Offline Proxy Metric | **34.44% (62/180)** | Raw pairwise hash Jaccard >= 0.65; offline proxy bypassing multi-turn train/valence dynamics |
*See [`benchmarks/2026-09-eval/`](benchmarks/2026-09-eval/) for complete JSONL test records, pre-registered targets, methodology, and reproduction scripts (`scripts/eval_generalization.py`).*
> [!IMPORTANT]
> **Loss Asymmetry by Design:** Calyx implements biologically inspired loss aversion. A single punished failure immediately triggers an `avoid` reflex (one-shot aversive conditioning) to shield against regressions. Conversely, achieving a confirmed `safe` reflex requires multiple verified successes (>= 2 rewards) to avoid premature complacency on unverified edge cases.
## 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 (p50: 2.013ms / p99: 3.711ms real-path; p50: 0.217ms in-memory) 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`.
---
## 1-Click Automatic Setup (Recommended)
Calyx includes built-in auto-discovery to configure your IDE's MCP settings automatically without manually editing JSON files:
```bash
# 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 init
```
---
## Manual Installation & Configuration
### Standard Installation via pip or uv
```bash
pip install calyx-mcp
```
### Run Without Installation via uvx
```bash
uvx calyx-mcp
```
### Manual MCP Client JSON Configuration
Add Calyx to your MCP client configuration file (e.g. `~/.gemini/config/mcp_config.json`, Claude Desktop, or Cursor):
```json
{
"mcpServers": {
"calyx": {
"command": "python",
"args": [
"-m",
"calyx_mcp.server"
]
}
}
}
```
---
## Recommended Agent Rules (`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`:
```markdown
## 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")`.
```
---
## Running Tests
Execute the 92-test suite:
```bash
python -m pytest tests/ -v
```
### Test Suite Results (92 / 92 Passing)
| Test Suite | Scope & Invariants Tested | Test Count | Status |
| :--- | :--- | :---: | :---: |
| **`tests/unit/test_contradiction_resolution.py`** | Failure Override Rule (recent failure overrides positive history), recency tie-breaking, state transitions | 3 | **PASSED** |
| **`tests/unit/test_edge_cases_and_resilience.py`** | Empty/whitespace rejection, 150KB code blocks, polyglot resilience (Rust, TypeScript, Go, SQL, JSON), unicode | 4 | **PASSED** |
| **`tests/unit/test_memory_lifecycle_and_bounds.py`** | 500-record ring buffer bounds, corrupt file baseline recovery, passive synaptic weight decay | 3 | **PASSED** |
| **`tests/unit/test_hasher.py`** | Fly-LSH $D=2048, k=102$ top-k sparsity, deterministic random projection, AST token extraction | 5 | **PASSED** |
| **`tests/unit/test_memory.py`** | Dopaminergic PAM reward / PPL1 punishment updates, synaptic weight bounds $[0.0, 5.0]$ | 2 | **PASSED** |
| **`tests/unit/test_reflex.py`** | MBON decision thresholds across `avoid`, `safe`, and `neutral` | 4 | **PASSED** |
| **`tests/unit/test_installer.py`** | Multi-OS paths, safe JSON merging, aliases, backup creation, Zed context_servers, interpreter resolution | 10 | **PASSED** |
| **`tests/unit/test_installer_regressions.py`** | JSONC string preservation, malformed-input rejection, JSONC discovery, native Cursor paths | 4 | **PASSED** |
| **`tests/test_security_hardening.py`** | Deserialization guards (`allow_pickle=False`), NaN/Inf recovery, payload length bounds, `.orig.bak` preservation, JSONC comments | 6 | **PASSED** |
| **`tests/e2e/test_mcp_api_hardening.py`** | Input validation, parameter clamping, aliases (`query`, `code`), compact mode, `-32601` method errors, resources read/list, ping | 7 | **PASSED** |
| **`tests/e2e/test_concurrency_stress.py`** | Async lock correctness and state integrity under 50 concurrent agent coroutines | 1 | **PASSED** |
| **`tests/e2e/test_outcome_validation.py`** | 15 parametrized valid and invalid input formats (rejects arbitrary strings, booleans, empty strings) | 15 | **PASSED** |
| **`tests/e2e/test_tool_annotations.py`** | MCP protocol annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) | 2 | **PASSED** |
| **`tests/e2e/test_mcp_stdio.py`** | End-to-end MCP JSON-RPC 2.0 stdio initialization, tool listing, and tool dispatch | 1 | **PASSED** |
| **`tests/e2e/test_cli_installer.py`** | CLI subcommands: `calyx-mcp --help`, `calyx-mcp install --status`, and `calyx-mcp init` | 3 | **PASSED** |
| **`tests/integration/test_persistence.py`** | Atomic synaptic weight save/reload and persistent reflex evaluation across instances | 2 | **PASSED** |
| **`tests/integration/test_shared_storage.py`** | Custom filenames, exact weight shape, stale and concurrent process writes, reader refresh and reset | 5 | **PASSED** |
| **`tests/e2e/test_release_followups.py`** | Hidden-failure recall across insertion orders, disk write error propagation, and stdio subprocess restart | 5 | **PASSED** |
| **`tests/benchmarks/test_token_economics.py`** | Schema token budget (<800 tokens), reflex response footprint (<80 tokens), and mathematical ROI modeling | 3 | **PASSED** |
| **`tests/unit/test_history_reuse_benchmark.py`** | Synthetic corpus integrity and repair validation, including hardcoded-value rejection | 4 | **PASSED** |
| **`tests/unit/test_history_usage.py`** | Negative savings, cache accounting, invalid telemetry and ineligible pairs | 3 | **PASSED** |
| **Total** | **92 passing test cases** | **92** | **100% PASS** |
> [!NOTE]
> **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.
>
> **Shared Storage**: Cooperating clients serialize reload/update/save operations with an OS file lock. Queries refresh their snapshot so another client's writes and resets are visible. All clients sharing a directory must use a version with this locking behavior; older clients do not participate. Each file replacement is atomic, but the two-file format is not a crash-atomic transaction. A failed write can still leave partial state, as reported by the persistence error. These reads now include filesystem work; the historical in-memory latency measurements above are not a benchmark of shared-store reads.
>
> **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.
---
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
TDQS
A4/5.0
Scored across 5 tools
Disambiguation4/5
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.
Naming Consistency5/5
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.
Tool Count5/5
Five tools is well-scoped for a memory system server. Each tool covers a necessary operation without redundancy or bloat.
Completeness5/5
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.
Maintenance
ActivityMaintained
ResponsivenessNo issues