Contents
- 01From Chatbot to Answer Engine
- 02Model the Personal Knowledge Graph
- 03Engineer Trust, Provenance, and Uncertainty
- 04Build a Self-Wiring Ingestion Flow
- 05Retrieve, Traverse, and Synthesize
- 06Build the Dream and Consolidation Cycle
- 07Secure and Operate a Multi-User Brain
- 08Evaluate Trust and Ship the Product
Secure and Operate a Multi-User Brain
Enforce isolation, least privilege, local-first options, observability, and recovery before inviting real users.
By the end
You can design storage and access boundaries, protect sensitive evidence, instrument every answer path, and recover from operational failures.
Choose the local and cloud boundary deliberately
gbrain init --pglite provides a local database path, and gbrain serve exposes the local stdio MCP server used by coding agents. A hosted deployment can expose HTTP with gbrain serve --http and scope access through OAuth 2.1 clients registered by gbrain auth register-client. Legacy bearer tokens are long-lived and full-access at this pinned version; do not present them as scoped credentials. Decide which layer is canonical, what may leave the device, how conflicts resolve, and how users revoke access. Local-first is a custody promise, not merely a database choice.
Enforce user and workspace isolation in storage
Attach user and workspace ownership to sources, nodes, claims, edges, embeddings, and receipts. Enforce policy in the database and service, not only in application prompts. Retrieval queries must carry authenticated scope before any candidate search. Test one user attempting to address another user's IDs directly.
Control model exposure and retention
Classify sources by sensitivity and provider eligibility. Some material may remain local; some may be redacted; some may use an approved enterprise endpoint; some should never enter an LLM prompt. Log which source IDs were sent to which provider without copying sensitive content into general logs. Make deletion propagate through derived claims and indexes.
Trace every answer from request to evidence
Record request scope, retrieval plan, candidate counts, graph limits, selected evidence, model and prompt versions, validation outcomes, latency, cost, fallback, approvals, and receipt ID. Avoid logging raw secrets or private content by default. A trace should answer why this result happened without becoming a second ungoverned data store.
Define degraded modes and recovery objectives
Plan for unavailable embeddings, failed graph writes, stale indexes, model timeouts, partial consolidation, and corrupted local state. Define what still works, what the UI reports, how long recovery may take, and which operations stop. Test backup restore and index rebuild before calling the system dependable.
Working reference
Commands and patterns
Connect Claude Code and Codex to local GBrain
claude mcp add gbrain -- gbrain serve codex mcp add gbrain -- gbrain serve
Registers the same local stdio server in both clients. capture remains a CLI command; agents write durable pages through GBrain's MCP tools such as put_page.
Start the OAuth HTTP server in its own host terminal
gbrain serve --http --port 3131 --bind 127.0.0.1 --public-url https://brain.example.com
Keep this foreground process in its own terminal and terminate TLS through a trusted reverse proxy or tunnel. --public-url must match the issuer clients reach; do not expose the admin surface without transport security and network controls.
Register a least-privilege OAuth client on the host
gbrain auth register-client coding-agent --grant-types client_credentials --scopes 'read write' --source personal --federated-read personal,shared
Run this in a second host terminal after replacing source IDs with real sources. The OAuth client gets read/write operations only, writes only to its --source, and reads only the listed federation. The client secret is revealed once: move it directly into an OS secret manager, never a note, repository, command argument, or shell history.
Initialize a thin client without secret-bearing arguments
read -r GBRAIN_REMOTE_CLIENT_ID read -rs GBRAIN_REMOTE_CLIENT_SECRET export GBRAIN_REMOTE_CLIENT_ID GBRAIN_REMOTE_CLIENT_SECRET gbrain init --mcp-only --issuer-url https://brain.example.com --mcp-url https://brain.example.com/mcp
Paste the client ID and one-time secret only into the silent prompts or load the same expected environment variables from your OS secret manager. gbrain init reads them from the environment, so neither credential appears in process arguments or shell history. Revoke with gbrain auth revoke-client <client_id> on the host and then unset both variables.
Diagnose the runtime and model layer
gbrain doctor --json gbrain models gbrain models doctor
Separates storage and configuration health from model-provider health before debugging retrieval or synthesis.
When the happy path breaks
Failure modes
Symptom
Cross-user semantic matches appear before the application filters them.
Likely cause
Ownership filtering occurs after vector retrieval.
Recovery
Include authenticated scope inside the storage query and test direct identifier attacks.
Symptom
Private evidence is copied into ordinary application logs.
Likely cause
Debug logging serializes entire retrieval packets.
Recovery
Log stable IDs, counts, hashes, and decisions by default; gate redacted content inspection explicitly.
Symptom
An embedding outage makes the brain appear completely offline.
Likely cause
The product has no declared degraded mode.
Recovery
Provide scoped lexical and direct graph lookup, report fallback, lower confidence, and stop only operations that require unavailable services.
Hands-on lab
Pass a two-user isolation and recovery drill
Prove that one user's knowledge cannot leak and that a provider outage does not erase core utility.
- 01Seed two users with similarly worded private sources and overlapping entity names.
- 02Register one source-scoped OAuth client per user and give each only the read, write, source, and federated-read access it needs.
- 03Run direct-ID, semantic, graph-neighbor, and export attacks across users.
- 04Disable embeddings and the synthesis provider separately.
- 05Verify visible fallback, source isolation, and honest confidence changes.
- 06Restore a clean instance from canonical data and rebuild derived indexes.
Deliverable: A security and recovery report with denied attacks, degraded-mode answers, and restore evidence.
Reusable artifact
Knowledge-engine threat and recovery sheet
A compact operating reference for custody, isolation, degradation, and incidents.
Canonical storage and local/cloud boundary User, workspace, and sharing model Sensitive data classes and allowed providers Retrieval and graph isolation controls Secrets and encryption ownership Logging and trace redaction rules Expected degraded modes Backup, index rebuild, RPO, and RTO Deletion and export procedure Incident owners and stop conditions
Before you move on
Receipt checklist
- Data-flow and trust-boundary map.
- Passing cross-user attack suite.
- Provider-disabled fallback results.
- Redacted trace proving answer lineage.
- Clean restore and index rebuild.
Primary sources
