Compare commits
3 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 9802bdfd50 | |||
| 9215e765eb | |||
|
1931911eca |
234
GENOME.md
234
GENOME.md
@@ -1,234 +0,0 @@
|
||||
# GENOME.md — The Nexus Codebase Architecture Map
|
||||
|
||||
**Generated**: 2026-04-20
|
||||
**Repository**: Timmy_Foundation/the-nexus
|
||||
**Purpose**: Comprehensive map of the Nexus codebase for developers and AI agents.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The Nexus is Timmy's canonical 3D/world repository — a sovereign AI agent visualization surface and local-first training ground. It combines a Three.js 3D browser world with Python cognition components, WebSocket bridges, and fleet orchestration tools.
|
||||
|
||||
**Key Stats**:
|
||||
- ~357 source files
|
||||
- 201 Python files
|
||||
- 23 JavaScript files
|
||||
- 107 Markdown docs
|
||||
- 24 Shell scripts
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
the-nexus/
|
||||
├── app.js # Main Three.js 3D world (frontend entry)
|
||||
├── index.html # HTML shell
|
||||
├── style.css # Global styles
|
||||
├── server.py # WebSocket gateway
|
||||
├── gofai_worker.js # GOFAI web worker
|
||||
├── portals.json # Portal registry
|
||||
├── vision.json # Vision points config
|
||||
├── provenance.json # File integrity hashes
|
||||
│
|
||||
├── nexus/ # Python cognition layer
|
||||
│ ├── components/ # Frontend JS modules
|
||||
│ ├── mnemosyne/ # Memory system
|
||||
│ ├── mempalace/ # Long-term memory
|
||||
│ └── symbolic-engine.js # GOFAI rules
|
||||
│
|
||||
├── scripts/ # Operational scripts
|
||||
├── bin/ # CLI tools
|
||||
├── tests/ # Test suite
|
||||
├── docs/ # Documentation
|
||||
└── config/ # Configuration files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Frontend (Browser World)
|
||||
|
||||
### Entry Points
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `index.html` | HTML shell, HUD layout |
|
||||
| `app.js` | Main Three.js app (~141K lines) |
|
||||
| `style.css` | All styles (~61K) |
|
||||
| `gofai_worker.js` | Off-thread GOFAI reasoning |
|
||||
|
||||
### Core Systems
|
||||
| System | File | Description |
|
||||
|--------|------|-------------|
|
||||
| 3D World | `app.js` | Three.js scene, camera, rendering |
|
||||
| GOFAI | `app.js` | Symbolic rules, blackboard, planner |
|
||||
| Memory | `nexus/components/spatial-memory.js` | 3D memory crystals |
|
||||
| Audio | `nexus/components/spatial-audio.js` | Spatial sound system |
|
||||
| Portals | `portals.json` | External service links |
|
||||
| Chat | `app.js` | Chat panel and messaging |
|
||||
| HUD | `app.js` + `style.css` | Heads-up display |
|
||||
|
||||
### Components (`nexus/components/`)
|
||||
| Component | Purpose |
|
||||
|-----------|---------|
|
||||
| `spatial-memory.js` | 3D memory crystal visualization |
|
||||
| `spatial-audio.js` | Spatial sound for memories |
|
||||
| `memory-birth.js` | Memory creation animation |
|
||||
| `memory-pulse.js` | BFS pulse wave on click |
|
||||
| `memory-inspect.js` | Memory detail panel |
|
||||
| `memory-connections.js` | Connection graph |
|
||||
| `memory-particles.js` | Particle effects |
|
||||
| `memory-optimizer.js` | Memory cleanup |
|
||||
| `session-rooms.js` | Evennia room snapshots |
|
||||
| `timeline-scrubber.js` | Time navigation |
|
||||
| `resonance-visualizer.js` | Pattern visualization |
|
||||
| `portal-health-check.js` | Portal status monitoring |
|
||||
| `spatial-chat.js` | 3D audio chat notifications |
|
||||
|
||||
---
|
||||
|
||||
## Backend (Python)
|
||||
|
||||
### Core Services
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `server.py` | WebSocket gateway for real-time comms |
|
||||
| `multi_user_bridge.py` | Multi-user MUD bridge |
|
||||
| `gitea_api/` | Gitea API helpers |
|
||||
|
||||
### Scripts (`scripts/`)
|
||||
| Script | Purpose |
|
||||
|--------|---------|
|
||||
| `cleanup-duplicate-prs.sh` | Close duplicate PRs |
|
||||
| `check-existing-prs.sh` | Pre-flight PR check |
|
||||
| `pr_backlog_analyzer.py` | PR backlog analysis |
|
||||
| `audit_mempalace_privacy.py` | Privacy audit |
|
||||
| `provision-runner.sh` | Runner setup |
|
||||
| `runner_health_probe.sh` | Health monitoring |
|
||||
|
||||
### Bin Tools (`bin/`)
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `enforce_branch_protection.py` | Branch protection enforcement |
|
||||
| `check_duplicate_milestones.py` | Milestone cleanup |
|
||||
| `generate_provenance.py` | Provenance hash generation |
|
||||
|
||||
---
|
||||
|
||||
## Data Files
|
||||
|
||||
| File | Format | Purpose |
|
||||
|------|--------|---------|
|
||||
| `portals.json` | JSON | Portal registry (8 portals) |
|
||||
| `vision.json` | JSON | Vision points |
|
||||
| `world_state.json` | JSON | World state snapshot |
|
||||
| `provenance.json` | JSON | File integrity hashes |
|
||||
| `manifest.json` | JSON | PWA manifest |
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `.gitea/branch-protection/` | Branch protection rules |
|
||||
| `.github/workflows/` | CI/CD workflows |
|
||||
| `config/` | Runtime configuration |
|
||||
| `pytest.ini` | Test configuration |
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
| Directory | Coverage |
|
||||
|-----------|----------|
|
||||
| `tests/` | Unit and integration tests |
|
||||
| `tests/test_provenance.py` | File integrity tests |
|
||||
| `tests/test_spatial_search.js` | Spatial search tests |
|
||||
|
||||
Run tests:
|
||||
```bash
|
||||
python3 -m pytest tests/ -v
|
||||
node --test tests/*.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Patterns
|
||||
|
||||
### Component Pattern
|
||||
```javascript
|
||||
const ComponentName = (() => {
|
||||
let _state = null;
|
||||
|
||||
function init(config) { ... }
|
||||
function update(delta) { ... }
|
||||
|
||||
return { init, update };
|
||||
})();
|
||||
|
||||
export { ComponentName };
|
||||
```
|
||||
|
||||
### WebSocket Pattern
|
||||
```python
|
||||
async def handler(websocket):
|
||||
async for message in websocket:
|
||||
# Process and broadcast
|
||||
pass
|
||||
```
|
||||
|
||||
### Portal Schema
|
||||
```json
|
||||
{
|
||||
"id": "portal-id",
|
||||
"name": "Display Name",
|
||||
"portal_type": "game-world",
|
||||
"destination": { "url": "...", "type": "harness" }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
- WebSocket gateway binds to `127.0.0.1` by default
|
||||
- Optional token authentication via `NEXUS_WS_TOKEN`
|
||||
- Rate limiting on connections and messages
|
||||
- Branch protection on `main`
|
||||
- Provenance hash verification
|
||||
|
||||
See `SECURITY.md` for full details.
|
||||
|
||||
---
|
||||
|
||||
## Related Repos
|
||||
|
||||
| Repo | Relationship |
|
||||
|------|--------------|
|
||||
| `timmy-config` | Configuration and fleet management |
|
||||
| `hermes-agent` | Agent runtime |
|
||||
| `timmy-home` | SOUL.md and core docs |
|
||||
| `the-door` | Crisis detection system |
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Clone
|
||||
git clone https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus.git
|
||||
|
||||
# Run WebSocket gateway
|
||||
python3 server.py
|
||||
|
||||
# Open browser world
|
||||
open index.html
|
||||
|
||||
# Run tests
|
||||
python3 -m pytest tests/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*This GENOME.md is auto-maintained. Update when adding major new systems.*
|
||||
@@ -1,9 +1,13 @@
|
||||
{
|
||||
"version": 1,
|
||||
"generated": "2026-04-06",
|
||||
"refs": ["#836", "#204", "#195", "#196"],
|
||||
"refs": [
|
||||
"#836",
|
||||
"#204",
|
||||
"#195",
|
||||
"#196"
|
||||
],
|
||||
"description": "Canonical fleet routing table. Evaluated agents, routing verdicts, and dispatch rules for the Timmy Foundation task harness.",
|
||||
|
||||
"agents": [
|
||||
{
|
||||
"id": 27,
|
||||
@@ -46,12 +50,14 @@
|
||||
"location": "Bag End, The Shire (VPS)",
|
||||
"description": "Ollama on VPS. Speaks when spoken to. Prefers quiet. Not for delegated work.",
|
||||
"primary_role": "on-request-queries",
|
||||
"routing_verdict": "ROUTE TO: background monitoring, status checks, low-priority Q&A. Only on-request — do not delegate autonomously.",
|
||||
"routing_verdict": "ROUTE TO: background monitoring, status checks, low-priority Q&A. Only on-request \u2014 do not delegate autonomously.",
|
||||
"active": true,
|
||||
"do_not_route": false,
|
||||
"created": "2026-04-02",
|
||||
"repo_count": 1,
|
||||
"repos": ["bilbobagginshire/bilbo-adventures"]
|
||||
"repos": [
|
||||
"bilbobagginshire/bilbo-adventures"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 24,
|
||||
@@ -60,7 +66,7 @@
|
||||
"model": "codex",
|
||||
"tier": "prepaid",
|
||||
"location": "The Harness",
|
||||
"description": "OpenClaw bridge. Protocol adapter layer — not a personality. Infrastructure, not a destination.",
|
||||
"description": "OpenClaw bridge. Protocol adapter layer \u2014 not a personality. Infrastructure, not a destination.",
|
||||
"primary_role": "protocol-bridge",
|
||||
"routing_verdict": "DO NOT ROUTE directly. claw-code is the bridge to external Codex agents, not an endpoint. Remove from routing cascade.",
|
||||
"active": true,
|
||||
@@ -79,7 +85,7 @@
|
||||
"location": "Below the Surface",
|
||||
"description": "Infrastructure, deployments, bedrock services. Needs model assignment before activation.",
|
||||
"primary_role": "devops",
|
||||
"routing_verdict": "DO NOT ROUTE — no model assigned yet. Activate after Epic #196 (Local Model Fleet) assigns a model.",
|
||||
"routing_verdict": "DO NOT ROUTE \u2014 no model assigned yet. Activate after Epic #196 (Local Model Fleet) assigns a model.",
|
||||
"active": false,
|
||||
"do_not_route": true,
|
||||
"do_not_route_reason": "No model assigned. Blocked on Epic #196.",
|
||||
@@ -97,13 +103,15 @@
|
||||
"location": "The Archive",
|
||||
"description": "Original prototype. Museum piece. Preserved for historical reference only.",
|
||||
"primary_role": "inactive",
|
||||
"routing_verdict": "DO NOT ROUTE — retired from active duty. Preserved only.",
|
||||
"routing_verdict": "DO NOT ROUTE \u2014 retired from active duty. Preserved only.",
|
||||
"active": false,
|
||||
"do_not_route": true,
|
||||
"do_not_route_reason": "Retired prototype. Historical preservation only.",
|
||||
"created": "2026-03-31",
|
||||
"repo_count": 1,
|
||||
"repos": ["allegro-primus/first-steps"]
|
||||
"repos": [
|
||||
"allegro-primus/first-steps"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
@@ -120,7 +128,10 @@
|
||||
"gap": "Agent description is empty in Gitea profile. Needs enrichment.",
|
||||
"created": "2026-03-14",
|
||||
"repo_count": 2,
|
||||
"repos": ["kimi/the-nexus-fork", "kimi/Timmy-time-dashboard"]
|
||||
"repos": [
|
||||
"kimi/the-nexus-fork",
|
||||
"kimi/Timmy-time-dashboard"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 20,
|
||||
@@ -148,10 +159,10 @@
|
||||
"id": 19,
|
||||
"name": "ezra",
|
||||
"gitea_user": "ezra",
|
||||
"model": "claude",
|
||||
"model": "kimi-coding/kimi-k2.5",
|
||||
"tier": "prepaid",
|
||||
"location": "Hermes VPS",
|
||||
"description": "Archivist. Claude-Hermes wizard. 9 repos owned — most in the fleet. Handles complex multi-file and cross-repo work.",
|
||||
"description": "Archivist. Research and triage wizard. 9 repos owned \u2014 most in the fleet. Handles complex multi-file and cross-repo work.",
|
||||
"primary_role": "documentation",
|
||||
"routing_verdict": "ROUTE TO: docs, specs, architecture, complex multi-file work. Escalate here when breadth and precision both matter.",
|
||||
"active": true,
|
||||
@@ -176,7 +187,7 @@
|
||||
"gitea_user": "bezalel",
|
||||
"model": "groq",
|
||||
"tier": "free",
|
||||
"location": "TestBed VPS — The Forge",
|
||||
"location": "TestBed VPS \u2014 The Forge",
|
||||
"description": "Builder, debugger, testbed wizard. Groq-powered, free tier. Strong on PR review and CI.",
|
||||
"primary_role": "code-review",
|
||||
"routing_verdict": "ROUTE TO: PR review, test writing, debugging, CI fixes.",
|
||||
@@ -184,29 +195,39 @@
|
||||
"do_not_route": false,
|
||||
"created": "2026-03-29",
|
||||
"repo_count": 1,
|
||||
"repos": ["bezalel/forge-log"]
|
||||
"repos": [
|
||||
"bezalel/forge-log"
|
||||
]
|
||||
}
|
||||
],
|
||||
|
||||
"routing_cascade": {
|
||||
"description": "Cost-optimized routing cascade — cheapest capable agent first, escalate on complexity.",
|
||||
"description": "Cost-optimized routing cascade \u2014 cheapest capable agent first, escalate on complexity.",
|
||||
"tiers": [
|
||||
{
|
||||
"tier": 1,
|
||||
"label": "Free",
|
||||
"agents": ["fenrir", "bezalel", "carnice"],
|
||||
"agents": [
|
||||
"fenrir",
|
||||
"bezalel",
|
||||
"carnice"
|
||||
],
|
||||
"use_for": "Issue triage, code review, local code generation. Default lane for most tasks."
|
||||
},
|
||||
{
|
||||
"tier": 2,
|
||||
"label": "Cheap",
|
||||
"agents": ["kimi", "allegro"],
|
||||
"use_for": "Small scoped edits (kimi ≤3 files), triage decisions and routing (allegro)."
|
||||
"agents": [
|
||||
"kimi",
|
||||
"allegro"
|
||||
],
|
||||
"use_for": "Small scoped edits (kimi \u22643 files), triage decisions and routing (allegro)."
|
||||
},
|
||||
{
|
||||
"tier": 3,
|
||||
"label": "Premium / Escalate",
|
||||
"agents": ["ezra"],
|
||||
"agents": [
|
||||
"ezra"
|
||||
],
|
||||
"use_for": "Complex multi-file work, docs, architecture. Escalate only."
|
||||
}
|
||||
],
|
||||
@@ -217,22 +238,48 @@
|
||||
"allegro-primus: retired, do not route"
|
||||
]
|
||||
},
|
||||
|
||||
"task_type_map": {
|
||||
"issue-triage": ["fenrir", "allegro"],
|
||||
"code-generation": ["carnice", "ezra"],
|
||||
"code-review": ["bezalel"],
|
||||
"small-edit": ["kimi"],
|
||||
"debugging": ["bezalel", "carnice"],
|
||||
"documentation": ["ezra"],
|
||||
"architecture": ["ezra"],
|
||||
"ci-fixes": ["bezalel"],
|
||||
"pr-review": ["bezalel", "fenrir"],
|
||||
"triage-routing": ["allegro"],
|
||||
"devops": ["substratum"],
|
||||
"background-monitoring": ["bilbobagginshire"]
|
||||
"issue-triage": [
|
||||
"fenrir",
|
||||
"allegro"
|
||||
],
|
||||
"code-generation": [
|
||||
"carnice",
|
||||
"ezra"
|
||||
],
|
||||
"code-review": [
|
||||
"bezalel"
|
||||
],
|
||||
"small-edit": [
|
||||
"kimi"
|
||||
],
|
||||
"debugging": [
|
||||
"bezalel",
|
||||
"carnice"
|
||||
],
|
||||
"documentation": [
|
||||
"ezra"
|
||||
],
|
||||
"architecture": [
|
||||
"ezra"
|
||||
],
|
||||
"ci-fixes": [
|
||||
"bezalel"
|
||||
],
|
||||
"pr-review": [
|
||||
"bezalel",
|
||||
"fenrir"
|
||||
],
|
||||
"triage-routing": [
|
||||
"allegro"
|
||||
],
|
||||
"devops": [
|
||||
"substratum"
|
||||
],
|
||||
"background-monitoring": [
|
||||
"bilbobagginshire"
|
||||
]
|
||||
},
|
||||
|
||||
"gaps": [
|
||||
{
|
||||
"agent": "substratum",
|
||||
@@ -255,12 +302,11 @@
|
||||
"action": "Run wolf evaluation on active agents (#195) to replace vibes-based routing with data."
|
||||
}
|
||||
],
|
||||
|
||||
"next_actions": [
|
||||
"Assign model to substratum — Epic #196",
|
||||
"Run wolf evaluation on active agents — Issue #195",
|
||||
"Remove claw-code from routing cascade — it is infrastructure, not a destination",
|
||||
"Assign model to substratum \u2014 Epic #196",
|
||||
"Run wolf evaluation on active agents \u2014 Issue #195",
|
||||
"Remove claw-code from routing cascade \u2014 it is infrastructure, not a destination",
|
||||
"Enrich kimi's Gitea profile description",
|
||||
"Wire fleet-routing.json into workforce-manager.py — Epic #204"
|
||||
"Wire fleet-routing.json into workforce-manager.py \u2014 Epic #204"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -7,13 +7,13 @@
|
||||
|
||||
## Role
|
||||
|
||||
Dedicated reasoning and architecture wizard. Claude-native.
|
||||
Dedicated research and triage wizard. Kimi-native.
|
||||
|
||||
## Routing
|
||||
|
||||
Route to Hermes Trismegistus when:
|
||||
- Task requires deep architectural reasoning
|
||||
- Novel problem-solving that benefits from Claude's reasoning depth
|
||||
- Novel problem-solving that benefits from strong reasoning depth
|
||||
- Planning and design decisions for the fleet
|
||||
- Complex multi-step analysis that goes beyond code generation
|
||||
|
||||
|
||||
@@ -160,7 +160,7 @@
|
||||
}
|
||||
},
|
||||
"agents_present": [
|
||||
"claude"
|
||||
"ezra"
|
||||
],
|
||||
"interaction_ready": true
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user