Neuron - "Synapse"
Neuron is an MCP server that gives LLMs persistent, associative semantic memory across conversations.
Run the core memory loop:
pre_turnbefore replying to load relevant context, thenstore_turnafter replying to persist curated facts.Store rich memories with topic, keywords, domain, intent, sentiment, entities, links, tags, references, and a compact episode fact.
Retrieve existing knowledge via
get_context,pre_turn,find_candidates, andvector_search.Give feedback with
confirmto boost concepts that were actually useful.Manage topic contexts: switch, list, create context paths, and use context inheritance.
Inspect graph health and contents with
status,summary, andforgotten.Clean and maintain memory with
merge,consolidate,prune,dedup,flash,reset, andexport.Extract or auto-save memories from text using
extractandauto.Access guidance through
helpandskillplaybooks.
Provides persistent semantic memory for LLMs using Turso's native vector search to store and retrieve concepts with 256-dimensional embeddings.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Neuron - "Synapse" get context from last session about neural networks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
β¨ 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
.dbfile, 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 |
π₯ | 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 ( |
π§ 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
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.
Platform | Action |
Windows | Double-click |
macOS | Double-click |
Linux |
|
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 supportOption 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: followINSTALL-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 | restart the client |
Claude Code, VS Code, Zed, Windsurf, Cline/Roocode, Continue, Cody, Amazon Q | add the launch command ( | 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:
Turso Cloud β when
TURSO_DATABASE_URL+TURSO_AUTH_TOKENare set. Memory is shared across machines and people;vector_distance_cos()runs server-side.Local pyturso β embedded libSQL, native vector search, one local file (the default).
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 |
| Before replying β the facts relevant to the topic, each with its |
| After replying β save 0-3 facts; |
| A recalled fact helped ( |
Tool | Description |
| Graph state Β· top nodes and recent links |
| Switch / list domain contexts (e.g. |
| One line per command Β· full text of a playbook on demand |
Tool | Description |
| Related nodes/links; |
| Similar existing keywords Β· semantic search over concepts |
| Concepts idle for N turns ( |
| Negative feedback: lower salience and trust of misleading associations |
| Absorb duplicates into one Β· merge near-duplicates by cosine Β· toggle keyword dedup |
| Standalone extraction Β· extract-and-save in one call |
| Force-prune expired links Β· toggle semantic flashbacks |
| Self-model: strongest concepts, recent growth, weakest areas |
| Export the graph as JSON Β· clear it (requires |
ποΈ 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 monitoringEnvironment 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 installArchitecture, 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 |
Every install path (Windows one-click β manual β source) + troubleshooting | |
Automated install+register instructions for AI agents | |
Architecture, memory dynamics, DB layer, per-client config | |
Running a shared team brain on Turso Cloud | |
Exposing Neuron over HTTP for ChatGPT / remote connectors | |
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 toolsautoA
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).
vector_searchB
Semantic vector search. Find similar keywords via Turso vector_distance_cos or a Python cosine fallback (384-dim fastembed embeddings, NS_EMBED_MODEL).
Inputs: keywords (required), top_n, context.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 22 tools
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.
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.
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.
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
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Shared cross-LLM long-term memory over MCP: semantic recall, sessions, and media (pgvector).
Persistent, portable memory for AI assistants β your private memory graph, from any MCP client.
An MCP memory server. One memory your agents share β across models, devices and apps.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn 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
- AlicenseBqualityDmaintenanceAn 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.55 npmMIT
- AlicenseNot gradedqualityDmaintenancePersistent semantic memory server for AI assistants via MCP, enabling long-term context retention and semantic search across conversations.12MIT
- AlicenseNot gradedqualityDmaintenanceOpen-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.51MIT