Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: anatomy of a page, where your memory lives, entity-scoped facts walkthrough

garrytan52d44f005571
diff --git a/README.md b/README.md
index dbbcc80d93..0b7dccf363 100644
--- a/README.md
+++ b/README.md
@@ -405,11 +405,11 @@ flowchart LR
Synthesis --> Answer[Cited answer]
```
-**Two engines, one contract.** PGLite (Postgres 17 via WASM, zero-config, default) for personal brains up to ~50K pages. Postgres + pgvector (Supabase or self-hosted) for shared / large / multi-machine deployments. The contract-first `BrainEngine` interface in [`src/core/engine.ts`](src/core/engine.ts) defines the 140+ methods both engines implement; CLI and MCP server are generated from one source.
+**Two engines, one contract.** PGLite (Postgres 17 via WASM, zero-config, default) for personal brains up to ~50K pages. Postgres + pgvector (Supabase or self-hosted) for shared, large or multi-machine brains. Both implement one `BrainEngine` contract ([`src/core/engine.ts`](src/core/engine.ts)); CLI and MCP are generated from it.
-**Canonical files preserve file-backed knowledge.** Your brain repo holds Markdown that GBrain indexes for retrieval; deletes in git become soft-deletes in the database. DB-only pages, unresolved facts, revision history, and operational state need a separate database backup. See the [system-of-record contract](docs/architecture/system-of-record.md). You can publish public subsets, share team mounts, and run thin-client setups pointing at a colleague's brain server. Topologies in [`docs/architecture/topologies.md`](docs/architecture/topologies.md).
+**Canonical files preserve file-backed knowledge.** Your brain repo holds the Markdown; the database is an index rebuildable from it, and git deletes become soft-deletes. DB-only pages, unresolved facts, history and operational state need a database backup: [where your memory lives](docs/guides/where-your-memory-lives.md), [system of record](docs/architecture/system-of-record.md). Publish public subsets, share team mounts, or point a thin client at a colleague's brain. Topologies in [`docs/architecture/topologies.md`](docs/architecture/topologies.md).
-**Two organizational axes (brain ⊥ source).** A *brain* is a database (your personal brain, a team mount you joined). A *source* is a repo inside that brain (wiki, gstack, an essay, a knowledge base). Routing lives in `.gbrain-source` dotfiles and resolves via a documented 6-tier precedence chain. Full diagrams in [`docs/architecture/brains-and-sources.md`](docs/architecture/brains-and-sources.md).
+**Two organizational axes (brain ⊥ source).** A *brain* is a database (your personal brain, a team mount you joined). A *source* is a repo inside that brain. Routing uses `.gbrain-source` dotfiles and a 6-tier precedence chain. Diagrams in [`docs/architecture/brains-and-sources.md`](docs/architecture/brains-and-sources.md).
**Why the graph matters.** Vector search finds similar text; graph retrieval follows stored relationships. Extracted edges are evidence to inspect, not proof that a relationship is true. Graph freshness depends on the write path and maintenance described in [memory boundaries](docs/guides/memory-boundaries.md#page-writes-and-the-graph-are-separate-outcomes). Deep dive: [retrieval architecture](docs/architecture/RETRIEVAL.md); [entity recall](docs/guides/entity-recall.md).
@@ -425,6 +425,7 @@ Start with `gbrain doctor`. For database access failures, use `gbrain engine sta
- [`docs/INSTALL.md`](docs/INSTALL.md) — every install path, end to end
- [`docs/guides/bootstrap.md`](docs/guides/bootstrap.md) — the persistent-personal-agent bootstrap contract (interview, identity files, hooks, private repo, security posture, uninstall), plus local harness mode (`gbrain bootstrap harness`) for wiring framework-spawned Claude Code/Codex sessions to a running serve
+- [Anatomy of a page](docs/guides/page-anatomy.md) — frontmatter, timeline, facts; [per-client facts](docs/guides/entity-scoped-facts.md)
- [`docs/what-schemas-unlock.md`](docs/what-schemas-unlock.md) — why schemas matter: 7 killer use cases, the structural argument for typed page kinds, the agent-co-curates pattern
- [`docs/schema-author-tutorial.md`](docs/schema-author-tutorial.md) — 5-minute walkthrough: fork the bundled pack, add a custom type, backfill existing pages, prove the wiring via `gbrain whoknows`
- [`docs/architecture/`](docs/architecture/) — system design, topologies, retrieval theory
diff --git a/docs/guides/entity-scoped-facts.md b/docs/guides/entity-scoped-facts.md
new file mode 100644
index 0000000000..be5a5ccd5e
--- /dev/null
+++ b/docs/guides/entity-scoped-facts.md
@@ -0,0 +1,107 @@
+# Entity-scoped facts: a different answer per client
+
+When the same question has a different answer for each customer ("what price
+did we quote?"), save each answer as a fact about that customer. gbrain stores
+the customer on every fact (`entity_slug`), and recall for one customer reads
+only that customer's facts, so client A's price never shows up when you ask
+about client B.
+
+**Say to your agent:** *"Remember that we quoted client-a-example $5,000 a
+year and client-b-example $10,000. When I ask about a client's price, recall
+that client's facts, not all prices."*
+
+## Walkthrough
+
+The output below is from a keyless PGLite brain (no embedding provider), so the
+question ranking runs on keywords and says so.
+
+**1. Each client has a page.** Pass `entity` as the page slug with its folder.
+A name without a folder must match exactly one page: `--entity Client` here is
+refused with `entity_unverified` and both client slugs as candidates, and
+nothing is saved.
+
+```bash
+printf -- '---\ntype: company\ntitle: Client A Example\n---\nA prospect.\n' | gbrain put companies/client-a-example
+printf -- '---\ntype: company\ntitle: Client B Example\n---\nA prospect.\n' | gbrain put companies/client-b-example
+```
+
+**2. Save each price with its client.**
+
+```bash
+gbrain remember 'Quoted annual price is $5,000' --entity companies/client-a-example --provenance "pricing call 2026-10-20"
+gbrain remember 'Quoted annual price is $10,000' --entity companies/client-b-example --provenance "pricing call 2026-10-21"
+```
+
+Over MCP it is `remember {fact, entity, provenance}`. Each fact becomes a row
+in the client page's `## Facts` table, so it lives in that page's file
+([anatomy of a page](page-anatomy.md#facts-and-takes-fences)).
+
+**3. Ask about one client.**
+
+```text
+$ gbrain recall companies/client-b-example
+📌 id=2 [companies/client-b-example] Quoted annual price is $10,000 (fact, conf 1.00)
+
+$ gbrain recall "Client A Example"
+📌 id=1 [companies/client-a-example] Quoted annual price is $5,000 (fact, conf 1.00)
+```
+
+`recall {entity}` reads that entity's facts only; the name resolves to the
+page by slug, title or alias. Add `question` to rank within the client's facts
+(`gbrain recall --entity companies/client-a-example --question "annual price"`
+returns the $5,000 row alone).
+
+## When no client is named
+
+`recall {question}` with no entity ranks every fact the caller can read. Today
+the result is one flat list, and each row carries its `entity_slug`:
+
+```text
+$ gbrain recall --question "annual price"
+Facts (ranked by relevance to the question):
+ #3 [fact] Standard annual price is $10,000 unless a client has its own quote — pricing policy 2026-10-01 (relevance 0.67)
+ #2 [fact] (companies/client-b-example) Quoted annual price is $10,000 — pricing call 2026-10-21 (relevance 0.67)
+ #1 [fact] (companies/client-a-example) Quoted annual price is $5,000 — pricing call 2026-10-20 (relevance 0.67)
+note: fact ranking degraded (keyword_only_embedding_disabled)
+```
+
+gbrain does not blend the rows: each one names its client (`entity_slug` in
+`--json` and MCP results), and a row with `entity_slug: null` was saved with no
+entity. Choosing between them is the agent's job, so the agent should:
+
+1. Name the client whenever the conversation is about one, and call
+ `recall {entity}`.
+2. When no client is named, read `entity_slug` on each row and answer per
+ client, or ask which client the person means. Never quote one client's row
+ as the answer for another.
+
+Remote (MCP) callers see `world` facts only, so a fact saved `--visibility
+private` never reaches them.
+
+## A default for everyone else
+
+A rule like "the standard price is $10,000 unless a client has its own quote"
+belongs on a page of its own, so it lives in a file and recall can read it by
+name:
+
+```bash
+printf -- '---\ntype: concept\ntitle: Pricing policy\n---\nHow we price.\n' | gbrain put concepts/pricing
+gbrain remember 'Standard annual price is $10,000' --entity concepts/pricing --provenance "pricing policy 2026-10-01"
+```
+
+The agent then checks the client first (`recall companies/client-a-example`)
+and falls back to the policy (`recall concepts/pricing`) when the client has
+no price of its own. gbrain has no built-in "default unless the entity says
+otherwise" rule; the two calls are that rule.
+
+A fact saved with no entity, or with an entity slug that has no page, still
+saves and still shows up in question recall, but it has no file to live in:
+its only copy is in the database ([where your memory lives](where-your-memory-lives.md)).
+Create the page first.
+
+## Related
+
+- [Entity recall](entity-recall.md): how gbrain resolves a name to an entity.
+- [MCP tool reference: `recall`](../mcp/TOOL_REFERENCE.md#recall) and
+ [`remember`](../mcp/TOOL_REFERENCE.md#remember): every parameter.
+- [Fence format](fence-format.md): the facts table columns.
diff --git a/docs/guides/page-anatomy.md b/docs/guides/page-anatomy.md
new file mode 100644
index 0000000000..8f8943f28f
--- /dev/null
+++ b/docs/guides/page-anatomy.md
@@ -0,0 +1,136 @@
+# Anatomy of a page
+
+A gbrain page is one Markdown file with a fixed shape. Most of it is free text an
+agent or a person writes, and a few parts have a format gbrain reads and writes
+exactly: the YAML frontmatter at the top, the timeline below a sentinel line,
+and the fenced facts and takes tables. This page shows each part once, on a
+real page, and links to the reference that owns it.
+
+The path decides the page's slug: `companies/client-a-example.md` is the page
+`companies/client-a-example`.
+
+## An annotated example
+
+This is the file gbrain wrote for a company page after one `gbrain put`, one
+`gbrain remember` and one `gbrain timeline-add` (PGLite, gbrain-base-v2):
+
+```markdown
+---
+type: company
+title: Client A Example
+subtype: company
+trust_tier: agent_written
+ingested_at: '2026-10-27T19:14:03.639Z'
+source_kind: put_page
+ingested_via: put_page
+---
+
+A prospect.
+
+## Facts
+
+<!--- gbrain:facts:begin -->
+
+| # | claim | kind | confidence | visibility | notability | valid_from | valid_until | source | context |
+|---|-------|------|------------|------------|------------|------------|-------------|--------|---------|
+| 1 | Quoted annual price is $5,000 | fact | 1.0 | world | medium | 2026-10-27T19:14:05Z | | pricing call 2026-10-20 | |
+<!--- gbrain:facts:end -->
+
+<!-- timeline -->
+
+## Timeline
+
+- **2026-10-20** | Meeting notes — Pricing call; quoted the annual plan
+```
+
+| Part | Lines | What it is |
+|---|---|---|
+| Frontmatter | from the first `---` to the second | YAML keys about the page. See [frontmatter keys](#frontmatter-keys). |
+| Compiled truth | everything after the frontmatter and above `<!-- timeline -->` | The current synthesis, in prose. An agent rewrites it when the evidence changes. It can hold the facts and takes fences. |
+| Facts fence | `<!--- gbrain:facts:begin -->` to `<!--- gbrain:facts:end -->` | One row per saved claim about the page's subject. See [fences](#facts-and-takes-fences). |
+| Timeline sentinel | `<!-- timeline -->` | Splits compiled truth from the timeline. |
+| Timeline | everything below the sentinel | Dated evidence, one bullet per event, only ever appended to. See [timeline rows](#timeline-rows). |
+
+## Frontmatter keys
+
+Frontmatter is ordinary YAML. Any key may appear, and gbrain keeps keys it
+doesn't know. These are the ones it reads:
+
+| Key | What gbrain does with it |
+|---|---|
+| `type` | The page type, one of the types the active schema pack declares (`person`, `company`, `concept`, `deal`, ...). When it is missing, the pack infers it from the path prefix (`people/` → `person`). Search and query filter on it (`--types`). |
+| `title` | The display title. Without one, gbrain uses the first `# ` heading, then the file name. |
+| `tags` | A list of tags. |
+| `aliases` | Other names for the page. Entity lookup and link resolution match them, so `[[Alice]]` can find `people/alice-example`. |
+| `email`, `emails` | Exact identity for `gbrain whois`. |
+| `visibility` | `private` hides the page from remote (MCP) callers and keeps facts derived from it private; on a [git-canonical](git-canonical.md) source a private page is never committed. Absent means not private. |
+| `status` | A free-form state such as `draft` or `archived`, returned on every search row. |
+| `event_date`, `date`, `published`, `created` | The page's content date (`effective_date`), in that order of precedence, used by `--since`/`--until` and recency. A leading `YYYY-MM-DD` in the file name also counts. |
+| `slug` | Optional. When present it must name the same page as the path, or the write is refused and sync holds the file ([`frontmatter_slug_conflict`](write-refusals.md#frontmatter_slug_conflict)). |
+
+gbrain stamps a few keys itself: `subtype` (the finer kind gbrain-base-v2 records
+next to the type), `trust_tier` (who the content came from; see
+[memory trust](memory-trust.md)), and `ingested_at`, `source_kind` and
+`ingested_via` (how the page arrived). Leave them as written.
+
+Quote a value that contains `: ` (an email subject such as `Re: pricing`).
+gbrain quotes the common cases before parsing; sync holds a file whose
+frontmatter still doesn't parse ([`invalid_frontmatter`](write-refusals.md#invalid_frontmatter))
+instead of guessing.
+
+## Timeline rows
+
+Below `<!-- timeline -->` each event is one bullet:
+
+```text
+- **YYYY-MM-DD** | Source — Summary
+```
+
+The date is bold, a `|` separates it from the source, and an em dash
+separates the source from the summary. `gbrain timeline-add <slug> <date>
+<summary> --source <source>` (MCP `add_timeline_entry`) writes this form, and
+sync turns each bullet into a timeline row. Older files that split at
+`--- timeline ---`, or at a `---` line directly above `## Timeline`, still
+parse; gbrain writes `<!-- timeline -->`. The
+[compiled truth and timeline pattern](compiled-truth.md) explains how agents
+keep the two halves honest: rewrite the truth, append to the timeline, and
+trace every claim in the truth to a timeline entry.
+
+## Facts and takes fences
+
+A **facts** fence holds what is true about the page's subject. Each row has a
+row number, the claim, its kind (`event`, `preference`, `commitment`,
+`belief`, `fact`, `idea`), confidence, visibility (`world` or `private`),
+notability, `valid_from` / `valid_until`, a source and context. gbrain writes
+those 10 columns; five optional ones carry a typed metric (`claim_metric`,
+`claim_value`, `claim_unit`, `claim_period`) and who asserted the claim
+(`attributed_to`). A struck-through claim (`~~claim~~`) is no longer active.
+
+A **takes** fence holds who believes what, and how strongly: claim, kind
+(`fact`, `take`, `bet`, `hunch`), holder (`who`), weight and since.
+
+Don't hand-write these tables. `remember` adds a fact row and `takes_add` a
+take row, each with a valid row number. When a fence is malformed, gbrain fixes
+what has one exact meaning and holds the rest. Every column, value and repair
+rule is in the generated [fence format](fence-format.md) reference.
+
+## Types come from the schema pack
+
+The active schema pack says which types exist, which folders they live in and
+which types facts are extracted from. The default pack, gbrain-base-v2, has 14
+types plus `note` as the catch-all; see the [type taxonomy](../architecture/type-taxonomy.md).
+`gbrain schema show` prints the active pack, `gbrain schema explain <type>`
+one type's settings, and `gbrain schema lint` checks a pack. MCP agents use
+`schema_explain_type` and `schema_lint`. To change the shape of your brain,
+see [schema packs](../architecture/schema-packs.md) and the
+[schema author tutorial](../schema-author-tutorial.md).
+
+## Where to go next
+
+- [Recommended schema](../GBRAIN_RECOMMENDED_SCHEMA.md): the directory layout
+ (`people/`, `companies/`, `concepts/`, ...) and the filing rules agents follow.
+- [Compiled truth and timeline](compiled-truth.md): how to update a page.
+- [Fence format](fence-format.md): every facts and takes column.
+- [Type taxonomy](../architecture/type-taxonomy.md): the default types.
+- [Where your memory lives](where-your-memory-lives.md): which copy of a page is
+ the record, and what to back up.
diff --git a/docs/guides/where-your-memory-lives.md b/docs/guides/where-your-memory-lives.md
new file mode 100644
index 0000000000..d34eb3ce5d
--- /dev/null
+++ b/docs/guides/where-your-memory-lives.md
@@ -0,0 +1,65 @@
+# Where your memory lives
+
+**The short answer.** gbrain keeps your knowledge as Markdown files with YAML
+frontmatter, in a folder you own and normally version in Git. Those files are
+the record. gbrain indexes them into Postgres (embedded PGLite by default, or
+Postgres with pgvector) with embeddings and keyword search for recall, and that
+index can be rebuilt from the files at any time. What lives only in the
+database, such as private pages, saved facts with no page, revision history and
+write receipts, needs a database backup.
+
+That is the paragraph to quote. The rest of this page says where each part is
+and what follows from it.
+
+## Three layers, one parent
+
+| Layer | What it holds | Can it be rebuilt? |
+|---|---|---|
+| Markdown files in a source folder | Every file-backed page: frontmatter, compiled truth, timeline, and the facts and takes tables ([anatomy of a page](page-anatomy.md)). | It is the record. Git, when the folder is a repository, holds its history. |
+| The index in Postgres | Pages, chunks with embeddings, the keyword (full-text) index, links, timeline rows, and facts and takes parsed from the files. | Yes, from the files: `gbrain sync`, then `gbrain extract all`. Embeddings cost a provider call again. |
+| Database-only records | Pages that have no file on purpose (private pages on a strict source, `storage.db_only` folders, sources with no folder such as connectors), facts saved with no page to hold them, page revision history, receipts and other operational state. | No. Back up the database. |
+
+Recall reads the index: hybrid search ranks keyword and vector matches
+together, optionally reranked, and `recall` reads saved facts. Nothing is
+"just a vector store": the vectors and the keyword index both point back at
+pages whose text is in the files.
+
+## Where the folder is
+
+A fresh `gbrain init` creates one source at
+`~/.gbrain/content/<brain-id>/default` (under `GBRAIN_HOME` when it is set).
+It is a plain folder until you make it a repository: `gbrain init --git`
+initializes Git in a new empty folder, `--content-root <path>` picks the
+folder, and `gbrain sources add <id> --path <repo>` adds a Git repository
+you already have. `gbrain sources harden <id>` adds the commit-and-push hook that
+keeps a remote copy current. `gbrain sources list` shows every source and its
+folder. A brain initialized with `--db-only`, or a connector source (Gmail,
+Calendar, GitHub), has no folder, and the database is its record.
+
+## How tightly the database follows Git
+
+Each source with a Git checkout runs in one of two modes:
+
+- **Mixed (the default).** Sync imports what is committed. A write lands in the
+ file and the database together and is committed to Git afterwards. When the
+ two disagree, sync keeps the database copy or holds the page for review.
+- **Strict, or git-canonical (opt-in per source).** Every write is committed to
+ Git before the database records it, sync indexes committed files only, and
+ Git wins any disagreement. See [git-canonical sources](git-canonical.md).
+
+Either way, a page with a file can be recovered from Git. The difference is
+whether the database can ever be briefly ahead of it.
+
+## What to back up
+
+- **The folder, through Git.** Push it somewhere you control. That covers every
+ file-backed page and its history.
+- **The database.** It holds the database-only records above. On PGLite that
+ is `gbrain backup create --output <absolute path>`; on Postgres, your
+ provider's backups or `pg_dump`. Markdown export is
+ not a database backup.
+
+The full contract, with every table classified and the disaster-recovery
+commands, is the [system of record](../architecture/system-of-record.md).
+[Memory boundaries](memory-boundaries.md) covers what leaves the machine and
+what sharing can and can't promise.
diff --git a/llms-full.txt b/llms-full.txt
index 76575d3143..a9551ba195 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -5399,11 +5399,11 @@ flowchart LR
Synthesis --> Answer[Cited answer]
```
-**Two engines, one contract.** PGLite (Postgres 17 via WASM, zero-config, default) for personal brains up to ~50K pages. Postgres + pgvector (Supabase or self-hosted) for shared / large / multi-machine deployments. The contract-first `BrainEngine` interface in [`src/core/engine.ts`](src/core/engine.ts) defines the 140+ methods both engines implement; CLI and MCP server are generated from one source.
+**Two engines, one contract.** PGLite (Postgres 17 via WASM, zero-config, default) for personal brains up to ~50K pages. Postgres + pgvector (Supabase or self-hosted) for shared, large or multi-machine brains. Both implement one `BrainEngine` contract ([`src/core/engine.ts`](src/core/engine.ts)); CLI and MCP are generated from it.
-**Canonical files preserve file-backed knowledge.** Your brain repo holds Markdown that GBrain indexes for retrieval; deletes in git become soft-deletes in the database. DB-only pages, unresolved facts, revision history, and operational state need a separate database backup. See the [system-of-record contract](docs/architecture/system-of-record.md). You can publish public subsets, share team mounts, and run thin-client setups pointing at a colleague's brain server. Topologies in [`docs/architecture/topologies.md`](docs/architecture/topologies.md).
+**Canonical files preserve file-backed knowledge.** Your brain repo holds the Markdown; the database is an index rebuildable from it, and git deletes become soft-deletes. DB-only pages, unresolved facts, history and operational state need a database backup: [where your memory lives](docs/guides/where-your-memory-lives.md), [system of record](docs/architecture/system-of-record.md). Publish public subsets, share team mounts, or point a thin client at a colleague's brain. Topologies in [`docs/architecture/topologies.md`](docs/architecture/topologies.md).
-**Two organizational axes (brain ⊥ source).** A *brain* is a database (your personal brain, a team mount you joined). A *source* is a repo inside that brain (wiki, gstack, an essay, a knowledge base). Routing lives in `.gbrain-source` dotfiles and resolves via a documented 6-tier precedence chain. Full diagrams in [`docs/architecture/brains-and-sources.md`](docs/architecture/brains-and-sources.md).
+**Two organizational axes (brain ⊥ source).** A *brain* is a database (your personal brain, a team mount you joined). A *source* is a repo inside that brain. Routing uses `.gbrain-source` dotfiles and a 6-tier precedence chain. Diagrams in [`docs/architecture/brains-and-sources.md`](docs/architecture/brains-and-sources.md).
**Why the graph matters.** Vector search finds similar text; graph retrieval follows stored relationships. Extracted edges are evidence to inspect, not proof that a relationship is true. Graph freshness depends on the write path and maintenance described in [memory boundaries](docs/guides/memory-boundaries.md#page-writes-and-the-graph-are-separate-outcomes). Deep dive: [retrieval architecture](docs/architecture/RETRIEVAL.md); [entity recall](docs/guides/entity-recall.md).
@@ -5419,6 +5419,7 @@ Start with `gbrain doctor`. For database access failures, use `gbrain engine sta
- [`docs/INSTALL.md`](docs/INSTALL.md) — every install path, end to end
- [`docs/guides/bootstrap.md`](docs/guides/bootstrap.md) — the persistent-personal-agent bootstrap contract (interview, identity files, hooks, private repo, security posture, uninstall), plus local harness mode (`gbrain bootstrap harness`) for wiring framework-spawned Claude Code/Codex sessions to a running serve
+- [Anatomy of a page](docs/guides/page-anatomy.md) — frontmatter, timeline, facts; [per-client facts](docs/guides/entity-scoped-facts.md)
- [`docs/what-schemas-unlock.md`](docs/what-schemas-unlock.md) — why schemas matter: 7 killer use cases, the structural argument for typed page kinds, the agent-co-curates pattern
- [`docs/schema-author-tutorial.md`](docs/schema-author-tutorial.md) — 5-minute walkthrough: fork the bundled pack, add a custom type, backfill existing pages, prove the wiring via `gbrain whoknows`
- [`docs/architecture/`](docs/architecture/) — system design, topologies, retrieval theory
diff --git a/llms.txt b/llms.txt
index f2f8a208d7..f2f90fe6dd 100644
--- a/llms.txt
+++ b/llms.txt
@@ -32,6 +32,9 @@ Repo: https://github.com/garrytan/gbrain
- [docs/guides/multi-hop.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/multi-hop.md): Multi-hop relationship questions: typed hop chains over links (search planner + traverse_graph hops), evidence edges, refusals, notices, settings.
- [docs/ENGINES.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/ENGINES.md): PGLite vs Postgres trade-off and when to migrate.
- [docs/guides/move-to-postgres.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/move-to-postgres.md): Move a PGLite brain to Postgres with its history: --url-env target setup, plan (exit 3) then --yes --expect, status/resume/rollback, what moves vs stays on this computer, recovery by error code.
+- [docs/guides/where-your-memory-lives.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/where-your-memory-lives.md): The quotable answer to "database, vector store or Markdown?": Markdown with frontmatter in a folder you own (normally Git) is the record, Postgres with embeddings and keyword search is a rebuildable index, and database-only records (private pages on strict sources, facts with no page, history, receipts) need a database backup. Where the folder is, mixed vs strict sources, what to back up.
+- [docs/guides/page-anatomy.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/page-anatomy.md): Anatomy of a page on one annotated example: frontmatter keys gbrain reads and stamps, compiled truth, the `<!-- timeline -->` sentinel and `- **YYYY-MM-DD** | Source — Summary` rows, the facts and takes fences, and schema-pack types; links to the four reference docs.
+- [docs/guides/entity-scoped-facts.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/entity-scoped-facts.md): Different answer per client: `remember --entity` ties a fact to a page, `recall <entity>` reads only that client's facts, `recall --question` with no entity returns a flat list with each row's entity_slug, and a default kept on its own page.
- [docs/GBRAIN_RECOMMENDED_SCHEMA.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/GBRAIN_RECOMMENDED_SCHEMA.md): MECE directory structure (people/, companies/, concepts/).
- [docs/what-schemas-unlock.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/what-schemas-unlock.md): Why schemas matter: 7 killer use cases (4000 invisible meetings, founder ops brain, research brain, legal brain, team brain, agent-as-co-curator) + the structural argument for typed page kinds. Read this before pitching schema authoring.
- [docs/schema-author-tutorial.md](https://raw.githubusercontent.com/garrytan/gbrain/master/docs/schema-author-tutorial.md): 5-minute walkthrough: fork the bundled pack, add a custom `researcher` type, backfill existing pages via `gbrain schema sync --apply`, prove the T1.5 wiring via `gbrain whoknows`.
diff --git a/scripts/llms-config.ts b/scripts/llms-config.ts
index e0118e417e..a51ec47573 100644
--- a/scripts/llms-config.ts
+++ b/scripts/llms-config.ts
@@ -122,6 +122,27 @@ export const SECTIONS: DocSection[] = [
path: "docs/guides/move-to-postgres.md",
includeInFull: false,
},
+ {
+ title: "docs/guides/where-your-memory-lives.md",
+ description:
+ "The quotable answer to \"database, vector store or Markdown?\": Markdown with frontmatter in a folder you own (normally Git) is the record, Postgres with embeddings and keyword search is a rebuildable index, and database-only records (private pages on strict sources, facts with no page, history, receipts) need a database backup. Where the folder is, mixed vs strict sources, what to back up.",
+ path: "docs/guides/where-your-memory-lives.md",
+ includeInFull: false,
+ },
+ {
+ title: "docs/guides/page-anatomy.md",
+ description:
+ "Anatomy of a page on one annotated example: frontmatter keys gbrain reads and stamps, compiled truth, the `<!-- timeline -->` sentinel and `- **YYYY-MM-DD** | Source — Summary` rows, the facts and takes fences, and schema-pack types; links to the four reference docs.",
+ path: "docs/guides/page-anatomy.md",
+ includeInFull: false,
+ },
+ {
+ title: "docs/guides/entity-scoped-facts.md",
+ description:
+ "Different answer per client: `remember --entity` ties a fact to a page, `recall <entity>` reads only that client's facts, `recall --question` with no entity returns a flat list with each row's entity_slug, and a default kept on its own page.",
+ path: "docs/guides/entity-scoped-facts.md",
+ includeInFull: false,
+ },
{
title: "docs/GBRAIN_RECOMMENDED_SCHEMA.md",
description: