elizaos--eliza/plugins/plugin-vector-browser/AGENTS.md

@elizaos/plugin-vector-browser

A developer/system app plugin that contributes the Vector Browser view: an in-browser surface for browsing agent memories and visualising their embeddings as a list, a 2D canvas projection, and a 3D (three.js / WebGL) point cloud. The heavy three.js surface is shipped as a dynamically loaded view bundle so neither the component nor three ships in the always-loaded @elizaos/ui bundle.

Layout / exports

• src/index.ts — barrel. Re-exports the views, the plugin, and the snapshot types.
• src/plugin.ts — vectorBrowserPlugin (Plugin). Declares the single views[] entry (id: "vector-browser", developerOnly, modality gui, componentExport: "VectorBrowserView", served at /vector-browser).
• src/register.ts (export ./register, also appRegister in package.json) — side-effect module. Calls registerAppRoutePluginLoader so the agent can resolve Plugin.views and serve /api/views/vector-browser/bundle.js.
• src/VectorBrowserView.tsx — the rich GUI surface (VectorBrowserView, VectorBrowserRichView, VectorGraph3D). Loads three and queries memory tables via @elizaos/ui/api's client.
• src/VectorBrowserSpatialView.tsx — lightweight presentational summary kept for future adapter work plus the VectorBrowserPoint / VectorBrowserSnapshot types. The shipped route mounts the rich DOM/WebGL surface.
• test/ — VectorBrowserView.test.tsx, VectorGraph3D.test.tsx, the vector-browser-parser.contract.test.ts, and ui-stubs/ (per-specifier no-op stubs for @elizaos/ui subpaths that vitest's resolver can't resolve).

Exports map (package.json): . (barrel), ./plugin, ./register, ./*.css, and ./*. Build output goes to dist/ (including dist/views/bundle.js).

Key scripts (scope with --cwd)

bun run --cwd plugins/plugin-vector-browser build      # build:js + build:views (vite) + build:types
bun run --cwd plugins/plugin-vector-browser typecheck  # tsgo --noEmit
bun run --cwd plugins/plugin-vector-browser test       # vitest run (vitest.config.ts)
bun run --cwd plugins/plugin-vector-browser clean      # remove dist

build is three steps: build:js (tsup, shared plugin config), build:views (vite build with vite.config.views.ts), and build:types (tsc --noCheck).

Conventions / gotchas

• Lazy WebGL by design. Registration adds no eager three.js cost — the view bundle (and three) is only fetched when the view is actually mounted. Don't import three or the rich view from an always-loaded path.
• One shipped GUI declaration. The 3D point cloud and 2D canvas projection live in the rich DOM/WebGL view. The spatial summary remains a lightweight future-adapter seam, not a registered alternate view.
• Test resolver aliases. vitest.config.ts aliases each @elizaos/ui subpath the view imports to its own distinct no-op stub (vitest dedupes mocks by resolved path, so stubs must be separate files); the parser/layout module and the spatial barrel are aliased to real packages/ui/src source so contract tests exercise the real implementation.
• peerDependencies requires react >=18; react / three / @types/* are devDependencies. Runtime deps are @elizaos/core, @elizaos/shared, @elizaos/ui, lucide-react. No env vars.
• A host runtime can override the renderer via getBootConfig().companionVectorBrowser (THREE + createVectorBrowserRenderer); the default lazily imports three and prefers a WebGPU renderer when navigator.gpu is available.

Repo-wide rules (logger-only, ESM, naming, architecture) are in the root AGENTS.md.

⛔ NON-NEGOTIABLE — evidence, trajectories & real end-to-end tests

The binding, repo-wide standard is AGENTS.md. Read it. Nothing in this package is done until it is proven done — a reviewer must confirm it works without reading the code, from the artifacts you attach. This applies to every feature, fix, refactor, and chore here. "Tests pass" is not proof; "CI is green" is not proof.

• Record AND read model trajectories. Capture the actual inputs and outputs of the model from a live LLM — not the deterministic proxy, not a mock: the prompt, the providers/context, the raw model output, every tool/action call, and the result. Then open the trajectory and review it by hand. A captured-but-unread trajectory is not evidence (packages/scenario-runner/bin/eliza-scenarios run <scenario> --report <out>).
• Real, full-featured E2E — no larp. Every feature ships detailed end-to-end tests that drive the real path end to end. Not the happy "front door" only: cover error paths, edge/empty/invalid input, concurrency, roles/permissions, and adversarial input. A test that asserts against a mock/stub/fixture standing in for the thing under test does not count. If the real model/device/chain/connector/account is hard to reach, make it reachable — that is the work, not an excuse to mock. If the existing tests here are shallow or mocked, fixing them is part of your change.
• Screenshots + logs at every phase, plus a complete walkthrough video/run-through of the entire feature or view, start to finish (bun run test:e2e:record).
• Manually review every artifact the change touches — never just the green check: client logs (console + network), server logs ([ClassName] …), the model trajectories in and out, before/after full-page screenshots, and the domain artifacts listed below for this package.
• No residuals. No shortcuts. The goal is not "done" — it is everything done. Clear every blocker by the hard path: build the real architecture, stand up the real model/device/service, actually test it. Never leave a TODO, a stub, a stepping-stone, or a "follow-up." When unsure, research thoroughly, weigh the options, and ship the best, highest-effort, production-ready version. Keep going until every possibility is exhausted.

Artifacts → attached inline in the PR (MP4 video, JPG screenshots, logs in <details>); attach each evidence type or explicitly mark it N/A with a reason — never leave it blank. If develop moved and changed behavior, re-capture evidence; stale proof is worse than none.

Capture & manually review for this package — storage / memory:

• The actual rows / embeddings / documents written and read back, with their shape inspected — not a mock asserting itself.
• Query correctness: precision/recall on real data, ordering, pagination, and migration up/down.
• GC/retention, concurrency, and large-payload paths.
• A trajectory showing memory/knowledge actually recalled into a turn, where relevant.