Compare commits
3 Commits
fix/1644
...
fix/1601-m
| Author | SHA1 | Date | |
|---|---|---|---|
| b5ddf317d3 | |||
| 681b92646e | |||
|
d99976dc8b |
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.*
|
||||
190
app.js
190
app.js
@@ -3903,189 +3903,7 @@ init().then(() => {
|
||||
navigator.serviceWorker.register('/service-worker.js');
|
||||
}
|
||||
|
||||
// Initialize MemPalace memory system
|
||||
function connectMemPalace() {
|
||||
try {
|
||||
// Initialize MemPalace MCP server
|
||||
console.log('Initializing MemPalace memory system...');
|
||||
|
||||
// Actual MCP server connection
|
||||
const statusEl = document.getElementById('mem-palace-status');
|
||||
if (statusEl) {
|
||||
statusEl.textContent = 'MemPalace ACTIVE';
|
||||
statusEl.style.color = '#4af0c0';
|
||||
statusEl.style.textShadow = '0 0 10px #4af0c0';
|
||||
}
|
||||
|
||||
// Initialize MCP server connection
|
||||
if (window.Claude && window.Claude.mcp) {
|
||||
window.Claude.mcp.add('mempalace', {
|
||||
init: () => {
|
||||
return { status: 'active', version: '3.0.0' };
|
||||
},
|
||||
search: (query) => {
|
||||
return new Promise((query) => {
|
||||
setTimeout(() => {
|
||||
resolve([
|
||||
{
|
||||
id: '1',
|
||||
content: 'MemPalace: Palace architecture, AAAK compression, knowledge graph',
|
||||
score: 0.95
|
||||
},
|
||||
{
|
||||
id: '2',
|
||||
content: 'AAAK compression: 30x lossless compression for AI agents',
|
||||
score: 0.88
|
||||
}
|
||||
]);
|
||||
}, 500);
|
||||
});
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// Initialize memory stats tracking
|
||||
document.getElementById('compression-ratio').textContent = '0x';
|
||||
document.getElementById('docs-mined').textContent = '0';
|
||||
document.getElementById('aaak-size').textContent = '0B';
|
||||
} catch (err) {
|
||||
console.error('Failed to initialize MemPalace:', err);
|
||||
const statusEl = document.getElementById('mem-palace-status');
|
||||
if (statusEl) {
|
||||
statusEl.textContent = 'MemPalace ERROR';
|
||||
statusEl.style.color = '#ff4466';
|
||||
statusEl.style.textShadow = '0 0 10px #ff4466';
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Initialize MemPalace
|
||||
const mempalace = {
|
||||
status: { compression: 0, docs: 0, aak: '0B' },
|
||||
mineChat: () => {
|
||||
try {
|
||||
const messages = Array.from(document.querySelectorAll('.chat-msg')).map(m => m.innerText);
|
||||
if (messages.length > 0) {
|
||||
// Actual MemPalace mining
|
||||
const wing = 'nexus_chat';
|
||||
const room = 'conversation_history';
|
||||
|
||||
messages.forEach((msg, idx) => {
|
||||
// Store in MemPalace
|
||||
window.mempalace.add_drawer({
|
||||
wing,
|
||||
room,
|
||||
content: msg,
|
||||
metadata: {
|
||||
type: 'chat',
|
||||
timestamp: Date.now() - (messages.length - idx) * 1000
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
// Update stats
|
||||
mempalace.status.docs += messages.length;
|
||||
mempalace.status.compression = Math.min(100, mempalace.status.compression + (messages.length / 10));
|
||||
mempalace.status.aak = `${Math.floor(parseInt(mempalace.status.aak.replace('B', '')) + messages.length * 30)}B`;
|
||||
|
||||
updateMemPalaceStatus();
|
||||
}
|
||||
} catch (error) {
|
||||
console.error('MemPalace mine failed:', error);
|
||||
document.getElementById('mem-palace-status').textContent = 'Mining Error';
|
||||
document.getElementById('mem-palace-status').style.color = '#ff4466';
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
// Mine chat history to MemPalace with AAAK compression
|
||||
function mineChatToMemPalace() {
|
||||
const messages = Array.from(document.querySelectorAll('.chat-msg')).map(m => m.innerText);
|
||||
if (messages.length > 0) {
|
||||
try {
|
||||
// Convert to AAAK format
|
||||
const aaakContent = messages.map(msg => {
|
||||
const lines = msg.split('\n');
|
||||
return lines.map(line => {
|
||||
// Simple AAAK compression pattern
|
||||
return line.replace(/(\w+): (.+)/g, '$1: $2')
|
||||
.replace(/(\d{4}-\d{2}-\d{2})/, 'DT:$1')
|
||||
.replace(/(\d+ years?)/, 'T:$1');
|
||||
}).join('\n');
|
||||
}).join('\n---\n');
|
||||
|
||||
mempalace.add({
|
||||
content: aaakContent,
|
||||
wing: 'nexus_chat',
|
||||
room: 'conversation_history',
|
||||
tags: ['chat', 'conversation', 'user_interaction']
|
||||
});
|
||||
|
||||
updateMemPalaceStatus();
|
||||
} catch (error) {
|
||||
console.error('MemPalace mining failed:', error);
|
||||
document.getElementById('mem-palace-status').textContent = 'Mining Error';
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function updateMemPalaceStatus() {
|
||||
try {
|
||||
const stats = mempalace.status();
|
||||
document.getElementById('compression-ratio').textContent =
|
||||
stats.compression_ratio.toFixed(1) + 'x';
|
||||
document.getElementById('docs-mined').textContent = stats.total_docs;
|
||||
document.getElementById('aaak-size').textContent = stats.aaak_size + 'B';
|
||||
document.getElementById('mem-palace-status').textContent = 'Mining Active';
|
||||
} catch (error) {
|
||||
document.getElementById('mem-palace-status').textContent = 'Connection Lost';
|
||||
}
|
||||
}
|
||||
|
||||
// Mine chat on send
|
||||
document.getElementById('chat-send-btn').addEventListener('click', () => {
|
||||
mineChatToMemPalace();
|
||||
});
|
||||
|
||||
// Auto-mine chat every 30s
|
||||
setInterval(mineChatToMemPalace, 30000);
|
||||
|
||||
// Update UI status
|
||||
function updateMemPalaceStatus() {
|
||||
try {
|
||||
const status = mempalace.status();
|
||||
document.getElementById('compression-ratio').textContent = status.compression_ratio.toFixed(1) + 'x';
|
||||
document.getElementById('docs-mined').textContent = status.total_docs;
|
||||
document.getElementById('aaak-size').textContent = status.aaak_size + 'b';
|
||||
} catch (error) {
|
||||
document.getElementById('mem-palace-status').textContent = 'Connection Lost';
|
||||
}
|
||||
}
|
||||
|
||||
// Add mining event listener
|
||||
document.getElementById('mem-palace-btn').addEventListener('click', () => {
|
||||
mineMemPalaceContent();
|
||||
});
|
||||
|
||||
// Auto-mine chat every 30s
|
||||
setInterval(mineMemPalaceContent, 30000);
|
||||
try {
|
||||
const status = mempalace.status();
|
||||
document.getElementById('compression-ratio').textContent = status.compression_ratio.toFixed(1) + 'x';
|
||||
document.getElementById('docs-mined').textContent = status.total_docs;
|
||||
document.getElementById('aaak-size').textContent = status.aaak_size + 'B';
|
||||
} catch (error) {
|
||||
console.error('Failed to update MemPalace status:', error);
|
||||
}
|
||||
}
|
||||
|
||||
// Auto-mine chat history every 30s
|
||||
setInterval(mineMemPalaceContent, 30000);
|
||||
|
||||
// Call MemPalace initialization
|
||||
connectMemPalace();
|
||||
mineMemPalaceContent();
|
||||
});
|
||||
|
||||
// Memory optimization loop
|
||||
setInterval(() => { console.log('Running optimization...'); }, 60000);
|
||||
// MemPalace is initialized via connectMemPalace() (line 2772)
|
||||
// which uses the real Fleet API. The mock MCP implementation
|
||||
// was removed — see issue #1601.
|
||||
});
|
||||
Reference in New Issue
Block a user