| 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 agent 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 | `search_context` and `get_entity`. |
| 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 | |
| 40 | and joins them with what g1t already knows: |
| 41 | |
| 42 | - **Dependencies** between projects, from [Projects](/guides/projects/); |
| 43 | - **Apps and environments**, with their live addresses, from |
| 44 | [Deployments](/guides/deployments/); |
| 45 | - **Integrations**, from [Integrations](/guides/integrations/); |
| 46 | - **Owners** also include the members who wrote at least a fifth of the |
| 47 | project's last 100 commits, up to three. |
| 48 | |
| 49 | Each entry links to where it lives: a project's code, a doc's file, an |
| 50 | app's address. Entries relate to each other: |
| 51 | |
| 52 | | Relation | Example | |
| 53 | | --- | --- | |
| 54 | | `depends_on` | `web` depends on `api`; `@acme/web` depends on `@acme/ui` | |
| 55 | | `owned_by` | `web` is owned by `ana` | |
| 56 | | `deploys_to` | the `web` app deploys to `web/production` | |
| 57 | | `documented_by` | `web` is documented by its `README.md` | |
| 58 | | `exposes` | `web` exposes the `@acme/web` package and its app; the app exposes its routes | |
| 59 | | `uses` | `web` uses TypeScript, and the Sentry integration that reports on it | |
| 60 | |
| 61 | The **Catalog** tab filters by kind and by project, and draws the |
| 62 | workspace's projects with an arrow from each to the projects it uses. |
| 63 | |
| 64 | Building the catalog is cheap and repeatable: each push reads at most 15 |
| 65 | files of a project, a file whose contents have not changed is never read |
| 66 | again, and building twice from the same commit gives the same catalog. |
| 67 | |
| 68 | ## Memory that fills itself |
| 69 | |
| 70 | [Memory](/guides/agents-and-memory/#memory) is what agents are told about a |
| 71 | project and its workspace. Besides what agents save with `remember` and |
| 72 | what people add by hand, the hub captures it from four places: |
| 73 | |
| 74 | | Source | What it captures | Kind | |
| 75 | | --- | --- | --- | |
| 76 | | **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 | |
| 77 | | **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 | |
| 78 | | **Merges** | A merged pull request's title, why (the first paragraph of its description) and the files it changed | decision | |
| 79 | | **Docs and manifests** | Bullets in `AGENTS.md`; commands under a README's setup and testing sections; conventions sections; the package manager and test commands from manifests | fact, convention or gotcha | |
| 80 | |
| 81 | What is captured arrives as a **candidate**. No agent is given a candidate |
| 82 | until it is **kept**: |
| 83 | |
| 84 | - **at once**, when two independent sources say the same thing (a doc and |
| 85 | a run, two runs, a run and a review), or when a project's `AGENTS.md` or |
| 86 | manifests state it; |
| 87 | - **by a person**, in the Review queue. |
| 88 | |
| 89 | The same thing said again in different case, punctuation or spacing counts |
| 90 | as the same memory, seen once more. A memory seen again from the same |
| 91 | source (the same run, the same file) is not counted twice. |
| 92 | |
| 93 | ### Review |
| 94 | |
| 95 | The **Memory** tab of the Context page lists every candidate in the |
| 96 | workspace; a project's **Agents → Memory** lists its own. Each shows where |
| 97 | it came from (a run, a review comment, a merged pull request, a doc), the |
| 98 | evidence quoted, how sure its source was and how often it has been seen. |
| 99 | |
| 100 | - **Keep** gives it to every agent from their next run on. |
| 101 | - **Edit** rewords it, or changes its kind, and keeps it. |
| 102 | - **Dismiss** throws it away, and the same wording is never suggested |
| 103 | again. |
| 104 | |
| 105 | ### Never a secret |
| 106 | |
| 107 | Captured memory is held to the same rule as everything else in memory: text |
| 108 | that looks like a key, a token, a password or a private key is refused, in |
| 109 | the memory and in its evidence. Agents are told never to report one. |
| 110 | |
| 111 | ## Search |
| 112 | |
| 113 | **Search** finds things by meaning, across: |
| 114 | |
| 115 | - catalog entries; |
| 116 | - the sections of every project's docs; |
| 117 | - issues and pull requests, with their descriptions (an agent's pull |
| 118 | request description is its account of the session); |
| 119 | - kept memory. |
| 120 | |
| 121 | Each result says what kind of thing it is, where it came from, who wrote it |
| 122 | and how fresh it is. When the search index cannot answer, g1t matches the |
| 123 | words of your query instead, and says so. |
| 124 | |
| 125 | Searching by meaning uses embeddings, which are compute, so it is for |
| 126 | workspaces on the [g1t plan](/guides/usage-and-billing/#the-g1t-plan) and |
| 127 | the [trial](/guides/usage-and-billing/#the-trial). Every other workspace gets the catalog, |
| 128 | memory and search by matching words, with nothing to set up; the Context |
| 129 | page says which it has. If g1t cannot reach its billing service, search |
| 130 | matches words until it can. |
| 131 | |
| 132 | ### Who sees what |
| 133 | |
| 134 | What you find follows what you can read, project by project: |
| 135 | |
| 136 | - Search never reads another workspace's rows. |
| 137 | - Owners, members while the workspace's |
| 138 | [base permission](/guides/access-and-roles/#the-base-permission) is Read |
| 139 | or higher, and the workspace's own agents find everything in it. |
| 140 | - A member whose base permission is **None** finds the public projects and |
| 141 | the private ones whose repositories they were given a role on, and |
| 142 | nothing of the others: the counts on the Context page, the catalog, |
| 143 | search and scorecards leave them out. |
| 144 | - An [outside collaborator](/guides/access-and-roles/#outside-collaborators) |
| 145 | finds the projects shared with them, and anyone else the public ones: |
| 146 | their catalog entries, docs, issues and pull requests. |
| 147 | - Workspace memory is for members only. A project's memory is for members |
| 148 | who can read the project; no one outside the workspace finds memory in |
| 149 | search. |
| 150 | - A project made private is hidden from everyone who cannot read it at |
| 151 | once, even before it is searched again. |
| 152 | |
| 153 | ## Scorecards |
| 154 | |
| 155 | Each project is checked against a few rules: |
| 156 | |
| 157 | | Rule | Passes when | |
| 158 | | --- | --- | |
| 159 | | **Has an owner** | `.g1t/project.yml` or `CODEOWNERS` names one, or a member wrote most of it | |
| 160 | | **Has a README** | A README sits at the project's root | |
| 161 | | **Has an AGENTS.md** | An `AGENTS.md` (or `CLAUDE.md`) tells agents how to work here | |
| 162 | | **Tests run in checks** | A workflow in `.g1t/workflows` or `.github/workflows` runs tests | |
| 163 | | **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 | |
| 164 | | **No open secret findings** | [Security](/guides/security/) has no open secret findings for it | |
| 165 | |
| 166 | A failing rule has **Fix with an agent**: g1t opens an issue saying what to |
| 167 | do, with an acceptance check where one can be written (such as |
| 168 | `test -f AGENTS.md`), and puts g1t's agent on it. |
| 169 | |
| 170 | ## Agents start with context |
| 171 | |
| 172 | Every g1t agent run is given a **Context** section, after the project's |
| 173 | memory, within about 4,000 characters: |
| 174 | |
| 175 | - the project's stack, test commands, owners, docs, and its environments |
| 176 | with their addresses; |
| 177 | - the projects it uses, with their live addresses and the variables that |
| 178 | carry them, and the projects that use it; |
| 179 | - the kept memories closest to the task, beyond the pinned ones every run |
| 180 | already has; |
| 181 | - the latest decisions from merged pull requests. |
| 182 | |
| 183 | Each line says where it came from (`[source: catalog]`, |
| 184 | `[source: AGENTS.md]`, `[source: review on #12]`). Agents are told it is |
| 185 | reference material: where it disagrees with the code, the code wins. |
| 186 | |
| 187 | The section holds only what the person the run acts for can read. A run |
| 188 | for an outside collaborator is told the project's own memory, never the |
| 189 | workspace's, and names only the projects around it that they can read. |
| 190 | |
| 191 | ## Building it for a workspace |
| 192 | |
| 193 | The first time anyone opens a workspace's Context page, g1t builds its hub: |
| 194 | the catalog for every project (up to 50), memory candidates from their |
| 195 | docs, manifests and last 20 merged pull requests with their reviews, and |
| 196 | the search index for docs, recent issues and pull requests, and kept |
| 197 | memory. **Rebuild** does it again, reading every file afresh. |
| 198 | |
| 199 | Putting text in the search index uses Workers AI and is counted per |
| 200 | workspace and month. Before each batch is embedded, g1t reserves what it |
| 201 | may cost with billing, and settles what it really cost afterwards; a |
| 202 | workspace billing refuses (no plan or trial, its spend limit reached, |
| 203 | compute paused) keeps text search, and its new text is not embedded. A |
| 204 | workspace that passes 20 million tokens in a month keeps text search too, |
| 205 | and new text waits for the next month's index. |
| 206 | |
| 207 | ## MCP tools |
| 208 | |
| 209 | | Tool | Takes | Does | |
| 210 | | --- | --- | --- | |
| 211 | | `search_context` | `query`, and `workspace` or `repo`; optional `project`, `kinds`, `limit` | One search across the catalog, docs, issues, pull requests and memory, as [Search](#search) | |
| 212 | | `get_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 | |
| 213 | |
| 214 | g1t's own agents have both. Over REST: |
| 215 | |
| 216 | ```sh |
| 217 | curl "https://api.g1t.sh/workspaces/acme/context/search?q=how+do+we+deploy+the+api" \ |
| 218 | -H "Authorization: Bearer $G1T_TOKEN" |
| 219 | |
| 220 | curl "https://api.g1t.sh/workspaces/acme/context/project/web" \ |
| 221 | -H "Authorization: Bearer $G1T_TOKEN" |
| 222 | ``` |
| 223 | |
| 224 | See [Search the context hub](/reference/api/context/search-context/) and |
| 225 | [Get a catalog entry](/reference/api/context/get-entity/). |