> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/knowledge-graph/knowledge-graph-handover.md). # Knowledge Graph Handover This handover is for maintainers continuing the AI OS Knowledge Graph Shared Brain work. It maps the upstream Claude OS graphify behavior into the shipped AI OS architecture. ## Current State Phase 26 ships a local Knowledge Graph product slice: * Typed graphify graph and registry contracts. * Committed AI OS self-graph seed for fresh clones. * Loopback-only read bridge for registry and graph files. * Admin-gated ingest and remove bridge. * Reusable lazy 3D renderer. * `/knowledge-graph` route with gallery, hero, side rail, ingest UI, starter questions, grounded Hermes chat, and connect prompt. * Home Shared Brain preview. * Shared-brain setup and agent-to-dashboard scripts. The session closeout is documentation and validation only. It should not add new endpoint behavior or graph schema fields. ## Architecture Map ``` src/routes/knowledge-graph.tsx -> KnowledgeGraphPage -> useKnowledgeGraph() -> /__graphify_list -> /__graphify_graph?id= -> bundled seed or demo fallback -> useKnowledgeGraphToken() -> /__token -> useKnowledgeGraphAdmin() -> /__graphify_admin_status -> /__graphify_ingest -> /__graphify_remove -> KnowledgeGraphGroundedChat -> HermesChatTab with graphify grounding vite.config.ts configureServer -> registerKnowledgeGraphDevBridge() -> registerKnowledgeGraphAdminBridge() src/data/graphs/index.json -> registry source of truth src/data/graphs/.json -> graphify NetworkX node-link graph payloads ``` ## File Map | Area | Files | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Route | `src/routes/knowledge-graph.tsx` | | Page composition | `src/components/knowledge-graph/knowledge-graph-page.tsx` | | 3D renderer | `src/components/knowledge-graph/knowledge-graph-3d.tsx`, `src/components/knowledge-graph/knowledge-graph-loader.tsx`, `src/components/knowledge-graph/knowledge-graph-panel.tsx` | | Gallery and details | `src/components/knowledge-graph/knowledge-graph-project-gallery.tsx`, `src/components/knowledge-graph/knowledge-graph-side-rail.tsx`, `src/components/knowledge-graph/knowledge-graph-hero.tsx` | | Admin UI | `src/components/knowledge-graph/knowledge-graph-ingest-card.tsx` | | Grounded chat | `src/components/knowledge-graph/knowledge-graph-grounded-chat.tsx`, `src/lib/knowledge-graph-hermes-grounding.ts` | | Connect prompt and starters | `src/components/knowledge-graph/knowledge-graph-connect-prompt.tsx`, `src/components/knowledge-graph/knowledge-graph-starter-chips.tsx`, `src/lib/knowledge-graph-connect-prompt.ts` | | Home preview | `src/components/home/knowledge-graph-section.tsx`, `src/lib/knowledge-graph-home-summary.ts` | | Read hook | `src/hooks/use-knowledge-graph.ts` | | Admin hook and token hook | `src/hooks/use-knowledge-graph-admin.ts`, `src/hooks/use-knowledge-graph-token.ts` | | Graph contracts | `src/lib/knowledge-graph-types.ts`, `src/lib/knowledge-graph-admin-types.ts` | | Demo data | `src/lib/knowledge-graph-demo-data.ts` | | Read bridge | `scripts/lib/knowledge-graph-dev-bridge.ts` | | Admin bridge | `scripts/lib/knowledge-graph-admin-bridge.ts` | | Setup scripts | `scripts/setup-graphify-brain.sh`, `scripts/graph-to-dashboard.sh` | | Seed data | `src/data/graphs/index.json`, `src/data/graphs/ai-os.json` | ## Data Contract Graph payloads follow graphify NetworkX node-link shape: * `nodes` is required. * `links` is required. * Node `id` values are canonical identity and must be unique. * Link `source` and `target` must reference existing node ids. * Link confidence is `EXTRACTED`, `INFERRED`, or `AMBIGUOUS`. * Missing link confidence defaults to `INFERRED`. * Missing node labels default to the node id. * Missing node file type defaults to `concept`. * Metadata is derived from parsed graph content. Registry entries must include: * `id` as lowercase kebab-case. * `name`, `description`, `lang`, `color`. * `nodeCount`, `edgeCount`, `communities`, `extractedPct`. * `godNodes`. * `graphPath`. * `provenance`. Browser-visible registry `graphPath` values are projected as `src/data/graphs/*.json`. Local setup may backfill absolute paths for external agent skills, but the dev bridge resolves and re-projects them before returning registry entries to the browser. ## Endpoint Contract | Method | Path | Purpose | Access | | -------- | ---------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------- | | `GET` | `/__graphify_list` | Return sorted registry entries, pruning stale graph artifacts and missing local source paths | Loopback only | | `GET` | `/__graphify_graph?id=` | Stream a graph JSON file or fall back to bundled seed graph | Loopback only | | `GET` | `/__graphify_admin_status` | Return local admin gate and optional graphify availability | Loopback only | | `POST` | `/__graphify_ingest` | Run graphify for a local path or Git URL and upsert registry and graph artifact | Loopback only, token required, admin gate | | `DELETE` | `/__graphify_remove?id=` | Remove one registry entry and its confined graph artifact | Loopback only, token required, admin gate | Admin writes require `HERMES_DASHBOARD_ADMIN=1`, the same-run token from `/__token`, and non-production mode. Demo mode blocks client-side writes before the bridge is called. ## Data Flow ### Fresh Clone 1. `src/data/graphs/index.json` contains the committed `ai-os` seed entry. 2. `src/data/graphs/ai-os.json` contains the committed seed graph. 3. `useKnowledgeGraph()` renders seed fallback if live bridge reads are idle, offline, empty, or failed. ### Live Read 1. The route calls `/__graphify_list`. 2. The read bridge loads and normalizes the registry. 3. Missing graph artifacts and missing local source paths are pruned. 4. The route chooses an active project. 5. The route calls `/__graphify_graph?id=`. 6. The graph is parsed in the browser through `parseKnowledgeGraph()`. ### Ingest 1. The browser checks `/__graphify_admin_status`. 2. The browser gets `/__token`. 3. The Add Project form posts `{ path, name? }` to `/__graphify_ingest`. 4. The admin bridge validates loopback, token, admin env, JSON body, path/name, and source type. 5. Git URLs are shallow-cloned to a temp directory; local paths are resolved to a directory. 6. The bridge runs `graphify update ` with argv-only execution. 7. The bridge reads `graphify-out/graph.json`, parses it, rejects oversized or vendored graphs, writes `src/data/graphs/.json`, and upserts the registry. 8. Temp clones or `graphify-out` output are removed in cleanup. 9. The client invalidates the graph list and refreshes. ### Remove 1. The browser sends `DELETE /__graphify_remove?id=`. 2. The bridge validates loopback, token, admin env, id, and registry state. 3. The graph artifact is resolved under `src/data/graphs/`. 4. The artifact is removed and the registry is rewritten. 5. A missing target returns `{ ok: true, removed: false }`. ## Security Model Read endpoints: * GET-only. * Loopback-only. * No-store JSON or stream responses. * Bounded error envelopes. * Path confinement through graph directory resolution and `realpath`. Write endpoints: * Local development only. * Disabled in production even when env is present. * Loopback-only. * Token required for mutations. * `HERMES_DASHBOARD_ADMIN=1` required for mutations. * Bounded JSON request bodies. * Git URL validation rejects unsafe metacharacters and HTTP(S) usernames. * Git and graphify commands use argument arrays, not shell strings. * Command timeouts and max output buffers are set. * Command failure details are redacted and bounded. * Graph artifacts are written atomically where possible. * Graph ids are slug/hash collision-safe. * Remove deletes only confined graph artifacts. The Knowledge Graph port does not add public APIs, hosted ingest, remote dashboard writes, new browser token display, or a new third-party transfer path. ## Hermes Grounding `buildKnowledgeGraphHermesGrounding()` creates a bounded invisible prompt prefix from the active project and graph metadata. The returned grounding: * Names the active project. * Includes graph path, size, language, description, and top connected files. * Tells Hermes to use `graphify query`, `graphify explain`, or `graphify path` when useful. * Tells Hermes not to guess when the graph lacks evidence. * Sends `{ toolsets: "graphify", yolo: true }`. This grounding is passed only by `KnowledgeGraphGroundedChat`. It does not change the Hermes Agent page chat behavior. ## 3D Renderer Notes The renderer is lazy-loaded. Home and route surfaces keep fallback states for loading, unsupported WebGL, empty graphs, and renderer load failure. The home preview renders only when a WebGL context can be created. Otherwise it shows an accessible "3D preview unavailable" status while retaining stats and file summaries. Large graph safety has two layers: * Ingest rejects graphs above 12,000 nodes. * Renderer density controls can show a core subset for browser performance. ## Gotchas ### Relative And Absolute Graph Paths Committed seed data uses workspace-relative paths. The setup script may write absolute paths for external graphify skills. Do not treat this as a browser schema change. The bridge accepts and resolves both, then returns workspace-relative paths to the browser. ### Graphify Is Optional Do not make `graphify` a package dependency or a hard startup requirement. Fresh clones must still render the seed graph. ### Admin Status Is Not Permission To Mutate `/__graphify_admin_status` reports status without a token so the UI can show setup guidance. Mutations still require the same-run token and admin env. ### GitHub URL Ingest Is Local The bridge performs a local shallow `git clone`, runs graphify locally, then deletes the temp clone. It does not call a hosted GitHub API. ### Do Not Document Private Paths In Evidence Validation evidence should record command names, pass/fail status, and counts. Do not paste local graph payloads, absolute source paths, dashboard tokens, OAuth material, screenshots, traces, or generated private data into committed docs. ## Verification Anchors Focused tests: ```bash bun run test -- src/lib/__tests__/knowledge-graph-types.test.ts bun run test -- scripts/lib/__tests__/knowledge-graph-dev-bridge.test.ts bun run test -- scripts/lib/__tests__/knowledge-graph-admin-bridge.test.ts bun run test -- src/hooks/__tests__/use-knowledge-graph.test.tsx bun run test -- src/hooks/__tests__/use-knowledge-graph-admin.test.tsx bun run test -- src/hooks/__tests__/use-knowledge-graph-token.test.tsx bun run test -- src/components/knowledge-graph/__tests__/knowledge-graph-page.test.tsx bun run test -- src/components/knowledge-graph/__tests__/knowledge-graph-ingest-card.test.tsx bun run test -- src/components/knowledge-graph/__tests__/knowledge-graph-grounded-chat.test.tsx bun run test -- src/components/home/__tests__/knowledge-graph-section.test.tsx bun run test -- scripts/lib/__tests__/graphify-shared-brain-scripts.test.ts ``` Release gates: ```bash bun run test bun run typecheck bun run typecheck:scripts bun run lint bun run format:check bun run build bun run budget:check bun run runtime:check-private ``` Manual/browser checks: * `/knowledge-graph` desktop and mobile. * Home Shared Brain section desktop and mobile. * Seed fallback with no live graphs. * Admin disabled state. * Graphify missing state when the binary is unavailable. * Grounded Hermes chat prompt context. * Connect-with-Hermes copy prompt. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/knowledge-graph/knowledge-graph-handover.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.