Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: fact-check fixes (aliases, visibility, date precedence, connector folders, inference, collapsed rows)

garrytan3257cee3932a
diff --git a/README.md b/README.md
index 0b7dccf363..209d7486bd 100644
--- a/README.md
+++ b/README.md
@@ -405,7 +405,7 @@ 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 or multi-machine brains. Both implement one `BrainEngine` contract ([`src/core/engine.ts`](src/core/engine.ts)); CLI and MCP are generated from it.
+**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 share one op registry.
**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).
diff --git a/docs/guides/entity-scoped-facts.md b/docs/guides/entity-scoped-facts.md
index be5a5ccd5e..78470c5740 100644
--- a/docs/guides/entity-scoped-facts.md
+++ b/docs/guides/entity-scoped-facts.md
@@ -65,9 +65,11 @@ Facts (ranked by relevance to the question):
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:
+gbrain does not merge different claims: each row names its client
+(`entity_slug` in `--json` and MCP results), and a row with `entity_slug: null`
+was saved with no entity. The same claim saved for several entities can come
+back as one row; it then lists every entity in `entity_slugs` with a
+`collapsed_count`. 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}`.
@@ -94,10 +96,12 @@ 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.
+Without `entity`, `remember` attaches the fact to a page only when the text
+names exactly one entity page (`entity_inferred: "mention"`; `--infer-entity
+false` turns that off). A fact that ends up 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
diff --git a/docs/guides/page-anatomy.md b/docs/guides/page-anatomy.md
index 8f8943f28f..b24ae52828 100644
--- a/docs/guides/page-anatomy.md
+++ b/docs/guides/page-anatomy.md
@@ -49,7 +49,7 @@ A prospect.
| 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). |
+| Timeline | everything below the sentinel | Dated evidence, one bullet per event. New entries are added in date order; existing ones aren't rewritten. See [timeline rows](#timeline-rows). |
## Frontmatter keys
@@ -61,11 +61,11 @@ doesn't know. These are the ones it reads:
| `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`. |
+| `aliases` | Other names for the page. Entity lookup (`entity`, `recall <name>`, `remember --entity <name>`) and `gbrain whois` match them. A wikilink resolves by slug or file name, so write `[[people/alice-example]]` for a dependable link. |
| `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. |
+| `visibility` | `private` hides the page from remote (MCP) callers by default and keeps facts derived from it private; on a [git-canonical](../designs/GIT_CANONICAL_MEMORY.md) source a private page is never committed. A page without `visibility` is normally world, but some are private anyway: privacy aliases such as `access: private`, derived pages whose origin is private, and pinned-question pages. See [what confines remote callers](../architecture/brains-and-sources.md#what-confines-remote-callers-and-what-does-not). |
| `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. |
+| `event_date`, `date`, `published`, `created` | The page's content date (`effective_date`), used by `--since`/`--until` and recency. Precedence: `event_date`, `date`, `published`, a leading `YYYY-MM-DD` in the file name, then `created` (or `created_at`, `date_created`). Under `daily/` and `meetings/` the file name comes first. |
| `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
@@ -118,7 +118,8 @@ rule is in the generated [fence format](fence-format.md) reference.
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).
+canonical types plus `note` as the catch-all, and a few internal types gbrain
+writes itself; 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,
diff --git a/docs/guides/where-your-memory-lives.md b/docs/guides/where-your-memory-lives.md
index d34eb3ce5d..3281e44588 100644
--- a/docs/guides/where-your-memory-lives.md
+++ b/docs/guides/where-your-memory-lives.md
@@ -17,7 +17,7 @@ and what follows from it.
|---|---|---|
| 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. |
+| Database-only records | Pages that have no file on purpose (private pages on a strict source, `storage.db_only` folders, a brain or source with write-through off), 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
@@ -33,19 +33,22 @@ 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.
+folder. A brain initialized with `--db-only` has no folder, and the database is its
+record. Connector sources (Gmail, Calendar, GitHub) render their pages into
+a folder of their own.
## 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).
+- **Mixed (the default).** Sync imports changes made in the files. A write
+ lands in the file and the database together and is committed to Git
+ afterwards. When the two disagree, sync keeps a database-only change or
+ holds the page for review.
+- **Strict, or git-canonical (opt-in per source).** Every file-backed write is
+ committed to Git before the database records it, sync indexes committed
+ files only, and Git wins any disagreement; the declared database-only
+ classes above are the exception. See the [git-canonical design](../designs/GIT_CANONICAL_MEMORY.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.
diff --git a/llms-full.txt b/llms-full.txt
index a9551ba195..7ba931bea6 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -5399,7 +5399,7 @@ 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 or multi-machine brains. Both implement one `BrainEngine` contract ([`src/core/engine.ts`](src/core/engine.ts)); CLI and MCP are generated from it.
+**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 share one op registry.
**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).