Open Neural Substrate

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.

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