ui files missing from plugin?

[darval]

I am just installed 2.3.0 and most appears to be working.

/cortex-visualize

Claude’s response:
_We already tried both of these and they failed — the UI HTML files aren't bundled in the Cortex 2.3.0 package. The ui/ directory is completely missing from the installed package at /Users/rick/.cache/uv/archive-v0/.../site-packages/.

This is a packaging bug in Cortex 2.3.0 — the memory-dashboard.html and unified-viz.html files weren't included in the distribution. The backend data is all working fine (codebase_analyze just pulled 3,636 entities), it's just the browser frontends that are missing.

You could file an issue with the Cortex plugin maintainer, or wait for a 2.3.1 fix. In the meantime, the CLI tools (recall, navigate_memory, memory_stats, etc.) give you the same underlying data — just without the pretty browser UI._

[cdeust]

Thanks for reporting the issue, fixing at the moment the issue. Next release 2.4.0 will be including the fix

[cdeust]

@darval Feel free to test out with version 2.4.0

[darval]

I tried. ;) Turns out that they were there in both 2.3.0 and 2.4.0. According claude, this is the issue.

Diagnosis: Cortex UI Files Not Found
The problem: The get_ui_root() function in http_common.py resolves the ui/ directory relative to file (the Python source file's location). It checks two paths:

Installed layout: Path(file).parent.parent / "ui" → resolves to the uv cache at /Users/rick/.cache/uv/archive-v0/hgf6fILW-uJgm8pyJ1dbM/lib/python3.12/site-packages/ui/ — doesn't exist
Dev layout: Path(file).parent.parent.parent / "ui" → resolves to .../lib/python3.12/ui/ — also doesn't exist
Meanwhile, the actual ui/ directory with all the HTML files is at the plugin root: /Users/rick/.claude/plugins/cache/cortex-plugins/cortex/2.4.0/ui/

Why it happens: The MCP config sets cwd to ${CLAUDE_PLUGIN_ROOT} and runs python3 -m mcp_server, but the Python runtime resolves file to wherever the code is physically installed (the uv archive cache), not the working directory. The ui/ assets ship with the plugin root but aren't copied into the uv virtualenv's site-packages.

Is this caused by MCP-first then plugin install? Possibly a contributing factor, but the core issue is architectural: the get_ui_root() function assumes ui/ is either inside the Python package or one level above it. In the Claude Code plugin layout, the code runs from a uv-managed virtualenv cache while the static assets live in the plugin cache — two completely separate directory trees. This would likely break for any fresh plugin install regardless of order.

Suggested fix for maintainer: get_ui_root() should also check the CLAUDE_PLUGIN_ROOT environment variable (already set by the MCP config's cwd field) or os.getcwd() as a fallback path:

Plugin layout: CLAUDE_PLUGIN_ROOT/ui/

plugin_root = os.environ.get("CLAUDE_PLUGIN_ROOT")
if plugin_root:
plugin_ui = Path(plugin_root) / "ui"
if plugin_ui.is_dir():
return plugin_ui

[cdeust]

Relative path from mcp is always driving me crazy. Making a fix, thanks for diagnosis, it helps so much.

[cdeust]

@darval Tested the release 2.4.1 with multiple version of uv and python seems to be ok. Could you let me know if it solves the issue ?

[darval]

If I don’t get there tonight, I will check in the morning. I figure I might have screwed it up on my original install as i installed the mcp, since I have my own postgres server I wanted to use. Then realised I wanted the plugin. Claude helped me clean it up, but we may have residual problems. I will try the update and see what happens.

[cdeust]

Let me know, and if you still have some issues, we can try to fix them out together if you want.

[darval]

Ok, I tried it on my existing project and it was still broken. So I tried it on a different project, still had to struggle through the setup (might be me as much as anything). The biggest setup issue is I am using a different (external postgres db), but once I got that connected, it appears to work, and the visualization IS working.
I need to go back now and compare the two projects and understand why it doesn’t work yet for the original.

[cdeust]

@darval Could you indicate me which postgres db you're using could give me a lead on what fail to work with your setup?

[darval]

Sure Postgresql 17.8 on a debian vm
│ Extension │ Version │ Purpose │
│ plpgsql │ 1.0 │ Default procedural language │
│ pg_stat_statements │ 1.11 │ Query performance tracking (enabled per your alloy.conf tuning) │

And on the cortex db
pgvector 0.8.2, pg_trgm 1.6

[cdeust]

Circling back on the issue

CLAUDE DIAGNOSIS (to take lightly):

These are the likely causes (in order of probability):

1. Schema cascade failure (just fixed) — one DDL statement failing silently killed 7+ subsequent tables
2. CREATE EXTENSION permissions — external DB user may not be superuser. If CREATE EXTENSION IF NOT EXISTS vector fails because the user lacks privileges, every vector-dependent operation breaks. The extensions need to be created by a DBA beforehand (which he did — pgvector 0.8.2 and pg_trgm 1.6 are installed)
3. content_tsv generated column — to_tsvector('english', content) requires the english text search configuration. On a minimal Debian PG install this might be missing if postgresql-contrib wasn't installed. This would prevent the entire memories table from being created
4. DATABASE_URL format — external DB needs postgresql://user:password@host:port/dbname. If the password has special chars (@, /, %) they need URL-encoding
5. SSL requirement — external Debian PG might require sslmode=require in the connection string. Our code doesn't handle this — it's up to the user's DATABASE_URL

What is already handled now:

• pgvector 0.8.2 supports <=> and HNSW ✓
• PG 17.8 supports all SQL features we use ✓
• pg_trgm 1.6 supports gin_trgm_ops ✓

[darval]

I think we might be getting distracted with the postgres stuff, since it appears to all be working (including the ui) on the second project I enabled it on. This means it is back to where we started with it not finding the right directory in that first project. I will get claude to help me examine the diffs between the setup for the two projects and see if we can identify why it works on project 2 and not on project 1.