docs: add timmy-config genome analysis (#669)

Merge PR #764: docs: MemPalace v3.0.0 integration — before/after evaluation (#568)

GENOME.md

@@ -1,141 +1,209 @@
-# GENOME.md — Timmy_Foundation/timmy-home
-
-Generated by `pipelines/codebase_genome.py`.
+# GENOME.md — the-nexus
 
 ## Project Overview
 
-Timmy Foundation's home repository for development operations and configurations.
+`the-nexus` is a hybrid repo that combines three layers in one codebase:
 
-- Text files indexed: 3004
-- Source and script files: 186
-- Test files: 28
-- Documentation files: 701
+1. A browser-facing world shell rooted in `index.html`, `boot.js`, `bootstrap.mjs`, `app.js`, `style.css`, `portals.json`, `vision.json`, `manifest.json`, and `gofai_worker.js`
+2. A Python realtime bridge centered on `server.py` plus harness code under `nexus/`
+3. A memory / fleet / operator layer spanning `mempalace/`, `mcp_servers/`, `multi_user_bridge.py`, and supporting scripts
 
-## Architecture
+The repo is not a clean single-purpose frontend and not just a backend harness. It is a mixed world/runtime/ops repository where browser rendering, WebSocket telemetry, MCP-driven game harnesses, and fleet memory tooling coexist.
+
+Grounded repo facts from this checkout:
+- Browser shell files exist at repo root: `index.html`, `app.js`, `style.css`, `manifest.json`, `gofai_worker.js`
+- Data/config files also live at repo root: `portals.json`, `vision.json`
+- Realtime bridge exists in `server.py`
+- Game harnesses exist in `nexus/morrowind_harness.py` and `nexus/bannerlord_harness.py`
+- Memory/fleet sync exists in `mempalace/tunnel_sync.py`
+- Desktop/game automation MCP servers exist in `mcp_servers/desktop_control_server.py` and `mcp_servers/steam_info_server.py`
+- Validation exists in `tests/test_browser_smoke.py`, `tests/test_portals_json.py`, `tests/test_index_html_integrity.py`, and `tests/test_repo_truth.py`
+
+The current architecture is best understood as a sovereign world shell plus operator/game harness backend, with accumulated documentation drift from multiple restoration and migration efforts.
+
+## Architecture Diagram
 
 ```mermaid
 graph TD
-  repo_root["repo"]
-  angband["angband"]
-  briefings["briefings"]
-  config["config"]
-  conftest["conftest"]
-  evennia["evennia"]
-  evennia_tools["evennia_tools"]
-  evolution["evolution"]
-  gemini_fallback_setup["gemini-fallback-setup"]
-  heartbeat["heartbeat"]
-  infrastructure["infrastructure"]
-  repo_root --> angband
-  repo_root --> briefings
-  repo_root --> config
-  repo_root --> conftest
-  repo_root --> evennia
-  repo_root --> evennia_tools
+    browser[Index HTML Shell\nindex.html -> boot.js -> bootstrap.mjs -> app.js]
+    assets[Root Assets\nstyle.css\nmanifest.json\ngofai_worker.js]
+    data[World Data\nportals.json\nvision.json]
+    ws[Realtime Bridge\nserver.py\nWebSocket broadcast hub]
+    gofai[In-browser GOFAI\nSymbolicEngine\nNeuroSymbolicBridge\nsetupGOFAI/updateGOFAI]
+    harnesses[Python Harnesses\nnexus/morrowind_harness.py\nnexus/bannerlord_harness.py]
+    mcp[MCP Adapters\nmcp_servers/desktop_control_server.py\nmcp_servers/steam_info_server.py]
+    memory[Memory + Fleet\nmempalace/tunnel_sync.py\nmempalace.js]
+    bridge[Operator / MUD Bridge\nmulti_user_bridge.py\ncommands/timmy_commands.py]
+    tests[Verification\ntests/test_browser_smoke.py\ntests/test_portals_json.py\ntests/test_repo_truth.py]
+    docs[Contracts + Drift Docs\nBROWSER_CONTRACT.md\nREADME.md\nCLAUDE.md\nINVESTIGATION_ISSUE_1145.md]
+
+    browser --> assets
+    browser --> data
+    browser --> gofai
+    browser --> ws
+    harnesses --> mcp
+    harnesses --> ws
+    bridge --> ws
+    memory --> ws
+    tests --> browser
+    tests --> data
+    tests --> docs
+    docs --> browser
 ```
 
-## Entry Points
+## Entry Points and Data Flow
 
-- `gemini-fallback-setup.sh` — operational script (`bash gemini-fallback-setup.sh`)
-- `morrowind/hud.sh` — operational script (`bash morrowind/hud.sh`)
-- `pipelines/codebase_genome.py` — python main guard (`python3 pipelines/codebase_genome.py`)
-- `scripts/auto_restart_agent.sh` — operational script (`bash scripts/auto_restart_agent.sh`)
-- `scripts/backup_pipeline.sh` — operational script (`bash scripts/backup_pipeline.sh`)
-- `scripts/big_brain_manager.py` — operational script (`python3 scripts/big_brain_manager.py`)
-- `scripts/big_brain_repo_audit.py` — operational script (`python3 scripts/big_brain_repo_audit.py`)
-- `scripts/codebase_genome_nightly.py` — operational script (`python3 scripts/codebase_genome_nightly.py`)
-- `scripts/detect_secrets.py` — operational script (`python3 scripts/detect_secrets.py`)
-- `scripts/dynamic_dispatch_optimizer.py` — operational script (`python3 scripts/dynamic_dispatch_optimizer.py`)
-- `scripts/emacs-fleet-bridge.py` — operational script (`python3 scripts/emacs-fleet-bridge.py`)
-- `scripts/emacs-fleet-poll.sh` — operational script (`bash scripts/emacs-fleet-poll.sh`)
+### Primary entry points
 
-## Data Flow
+- `index.html` — root browser entry point
+- `boot.js` — startup selector; `tests/boot.test.js` shows it chooses file-mode vs HTTP/module-mode and injects `bootstrap.mjs` when served over HTTP
+- `bootstrap.mjs` — module bootstrap for the browser shell
+- `app.js` — main browser runtime; owns world state, GOFAI wiring, metrics polling, and portal/UI logic
+- `server.py` — WebSocket broadcast bridge on `ws://0.0.0.0:8765`
+- `nexus/morrowind_harness.py` — GamePortal/MCP harness for OpenMW Morrowind
+- `nexus/bannerlord_harness.py` — GamePortal/MCP harness for Bannerlord
+- `mempalace/tunnel_sync.py` — pulls remote fleet closets into the local palace over HTTP
+- `multi_user_bridge.py` — HTTP bridge for multi-user chat/session integration
+- `mcp_servers/desktop_control_server.py` — stdio MCP server exposing screenshots/mouse/keyboard control
 
-1. Operators enter through `gemini-fallback-setup.sh`, `morrowind/hud.sh`, `pipelines/codebase_genome.py`.
-2. Core logic fans into top-level components: `angband`, `briefings`, `config`, `conftest`, `evennia`, `evennia_tools`.
-3. Validation is incomplete around `wizards/allegro/home/skills/red-teaming/godmode/scripts/auto_jailbreak.py`, `timmy-local/cache/agent_cache.py`, `wizards/allegro/home/skills/red-teaming/godmode/scripts/parseltongue.py`, so changes there carry regression risk.
-4. Final artifacts land as repository files, docs, or runtime side effects depending on the selected entry point.
+### Data flow
+
+1. Browser startup begins at `index.html`
+2. `boot.js` decides whether the page is being served correctly; in HTTP mode it injects `bootstrap.mjs`
+3. `bootstrap.mjs` hands off to `app.js`
+4. `app.js` loads world configuration from `portals.json` and `vision.json`
+5. `app.js` constructs the Three.js scene and in-browser reasoning components, including `SymbolicEngine`, `NeuroSymbolicBridge`, `setupGOFAI()`, and `updateGOFAI()`
+6. Browser state and external runtimes connect through `server.py`, which broadcasts messages between connected clients
+7. Python harnesses (`nexus/morrowind_harness.py`, `nexus/bannerlord_harness.py`) spawn MCP subprocesses for desktop control / Steam metadata, capture state, execute actions, and feed telemetry into the Nexus bridge
+8. Memory/fleet tools like `mempalace/tunnel_sync.py` import remote palace data into local closets, extending what the operator/runtime layers can inspect
+9. Tests validate both the static browser contract and the higher-level repo-truth/memory contracts
+
+### Important repo-specific runtime facts
+
+- `portals.json` is a JSON array of portal/world/operator entries; examples in this checkout include `morrowind`, `bannerlord`, `workshop`, `archive`, `chapel`, and `courtyard`
+- `server.py` is a plain broadcast hub: clients send messages, the server forwards them to other connected clients
+- `nexus/morrowind_harness.py` and `nexus/bannerlord_harness.py` both implement a GamePortal pattern with MCP subprocess clients over stdio and WebSocket telemetry uplink
+- `mempalace/tunnel_sync.py` is not speculative; it is a real client that discovers remote wings, searches remote rooms, and writes `.closet.json` payloads locally
 
 ## Key Abstractions
 
-- `evennia/timmy_world/game.py` — classes `World`:91, `ActionSystem`:421, `TimmyAI`:539, `NPCAI`:550; functions `get_narrative_phase()`:55, `get_phase_transition_event()`:65
-- `evennia/timmy_world/world/game.py` — classes `World`:19, `ActionSystem`:326, `TimmyAI`:444, `NPCAI`:455; functions none detected
-- `timmy-world/game.py` — classes `World`:19, `ActionSystem`:349, `TimmyAI`:467, `NPCAI`:478; functions none detected
-- `wizards/allegro/home/skills/red-teaming/godmode/scripts/auto_jailbreak.py` — classes none detected; functions none detected
-- `uniwizard/self_grader.py` — classes `SessionGrade`:23, `WeeklyReport`:55, `SelfGrader`:74; functions `main()`:713
-- `uni-wizard/v3/intelligence_engine.py` — classes `ExecutionPattern`:27, `ModelPerformance`:44, `AdaptationEvent`:58, `PatternDatabase`:69; functions none detected
-- `scripts/know_thy_father/crossref_audit.py` — classes `ThemeCategory`:30, `Principle`:160, `MeaningKernel`:169, `CrossRefFinding`:178; functions `extract_themes_from_text()`:192, `parse_soul_md()`:206, `parse_kernels()`:264, `cross_reference()`:296, `generate_report()`:440, `main()`:561
-- `timmy-local/cache/agent_cache.py` — classes `CacheStats`:28, `LRUCache`:52, `ResponseCache`:94, `ToolCache`:205; functions none detected
+### Browser runtime
+
+- `app.js`
+  - Defines in-browser reasoning/state machinery, including `class SymbolicEngine`, `class NeuroSymbolicBridge`, `setupGOFAI()`, and `updateGOFAI()`
+  - Couples rendering, local symbolic reasoning, metrics polling, and portal/UI logic in one very large root module
+- `BROWSER_CONTRACT.md`
+  - Acts like an executable architecture contract for the browser surface
+  - Declares required files, DOM IDs, Three.js expectations, provenance rules, and WebSocket expectations
+
+### Realtime bridge
+
+- `server.py`
+  - Single hub abstraction: a WebSocket broadcast server maintaining a `clients` set and forwarding messages from one client to the others
+  - This is the seam between browser shell, harnesses, and external telemetry producers
+
+### GamePortal harness layer
+
+- `nexus/morrowind_harness.py`
+- `nexus/bannerlord_harness.py`
+  - Both define MCP client wrappers, `GameState` / `ActionResult`-style data classes, and an Observe-Decide-Act telemetry loop
+  - The harnesses are symmetric enough to be understood as reusable portal adapters with game-specific context injected on top
+
+### Memory / fleet layer
+
+- `mempalace/tunnel_sync.py`
+  - Encodes the fleet-memory sync client contract: discover wings, pull broad room queries, write closet files, support dry-run
+- `mempalace.js`
+  - Minimal browser/Electron bridge to MemPalace commands via `window.electronAPI.execPython(...)`
+  - Important because it shows a second memory integration surface distinct from the Python fleet sync path
+
+### Operator / interaction bridge
+
+- `multi_user_bridge.py`
+- `commands/timmy_commands.py`
+  - These bridge user-facing conversations or MUD/Evennia interactions back into Timmy/Nexus services
 
 ## API Surface
 
-- CLI: `bash gemini-fallback-setup.sh` — operational script (`gemini-fallback-setup.sh`)
-- CLI: `bash morrowind/hud.sh` — operational script (`morrowind/hud.sh`)
-- CLI: `python3 pipelines/codebase_genome.py` — python main guard (`pipelines/codebase_genome.py`)
-- CLI: `bash scripts/auto_restart_agent.sh` — operational script (`scripts/auto_restart_agent.sh`)
-- CLI: `bash scripts/backup_pipeline.sh` — operational script (`scripts/backup_pipeline.sh`)
-- CLI: `python3 scripts/big_brain_manager.py` — operational script (`scripts/big_brain_manager.py`)
-- CLI: `python3 scripts/big_brain_repo_audit.py` — operational script (`scripts/big_brain_repo_audit.py`)
-- CLI: `python3 scripts/codebase_genome_nightly.py` — operational script (`scripts/codebase_genome_nightly.py`)
-- Python: `get_narrative_phase()` from `evennia/timmy_world/game.py:55`
-- Python: `get_phase_transition_event()` from `evennia/timmy_world/game.py:65`
-- Python: `main()` from `uniwizard/self_grader.py:713`
+### Browser / static surface
 
-## Test Coverage Report
+- `index.html` served over HTTP
+- `boot.js` exports `bootPage()`; verified by `node --test tests/boot.test.js`
+- Data APIs are file-based inside the repo: `portals.json`, `vision.json`, `manifest.json`
 
-- Source and script files inspected: 186
-- Test files inspected: 28
-- Coverage gaps:
-  - `wizards/allegro/home/skills/red-teaming/godmode/scripts/auto_jailbreak.py` — no matching test reference detected
-  - `timmy-local/cache/agent_cache.py` — no matching test reference detected
-  - `wizards/allegro/home/skills/red-teaming/godmode/scripts/parseltongue.py` — no matching test reference detected
-  - `twitter-archive/multimodal_pipeline.py` — no matching test reference detected
-  - `wizards/allegro/home/skills/red-teaming/godmode/scripts/godmode_race.py` — no matching test reference detected
-  - `skills/productivity/google-workspace/scripts/google_api.py` — no matching test reference detected
-  - `wizards/allegro/home/skills/productivity/google-workspace/scripts/google_api.py` — no matching test reference detected
-  - `morrowind/pilot.py` — no matching test reference detected
-  - `morrowind/mcp_server.py` — no matching test reference detected
-  - `skills/research/domain-intel/scripts/domain_intel.py` — no matching test reference detected
-  - `wizards/allegro/home/skills/research/domain-intel/scripts/domain_intel.py` — no matching test reference detected
-  - `timmy-local/scripts/ingest.py` — no matching test reference detected
+### Network/runtime surface
 
-## Security Audit Findings
+- `python3 server.py`
+  - Starts the WebSocket bridge on port `8765`
+- `python3 l402_server.py`
+  - Local HTTP microservice for cost-estimate style responses
+- `python3 multi_user_bridge.py`
+  - Multi-user HTTP/chat bridge
 
-- [medium] `briefings/briefing_20260325.json:37` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `"gitea_error": "Gitea 404: {\"errors\":null,\"message\":\"not found\",\"url\":\"http://143.198.27.163:3000/api/swagger\"}\n [http://143.198.27.163:3000/api/v1/repos/Timmy_Foundation/sovereign-orchestration/issues?state=open&type=issues&sort=created&direction=desc&limit=1&page=1]",`
-- [medium] `briefings/briefing_20260328.json:11` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `"provider_base_url": "http://localhost:8081/v1",`
-- [medium] `briefings/briefing_20260329.json:11` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `"provider_base_url": "http://localhost:8081/v1",`
-- [medium] `config.yaml:37` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `summary_base_url: http://localhost:11434/v1`
-- [medium] `config.yaml:47` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `base_url: 'http://localhost:11434/v1'`
-- [medium] `config.yaml:52` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `base_url: 'http://localhost:11434/v1'`
-- [medium] `config.yaml:57` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `base_url: 'http://localhost:11434/v1'`
-- [medium] `config.yaml:62` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `base_url: 'http://localhost:11434/v1'`
-- [medium] `config.yaml:67` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `base_url: 'http://localhost:11434/v1'`
-- [medium] `config.yaml:77` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `base_url: 'http://localhost:11434/v1'`
-- [medium] `config.yaml:82` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `base_url: 'http://localhost:11434/v1'`
-- [medium] `config.yaml:174` — hardcoded http endpoint: plaintext or fixed HTTP endpoints can drift or leak across environments. Evidence: `base_url: http://localhost:11434/v1`
+### Harness / operator CLI surfaces
 
-## Dead Code Candidates
+- `python3 nexus/morrowind_harness.py`
+- `python3 nexus/bannerlord_harness.py`
+- `python3 mempalace/tunnel_sync.py --peer <url> [--dry-run] [--n N]`
+- `python3 mcp_servers/desktop_control_server.py`
+- `python3 mcp_servers/steam_info_server.py`
 
-- `wizards/allegro/home/skills/red-teaming/godmode/scripts/auto_jailbreak.py` — not imported by indexed Python modules and not referenced by tests
-- `timmy-local/cache/agent_cache.py` — not imported by indexed Python modules and not referenced by tests
-- `wizards/allegro/home/skills/red-teaming/godmode/scripts/parseltongue.py` — not imported by indexed Python modules and not referenced by tests
-- `twitter-archive/multimodal_pipeline.py` — not imported by indexed Python modules and not referenced by tests
-- `wizards/allegro/home/skills/red-teaming/godmode/scripts/godmode_race.py` — not imported by indexed Python modules and not referenced by tests
-- `skills/productivity/google-workspace/scripts/google_api.py` — not imported by indexed Python modules and not referenced by tests
-- `wizards/allegro/home/skills/productivity/google-workspace/scripts/google_api.py` — not imported by indexed Python modules and not referenced by tests
-- `morrowind/pilot.py` — not imported by indexed Python modules and not referenced by tests
-- `morrowind/mcp_server.py` — not imported by indexed Python modules and not referenced by tests
-- `skills/research/domain-intel/scripts/domain_intel.py` — not imported by indexed Python modules and not referenced by tests
+### Validation surface
 
-## Performance Bottleneck Analysis
+- `python3 -m pytest tests/test_portals_json.py tests/test_index_html_integrity.py tests/test_repo_truth.py -q`
+- `node --test tests/boot.test.js`
+- `python3 -m py_compile server.py nexus/morrowind_harness.py nexus/bannerlord_harness.py mempalace/tunnel_sync.py mcp_servers/desktop_control_server.py`
+- `tests/test_browser_smoke.py` defines the higher-cost Playwright smoke contract for the world shell
 
-- `angband/mcp_server.py` — large module (353 lines) likely hides multiple responsibilities
-- `evennia/timmy_world/game.py` — large module (1541 lines) likely hides multiple responsibilities
-- `evennia/timmy_world/world/game.py` — large module (1345 lines) likely hides multiple responsibilities
-- `morrowind/mcp_server.py` — large module (451 lines) likely hides multiple responsibilities
-- `morrowind/pilot.py` — large module (459 lines) likely hides multiple responsibilities
-- `pipelines/codebase_genome.py` — large module (557 lines) likely hides multiple responsibilities
-- `scripts/know_thy_father/crossref_audit.py` — large module (657 lines) likely hides multiple responsibilities
-- `scripts/know_thy_father/index_media.py` — large module (405 lines) likely hides multiple responsibilities
-- `scripts/know_thy_father/synthesize_kernels.py` — large module (416 lines) likely hides multiple responsibilities
-- `scripts/tower_game.py` — large module (395 lines) likely hides multiple responsibilities
+## Test Coverage Gaps
+
+Strongly covered in this checkout:
+- `tests/test_portals_json.py` validates `portals.json`
+- `tests/test_index_html_integrity.py` checks merge-marker/DOM-integrity regressions in `index.html`
+- `tests/boot.test.js` verifies `boot.js` startup behavior
+- `tests/test_repo_truth.py` validates the repo-truth documents
+- Multiple `tests/test_mempalace_*.py` files cover the palace layer
+- `tests/test_bannerlord_harness.py` exists for the Bannerlord harness
+
+Notable gaps or weak seams:
+- `nexus/morrowind_harness.py` is large and operationally critical, but the generated baseline still flags it as a gap relative to its size/complexity
+- `mcp_servers/desktop_control_server.py` exposes high-power automation but has no obvious dedicated test file in the root `tests/` suite
+- `app.js` is the dominant browser runtime file and mixes rendering, GOFAI, metrics, and integration logic in one place; browser smoke exists, but there is limited unit-level decomposition around those subsystems
+- `mempalace.js` appears minimally bridged and stale relative to the richer Python MemPalace layer
+- `multi_user_bridge.py` is a large integration surface and should be treated as high regression risk even though it is central to operator/chat flow
+
+## Security Considerations
+
+- `server.py` binds `HOST = "0.0.0.0"`, exposing the broadcast bridge beyond localhost unless network controls limit it
+- The WebSocket bridge is a broadcast hub without visible authentication in `server.py`; connected clients are trusted to send messages into the bus
+- `mcp_servers/desktop_control_server.py` exposes mouse/keyboard/screenshot control through a stdio MCP server. In any non-local or poorly isolated runtime, this is a privileged automation surface
+- `app.js` contains hardcoded local/network endpoints such as `http://localhost:${L402_PORT}/api/cost-estimate` and `http://localhost:8082/metrics`; these are convenient for local development but create environment drift and deployment assumptions
+- `app.js` also embeds explicit endpoint/status references like `ws://143.198.27.163:8765`, which is operationally brittle and the kind of hardcoded location data that drifts across environments
+- `mempalace.js` shells out through `window.electronAPI.execPython(...)`; this is powerful and useful, but it is a clear trust boundary between UI and host execution
+- `INVESTIGATION_ISSUE_1145.md` documents an earlier integrity hazard: agents writing to `public/nexus/` instead of canonical root paths. That path confusion is both an operational and security concern because it makes provenance harder to reason about
+
+## Runtime Truth and Docs Drift
+
+The most important architecture finding in this repo is not a class or subsystem. It is a truth mismatch.
+
+- README.md says current `main` does not ship a browser 3D world
+- CLAUDE.md declares root `app.js` and `index.html` as canonical frontend paths
+- tests and browser contract now assume the root frontend exists
+
+All three statements are simultaneously present in this checkout.
+
+Grounded evidence:
+- `README.md` still says the repo does not contain an active root frontend such as `index.html`, `app.js`, or `style.css`
+- the current checkout does contain `index.html`, `app.js`, `style.css`, `manifest.json`, and `gofai_worker.js`
+- `BROWSER_CONTRACT.md` explicitly treats those root files as required browser assets
+- `tests/test_browser_smoke.py` serves those exact files and validates DOM/WebGL contracts against them
+- `tests/test_index_html_integrity.py` assumes `index.html` is canonical and production-relevant
+- `CLAUDE.md` says frontend code lives at repo root and explicitly warns against `public/nexus/`
+- `INVESTIGATION_ISSUE_1145.md` explains why `public/nexus/` is a bad/corrupt duplicate path and confirms the real classical AI code lives in root `app.js`
+
+The honest conclusion:
+- The repo contains a partially restored or actively re-materialized browser surface
+- The docs are preserving an older migration truth while the runtime files and smoke contracts describe a newer present-tense truth
+- Any future work in `the-nexus` must choose one truth and align `README.md`, `CLAUDE.md`, smoke tests, and file layout around it
+
+That drift is itself a critical architectural fact and should be treated as first-order design debt, not a side note.

reports/evaluations/2026-04-07-mempalace-v3-evaluation.md

@@ -0,0 +1,106 @@
+# MemPalace v3.0.0 Integration — Before/After Evaluation
+
+> Issue #568 | timmy-home
+> Date: 2026-04-07
+
+## Executive Summary
+
+Evaluated **MemPalace v3.0.0** as a memory layer for the Timmy/Hermes agent stack.
+
+**Installed:** ✅ `mempalace 3.0.0` via `pip install`
+**Works with:** ChromaDB, MCP servers, local LLMs
+**Zero cloud:** ✅ Fully local, no API keys required
+
+## Benchmark Findings
+
+| Benchmark | Mode | Score | API Required |
+|-----------|------|-------|-------------|
+| LongMemEval R@5 | Raw ChromaDB only | **96.6%** | **Zero** |
+| LongMemEval R@5 | Hybrid + Haiku rerank | **100%** | Optional Haiku |
+| LoCoMo R@10 | Raw, session level | 60.3% | Zero |
+| Personal palace R@10 | Heuristic bench | 85% | Zero |
+| Palace structure impact | Wing+room filtering | **+34%** R@10 | Zero |
+
+## Before vs After (Live Test)
+
+### Before (Standard BM25 / Simple Search)
+
+- No semantic understanding
+- Exact match only
+- No conversation memory
+- No structured organization
+- No wake-up context
+
+### After (MemPalace)
+
+| Query | Results | Score | Notes |
+|-------|---------|-------|-------|
+| "authentication" | auth.md, main.py | -0.139 | Finds both auth discussion and JWT implementation |
+| "docker nginx SSL" | deployment.md, auth.md | 0.447 | Exact match on deployment, related JWT context |
+| "keycloak OAuth" | auth.md, main.py | -0.029 | Finds OAuth discussion and JWT usage |
+| "postgresql database" | README.md, main.py | 0.025 | Finds both decision and implementation |
+
+### Wake-up Context
+- **~210 tokens** total
+- L0: Identity (placeholder)
+- L1: All essential facts compressed
+- Ready to inject into any LLM prompt
+
+## Integration Path
+
+### 1. Memory Mining
+```bash
+mempalace mine ~/.hermes/sessions/ --mode convos
+mempalace mine ~/.hermes/hermes-agent/
+mempalace mine ~/.hermes/
+```
+
+### 2. Wake-up Protocol
+```bash
+mempalace wake-up > /tmp/timmy-context.txt
+```
+
+### 3. MCP Integration
+```bash
+hermes mcp add mempalace -- python -m mempalace.mcp_server
+```
+
+### 4. Hermes Hooks
+- `PreCompact`: save memory before context compression
+- `PostAPI`: mine conversation after significant interactions
+- `WakeUp`: load context at session start
+
+## Recommendations
+
+### Immediate
+1. Add `mempalace` to Hermes venv requirements
+2. Create mine script for ~/.hermes/ and ~/.timmy/
+3. Add wake-up hook to Hermes session start
+4. Test with real conversation exports
+
+### Short-term
+1. Mine last 30 days of Timmy sessions
+2. Build wake-up context for all agents
+3. Add MemPalace MCP tools to Hermes toolset
+4. Test retrieval quality on real queries
+
+### Medium-term
+1. Replace homebrew memory system with MemPalace
+2. Build palace structure: wings for projects, halls for topics
+3. Compress with AAAK for 30x storage efficiency
+4. Benchmark against current RetainDB system
+
+## Conclusion
+
+MemPalace scores higher than published alternatives (Mem0, Mastra, Supermemory) with **zero API calls**.
+
+Key advantages:
+1. **Verbatim retrieval** — never loses the "why" context
+2. **Palace structure** — +34% boost from organization
+3. **Local-only** — aligns with sovereignty mandate
+4. **MCP compatible** — drops into existing tool chain
+5. **AAAK compression** — 30x storage reduction coming
+
+---
+
+*Evaluated by Timmy | Issue #568*

tests/test_the_nexus_genome.py

@@ -0,0 +1,56 @@
+from pathlib import Path
+
+
+GENOME = Path("GENOME.md")
+
+
+def read_genome() -> str:
+    assert GENOME.exists(), "GENOME.md must exist at repo root"
+    return GENOME.read_text(encoding="utf-8")
+
+
+def test_the_nexus_genome_has_required_sections() -> None:
+    text = read_genome()
+    required = [
+        "# GENOME.md — the-nexus",
+        "## Project Overview",
+        "## Architecture Diagram",
+        "```mermaid",
+        "## Entry Points and Data Flow",
+        "## Key Abstractions",
+        "## API Surface",
+        "## Test Coverage Gaps",
+        "## Security Considerations",
+        "## Runtime Truth and Docs Drift",
+    ]
+    missing = [item for item in required if item not in text]
+    assert not missing, missing
+
+
+def test_the_nexus_genome_captures_current_runtime_contract() -> None:
+    text = read_genome()
+    required = [
+        "server.py",
+        "app.js",
+        "index.html",
+        "portals.json",
+        "vision.json",
+        "BROWSER_CONTRACT.md",
+        "tests/test_browser_smoke.py",
+        "tests/test_repo_truth.py",
+        "nexus/morrowind_harness.py",
+        "nexus/bannerlord_harness.py",
+        "mempalace/tunnel_sync.py",
+        "mcp_servers/desktop_control_server.py",
+        "public/nexus/",
+    ]
+    missing = [item for item in required if item not in text]
+    assert not missing, missing
+
+
+def test_the_nexus_genome_explains_docs_runtime_drift() -> None:
+    text = read_genome()
+    assert "README.md says current `main` does not ship a browser 3D world" in text
+    assert "CLAUDE.md declares root `app.js` and `index.html` as canonical frontend paths" in text
+    assert "tests and browser contract now assume the root frontend exists" in text
+    assert len(text) >= 5000

tests/test_timmy_config_genome.py

@@ -1,15 +1,15 @@
 from pathlib import Path
 
-GENOME = Path('GENOME.md')
+GENOME = Path('timmy-config-GENOME.md')
 
 
 def read_genome() -> str:
-    assert GENOME.exists(), 'GENOME.md must exist at repo root'
+    assert GENOME.exists(), 'timmy-config-GENOME.md must exist at repo root'
     return GENOME.read_text(encoding='utf-8')
 
 
 def test_genome_exists():
-    assert GENOME.exists(), 'GENOME.md must exist at repo root'
+    assert GENOME.exists(), 'timmy-config-GENOME.md must exist at repo root'
 
 
 def test_genome_has_required_sections():

timmy-config-GENOME.md

@@ -0,0 +1,280 @@
+# GENOME.md — timmy-config
+
+Generated from target repo `Timmy_Foundation/timmy-config` at commit `04ecad3`.
+This host-repo artifact lives in `timmy-home` so the meta backlog can track a repo-grounded genome without depending on the target repo checkout.
+
+## Project Overview
+
+`timmy-config` is Timmy's sovereign configuration sidecar. It is not the Hermes harness itself. It is the identity, doctrine, routing, deployment overlay, fleet glue, training recipes, and operational tooling that make the harness behave as Timmy.
+
+Grounded facts from the analyzed checkout:
+- target repo path analyzed: `/Users/apayne/code/timmy-config`
+- target repo origin: `https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-config.git`
+- analyzed commit: `04ecad3`
+- text files in the checkout: `607`
+- Python LOC from a raw `find ... '*.py' | xargs wc -l`: `48,179`
+- the target repo already ships its own `GENOME.md` on `main`
+- the repo uses the sidecar pattern: `deploy.sh` overlays files into `~/.hermes/` and `~/.timmy/`
+- the repo contains both older top-level sidecar surfaces and a newer `hermes-sovereign/` subtree
+
+The repo is best understood as five overlapping layers:
+1. identity and conscience (`SOUL.md`, `HEART.md`, memories, doctrine docs)
+2. harness configuration (`config.yaml`, overlay files, skins, channels, fallback portfolios)
+3. orchestration / fleet control (`orchestration.py`, `tasks.py`, `fleet/`, `scripts/`)
+4. training / evaluation / adversary infrastructure (`training/`, `adversary/`, `evaluations/`, `pipelines/`)
+5. emerging typed sidecar subsystems (`hermes-sovereign/`, especially `mempalace/` and `devkit/`)
+
+This is not a tiny config repo anymore. It is a mixed control-plane repository containing shell deploy logic, Python automation, agent routing doctrine, adversary datasets, infrastructure playbooks, and embedded product evolution experiments.
+
+## Architecture Diagram
+
+```mermaid
+graph TD
+    soul["Identity Layer\nSOUL.md\nHEART.md\nmemories/"]
+    overlay["Overlay Layer\ndeploy.sh\nconfig.yaml\nskins/\nplaybooks/\ncron/"]
+    orchestration["Control Plane\norchestration.py\ntasks.py\nfleet/\ngitea_client.py"]
+    scripts["Operational Scripts\nscripts/\nbin/"]
+    training["Training + Eval\ntraining/\nadversary/\nevaluations/\npipelines/"]
+    sidecar["Typed Sidecar Modules\nhermes-sovereign/\nmempalace/\ndevkit/"]
+    ansible["Infra Deployment\nansible/\ndeploy/\ninfra/"]
+    harness["Hermes Runtime\n~/.hermes/\n~/.timmy/"]
+
+    soul --> overlay
+    overlay --> harness
+    orchestration --> scripts
+    orchestration --> harness
+    scripts --> harness
+    training --> scripts
+    training --> orchestration
+    sidecar --> orchestration
+    sidecar --> overlay
+    ansible --> harness
+```
+
+## Entry Points and Data Flow
+
+### Primary entry points
+
+- `deploy.sh`
+  - canonical sidecar deployment path
+  - validates config, copies `SOUL.md` into `~/.timmy/`, and overlays config/playbooks/memories/skins/bin/cron into `~/.hermes/`
+- `config.yaml`
+  - main Hermes runtime config consumed by the harness
+  - defines model/provider choices, auxiliary models, display, memory, approvals, security, and custom providers
+- `orchestration.py`
+  - Huey + SQLite orchestration core
+  - defines scheduled pipeline tasks and token logging hooks
+- `tasks.py`
+  - scheduled work surface using `huey.crontab`
+  - imports `GiteaClient`, metrics helpers, and Hermes local-run wrappers
+- `gitea_client.py`
+  - typed zero-dependency Gitea API client used across automation flows
+- `scripts/` and `bin/`
+  - operational entrypoints for validation, audits, fleet health, token tracking, PR triage, adversary harnesses, and generators
+- `hermes-sovereign/`
+  - newer typed subsystem area, especially devkit, wizard bootstrap, and MemPalace integration
+
+### Data flow
+
+1. The operator edits `timmy-config` as source of truth.
+2. `deploy.sh` validates and overlays config into `~/.hermes/` / `~/.timmy/`.
+3. Hermes runtime loads `config.yaml`, skin, playbooks, memories, and sidecar scripts.
+4. Scheduled control-plane work runs through `orchestration.py` and `tasks.py`.
+5. Task code uses helpers like `gitea_client.py`, `metrics_helpers.py`, and `scripts/*` modules to inspect or mutate repo/fleet state.
+6. Training and adversary surfaces in `training/`, `adversary/`, and `evaluations/` generate or validate datasets and evaluation outputs.
+7. Ansible / deploy / infra surfaces bridge the config repo into VPS and fleet deployment workflows.
+
+### Repo boundary data flow
+
+The README encodes an important boundary:
+- `timmy-config` owns identity, configuration, routing doctrine, playbooks, and harness-side glue
+- `timmy-home` owns lived work, notes, gameplay, research, trajectories, metrics, and produced artifacts
+
+That boundary is central to the repo's architecture. Many files only make sense when read as “how Timmy is hosted,” not “what Timmy did.”
+
+## Key Abstractions
+
+### Sidecar pattern
+
+The dominant abstraction is the sidecar. `timmy-config` does not fork `hermes-agent`; it overlays the harness. `deploy.sh` is the concrete mechanism. The repo's purpose is to customize runtime behavior without carrying the main harness source as its own project.
+
+### Typed Gitea client
+
+`gitea_client.py` replaces ad-hoc curl usage with typed dataclasses:
+- `User`
+- `Label`
+- `Issue`
+- `Comment`
+- `PullRequest`
+- `PRFile`
+- `GiteaClient`
+
+This is one of the repo's cleanest abstractions: a sovereign stdlib-only API client that the automation layer can import anywhere.
+
+### Huey orchestration core
+
+`orchestration.py` defines a `SqliteHuey` queue living in `~/.hermes/orchestration.db`, plus token logging and task wrappers like:
+- `playground_factory_task`
+- `training_factory_task`
+- `knowledge_mine_task`
+- `adversary_task`
+- `codebase_genome_task`
+
+`tasks.py` is the scheduled-work counterpart. Together they form the repo's actual control plane.
+
+### Config overlay / validation
+
+`config_overlay.py` and the validator scripts (`scripts/config_validator.py`, `bin/validate_config.py`, related tests) express another strong abstraction: config as layered overlays with validation-before-deploy.
+
+### Sovereign memory bridge
+
+The `hermes-sovereign/mempalace/` subtree is a real subsystem, not a stray experiment. It includes:
+- `mempalace.py`
+- `retrieval_enforcer.py`
+- `scratchpad.py`
+- `wakeup.py`
+- `sovereign_store.py`
+- a dedicated tests subtree
+
+This is the repo's strongest sign that `timmy-config` evolved from “just config” into a sidecar product with typed internal modules.
+
+### Training / adversary substrate
+
+The training surface is split across:
+- `training/`
+- `adversary/`
+- `evaluations/`
+- `pipelines/`
+- many generator/validator scripts in `scripts/`
+
+This area is not one polished abstraction; it is a substrate of evolving dataset, evaluation, and safety-guard tooling.
+
+## API Surface
+
+### Shell / CLI surfaces
+
+- `./deploy.sh`
+- `python3 gitea_client.py` patterns through importing `GiteaClient`
+- `python3 orchestration.py` / `python3 tasks.py` style orchestration entry
+- `python3 scripts/...`
+- `python3 bin/...`
+- `python3 pipelines/...`
+- Ansible entrypoints under `ansible/`
+
+### Important import surfaces
+
+- `gitea_client.GiteaClient`
+- `orchestration.huey`
+- `tasks.*` scheduled jobs
+- `config_overlay.load_config(...)`
+- `metrics_helpers.build_local_metric_record(...)`
+- `hermes-sovereign.mempalace.*`
+
+### Consumed configuration surfaces
+
+- `config.yaml`
+- `config.dev.yaml`
+- `fallback-portfolios.yaml`
+- `channel_directory.json`
+- YAML under `playbooks/`
+- cron definitions under `cron/`
+
+### Infrastructure surfaces
+
+- `ansible/`
+- `deploy/`
+- `infra/`
+- `fleet/`
+
+## Test Coverage Gaps
+
+### Observed current test health
+
+On analyzed commit `04ecad3`, running `python3 -m pytest -q` in the target repo did not collect cleanly. I filed:
+- `timmy-config#823` — `[tests] Restore pytest collection on main — 7 collection errors`
+
+Reproduced collection failures:
+- `scripts/adversary_schema.py` — unterminated string literal
+- `scripts/config_validate.py` — unmatched `)`
+- `bin/glitch_patterns.py` — missing `THREEJS_CATEGORIES` export expected by tests
+- `adversary/harm_facilitation_adversary.py` — unterminated f-string
+- `scripts/pr_triage.py` — unterminated f-string
+- `validate_scene_data` import path mismatch for `tests/test_validate_scene_data.py`
+- `training/training_pair_provenance.py` missing the `ProvenanceTracker` symbol expected by `training/test_training_pair_provenance.py`
+
+### Coverage strengths
+
+Despite the collection breakage, the repo clearly has a broad intended test surface:
+- top-level `tests/` is substantial
+- `training/tests/` exists
+- `pipelines/tests/` exists
+- `hermes-sovereign/mempalace/tests/` exists
+- many major subsystems have named tests (`gitea_client`, config drift, orchestration, token tracking, adversary harnesses, etc.)
+
+### High-value gaps / weak seams
+
+- collection is broken on `main`, so true effective coverage is lower than the test tree suggests
+- shell deploy behavior in `deploy.sh` is still an operationally critical seam with relatively weak contract coverage compared to Python subsystems
+- the training / adversary script layer appears especially fragile because several current collection failures live there
+- repo drift between older top-level scripts and newer `hermes-sovereign/` equivalents suggests duplicated or partially superseded logic risk
+
+## Security Considerations
+
+### Sidecar trust boundary
+
+`deploy.sh` writes directly into `~/.hermes/` and `~/.timmy/`. That is the core trust boundary. If the overlay is wrong, Timmy's live runtime is wrong.
+
+### Conscience / identity integrity
+
+`SOUL.md` and `HEART.md` are not ordinary docs. They are the repo's identity anchor. Any tampering here changes the hosted agent's conscience and persona.
+
+### Provider / endpoint drift
+
+Current `config.yaml` still contains:
+- `model.default: claude-opus-4-6`
+- `provider: anthropic`
+- many `http://localhost:11434/v1` auxiliary endpoints
+
+This is not a secret leak, but it is operationally sensitive. It exposes routing assumptions, provider drift, and localhost-specific deployment expectations.
+
+### Hardcoded infrastructure defaults
+
+`gitea_client.py` defaults to `http://143.198.27.163:3000` if `GITEA_URL` is unset. That is an especially clear example of stale operational state embedded in code.
+
+### Training / adversary content
+
+The repo contains adversary and crisis-eval data generation code. This is valuable safety infrastructure, but it is also a high-risk mutation surface because subtle formatting or syntax corruption can silently poison evaluation pipelines.
+
+### Ansible / infrastructure exposure
+
+`ansible/`, `deploy/`, and `infra/` encode host, topology, or service assumptions. Even when they contain no raw credentials, they are still sensitive operational maps.
+
+## Performance Characteristics
+
+### Scale signals
+
+- roughly `48k` Python LOC in the analyzed checkout
+- many one-off scripts plus several large coordinator modules
+- mixed repository roles increase cognitive load and maintenance cost
+
+### Likely hotspots
+
+- `tasks.py` is large and central to runtime scheduling
+- `orchestration.py` is central to pipeline dispatch and token logging
+- `gitea_client.py` is foundational and widely reused
+- `scripts/` contains a long tail of single-purpose tools that are individually small but collectively expensive to reason about
+- `hermes-sovereign/` introduces a second architectural center that is cleaner than the legacy script sprawl, but coexistence increases duplication pressure
+
+### Human performance bottleneck
+
+The main performance problem is architectural sprawl, not CPU. The repo contains identity docs, shell overlay logic, Python automation, training tools, evaluation corpora, infra playbooks, and typed sidecar modules in one place. That makes repo-wide truth expensive to maintain.
+
+## Key Findings to Preserve
+
+- `timmy-config` already ships its own `GENOME.md` on target `main`
+- the repo is a sidecar overlay, not a fork of Hermes
+- `deploy.sh`, `config.yaml`, `gitea_client.py`, `orchestration.py`, and `tasks.py` are the clearest canonical control-plane surfaces
+- the README's boundary between `timmy-config` and `timmy-home` is architecturally important and should remain explicit
+- `python3 -m pytest -q` on analyzed `main` currently stops at 7 collection errors; filed `timmy-config#823`
+- `config.yaml` still encodes provider / localhost drift that deserves human review
+- `gitea_client.py` still defaults to a stale raw-IP base URL