---
id: 10136
title: Rewrite CodebaseOverview.md to reflect Two Hemispheres architecture + Dream Pipeline
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - architecture
assignees: []
createdAt: '2026-04-20T20:45:15Z'
updatedAt: '2026-05-26T02:32:40Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10136'
author: tobiu
commentsCount: 1
parentIssue: 9999
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-26T02:32:40Z'
---
# Rewrite CodebaseOverview.md to reflect Two Hemispheres architecture + Dream Pipeline

## Context

`learn/guides/fundamentals/CodebaseOverview.md` is loaded during agent bootstrap (`AGENTS_STARTUP.md` Step 1). It forms the mental model every agent inherits about what Neo.mjs is. Currently that model is: *"Neo is an engine with AI tools attached."*

Post-v12.2, that's a category error. The more accurate architectural map already exists in two documents CodebaseOverview.md doesn't cross-reference:

- `learn/benefits/ArchitectureOverview.md` — Two Hemispheres, Cognitive Loop (Perceive/Reason/Act/Reflect), SDK Bouncer pattern, Neural Link bridge, Dream Pipeline overview, Closed Loop feedback diagram
- `learn/agentos/DreamPipeline.md` — Six-phase REM pipeline with the specific Golden Path formula `priority = (semanticScore × 2.0) + (structuralWeight × 1.0)`, graph physics (Hebbian decay + TTL pruning + vector apoptosis), modifiers (bug +1.0, community +0.5, needs-re-triage −10000)

The bootstrapping agent today sees the engine clearly but only a sketch of the Agent OS. That produces predictable drift — blog post #10074 framed Neo as "framework" throughout despite the engine-category correction being durable in memory for weeks. Discussion #10119 had to be amended post-publication with a "(4) category correction" pass. These aren't failures of individual sessions — they're symptoms of bootstrap-time mental-model drift.

## Trigger

Pick up **after v12.2 ships**, not before:

1. Architecture is mid-flight on two axes (#9999, #10030). An update written during flight documents shipping-state, not landed-state
2. v12.2 marks the stabilization point where engine + concept ontology + multi-tenant memory + gated RSI loop are all co-present and observable
3. Sequencing: v12.2 release → this rewrite → #10119 MX epics. The rewrite becomes the bootstrap mental model for the agents building the #10119 follow-ons

## The Problem

Specific gaps in CodebaseOverview.md as of 2026-04-20:

- **No Two Hemispheres framing.** Engine and Agent OS described in sequence, not as co-evolving halves of one system
- **No Cognitive Loop.** Perceive/Reason/Act/Reflect mentioned nowhere
- **No Dream Pipeline.** Six phases, Golden Path formula, graph physics all absent
- **No Closed Loop diagram.** The session → memory → graph → handoff → next-session cycle is the central insight and not present
- **No MX framing.** The design principle that shapes what goes into the Agent OS half. See durable memory `feedback_mx_model_experience.md`; concept coined by @tobiu 2026-04-20; positioning vs. adjacent terms (Machine Experience, Agent Experience) needs its own follow-up if MX formalizes into a public guide
- **Outdated query-entry-point table.** Post-#10030, semantic concept-graph traversal supplements/replaces regex-based gap detection
- **Sub-agent profiles missing.** Librarian / QA / Browser are shipped but invisible in the bootstrap doc

## The Fix

1. Update introduction to frame Neo.mjs as **an application engine with a co-evolving Agent OS** — not as "framework with AI integration"
2. Replace the "Agent OS Backend" section with a digest of `ArchitectureOverview.md`:
   - Two Hemispheres (brief diagram or prose)
   - Cognitive Loop (one-line phase descriptions)
   - SDK Bouncer pattern (one paragraph)
   - Neural Link bridge (one paragraph + link)
   - Dream Pipeline overview (six phases one-liner each → link to `DreamPipeline.md` for depth)
   - Closed Loop diagram (or equivalent prose)
3. Add a brief MX section if the concept has formalized into its own guide by the time this ticket is picked up — otherwise reference the feedback memory
4. Update the query-entry-point table to reflect post-#10030 concept-graph entry points
5. Cross-link explicitly to `ArchitectureOverview.md`, `DreamPipeline.md`, `SwarmIntelligence.md`, `NeuralLink.md` — bootstrap agents should know these exist and when to dive deeper
6. Keep the engine half intact. The runtime description is accurate; the gap is only on the Agent OS side

## Acceptance Criteria

- [ ] Introduction frames Neo as "application engine with co-evolving Agent OS"
- [ ] Two Hemispheres diagram or prose present (simpler than `ArchitectureOverview.md` — this is a bootstrap doc, not a reference)
- [ ] Cognitive Loop (Perceive/Reason/Act/Reflect) mentioned with one-line explanations
- [ ] Dream Pipeline six phases listed (depth deferred to `DreamPipeline.md`)
- [ ] Closed Loop feedback idea communicated (minimum: "agent → memory → graph → handoff → next agent")
- [ ] Sub-agent profiles (Librarian, QA, Browser) mentioned with one-line purpose each
- [ ] Cross-links to `ArchitectureOverview.md`, `DreamPipeline.md`, `SwarmIntelligence.md`, `NeuralLink.md` present
- [ ] Line count stays comparable to current (~700 lines) — bootstrap doc, not reference. Depth goes to linked docs
- [ ] `learn/tree.json` updated if hierarchy shifts (probably not)
- [ ] At least one empirical validation: read the rewrite as a fresh bootstrap agent and verify the mental model formed matches "engine + co-evolving Agent OS"

## Out of Scope

- Deep Dream Pipeline internals — those live in `DreamPipeline.md`
- Deep MX principles — those need a dedicated guide if the concept formalizes (separate follow-up ticket)
- Multi-tenant Memory Core specifics — those live in the Memory Core Server guide
- Grid / frontend deep dives — CodebaseOverview.md links; specifics stay in guides

## Avoided Traps

- **Rejected: rewrite `ArchitectureOverview.md` instead.** That doc is the correct reference — the problem is only that the bootstrap doc doesn't point to it. Updating the wrong file would solve nothing.
- **Rejected: do it now.** Documentation written during architectural flux ages poorly. Wait for v12.2 stabilization.
- **Rejected: scope-creep to update every referenced downstream guide.** One doc at a time; downstream guides update naturally as their areas evolve.

## Related

- Parent epic: #9999 (Cloud-Native Knowledge & Multi-Tenant Memory Core) — this rewrite is the documentation-stabilization task that closes the epic loop for future agent onboarding
- Existing reference docs to digest: `learn/benefits/ArchitectureOverview.md`, `learn/agentos/DreamPipeline.md`
- Triggered by session insight: `#10074` (origin `51640d07`) — a bootstrap agent formed framework-category mental model despite engine-category correction being durable in memory; bootstrap doc was the load-bearing gap
- MX framing (durable memory `feedback_mx_model_experience.md` saved this session). If MX formalizes into a public guide between now and pickup, this rewrite introduces it briefly; full depth goes to the dedicated guide

Origin Session ID: 5a521819-dc75-4549-888e-fcea818d0401

## Timeline

- 2026-04-20T20:45:17Z @tobiu added the `documentation` label
- 2026-04-20T20:45:17Z @tobiu added the `enhancement` label
- 2026-04-20T20:45:17Z @tobiu added the `ai` label
- 2026-04-20T20:45:17Z @tobiu added the `architecture` label
- 2026-04-20T20:45:24Z @tobiu added parent issue #9999
- 2026-04-20T23:40:12Z @tobiu cross-referenced by PR #10140
- 2026-04-21T14:54:14Z @tobiu cross-referenced by PR #10162
- 2026-04-23T22:22:29Z @neo-opus-ada cross-referenced by #9999
### @neo-gpt - 2026-05-26T02:32:40Z

Closing this stale documentation ticket after live re-triage.

Original intent: prevent bootstrap-time category drift by making agents see Neo as engine + Agent OS / Brain rather than a web framework with AI tools attached. That intent is now satisfied by newer source-of-authority changes rather than by the originally proposed full `CodebaseOverview.md` rewrite.

V-B-A evidence:
- `AGENTS_STARTUP.md` Step 1 now reads `README.md` first as the organism identity / Four Pillars / Agent OS / MX-loop anchor, then `learn/guides/devindex/frontend/Architecture.md` for concise frontend architecture. It explicitly demotes `learn/guides/fundamentals/CodebaseOverview.md` to long-form reference material, not mandatory bootstrap.
- `README.md` now frames Neo as a self-evolving digital organism with Brain, Institution/Swarm, Body, and Evolution/MX-loop; this landed in `b59eef11f` (`docs(readme): rewrite around 4-pillar digital-organism identity (#10452) (#10455)`).
- `learn/benefits/ArchitectureOverview.md` already owns the requested Two Hemispheres, Cognitive Loop, Dream Pipeline, Golden Path, Neural Link, and Closed Loop reference sections; initial guide landed in `fc6bf3cb0` (`docs: add Agent OS Architecture Overview guide (#9981) (#9982)`).
- `learn/guides/fundamentals/CodebaseOverview.md` already links to `ArchitectureOverview.md`, `SwarmIntelligence.md`, and `DreamPipeline.md`, and already documents the Librarian / QA / Browser agent profiles.

Keeping #10136 open now asks for a low-ROI rewrite of a document that is no longer the boot mental-model authority. If a future gap appears, it should target the current boot anchors (`README.md`, `AGENTS_STARTUP.md`, `learn/benefits/ArchitectureOverview.md`) with a narrow new issue rather than reviving this stale prescription.

- 2026-05-26T02:32:41Z @neo-gpt closed this issue

