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
From Chatbot to Answer Engine
Understand the product shape: answer, proof, gaps, freshness, and a next verification step.
By the end
You can explain why a knowledge engine is different from chat history, search, a vector database, or a generic chatbot.
Start with the output contract
A trustworthy knowledge engine does not merely respond. It returns an answer, the evidence supporting it, important gaps, the age of that evidence, and the next step when confidence is limited. This product shape, emphasized in GBrain, makes uncertainty useful rather than embarrassing. It also gives engineers a concrete interface to build and test.
- Answer: the best supported conclusion for the requested scope.
- Proof: sources and specific evidence behind each material claim.
- Gaps: missing, weak, contradictory, or inaccessible evidence.
- Freshness: when relevant sources were created, observed, or reviewed.
- Next step: the smallest action that would reduce uncertainty.
A transcript remembers events; an answer engine models knowledge
Chat logs preserve who said what and when, but they do not automatically resolve identity, update an outdated belief, or connect a decision to its evidence. A knowledge engine treats chats as sources. It extracts proposed claims and relationships into an inspectable model while retaining the transcript for provenance.
Similarity is useful, but it is not truth
A vector database can find text that resembles a question. It cannot by itself determine whether a source is current, whether two names refer to the same person, whether one decision superseded another, or whether an answer lacks evidence. GBrain's stronger idea is the synthesis layer above storage: retrieval, graph context, source evaluation, gaps, and a response contract.
Separate evidence, knowledge, and operation
Use three planes. The evidence plane preserves sources and derivations. The knowledge plane stores entities, claims, and relationships. The operation plane handles ingestion, retrieval, synthesis, consolidation, permissions, and receipts. Separating them prevents a background job from silently turning a model guess into canonical truth.
Design an excellent unknown response
Unknown is a valid result, not an exception. The system should say which sources it searched, why they were insufficient, what related evidence exists, and what would resolve the question. An honest unknown builds more trust than a fluent guess and turns missing knowledge into a concrete research queue.
Working reference
Commands and patterns
Install GBrain and create a local brain
bun install -g github:garrytan/gbrain gbrain init --pglite
Installs the first-party CLI and initializes its local PGlite-backed mode. Run it from the directory where you want GBrain's local configuration and knowledge roots.
Verify the installation
gbrain doctor gbrain doctor --json
The human-readable run explains repairs; the JSON form is suitable for a saved setup receipt or automated check.
When the happy path breaks
Failure modes
Symptom
The product is described as a second brain but only offers chat over embeddings.
Likely cause
Storage technology was confused with the complete answer workflow.
Recovery
Define the answer contract, graph responsibilities, gap types, and operational receipts before adding more retrieval infrastructure.
Symptom
Every response sounds equally confident.
Likely cause
The UI exposes model prose but hides source coverage and retrieval conditions.
Recovery
Derive confidence from evidence, freshness, conflict, scope, and retrieval path, then display the reasons.
Symptom
No-result queries become plausible general-knowledge answers.
Likely cause
The model was allowed to fill corpus gaps invisibly.
Recovery
Constrain grounded mode to supplied evidence and label any outside knowledge as a separate, optional lane.
Hands-on lab
Design the answer before the engine
Create output examples that force the system to be useful when evidence is strong, weak, conflicting, or absent.
- 01Choose one real domain such as a project, research topic, customer, or personal plan.
- 02Write four questions: strongly answerable, weakly answerable, contradictory, and unknown.
- 03Manually create the ideal answer, proof, gaps, freshness, and next-step result for each.
- 04Underline every sentence that requires evidence and attach a source ID.
- 05Turn the four examples into acceptance tests for later chapters.
Deliverable: Four golden answer records covering the system's major trust states.
Reusable artifact
Knowledge answer contract
The stable public shape every retrieval and synthesis path must produce.
question:
scope: { user, project, timeWindow }
answer:
claims: [{ text, citationIds, confidence }]
citations: [{ id, sourceId, location, observedAt }]
gaps: [{ type, severity, explanation }]
freshness: { checkedAt, newestEvidenceAt, staleEvidenceIds }
conflicts: [{ claimIds, explanation }]
nextVerificationStep:
operationReceiptId:Before you move on
Receipt checklist
- Four golden questions and hand-authored expected results.
- Claim-to-evidence map for each answer.
- An unknown result that provides a useful next step.
- A written boundary explaining what the product does not claim to know.
Primary sources
