Neuron

✨ What is Neuron?

Neuron is a local-first MCP server that gives large language models long-term, associative memory. Point any MCP client at it (Claude, Cursor, OpenCode, VS Code, ChatGPT via a bridge, and more) and across every conversation Neuron builds a concept graph:

• every meaningful turn stores keywords with 384-dim vector embeddings and typed semantic links, organized into topic contexts with inheritance from parents;
• retrieval is associative, not just keyword matching — spreading activation, salience & recency ranking, and cross-context "drift" surface the right memory even without an exact hit;
• it runs local-first (one .db file, no daemon, no network) and can optionally back a shared team memory on Turso Cloud where several people write into the same brain at once.

In one line: stop re-explaining context to your AI every session. Neuron remembers.

🌟 Highlights

🧠 How it works

Neuron runs a simple two-step loop around every substantial turn:

        ┌─────────────────────────────────────────────────────────┐
        │  1. pre_turn(topic, keywords)                           │
        │     → loads the relevant slice of memory BEFORE you reply │
        └─────────────────────────────────────────────────────────┘
                              │  the model answers, now informed
                              ▼
        ┌─────────────────────────────────────────────────────────┐
        │  2. store_turn(keywords, links, facts…)                 │
        │     → saves what's NEW as concepts + typed links         │
        └─────────────────────────────────────────────────────────┘

Under the hood each concept is a node (keyword + embedding + salience + domain), each relationship a typed link (cause-effect, analogy, evolution, contrast, deepening, instance-of). Links that keep co-activating get reinforced; idle tangential ones get pruned; concepts you stop touching fade to dormant. Retrieval blends vector similarity, graph traversal and salience — so the model recalls what matters, not only what literally matches.

⚡ Quickstart

Option A — One-click installer (recommended)

The installer sets up Gray Matter + Neuron in a single venv, registers the gateway in your MCP clients, and creates a Desktop shortcut to the control center.

No Python? The installer bootstraps it (winget on Windows, brew/apt on Linux/macOS). Pre-built pyturso wheels are bundled — no C/Rust compiler needed.

Option B — pip (source checkout)

git clone https://github.com/recla93/Neuron.git
cd Neuron
pip install -e ".[dev]"        # editable install with test deps
pip install "neuron[cloud]"    # optional: Turso Cloud support

Option C — Standalone MCP (no gateway)

If you prefer Neuron without Gray Matter:

// ~/.config/opencode/opencode.json  (or your client's MCP config)
{
  "mcp": {
    "neuron": { "command": ["python", "-m", "neuron"], "type": "local" }
  }
}

Or register across all clients at once:

neuron register                # registers in Claude Desktop, Cursor, VS Code, etc.
neuron doctor                  # verify registrations, fix stale entries

📖 Full instructions, the manual path and troubleshooting live in INSTALL.md.

🔌 Mounting in an MCP client

🧠 Recommended: the Gray Matter gateway. Neuron ships alongside Gray Matter, an orchestrator that registers one server in your clients and runs Neuron (and NeuRAG) as warm managed workers — plus a combined gray_matter_pulse, context cache and cross-store bridges. One command does everything (register, hooks, plugins, manifest): gray-matter install. AI agents: follow INSTALL-AI.md. The table below is the standalone path.

Neuron is a local stdio MCP server — your client launches it as a subprocess. "Mounting" just means registering that launch command; on Windows the installer can do it for you.

Ready-made JSON snippets for every client live in clients/. Example — OpenCode (~/.config/opencode/opencode.json):

{
  "mcp": {
    "neuron": { "command": ["python", "-m", "neuron"], "type": "local" }
  }
}

💾 Storage: local, or shared on Turso Cloud

Neuron resolves its storage tier automatically, in this order:

1. Turso Cloud — when TURSO_DATABASE_URL + TURSO_AUTH_TOKEN are set. Memory is shared across machines and people; vector_distance_cos() runs server-side.
2. Local pyturso — embedded libSQL, native vector search, one local file (the default).
3. stdlib sqlite3 — last-resort fallback, Python-side cosine similarity.

One connection layer serves all three, so working solo vs. as a team is just a connection string — no code changes. Turn on the cloud in one step:

pip install "neuron[cloud]"
python scripts/connect_turso.py     # prompts, live-tests the connection, saves to .env

👥 Running a whole team on one brain? See the Team guide.

🕰️ Graph Visualizer

Neuron ships an interactive, self-contained HTML visualizer — launch it from neuron manage (option 4, Graph visualizer) or python scripts/generate_graph_html.py. It reads through Neuron's own engine (so it sees the cloud too) and gives you:

salience-sized, domain-colored nodes · Hebbian-thickened edges · drift-link styling · dormant fading · neighborhood highlight · search · domain/type filters · an insights panel (hubs, most-salient, dormant, strongest synapses, cross-context bridges) · a Replay slider that animates your memory growing turn by turn · and an Obsidian-style 🎨 appearance editor.

🧰 MCP tools

🏗️ Architecture

neuron/
├── src/neuron/
│   ├── server.py        # MCP server: ~22 tools, handshakes, skill delivery
│   ├── models.py        # Dataclasses: Node, Link, Graph
│   ├── db.py            # 3-tier DB: Turso Cloud → pyturso → sqlite3
│   ├── registry.py      # Multi-context graph registry (java/spring, python/django)
│   ├── extraction.py    # SemanticExtractor: keyword/topic/domain (0 LLM tokens)
│   ├── search.py        # Hybrid vector search (cosine + salience + recency)
│   ├── stimulus.py      # Spreading activation, flash, auto-link
│   ├── curation.py      # Quality gate: drops verbs, paths, phrases at write time
│   ├── funnel.py        # Skill delivery: signpost + packaged skill files
│   ├── clients.py       # MCP client registration (7 clients, TOML/JSON/JSONC)
│   ├── connect.py       # Turso Cloud onboarding (connect → probe → save)
│   ├── config.py        # Centralized paths & slug (SSOT, no circular imports)
│   ├── console.py       # Dev Console: one-shot or watch mode graph snapshot
│   └── skills/          # Packaged skill files (playbook, curated memory)
├── tests/               # Test suite (unit tests, mocked — no network)
└── knowledge/           # Seed knowledge DB (base_knowledge.db)

Key design decisions:

• Multi-context graph: contexts form a tree (java → java/spring) with inheritance.
• Curation gate: bad keywords (verbs, paths, phrases) are dropped or remapped at write time.
• 3-tier DB: Turso Cloud → pyturso (native vector SQL) → sqlite3 (stdlib fallback).
• 0-token extraction: keyword/topic/domain extraction via regex + heuristics, no LLM calls.
• Spreading activation: BFS on the graph to propagate importance from seed nodes.

🛠️ Development

pip install -e ".[dev]"
python -m pytest tests/ -v        # unit tests (fastembed/mcp/turso mocked — no network)
python -m build                   # wheel + sdist (CI verifies this on every push)

Self-checks (no install needed):

python -c "from neuron.embedder import demo; demo()"; echo "OK"   # embedder routing
python scripts/neuron_console.py                                    # graph health snapshot
python scripts/neuron_console.py --watch                           # live monitoring

Environment tuning (for dev/experiments):

NS_GRAPHS_DIR=/tmp/neuron-test python -m neuron   # isolated store
NEURON_SLUG=neuron5 python -m neuron               # side-by-side with another install

Architecture, the DB layer, per-client config and cloud/bridge internals are documented in docs/DEVELOPER.md; release & CI mechanics in docs/RELEASE_PLAN.md. Requires Python 3.10–3.14.

🗺️ Documentation map

👤 Author

Neuron is designed and built by Claudio Costantino.

Found Neuron useful? A ⭐ on the repo genuinely helps.

🧩 Part of the Gray Matter suite

Three MCP servers that work alone and work better together. Install any one of them and it can pull in the others; the gateway then serves all three through a single connector, so your client registers once.

Whoever is installed first owns the session handshake: the gateway when it is present, otherwise the standalone tool — so the model is never told to call tools that are not there.

📜 License

PolyForm Noncommercial License 1.0.0 — free for noncommercial use. See LICENSE.