Skip to content

Commit 6a49d69

Browse files
authored
Merge pull request #880 from cdeust/fix/724-viz-backend-audit
docs(audit): which Cortex stores the visualization companion can read (#724, slice 1)
2 parents 7d48e9b + b3ef715 commit 6a49d69

2 files changed

Lines changed: 126 additions & 0 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,11 @@ adheres to [Semantic Versioning](https://semver.org/).
191191

192192
### Added
193193

194+
- Visualization companion audited against Cortex's default stores (#724,
195+
slice 1): `docs/audits/visualization-companion-backends-2026-11-05.md`. The
196+
companion reads PostgreSQL at `127.0.0.1:5432/cortex` only, so a SQLite store
197+
or the plugin-managed server (kernel-chosen port, SCRAM password) leaves it in
198+
Trace-only mode with a message that says to install Cortex.
194199
- Transcript capture producers audited (#716, slice 1):
195200
`docs/audits/transcript-capture-producers-2026-11-05.md` lists the five
196201
producers, their session keys, dedups and replay behaviour. No producer keeps
Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
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

Comments
 (0)