Skip to main content
Glama
Sign In
open-neural-substrate

open-neural-substrate

by pedroknigge
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Open Neural Substrate (ONS)

A persistent, human-readable knowledge layer that acts as a second brain for any software.

What Is This?

ONS stores your knowledge — customers, tasks, notes, concepts, decisions — as neurons: structured records with natural-language content, embedding vectors, and weighted connections to other neurons.

Any software can query and update your knowledge through a local API:

  • Claude connects via MCP (Model Context Protocol)

  • Codex / GPT connects via function calling

  • Scripts, automations, apps connect via plain HTTP

The substrate runs as a persistent local service on port 52830, starting at login. A background consolidation process — inspired by how brains consolidate memory during sleep — continuously strengthens useful connections, surfaces implicit clusters, prunes stale links, and refreshes embeddings.

Your neurons are like open weights for your mind: fully human-readable, machine-queryable, and owned entirely by you.

Related MCP server: Loc Knowledge Graph Memory Server

Quick Start

# Clone and setup
git clone <repo-url> ons && cd ons
make setup

# Start the server
make run

# In another terminal — create your first neuron
curl -X POST http://localhost:52830/upsert \
  -H "Content-Type: application/json" \
  -d '{
    "type": "knowledge",
    "title": "ONS Design Principles",
    "content": "Every piece of knowledge is one neuron. Connections are first-class. All edits are local.",
    "metadata": {"tags": ["architecture", "core"]}
  }'

# Query it back
curl -X POST http://localhost:52830/query \
  -H "Content-Type: application/json" \
  -d '{"text": "design principles of the system"}'

Import Existing Knowledge

# Import a folder of markdown notes
make import-md DIR=~/notes

# Import JSON data (customers, tasks, etc.)
make import-json FILE=~/customers.json

# Export everything for backup
make export DIR=./backup

Connect Claude (MCP)

Add to your Claude Desktop or Claude Code config:

{
  "mcpServers": {
    "ons": {
      "url": "http://localhost:52830/mcp",
      "name": "open-neural-substrate"
    }
  }
}

Claude will now have access to your entire knowledge substrate as native tools.

Run as a Persistent Service

# Linux (systemd user service)
make install-service

# macOS (LaunchAgent)
make install-service

# Verify it's running
curl http://localhost:52830/health

The server starts at login and stays alive. Consolidation runs automatically during idle periods.

How It Works

 Neurons (knowledge atoms)     Edges (connections)        Embeddings (search vectors)
 ┌──────────────────────┐     ┌─────────────────────┐    ┌──────────────────────────┐
 │ id: neu_4f8a2c       │     │ source → target      │    │ neuron + model → vector  │
 │ type: customer       │────▶│ type: has_task        │    │ cached per-model         │
 │ title: Acme Corp     │     │ strength: 0.92        │    │ refreshed on change      │
 │ content: (markdown)  │     │ created_by: human     │    │ 384-dim default          │
 │ version: 7           │     └─────────────────────┘    └──────────────────────────┘
 └──────────────────────┘
          │
          ▼  (during idle / sleep)
 ┌──────────────────────────────────────────────────────┐
 │ Consolidation Cycle                                   │
 │ 1. Replay & strengthen used paths                     │
 │ 2. Cluster frequently co-retrieved neurons            │
 │ 3. Decay unused connections                           │
 │ 4. Re-embed stale neurons                             │
 └──────────────────────────────────────────────────────┘

API Reference

Endpoint

Method

Description

/query

POST

Semantic search + relational filtering. Returns ranked neurons.

/upsert

POST

Create or update a neuron. Auto-embeds.

/rewire

POST

Add, remove, or adjust connections.

/delete/{id}

DELETE

Soft-delete with version snapshot.

/health

GET

Service status + neuron count.

/consolidation/status

GET

Last run info + pending proposals.

/consolidation/trigger

POST

Manually trigger a consolidation cycle.

Configuration

Copy .env.example to .env and adjust:

ONS_PORT=52830                  # Server port
ONS_DB_PATH=~/.ons/brain.db    # Database location
ONS_EMBEDDER=local              # local | openai | anthropic
ONS_EMBED_MODEL=all-MiniLM-L6-v2
ONS_IDLE_MINUTES=30             # Idle time before consolidation
ONS_LOG_LEVEL=info

License

MIT

Tool Schema Changelog

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

Loading tool schema changelog…

    This server cannot be deployed

    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Loc Knowledge Graph Memory

      Myangsun
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to remember information about users across conversations by storing and retrieving data as entities, relations, and observations in a persistent local knowledge graph.
      315,072 npm
      MIT

    • Fuzzy Memory MCP Server

      flrngel
      A
      license
      A
      quality
      D
      maintenance
      Enables Claude to maintain persistent memory across conversations using a local knowledge graph with fuzzy search capabilities, allowing it to remember and recall information about users, relationships, and context.
      9
      MIT