# Iconia setup — paste this to your coding agent

You are setting up Iconia for this project. Iconia is a memory layer that sits
between your agent and its model provider. It gives the agent persistent memory
across sessions and models, and lowers token spend on long sessions because
Iconia holds the conversation context instead of your tool resending it.

Do all of the following, then report back to the human.

---

## 1. Point the agent at Iconia

Set these two variables wherever this project configures its model provider
(`.env`, shell profile, or the agent's own config file):

```
ANTHROPIC_BASE_URL = https://www.iconia.tech/v1
ANTHROPIC_API_KEY  = ick_YOUR_KEY_HERE
```

For an OpenAI-compatible client, the equivalent is:

```
OPENAI_BASE_URL = https://www.iconia.tech/v1
OPENAI_API_KEY  = ick_YOUR_KEY_HERE
```

The key starts with `ick_`. Get it at https://www.iconia.tech — signup takes
seconds and needs no card.

Nothing else is installed. There is no SDK and no package to add.

---

## 2. Teach it what this project knows

Memory is **declared, not harvested** — Iconia never silently reads your prompts
into storage. You state a fact once and it is available in every future session.

```bash
curl -s https://www.iconia.tech/api/authority/store \
  -H "x-api-key: $ICONIA_KEY" -H "Content-Type: application/json" \
  -d '{"text":"<one fact>","label":"<category>"}'
```

Store the standing facts about this project that a new engineer would need and
that no model could guess. Good candidates — adapt to what is true here:

- how this project deploys, and what must never be used to deploy it
- where production data lives
- the conventions this team enforces in review
- environment or configuration values that must not be wrong
- decisions already made, so they are not re-litigated

Rules of thumb:
- **One fact per entry.** Short and declarative beats a paragraph.
- **Store knowledge, not instructions.** "Our production DB is at /data/app.db"
  is knowledge. "Always answer concisely" is configuration — that belongs in
  your system prompt, and Iconia deliberately does not store it.
- Add `"pinned": true` for rules that must be present on **every** request
  regardless of relevance (security rules, hard constraints). Pinned memories
  bypass the relevance budget.

---

## 3. Verify it actually works

The point is memory that survives a fresh session. Prove it:

```bash
# store a fact
curl -s https://www.iconia.tech/api/authority/store \
  -H "x-api-key: $ICONIA_KEY" -H "Content-Type: application/json" \
  -d '{"text":"This project deploys with `make ship`, never from CI.","label":"ops"}'

# ask in a BRAND-NEW session, with no system prompt and no history
curl -s https://www.iconia.tech/v1/chat/completions \
  -H "x-api-key: $ICONIA_KEY" -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","max_tokens":60,
       "messages":[{"role":"user","content":"How does this project deploy?"}]}'
```

The answer should say `make ship`. That session was never told — the answer came
from memory.

Two response headers tell you what happened on any request:

- `x-iconia-items-injected` — how many memories were used. `0` means nothing
  relevant matched, which is correct behaviour, not a failure.
- `x-iconia-retrieval-ms` — what Iconia's own lookup cost. Typically ~3ms.

---

## 4. Report back to the human

Tell them:

1. Which config file you changed, and whether the key is set from an environment
   variable rather than committed.
2. How many facts you stored, and list them so they can correct anything wrong.
3. The verification result — the exact answer the fresh session gave.
4. That savings grow with session length: short exchanges may cost slightly more
   (memory is added to a small prompt), and the gap widens the longer a session
   runs, because their client's history stops being resent.

---

## Notes for the agent

- **Never commit the `ick_` key.** Environment variable or secret store only.
- If a request returns `429`, the free tier's monthly request allowance is used
  up. The memory is safe; the human needs to choose a plan.
- If `x-iconia-items-injected` is `0` on a question you expect memory to answer,
  the stored fact probably does not share vocabulary with the question. Rephrase
  the stored fact to use the words people actually ask with.
- Iconia does not change your model, your prompts, or your tools. Point the base
  URL somewhere else and everything returns to exactly how it was.