Opus Nx turns model reasoning traces into persistent, inspectable artifacts you can explore, verify, rerun, and improve. Every thinking step becomes a node in a navigable graph — not a black box.

This repository is positioned for research and open-source collaboration. Run it locally with your own credentials.

A live reasoning session: 17 thinking nodes, typed edges (influence, support, contradiction, refinement), compaction boundaries, and fork branches — all persisted and queryable.

Most AI workflows keep only final answers. Opus Nx keeps the entire reasoning path and supports policy improvement over time.

Full visual walkthrough with all screenshots: docs/features.md

Every extended thinking session becomes a graph of discrete reasoning steps — nodes scored for confidence, connected by typed edges showing how ideas flow, branch, and build on each other.

Reasoning nodes colored by type (thinking, compaction, fork branch) with edges showing influence, support, contradiction, and refinement relationships. Minimap in corner for navigation.

Deploy a swarm of 6 specialized AI agents that collaborate in real-time via WebSocket streaming. Maestro decomposes the problem, DeepThinker analyzes, Contrarian challenges, Verifier validates, Synthesizer merges, and Metacognition audits.

The Synthesizer agent merging perspectives from all agents into a coherent framework, with live session stats (17 nodes, 62K tokens) and human-in-the-loop checkpoints.

Explore problems using arbitrary reasoning graphs with BFS, DFS, or best-first search. Thoughts branch, aggregate, and get verified at each depth level — a visual implementation of Besta et al. (2023).

A 4-depth GoT tree with 8 branches. Each node shows its thought, confidence score (40%-94%), verification status (Verified/Aggregated), and reasoning path. Color-coded by depth level.

Process Reward Model verifies each reasoning step independently. See structured steps (CONSIDERATION → HYPOTHESIS → EVALUATION → CONCLUSION) with confidence scores, decision counts, and edge relationships.

13 structured reasoning steps extracted from a single thinking pass. Each step typed (Consideration, Hypothesis, Evaluation, Conclusion) with 1.6K thinking tokens and 13 decision points persisted.

Final steps: EVALUATION → MAIN CONCLUSION → MODEL OUTPUT. The reasoning chain ends with a persisted artifact showing both the internal deliberation and the final structured response.

Fork any question into 4 concurrent reasoning styles: conservative, aggressive, balanced, and contrarian. Each branch reasons independently, then results are compared with confidence scores and key points.

Left: Fork analysis showing 4 perspectives with confidence scores (45%–82%) and synthesis. Right: Metacognitive Insights panel with 3 biases, 3 patterns, and 1 improvement idea detected.

A 3-tier memory system: working context (active reasoning), recall buffer (recent history), and archival storage (long-term knowledge). Entries persist across sessions with semantic search and importance scoring.

Left: Memory hierarchy showing 4 entries in Main Context, 4 in Recall, with importance scores and source types. Right: Session stats with confidence breakdown and token usage visualization.

1. ThinkGraph — Persistent reasoning graphs with queryable nodes and typed edges
2. ThinkFork — 4-style branching, steering, and debate mode
3. PRM Verification — Step-level verification with structured reasoning extraction
4. Agent Swarm — 6-agent orchestration with WebSocket streaming
5. Graph of Thoughts — BFS/DFS/best-first search over thought trees
6. Metacognitive Insights — Bias detection, pattern recognition, improvement hypotheses
7. Memory Hierarchy — 3-tier MemGPT-style memory with semantic retrieval
8. Hypothesis Lifecycle — Promote → rerun → compare → retain loops
9. Session Sharing — Persistent sessions with replay and sharing
10. Evaluation Harnesses — Retrieval benchmarks and quality metrics

Two-service runtime with shared persistence:

Browser
  -> Next.js web app (apps/web)
      -> packages/core reasoning modules
      -> packages/db Supabase access
      -> swarm proxy routes
  -> Python FastAPI swarm service (agents)
  -> Supabase Postgres + pgvector

See full architecture details: docs/architecture.md

git clone https://github.com/omerakben/opus-nx.git
cd opus-nx
./scripts/dev-start.sh

The setup script handles everything: prerequisites check, dependency install, env bootstrap, connection verify, build, and launch. It will prompt you for API credentials on first run.

Run everything locally with just an Anthropic API key — no Supabase cloud account needed. Data stays on your machine.

Prerequisites: Docker, Node.js 22+, pnpm. Optional: Python 3.12+ and uv for the agent swarm.

git clone https://github.com/omerakben/opus-nx.git
cd opus-nx
./scripts/docker-start.sh

The script handles everything: checks prerequisites, copies .env.docker to .env, prompts for your Anthropic API key, starts a local PostgreSQL + pgvector database in Docker, installs all dependencies, builds the project, and launches the dev servers.

When it's done, open http://localhost:3000 in your browser.

Or step by step:

cp .env.docker .env
# Edit .env → add your ANTHROPIC_API_KEY

docker compose -f docker-compose.local.yml up -d    # Start local DB
pnpm install && pnpm build && pnpm dev              # Install, build, run

# Lifecycle
./scripts/docker-start.sh --stop       # Stop everything (dev servers + database)
./scripts/docker-start.sh --reset      # Wipe database and start fresh
./scripts/docker-start.sh --db-only    # Start only the database (no dev servers)

# Database access
docker exec -it opus-nx-postgres psql -U postgres -d opus_nx  # Direct SQL access
docker compose -f docker-compose.local.yml logs -f postgres   # Stream DB logs

1. Node.js >= 22
2. pnpm 9.x
3. Python 3.12+
4. uv

git clone https://github.com/omerakben/opus-nx.git
cd opus-nx
pnpm install

pnpm setup

This creates .env and agents/.env if missing and aligns AUTH_SECRET across both files.

Required values:

1. ANTHROPIC_API_KEY
2. AUTH_SECRET
3. SUPABASE_URL
4. SUPABASE_SERVICE_ROLE_KEY
5. SUPABASE_ANON_KEY

pnpm setup:verify

pnpm dev

Optional local swarm backend:

cd agents
uv run uvicorn src.main:app --reload --port 8000

Use your own provider accounts and keys.

• Do not rely on maintainer personal credentials
• Keep AUTH_SECRET consistent across web and agents
• Treat demo mode as optional (DEMO_MODE=true only when intentionally enabled)

pnpm dev                        # Start all dev servers
pnpm lint                       # Lint all packages
pnpm typecheck                  # Type-check all packages
pnpm test                       # Run tests
pnpm db:migrate                 # Run Supabase migrations
pnpm setup                      # Bootstrap env files
pnpm setup:verify               # Verify API connections
./scripts/dev-start.sh          # Full setup + launch (recommended)
./scripts/docker-start.sh       # Docker local DB + dev servers
./scripts/docker-start.sh --db-only  # Docker DB only (no dev servers)

Agent tests:

cd agents
uv run pytest

• POST /api/thinking — Extended thinking request
• POST /api/thinking/stream — SSE streaming for thinking deltas
• POST /api/fork — ThinkFork parallel reasoning
• POST /api/verify — PRM step-by-step verification
• POST /api/got — Graph of Thoughts reasoning

• GET/POST /api/sessions — List/create sessions
• GET /api/sessions/[sessionId]/nodes — Get thinking nodes
• GET /api/reasoning/[id] — Get reasoning node details

• POST /api/swarm — Initiate multi-agent swarm
• GET /api/swarm/token — WebSocket auth token
• POST /api/swarm/[sessionId]/checkpoint — Human-in-the-loop checkpoint

• GET/POST /api/memory — Hierarchical memory operations
• GET/POST /api/insights — Metacognitive insights

Implemented concepts are grounded in:

See:

• docs/reasoning-artifacts-research-charter.md
• docs/evals/reasoning-artifacts-v1.md
• RESEARCH.md

• Visual feature guide: docs/features.md
• Canonical docs index: docs/README.md
• PRD: docs/prd.md
• Architecture: docs/architecture.md
• Runbooks: docs/runbooks/
• Historical docs archive: docs/archive/build-history/

Contributions are welcome.

• Contribution guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md

Priority areas:

1. Reasoning quality and evaluation rigor
2. Setup ergonomics and onboarding
3. Lifecycle and experiment UX
4. Reliability and observability

Ozzy — AI Engineer & Full-Stack Developer

TUEL AI — AI Research Platform

Claude — AI Research Partner (Anthropic)

A human + AI collaboration exploring persistent reasoning artifacts.

MIT