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.mdindex 0b7dccf363..209d7486bd 100644--- a/README.md+++ b/README.md@@ -405,7 +405,7 @@ flowchart LRSynthesis --> 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.mdindex 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 hasno price of its own. gbrain has no built-in "default unless the entity saysotherwise" 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.## Relateddiff --git a/docs/guides/page-anatomy.md b/docs/guides/page-anatomy.mdindex 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 andwhich 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.mdindex 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 matchestogether, optionally reranked, and `recall` reads saved facts. Nothing is@@ -33,19 +33,22 @@ initializes Git in a new empty folder, `--content-root <path>` picks thefolder, and `gbrain sources add <id> --path <repo>` adds a Git repositoryyou already have. `gbrain sources harden <id>` adds the commit-and-push hook thatkeeps 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 GitEach 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 iswhether the database can ever be briefly ahead of it.diff --git a/llms-full.txt b/llms-full.txtindex a9551ba195..7ba931bea6 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -5399,7 +5399,7 @@ flowchart LRSynthesis --> 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).