calyx-mcp 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- calyx_mcp-1.0.0/LICENSE +21 -0
- calyx_mcp-1.0.0/PKG-INFO +263 -0
- calyx_mcp-1.0.0/README.md +228 -0
- calyx_mcp-1.0.0/pyproject.toml +73 -0
- calyx_mcp-1.0.0/setup.cfg +4 -0
- calyx_mcp-1.0.0/setup.py +7 -0
- calyx_mcp-1.0.0/src/calyx_mcp/__init__.py +29 -0
- calyx_mcp-1.0.0/src/calyx_mcp/client.py +65 -0
- calyx_mcp-1.0.0/src/calyx_mcp/config.py +98 -0
- calyx_mcp-1.0.0/src/calyx_mcp/hasher.py +145 -0
- calyx_mcp-1.0.0/src/calyx_mcp/memory.py +189 -0
- calyx_mcp-1.0.0/src/calyx_mcp/reflex.py +90 -0
- calyx_mcp-1.0.0/src/calyx_mcp/server.py +201 -0
- calyx_mcp-1.0.0/src/calyx_mcp/tools.py +119 -0
- calyx_mcp-1.0.0/src/calyx_mcp.egg-info/PKG-INFO +263 -0
- calyx_mcp-1.0.0/src/calyx_mcp.egg-info/SOURCES.txt +18 -0
- calyx_mcp-1.0.0/src/calyx_mcp.egg-info/dependency_links.txt +1 -0
- calyx_mcp-1.0.0/src/calyx_mcp.egg-info/entry_points.txt +4 -0
- calyx_mcp-1.0.0/src/calyx_mcp.egg-info/requires.txt +8 -0
- calyx_mcp-1.0.0/src/calyx_mcp.egg-info/top_level.txt +1 -0
calyx_mcp-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Calyx Research Team
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
calyx_mcp-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: calyx-mcp
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Bio-inspired associative memory & code reflex MCP server powered by the Drosophila Mushroom Body
|
|
5
|
+
Author-email: Eric Maddox <eric.maddox@outlook.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/ericmaddox/calyx-mcp
|
|
8
|
+
Project-URL: Repository, https://github.com/ericmaddox/calyx-mcp
|
|
9
|
+
Project-URL: Issues, https://github.com/ericmaddox/calyx-mcp/issues
|
|
10
|
+
Project-URL: Documentation, https://github.com/ericmaddox/calyx-mcp#readme
|
|
11
|
+
Keywords: mcp,model-context-protocol,fruit-fly,mushroom-body,fly-lsh,associative-memory,code-reflex,ai-agents
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
23
|
+
Classifier: Topic :: Software Development :: Code Generators
|
|
24
|
+
Requires-Python: >=3.9
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Requires-Dist: numpy>=1.21.0
|
|
28
|
+
Provides-Extra: dev
|
|
29
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
30
|
+
Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
|
|
31
|
+
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
|
|
32
|
+
Requires-Dist: build>=1.0.0; extra == "dev"
|
|
33
|
+
Requires-Dist: twine>=5.0.0; extra == "dev"
|
|
34
|
+
Dynamic: license-file
|
|
35
|
+
|
|
36
|
+
# Calyx MCP
|
|
37
|
+
|
|
38
|
+
[](https://www.python.org/)
|
|
39
|
+
[](https://modelcontextprotocol.io/)
|
|
40
|
+
[](LICENSE)
|
|
41
|
+
[](tests/)
|
|
42
|
+
[](#benchmark-and-token-savings)
|
|
43
|
+
|
|
44
|
+
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).
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## Why "Calyx"?
|
|
49
|
+
|
|
50
|
+
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).
|
|
51
|
+
|
|
52
|
+
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.
|
|
53
|
+
|
|
54
|
+
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.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Overview
|
|
59
|
+
|
|
60
|
+
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.
|
|
61
|
+
|
|
62
|
+
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.
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Architectural Principles
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
+-----------------------------------------------------------------------+
|
|
70
|
+
| Calyx MCP |
|
|
71
|
+
+-----------------------------------------------------------------------+
|
|
72
|
+
| Input Code Snippet / AST Tokens |
|
|
73
|
+
| | |
|
|
74
|
+
| v |
|
|
75
|
+
| Fly-LSH Hash Projection (Projection Dimension = 2048) |
|
|
76
|
+
| | |
|
|
77
|
+
| v |
|
|
78
|
+
| Winner-Take-All Sparsification (k = 102 active Kenyon Cells, ~5%) |
|
|
79
|
+
| | |
|
|
80
|
+
| v |
|
|
81
|
+
| Mushroom Body Output Neuron (MBON) Synaptic Weight Matrix |
|
|
82
|
+
| | |
|
|
83
|
+
| +----+------------------------------------------------------------+ |
|
|
84
|
+
| | Dopaminergic Modulation: dW = eta * Dopamine * (KC (x) MBON) | |
|
|
85
|
+
| +-----------------------------------------------------------------+ |
|
|
86
|
+
| | |
|
|
87
|
+
| v |
|
|
88
|
+
| Reflex Output: Neutral / Attraction / Aversion (< 0.5 ms, 0 Tokens) |
|
|
89
|
+
+-----------------------------------------------------------------------+
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
1. **Fly-LSH Projection**: Projects token distributions into a 2,048-dimensional space using deterministic hashing, mimicking the projection neuron to Kenyon cell expansion.
|
|
93
|
+
2. **Winner-Take-All (WTA) Sparsity**: Retains only the top $k=102$ activations (~4.98% sparsity) via inhibitory feedback (APL neuron equivalent).
|
|
94
|
+
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.
|
|
95
|
+
4. **Local Atomic Persistence**: Synaptic states and associative memory records persist locally in compressed `.npz` and JSON formats (`~/.calyx/`).
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## Benchmark and Token Savings
|
|
100
|
+
|
|
101
|
+
The following performance metrics were measured on a Windows x86_64 host running Python 3.13 with native NumPy operations:
|
|
102
|
+
|
|
103
|
+
### Test Execution Log
|
|
104
|
+
|
|
105
|
+
```text
|
|
106
|
+
============================================================================
|
|
107
|
+
CALYX MCP: LIVE TOOL EXECUTION & TOKEN SAVINGS BENCHMARK
|
|
108
|
+
============================================================================
|
|
109
|
+
|
|
110
|
+
[Step 1] Initial Code Reflex Check (Zero Prior Training):
|
|
111
|
+
* Latency: 0.729 ms
|
|
112
|
+
* Reflex Status: NEUTRAL
|
|
113
|
+
* Valence: 1.000
|
|
114
|
+
* Recommendation: Novel or unverified code pattern. Proceed normally.
|
|
115
|
+
* LLM Tokens Used: 0 tokens (Zero API overhead)
|
|
116
|
+
|
|
117
|
+
[Step 2] Dopamine Reinforcement (Negative Dopamine Delivery):
|
|
118
|
+
* Plasticity Latency: 4.040 ms
|
|
119
|
+
* Status: recorded
|
|
120
|
+
* Valence Type: punishment (Dopaminergic depression signal)
|
|
121
|
+
* Active Synapses: 102 Kenyon Cells updated
|
|
122
|
+
* Persistent State: Saved to ~/.calyx/mushroom_body_weights.npz
|
|
123
|
+
|
|
124
|
+
[Step 3] Fast Bio-Reflex on Novel Code Variant:
|
|
125
|
+
* Latency: 0.400 ms
|
|
126
|
+
* Reflex Status: AVOID (AVERSION TRIGGERED)
|
|
127
|
+
* Valence Score: 0.775 (Aversive)
|
|
128
|
+
* Bug Similarity: 100.0%
|
|
129
|
+
* Warning: High resemblance (100%) to a previously punished bug pattern.
|
|
130
|
+
* Recommendation: Review code logic, check edge cases, or adopt alternative.
|
|
131
|
+
|
|
132
|
+
============================================================================
|
|
133
|
+
TOKEN SAVINGS & SPEEDUP
|
|
134
|
+
============================================================================
|
|
135
|
+
Traditional LLM Querying Loop:
|
|
136
|
+
* Latency per review: ~1450 ms
|
|
137
|
+
* Inspection Cost: ~650 prompt tokens per check
|
|
138
|
+
* Debugging Loop: ~2400 tokens per repeated bug
|
|
139
|
+
|
|
140
|
+
Calyx Mushroom Body Reflex:
|
|
141
|
+
* Latency per review: 0.400 ms (~3,628x speedup)
|
|
142
|
+
* Token Cost: 0 tokens (Local Fly-LSH sparse projection)
|
|
143
|
+
* Token Efficiency: 100% of LLM tokens saved on learned code anti-patterns
|
|
144
|
+
|
|
145
|
+
============================================================================
|
|
146
|
+
MUSHROOM BODY NEURAL ARCHITECTURE STATE
|
|
147
|
+
============================================================================
|
|
148
|
+
* Kenyon Cells Dimension: 2048
|
|
149
|
+
* Sparsity Active Ratio: 4.98% active neurons
|
|
150
|
+
* Total Memories Stored: 1
|
|
151
|
+
* Depressed Synapses (W): 102
|
|
152
|
+
* Weights Min / Avg / Max: 0.775 / 0.9888 / 1.0
|
|
153
|
+
* Storage Directory: C:\Users\EricM\.calyx
|
|
154
|
+
============================================================================
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### Performance Summary
|
|
158
|
+
|
|
159
|
+
| Metric | Traditional LLM Inspection | Calyx Mushroom Body | Improvement |
|
|
160
|
+
| :--- | :--- | :--- | :--- |
|
|
161
|
+
| **Latency** | ~1,450 ms | **0.400 ms** | **3,628x faster** |
|
|
162
|
+
| **Token Consumption** | 650 - 2,400 tokens | **0 tokens** | **100% token savings** |
|
|
163
|
+
| **Memory Footprint** | External API | **< 15 MB RAM** | Local execution |
|
|
164
|
+
| **Pattern Match Type** | Full prompt parsing | **Sparse Kenyon Cell overlap** | Deterministic associative recall |
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## MCP Tools Reference
|
|
169
|
+
|
|
170
|
+
Calyx registers the following tools conforming to the MCP JSON-RPC 2.0 specification:
|
|
171
|
+
|
|
172
|
+
### 1. `check_code_reflex`
|
|
173
|
+
Evaluates a code snippet against synaptic valence weights and stored experiences.
|
|
174
|
+
- **Parameters**:
|
|
175
|
+
- `code_snippet` (string, required): Source code to evaluate.
|
|
176
|
+
- `language` (string, optional): Programming language (e.g. `python`, `javascript`).
|
|
177
|
+
- **Returns**: `status` (`neutral`, `aversion`, `attraction`), `valence`, `similarity_with_past_bugs`, `warning`, `recommendation`.
|
|
178
|
+
|
|
179
|
+
### 2. `remember_code_outcome`
|
|
180
|
+
Applies dopamine-driven synaptic updates based on test execution or runtime results.
|
|
181
|
+
- **Parameters**:
|
|
182
|
+
- `code_snippet` (string, required): Code associated with the outcome.
|
|
183
|
+
- `language` (string, required): Programming language.
|
|
184
|
+
- `outcome` (string, required): `success` or `failure`.
|
|
185
|
+
- `lesson` (string, required): Summary of the bug or successful pattern.
|
|
186
|
+
- `reward_score` (number, optional): Value between `-1.0` (punishment) and `+1.0` (reward). Default `-1.0` for failure, `+1.0` for success.
|
|
187
|
+
|
|
188
|
+
### 3. `query_associative_memory`
|
|
189
|
+
Performs approximate nearest-neighbor search across stored code experiences using Fly-LSH similarity.
|
|
190
|
+
- **Parameters**:
|
|
191
|
+
- `query_code` (string, required): Code snippet to match.
|
|
192
|
+
- `top_k` (integer, optional): Maximum results to return (default: `5`).
|
|
193
|
+
- `language` (string, optional): Language filter.
|
|
194
|
+
|
|
195
|
+
### 4. `inspect_memory_state`
|
|
196
|
+
Returns operational metrics and synaptic weight distribution of the Mushroom Body.
|
|
197
|
+
- **Parameters**: None.
|
|
198
|
+
- **Returns**: Active sparsity percentage, total Kenyon cells, weight distribution stats, and storage location.
|
|
199
|
+
|
|
200
|
+
### 5. `reset_memory`
|
|
201
|
+
Resets synaptic weights to neutral baseline and purges stored experiences.
|
|
202
|
+
- **Parameters**:
|
|
203
|
+
- `confirm` (boolean, required): Confirmation flag (`true`).
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## Installation
|
|
208
|
+
|
|
209
|
+
### Prerequisites
|
|
210
|
+
- Python 3.10 or higher
|
|
211
|
+
- NumPy >= 1.24.0
|
|
212
|
+
|
|
213
|
+
### Install via pip (Editable Mode)
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
git clone https://github.com/ericmaddox/calyx-mcp.git
|
|
217
|
+
cd calyx-mcp
|
|
218
|
+
pip install -e .
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## Configuration
|
|
224
|
+
|
|
225
|
+
Add Calyx to your MCP configuration file (e.g., `~/.gemini/config/mcp_config.json`, Claude Desktop config, or Cursor configuration):
|
|
226
|
+
|
|
227
|
+
```json
|
|
228
|
+
{
|
|
229
|
+
"mcpServers": {
|
|
230
|
+
"calyx": {
|
|
231
|
+
"command": "python",
|
|
232
|
+
"args": [
|
|
233
|
+
"-m",
|
|
234
|
+
"calyx_mcp.server",
|
|
235
|
+
"--transport",
|
|
236
|
+
"stdio"
|
|
237
|
+
]
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
## Running Tests
|
|
246
|
+
|
|
247
|
+
Execute the comprehensive test suite:
|
|
248
|
+
|
|
249
|
+
```bash
|
|
250
|
+
python -m unittest discover -s tests -p "test_*.py" -v
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
### Test Coverage
|
|
254
|
+
- `test_hasher.py`: Verifies deterministic hashing, projection dimensions, and Winner-Take-All sparsity.
|
|
255
|
+
- `test_memory.py`: Verifies associative retrieval, dopamine-mediated plasticity, weight bounds, and file persistence.
|
|
256
|
+
- `test_reflex.py`: Verifies rapid aversion on bug patterns and attraction on reinforced patterns.
|
|
257
|
+
- `test_server.py`: Verifies JSON-RPC 2.0 tool registration, protocol initialization, and execution handlers.
|
|
258
|
+
|
|
259
|
+
---
|
|
260
|
+
|
|
261
|
+
## License
|
|
262
|
+
|
|
263
|
+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
|
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
# Calyx MCP
|
|
2
|
+
|
|
3
|
+
[](https://www.python.org/)
|
|
4
|
+
[](https://modelcontextprotocol.io/)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](tests/)
|
|
7
|
+
[](#benchmark-and-token-savings)
|
|
8
|
+
|
|
9
|
+
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).
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Why "Calyx"?
|
|
14
|
+
|
|
15
|
+
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).
|
|
16
|
+
|
|
17
|
+
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.
|
|
18
|
+
|
|
19
|
+
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.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Overview
|
|
24
|
+
|
|
25
|
+
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.
|
|
26
|
+
|
|
27
|
+
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.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Architectural Principles
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
+-----------------------------------------------------------------------+
|
|
35
|
+
| Calyx MCP |
|
|
36
|
+
+-----------------------------------------------------------------------+
|
|
37
|
+
| Input Code Snippet / AST Tokens |
|
|
38
|
+
| | |
|
|
39
|
+
| v |
|
|
40
|
+
| Fly-LSH Hash Projection (Projection Dimension = 2048) |
|
|
41
|
+
| | |
|
|
42
|
+
| v |
|
|
43
|
+
| Winner-Take-All Sparsification (k = 102 active Kenyon Cells, ~5%) |
|
|
44
|
+
| | |
|
|
45
|
+
| v |
|
|
46
|
+
| Mushroom Body Output Neuron (MBON) Synaptic Weight Matrix |
|
|
47
|
+
| | |
|
|
48
|
+
| +----+------------------------------------------------------------+ |
|
|
49
|
+
| | Dopaminergic Modulation: dW = eta * Dopamine * (KC (x) MBON) | |
|
|
50
|
+
| +-----------------------------------------------------------------+ |
|
|
51
|
+
| | |
|
|
52
|
+
| v |
|
|
53
|
+
| Reflex Output: Neutral / Attraction / Aversion (< 0.5 ms, 0 Tokens) |
|
|
54
|
+
+-----------------------------------------------------------------------+
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
1. **Fly-LSH Projection**: Projects token distributions into a 2,048-dimensional space using deterministic hashing, mimicking the projection neuron to Kenyon cell expansion.
|
|
58
|
+
2. **Winner-Take-All (WTA) Sparsity**: Retains only the top $k=102$ activations (~4.98% sparsity) via inhibitory feedback (APL neuron equivalent).
|
|
59
|
+
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.
|
|
60
|
+
4. **Local Atomic Persistence**: Synaptic states and associative memory records persist locally in compressed `.npz` and JSON formats (`~/.calyx/`).
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## Benchmark and Token Savings
|
|
65
|
+
|
|
66
|
+
The following performance metrics were measured on a Windows x86_64 host running Python 3.13 with native NumPy operations:
|
|
67
|
+
|
|
68
|
+
### Test Execution Log
|
|
69
|
+
|
|
70
|
+
```text
|
|
71
|
+
============================================================================
|
|
72
|
+
CALYX MCP: LIVE TOOL EXECUTION & TOKEN SAVINGS BENCHMARK
|
|
73
|
+
============================================================================
|
|
74
|
+
|
|
75
|
+
[Step 1] Initial Code Reflex Check (Zero Prior Training):
|
|
76
|
+
* Latency: 0.729 ms
|
|
77
|
+
* Reflex Status: NEUTRAL
|
|
78
|
+
* Valence: 1.000
|
|
79
|
+
* Recommendation: Novel or unverified code pattern. Proceed normally.
|
|
80
|
+
* LLM Tokens Used: 0 tokens (Zero API overhead)
|
|
81
|
+
|
|
82
|
+
[Step 2] Dopamine Reinforcement (Negative Dopamine Delivery):
|
|
83
|
+
* Plasticity Latency: 4.040 ms
|
|
84
|
+
* Status: recorded
|
|
85
|
+
* Valence Type: punishment (Dopaminergic depression signal)
|
|
86
|
+
* Active Synapses: 102 Kenyon Cells updated
|
|
87
|
+
* Persistent State: Saved to ~/.calyx/mushroom_body_weights.npz
|
|
88
|
+
|
|
89
|
+
[Step 3] Fast Bio-Reflex on Novel Code Variant:
|
|
90
|
+
* Latency: 0.400 ms
|
|
91
|
+
* Reflex Status: AVOID (AVERSION TRIGGERED)
|
|
92
|
+
* Valence Score: 0.775 (Aversive)
|
|
93
|
+
* Bug Similarity: 100.0%
|
|
94
|
+
* Warning: High resemblance (100%) to a previously punished bug pattern.
|
|
95
|
+
* Recommendation: Review code logic, check edge cases, or adopt alternative.
|
|
96
|
+
|
|
97
|
+
============================================================================
|
|
98
|
+
TOKEN SAVINGS & SPEEDUP
|
|
99
|
+
============================================================================
|
|
100
|
+
Traditional LLM Querying Loop:
|
|
101
|
+
* Latency per review: ~1450 ms
|
|
102
|
+
* Inspection Cost: ~650 prompt tokens per check
|
|
103
|
+
* Debugging Loop: ~2400 tokens per repeated bug
|
|
104
|
+
|
|
105
|
+
Calyx Mushroom Body Reflex:
|
|
106
|
+
* Latency per review: 0.400 ms (~3,628x speedup)
|
|
107
|
+
* Token Cost: 0 tokens (Local Fly-LSH sparse projection)
|
|
108
|
+
* Token Efficiency: 100% of LLM tokens saved on learned code anti-patterns
|
|
109
|
+
|
|
110
|
+
============================================================================
|
|
111
|
+
MUSHROOM BODY NEURAL ARCHITECTURE STATE
|
|
112
|
+
============================================================================
|
|
113
|
+
* Kenyon Cells Dimension: 2048
|
|
114
|
+
* Sparsity Active Ratio: 4.98% active neurons
|
|
115
|
+
* Total Memories Stored: 1
|
|
116
|
+
* Depressed Synapses (W): 102
|
|
117
|
+
* Weights Min / Avg / Max: 0.775 / 0.9888 / 1.0
|
|
118
|
+
* Storage Directory: C:\Users\EricM\.calyx
|
|
119
|
+
============================================================================
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Performance Summary
|
|
123
|
+
|
|
124
|
+
| Metric | Traditional LLM Inspection | Calyx Mushroom Body | Improvement |
|
|
125
|
+
| :--- | :--- | :--- | :--- |
|
|
126
|
+
| **Latency** | ~1,450 ms | **0.400 ms** | **3,628x faster** |
|
|
127
|
+
| **Token Consumption** | 650 - 2,400 tokens | **0 tokens** | **100% token savings** |
|
|
128
|
+
| **Memory Footprint** | External API | **< 15 MB RAM** | Local execution |
|
|
129
|
+
| **Pattern Match Type** | Full prompt parsing | **Sparse Kenyon Cell overlap** | Deterministic associative recall |
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## MCP Tools Reference
|
|
134
|
+
|
|
135
|
+
Calyx registers the following tools conforming to the MCP JSON-RPC 2.0 specification:
|
|
136
|
+
|
|
137
|
+
### 1. `check_code_reflex`
|
|
138
|
+
Evaluates a code snippet against synaptic valence weights and stored experiences.
|
|
139
|
+
- **Parameters**:
|
|
140
|
+
- `code_snippet` (string, required): Source code to evaluate.
|
|
141
|
+
- `language` (string, optional): Programming language (e.g. `python`, `javascript`).
|
|
142
|
+
- **Returns**: `status` (`neutral`, `aversion`, `attraction`), `valence`, `similarity_with_past_bugs`, `warning`, `recommendation`.
|
|
143
|
+
|
|
144
|
+
### 2. `remember_code_outcome`
|
|
145
|
+
Applies dopamine-driven synaptic updates based on test execution or runtime results.
|
|
146
|
+
- **Parameters**:
|
|
147
|
+
- `code_snippet` (string, required): Code associated with the outcome.
|
|
148
|
+
- `language` (string, required): Programming language.
|
|
149
|
+
- `outcome` (string, required): `success` or `failure`.
|
|
150
|
+
- `lesson` (string, required): Summary of the bug or successful pattern.
|
|
151
|
+
- `reward_score` (number, optional): Value between `-1.0` (punishment) and `+1.0` (reward). Default `-1.0` for failure, `+1.0` for success.
|
|
152
|
+
|
|
153
|
+
### 3. `query_associative_memory`
|
|
154
|
+
Performs approximate nearest-neighbor search across stored code experiences using Fly-LSH similarity.
|
|
155
|
+
- **Parameters**:
|
|
156
|
+
- `query_code` (string, required): Code snippet to match.
|
|
157
|
+
- `top_k` (integer, optional): Maximum results to return (default: `5`).
|
|
158
|
+
- `language` (string, optional): Language filter.
|
|
159
|
+
|
|
160
|
+
### 4. `inspect_memory_state`
|
|
161
|
+
Returns operational metrics and synaptic weight distribution of the Mushroom Body.
|
|
162
|
+
- **Parameters**: None.
|
|
163
|
+
- **Returns**: Active sparsity percentage, total Kenyon cells, weight distribution stats, and storage location.
|
|
164
|
+
|
|
165
|
+
### 5. `reset_memory`
|
|
166
|
+
Resets synaptic weights to neutral baseline and purges stored experiences.
|
|
167
|
+
- **Parameters**:
|
|
168
|
+
- `confirm` (boolean, required): Confirmation flag (`true`).
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## Installation
|
|
173
|
+
|
|
174
|
+
### Prerequisites
|
|
175
|
+
- Python 3.10 or higher
|
|
176
|
+
- NumPy >= 1.24.0
|
|
177
|
+
|
|
178
|
+
### Install via pip (Editable Mode)
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
git clone https://github.com/ericmaddox/calyx-mcp.git
|
|
182
|
+
cd calyx-mcp
|
|
183
|
+
pip install -e .
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## Configuration
|
|
189
|
+
|
|
190
|
+
Add Calyx to your MCP configuration file (e.g., `~/.gemini/config/mcp_config.json`, Claude Desktop config, or Cursor configuration):
|
|
191
|
+
|
|
192
|
+
```json
|
|
193
|
+
{
|
|
194
|
+
"mcpServers": {
|
|
195
|
+
"calyx": {
|
|
196
|
+
"command": "python",
|
|
197
|
+
"args": [
|
|
198
|
+
"-m",
|
|
199
|
+
"calyx_mcp.server",
|
|
200
|
+
"--transport",
|
|
201
|
+
"stdio"
|
|
202
|
+
]
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## Running Tests
|
|
211
|
+
|
|
212
|
+
Execute the comprehensive test suite:
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
python -m unittest discover -s tests -p "test_*.py" -v
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
### Test Coverage
|
|
219
|
+
- `test_hasher.py`: Verifies deterministic hashing, projection dimensions, and Winner-Take-All sparsity.
|
|
220
|
+
- `test_memory.py`: Verifies associative retrieval, dopamine-mediated plasticity, weight bounds, and file persistence.
|
|
221
|
+
- `test_reflex.py`: Verifies rapid aversion on bug patterns and attraction on reinforced patterns.
|
|
222
|
+
- `test_server.py`: Verifies JSON-RPC 2.0 tool registration, protocol initialization, and execution handlers.
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## License
|
|
227
|
+
|
|
228
|
+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "calyx-mcp"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Bio-inspired associative memory & code reflex MCP server powered by the Drosophila Mushroom Body"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.9"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [
|
|
14
|
+
{name = "Eric Maddox", email = "eric.maddox@outlook.com"}
|
|
15
|
+
]
|
|
16
|
+
keywords = [
|
|
17
|
+
"mcp",
|
|
18
|
+
"model-context-protocol",
|
|
19
|
+
"fruit-fly",
|
|
20
|
+
"mushroom-body",
|
|
21
|
+
"fly-lsh",
|
|
22
|
+
"associative-memory",
|
|
23
|
+
"code-reflex",
|
|
24
|
+
"ai-agents"
|
|
25
|
+
]
|
|
26
|
+
classifiers = [
|
|
27
|
+
"Development Status :: 4 - Beta",
|
|
28
|
+
"Intended Audience :: Developers",
|
|
29
|
+
"Intended Audience :: Science/Research",
|
|
30
|
+
"Operating System :: OS Independent",
|
|
31
|
+
"Programming Language :: Python :: 3",
|
|
32
|
+
"Programming Language :: Python :: 3.9",
|
|
33
|
+
"Programming Language :: Python :: 3.10",
|
|
34
|
+
"Programming Language :: Python :: 3.11",
|
|
35
|
+
"Programming Language :: Python :: 3.12",
|
|
36
|
+
"Programming Language :: Python :: 3.13",
|
|
37
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
38
|
+
"Topic :: Software Development :: Code Generators"
|
|
39
|
+
]
|
|
40
|
+
dependencies = [
|
|
41
|
+
"numpy>=1.21.0",
|
|
42
|
+
]
|
|
43
|
+
|
|
44
|
+
[project.optional-dependencies]
|
|
45
|
+
dev = [
|
|
46
|
+
"pytest>=7.0.0",
|
|
47
|
+
"pytest-asyncio>=0.20.0",
|
|
48
|
+
"pytest-cov>=4.0.0",
|
|
49
|
+
"build>=1.0.0",
|
|
50
|
+
"twine>=5.0.0"
|
|
51
|
+
]
|
|
52
|
+
|
|
53
|
+
[project.urls]
|
|
54
|
+
Homepage = "https://github.com/ericmaddox/calyx-mcp"
|
|
55
|
+
Repository = "https://github.com/ericmaddox/calyx-mcp"
|
|
56
|
+
Issues = "https://github.com/ericmaddox/calyx-mcp/issues"
|
|
57
|
+
Documentation = "https://github.com/ericmaddox/calyx-mcp#readme"
|
|
58
|
+
|
|
59
|
+
[project.scripts]
|
|
60
|
+
calyx-mcp = "calyx_mcp.server:main"
|
|
61
|
+
calyx-server = "calyx_mcp.server:main"
|
|
62
|
+
calyx-client = "calyx_mcp.client:main"
|
|
63
|
+
|
|
64
|
+
[tool.setuptools.packages.find]
|
|
65
|
+
where = ["src"]
|
|
66
|
+
|
|
67
|
+
[tool.setuptools.package-dir]
|
|
68
|
+
"" = "src"
|
|
69
|
+
|
|
70
|
+
[tool.pytest.ini_options]
|
|
71
|
+
testpaths = ["tests"]
|
|
72
|
+
asyncio_mode = "auto"
|
|
73
|
+
addopts = "-v --tb=short"
|
calyx_mcp-1.0.0/setup.py
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Calyx MCP: Neuro-Symbolic Associative Code Memory MCP Server
|
|
3
|
+
Powered by the Drosophila Mushroom Body & Fly-LSH sparse memory architecture.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
__version__ = "1.0.0"
|
|
7
|
+
__author__ = "Calyx Research Team"
|
|
8
|
+
|
|
9
|
+
from .config import CalyxConfig, get_default_config
|
|
10
|
+
from .hasher import FlyLSHHasher, KenyonSparseRepresentation
|
|
11
|
+
from .memory import MushroomBodyMemory
|
|
12
|
+
from .reflex import ReflexDecisionEngine, ReflexOutcome
|
|
13
|
+
from .tools import CalyxToolRegistry, get_tool_schemas
|
|
14
|
+
from .server import CalyxMCPServer, create_mcp_server
|
|
15
|
+
|
|
16
|
+
__all__ = [
|
|
17
|
+
"__version__",
|
|
18
|
+
"CalyxConfig",
|
|
19
|
+
"get_default_config",
|
|
20
|
+
"FlyLSHHasher",
|
|
21
|
+
"KenyonSparseRepresentation",
|
|
22
|
+
"MushroomBodyMemory",
|
|
23
|
+
"ReflexDecisionEngine",
|
|
24
|
+
"ReflexOutcome",
|
|
25
|
+
"CalyxToolRegistry",
|
|
26
|
+
"get_tool_schemas",
|
|
27
|
+
"CalyxMCPServer",
|
|
28
|
+
"create_mcp_server",
|
|
29
|
+
]
|