maestro-nerve

Shared intelligence memory layer for procurement, compliance, and tender-review agents.

maestro-nerve gives AI agents a shared, evidence-backed memory over fragmented work sources. It is built for procurement, compliance, and tender-review workflows where Gmail, Drive, docs, sheets, notes, and agent outputs need to converge into one inspectable intelligence layer.

Why nerve?

Quickstart

For AI Agents (Claude Code skill)

# nerve is available as a Claude Code skill
mnerve understand "your query"

For Developers

Neon is the required V1 database. Point NEON_DATABASE_URL at a Neon Postgres database with sslmode=require, then initialize and serve:

# Install
pip install maestro-nerve

# Point nerve at Neon
export NEON_DATABASE_URL="postgresql://USER:PASS@HOST.neon.tech/DB?sslmode=require"
mnerve init

# Start daemon
mnerve serve

Architecture

┌─────────────────────────────────────────────────────┐
│         External Sources + Heterogeneous Agents     │
├───────────────────────┬─────────────────────────────┤
│  source intake        │  agent-authored intake      │
│  Gmail · Drive · ...  │  fact · conclusion · ...    │
├───────────────────────┴─────────────────────────────┤
│                 Evidence Ledger                     │
│   source_objects · facts · conclusions · events     │
├─────────────────────────────────────────────────────┤
│                 Semantic Layer                      │
│     entities · claims · evidence · decisions        │
├─────────────────────────────────────────────────────┤
│                 Serve Layer                         │
│        MCP · HTTP · CLI · workspace surfaces        │
└─────────────────────────────────────────────────────┘

Legacy compatibility CLI

The repo still contains legacy remember/understand/feedback surfaces. They are compatibility-only and do not define the long-term product contract. The authoritative V1 and cross-agent naming lives in:

• docs/superpowers/specs/2026-04-21-mcp-v1-tools.md
• docs/superpowers/plans/2026-04-23-cross-agent-memory-broker.md
• docs/superpowers/plans/2026-04-23-unified-agent-source-intake-architecture.md

Legacy examples:

# Store knowledge (structured)
echo '{"nodes":[{"name":"Dr. Chen","type":"person","properties":{"affiliation":"NUS"}}]}' \
  | mnerve remember --structured

# Recall
mnerve understand "climate data gaps"

# Feedback (improves future ranking)
mnerve feedback q-abc123 548 515

# Batch (preferred — one call instead of many)
mnerve batch '[
  {"op":"understand","params":{"question":"ERA5 climate"}},
  {"op":"remember","params":{"content":"ERA5 has gaps pre-1979","type":"experience"}},
  {"op":"feedback","params":{"query_id":"$0.query_id","selected":[548]}}
]'

Legacy compatibility API reference

Configuration

Local V1 env setup

The repo includes a root env template at .env.example.

What you need right now for the current V1 scaffold:

• NEON_DATABASE_URL for the Python daemon / CLI
• NERVE_LEGACY=1 only if you still need the deprecated nerve-v1 REST surface during migration
• INTERNAL_API_BASE_URL only if apps/web should talk to a daemon URL other than http://127.0.0.1:7420
• repo-root SQL migrations under migrations/ are applied by mnerve init and on daemon startup

What is documented but not yet required for the current scaffold:

• NERVE_AUTH_SECRET
• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• MICROSOFT_CLIENT_ID
• MICROSOFT_CLIENT_SECRET
• STRIPE_SECRET_KEY
• STRIPE_WEBHOOK_SECRET
• NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
• R2_*
• NERVE_DSN only if you intentionally override NEON_DATABASE_URL with another Neon DSN

Those V1 cloud variables are part of the target architecture, but the current web and desktop passes are still scaffold / contract-first for auth, billing, and companion flows. They should be requested when the corresponding runtime path is actually wired, not before.

For Google OAuth, keep the two redirect URIs distinct:

• Sign-in auth callback: http://localhost:3000/api/auth/google/callback
• Connector grant callback: http://127.0.0.1:7420/api/connectors/google/callback

For Microsoft connector OAuth:

• Connector grant callback: http://127.0.0.1:7420/api/connectors/microsoft/callback

In production, replace those origins with the real web and daemon base URLs.

Workspace RLS note

V1 tables use real PostgreSQL row-level security with current_setting('app.workspace_id')::uuid. The schema is in place, but the current daemon does not yet inject app.workspace_id on every connection checkout. Until workspace-scoped request plumbing lands, callers that query V1 tables directly must SET app.workspace_id = '<workspace-uuid>' on the session before issuing workspace-bound SQL.

Performance

Benchmarked on M4 Pro, single uvicorn worker:

Embedding inference runs through Cloudflare Workers AI in the V1 runtime; the Python daemon no longer loads a local embedding model on startup.

Contributing

# Dev setup
git clone https://github.com/maestro-ai-stack/maestro-nerve-internal.git maestro-nerve
cd maestro-nerve
pip install -e ".[dev,onnx]"

# Run tests
pytest tests/ -x -v

# Lint
ruff check src/ tests/

Harness

Canonical repo-level harness entrypoints:

scripts/harness-fast.sh
scripts/harness-python-fast.sh
scripts/harness-web-fast.sh
scripts/harness-web-smoke.sh
scripts/harness-desktop-fast.sh
scripts/harness-install-hooks.sh

What they do:

• scripts/harness-fast.sh: hygiene, import boundaries, Python fast lane, web fast lane, desktop fast lane
• scripts/harness-python-fast.sh: ruff + mypy + pytest-cov for the stable runtime lane
• scripts/harness-web-fast.sh: eslint + typecheck + vitest + next build
• scripts/harness-web-smoke.sh: Playwright smoke suite for landing, 404, and health route
• scripts/harness-desktop-fast.sh: desktop typecheck + build:ui + cargo check
• scripts/harness-install-hooks.sh: installs local pre-commit and pre-push hooks

License

MIT — see LICENSE.

Built by Maestro — Singapore AI product studio.