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

🪟 Windows — one click

Double-click NeuronInstaller.exe in the project folder. It installs Neuron and creates a Neuron — Control Center shortcut on the Desktop. From then on, double-click that shortcut: the GUI is the single front door for setup, registration, deploy/update, Turso, Bridge + Tunnel, graph maintenance, vault import and live logs. No terminal is needed for normal use.

.\NeuronInstaller.exe

Installs into a dedicated venv using a pre-built pyturso wheel from .\vendor (Python 3.10–3.14), so no C/Rust compiler is needed.

🍎 macOS / 🐧 Linux

pyturso ships prebuilt wheels on PyPI for macOS/Linux, so a plain install just works:

python3 -m venv .venv && source .venv/bin/activate
pip install neuron-<version>-py3-none-any.whl     # from the GitHub Release
python -m neuron                                   # starts the MCP server on stdio

From a source checkout: pip install ".[dev]".

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

🔌 Mounting in an MCP client

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

🛠️ 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)

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.

📜 License

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