|
| 1 | +# Visualization companion against Cortex's default stores (audit, 2026-11-05) |
| 2 | + |
| 3 | +First slice of #724. The issue asks to audit and reuse the existing companion |
| 4 | +(`hypermnesia-mcp-viz`, repository `cdeust/cortex-viz`) before anything else. |
| 5 | +This document answers one question: from a default Cortex install, which |
| 6 | +companion views can read the user's memory store, and what does the user see |
| 7 | +when they cannot. It changes no code. |
| 8 | + |
| 9 | +Revisions read: Cortex `main` at `2126d2a`; companion `main` at `e9c1a31` |
| 10 | +(read-only shallow clone). Nothing was executed against a user datastore: every |
| 11 | +statement below is read from the cited lines. Statements marked *inferred* were |
| 12 | +derived from code, not observed in a running process. |
| 13 | + |
| 14 | +## 1. The stores a default Cortex install writes |
| 15 | + |
| 16 | +| Install path | Store | URL shape | Cited | |
| 17 | +|---|---|---|---| |
| 18 | +| Plugin, no database configured (Windows, older glibc, or no `claude --init-only`) | SQLite file `~/.claude/methodology/memory.db` | none (file path) | `PRIVACY.md:34` | |
| 19 | +| Plugin after `claude --init-only` on macOS / Linux glibc ≥ 2.36 | Plugin-managed PostgreSQL on loopback | `postgresql://postgres:<password>@127.0.0.1:<port>/cortex` | `PRIVACY.md:44`; `mcp_server/infrastructure/managed_pg.py:36-38`, `:140-143` | |
| 20 | +| CLI / dev, or `install-plugin.sh --postgres` | User-configured PostgreSQL | whatever `DATABASE_URL` names | `docs/agent-guidance.md` § Cortex | |
| 21 | + |
| 22 | +The managed server's port is not fixed. The first start passes no preferred port |
| 23 | +(`mcp_server/infrastructure/managed_pg_supervisor.py:118`), and `free_port` |
| 24 | +then binds port 0, i.e. any free port chosen by the kernel |
| 25 | +(`mcp_server/infrastructure/managed_pg_server.py:69-78`, `:165`). A restart |
| 26 | +reuses the recorded port when it is free (`managed_pg_supervisor.py:75-79`). |
| 27 | +The password lives in a file under the managed root (`managed_pg.py:69-70`, |
| 28 | +`:142`), and the cluster requires it (`--auth=scram-sha-256`, |
| 29 | +`scripts/launcher_pg_provision.py:71`). |
| 30 | + |
| 31 | +## 2. What the companion reads |
| 32 | + |
| 33 | +- The companion reads PostgreSQL only. Its reader is built on `psycopg` and |
| 34 | + `psycopg_pool` (`cortex_viz/infrastructure/memory_read.py:43-45`); its |
| 35 | + startup probe treats any `psycopg.Error` as "no database" |
| 36 | + (`cortex_viz/infrastructure/db_probe.py:60-100`). |
| 37 | +- Its default URL is `postgresql://127.0.0.1:5432/cortex`, set in four places: |
| 38 | + `cortex_viz/infrastructure/memory_config.py:52`, |
| 39 | + `cortex_viz/infrastructure/memory_read.py:51`, `scripts/launcher.py:269-270` |
| 40 | + and the plugin's `database_url` setting (`.claude-plugin/plugin.json:25`). |
| 41 | +- `memory_config.py:54-55` declares `SQLITE_FALLBACK_PATH` and |
| 42 | + `STORE_BACKEND = "auto" # "auto" | "postgresql" | "sqlite"`, but no other |
| 43 | + line of `cortex_viz/` or `scripts/` reads either setting (`grep -rn` |
| 44 | + over both trees). The SQLite option is declared, not implemented. |
| 45 | +- Nothing in the companion reads Cortex's managed-server status or password |
| 46 | + file (`grep -rni "managed.pg\|backend_marker"` over `cortex_viz/` and |
| 47 | + `scripts/`: no match). |
| 48 | + |
| 49 | +## 3. Result per default store |
| 50 | + |
| 51 | +| Cortex store | Companion default URL reaches it? | Views served | Cited | |
| 52 | +|---|---|---|---| |
| 53 | +| SQLite (`memory.db`) | No: not a PostgreSQL server | Trace only | §2 | |
| 54 | +| Managed PostgreSQL | No (*inferred*): port is kernel-chosen, not 5432, and the URL carries no password | Trace only | §1, §2 | |
| 55 | +| User PostgreSQL on `127.0.0.1:5432/cortex` without password | Yes | all six | §2 | |
| 56 | +| User PostgreSQL elsewhere | Only after the user copies the URL into the companion's `database_url` | all six | companion `README.md:75` | |
| 57 | + |
| 58 | +The managed-PostgreSQL row is *inferred* (not run): even a managed server that |
| 59 | +the kernel happened to place on port 5432 would refuse the password-less URL, |
| 60 | +because its cluster is created with `--auth=scram-sha-256` |
| 61 | +(`scripts/launcher_pg_provision.py:71`). |
| 62 | + |
| 63 | +## 4. What the user sees when the store is not reached |
| 64 | + |
| 65 | +The companion starts in no-DB mode and keeps Trace (companion `README.md:92`). |
| 66 | +The five store-backed views (Graph, Brain, Knowledge, Wiki, Board) answer HTTP |
| 67 | +503 with: |
| 68 | + |
| 69 | +> hypermnesia-mcp-viz is running in no-DB mode (Trace only). Install Cortex |
| 70 | +> (https://github.com/cdeust/Cortex) and point DATABASE_URL at its PostgreSQL to |
| 71 | +> enable this view. |
| 72 | +
|
| 73 | +(`cortex_viz/server/http_standalone_nodb.py:66-91`.) The startup line on stderr |
| 74 | +says the same and adds "Start Cortex's PostgreSQL or fix DATABASE_URL" |
| 75 | +(`db_probe.py:87-96`). |
| 76 | + |
| 77 | +For a user whose Cortex runs on SQLite, both messages are wrong about the |
| 78 | +cause: Cortex is installed and has no PostgreSQL to start. This is the case the |
| 79 | +issue's third acceptance item names ("a failed dependency must not look like |
| 80 | +an empty memory store"): here the store is not empty, it is absent from the |
| 81 | +companion's view, and the message points at an install the user already has. |
| 82 | + |
| 83 | +## 5. What Cortex's own documentation says |
| 84 | + |
| 85 | +`README.md:149-165` names the companion in the rename notice and `README.md:577` |
| 86 | +in the locality statement; no line of |
| 87 | +`README.md`, `PRIVACY.md` or `docs/codex-plugin.md` says that its five |
| 88 | +store-backed views need PostgreSQL (`grep -n -i "viz\|visual"` over the three |
| 89 | +files). The companion's own README states it (`README.md:75`, `:92`), so a |
| 90 | +Cortex user learns it only after installing the companion. |
| 91 | + |
| 92 | +## 6. Dead read client in Cortex |
| 93 | + |
| 94 | +`mcp_server/infrastructure/viz_client.py` (106 lines, ADR-0623) was written for |
| 95 | +the `query_workflow_graph` handler. That handler is no longer in `mcp_server/` |
| 96 | +(`grep -rln query_workflow_graph mcp_server`: only `viz_client.py` itself), and |
| 97 | +no module imports `viz_client` (`grep -rn viz_client mcp_server`: no match |
| 98 | +outside the file). Only `tests_py/infrastructure/test_viz_client.py` exercises |
| 99 | +it. GitHub commit search places the extraction of the visualization stack in |
| 100 | +`77dba678` (2026-06-13) and `67286929` (v3.21.0, 2026-06-15); this shallow |
| 101 | +clone does not hold that history, so the exact removal commit is not verified. |
| 102 | + |
| 103 | +## 7. Remaining slices of #724 |
| 104 | + |
| 105 | +Ordered so that each is autonomous and the owner's product decision comes |
| 106 | +first, per the issue's *Alternatives considered*: |
| 107 | + |
| 108 | +1. **Decision (owner):** the companion reads SQLite (implement the declared |
| 109 | + `STORE_BACKEND`), or the companion stays PostgreSQL-only and both READMEs say |
| 110 | + so. Either is consistent with the issue; it is a product choice. |
| 111 | +2. **Companion:** discover the managed server's URL (status port and password |
| 112 | + file) instead of the fixed `5432` default, when the plugin-managed store is |
| 113 | + the one Cortex uses. Companion-owned work, per the issue's last acceptance |
| 114 | + item. |
| 115 | +3. **Companion:** the no-DB message distinguishes "Cortex not found" from |
| 116 | + "Cortex found on a store this companion cannot read" (§4). |
| 117 | +4. **Cortex:** one line in `README.md` next to the companion link stating which |
| 118 | + stores its views read (§5), once slice 1 is decided. |
| 119 | +5. **Cortex:** remove `viz_client.py` and its test, or give it a caller (§6). |
| 120 | +6. The rendered-UI acceptance items (keyboard, reduced motion, viewports, local |
| 121 | + assets) belong to the companion repository and need a running browser. |
0 commit comments