odysseus/docs/handoff.md

# Memory Graph View — Handoff

Read this first if picking up this work in a new session. It answers: what's done, what's the very next thing to do, what could bite you, and why certain calls were made.

For the full checklist see `docs/todos.md`. For the session-by-session history see `docs/progress.md`. For the accepted design see `docs/memory-graph-design.md`. For the repo research behind it see `docs/memory-graph-analysis.md`.

## Where things stand right now

- **Branch**: `feature/memory-graph-view`.
- **Milestone 1 (backend API)**: done, tested, **committed**. One additional bug found and fixed during M2 verification (see below) — `memory_graph_routes.py`'s owner resolution was inconsistent with the rest of the memory routes, which made the graph always empty and links always 404 in single-user/no-auth mode. Committed separately (`fix(memory-graph): align owner resolution with rest of memory routes`).
- **Milestone 2 (frontend)**: done, **committed**, **visually verified** end-to-end against a real seeded dataset (render, node click + neighborhood highlight, detail panel, inline edit, search, category filters, similarity slider, link-mode create, theme switch — see `docs/progress.md` Session 4 for the full pass). Two frontend bugs found and fixed in the same commit: the detail panel's `hidden` class was never removed on node selection (panel was permanently invisible), and `_applySearch()` left stale `mg-dimmed`/`mg-highlighted` classes from a prior node selection that masked search-match nodes at `opacity:0.08`.
- **Milestone 3 (polish)**: not started. This is the next work.

## Exact next task

Resume the Milestone 3 checklist in `docs/todos.md` (legend refinement, isolate-component affordance, keyboard shortcuts, `MODULE_SUMMARY.md` update, a real automated-test pass for `memoryGraph.js`). Two things need explicit user sign-off before or during M3:

1. **The "feature flag enabled (beta)" open question** (see below) — confirm whether a real togglable flag is wanted, or whether the current privilege-gate + static "beta" label is sufficient as shipped.
2. Whether to also fix the known limitation that graph node colors are only recomputed on next render, not live-reactive to a theme flip while the modal is already open (confirmed still true during verification — switching theme via the Theme modal while Memory Graph was open did not immediately recolor node fills, though all non-canvas chrome — detail panel, chips, buttons — is CSS-variable-driven and did update live).

For a repeatable verification loop in a future session (isolated data dir, seeding via the real API, symmetric Chroma cleanup, PID-verified process kill), the exact steps used are preserved in `docs/progress.md` Session 4 — worth reusing as-is rather than re-deriving.

## Open decision needed from the user

**The "feature flag enabled (beta)" requirement was interpreted as "ship it visible, label it beta" — not as "build an actual on/off toggle."** Right now the only thing gating visibility of the "Memory Graph" nav item is the existing `can_manage_memory` privilege (the same gate the "Brain" button already uses), plus a static "beta" label next to the title in the modal header. There is no separate settings switch a user or admin could flip to hide the feature independent of that privilege, and no server-side flag either. If a real togglable flag was intended (e.g. a Settings-tab checkbox like the design doc's original Phase 2 proposal in `docs/memory-graph-design.md` §8), that hasn't been built. **Confirm which was actually wanted before Milestone 3.**

## Risks / things to watch

1. **The `src/agent_loop.py` one-line fix is uncommitted and out of this feature's actual scope.** It's a genuinely pre-existing bug (confirmed via `git stash` to reproduce identically on a clean `dev` checkout — `NameError: name 'Any' is not defined` because `dict[str, Any]` was used in a function signature without importing `Any`), and without it the entire app fails to import, which blocks any local verification at all. It's about as safe a fix as they come (adding a missing stdlib import can't break anything that currently works, since nothing downstream of that line currently works). But it wasn't asked for, so **don't fold it silently into a Memory Graph commit** — either commit it separately with a clear message, or ask the user whether they even want it touched at all (they may already have a fix for it elsewhere, or may want to report it upstream themselves).
2. **Do not seed demo/test memory data into the real ChromaDB without cleaning it up.** See step 4 above — this bit us mid-session (server was mid-startup, about to seed, when told to stop; it was killed before anything was written, so no cleanup is currently owed, but the *next* session doing this must not skip the deletion step).
3. **The dev venv (`.venv-test/`) is a throwaway, git-ignored (via `.git/info/exclude`, not `.gitignore`) local artifact**, created because this sandbox had no Python environment with the project's dependencies installed. It is NOT part of the repo and should not be referenced by anything committed. A future session may need to recreate it (`python -m venv .venv-test && .venv-test/Scripts/python.exe -m pip install -r requirements.txt`) if it's not still present.
4. **Pre-existing test failures are numerous (199) in this sandbox and are all environment-driven** (missing Node/`rg`, an `mcp` package version mismatch, Windows path-confinement assumptions) — confirmed byte-for-byte identical between this branch and a clean `dev` baseline. Don't waste time trying to fix them as part of this feature; they were already broken before this work started, and fixing them is a separate, unrelated effort.
5. **Chroma collections are global, not owner-scoped.** This was already true of the existing memory system before this feature (`docs/memory-graph-analysis.md` §10) and the graph feature doesn't change it, but it's exactly why step 4 above matters — any manual testing against a real/shared Chroma instance needs symmetric cleanup.

## Implementation notes worth knowing before touching this code

- **Route-ordering is load-bearing.** `routes/memory/memory_graph_routes.py` must be `include_router()`'d in `app.py` *before* `routes/memory/memory_routes.py`'s router. The latter's `GET/PUT/DELETE /api/memory/{memory_id}` is a single-segment wildcard; Starlette matches routes in registration order across the whole app (not by specificity), so `GET /api/memory/graph` would otherwise resolve to the wildcard with `memory_id="graph"` and 404. This is regression-tested in `tests/test_memory_graph_route_ordering.py` using a real `TestClient` — the only place in this feature's tests that a full ASGI app was actually needed, because the repo's usual "look up the route by exact path string, call the endpoint function directly" test convention can't catch this class of bug (it never exercises real Starlette path matching).
- **The runtime memory store is a JSON file, not the SQL `memories` table.** `src/memory.py::MemoryManager` persists to `data/memory.json`; there's a `memories` SQLAlchemy table in `core/database.py` too, but it's unused by any live code path (see `docs/memory-graph-analysis.md` §8's "Important discrepancy"). The Memory Graph feature correctly targets the JSON store + the `odysseus_memories` Chroma collection, matching what every other memory route already does. Don't be tempted to "fix" this by wiring the graph to the SQL table — that's explicitly out of scope (see the analysis doc).
- **Manual links are stored as a new optional `links: []` field directly on memory JSON entries.** No migration was needed because it's a JSON file, not a SQL schema — old entries without the field are handled via `entry.get("links", [])`/`mem.get("links") or []` throughout, so nothing breaks for pre-existing memories.
- **The frontend has zero bundler.** Cytoscape.js is vendored as a single UMD file (`static/lib/cytoscape.min.js`, fetched via `npm pack cytoscape@3` in a scratch dir — not a hand-typed CDN URL) and lazy-loaded via a dynamically-created `<script>` tag the first time the Graph modal opens, mirroring the exact pattern `documentLibrary.js` already uses for `xlsx.full.min.js`/`mammoth.browser.min.js` (`ensureXLSX`/`ensureMammoth` → `ensureCytoscape` in `memoryGraph.js`).
- **The modal itself is built entirely in JS, not in `index.html`.** `memoryGraph.js`'s `_getModal()` follows `calendar.js`'s `_getModal()` template exactly: lazily `document.createElement`'d on first open, appended to `document.body` once, memoized in a module-level variable, registered with `modalManager.js`'s `Modals.register(...)` (gets minimize/dock/restore/z-order for free — same mechanism gallery/notes/cookbook/calendar all use). This was a deliberate choice over adding static modal markup to `index.html` (which is how the older "Brain"/"Calendar" full-page structure looks from the HTML side, but their *actual* open/close JS logic turned out to live in `app.js`/`calendar.js`, not be purely declarative — worth rereading `docs/memory-graph-analysis.md` if this surprises you). Following the newer self-registering pattern meant **zero edits** to `app.js`'s older hardcoded Escape-key modal-id arrays (`modalItemMap`, `_modalSidebarMap`, `dynamicModals`) — the new modal manages its own Escape handling directly, exactly like `calendar.js` does.
- **Category colors are resolved from existing theme CSS custom properties** (`--fg`, `--hl-keyword`, `--warn`, `--color-accent`, `--color-brand-blue`, `--accent-warm`, `--green`) via `getComputedStyle(document.documentElement)` at render time — not hardcoded hex values — so dark/light theme support came largely for free. **Known limitation**: colors are only (re)computed when the graph is (re)rendered (on open, or after a mutation reload), not on a live theme-toggle while the modal is already open. Flipping the theme mid-session and expecting instant recolor without reopening the modal is a Milestone 3 nice-to-have, not yet built.
- **Filtering is entirely client-side; only the initial load hits the backend.** The graph is fetched once per open (or after a mutation) at a generous floor (`min_similarity=0.5`, `max_edges_per_node=8`) and cached in memory; the category chips, the similarity slider, and the search box all operate on that cached copy via Cytoscape's own `style('display', ...)`/class toggling. This was a deliberate deviation from a literal reading of the design doc's per-request query params (`docs/memory-graph-design.md` §3) — it makes filter interactions instant instead of a round-trip per click, at the cost of the UI slider not being able to go below 0.5 (the server floor). Worth flagging as a design refinement, not an oversight.
- **Nav item scope was deliberately kept to the sidebar Tools list only.** There's also a separate, fixed-size compact "icon rail" (mobile/collapsed-sidebar duplicate) in `index.html` with a hardcoded `_railToolMap` in `app.js` — extending that to add a Memory Graph icon was skipped as out of scope for this milestone (higher risk of visually cramming a fixed-width icon strip, not explicitly requested). If compact/mobile nav parity is wanted, that's a small, well-scoped follow-up.