Welcome

Cognitum Seed is a portable edge intelligence appliance. It provides an on-device vector store in RVF binary format, real-time sensor processing with drift detection, thermal-aware DVFS management, cryptographic custody with Ed25519 signing, and a cognitive container for spectral graph analysis — all accessible through 90 HTTPS API endpoints with per-client bearer token authentication.

Framework

The seed exposes its capabilities as a browser-addressable MCP surface and a curated Cog Store. You build your own applications on top using Claude or Claude Code — the seed itself stays focused on the substrate.

Open the Framework page for the live identity card, MCP connection helper, ESP32 firmware download, mesh + OTA status, and embedded WASM persistence (rvlite + rulake) demos.

What's there

• Identity — this seed's device_id, firmware version, paired flag, public key. Apps should partition client-side state by device_id.
• MCP connection — copy the URL (POST /mcp) into your Claude / Claude Code session via claude mcp add. The Test connection button issues a tools/list and reports the count of cog and framework tools.
• Claude Code plugin (@cognitum/cog-dev) — slash commands, skills, and subagents for the cog dev/test/deploy/ops loop. Scaffold lives at tools/cog-dev-plugin/ in the seed repo.
• ESP32 firmware — current Cognitum-pinned distribution URL (also reachable from the Cog Store wizard).
• Mesh + OTA status — auto-mesh state, peer count, password set; firmware slot, version, boot count.
• Persistence (WASM) — rvlite (SQL/SPARQL/Cypher vector DB, IndexedDB-backed) and rulake (exact brute-force kNN + SHAKE-256 bundle witnesses). Both served from /static/wasm/; user-built UIs import them directly.
• Settings — default sensor source for new cogs, pairing window, auto-update flag. Persisted via GET/PUT /api/v1/framework/settings.

MCP tool families on the seed

• seed.cogs.* — list, available, install, start, stop, logs, config_get, config_set, console, uninstall (Public reads; Paired writes)
• seed.framework.* — identity, firmware_status, mesh_status, esp32_flash_url (Public)
• seed.sensor.snapshot, seed.sensor.config — sensor stream + pipeline config (Paired)
• seed.rvf.query — kNN over the on-device RVF store (Paired)

Resources (cognitum:// URI scheme)

• cognitum://registry — full 88-cog catalog
• cognitum://identity — device UUID, key, paired flag
• cognitum://sensor/stream/snapshot — latest sensor frame
• cognitum://rvf/witness/head — current witness chain head + length
• cognitum://firmware/esp32/latest — ESP32 firmware metadata + URL
• cognitum://cogs/{id}/manifest and cognitum://cogs/{id}/logs/recent — per-cog manifest and recent logs

Quick connect

npx -y @cognitum/cog-dev mcp connect --seed http://169.254.42.1
# or, with auto-discovery (USB / mDNS / configured WiFi):
npx -y @cognitum/cog-dev mcp connect --auto-discover

Wraps claude mcp add with seed auto-discovery and bundled MCP transport. Or open /framework and click Test connection — the page issues a real tools/list against this seed and shows the count.

Quick Start

Get up and running with your Cognitum Seed.

1. Plug in via USB data port (not the power port). Three interfaces appear: a COGNITUM USB drive, a USB Ethernet adapter, and mDNS at cognitum.local.
2. Open the guide at http://169.254.42.1/guide (HTTP — works immediately on first boot).
3. Pair your client to unlock write endpoints. Go to the Pairing section and click “Pair”. This issues a bearer token and saves it to your browser.
4. Connect WiFi — enter your SSID and password in the WiFi Setup section. Once connected, the seed automatically provisions a CA-signed TLS certificate (~2 minutes).
5. Install the trust certificate (one-time per computer). Open the COGNITUM USB drive → trust/ folder → run the installer for your OS:
   • Windows: double-click install-trust.bat
   • macOS: double-click install-trust.command
   • Linux: bash install-trust.sh
6. Reboot the seed (unplug/replug USB). HTTPS is now active — open https://169.254.42.1:8443/guide with no browser warnings.
7. Ingest sample data to test the store. Click POST /api/v1/demo/ingest-sample — this adds 100 random 8-dim vectors. Then try a k-NN query with POST /api/v1/store/query.
8. Explore endpoints — 100+ endpoints cover vectors, sensors, thermal governor, temporal coherence, cognitive container, custody, and more. Read endpoints work without authentication; write endpoints require a bearer token.

curl -sk -X POST https://169.254.42.1:8443/api/v1/demo/ingest-sample

Connect to Your Seed

The Seed provides three connection methods. USB is primary (no network config required); WiFi is secondary for wireless access.

USB Connection (recommended)

Plug the Seed into your computer via the USB data port (not the power-only port). Three interfaces appear:

curl -sk https://169.254.42.1:8443/api/v1/status

SSH Access

# Via USB
ssh genesis@169.254.42.1

# Via mDNS
ssh genesis@cognitum.local

# Via WiFi (if configured)
ssh genesis@192.168.1.x

Cross-Platform Compatibility

Pairing & Authentication (ADR-048)

Pairing authorizes your client to use write endpoints (ingest, delete, config updates, OTA, actuator fire). Read-only endpoints work without pairing. Each client receives a unique bearer token during pairing that must be included in all write requests.

How It Works

1. Open pairing window — POST /api/v1/pair/window opens a 30-second window. Accepted from: USB (169.254.x.x), Setup WiFi AP (192.168.4.x), localhost, or any LAN client when the device is unpaired (ADR-086).
2. Pair — POST /api/v1/pair with {"client_name":"my-laptop"}. The server generates a 256-bit random token and returns it. The server stores only the SHA-256 hash of the token.
3. Save the token — This guide saves it to localStorage automatically. CLI users must save the token manually; it is shown only once.
4. Authenticate — Include Authorization: Bearer <token> on every write request. The guide does this automatically.

# Step 1: Open pairing window (USB, Setup WiFi, or LAN when unpaired)
curl -s -X POST http://cognitum.local/api/v1/pair/window

# Step 2: Pair and receive token
curl -s -X POST http://cognitum.local/api/v1/pair \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"my-laptop"}'

# Step 3: Use token in subsequent requests
curl -s -X POST http://cognitum.local/api/v1/store/ingest \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{"vectors":[[0,[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8]]]}'

Paired Clients

View all clients currently paired with this Seed.

curl -sk https://169.254.42.1:8443/api/v1/pair/clients

RVF Binary Format

The Seed stores all vectors in RVF (RuVector Format), a compact append-only binary format designed for embedded devices. RVF files are binary-compatible with the parent ruvector workspace — you can generate .rvf files on your workstation and import them into the Seed, or export the Seed's store for analysis on your computer.

File Structure

An RVF file is a sequential log of entries. Each entry has a fixed-size header followed by variable-length data:

Key Properties

• Append-only — deletions are tombstones, not erasures. The file grows monotonically until compaction.
• Content-addressed IDs — vector IDs are derived from SHA-256 of the vector data (truncated to u64). Duplicate vectors get the same ID automatically.
• Witness entries — every write appends a witness entry with a SHA-256 hash linking to the previous entry, forming a tamper-evident chain.
• Compaction — POST /api/v1/store/compact rewrites the file excluding deleted vectors, reclaiming disk space.
• Pre-computed norms — L2 norms are cached per vector to accelerate cosine similarity queries (dot product + 1 division instead of 2 square roots per candidate).

Storage Budget

The Seed has 512 MB RAM. Keep total vectors * dimension * 4 bytes under ~100 MB to leave room for the sensor pipeline, kNN graph, and cognitive container.

Vector Store

The store holds vectors in RVF format with content-addressed IDs. It supports k-nearest-neighbor queries using cosine similarity, batch ingest with deduplication, soft-delete with compaction, and a kNN graph for structural analysis.

k-NN Query

Query returns the k most similar vectors by cosine similarity. Uses a BinaryHeap with O(n log k) complexity and early distance pruning. Supports multiple distance metrics via the metric field: cosine (default), l2, or dot.

curl -sk -X POST https://169.254.42.1:8443/api/v1/store/query \
  -H 'Content-Type: application/json' \
  -d '{"vector":[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8],"k":5}'

# With metadata filter and metric
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/query \
  -d '{"vector":[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8],"k":5,"metric":"l2","filter":{"field_id":0,"op":"eq","value":"sensor"}}'

kNN Graph

The optimizer loop rebuilds a k=16 nearest-neighbor graph every 10 seconds (when changes are detected). The graph drives boundary analysis (Stoer-Wagner min-cut) which produces a fragility score from 0.0 (solid) to 1.0 (fragile). Fragility directly controls the thermal governor's demand level.

Witness Chain

Every write operation (ingest, delete, compact) appends a tamper-evident entry to the witness chain. Each entry contains a SHA-256 hash that links to the previous entry, forming a cryptographic audit trail. If any historical entry is modified, the chain verification fails at the tampered link.

What Gets Witnessed

curl -sk -X POST https://169.254.42.1:8443/api/v1/witness/verify

Custody & Ed25519 Signing

Each Seed has a unique Ed25519 keypair derived from its device ID. The private key never leaves the device. You can sign arbitrary data and verify signatures, enabling cryptographic proof that data originated from a specific Seed.

Signing Workflow

1. Sign data with POST /api/v1/custody/sign — returns hex-encoded Ed25519 signature + public key.
2. Verify with POST /api/v1/custody/verify — pass the data, signature, and optionally a public key. Uses the device's own key if omitted.
3. Attestation with GET /api/v1/custody/attestation — returns a signed attestation proving the device booted with its identity, including epoch, vector count, and witness head.

curl -sk -X POST https://169.254.42.1:8443/api/v1/custody/sign \
  -H 'Content-Type: application/json' -d '{"data":"hello world"}'

MCP Proxy (ADR-047)

The Model Context Protocol proxy exposes the Seed's capabilities to AI assistants (Claude, GPT, etc.) via JSON-RPC 2.0 over Streamable HTTP at /mcp. 12 tools across 6 groups, 4 resources, 3 guided prompts, and a default-deny policy engine.

Architecture

Tool Scopes

Set via capabilities.experimental.cognitum.toolScope in the initialize request.

Auth Classes

Tool Groups (21)

Connection Flow

# 1. Initialize the MCP session (default scope = 24 tools)
curl -s -X POST http://169.254.42.1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-11-25","clientInfo":{"name":"my-client","version":"1.0"},"capabilities":{"experimental":{"cognitum":{"toolScope":"default"}}}}}'

# 2. Send initialized notification
curl -s -X POST http://169.254.42.1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 3. List available tools
curl -s -X POST http://169.254.42.1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2,"params":{}}'

# 4. Call a tool
curl -s -X POST http://169.254.42.1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","id":3,"params":{"name":"seed.device.status","arguments":{}}}'

Try It — MCP Initialize + Status

Try It — MCP Tools List

Try It — MCP Query Vectors

Resources & Prompts

Resources (read via resources/read):

Prompts (expand via prompts/get):

Batch Requests

Send multiple JSON-RPC calls in a single HTTP POST as a JSON array. Notifications (no id) return HTTP 202.

# Batch: initialize + list tools in one request
curl -s -X POST http://169.254.42.1/mcp \
  -H "Content-Type: application/json" \
  -d '[
  {"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-11-25","clientInfo":{"name":"test"}}},
  {"jsonrpc":"2.0","method":"notifications/initialized"},
  {"jsonrpc":"2.0","method":"tools/list","id":2,"params":{}}
]'

{
  "mcpServers": {
    "cognitum-seed": {
      "url": "http://169.254.42.1/mcp",
      "transport": "streamable-http"
    }
  }
}

# Step 1: Initialize (get server capabilities)
POST /mcp  {"jsonrpc":"2.0","method":"initialize","id":1,
  "params":{"protocolVersion":"2025-11-25",
    "clientInfo":{"name":"my-app","version":"1.0"}}}

# Step 2: Confirm initialization
POST /mcp  {"jsonrpc":"2.0","method":"notifications/initialized"}

# Step 3: Use tools, resources, or prompts
POST /mcp  {"jsonrpc":"2.0","method":"tools/call","id":2,
  "params":{"name":"seed.status.get","arguments":{}}}

# User: "Search the seed for vectors similar to [0.1, 0.2, ...]"
# Claude calls: seed.memory.query with {"query":[0.1,0.2,...], "k":10}
# User: "What's the device status?"
# Claude calls: seed.status.get
# User: "Diagnose this seed"
# Claude uses prompt: seed_diagnose

ssh -L 8444:127.0.0.1:8444 genesis@cognitum.local

Sensor Subsystem (ADR-041)

The sensor loop samples 6 channels at 10 Hz, producing 45-dimensional embeddings. The pipeline flows: raw samples → sliding window → feature extraction (5 stats per channel + pairwise cross-correlations) → HD gate (1024-bit hyperdimensional hash for anomaly screening) → drift detection (Page-Hinkley + ADWIN + Reservoir ESN) → reflex arc (sensor-to-actuator rules).

Embedding Dimensions

For C channels, the embedding has 5C + C*(C-1)/2 dimensions:

Drift Detection

Three independent detectors run simultaneously. An alarm fires when any detector triggers:

Available Drivers

Thermal Governor (ADR-043)

A 1 Hz DVFS governor manages CPU frequency across 4 steps based on SoC temperature, workload demand, and per-chip silicon characterization. The governor runs a 5-step decision pipeline every tick:

1. Firmware veto — check for hardware throttle flags
2. Thermal ceiling — cap frequency based on temperature zone
3. Predictive preemption — if temperature derivative is rising fast, step down early
4. Demand target — set frequency based on workload (fragility score, query rate)
5. Turbo management — burst scheduler with cooldown

Thermal Zones

Zones use 3°C hysteresis to prevent oscillation at boundaries.

Frequency Steps

Temporal Coherence (ADR-042)

Temporal coherence tracks the structural stability of the vector store over time. Every 10 seconds, the optimizer collects a time slice — a snapshot of the kNN graph's similarity structure. Coherence is computed by comparing adjacent slices: a score of 1.0 means the structure is perfectly stable; 0.0 means complete restructuring between slices.

Phase Boundaries

A phase boundary marks a structural regime change — the point where the vector store's topology shifted significantly (e.g., a burst of new data changed cluster structure). Boundaries must persist across N consecutive recomputes to be reported, preventing false positives from transient noise.

Interpreting Scores

Cognitive Container

The cognitive container runs spectral graph analysis on the kNN graph every 30 seconds. Each tick computes a Spectral Coherence Score (SCS) — a measure of graph connectivity via eigenvalue analysis. It accumulates evidence over time and appends tamper-evident receipts to a secondary witness chain independent of the RVF store's chain.

Dual Witness Chains

Memory Budget

The container uses a 512 KB memory slab (reduced from the default 4 MB for the Seed's 512 MB RAM). Max retained receipts: 1000. Both are configurable via PUT /api/v1/cognitive/config.

Import / Export

Import .rvf files from the filesystem (placed via SCP or USB) or export the current store. Import validates dimension match (rejects with 409 on mismatch) and deduplicates by content hash. The Seed's 64 KB HTTP body limit means large files must be placed on the filesystem first, then imported by path.

How-To: Ingest Vectors

Ingest vectors via the JSON API or by importing .rvf files.

API Ingest (small batches)

Send vectors as [id, [f32...]] pairs. The array length must match the store dimension (default 8). IDs are u64; use 0 for auto-generated content-hash IDs.

# Single vector
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/ingest \
  -H 'Content-Type: application/json' \
  -d '{"vectors":[[1,[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8]]]}'

# Batch of 3 vectors with content-hash dedup
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/ingest \
  -d '{"vectors":[[0,[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8]],[0,[0.9,0.8,0.7,0.6,0.5,0.4,0.3,0.2]],[0,[0.5,0.5,0.5,0.5,0.5,0.5,0.5,0.5]]],"dedup":true}'

File Import (large datasets)

# 1. Copy .rvf file to the Seed
scp my-data.rvf genesis@169.254.42.1:~/

# 2. Import via API (reads from filesystem)
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/import \
  -d '{"path":"/home/genesis/my-data.rvf"}'

# 3. Check result
curl -sk https://169.254.42.1:8443/api/v1/store/status

Python Client Example

import requests, json, urllib3
urllib3.disable_warnings()  # self-signed cert

BASE = "https://169.254.42.1:8443/api/v1"
TOKEN = "<your-bearer-token-from-pairing>"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

# Ingest vectors (requires auth)
vectors = [[i, [float(j)/8 for j in range(8)]] for i in range(100)]
r = requests.post(f"{BASE}/store/ingest",
    json={"vectors": vectors}, headers=HEADERS, verify=False)
print(r.json())  # {"ingested": 100, "epoch": ...}

# Query (read-only, no auth required)
r = requests.post(f"{BASE}/store/query",
    json={"vector": [0.1]*8, "k": 5}, verify=False)
for hit in r.json()["results"]:
    print(f"ID {hit['id']}: distance={hit['distance']:.4f}")

How-To: Change Vector Dimension

The store dimension is set by the first ingested vector and cannot be changed without resetting the store. All subsequent vectors must match this dimension.

Setting the Dimension

1. Fresh store — the first ingest sets the dimension. If you ingest an 8-dim vector, the store is 8-dim forever (until reset).
2. Dimension mismatch — if you ingest a vector with the wrong dimension, you get a 400 error: "dimension mismatch: expected 8, got 16".
3. Import mismatch — importing an .rvf file with a different dimension returns 409 Conflict.

Resetting to a New Dimension

# 1. SSH into the Seed
ssh genesis@169.254.42.1

# 2. Stop the agent
sudo systemctl stop cognitum-agent

# 3. Remove the store file (WARNING: deletes all vectors)
sudo rm /var/lib/cognitum/rvf-store/*.rvf

# 4. Restart
sudo systemctl start cognitum-agent

# 5. Ingest with your new dimension (e.g., 128-dim)
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/ingest \
  -d '{"vectors":[[1,[0.1,0.2,...128 values...]]]}'

How-To: Add Real Sensors

The default configuration uses 6 synthetic (software) channels. To add real hardware sensors, wire them to the Seed's GPIO header and update the sensor configuration.

Example: BME280 (Temperature + Humidity + Pressure)

1. Wire the sensor to the I2C bus: VCC → 3.3V (pin 1), GND → GND (pin 6), SDA → GPIO 2 (pin 3), SCL → GPIO 3 (pin 5).
2. Enable I2C on the Pi: sudo raspi-config → Interface Options → I2C → Enable.
3. Verify detection: i2cdetect -y 1 should show the BME280 at address 0x76 or 0x77.
4. Update sensor config via the API (requires pairing):

   curl -sk -X PUT https://169.254.42.1:8443/api/v1/sensor/embedding/config \
     -H 'Content-Type: application/json' \
     -d '{"drivers":[{"type":"bme280","bus":1,"address":"0x76"}]}'

5. Verify readings: GET /api/v1/sensor/stream should show real temperature, humidity, and pressure values instead of synthetic sine waves.

Example: GPIO Digital (Reed Switch / PIR)

1. Wire: connect the switch between a GPIO pin (e.g., GPIO 17, pin 11) and GND. The internal pull-up provides the high state.
2. Configure: add a gpio_digital driver entry with the pin number.
3. Read: GET /api/v1/sensor/gpio/pins shows pin states.

How-To: Configure Reflex Rules

Reflex rules define automatic sensor-to-actuator responses. When a trigger condition is met, the reflex arc fires the specified actuator action. Rules have priorities and cooldown periods to prevent rapid-fire toggling.

Rule Structure

{
  "name": "high-temp-alert",
  "trigger": {
    "type": "threshold",        // threshold | drift | fragility
    "channel": "temperature",
    "op": "gt",                  // gt | lt | eq
    "value": 60.0
  },
  "action": {
    "type": "fire",             // fire | release | pwm
    "actuator": 0
  },
  "cooldown_ms": 5000,
  "priority": 1                  // lower = higher priority
}

Trigger Types

Update rules via PUT /api/v1/sensor/reflex/rules (requires pairing). Safety-first: fragility checks run before boundary analysis to prevent cascading failures.

How-To: Silicon Characterization

Each Pi chip is slightly different. Silicon characterization tests your specific chip to find its maximum stable overclock frequency.

1. Trigger characterization: POST /api/v1/thermal/characterize (requires pairing). This takes ~30 seconds.
2. The test runs boundary analysis 10 times at each frequency step [600, 1000, 1200, 1300 MHz] and compares SHA-256 hashes of the partition results.
3. If all 10 runs produce identical hashes at a frequency, that step is marked stable.
4. The governor's max frequency is automatically capped at the highest stable step.
5. View results: GET /api/v1/thermal/silicon-profile shows pass/fail per step.

How-To: Export & Backup

Export via API

# Export store to a file on the Seed
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/export \
  -d '{"path":"/tmp/backup.rvf"}'

# Download it to your computer
scp genesis@169.254.42.1:/tmp/backup.rvf ./backup.rvf

Full Sync (all live vectors)

# Pull all vectors as JSON
curl -sk https://169.254.42.1:8443/api/v1/store/sync > vectors.json

SD Card Image

# On the Pi: zero free space for better compression
sudo dd if=/dev/zero of=/tmp/zero bs=4M 2>/dev/null; sudo rm /tmp/zero

# On your computer: image the SD card
# (replace sdX with your SD card device)
sudo dd if=/dev/sdX bs=4M status=progress | gzip > cognitum-backup.img.gz

File Transfer

Upload RVF vector files or download the current store. The Seed accepts uploads up to 64 KB via HTTP; for larger files, use the SCP workflow below.

# 1. Copy file to Seed
scp my-data.rvf genesis@169.254.42.1:/home/genesis/

# 2. Import via API
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/import \
  -H 'Content-Type: application/json' \
  -d '{"path":"/home/genesis/my-data.rvf"}'

# 3. Verify
curl -sk https://169.254.42.1:8443/api/v1/store/status

Store Operations

Query, inspect, and manage the vector store directly from this page.

Configuration

View and update device configuration. Write operations require pairing.

Device Management

Monitor and control device operations. Destructive actions require pairing and confirmation.

Quick Actions

Optimization

Thermal & Characterization

Witness & Custody

Core API Endpoints (30)

Store v2 API Endpoints (9)

Sensor API Endpoints (17)

Thermal API Endpoints (13)

Coherence API Endpoints (5)

Cognitive API Endpoints (7)

Import / Export Endpoints (3)

Security & Firmware Endpoints (8)

Mesh Overlay Endpoints (7)

Mesh endpoints require the mesh feature to be compiled. Returns 404 when mesh is not available. The /disable and /enable endpoints only work from localhost (127.0.0.1 or USB 169.254.42.1) for security.

Sync & Swarm Endpoints (10)

Delta Sync Example

# Pull only changes since epoch 50
curl -sk "https://169.254.42.1:8443/api/v1/store/sync?since_epoch=50"
# Response: {"is_delta":true, "vectors":[...], "deletions":[12,45], "current_epoch":73}

# Push changes to peer
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/sync \
  -H "Content-Type: application/json" \
  -d '{"vectors":[[1,[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8]]],"deletions":[99],"source_device_id":"peer-uuid","source_epoch":30}'

MCP Tools — 114 Tools, 21 Groups (ADR-058)

All MCP communication uses JSON-RPC 2.0 via POST /mcp. Session must be initialized before calling tools. Scope controls how many tools are advertised.

Wire Format

# Request (using canonical tool name):
{"jsonrpc":"2.0","method":"tools/call","id":3,"params":{"name":"seed.device.status","arguments":{}}}

# Response (with annotations):
{"jsonrpc":"2.0","result":{"content":[{"type":"text","text":"{\"deviceId\":\"...\",\"uptimeSecs\":120,...}"}]},"id":3}

# Auth denied (wrong auth class):
{"jsonrpc":"2.0","error":{"code":-32001,"message":"Auth class 'dangerous' required","data":{"tool":"seed.firmware.update","requiredAuthClass":"dangerous"}},"id":4}

Headers

Upgrade & Other Endpoints (2)

OTA auto-update behavior

Every 6 hours by default, the agent fetches https://storage.googleapis.com/cognitum-apps/firmware/latest.json, compares versions, and if newer, downloads + verifies SHA-256 + atomically replaces the binary + restarts the service. Default: enabled.

Disable auto-update (AUTH required):

curl -sk -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"enabled":false}' https://<seed>:8443/api/v1/ota/config

Force an immediate check (AUTH required):

curl -sk -X POST -H "Authorization: Bearer $TOKEN" \
  https://<seed>:8443/api/v1/ota/check-now

The call returns {"triggered":true} immediately — the update check runs asynchronously. Poll GET /api/v1/upgrade/check to see last_check_epoch / last_update_version reflect the outcome. If an update is applied, the service restarts ~2s after the download completes.

CLI disable (requires editing the systemd unit): add --no-auto-update to ExecStart in cognitum-agent.service, then systemctl daemon-reload && systemctl restart cognitum-agent.

Hardware

GPIO Pin Assignments

Performance Benchmarks (20k vectors, dim=8)

Security

Witness Chain Verification

Every store mutation (ingest, delete, compact, metadata update) appends a SHA-256 witness hash: SHA-256(prev_hash || entry_data). The chain is tamper-evident — flipping any byte in any entry breaks all subsequent hashes.

# Verify the full witness chain
curl -sk -X POST https://169.254.42.1:8443/api/v1/witness/verify
# {"valid":true, "algorithm":"sha256", "head":"a1b2c3...", "entries_verified":20000}

OTA Firmware Verification

When a build key is configured, firmware updates require a valid Ed25519 signature. Two modes are supported:

# Mode 1: Detached signature (X-Signature header, hex-encoded)
curl -sk -X POST https://169.254.42.1:8443/api/v1/firmware/update \
  -H "X-Signature: a1b2c3d4..." \
  --data-binary @cognitum-agent

# Mode 2: Inline signature (last 64 bytes of body)
cat cognitum-agent signature.bin | \
curl -sk -X POST https://169.254.42.1:8443/api/v1/firmware/update \
  -H "X-Signed: true" \
  --data-binary @-

mTLS Auto-Enable

If a client CA certificate exists at the well-known path, mTLS is automatically enabled in optional mode. No flag needed.

# Production: /var/lib/cognitum/tls/client-ca.pem
# Virtual:    ./client-ca.pem

# Check mTLS status
curl -sk https://169.254.42.1:8443/api/v1/security/status | jq .mtls_active

Mesh Overlay Networking (ADR-084)

The mesh overlay enables secure peer-to-peer connectivity between seeds across the internet. It uses QUIC tunnels with mutual TLS (mTLS) authentication via the existing CA infrastructure.

How to Disable Mesh Features

Multiple methods for defense-in-depth. Use whichever fits your security posture:

# ── Method 1: Disable ALL mesh networking ──
# Add --no-mesh to the systemd service:
sudo sed -i 's|ExecStart=/opt/cognitum/cognitum-agent|ExecStart=/opt/cognitum/cognitum-agent --no-mesh|' \
  /etc/systemd/system/cognitum-agent.service
sudo systemctl daemon-reload && sudo systemctl restart cognitum-agent

# ── Method 2: Disable remote access only (keep mesh sync) ──
# Seed still syncs with peers but rejects shell/UI proxy requests
sudo sed -i 's|ExecStart=/opt/cognitum/cognitum-agent|ExecStart=/opt/cognitum/cognitum-agent --no-remote|' \
  /etc/systemd/system/cognitum-agent.service
sudo systemctl daemon-reload && sudo systemctl restart cognitum-agent

# ── Method 3: LAN-only mesh (no cloud, no relay) ──
# Peers discovered via mDNS only, encrypted tunnels, no GCP contact
sudo sed -i 's|ExecStart=/opt/cognitum/cognitum-agent|ExecStart=/opt/cognitum/cognitum-agent --mesh-local-only|' \
  /etc/systemd/system/cognitum-agent.service
sudo systemctl daemon-reload && sudo systemctl restart cognitum-agent

# ── Method 4: Disable via config file ──
echo '{"enabled": false}' | sudo tee /var/lib/cognitum/mesh-config.json
sudo systemctl restart cognitum-agent

# ── Method 5: Disable at runtime (no restart needed) ──
curl -sk -X POST http://169.254.42.1/api/v1/mesh/disable
# Re-enable: curl -sk -X POST http://169.254.42.1/api/v1/mesh/enable

# ── Method 6: Remove mesh config permanently ──
sudo rm /var/lib/cognitum/mesh-config.json
sudo systemctl restart cognitum-agent

# ── Check current mesh security status ──
curl -sk http://169.254.42.1/api/v1/mesh/security | jq .

Recommended Security Configurations

Getting Files Onto the Seed

The USB drive (COGNITUM) is read-only. Use these methods to transfer files:

SCP (Secure Copy)

# Over USB
scp myfile.rvf genesis@169.254.42.1:~/

# Over WiFi
scp myfile.rvf genesis@cognitum.local:~/

Typical Import Workflow

# 1. Copy .rvf file to the Seed
scp data.rvf genesis@169.254.42.1:~/

# 2. Import via API
curl -sk -X POST https://169.254.42.1:8443/api/v1/store/import \
  -H "Content-Type: application/json" \
  -d '{"path": "/home/genesis/data.rvf"}'

# 3. Verify
curl -sk https://169.254.42.1:8443/api/v1/store/status

WiFi Setup

Configure WiFi to access the Seed wirelessly from any device on your network.

Browser Setup (when connected via USB)

SSH Setup (Advanced)

For advanced users who prefer the command line. Connect via USB first, then configure WiFi over SSH.

# 1. SSH into the Seed via USB
ssh genesis@169.254.42.1
# Default password: cognitum

# 2. Scan for available WiFi networks
sudo nmcli device wifi list

# 3. Connect to your home WiFi
sudo nmcli device wifi connect "YourNetwork" password "YourPassword"

# 4. Verify connection and note the WiFi IP
ip -4 addr show wlan0 | grep inet
# Example output: inet 192.168.1.62/24 ...

# 5. Test internet connectivity
curl -sk https://localhost:8443/api/v1/network/internet-check

# 6. (Optional) Add a second WiFi network
sudo nmcli device wifi connect "Office-WiFi" password "officepass"
# The Seed auto-connects to whichever network is available

# 7. Manage saved networks
nmcli connection show                                    # List all
sudo nmcli connection delete "Office-WiFi"              # Remove one

# 8. Enable the Setup WiFi AP (for wireless-only access)
curl -sk -X POST https://localhost:8443/api/v1/network/setup-wifi/enable
# Other devices can now connect to Cognitum-Setup-XXXX

Manage Saved Networks

WiFi credentials persist across firmware updates (stored on the data partition). The Seed does not bridge USB and WiFi traffic (network isolation).

Network Overview

Firmware Updates

The Seed uses A/B slot partitioning. Updates write to the inactive slot. If the API doesn't respond within 30 seconds after reboot, the boot guard rolls back automatically after 3 failed attempts.

Quick Deploy (binary only)

# Stop, copy, restart
ssh genesis@cognitum.local "sudo systemctl stop cognitum-agent"
scp cognitum-agent genesis@cognitum.local:~/
ssh genesis@cognitum.local \
  "sudo cp ~/cognitum-agent /opt/cognitum/cognitum-agent && \
   sudo chmod 755 /opt/cognitum/cognitum-agent && \
   sudo systemctl start cognitum-agent"

Partition Layout

Troubleshooting

{"error":"Bearer token required for WiFi access. Pair via USB first."}

You hit a write or auth-required endpoint from a WiFi origin (not USB) without a valid bearer token in localStorage. Three ways to fix, easiest first:

1. Use USB instead. Load the guide at http://169.254.42.1/guide. USB (169.254.x.x), localhost (127.x.x.x), IPv6 link-local (fe80::), and Setup WiFi AP (192.168.4.x) are trust-bypassed — no token required.
2. Paste an existing token into this origin's localStorage. Open DevTools → Console and run:

   localStorage.setItem('cognitum_token','<your-token>'); location.reload();

   Important: localStorage is partitioned by browser origin (scheme+host+port). A token pasted on https://cognitum.local:8443 is invisible from a http://192.168.1.106 tab — you'll need to paste once per origin you use, even if they all point to the same seed. This is a browser security rule, not a seed policy.
3. Pair this origin fresh. Scroll to the Pairing section and click Pair. On v0.10.16+ a valid existing token (on any trusted path) authorizes opening a new pair window from WiFi, so one click handles both steps.

{"error":"pairing window can only be opened from localhost, USB, or Setup WiFi AP"}

Returned by POST /api/v1/pair/window when the device is already paired and the request comes from a plain LAN IP without a token. Fix:

• v0.10.16+: attach your existing Bearer token to the request. A paired client is allowed to open a window to pair additional clients.
• Pre-v0.10.16 or no token: SSH in and open the window from localhost:

  ssh genesis@<seed> 'curl -s -X POST http://127.0.0.1/api/v1/pair/window'
  # then click Pair in the guide within 30s

• First-boot only: while the device is still unpaired, any LAN client can open the window (ADR-086). Once paired, that relaxation is revoked.

{"error":"pairing window closed — open with POST /pair/window from USB first"}

You called POST /api/v1/pair outside the 30-second window. The window must be opened first (see the error above). After it's open, call /pair within 30s. The guide's Pair button chains both calls automatically.

Different seeds = different tokens (not interchangeable)

Each seed keeps its own clients.json. A token minted on seed A will not authenticate requests to seed B — you'll get a 401 even with the token attached. If you manage multiple seeds, expect to pair once per seed and keep their tokens separate. The seed's device_id is visible on GET /api/v1/identity — use it to tell them apart.

Browser shows "Not Secure" on https://cognitum.local:8443

The device TLS cert is signed by a self-signed Cognitum Device CA. Windows/macOS don't trust that CA by default, so browsers block the page. One-time install:

• Windows (admin):

  Import-Certificate -FilePath 'cognitum-local-ca.crt' `
    -CertStoreLocation 'Cert:\LocalMachine\Root'

  or: double-click the .crt → Install Certificate → Local Machine → Trusted Root Certification Authorities.
• macOS: double-click → Keychain Access → System → set "Always Trust".
• Source: the CA cert lives on the seed at /var/lib/cognitum/tls/ca.pem — you can fetch it via ssh genesis@<seed> 'cat /var/lib/cognitum/tls/ca.pem' > cognitum-local-ca.crt.
• curl: -k / --insecure skips the check entirely (safe on your own LAN, not recommended in scripts).

cognitum.local resolves to the wrong seed

mDNS is a broadcast protocol — if multiple seeds on the same LAN advertise cognitum.local, the first to answer wins. To pin a specific seed, add to your OS hosts file:

# Windows: C:\Windows\System32\drivers\etc\hosts
# macOS/Linux: /etc/hosts
192.168.1.106   cognitum.local

Or use the per-device hostname from the cert SAN: https://<device-id-short>.device.cognitum.one:8443 (visible in GET /api/v1/identity).

Guide's "Run" button hits a different URL than the curl example

The Run button calls fetch(BASE + path) where BASE is the origin the guide was loaded from (dynamically chosen when you Connect). The curl snippet shown in the <pre> block is just a copy-paste reference — it's often hard-coded to 169.254.42.1:8443 even when the Run button is firing against a different origin. If Run fails with 401 but your curl works, check the top-bar URL bar and make sure the guide is connected to the origin you expect.

Device not detected via USB

Use the USB data port (not power-only). Check for the COGNITUM drive. If USB Ethernet doesn't appear, SSH via WiFi and check: cat /sys/kernel/config/usb_gadget/cognitum/UDC (should show 3f980000.usb).

OTA via /api/v1/upgrade/apply returns failed to write binary: Read-only file system

Fixed in v0.21.1 (issue #102). On v0.21.1 and later, the handler stages the binary at /var/lib/cognitum/staging/cognitum-agent.new (which is in ReadWritePaths) and triggers a transient root unit (cognitum-agent-swap-transient.service) via systemd-run to perform the atomic swap into /opt/cognitum/ outside the agent's ProtectSystem=strict sandbox. No workaround needed.

If you see this error, the seed is on v0.21.0 or earlier. Either upgrade to v0.21.1+ (the OTA timer at /api/v1/ota/check-now still works on the older firmware because it runs as root outside the sandbox), or use the SCP+sudo workaround:

scp cognitum-agent-vX.Y.Z-arm genesis@<seed>:/tmp/
ssh genesis@<seed> '
  sudo systemctl stop cognitum-agent
  sudo cp /opt/cognitum/cognitum-agent /opt/cognitum/cognitum-agent.prev.bak
  sudo cp /tmp/cognitum-agent-vX.Y.Z-arm /opt/cognitum/cognitum-agent
  sudo chmod 755 /opt/cognitum/cognitum-agent
  sudo systemctl start cognitum-agent
'

401 Unauthorized / 403 Forbidden on write endpoints

401: Missing or invalid bearer token. Go to Pairing and pair your client, or paste an existing token into localStorage (see top of this section). For CLI, include -H 'Authorization: Bearer <token>'.

403: The pairing window is not open, or the request was rejected by a per-endpoint security rule (e.g. /pair/window on a paired device without a token). Check the error body for specifics.

TLS certificate warning (short version)

Install the Cognitum CA certificate (see dedicated section above). After installing, all Cognitum devices are trusted automatically with no browser warnings. For curl on Windows, add --ssl-no-revoke if needed.

409 on import

The .rvf file has a different vector dimension than the store. Check with GET /api/v1/store/import/formats. To change dimension, see How-To: Change Dimension.

Sensor endpoints return 404

Sensor endpoints require the optimizer loop to be running. In --virtual mode (localhost dev), only core + thermal endpoints are available. Deploy to Pi or run without --virtual.

Device goes to sleep

Check that g_ether is not loaded: lsmod | grep g_ether. If loaded, blacklist it and reboot.

Recovery

Hold the factory reset button (GPIO 27) for 10+ seconds to wipe data and regenerate identity. Or use the Cognitum mesh overlay for remote access.