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
Model the Personal Knowledge Graph
Represent people, projects, claims, sources, and time with relationships precise enough to reason over.
By the end
You can design a minimal graph schema with stable identity, typed edges, claim nodes, source links, user scope, and temporal validity.
Model the things inside documents
Documents remain evidence, but the graph should represent the things you reason about: people, organizations, projects, decisions, tools, events, goals, and claims. A source can mention many entities; one entity can appear across many sources. Separating the two lets the engine follow meaning without losing the original record.
Make claims first-class objects
A sentence such as Project Atlas launches in September is not an eternal property of the project. It is a claim asserted by a source, observed at a time, with confidence and possible conflicts. Modeling claims explicitly lets the engine show disagreement, track supersession, and answer what was believed when.
- Subject, predicate, and object or value.
- Source and precise evidence location.
- Observed time and validity interval.
- Confidence, review state, and author.
- Contradicts, supports, or supersedes relationships.
Give relationships verbs
An untyped related-to edge says almost nothing. Define a small vocabulary such as works-on, decided-by, depends-on, sourced-from, supports, contradicts, and supersedes. Each edge needs direction, scope, evidence, and optional time. Begin small; edge types are a public language your retrieval and UI must explain consistently.
Resolve identity without dangerous guessing
Names change, aliases collide, and a person can share a name with someone else. Give entities stable internal IDs and preserve human-readable names as attributes. Auto-link only high-confidence matches with distinctive evidence. Ambiguous matches become review proposals rather than silent merges.
Put user scope and time in the model
Per-user scope cannot be an afterthought. Every private node, claim, source, and edge needs an owning user or shared workspace. Time also belongs in the model: when evidence was captured, when a fact was valid, when the system learned it, and when it should be reviewed. Without both, retrieval can leak information and revive outdated truth.
Working reference
Commands and patterns
Inspect the schema that is actually active
gbrain schema active gbrain schema list gbrain schema show
Do not assume a default from an older guide. These commands show the active pack, available packs, and the current schema contract in the installed version.
Select and validate a first-party schema pack
gbrain schema use gbrain-recommended gbrain schema validate gbrain-recommended
Activates the named pack, then validates that exact manifest explicitly before more ingestion. A bare validate invocation is ambiguous in a teaching guide; always name the pack you intend to check.
Detect drift and review schema candidates
gbrain schema detect gbrain schema suggest gbrain schema review-candidates
Separates observed content patterns from schema changes. Review candidates first; apply only a bounded path with gbrain schema review-candidates --apply Projects/ after inspecting the proposal.
Create a custom schema pack safely
gbrain schema init my-pack gbrain schema validate my-pack gbrain schema use my-pack
Scaffolds a named pack, validates it, and activates it only after the contract passes.
When the happy path breaks
Failure modes
Symptom
The graph is a hairball of generic related-to edges.
Likely cause
Connections were created from co-occurrence with no semantic contract.
Recovery
Limit edge types, require evidence and direction, and remove relationships that cannot improve a real question.
Symptom
A person and company with similar names are merged.
Likely cause
Name similarity was treated as identity.
Recovery
Use stable IDs, entity type, distinguishing attributes, aliases, and a human review path for ambiguity.
Symptom
The engine states an old project plan as current fact.
Likely cause
Claims have no validity interval or supersession relationship.
Recovery
Model claims and time explicitly, then prefer active claims while preserving historical ones.
Hands-on lab
Build a twenty-node graph by hand
Model one real project deeply enough to answer relationship and time questions.
- 01Select one project with at least three people, three decisions, three sources, and two changing claims.
- 02Assign stable IDs and types to twenty nodes.
- 03Define no more than eight edge types with direction and examples.
- 04Attach every claim and edge to evidence.
- 05Mark one claim superseded and one identity match uncertain.
- 06Answer who decided what, based on which source, and what changed over time by traversing the graph.
Deliverable: A graph fixture in JSON, CSV, or Markdown plus three hand-verified traversal answers.
Reusable artifact
Minimal graph schema
A compact schema that preserves identity, evidence, scope, and time.
Node: id, type, name, aliases, userId, workspaceId, createdAt Source: id, origin, capturedAt, accessClass, checksum Claim: id, subjectId, predicate, object, sourceId, evidenceSpan Claim time: observedAt, validFrom, validTo, reviewAfter Claim state: proposed | accepted | disputed | superseded Edge: id, fromId, type, toId, sourceId, confidence, validFrom, validTo Identity proposal: candidateIds, evidenceFor, evidenceAgainst, status
Before you move on
Receipt checklist
- Twenty-node fixture with stable IDs.
- Edge dictionary with direction and meaning.
- Evidence link for every accepted claim and edge.
- Three traversal answers verified against sources.
Primary sources
