Skip to content

kapella-hub/NexusStack

BranchesTags

Repository files navigation

NexusStack

Unified cognitive stack for AI agents. Five services, one deployment, complete agent infrastructure.

Local Machine                              VPS
┌──────────────┐                         ┌────────────────────────────────────┐
│              │                         │ NexusCortex    :8100 (API)        │
│ Claude Code  │ ◄──── MCP over HTTP ──► │                :8080 (MCP)        │
│              │                         │ NexusBridge    :8070 (MCP)        │
│              │                         │ NexusSentinel  :8060 (MCP)        │
│              │                         │ NexusRelay     :8050 (MCP)        │
│              │                         │ NexusSymdex    :8090 (MCP)        │
│              │          Browser        │ Dashboard      :8040 (Web UI)     │
│              │ ─────────────────────►  │                                   │
└──────────────┘                         │ Neo4j, Qdrant, Redis, Ollama     │
                                         └────────────────────────────────────┘

What Each Service Does

Service Purpose Storage
NexusCortex Long-term memory — semantic + graph RAG, knowledge lifecycle, sleep cycle consolidation Neo4j + Qdrant + Redis
NexusBridge Session context — working state persistence across context compressions, distills to Cortex Redis (DB 3)
NexusSentinel Environment observer — Docker health, git activity, file changes, webhook intake Redis (DB 4)
NexusRelay Agent communication — real-time pub/sub channels, persistent bulletin board, resource claims Redis (DB 5)
NexusSymdex Code intelligence — tree-sitter AST parsing, 32+ MCP tools for symbol-level code exploration Local JSON indexes
Dashboard Unified web UI — 6-tab SPA for monitoring and interacting with all services Static HTML (nginx)

Quick Start

VPS Deployment

git clone https://github.com/kapella-hub/NexusStack.git
cd NexusStack
bash install.sh

The installer will:

  1. Check Docker and Docker Compose are available
  2. Prompt for your VPS IP, Neo4j password, and optional API key
  3. Build and start all 14 containers
  4. Run health checks and print MCP URLs

Local Setup (Claude Code Integration)

# Linux / macOS
bash local-setup.sh

# Windows (PowerShell)
.\local-setup.ps1

This will:

  1. Install NexusSymdex locally for the Claude Code plugin (hooks + skills)
  2. Write .mcp.json — all 5 MCP servers (project scope)
  3. Write .claude/settings.json — session hooks, symdex plugin, env vars (project scope)
  4. Clean user-scope ~/.claude.json and ~/.claude/settings.json of any NexusStack entries

All config is project-scoped — it only activates when Claude Code runs inside the NexusStack directory. The Symdex MCP server itself runs on the VPS via Docker; the local install is only for the Claude Code plugin that provides session hooks and pre-edit checks.

Update

bash update.sh

Pulls latest, rebuilds changed images, restarts services, verifies health.

Service Map

Port Service Container Protocol
8100 Cortex API cortex-api REST
8080 Cortex MCP cortex-mcp MCP (HTTP)
8070 NexusBridge bridge MCP (HTTP)
8060 NexusSentinel sentinel MCP (HTTP)
8050 NexusRelay relay MCP (HTTP)
8090 NexusSymdex symdex MCP (HTTP)
8040 Dashboard dashboard HTTP (nginx)
7687 Neo4j neo4j Bolt (localhost)
6333 Qdrant qdrant gRPC (localhost)
6379 Redis redis Redis (localhost)
11434 Ollama ollama HTTP (localhost)

Infrastructure ports are bound to 127.0.0.1 only. Application ports are on 0.0.0.0.

Repository Structure

NexusStack/
├── symdex/              # NexusSymdex — code intelligence
│   ├── src/nexus_symdex/
│   ├── tests/
│   ├── pyproject.toml
│   └── Dockerfile       # HTTP mode for VPS
├── cortex/              # NexusCortex — long-term memory
│   ├── app/
│   ├── tests/
│   ├── requirements.txt
│   └── Dockerfile
├── bridge/              # NexusBridge — session context
│   ├── app/
│   ├── tests/
│   ├── requirements.txt
│   └── Dockerfile
├── sentinel/            # NexusSentinel — environment observer
│   ├── app/
│   ├── requirements.txt
│   └── Dockerfile
├── relay/               # NexusRelay — agent communication
│   ├── app/
│   ├── requirements.txt
│   └── Dockerfile
├── dashboard/           # Unified web dashboard
│   ├── index.html
│   └── nginx.conf
├── docs/
│   └── DESIGN.md        # Full architecture design spec
├── docker-compose.yml   # All 14 containers
├── .env.example         # Combined configuration
├── install.sh           # Fresh VPS setup
├── update.sh            # Pull + rebuild + restart
├── local-setup.sh       # Local setup (Linux/macOS)
├── local-setup.ps1      # Local setup (Windows)
├── .mcp.json            # MCP server config (project scope, generated)
├── .claude/
│   └── settings.json    # Hooks + plugin config (project scope, generated)
├── CLAUDE.md            # AI agent instructions
└── README.md

Configuration

All configuration is via environment variables in .env. Copy the example and edit:

cp .env.example .env

Key Settings

Variable Default Description
NEO4J_PASSWORD (required) Neo4j database password
API_KEY (optional) API key for Cortex authentication
CORS_ORIGINS ["*"] Allowed CORS origins (set to dashboard URL)
LLM_MODEL qwen3:4b Ollama model for LLM inference
EMBEDDING_MODEL mxbai-embed-large Embedding model
MULTIHOP_ENABLED True Enable multi-hop graph traversal
RANKER_ENABLED False Enable ML recall ranker (needs feedback data)
NB_PROACTIVE_RECALL_ENABLED True Auto-inject memories on ctx_update

Redis DB Allocation

DB Service Prefix
0 Cortex data —
1 Celery broker —
2 Celery results —
3 NexusBridge nb:
4 NexusSentinel ns:
5 NexusRelay nr:

Environment Variable Prefixes

Prefix Service
NB_ NexusBridge
NS_ NexusSentinel
NR_ NexusRelay
NEXUS_SYMDEX_ NexusSymdex

Intelligence Features

NexusCortex includes several intelligence layers that improve recall quality over time:

Memory Type Classification

Every memory is typed as reference (no decay), procedural (180-day half-life), episodic (90-day, default), or transient (14-day). The sleep cycle LLM auto-classifies new memories. This prevents important reference knowledge from being buried by time-based decay.

Multi-hop Graph Reasoning

Graph queries traverse up to 3 hops with 0.5x score decay per hop, finding indirect connections like "auth → middleware → CORS" that single-hop queries miss. Enabled by default (MULTIHOP_ENABLED=True).

User Profile Model

The memory agent (Pass 7) automatically extracts your skills, preferences, and goals from your memory corpus into Person→Skill/Preference/Goal nodes in Neo4j. Recall results are boosted for domains matching your expertise. The profile builds itself over time — no manual configuration needed.

Proactive Recall

When you call ctx_update with a plan or progress update, NexusBridge automatically queries NexusCortex for relevant past experience and injects it into your session shadow under "Relevant Past Experience." Agents get context without asking.

Episodic Memory

Session distillation preserves the full sequence of decisions and progress (connected with →) instead of flattening to a summary. File paths are included. This means future recalls return rich narratives, not just facts.

Recall Ranker (optional)

A GradientBoosting model trained on your feedback data to re-rank recall results. Disabled by default — enable with RANKER_ENABLED=True after accumulating feedback via /memory/feedback.

Embedding Fine-tuning (optional)

Generate training triplets from your memory corpus and fine-tune the embedding model with POST /admin/embeddings/finetune. Requires sentence-transformers to be installed manually (heavy dependency, not included by default).

MCP Tools Reference

NexusBridge (session context)

Tool Purpose
ctx_start_session Start a new working session with a goal
ctx_update Record plan, decisions, file knowledge, progress, or scratch notes
ctx_get_shadow Retrieve full working context as Markdown
ctx_complete_session Complete session and distill learnings to Cortex
ctx_abandon_session Abandon session without saving
ctx_list_sessions List sessions filtered by status/agent
ctx_resume_session Resume a paused session

NexusSentinel (environment observer)

Tool Purpose
sentinel_get_events Get recent events (filter by source/type/severity)
sentinel_get_health Health status of all Docker services
sentinel_watch Register interest in a path/repo/service
sentinel_unwatch Remove a watch
sentinel_push_event Push an agent observation as an event

NexusRelay (agent communication)

Tool Purpose
relay_broadcast Send message to a real-time channel
relay_get_messages Get recent messages from channel backlog
relay_post Post to the persistent bulletin board
relay_read Read bulletin board (filter by tags/author)
relay_claim Claim a resource to prevent duplicate work
relay_release Release a claimed resource
relay_status Active agents, channels, claims overview

NexusCortex (memory)

Tool Purpose
memory_recall Query memories with semantic + graph search
memory_learn Store action/outcome pairs
memory_stream Ingest raw events for batch processing
memory_health Check memory service health

NexusSymdex (code intelligence)

32+ tools including index_folder, get_context, search_symbols, get_architecture_map, find_dead_code, get_review_context, and more. See symdex/README.md for the full list.

Dashboard

Access at http://<VPS_IP>:8040 after deployment.

6 tabs:

  • Overview — Health grid for all services, quick stats, auto-refresh
  • Memory — Search/browse Cortex memories, manual text input form
  • Sessions — View Bridge sessions, inspect shadow context
  • Events — Live event feed from Sentinel, severity filtering
  • Relay — Bulletin board, post form, channel activity, claims
  • Code — Symbol search via Symdex (when VPS instance is indexed)

The dashboard is a zero-dependency static SPA (dashboard/index.html). Edit the CONFIG object at the top of the JavaScript to change service URLs.

Development

Running Tests

# Per-service
cd cortex && pytest tests/ -v      # 503 tests
cd bridge && pytest tests/ -v      # 70 tests
cd sentinel && pytest tests/ -v    # 31 tests
cd relay && pytest tests/ -v       # 28 tests

# Symdex (requires uv)
cd symdex && uv run pytest tests/ -v  # 507 tests

Adding a Service

  1. Create a new directory with app/, requirements.txt, Dockerfile
  2. Follow the patterns in bridge/ (simplest service) or sentinel/ (with REST + MCP)
  3. Add to docker-compose.yml
  4. Add config section to .env.example
  5. Add a tab to dashboard/index.html

Tech Stack

  • Language: Python 3.11+
  • API Framework: FastAPI
  • MCP Framework: FastMCP (HTTP transport with stateless_http=True)
  • Config: Pydantic Settings (env-based)
  • Databases: Neo4j 5.x, Qdrant, Redis 7
  • LLM: Ollama (OpenAI-compatible API)
  • Deployment: Docker Compose
  • Dashboard: Vanilla HTML/CSS/JS, nginx

Architecture

See docs/DESIGN.md for the full design specification including:

  • Detailed service descriptions and MCP tool definitions
  • Docker Compose dependency chain
  • Integration points between services
  • Operational notes (Redis trade-offs, logging, backups, migrations)

License

Private repository. All rights reserved.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages