BB Graph Assistant

A local-first, human-led assistant for exploring captured application behavior, graph relationships, and evidence. It uses Neo4j for the analytical graph, SQLite for capture metadata and durable sync state, and keeps raw exchanges in the encrypted local vault.

Start Neo4j using the private configuration described in deploy/neo4j, then run:

./scripts/bb-assistant neo4j-check
./scripts/bb-assistant neo4j-backfill --project-key <registered-project-sha256>
./scripts/bb-assistant serve

Open http://127.0.0.1:8765/. To run the durable projection worker for selected registered projects, pass each project key explicitly with --project-key <sha256>. Without project keys, serve runs the web UI only. MCP clients launch the separate stdio server with ./scripts/bb-assistant-mcp; both launchers read the same private runtime configuration. The managed server does not start Caido intake or call a model. Runtime data and credentials stay outside this repository.

In the graph inspector, Focus on direct relationships narrows the display to the selected node and its immediate neighbors from the already-loaded graph. All nodes restores that graph slice. Focusing changes only the view; it does not reread Caido or change graph coverage.

Caido history intake and graph coverage are measured independently. Missing captures, incomplete parsing, or absent source snapshot guarantees remain PARTIAL; graph relationships are evidence navigation, not vulnerability verdicts.

To inspect pending projection jobs that may already be materialized in both graph stores, use projection-reconcile. It defaults to a read-only dry run; --apply acknowledges only exact matches after full snapshot parity.

Add URL navigation to previously retained captures using the separate graph-navigation-backfill-preview and graph-navigation-backfill-apply commands. They preserve accepted projection jobs and require an exact candidate digest.

Create and restore bounded, private project archives with project-backup and project-restore. Restore emits a fresh local capability summary; it does not establish Caido-history completeness or Neo4j parity.

See docs/SETUP.md, docs/ARCHITECTURE.md, and docs/PROJECT-STATUS.md for setup, data boundaries, and the current verified coverage. The checked local runtime has served the selected project's operation graph and exact evidence/comparison APIs through Neo4j; Hermes MCP discovery and a model-backed synthetic consultation/resume are also verified. Real capture content remains outside the model boundary pending a separate retention/data-boundary review, and full source/browser/JavaScript coverage is still partial.

go test ./...
go vet ./...

This project accepts vulnerability reports through GitHub's private vulnerability reporting on this repository (the Security tab). SECURITY.md describes what to include in a report and what must not be attached; please do not open a public issue for a suspected vulnerability.

CONTRIBUTING.md covers the development setup and review expectations, and CODE_OF_CONDUCT.md applies to every project space. The project is released under the MIT license — see LICENSE.