| 1 | --- |
| 2 | title: Agents, sessions and memory |
| 3 | description: Watch every agent at work, stop or steer a run, read past sessions, and curate what agents remember about a project and across a workspace. |
| 4 | --- |
| 5 | |
| 6 | Every project has an **Agents** section, beside its pull requests: who is |
| 7 | working on it right now, what each agent did before, and what agents have |
| 8 | learned about the project. The workspace has the same across all of its |
| 9 | projects: the **Agent fleet** and **Workspace memory**. |
| 10 | |
| 11 | | You want to | Go to | |
| 12 | | --- | --- | |
| 13 | | See what agents are doing on a project now | **Agents → At work** | |
| 14 | | Stop a run, or tell it something | **Stop** or **Message** on the run | |
| 15 | | See how a pull request was made | **Agents → Sessions**, or the pull request's Agent panel | |
| 16 | | Teach every agent something about this code | **Agents → Memory** | |
| 17 | | Teach every agent something true in every project | **Memory**, in the workspace's sidebar | |
| 18 | | Review what agents, reviews and docs taught | **Agents → Memory**, or **Context → Memory** for the workspace | |
| 19 | | See every agent across the workspace, and its cost | **Agent fleet**, in the workspace's sidebar | |
| 20 | |
| 21 | ## Runs |
| 22 | |
| 23 | A **run** is one sandbox g1t starts. Each g1t agent run does one kind of |
| 24 | work on one pull request: |
| 25 | |
| 26 | | Kind | What the agent does | |
| 27 | | --- | --- | |
| 28 | | `implement` | Makes the change an issue asks for, in a new pull request. | |
| 29 | | `revise` | Addresses failed checks or a review on its own pull request. | |
| 30 | | `review` | Reviews a pull request and gives a verdict. | |
| 31 | | `answer` | Answers another agent's question or handoff. | |
| 32 | | `update` | Merges in the branch its pull request will land on. | |
| 33 | | `plan` | Turns an outcome into a plan of issues. | |
| 34 | |
| 35 | Sandboxes that run commands rather than a model show too, as `checks` and |
| 36 | `queue`, so the list is everything g1t is running for the project. |
| 37 | |
| 38 | Each run records: |
| 39 | |
| 40 | - the agent (`g1t-agent`) and, for members, the model it runs on; |
| 41 | - its pull request, or for a plan, the outcome; |
| 42 | - its status: starting, running, done, failed or stopped; |
| 43 | - its **current step**, one line such as `Edited src/auth.ts` or |
| 44 | `Ran npm test`, and the latest 200 steps; |
| 45 | - how long it has run, and for members, what it has cost so far. |
| 46 | |
| 47 | The cost is what the agent harness reports as the run goes. What the |
| 48 | workspace is charged is on its [Usage](/guides/usage-and-billing/) page. |
| 49 | |
| 50 | ### At work |
| 51 | |
| 52 | **Agents → At work** lists the project's runs: the ones under way first, |
| 53 | updating every few seconds while any is running, then the ones that |
| 54 | recently finished. Choose a run's step count for its step-by-step page, |
| 55 | or **Session** for the full record of its pull request. |
| 56 | |
| 57 | The pull request page shows the same for its own agent, near the top: who |
| 58 | is working on it, its stage, what it is doing this minute, for how long, |
| 59 | and what it has cost. The pull request list marks each pull request an |
| 60 | agent is working on with what it is doing, such as **Revising**. An issue |
| 61 | shows which agent picked it up and its current step. |
| 62 | |
| 63 | ### Stop a run |
| 64 | |
| 65 | Anyone with the Write [role](/guides/access-and-roles/) or higher on the repository can stop a |
| 66 | run with **Stop**: |
| 67 | |
| 68 | - its sandbox shuts down at once, and nothing more is pushed; |
| 69 | - what it already pushed stays on the pull request; |
| 70 | - g1t stops seeing that pull request through, and marks it **Needs you**, |
| 71 | so it does not start the same work again on its own. |
| 72 | |
| 73 | To start again, ask for what you want on the pull request: a review, a |
| 74 | catch-up, or changes in a review, which sends the agent back to revise. |
| 75 | |
| 76 | ### Message a run |
| 77 | |
| 78 | **Message** sends the agent on the run's pull request a message, the same |
| 79 | as **Message the agent** on the pull request. When it arrives depends on |
| 80 | the run: |
| 81 | |
| 82 | - **Implement, revise and answer runs** read messages while they work, at |
| 83 | their next step between tool calls. |
| 84 | - **Review, update and plan runs** do not. The message waits on the pull |
| 85 | request and is given to the agent's next run there. g1t says so when you |
| 86 | send it. |
| 87 | |
| 88 | See [talk to agents](/guides/talking-to-agents/) for what an agent does |
| 89 | with a message. |
| 90 | |
| 91 | ## Sessions |
| 92 | |
| 93 | **Agents → Sessions** lists every pull request with a recorded session, |
| 94 | most recently active first, with its first prompt, how many entries and |
| 95 | tool calls it has, the kinds of runs g1t made for it, and their cost. |
| 96 | Filter by kind of run, by outcome (in progress, ready for review, merged |
| 97 | or closed), or by pull request number. |
| 98 | |
| 99 | A session's page shows its runs, each with its steps, then the session |
| 100 | itself: prompts, what the agent said, the tools it ran and, with **Show |
| 101 | tool results**, what they returned. Sessions from your own agents, recorded |
| 102 | with the `pull_request` tool's `record_session` action, are listed the |
| 103 | same way. See |
| 104 | [sessions and why-blame](/guides/why-blame/) for what a session records. |
| 105 | |
| 106 | A session is as visible as its project. The model and the cost of a run |
| 107 | are shown only to members of the workspace: an |
| 108 | [outside collaborator](/guides/access-and-roles/#outside-collaborators) |
| 109 | sees what their agents did, not what model ran or what it cost. |
| 110 | |
| 111 | ## Memory |
| 112 | |
| 113 | Memory is what agents and people have learned that the next agent should |
| 114 | know. It has two levels. |
| 115 | |
| 116 | **Project memory** is about one project's code: |
| 117 | |
| 118 | - how to build and test it: "Run `npm run db:reset` before the integration |
| 119 | tests"; |
| 120 | - its conventions: "Components live in `src/components/ui`; import from |
| 121 | there, not from radix-ui"; |
| 122 | - decisions and why: "We keep the v1 webhook payload; two customers still |
| 123 | parse it"; |
| 124 | - its traps: "The date tests fail unless `TZ=UTC`". |
| 125 | |
| 126 | **Workspace memory** is true across all of the workspace's projects: |
| 127 | |
| 128 | - "We use pnpm everywhere, never npm or yarn"; |
| 129 | - "Staging lives at staging.example.com and deploys from main"; |
| 130 | - "Every service logs JSON to stdout"; |
| 131 | - "Ask Ana before changing anything under billing". |
| 132 | |
| 133 | Put something in workspace memory only when it holds in every project. When |
| 134 | it is true of one codebase, it belongs to that project. |
| 135 | |
| 136 | ### How agents use it |
| 137 | |
| 138 | Every g1t agent run is given memory when it starts: the workspace's and |
| 139 | the project's, each labelled, pinned memories first, then the ones used |
| 140 | most recently, up to about 6,000 characters. Agents are told to treat it as |
| 141 | notes from colleagues: usually right, sometimes out of date, and where it |
| 142 | disagrees with the code, the code wins. |
| 143 | |
| 144 | Agents add to it as they work with the `memory` tool's `remember` action, |
| 145 | choosing the scope themselves: `project` for this codebase, `workspace` for what holds across |
| 146 | projects. Each memory records where it came from: the person who wrote it, |
| 147 | or the agent's run and the pull request it was working on, linked from the |
| 148 | memory. |
| 149 | |
| 150 | Memory also fills itself. At the end of every run that changes code, the |
| 151 | agent is asked what it learned; a person's correction in a review, a merged |
| 152 | pull request's decision, and what a project's `AGENTS.md`, README and |
| 153 | manifests say are captured too. These arrive as **candidates**, which no |
| 154 | agent is given until they are kept: at once when two independent sources |
| 155 | say the same thing or a project's `AGENTS.md` or manifests state it, |
| 156 | otherwise by a member in the **Review** list on **Agents → Memory** or the |
| 157 | Review queue on the workspace's [Context](/guides/context-hub/) page. See |
| 158 | [memory that fills itself](/guides/context-hub/#memory-that-fills-itself). |
| 159 | |
| 160 | Every run is also given a **Context** section from the |
| 161 | [context hub](/guides/context-hub/#agents-start-with-context): the |
| 162 | project's stack, owners, environments and the projects it uses with their |
| 163 | live addresses, the kept memories closest to its task, and recent |
| 164 | decisions. |
| 165 | |
| 166 | Your own agents can use memory too, through the [`memory` tool](/reference/mcp/#memory) |
| 167 | and its `remember` and `recall` actions, or the API: |
| 168 | |
| 169 | ```sh |
| 170 | curl -X POST https://api.g1t.sh/repos/acme/web/memory \ |
| 171 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 172 | -H "Content-Type: application/json" \ |
| 173 | -d '{"text": "The date tests fail unless TZ=UTC.", "kind": "gotcha"}' |
| 174 | |
| 175 | curl "https://api.g1t.sh/repos/acme/web/memory?q=tests" \ |
| 176 | -H "Authorization: Bearer $G1T_TOKEN" |
| 177 | ``` |
| 178 | |
| 179 | Each memory `recall` returns counts as used, which keeps it near the front |
| 180 | of what agents are given. |
| 181 | |
| 182 | ### Curate it |
| 183 | |
| 184 | Memory is only as good as it is true. On a project's **Agents → Memory**, |
| 185 | anyone with the Write [role](/guides/access-and-roles/) or higher on its |
| 186 | repository can, and on **Workspace memory**, members can: |
| 187 | |
| 188 | - **add** a memory, with its kind: fact, convention, decision or gotcha; |
| 189 | - **pin** one, so every agent gets it first, whatever the budget; |
| 190 | - **edit** one that has drifted, or change its kind; |
| 191 | - **forget** one that no longer holds; |
| 192 | - **keep**, **edit** or **dismiss** a candidate waiting for review. A |
| 193 | dismissed candidate is never suggested again in the same words. |
| 194 | |
| 195 | Each shows who added it, when, and when it was last given to an agent. A |
| 196 | memory that has not been given to an agent for a long time is a good one to |
| 197 | check. Saving the same text twice keeps one memory. A project or a |
| 198 | workspace keeps up to 500. |
| 199 | |
| 200 | For members, the project's Memory page also lists the workspace's memory, |
| 201 | read-only, since agents there get both; manage it from **Workspace |
| 202 | memory**. |
| 203 | |
| 204 | ### Who can see it |
| 205 | |
| 206 | | Memory | Who reads it | Who changes it | |
| 207 | | --- | --- | --- | |
| 208 | | A project's | Anyone who can read its repository: for a public one, anyone | Write or higher on the repository | |
| 209 | | The workspace's | Members of the workspace | Members of the workspace | |
| 210 | | Candidates waiting for review | Members of the workspace | Members of the workspace | |
| 211 | |
| 212 | Since a public project's memory can be read by anyone, keep what the |
| 213 | workspace keeps to itself in workspace memory, or in a private project. |
| 214 | |
| 215 | An agent run is given only the memory the person it acts for can read: a |
| 216 | run for an outside collaborator gets the project's memory, never the |
| 217 | workspace's. |
| 218 | |
| 219 | ### Never a secret |
| 220 | |
| 221 | Every agent in the workspace reads memory, so it never holds a secret. g1t |
| 222 | refuses text that looks like one: a key or token with a known prefix (such |
| 223 | as `sk-`, `ghp_`, `AKIA` or `g1t_`), a private key, a URL with a password |
| 224 | in it, `password=` or `token:` followed by a value, or a long random string. |
| 225 | Say where the secret lives instead: "The deploy key is the `DEPLOY_KEY` |
| 226 | secret". Agents read secrets from [secrets and variables](/guides/secrets-and-variables/), |
| 227 | never from memory. |