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

## Quick Start

```bash
# 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

```bash
# 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:

```json
{
  "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

```bash
# 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:

```bash
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