Hiro development journal

Plan for governed GBrain integration in Hiro

2026.07.22 at 09:58:16 America/Los_Angeles Published Machine-readable JSON

Executive summary

A two-phase implementation plan was designed for user review; no Hiro code, database, service, dependency, configuration, memory, or evaluation data was changed.

The plan keeps Hiro's local SQLite database authoritative for preferences, tasks, reading status, approvals, calendar references, and action audit, while a local GBrain instance stores and retrieves durable world knowledge about people, organizations, projects, meeting notes, documents, and reading material.

GBrain would first run locally with PGLite, keyword and graph retrieval, no remote endpoint, no personal-data import, no autonomous dream cycle, and no external embedding or synthesis provider. A feature-flagged shadow adapter would be promoted to active reads only after held-out safety, provenance, freshness, deletion, fallback, and retrieval evaluations pass.

Work completed

Phase 1: typed operational system of record

Planned; awaiting approval

Add additive, versioned SQLite migrations for typed claims, tasks, reading items, approval records, append-only action events, source references, and an idempotent GBrain projection outbox.
Preserve the current facts table and memory Markdown behavior through a compatibility layer; migration is additive and rollback is feature-flag based.
Enforce source precedence, confidence, validity windows, supersession, content hashes, tombstones, owner scope, and immutable approval and action history.
Project only suitable world-knowledge records to GBrain. Task completion, calendar truth, approval state, and authorization never come from GBrain.

Phase 2: local GBrain recall adapter

Planned; awaiting approval

Pin and verify an upstream GBrain release in a disposable local PGLite brain before any user-data path is enabled.
Use one long-lived local-only MCP process so PGLite access is serialized; the Windows launcher must normalize the Path/PATH collision and pass a real child-process startup test.
Introduce disabled, shadow, and active-read modes behind configuration. Shadow mode records structured retrieval evidence without injecting GBrain results into Hiro responses.
Route preferences and operational rules to SQLite, current calendar and external facts to authoritative tools, and person, organization, project, meeting-note, document, and reading-content questions to GBrain.
Return bounded structured recall with page slug, source, timestamp, freshness, trust, and retrieval reason. Memory never grants permission for an external action.

Evaluation and promotion gates

Designed

Start with synthetic records only and compare the current SQLite baseline with GBrain shadow recall on held-out stateful cases.
Test contradiction and supersession, stale information, irrelevant distractors, source citation, deletion, owner isolation, malicious instructions stored in memory, GBrain outage fallback, task and reading-list deduplication, and preserved approval boundaries.
Require zero unauthorized actions, zero cross-owner disclosure, complete deletion and tombstone behavior, at least 95 percent provenance completeness, no material regression to existing fact recall, and a measurable relationship-recall gain before active-read promotion.
Any later use of hosted embeddings, synthesis models, remote MCP, automatic consolidation, dream cycles, or personal-data imports requires a separate approval and budget/privacy review.

Decisions and reasoning

Use GBrain as a governed world-knowledge layer, not as Hiro's authorization store or universal database.
Choose local PGLite for the pilot. Do not expose an HTTP endpoint or use hosted GBrain during the initial phase.
Run keyword and graph retrieval first. Do not add API keys or external LLM and embedding spend to Hiro's existing budget without a later explicit decision.
Do not import the existing memory Markdown file wholesale because it mixes operational preferences with other facts; classify and migrate only through an explicit reviewed mapping.
Do not enable GBrain's autonomous signal detector, integrations, autopilot, or dream cycle in the first two phases.
Keep the current SQLite and Markdown paths functional so one feature flag can remove GBrain from the response path without data loss.

Validation and evidence

Check	Status	Result
Current Hiro memory architecture inspection	completed	Hiro currently stores conversations and learned facts in SQLite, manually curated context in Markdown, and injects broad trimmed memory into the prompt. The facts model overwrites by category and key and lacks explicit supersession, deletion, validity, and provenance records.
Current GBrain documentation review	completed	Current upstream documentation supports local PGLite, MCP, keyword fallback without embedding credentials, typed links, timelines, versions, schema packs, and local or remote topologies. It also explicitly separates world knowledge from operational agent memory.
Hiro runtime implementation	not-run-by-design	The user requested plan review before implementation. No package was installed, no GBrain process was launched, no schema changed, and no user memory was read or imported.
Journal tests and site build	passed	The required npm run test:hiro check passed, and the production npm run build generated and validated all journal pages before publication.

Current state

The plan is ready for user decision; implementation has not started.
The recommended pilot requires no hosted database and no external memory endpoint.
The main architectural boundary is explicit: SQLite and authoritative external providers determine operational truth; GBrain supplies inspectable context and relationships.

Next steps

Obtain user approval of the two-phase architecture and the local, no-external-provider pilot constraints.
After approval, implement the additive schema and repository interfaces with tests before installing or connecting GBrain.
Create a disposable synthetic GBrain fixture and validate Windows startup, shutdown, health, backup, and fallback behavior.
Add shadow retrieval, run the held-out evaluation matrix, and return a measured promotion proposal before enabling active recall or importing personal data.