Use cases by industry

Use case: personal knowledge vault

Every household forgets the things it can least afford to: which account is paying for the remodel, when the dishwasher warranty lapses, which pediatrician manages the asthma, what the emergency fund actually holds this month. A wrong warranty date, medication, or balance isn't a bad search result — it's a decision made on a fact that was never true. This guide builds a household assistant that recalls those facts with a citation and abstains rather than guess, touching seven module slices: Intake to capture the notes, Atlas to turn wikilinks into a typed graph, Warrant to certify what the family will act on, Conduit to ground live money questions, Lens to answer with citations, Lineage to trace any answer to its note, and Crucible & Ports to lock recall in and hand it to the family.

One vault, seven slices. The dashed edge is the loop that keeps it honest: a question the golden set catches getting worse steers the next round of curation.

Seed this workspace and follow along

Everything below runs against a real, offline, deterministic workspace. Seed it with yarn demo:seed personal and it appears as The Lindqvist Household Vault— a family's people, money, home, health, and travel, densely wikilinked, with the lindqvist-finance connector and the household-assistant agent already wired. See Demo workspaces for the full catalogue.

Prerequisites

A workspace key with kb:write, kb:read, data:read, data:run, agents:run, and runs:read, exported as $ELI_KEY. See Getting started.
Owner/admin on the workspace, to certify concepts and verify notes.
An enabled chat model, so /query can generate — otherwise 409 no-model-configured.

1 · Intake — capture the vault

The household's knowledge is already written down — it's just scattered across a dozen Markdown notes: the family roster, the accounts list, the appliance warranties, the medical summary, the trip plan. Post them as documents and each commits as a chunked, FTS-searchable document before embedding and graph enrichment continue independently. Here is the home-systems note that the rest of this guide hangs on:

POST/api/v1/documentsBearer · kb:write

Save markdown through the vault. The file, chunks, and full-text index commit before 201; embedding and graph enrichment continue as detached work, so the response contains stored-document metadata only.

Example requestbash

curl -s -X POST https://your-host/api/v1/documents \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "home/appliances.md",
    "title": "Home Systems & Appliances",
    "content": "# Home Systems & Appliances\n\nWarranties and maintenance for the [[Lindqvist Household]]. Utility usage shows up under [[Utilities]] in the [[Household Budget]].\n\n- [[Carrier HVAC System]] — installed 2022, 10-year parts warranty. Filter replaced every 3 months (last change May 2026).\n- [[Bosch Dishwasher]] — new in the [[Kitchen Renovation]]; 2-year manufacturer warranty expiring 2026-09-01."
  }'

Responsejson

{ "docId": "01KY10AAAAAAAAAAAAAAAAAAAA", "path": "home/appliances.md", "contentHash": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824", "title": "Home Systems & Appliances" }

The response has no entity count or processing status. Detached enrichment can later resolve references such as [[Bosch Dishwasher]], [[Carrier HVAC System]], [[Household Budget]] — into graph nodes and edges. Atlas builds the household's concept graph after the storage boundary. Do the same for the family roster, the accounts, the care team, and the trip; query the graph only after that enrichment has completed.

2 · Atlas — wikilinks become a graph

The vault's ontology types six kinds of thing a household tracks — Person, FinancialAccount, Project, Appliance, HealthRecord, and Trip — connected by four relations: owns, manages, treats, and funds. So retrieval isn't bag-of-words; it's structured. List the entities highest-PageRank first to see what the ingest produced:

GET/api/v1/entitiesBearer · kb:read

List canonical entities highest-PageRank first. The dense wikilinking makes the hub nodes — the people and the money — rise to the top automatically.

Example requestbash

curl -s "https://your-host/api/v1/entities?limit=6" \
  -H "Authorization: Bearer $ELI_KEY"

Responsejson

{
  "entities": [
    { "id": "01KZMARALINDQVIST00000000", "name": "Mara Lindqvist", "type": "Person", "pagerank": 0.061 },
    { "id": "01KZEMERGENCYFUND00000000", "name": "Emergency Fund", "type": "FinancialAccount", "pagerank": 0.044 },
    { "id": "01KZKITCHENRENO0000000000", "name": "Kitchen Renovation", "type": "Project", "pagerank": 0.041 },
    { "id": "01KZBOSCHDISH000000000000", "name": "Bosch Dishwasher", "type": "Appliance", "pagerank": 0.033 },
    { "id": "01KZPEANUTALLERGY00000000", "name": "Peanut Allergy", "type": "HealthRecord", "pagerank": 0.029 },
    { "id": "01KZJAPAN20260000000000AA", "name": "Japan 2026", "type": "Trip", "pagerank": 0.026 }
  ],
  "total": 38
}

Pick a hub and expand its neighborhood to read the household as a graph. Mara Lindqvist is the primary account holder, so her frontier fans out across money and projects:

GET/api/v1/entities/{id}/neighborhoodBearer · kb:read

Expand the canonical relations around one entity, both directions. This is the typed edge set — owns / manages / treats / funds — that grounds structured retrieval.

Example requestbash

curl -s "https://your-host/api/v1/entities/01KZMARALINDQVIST00000000/neighborhood?depth=1" \
  -H "Authorization: Bearer $ELI_KEY"

Responsejson

{
  "entity": { "id": "01KZMARALINDQVIST00000000", "name": "Mara Lindqvist", "type": "Person" },
  "edges": [
    { "rel": "owns",    "dst": { "name": "Everyday Checking", "type": "FinancialAccount" } },
    { "rel": "owns",    "dst": { "name": "Emergency Fund",    "type": "FinancialAccount" } },
    { "rel": "manages", "dst": { "name": "Household Budget",  "type": "Project" } },
    { "rel": "manages", "dst": { "name": "Kitchen Renovation","type": "Project" } }
  ]
}

The graph is free

Nothing above needed a model. Because the notes are written in [[wikilink]] style, the entire typed graph — 38 entities across six types, joined by four relations — is derived deterministically at ingest. Curate it by hand in Manage entities when you want to merge duplicates or add a relation the notes didn't spell out.

3 · Warrant — certify what the family will act on

Extraction gives you concepts at authority machine_extracted — good enough to retrieve, not good enough to bet on. A household fact the family will act on — a warranty deadline, a balance, a medication — has to be vouched for. In Warrant, pin the canonical definition as a reviewable change and then certify it. Take the Bosch Dishwasher and lock its warranty date:

POST/api/v1/change-requestsBearer · kb:write

Propose the canonical definition as a reviewable change rather than editing silently. Approval promotes authority to at least curated and records the reviewer on the revision.

Example requestbash

curl -s -X POST https://your-host/api/v1/change-requests \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "update",
    "entityId": "01KZBOSCHDISH000000000000",
    "payload": { "description": "Bosch Dishwasher — installed in the Kitchen Renovation; 2-year manufacturer warranty expiring 2026-09-01." },
    "note": "Pinning the warranty date before it lapses"
  }'

Responsejson

{ "id": "01KZCR00000000000000000AA", "entityId": "01KZBOSCHDISH000000000000", "kind": "update", "status": "open" }

POST/api/v1/entities/{id}/certifyBearer · kb:write

Owner/admin sign-off — authority certified. Also starts the review clock: nextReviewAt lands at now + the workspace's reviewIntervalDays, so a certified household fact can't quietly go stale.

Example requestbash

curl -s -X POST https://your-host/api/v1/entities/01KZBOSCHDISH000000000000/certify \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "Verified against the manufacturer receipt"}'

Responsejson

{ "authority": "certified", "lifecycleStatus": "published", "version": 2, "nextReviewAt": "2027-01-19T09:10:00.000Z" }

Then verify the note the concept came from, so its provenance carries a governance tier the whole platform can read:

POST/api/v1/documents/{id}/verifyBearer · kb:write

Glean-style document verification. Stamps the verification tier, the verifier, and the next re-verify date — the governance block Lineage reports and the manifest counts.

Example requestbash

curl -s -X POST https://your-host/api/v1/documents/01KY10AAAAAAAAAAAAAAAAAAAA/verify \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"verification":"certified","note":"Warranty dates checked against receipts"}'

Responsejson

{ "id": "01KY10AAAAAAAAAAAAAAAAAAAA", "verification": "certified", "verifiedAt": "2026-07-22T09:12:00.000Z", "nextVerifyAt": "2026-12-29T00:00:00.000Z" }

Certification changes how the policy answers

Governance isn't decoration — it feeds the answer policy. Once Emergency Fund is certified and its accounts note verified, the seeded decision for "What's the balance of our emergency fund?" is answer at confidence 0.82 (confidence_above_answer_floor) — stated plainly. The same treatment applies to the household's one non-negotiable: Peanut Allergy. Curate any of it as a click in the Curation page — the API and the UI write the same append-only revisions.

4 · Conduit — connect the money

Notes describe the household's money; the bank knows what it holds right now. The pack ships a read-only connector, lindqvist-finance (a Postgres household_finance database of accounts, transactions, and budgets), with three governed named queries authored against it. List the surface — you get slugs, titles, and parameter specs, never credentials:

GET/api/v1/data/queriesBearer · data:read

List the named queries (domain components) you can run, with their parameter specs. Secrets and connection configs are never returned.

Example requestbash

curl -s https://your-host/api/v1/data/queries \
  -H "Authorization: Bearer $ELI_KEY"

Responsejson

{
  "queries": [
    { "slug": "account-balances",     "title": "Account balances",           "connectorName": "lindqvist-finance", "params": [] },
    { "slug": "spending-in-category", "title": "Monthly spend in a category", "connectorName": "lindqvist-finance", "params": [ { "name": "category", "type": "string", "required": true, "description": "Budget category, e.g. Groceries" } ] },
    { "slug": "budget-vs-actual",     "title": "Budget vs actual for a month","connectorName": "lindqvist-finance", "params": [ { "name": "month", "type": "string", "required": true, "description": "Budget month, e.g. 2026-06" } ] }
  ]
}

Now answer the household's most-asked money question — what did we spend on groceries this month? — by running spending-in-category by its slug. Params are bound, never interpolated; the read is capped and timed, and every run writes a data_calls provenance row:

POST/api/v1/data/queries/{slug}/runBearer · data:run

Execute the named query with validated params. Read-only, row-capped at the connector's maxRows (200), and provenance-logged with a dataCallId you can trace.

Example requestbash

curl -s -X POST https://your-host/api/v1/data/queries/spending-in-category/run \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{"category":"Groceries"}}'

Responsejson

{
  "dataCallId": "01KY10CCCCCCCCCCCCCCCCCCCC",
  "connectorName": "lindqvist-finance",
  "queryTitle": "Monthly spend in a category",
  "columns": ["txn_month", "spent_usd"],
  "rows": [
    { "txn_month": "2026-07", "spent_usd": 812.44 },
    { "txn_month": "2026-06", "spent_usd": 901.10 }
  ],
  "rowCount": 2,
  "truncated": false,
  "durationMs": 37
}

Authoring the connector is a UI job — running it isn't

The lindqvist-finance connector, its read-only credential, and these three queries are created in the workspace Data page (and seeded for you by yarn demo:seed personal). The API only consumes that governed surface — it lists and runs by slug, it never writes SQL. Each query is also bound to an entity, so account-balances hangs off Household Finance Tracker, spending-in-category off Groceries, and budget-vs-actual off Household Budget. See Query live data for the whole surface.

5 · Lens — ask, and get a cited answer

Now the payoff. Someone in the family asks in plain language; Lens retrieves, grounds, and returns an answer with inline [Sn] citations, an atomic claims breakdown, and a policy decision that says how much to trust it. Ask the warranty question — a certain fact, but a time-sensitive yes/no:

POST/api/v1/queryBearer · agents:run

Run the grounded query pipeline: retrieval + entity detection + one generation + a groundedness check + the answer-policy engine. Returns a cited answer with a policy decision. The workspace comes from the key.

Example requestbash

curl -s -X POST https://your-host/api/v1/query \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Is the dishwasher still under warranty?"}'

Responsejson

{
  "answer": "Yes, but not for long: the Bosch Dishwasher's 2-year manufacturer warranty runs out 2026-09-01 — about 40 days away [S1]. Confirm the purchase date on the receipt before you rely on it.",
  "claims": [
    { "text": "The Bosch Dishwasher's manufacturer warranty expires 2026-09-01", "citations": ["S1"] },
    { "text": "That is roughly 40 days from today", "citations": ["S1"] }
  ],
  "sources": [
    { "id": "S1", "docId": "01KY10AAAAAAAAAAAAAAAAAAAA", "docTitle": "Home Systems & Appliances", "docPath": "home/appliances.md", "chunkId": "01KY10BBBBBBBBBBBBBBBBBBBB" }
  ],
  "entities": [ { "id": "01KZBOSCHDISH000000000000", "name": "Bosch Dishwasher", "type": "Appliance", "authority": "certified" } ],
  "policy": { "decision": "answer_with_caveat", "confidence": 0.47, "reason": "confidence_in_caveat_band" },
  "groundedness": { "verified": 2, "total": 2 },
  "model": { "chat": "claude-sonnet-4-5", "judge": "claude-haiku-4-5" }
}

The policy block is the trust signal, and it has range. Here it returns answer_with_caveat at 0.47: the warranty date is certain, but "still under warranty?" is a borderline yes/no in time, so the policy hedges instead of stating it flat. Ask something the vault backs cleanly — "Which doctor treats Nils's asthma?" — and you get a plain answer at 0.76 (confidence_above_answer_floor), citing the people/care-team.md note that names Dr. Rajesh Patel. Ask something the vault can't back — "Should we refinance the mortgage this year?" — and the policy engine returns abstain_with_pointers at 0.14 (no_relevant_chunks), pointing at a financial advisor rather than inventing a recommendation the family would act on. That's the whole ethos of a personal vault: cite the note, or say you don't know.

6 · Lineage — trace it back to the note

A month later someone edits the appliances note and wonders what they just changed. The warranty answer cited S1 → docId 01KY10…. Pull that document's lineage and read the whole trail in one call — origin, governance, and the downstream answers it's grounding right now:

GET/api/v1/documents/{id}/lineageBearer · kb:read or runs:read

The unified per-document lineage trail: origin provenance, governance, the audit trail, derived knowledge, and downstream impact. This is how you prove an answer's pedigree end to end.

Example requestbash

curl -s https://your-host/api/v1/documents/01KY10AAAAAAAAAAAAAAAAAAAA/lineage \
  -H "Authorization: Bearer $ELI_KEY" | jq '{origin: .origin, verification: .governance.verification, citedBy: .downstream.citedByAnswers}'

Responsejson

{
  "origin": {
    "kind": "upload",
    "sourceType": "markdown_upload",
    "externalId": "home/appliances.md",
    "lastSyncedAt": "2026-07-22T09:22:41.008Z"
  },
  "verification": "certified",
  "citedBy": 3
}

There it is, closed loop: the answer traces to the note you posted in step 1 (home/appliances.md), that note is certified, and it is currently grounding 3 answers — so an edit to it has a known blast radius. Nobody had to trust the model; they read the pedigree. The full trail also lists the derived concepts (Bosch Dishwasher, Carrier HVAC System) and the dependent cache entries that would invalidate if the warranty note changed.

Same trail, three surfaces

The workspace UI renders this exact DocumentLineage as a visual trail on the document page (via the BFF at GET /api/w/{workspaceId}/documents/{docId}/lineage), and the household assistant can pull it mid-run with the kb_document_lineage MCP tool. One shape, three surfaces.

7 · Crucible & Ports — lock recall in, hand it to the family

Household facts drift — a filter gets changed, a warranty lapses, a doctor moves practices. Capture the questions the family actually asks as a golden set so Crucible can prove recall still holds after every edit. The Household recall baseline set includes "When is the Carrier HVAC filter due for replacement?" — anchor a provenance qrel to the appliances chunk that should ground it:

POST/api/v1/qrelsBearer · kb:write

Author a graded relevance judgment for a golden item. source=provenance derives the highest-grade judgment from the item's anchored citation — deterministic, no judge model needed.

Example requestbash

curl -s -X POST https://your-host/api/v1/qrels \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queryId": "01KZGOLDENHVAC00000000000",
    "chunkId": "01KY10BBBBBBBBBBBBBBBBBBBB",
    "docId": "01KY10AAAAAAAAAAAAAAAAAAAA",
    "grade": 3,
    "source": "provenance"
  }'

Responsejson

{ "id": "01KZQREL0000000000000000A", "queryId": "01KZGOLDENHVAC00000000000", "grade": 3, "source": "provenance" }

Run the set and read the metrics. When a number drops after an edit, the golden set names exactly which question regressed — and promoting that miss back in turns it into a permanent test. That is the dashed loop in the diagram: Crucible's regressions steer the next round of Warrant curation.

GET/api/v1/evals/runs/{id}/metricsBearer · kb:read or runs:read

Retrieval, RAGAS, and abstention metrics for one run — overall and by facet. The ruler for 'did recall get worse?'

Example requestbash

curl -s https://your-host/api/v1/evals/runs/01KZRUNHOUSEHOLD000000000/metrics \
  -H "Authorization: Bearer $ELI_KEY"

Responsejson

{
  "runId": "01KZRUNHOUSEHOLD000000000",
  "config": "Household recall baseline",
  "n": 12,
  "retrieval": { "recallAtK": 0.83, "ndcgAt10": 0.79, "mrr": 0.88, "hitAtK": 1.0 },
  "ragas": { "faithfulness": 0.94, "responseRelevancy": 0.86, "contextPrecision": 0.71 },
  "abstention": { "truthfulness": 0.79, "abstainRate": 0.17, "aurc": 0.061 }
}

Finally, put it in the family's hands. The pack ships the household-assistant agent — grounded, memory-enabled, and instructed to cite the note for every claim and abstain rather than guess a warranty date, medication, or balance. Start a durable run over the same golden question:

POST/api/v1/agents/{slug}/runsBearer · agents:run

Start a durable run of the Household Assistant. Returns immediately with a runId and a stream URL; the loop runs on the worker with retrieval, memory, and the groundedness check enabled.

Example requestbash

curl -s -X POST https://your-host/api/v1/agents/household-assistant/runs \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"When is the Carrier HVAC filter due for replacement?"}'

Responsejson

{ "runId": "01KZRUNHH00000000000000AA", "status": "queued", "stream": "/api/v1/runs/01KZRUNHH00000000000000AA/stream" }

The seeded run trace shows the assistant answering from its hvac-filtermemory ("last changed May 2026, 3-month interval — next change due around August 2026") with a citation back to the appliances note. Its peanut-allergy memory makes it flag nut risk in any recipe, restaurant, or travel form for Iris Lindqvist without being asked. And the two seeded alerts — warranty.expiring (Bosch Dishwasher, ~40 days) and maintenance.due (Carrier HVAC filter) — surface those deadlines before they lapse instead of after.

The leverage

Seven slices, one vault, one audit trail. The family gets a fast, cited answer to "which account funds the remodel?" or "what did we spend on groceries?"; any answer traces back to the note or the read-only query behind it; and the whole thing is measured, so recall is a number you watch rather than a memory you hope holds. Swap "household" for a research vault, a small business, or a nonprofit and the shape is identical — the platform doesn't care what the notes are about, only that every answer is grounded, governed, traceable, and measured.

Keep going

Wire the live money layer end to end with Query live data, or see the whole platform at a glance in the Capability map.