| 1 | --- |
| 2 | title: Context hub |
| 3 | description: The catalog g1t builds of everything a workspace builds and runs, memory that fills itself from runs, reviews, merges and docs, one search over all of it, and a scorecard for every project. |
| 4 | --- |
| 5 | |
| 6 | The **context hub** is one place to ask about a workspace: what it builds |
| 7 | and runs, who owns what, how each project is built, tested and deployed, |
| 8 | and what people and agents have learned along the way. It fills itself |
| 9 | from your repositories, deployments and integrations, and from the work |
| 10 | agents and people do, so it is never a wiki someone has to keep up. |
| 11 | |
| 12 | Open it from **Context**, in the workspace's sidebar. |
| 13 | It has four tabs: |
| 14 | |
| 15 | | Tab | What it shows | |
| 16 | | --- | --- | |
| 17 | | **Catalog** | Every project, app, API, package, language, owner, environment, integration and doc, and how they relate | |
| 18 | | **Memory** | The Review queue: memory candidates waiting for a person | |
| 19 | | **Search** | One search across the catalog, docs, issues, pull requests and memory | |
| 20 | | **Scorecards** | A few rules every project should meet, each failing one a click away from an issue an agent fixes | |
| 21 | |
| 22 | Every g1t run starts with a **Context** section drawn from the hub, |
| 23 | and your own agents can ask it through the [MCP tools](#mcp-tools): |
| 24 | the `search` tool's `context` and `entity` actions. |
| 25 | |
| 26 | ## The catalog |
| 27 | |
| 28 | The catalog is built from each project's default branch, on every push to |
| 29 | it. g1t reads the files that say what a project is, and only those whose |
| 30 | contents changed since the last push: |
| 31 | |
| 32 | | Read from | Gives | |
| 33 | | --- | --- | |
| 34 | | `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `requirements.txt` | **Packages** (name, version, dependencies), **languages**, test and build commands, the package manager from the committed lockfile | |
| 35 | | `wrangler.jsonc`, `wrangler.json`, `wrangler.toml`; `openapi.*`, `swagger.*` | **APIs**: a Worker's routes, or an OpenAPI document's operations | |
| 36 | | `README`, `AGENTS.md` (or `CLAUDE.md`), `CONTRIBUTING`, `docs/*.md`, `runbooks/*.md` | **Docs**, split into sections for search | |
| 37 | | `.g1t/workflows/*`, `.github/workflows/*` | Whether the project's tests run in checks | |
| 38 | | `owners:` in `.g1t/project.yml`, and `CODEOWNERS` | **Owners** | |
| 39 | | `memory:` in `.g1t/project.yml` | Which docs are [read for memory](#which-docs-are-read-for-memory) | |
| 40 | |
| 41 | and joins them with what g1t already knows: |
| 42 | |
| 43 | - **Dependencies** between projects, from [Projects](/guides/projects/); |
| 44 | - **Apps and environments**, with their live addresses, from |
| 45 | [Deployments](/guides/deployments/); |
| 46 | - **Integrations**, from [Integrations](/guides/integrations/); |
| 47 | - **Owners** also include the members who wrote at least a fifth of the |
| 48 | project's last 100 commits, up to three. |
| 49 | |
| 50 | Each entry links to where it lives: a project's code, a doc's file, an |
| 51 | app's address. Entries relate to each other: |
| 52 | |
| 53 | | Relation | Example | |
| 54 | | --- | --- | |
| 55 | | `depends_on` | `@acme/web` depends on `@acme/ui` | |
| 56 | | `owned_by` | `web` is owned by `ana` | |
| 57 | | `deploys_to` | the `web` app deploys to `web/production` | |
| 58 | | `documented_by` | `web` is documented by its `README.md` | |
| 59 | | `exposes` | `web` exposes the `@acme/web` package and its app; the app exposes its routes | |
| 60 | | `uses` | `web` uses TypeScript, and the Sentry integration that reports on it | |
| 61 | |
| 62 | The **Catalog** tab filters by kind and by project, and draws the |
| 63 | workspace's projects with an arrow from each to the projects it uses. |
| 64 | |
| 65 | Building the catalog is cheap and repeatable: each push reads at most 15 |
| 66 | files of a project, a file whose contents have not changed is never read |
| 67 | again, and building twice from the same commit gives the same catalog. |
| 68 | |
| 69 | ## Memory that fills itself |
| 70 | |
| 71 | [Memory](/guides/agents-and-memory/#memory) is what agents are told about a |
| 72 | project and its workspace. Besides what agents save with the `memory` tool's |
| 73 | `remember` action and what people add by hand, the hub captures it from four places: |
| 74 | |
| 75 | | Source | What it captures | Kind | |
| 76 | | --- | --- | --- | |
| 77 | | **Agent runs** | At the end of every run that changes code, the agent is asked what it learned that the next agent would need, with what showed it | fact, convention, decision or gotcha | |
| 78 | | **Reviews** | A person's request for changes, or a comment that corrects the agent ("we use the shared client instead"), on a pull request | convention, quoting the comment | |
| 79 | | **Merges** | A merged pull request's title, why (the first paragraph of its description) and the files it changed | decision | |
| 80 | | **Docs and manifests** | Bullets in `AGENTS.md`; commands and bullets under the setup, testing and conventions sections of docs on how to work in the project; the package manager and test commands from manifests | fact, convention or gotcha | |
| 81 | |
| 82 | What is captured arrives as a **candidate**. No agent is given a candidate |
| 83 | until it is **kept**: |
| 84 | |
| 85 | - **at once**, when two independent sources say the same thing (a doc and |
| 86 | a run, two runs, a run and a review), or when a project's `AGENTS.md` or |
| 87 | manifests state it; |
| 88 | - **by a person**, in the Review queue. |
| 89 | |
| 90 | The same thing said again in different case, punctuation or spacing counts |
| 91 | as the same memory, seen once more. So does the same thing in slightly |
| 92 | different words: a sentence that grew (a list with one more item), or one |
| 93 | that holds all of another's words. A memory seen again from the same |
| 94 | source (the same run, the same file) is not counted twice. |
| 95 | |
| 96 | ### Which docs are read for memory |
| 97 | |
| 98 | Memory is for how to work in a project, so only docs that say how are |
| 99 | read for it: |
| 100 | |
| 101 | | Read for memory | Not read for memory | |
| 102 | | --- | --- | |
| 103 | | `README`, `AGENTS.md` (or `CLAUDE.md`), `CONTRIBUTING`, `runbooks/*.md` | Plans and roadmaps (`PLAN.md`, `roadmap.md`) | |
| 104 | | A doc in `docs/` whose name says how to work: `DEPLOYING.md`, `testing.md`, `architecture.md`, `setup.md`, `conventions.md`, `getting-started.md` | Changelogs, release notes, history, incidents, demos, research, notes, feedback | |
| 105 | |
| 106 | Within those docs: |
| 107 | |
| 108 | - Only the **setup, testing and conventions** sections are read (in |
| 109 | `AGENTS.md`, every section). A section about plans, a roadmap, asks or |
| 110 | feedback is skipped with everything under it, wherever it is. |
| 111 | - A doc that reads as a plan or a report (most of its headings are plans, |
| 112 | or its bullets are labelled "What we tried", "Ask" and the like) gives |
| 113 | nothing, whatever its name. |
| 114 | - A line that says what someone wants rather than how things are ("g1t |
| 115 | will", "should", "TODO") is left out. In `AGENTS.md`, "should" states a |
| 116 | rule, and is kept. |
| 117 | - A bullet is taken whole, with the lines it wraps onto. A long one is cut |
| 118 | only between sentences, to 300 characters; one whose first sentence is |
| 119 | longer is left out rather than cut. |
| 120 | - A bullet that tells you to do or never do something is a convention or |
| 121 | a gotcha; anything else is a fact. Outside `AGENTS.md`, a bullet waits |
| 122 | for review at 50 to 60% sure. |
| 123 | |
| 124 | To read another doc for memory, or never read one, say so in the |
| 125 | project's `.g1t/project.yml`, by path or a whole folder: |
| 126 | |
| 127 | ```yaml |
| 128 | memory: |
| 129 | docs: |
| 130 | - docs/PERFORMANCE.md |
| 131 | skip: |
| 132 | - README.md |
| 133 | - docs/legacy/* |
| 134 | ``` |
| 135 | |
| 136 | `skip` wins over `docs`. A change to these lists applies to each doc the |
| 137 | next time it changes, or for every doc at once with **Rebuild**. |
| 138 | |
| 139 | Once g1t has read every file of a project as these rules read it, a |
| 140 | candidate from its docs that is still waiting and that its docs no longer |
| 141 | suggest (the doc changed, or the rules leave the line out) is removed from |
| 142 | the queue. A candidate another source saw too, and every kept or dismissed |
| 143 | memory, stays. A waiting candidate its doc now says in other words takes |
| 144 | the new words. |
| 145 | |
| 146 | ### Review |
| 147 | |
| 148 | The **Memory** tab of the Context page lists every candidate in the |
| 149 | workspace; a project's **Agents → Memory** lists its own. Each shows where |
| 150 | it came from (a run, a review comment, a merged pull request, a doc), the |
| 151 | evidence quoted, how sure its source was and how often it has been seen. |
| 152 | |
| 153 | - **Keep** gives it to every agent from their next run on. |
| 154 | - **Edit** rewords it, or changes its kind, and keeps it. |
| 155 | - **Dismiss** throws it away, and the same thing, in the same words or |
| 156 | near enough to them, is never suggested again. |
| 157 | |
| 158 | ### Never a secret |
| 159 | |
| 160 | Captured memory is held to the same rule as everything else in memory: text |
| 161 | that looks like a key, a token, a password or a private key is refused, in |
| 162 | the memory and in its evidence. Agents are told never to report one. |
| 163 | |
| 164 | ## Search |
| 165 | |
| 166 | **Search** finds things by meaning, across: |
| 167 | |
| 168 | - catalog entries; |
| 169 | - the sections of every project's docs; |
| 170 | - issues and pull requests, with their descriptions (an agent's pull |
| 171 | request description is its account of the session); |
| 172 | - kept memory. |
| 173 | |
| 174 | Each result says what kind of thing it is, where it came from, who wrote it |
| 175 | and how fresh it is. When the search index cannot answer, g1t matches the |
| 176 | words of your query instead, and says so. |
| 177 | |
| 178 | Searching by meaning uses embeddings, which are compute, so it is for |
| 179 | workspaces on the [g1t plan](/guides/usage-and-billing/#the-g1t-plan) and |
| 180 | the [trial](/guides/usage-and-billing/#the-trial). Every other workspace gets the catalog, |
| 181 | memory and search by matching words, with nothing to set up; the Context |
| 182 | page says which it has. If g1t cannot reach its billing service, search |
| 183 | matches words until it can. |
| 184 | |
| 185 | ### Who sees what |
| 186 | |
| 187 | What you find follows what you can read, project by project: |
| 188 | |
| 189 | - Search never reads another workspace's rows. |
| 190 | - Owners, members while the workspace's |
| 191 | [base permission](/guides/access-and-roles/#the-base-permission) is Read |
| 192 | or higher, and the workspace's own agents find everything in it. |
| 193 | - A member whose base permission is **None** finds the public projects and |
| 194 | the private ones whose repositories they were given a role on, and |
| 195 | nothing of the others: the counts on the Context page, the catalog, |
| 196 | search and scorecards leave them out. |
| 197 | - An [outside collaborator](/guides/access-and-roles/#outside-collaborators) |
| 198 | finds the projects shared with them, and anyone else the public ones: |
| 199 | their catalog entries, docs, issues and pull requests. |
| 200 | - Workspace memory is for members only. A project's memory is for members |
| 201 | who can read the project; no one outside the workspace finds memory in |
| 202 | search. |
| 203 | - A project made private is hidden from everyone who cannot read it at |
| 204 | once, even before it is searched again. |
| 205 | |
| 206 | ## Scorecards |
| 207 | |
| 208 | Each project is checked against a few rules: |
| 209 | |
| 210 | | Rule | Passes when | |
| 211 | | --- | --- | |
| 212 | | **Has an owner** | `.g1t/project.yml` or `CODEOWNERS` names one, or a member wrote most of it | |
| 213 | | **Has a README** | A README sits at the project's root | |
| 214 | | **Has an AGENTS.md** | An `AGENTS.md` (or `CLAUDE.md`) tells agents how to work here | |
| 215 | | **Tests run in checks** | A workflow in `.g1t/workflows` or `.github/workflows` runs tests | |
| 216 | | **Production deploy is green** | Production is live and its latest build did not fail. Does not apply to a project that does not deploy on g1t | |
| 217 | | **No open secret findings** | [Security](/guides/security/) has no open secret findings for it | |
| 218 | |
| 219 | A failing rule has **Fix with an agent**: g1t opens an issue saying what to |
| 220 | do, with a definition of done where one can be written (such as |
| 221 | "`test -f AGENTS.md` passes."), and puts g1t's agent on it. |
| 222 | |
| 223 | ## Agents start with context |
| 224 | |
| 225 | Every g1t run is given a **Context** section, after the project's |
| 226 | memory, within about 4,000 characters: |
| 227 | |
| 228 | - the project's stack, test commands, owners, docs, and its environments |
| 229 | with their addresses; |
| 230 | - the kept memories closest to the task, beyond the pinned ones every run |
| 231 | already has; |
| 232 | - the latest decisions from merged pull requests. |
| 233 | |
| 234 | Each line says where it came from (`[source: catalog]`, |
| 235 | `[source: AGENTS.md]`, `[source: review on #12]`). Agents are told it is |
| 236 | reference material: where it disagrees with the code, the code wins. |
| 237 | |
| 238 | The section holds only what the person the run acts for can read. A run |
| 239 | for an outside collaborator is told the project's own memory, never the |
| 240 | workspace's, and names only the projects around it that they can read. |
| 241 | |
| 242 | ## Building it for a workspace |
| 243 | |
| 244 | The first time anyone opens a workspace's Context page, g1t builds its hub: |
| 245 | the catalog for every project (up to 50), memory candidates from their |
| 246 | docs, manifests and last 20 merged pull requests with their reviews, and |
| 247 | the search index for docs, recent issues and pull requests, and kept |
| 248 | memory. **Rebuild** does it again, reading every file afresh. |
| 249 | |
| 250 | Putting text in the search index uses Workers AI and is counted per |
| 251 | workspace and month. Before each batch is embedded, g1t reserves what it |
| 252 | may cost with billing, and settles what it really cost afterwards; a |
| 253 | workspace billing refuses (no plan or trial, its spend limit reached, |
| 254 | compute paused) keeps text search, and its new text is not embedded. A |
| 255 | workspace that passes 20 million tokens in a month keeps text search too, |
| 256 | and new text waits for the next month's index. |
| 257 | |
| 258 | ## MCP tools |
| 259 | |
| 260 | Both are actions of the [`search` tool](/reference/mcp/#search), and need |
| 261 | the `memory:read` scope. |
| 262 | |
| 263 | | `search` action | Takes | Does | |
| 264 | | --- | --- | --- | |
| 265 | | `context` | `query`, and `workspace` or `repo`; optional `project`, `kinds`, `limit` | One search across the catalog, docs, issues, pull requests and memory, as [Search](#search) | |
| 266 | | `entity` | `kind`, `id`, and `workspace` or `repo` | One catalog entry by its id or key (a project's slug, `npm:<name>`, a username), with every relation | |
| 267 | |
| 268 | g1t's own agents have both. Over REST: |
| 269 | |
| 270 | ```sh |
| 271 | curl "https://api.g1t.sh/workspaces/acme/context/search?q=how+do+we+deploy+the+api" \ |
| 272 | -H "Authorization: Bearer $G1T_TOKEN" |
| 273 | |
| 274 | curl "https://api.g1t.sh/workspaces/acme/context/project/web" \ |
| 275 | -H "Authorization: Bearer $G1T_TOKEN" |
| 276 | ``` |
| 277 | |
| 278 | See [Search the context hub](/reference/api/context/search-context/) and |
| 279 | [Get a catalog entry](/reference/api/context/get-entity/). |