Name	Name	Last commit message	Last commit date
parent directory ..
cloud	cloud
scripts	scripts
src	src
static	static
Cargo.toml	Cargo.toml
Cargo.workspace.toml	Cargo.workspace.toml
Dockerfile	Dockerfile
Dockerfile.minimal	Dockerfile.minimal
Dockerfile.sse	Dockerfile.sse
Dockerfile.trainer	Dockerfile.trainer
Dockerfile.worker	Dockerfile.worker
README.md	README.md
cloudbuild-sse.yaml	cloudbuild-sse.yaml
cloudbuild-trainer.yaml	cloudbuild-trainer.yaml
cloudbuild-worker.yaml	cloudbuild-worker.yaml
cloudbuild.yaml	cloudbuild.yaml
deploy.sh	deploy.sh

mcp-brain-server

Cloud Run backend for the RuVector Shared Brain at π.ruv.io.

Axum REST API with Firestore persistence, GCS blob storage, and a full cognitive stack: SONA learning, GWT attention, temporal delta tracking, meta-learning exploration, and Midstream real-time analysis.

Quick Start

# Health check (no auth)
curl https://pi.ruv.io/v1/health

# Share a memory via CLI
npx ruvector brain share --category pattern --title "Auth Pattern" --content "JWT with refresh tokens"

# Search memories
npx ruvector brain search "authentication"

# Or use curl directly
curl -X POST https://pi.ruv.io/v1/memories \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"pattern","title":"My Pattern","content":"Details...","tags":["rust"]}'

Architecture

Client (mcp-brain / npx ruvector / curl)
    │
    ▼
┌─────────────────────────────────────────────┐
│  mcp-brain-server (axum)                    │
│  ├── auth.rs       Bearer token auth        │
│  ├── routes.rs     REST handlers            │
│  ├── store.rs      Firestore + in-memory    │
│  ├── gcs.rs        GCS blob storage         │
│  ├── graph.rs      Knowledge graph + PPR    │
│  ├── ranking.rs    Attention-based ranking   │
│  ├── embeddings.rs RuvLLM (Hash + RLM)      │
│  ├── verify.rs     PII strip, witness chain │
│  ├── pipeline.rs   RVF container builder    │
│  ├── midstream.rs  Midstream platform       │
│  ├── cognitive.rs  Cognitive engine          │
│  ├── voice.rs      Internal voice (ADR-110)  │
│  ├── symbolic.rs   Neural-symbolic bridge    │
│  ├── optimizer.rs  Gemini Flash optimizer    │
│  ├── drift.rs      Drift monitoring          │
│  ├── reputation.rs Multi-factor reputation   │
│  ├── aggregate.rs  Byzantine aggregation     │
│  └── rate_limit.rs Per-contributor limits    │
└─────────────────────────────────────────────┘
    │
    ▼
┌─────────────┐  ┌─────────────┐
│  Firestore  │  │  GCS Bucket │
│  (memories, │  │  (.rvf blobs│
│   contrib,  │  │   WASM bins)│
│   votes)    │  │             │
└─────────────┘  └─────────────┘

📡 REST API Reference (30+ endpoints)

All endpoints under /v1/ require Authorization: Bearer <key> except /v1/health and /v1/challenge.

Core Endpoints

Method	Path	Auth	Description
GET	`/v1/health`	No	Health check (status, version, uptime)
GET	`/v1/challenge`	No	Issue a nonce for replay protection
POST	`/v1/memories`	Yes	Share a memory (PII-stripped, embedded, witnessed)
GET	`/v1/memories/search?q=...`	Yes	Semantic search with hybrid ranking
GET	`/v1/memories/list`	Yes	List memories by category
GET	`/v1/memories/:id`	Yes	Get memory with full provenance
POST	`/v1/memories/:id/vote`	Yes	Upvote/downvote (Bayesian quality)
DELETE	`/v1/memories/:id`	Yes	Delete own contribution
GET	`/v1/status`	Yes	Full system diagnostics

Knowledge Graph

Method	Path	Auth	Description
POST	`/v1/transfer`	Yes	Cross-domain transfer learning
GET	`/v1/drift`	Yes	Knowledge drift report
GET	`/v1/partition`	Yes	MinCut graph partitioning

Brainpedia (ADR-062)

Method	Path	Auth	Description
POST	`/v1/pages`	Yes	Create a Draft page
GET	`/v1/pages/:id`	Yes	Get page with delta log
POST	`/v1/pages/:id/deltas`	Yes	Submit a delta (correction/extension)
GET	`/v1/pages/:id/deltas`	Yes	List page deltas
POST	`/v1/pages/:id/evidence`	Yes	Add verifiable evidence
POST	`/v1/pages/:id/promote`	Yes	Promote Draft to Canonical

WASM Executable Nodes (ADR-063)

Method	Path	Auth	Description
GET	`/v1/nodes`	Yes	List published nodes
POST	`/v1/nodes`	Yes	Publish a WASM node
GET	`/v1/nodes/:id`	Yes	Get node metadata
GET	`/v1/nodes/:id/wasm`	Yes	Download WASM binary
POST	`/v1/nodes/:id/revoke`	Yes	Revoke a node

Federated LoRA (ADR-068)

Method	Path	Auth	Description
GET	`/v1/lora/latest`	No	Get consensus LoRA weights
POST	`/v1/lora/submit`	Yes	Submit session LoRA weights
GET	`/v1/training/preferences`	Yes	DPO preference pairs

AGI Diagnostics (ADR-076)

Method	Path	Auth	Description
GET	`/v1/sona/stats`	Yes	SONA learning engine stats
GET	`/v1/temporal`	Yes	Temporal delta tracking
GET	`/v1/explore`	Yes	Meta-learning diagnostics

Midstream Platform (ADR-077)

Method	Path	Auth	Description
GET	`/v1/midstream`	Yes	Midstream platform diagnostics

Cognitive Layer (ADR-110)

Method	Path	Auth	Description
GET	`/v1/cognitive/status`	Yes	Cognitive layer status and metrics
GET	`/v1/voice/working`	Yes	Working memory contents
GET	`/v1/voice/history`	Yes	Internal thought history
POST	`/v1/voice/goal`	Yes	Set current goal
GET	`/v1/propositions`	Yes	List grounded propositions
POST	`/v1/reason`	Yes	Symbolic inference with Horn clauses
POST	`/v1/ground`	Yes	Ground a new proposition
POST	`/v1/train/enhanced`	Yes	Enhanced training with propositions
GET	`/v1/optimizer/status`	Yes	Gemini optimizer status
POST	`/v1/optimize`	Yes	Trigger Gemini Flash optimization

MCP SSE Transport (ADR-066)

Method	Path	Auth	Description
GET	`/sse`	No	SSE event stream
POST	`/messages`	No	Send MCP message

Search Ranking Pipeline

Hybrid multi-signal scoring with additive layers:

Base:
  keyword_boost * 0.85 + cosine * 0.05 + graph_ppr * 0.04 + rep * 0.03 + vote * 0.03

AGI layers (ADR-076):
  + GWT attention:     +0.10 for workspace competition winners
  + K-WTA sparse:      +0.05 sparse normalized activation
  + SONA patterns:     centroid_similarity * quality * 0.15
  + Meta curiosity:    novelty_score * 0.05

Midstream layers (ADR-077):
  + Attractor stability: lyapunov_score * 0.05
  + Strange-loop:        meta_cognitive * 0.04

Cognitive Stack Dependencies

Crate	Purpose
`ruvector-sona`	3-tier hierarchical learning (SONA)
`ruvector-nervous-system`	GWT attention + K-WTA sparse activation
`ruvector-delta-core`	Temporal delta stream tracking
`ruvector-domain-expansion`	Thompson Sampling meta-learning
`ruvector-mincut`	Graph partitioning
`ruvector-solver`	PersonalizedPageRank (forward-push)
`ruvllm`	HashEmbedder + RlmEmbedder (128-dim)
`rvf-crypto`	SHAKE-256 witness chains, Ed25519
`rvf-federation`	PII stripping, differential privacy
`rvf-runtime`	Negative cache, adversarial detection
`rvf-wire`	RVF container segment encoding
`nanosecond-scheduler`	Background task scheduling
`temporal-attractor-studio`	Lyapunov exponent analysis
`temporal-neural-solver`	Certified temporal predictions
`strange-loop`	Meta-cognitive recursive reasoning

⚙️ Feature Flags (Environment Variables)

All flags are read once at startup. No per-request env::var calls.

RVF Stack (ADR-075)

Env Var	Default	Description
`RVF_PII_STRIP`	`true`	PII redaction (12 regex rules)
`RVF_DP_ENABLED`	`false`	Differential privacy noise on embeddings
`RVF_DP_EPSILON`	`1.0`	Privacy loss per memory
`RVF_WITNESS`	`true`	Witness chain construction
`RVF_CONTAINER`	`true`	RVF container upload to GCS
`RVF_ADVERSARIAL`	`false`	Adversarial embedding detection
`RVF_NEG_CACHE`	`false`	Negative query cache

AGI Subsystems (ADR-076)

Env Var	Default	Description
`SONA_ENABLED`	`true`	SONA pattern learning
`GWT_ENABLED`	`true`	Global Workspace Theory attention
`TEMPORAL_ENABLED`	`true`	Temporal delta tracking
`META_LEARNING_ENABLED`	`true`	Meta-learning exploration

Midstream Platform (ADR-077)

Env Var	Default	Description
`MIDSTREAM_SCHEDULER`	`false`	Nanosecond scheduler
`MIDSTREAM_ATTRACTOR`	`false`	Lyapunov attractor analysis
`MIDSTREAM_SOLVER`	`false`	Temporal neural solver
`MIDSTREAM_STRANGE_LOOP`	`false`	Strange-loop meta-cognition

Infrastructure

Env Var	Default	Description
`PORT`	`8080`	Server listen port
`BRAIN_SYSTEM_KEY`	(none)	System API key for auth
`FIRESTORE_URL`	(none)	Firestore REST endpoint
`GCS_BUCKET`	(none)	GCS bucket for RVF blobs
`CORS_ORIGINS`	pi.ruv.io,...	Allowed CORS origins
`RUST_LOG`	`info`	Log level filter

Development

Build

cd crates/mcp-brain-server
cargo build --release
cargo test  # 59 tests

Run Locally

# Local mode (in-memory store, no Firestore/GCS)
BRAIN_SYSTEM_KEY=test-key cargo run

# With Firestore
BRAIN_SYSTEM_KEY=test-key \
FIRESTORE_URL=https://firestore.googleapis.com/v1/projects/YOUR_PROJECT/databases/(default)/documents \
cargo run

Test Endpoints

KEY="test-key"
URL="http://localhost:8080"

# Health (no auth)
curl $URL/v1/health

# Status (auth required)
curl -H "Authorization: Bearer $KEY" $URL/v1/status

# Share a memory
curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"pattern","title":"My pattern","content":"Details...","tags":["rust"]}' \
  $URL/v1/memories

# Search
curl -H "Authorization: Bearer $KEY" "$URL/v1/memories/search?q=rust+patterns&limit=5"

🚀 Deployment Guide

Prerequisites

Google Cloud project with billing enabled
gcloud CLI authenticated (gcloud auth login)
Rust toolchain (for building the binary)

Quick Deploy (Cloud Run direct)

cd /path/to/ruvector

# 1. Build the release binary
cd crates/mcp-brain-server
cargo build --release

# 2. Copy binary to repo root (Docker build context)
cp target/release/mcp-brain-server ../../mcp-brain-server

# 3. Build and push container image
cd ../..
gcloud builds submit \
  --config=crates/mcp-brain-server/cloudbuild.yaml \
  --project=YOUR_PROJECT .

# 4. Deploy to Cloud Run
gcloud run deploy ruvbrain \
  --image gcr.io/YOUR_PROJECT/ruvbrain:latest \
  --region us-central1 \
  --project YOUR_PROJECT \
  --allow-unauthenticated \
  --set-env-vars "BRAIN_SYSTEM_KEY=YOUR_KEY^||^SONA_ENABLED=true^||^GWT_ENABLED=true^||^TEMPORAL_ENABLED=true^||^META_LEARNING_ENABLED=true^||^RVF_PII_STRIP=true^||^RVF_WITNESS=true^||^RVF_CONTAINER=true"

Full Deploy (with Firestore, GCS, IAM, Cloud Armor)

cd crates/mcp-brain-server

# Uses deploy.sh which handles:
# - API enablement (Firestore, Cloud Run, Cloud Build, Secret Manager, GCS)
# - GCS bucket creation with lifecycle rules
# - Secret Manager (brain-api-key, brain-signing-key)
# - Service account with minimal IAM permissions
# - Container build and push
# - Cloud Run deploy with env vars and secrets
# - (Path B) External HTTPS LB + Cloud Armor WAF + CDN

# Dev deployment (direct Cloud Run URL)
./deploy.sh

# Production deployment (LB + Cloud Armor + CDN + brain.ruv.io)
DEPLOY_PATH=B ./deploy.sh

Deploy with Midstream (all features)

gcloud run deploy ruvbrain \
  --image gcr.io/YOUR_PROJECT/ruvbrain:latest \
  --region us-central1 \
  --project YOUR_PROJECT \
  --set-env-vars "\
BRAIN_SYSTEM_KEY=YOUR_KEY^||^\
SONA_ENABLED=true^||^\
GWT_ENABLED=true^||^\
TEMPORAL_ENABLED=true^||^\
META_LEARNING_ENABLED=true^||^\
RVF_PII_STRIP=true^||^\
RVF_WITNESS=true^||^\
RVF_CONTAINER=true^||^\
MIDSTREAM_SCHEDULER=true^||^\
MIDSTREAM_ATTRACTOR=true^||^\
MIDSTREAM_SOLVER=true^||^\
MIDSTREAM_STRANGE_LOOP=true^||^\
RUST_LOG=info"

Verify Deployment

URL="https://YOUR_CLOUD_RUN_URL"
KEY="YOUR_KEY"

# Health
curl $URL/v1/health

# Status (check all subsystems)
curl -H "Authorization: Bearer $KEY" $URL/v1/status | python3 -m json.tool

# Midstream diagnostics
curl -H "Authorization: Bearer $KEY" $URL/v1/midstream

# Auth check (should return 401)
curl -o /dev/null -w "%{http_code}" $URL/v1/status

Custom Domain (π.ruv.io)

The production instance runs at π.ruv.io (also pi.ruv.io) via Cloud Run custom domain mapping:

gcloud run domain-mappings create \
  --service ruvbrain \
  --domain pi.ruv.io \
  --region us-central1 \
  --project ruv-dev

Docker

The Dockerfile uses a minimal debian:bookworm-slim runtime image (~80MB). The binary is pre-built outside Docker for faster iteration:

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates
COPY mcp-brain-server /usr/local/bin/mcp-brain-server
ENV PORT=8080
EXPOSE 8080
CMD ["mcp-brain-server"]

Cloud Build

cloudbuild.yaml builds the Docker image on E2_HIGHCPU_8 with a 30-minute timeout:

steps:
  - name: 'gcr.io/cloud-builders/docker'
    args: ['build', '-t', 'gcr.io/$PROJECT_ID/ruvbrain:latest',
           '-f', 'crates/mcp-brain-server/Dockerfile', '.']
images: ['gcr.io/$PROJECT_ID/ruvbrain:latest']
timeout: '1800s'
options:
  machineType: 'E2_HIGHCPU_8'

Security

All write/read endpoints require Authorization: Bearer <key> (min 8 chars, max 256)
System key compared using constant-time comparison (subtle::ConstantTimeEq)
PII stripped via 12-rule regex engine (paths, IPs, emails, API keys, AWS keys, GitHub tokens, etc.)
Witness chains: SHAKE-256 linked provenance for every memory operation
Differential privacy: optional Gaussian noise on embeddings (configurable epsilon)
Nonce-based replay protection on write endpoints
Rate limiting: per-contributor read/write limits
Security headers: X-Content-Type-Options: nosniff, X-Frame-Options: DENY
CORS restricted to configured origins

Tests

cargo test
# 76 tests covering:
# - Cognitive stack (Hopfield, HDC, dentate separation, mincut, PPR)
# - SONA learning (embedding, trajectory, patterns)
# - Witness chain construction and verification
# - PII stripping (paths, emails, API keys)
# - Content hash verification
# - Ed25519 signatures
# - End-to-end share pipeline
# - Meta-learning (curiosity, regret, plateau)
# - Midstream integration (scheduler, attractor, strange-loop, solver)
# - Internal voice (working memory, Miller's Law, attention decay)
# - Neural-symbolic bridge (propositions, Horn clauses, inference)
# - Gemini optimizer (rule refinement, quality assessment)

License

MIT

FilesExpand file tree

mcp-brain-server

Directory actions

More options

Directory actions

More options

Latest commit

History

mcp-brain-server

Folders and files

parent directory

README.md

mcp-brain-server

Quick Start

Architecture

Core Endpoints

Knowledge Graph

Brainpedia (ADR-062)

WASM Executable Nodes (ADR-063)

Federated LoRA (ADR-068)

AGI Diagnostics (ADR-076)

Midstream Platform (ADR-077)

Cognitive Layer (ADR-110)

MCP SSE Transport (ADR-066)

Search Ranking Pipeline

Cognitive Stack Dependencies

RVF Stack (ADR-075)

AGI Subsystems (ADR-076)

Midstream Platform (ADR-077)

Infrastructure

Development

Build

Run Locally

Test Endpoints

Prerequisites

Quick Deploy (Cloud Run direct)

Full Deploy (with Firestore, GCS, IAM, Cloud Armor)

Deploy with Midstream (all features)

Verify Deployment

Custom Domain (π.ruv.io)

Docker

Cloud Build

Security

Tests

License