Skip to main content
Glama


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


Related MCP server: Memory MCP

🌟 Highlights

Feature

What it means for you

🧩

Associative memory

Hebbian link reinforcement, spreading activation, salience/recency ranking β€” memories that fire together wire together.

🌐

Any MCP client

Claude Desktop/Code, Cursor, OpenCode, VS Code, Windsurf, Zed, Cline/Roocode, Continue, Cody, Amazon Q β€” plus ChatGPT via an HTTP bridge.

πŸ’Ύ

Local-first, zero setup

Embedded libSQL with native vector_distance_cos(). One file. No server, no port, no cloud required.

πŸ‘₯

Shared team brain (optional)

Flip on Turso Cloud and everyone writes into one graph β€” atomic, concurrent, no one's save clobbers another's.

🎯

Quality at the door

A curation gate drops filler, folds duplicates and canonicalizes links, so the graph stays clean instead of bloating.

πŸ“–

Typed facts

The unit of memory is a fact β€” a decision, a fix, an idea, who you are, how you work β€” one sentence with its why, indexed by concepts. Append-only: a newer fact supersedes an older one, nothing is evicted.

πŸ•°οΈ

See your memory

The control center's Grafi view shows concepts, facts, the knowledge base and the bridges as one interactive graph; a self-contained HTML visualizer replays the memory turn by turn.

🩺

Batteries-included tooling

Cross-platform CLI (neuron register / doctor / console), the shared web control center (neuron gui), and a full test suite.


🧠 How it works

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

        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
        β”‚  1. pre_turn(topic)                                     β”‚
        β”‚     β†’ loads the facts that matter BEFORE you reply      β”‚
        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                              β”‚  the model answers, now informed
                              β–Ό
        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
        β”‚  2. store_turn(facts=[{kind, text, concepts}])          β”‚
        β”‚     β†’ saves what is worth not repeating, as facts       β”‚
        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Each fact is one sentence with its why and a kind (progress, decision, fix, fact, idea, user, habit); a newer fact can supersede an older one, which stays on disk but leaves recall. Facts are indexed by concepts: 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

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.

Platform

Action

Windows

Double-click install.cmd (or .\install.ps1 from a terminal)

macOS

Double-click install.command (or sh install.sh from a terminal)

Linux

sh install.sh from a terminal

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/GrayMatterEnvironment.git
cd GrayMatterEnvironment/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.

Client

How to mount

Notes

Claude Desktop, Cursor, OpenCode

auto-registered by install.ps1 (or neuron register)

restart the client

Claude Code, VS Code, Zed, Windsurf, Cline/Roocode, Continue, Cody, Amazon Q

add the launch command (python -m neuron)

local stdio

ChatGPT / OpenAI

via an HTTP bridge β€” see the Bridge guide

Developer Mode, paid plans

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]"
neuron connect                      # prompts, live-tests the connection, saves to .env

πŸ‘₯ Running a whole team on one brain? See the Team guide.


πŸ•°οΈ Graph Visualizer

The everyday view is the control center: neuron gui (or gray-matter gui) β†’ Grafi shows Neuron's concepts and facts, NeuRAG's nodes and the bridges together; click a concept to read its active facts, drag from a concept to a knowledge node to create a bridge.

From a source checkout there is also a self-contained HTML visualizer: neuron manage --visualize 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

Tool names are bare (pre_turn, not neuron_pre_turn). MCP clients prefix them with the server name (mcp__neuron__pre_turn, or mcp__gray-matter__pre_turn behind the gateway). Admin tools are callable but not announced unless NEURON_TOOLS=all.

Tool

Description

pre_turn(topic)

Before replying β€” the facts relevant to the topic, each with its #id, plus the stimulus

store_turn(facts=[{kind, text, concepts}])

After replying β€” save 0-3 facts; supersedes=<#id> replaces an older one; links and references optional

confirm(facts=[#id])

A recalled fact helped (keywords boosts concepts; negative confidence refutes)

Tool

Description

status / summary

Graph state Β· top nodes and recent links

switch_context / list_contexts

Switch / list domain contexts (e.g. java/spring)

help / skill(name)

One line per command Β· full text of a playbook on demand

Tool

Description

get_context(topic, ...)

Related nodes/links; format=compact for injection (pre_turn covers it in the loop)

find_candidates(keywords) / vector_search(keywords)

Similar existing keywords Β· semantic search over concepts

forgotten / recall

Concepts idle for N turns (facts=true: dormant facts, what a flash shows) Β· bring an archived node back

dismiss(keywords)

Negative feedback: lower salience and trust of misleading associations

merge(canonical, aliases) / consolidate / dedup

Absorb duplicates into one Β· merge near-duplicates by cosine Β· toggle keyword dedup

extract(text) / auto(text)

Standalone extraction Β· extract-and-save in one call

prune / flash

Force-prune expired links Β· toggle semantic flashbacks

introspect

Self-model: strongest concepts, recent growth, weakest areas

export / reset

Export the graph as JSON Β· clear it (requires confirm=true)


πŸ—οΈ 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)

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/RELEASING.md. Requires Python 3.10–3.14.


πŸ—ΊοΈ Documentation map

Doc

What's in it

INSTALL.md

Every install path (Windows one-click β†’ manual β†’ source) + troubleshooting

INSTALL-AI.md

Automated install+register instructions for AI agents

docs/DEVELOPER.md

Architecture, memory dynamics, DB layer, per-client config

docs/TEAM.md

Running a shared team brain on Turso Cloud

docs/BRIDGE.md

Exposing Neuron over HTTP for ChatGPT / remote connectors

CHANGELOG.md

The full v5 "Synapse" story, release by release


πŸ‘€ 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.

Project

What it does

🧠 Neuron ← you are here

Semantic memory β€” concepts, links, salience. It learns.

πŸ“š NeuRAG

Hierarchical knowledge vault β€” nodes, chunks, triggers. It keeps.

⚑ Gray Matter

MCP gateway β€” one connector, warm workers, cross-store bridges.

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.

Available Tools

22 tools
autoA

POST fallback (0-token): one-shot extract + topic-shift + auto-link + save. Prefer a curated store_turn when you can pick the concepts yourself; use auto only for throwaway turns.

Inputs: text (required), context.

confirmA

Feedback signal: confirm that context retrieved from the graph was useful. Boosts salience of specified keywords so they surface more prominently in future get_context calls. Call this when retrieved context directly influenced your response. Skipping is safe β€” it only affects future retrieval quality.

Inputs: keywords (required), boost, context.

consolidateA

Consolidate the graph: merge near-duplicate concepts (cosine) and archive low-salience orphans to a recoverable _graveyard. Keeps the memory clean; safe to run periodically.

Inputs: merge, context, drop_orphans, sim_threshold.

dedupC

Toggle keyword deduplication

Inputs: no named parameters.

exportC

Export the complete graph as JSON

Inputs: context.

extractA

Automatic semantic extraction from text: keyword, topic, domain, intent, sentiment, entities. Heuristic (0 token) β€” no LLM extraction.

Inputs: text (required), context.

find_candidatesA

Screening: find existing similar keywords (vector search). Call BEFORE store_turn.

Inputs: keywords (required), top_n, context.

flashB

Toggle semantic flashbacks

Inputs: no named parameters.

forgottenA

Find keywords not touched in N turns (decaying salience). Useful for rediscovering lost concepts.

Inputs: top_n, context, threshold.

get_contextA

Retrieve related nodes and links for a topic/keyword β€” what the memory already knows. Call BEFORE answering when a question may have prior context worth recalling. For the normal start-of-turn load, prefer pre_turn (one shot: status + compact context).

Inputs: topic (required), depth, format, context, +2 more.

helpA

Show every Neuron command (one line each) plus how to use Neuron well. Call once at the start if unsure; full playbook: call skill(name='playbook').

Inputs: no named parameters.

list_contextsB

List all available contexts with metadata.

Inputs: parent.

mergeA

Merge duplicate or near-duplicate nodes. Moves all links from aliases into canonical, sums salience, then deletes the aliases. Use after find_candidates reveals near-duplicates (e.g. 'spring boot' / 'Spring Boot' / 'Spring Boot 3.2').

Inputs: aliases (required), canonical (required), context.

pre_turnA

MEMORY LOOP β€” STEP 1 (before replying). Call this FIRST on any substantive turn to load relevant past context in one shot (status + get_context in compact form). Fold what it returns silently into your answer; do not announce it. Then reply, then call store_turn (step 2). Skip only on trivial turns or when the graph is empty. Ideal for clients without automatic context-injection hooks.

Inputs: topic (required), keywords, max_tokens.

pruneC

Force prune inactive tangential links

Inputs: context.

resetC

Reset the graph and start over

Inputs: context.

skillA

Return the FULL text of a Neuron skill/playbook on demand β€” token-cheap, fetch it only when you need the details. Use after the compact opener to load the complete workflow or curation rules.

Inputs: name.

statusA

Current graph state: nodes, links, health, configuration. Safe first call to see if the memory holds anything. New to Neuron? The core workflow is a 2-step loop each substantive turn: pre_turn (before) then store_turn (after); call help or skill(name='playbook') for the full playbook.

Inputs: no named parameters.

store_turnA

MEMORY LOOP β€” STEP 2 (after replying). Call this AFTER you answer a substantive turn, to persist what is new into long-term memory. Curate for a clean graph: topic = 3-5 words; keywords = 3-5 CONCEPT nouns / entities / tech (never verbs or filler like 'use', 'make'); links = typed edges between keywords (never link a keyword to itself). This is the preferred way to save β€” cleaner than auto(). Skip on trivial turns (greetings, acknowledgements, yes/no).

Inputs: topic (required), domain (required), intent (required), keywords (required), +7 more.

summaryB

Textual graph summary: top keywords, recent links, health, forgotten concepts

Inputs: no named parameters.

switch_contextA

Switch active context (creates if new). E.g. 'java/spring', 'python/django'.

Inputs: context (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 22 tools

    Disambiguation3/5

    There are overlapping purposes among retrieval (get_context, pre_turn, vector_search, find_candidates) and maintenance commands (consolidate, merge, prune), but detailed usage notes help an agent choose. Still, find_candidates vs vector_search and consolidate vs merge are easy to confuse.

    Naming Consistency3/5

    The dominant pattern is lowercase snake_case with verb_noun commands like get_context and store_turn, but names like auto, skill, status, forgotten, dedup, and flash break the convention. The style is readable, but not consistently predictable.

    Tool Count3/5

    22 tools is on the heavy side for a focused memory server, with several that could be merged or hidden behind the core loop (e.g., vector_search/find_candidates, consolidate/merge, status/summary). It is not overwhelmingly large, but it feels padded.

    Completeness4/5

    The core lifecycle is covered well: pre-turn retrieval, post-turn storage, context switching, export, and cleanup. Notable gaps include no explicit restore-from-_graveyard tool and no way to delete or edit a single node/link directly.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides persistent semantic memory backed by PostgreSQL and pgvector for storing and searching thoughts via vector embeddings. It enables dimensional organization, conflict detection, and historical tracking of facts, decisions, and observations.
      ISC
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that provides AI assistants with persistent, semantic memory using Turso for storage and OpenAI for vector search. It enables natural language operations to store, retrieve, and refine information with automatic duplicate detection and quality validation.
      5
      5 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Persistent semantic memory server for AI assistants via MCP, enabling long-term context retention and semantic search across conversations.
      12
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Open-source MCP server that gives any LLM long-term memory using a knowledge graph and vector search hybrid. It stores entities, observations, and relationships, enabling semantic recall across sessions with automatic clustering and fail-loud infrastructure.
      51
      MIT