# Set up Augenta memory

You are a coding agent adding Augenta to the user's project. Augenta takes in what the user's agent sees and does, and returns the relevant context before each model call.

Work through the steps in order. Each step ends with a **Check**. Do not continue until it passes. If it fails, use "When a check fails" below, then tell the user what you saw.

## 0. Before you start

- Ask the user for `AUGENTA_API_KEY`. They sign up free at https://augenta.pages.dev/signup, then create a key with a Workspace selected at https://augenta.pages.dev/dashboard/keys. Their Default Workspace works. You cannot create a key yourself.
- Keep the key in the environment or the project's secret store. Never print it, log it or commit it.
- Find the one place this project calls its model. You will add one call before it and one after it.
- There is no package to install yet. Call the HTTP API from the project's own language.
- Every route is described at https://api.augenta.ai/v1/openapi.json

## 1. Check the key

```bash
curl -sS "https://api.augenta.ai/v1/engrams?limit=1" \
  -H "Authorization: AugentaKey $AUGENTA_API_KEY"
```

**Check:** 200, and the body has `"object": "list"`. `data` stays empty until the Workspace has memory.

- The scheme is `AugentaKey`. `Bearer` returns 401.
- 403 means the key has no Workspace. Ask the user to assign one to the key.
- 400 naming `workspace` means the key has more than one. Ask the user which to use. Add `&workspace=<id>` here, and `"workspace": "<id>"` to the request bodies in steps 3 and 4.

## 2. Send one message

```bash
curl -sS https://api.augenta.ai/v1/consolidate \
  -H "Authorization: AugentaKey $AUGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session": "setup-check", "messages": [{"role": "user", "content": "Production releases require owner approval."}]}'
```

**Check:** 200, and `extractedClaims.data[0].text` restates the message.

This call stores nothing. It can take several seconds.

## 3. Recall before each model call

```http
POST https://api.augenta.ai/v1/recall?mode=context&retrieval=pool
Authorization: AugentaKey $AUGENTA_API_KEY
Idempotency-Key: <a new UUID for each question>
X-Augenta-Content: content-v3
Content-Type: application/json

{"query": "<the user's message>", "origin": "auto", "budget_tokens": 1500}
```

Add the `text` of every block in `content` whose `type` is `engram` or `claim` to the model's context, before the user's message.

- Always send `X-Augenta-Content: content-v3`. Without it, recall answers in an older block format.
- `retrieval=pool` searches every claim by meaning and keyword, which suits the user's own words.
- If recall fails, call the model without it.

**Check:** 200. `noMatch: true` is expected until step 4 has run once.

## 4. Add the turn after the model call

```http
POST https://api.augenta.ai/v1/experiences?wait=30
Authorization: AugentaKey $AUGENTA_API_KEY
Content-Type: application/json

{"experiences": [{
  "src": "service",
  "sid": "<conversation id>",
  "events": [
    {"seq": 1, "ts": "<ISO 8601 time>", "kind": "msg", "role": "user", "text": "<the user's message>"},
    {"seq": 2, "ts": "<ISO 8601 time>", "kind": "msg", "role": "assistant", "text": "<the model's reply>"}
  ]
}]}
```

- Keep `sid` the same for one conversation.
- `seq` counts up across the whole conversation and never starts again. This first turn sends 1 and 2, and the next turn sends 3 and 4. Numbers already sent, with different text, are refused with 409 `conflict`.
- Send each turn once, after the reply is final.
- Remove secrets from `text` before sending.
- Send it in the background. The reply must never wait for it or fail with it.

**Check:** 200, and every item in `experiences` has `status` `processed` or `consolidated`.

## 5. Prove the loop

Run the user's agent for three turns in one conversation. In the third turn, ask about something said in the second.

**Check:** the recall from step 3 returns a `claim` block from the second turn.

## When a check fails

| Response | Means | Do |
|---|---|---|
| 401 `unauthenticated` | Wrong key, or the wrong scheme | Use `AugentaKey`, not `Bearer`. Ask the user to copy the key again. |
| 403 `forbidden` | The key has no Workspace for this request | Ask the user to assign a Workspace to the key. |
| 400 `invalid_request` | A header or field is wrong | `error.message` names it. Fix only that. |
| 402 `insufficient_balance` | The organization is out of credit | Tell the user. Do not retry. |
| 409 `conflict` | This `sid` and `seq` range was already sent with different text | Continue `seq` from the conversation's last number. |
| 406 `unsupported_content` | Recall got an unknown `X-Augenta-Content` | Send `content-v3`. |
| 429 `rate_limited` | Too many requests | Wait `Retry-After` seconds, then retry. |
| 202, `status: accepted` | Processing took longer than 30 seconds | Read `GET /v1/experiences/{id}` every few seconds until `status` is `processed`. |
| `status: failed` | Processing failed | Tell the user, with the experience `id`. |
| `noMatch: true` | Nothing is processed yet | Finish step 4, then recall again. |

Every error body is `{"error": {"code", "message", "retryable"}, "requestId"}`. Give the user the `requestId` when you report a failure.

## Tell the user

- Which files you changed, and where the two calls sit.
- The experience `id` from step 4. They can find it in the console under Experiences.
- The claim recall returned in step 5.
