> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase18-session02-mnemosyne-constellation-readonly/spec.md). # Session Specification **Session ID**: `phase18-session02-mnemosyne-constellation-readonly` **Phase**: 18 - Hermes Memory And Visualization **Status**: Completed **Created**: 2026-06-02 *** ## 1. Session Overview This session adds the Hermes Mnemosyne constellation as a read-only, code-split 3D tab inside the existing Hermes host cockpit. Phase 18 Session 01 already upgraded the Memory tab with token-gated memory/profile reads and the admin-gated Obsidian bridge, so this session can derive visualization data from the existing `memory`, `sessions`, `pantheon`, and Obsidian connection state without introducing new write behavior or new bridge endpoints. The v2.3 source anchor is `/home/aiwithapex/projects/claudeos/claude-os-v2.3/src/components/hermes-mnemosyne.tsx`. The port should preserve the useful behavior: Hermes as a central node, memory fragments, SOUL, personas, recent sessions, source toggles, view modes, bloom, and slow auto-orbit. The AI OS version must use current project contracts, assets, storage keys, and bundle-budget conventions instead of copying the old fetch hooks or legacy localStorage key. This was the final planned Phase 18 session. Implementation, validation, and PRD closeout have now completed for this phase. *** ## 2. Objectives 1. Add a lazy-loaded `Mnemosyne` Hermes tab that does not inflate the base Hermes route bundle. 2. Build a read-only graph data adapter from existing Hermes query views with bounded labels, empty-state reasons, and exhaustive state handling. 3. Render the v2.3-inspired 3D constellation with raw `three`, `react-force-graph-3d`, bloom, source toggles, view modes, reduced-motion handling, and cleanup on unmount. 4. Verify bundle impact, component behavior, and browser rendering with focused tests plus screenshot/canvas checks. *** ## 3. Prerequisites ### Required Sessions * [x] `phase16-session01-guardrails-architecture-parity-baseline` - Provides the Hermes guardrail baseline and sensitive-read rules. * [x] `phase16-session02-backend-endpoint-parity-write-safety` - Provides token-gated Hermes read endpoints and admin-gated write endpoint safety. * [x] `phase16-session03-data-layer-demo-fixtures` - Provides typed Hermes hook contracts and demo fixtures. * [x] `phase17-session01-visual-system-shell-status-pill` - Provides the Hermes shell and local visual primitives. * [x] `phase17-session02-chat-tab-write` - Provides established admin write UI patterns. * [x] `phase17-session03-pantheon-upgrade-write` - Provides Pantheon data and Hermes tab composition. * [x] `phase18-session01-memory-upgrade-write` - Provides upgraded memory/profile data shapes and Obsidian connection storage. ### Required Tools/Knowledge * React 19, TanStack Query, Radix Tabs, Tailwind CSS 4, lucide-react. * Existing Hermes contracts in `src/lib/hermes-types.ts`. * Existing Hermes visual primitives in `src/components/hermes/hermes-page-primitives.tsx`. * Existing 3D memory graph patterns in `src/components/memory-graph-3d.tsx`. * Bundle-budget script behavior in `scripts/check-bundle-budget.sh`. ### Environment Requirements * Bun 1.3.14 project environment. * Browser-only 3D imports must be lazy/dynamic and safe for SSR. * No live Hermes home, admin token, or Obsidian vault is required for automated tests. *** ## 4. Scope ### In Scope (MVP) * User can open a `Mnemosyne` tab in `/agents/hermes` - add a code-split tab and Suspense fallback in `src/components/hermes/hermes-read-only-page.tsx`. * User can inspect read-only memory constellation data - derive nodes and links from existing memory fragments, SOUL, Pantheon personas, recent sessions, and Obsidian connection state. * User can switch visualization modes - implement constellation, spheres, and drift/random-like modes with accessible segmented controls. * User can toggle Hermes and Obsidian sources - consume the current `ai-os.hermes.obsidian-connected.v1` key and disable Obsidian view when disconnected. * Maintainer can validate performance - record the bloom approach decision and bundle-budget results. * Maintainer can verify browser behavior - add focused component/data tests and Playwright screenshot/canvas-pixel checks for desktop and mobile. ### Out of Scope (Deferred) * Any write behavior - Reason: Mnemosyne is read-only and Session 01 owns the Obsidian write UI. * New Hermes bridge endpoints - Reason: existing hook/query views already provide required data. * Adding `postprocessing`, `@react-three/fiber`, or other heavy visualization dependencies - Reason: raw `three` and existing force-graph imports should satisfy MVP bloom needs. * Mission Control, Documents Gallery, Connections, and long-tail Hermes sections - Reason: later phases own those surfaces. * Public `/memory` route redesign - Reason: this session is scoped to the Hermes agent page. *** ## 5. Technical Approach ### Architecture Create a dedicated Mnemosyne component under `src/components/hermes/` and load it lazily from `HermesReadOnlyPage`. Keep the heavy `react-force-graph-3d`, `three`, and `UnrealBloomPass` imports inside the lazy component, using dynamic imports guarded by React effects so SSR and tests do not load WebGL code. Add a small data adapter that accepts existing Hermes query views and returns a typed graph model. This keeps the data derivation testable without rendering a WebGL canvas. The component consumes that graph model, handles non-success states explicitly, and displays a bounded empty state when all sources are disabled or unavailable. ### Design Patterns * Code-split visualization: the tab component and 3D vendor code load only when the tab renders. * Contract-first data: reuse `HermesMemoryBody`, `HermesSessionsBody`, and `HermesPantheonBody` instead of adding endpoint clients. * Exhaustive states: account for loading, empty, error, offline, token-failure, success, and demo query views. * Read-only source toggles: toggles affect visualization only and never perform bridge writes. * Cleanup-first effects: cancel dynamic import work, animation frames, resize observers, storage/focus listeners, and graph side effects on unmount. ### Technology Stack * React 19 with TypeScript. * Radix Tabs and existing Hermes primitives. * `react-force-graph-3d` and raw `three` `^0.184.0`. * `three/examples/jsm/postprocessing/UnrealBloomPass.js` for bloom if it works within the existing dependency set. * Vitest, Testing Library, and Playwright for validation. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------- | | `src/components/hermes/hermes-mnemosyne.tsx` | Lazy 3D Mnemosyne tab UI, canvas, controls, bloom, and state rendering | \~520 | | `src/components/hermes/hermes-mnemosyne-data.ts` | Typed graph node/link derivation from existing Hermes query views | \~220 | | `src/components/hermes/__tests__/hermes-mnemosyne.test.tsx` | Focused data and component tests for Mnemosyne behavior | \~180 | | `.spec_system/specs/phase18-session02-mnemosyne-constellation-readonly/implementation-notes.md` | Implementation decisions, bloom decision, validation commands, and bundle notes | \~80 | ### Files to Modify | File | Changes | Est. Lines | | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------- | | `src/components/hermes/hermes-read-only-page.tsx` | Add lazy Mnemosyne tab, Suspense fallback, and prop wiring | \~45 | | `src/components/hermes/__tests__/hermes-sections.test.tsx` | Extend Hermes page mode-matrix coverage for the lazy Mnemosyne tab | \~80 | | `scripts/check-bundle-budget.sh` | Update comments/patterns only if the new lazy chunk needs an explicit known-vendor label | \~10 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `Mnemosyne` appears as a Hermes tab and lazy-loads behind Suspense. * [ ] The base Hermes page renders without importing the 3D vendor chunk before Mnemosyne opens. * [ ] Mnemosyne renders Hermes, memory, SOUL, persona, session, and connected-Obsidian nodes from existing data. * [ ] Source toggles and view modes update the graph without mutating any bridge/admin state. * [ ] Loading, empty, error, offline, token-failure, success, and demo states render explicit user-facing states. * [ ] Reduced-motion users can pause or avoid auto-orbit behavior. ### Testing Requirements * [ ] Data adapter tests cover bounded labels, empty input, SOUL template filtering, session caps, Obsidian connected/disconnected states, and exhaustive state fallbacks. * [ ] Component tests cover tab wiring, lazy fallback, source toggles, view controls, empty state, and accessibility labels. * [ ] Playwright verifies desktop and mobile rendering with screenshots and canvas-pixel checks proving the 3D canvas is nonblank and framed correctly. * [ ] Bundle validation records whether raw `three` bloom was sufficient and proves no unnecessary dependency was added. ### Non-Functional Requirements * [ ] No new write path, bridge endpoint, personal data collection, or third-party transfer is introduced. * [ ] Sensitive memory/profile/session data remains within existing token-gated hook contracts. * [ ] Client labels are bounded and do not expose raw private paths or vault contents. * [ ] Lazy vendor chunks remain within the configured bundle budget. * [ ] Animation frames, listeners, dynamic imports, and graph resources clean up on unmount. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] No new global `findtrend` identifiers. * [ ] Typecheck, lint, focused tests, build, and bundle budget pass or any unrelated pre-existing failure is documented. *** ## 8. Implementation Notes ### Key Considerations * The old v2.3 component fetches directly from Hermes endpoints; the AI OS port should consume current hook views passed by `HermesReadOnlyPage`. * The old v2.3 Obsidian connected key was `claude-os.hermes.obsidian-connected.v1`; current AI OS Session 01 uses `ai-os.hermes.obsidian-connected.v1`. * `react-force-graph-3d`, `three`, and `UnrealBloomPass` are already used by the `/memory` route and should be reused before considering any new dependency. * The UI should feel like an operational Hermes tab, not a marketing hero or separate landing surface. ### Potential Challenges * WebGL modules can break SSR or happy-dom tests: keep imports dynamic and mockable. * Bloom can wash out the scene: start from the tuned `memory-graph-3d.tsx` approach and record final values in implementation notes. * Large 3D chunks can fail the bundle budget: lazy-load the tab and run `bun run build` plus `bun run budget:check`. * Canvas can trap scrolling on mobile: preserve a scroll gutter or disable problematic wheel/pan behavior where needed. ### Relevant Considerations * \[P01] **Bundle budget watch on 3D vendor chunks**: Code-split the tab and keep lazy vendor chunks within the 450 KB gzip budget. * \[P04] **Hermes bridge guardrails must stay intact**: Mnemosyne must not introduce writes or bypass token-gated sensitive reads. * \[P17] **One write surface per capability**: Obsidian writes stay in the Memory tab; Mnemosyne only reads the connected flag. * \[P17] **Redact and bound high-risk write feedback**: Do not expose vault contents or raw local paths in constellation labels. * \[P00] **Stack conventions**: Keep Bun, Vite, TanStack Start, React 19, Radix UI, and Cloudflare compatibility constraints intact. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Heavy 3D modules can load too early unless both the tab and vendor imports are lazy. * Graph effects can leak animation frames, listeners, or pending imports unless cleanup is explicit. * State transitions can look broken unless loading, empty, error, offline, token-failure, success, and demo paths are first-class. * The canvas can be blank, over-zoomed, or unusable on mobile unless browser screenshots and pixel checks verify framing. *** ## 9. Testing Strategy ### Unit Tests * Test `hermes-mnemosyne-data.ts` for node/link construction, source filters, bounded labels, SOUL template filtering, session caps, and empty/error state mapping. * Test `hermes-mnemosyne.tsx` with mocked graph imports for controls, fallbacks, source toggles, view modes, and accessibility names. * Extend `hermes-sections.test.tsx` to confirm the lazy tab is present and does not break live/demo mode matrix behavior. ### Integration Tests * Run focused Vitest for Hermes sections and Mnemosyne tests. * Run `bun run typecheck`, `bun run lint`, `bun run build`, and `bun run budget:check`. * If the budget script needs an explicit pattern for the new chunk, update comments or patterns only with measured evidence. ### Manual Testing * Visit `/agents/hermes`, open `Mnemosyne`, and verify live/setup-required/demo states. * Toggle Hermes and Obsidian sources, switch view modes, pause/resume orbit, and resize from desktop to mobile widths. * Confirm the Obsidian toggle is disabled unless Session 01 has marked the vault connected. ### Edge Cases * Memory succeeds with empty USER/MEMORY and template SOUL. * Sessions succeed with more than 12 rows and missing first-user messages. * Pantheon succeeds with missing avatar/model details. * Memory succeeds while sessions or Pantheon are empty/error/offline/token-failure. * Obsidian connected flag changes from another tab or after returning focus. * Dynamic import resolves after unmount. * Browser lacks WebGL or prefers reduced motion. *** ## 10. Dependencies ### External Libraries * `react-force-graph-3d`: existing dependency, lazy-loaded. * `three`: existing dependency, lazy-loaded. * `three/examples/jsm/postprocessing/UnrealBloomPass.js`: existing `three` example module for bloom. ### Internal Dependencies * `src/components/hermes/hermes-read-only-page.tsx` for tab wiring. * `src/components/hermes/hermes-page-primitives.tsx` for state and status primitives. * `src/lib/hermes-types.ts` for parser-backed Hermes contracts. * `src/lib/hermes-demo-data.ts` for demo memory, sessions, and Pantheon fixtures. * `src/components/memory-graph-3d.tsx` for proven force-graph, bloom, orbit, and scroll behavior patterns. * `scripts/check-bundle-budget.sh` for chunk budget validation. ### Other Sessions * Depends on: `phase18-session01-memory-upgrade-write` and all Phase 16-17 Hermes foundation sessions. * Depended by: Phase 19 Hermes Orchestration And Documents and Phase 20 Hermes Long-Tail And Parity Sign-off. *** ## Next Steps Run the `implement` workflow step to begin AI-led implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase18-session02-mnemosyne-constellation-readonly/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.