Fastest path — let your agent install it
Paste this to your coding agent. It sets the two variables, stores your first facts, verifies that a fresh session recalls them, and reports back what it changed.
Create an account, copy your ick_ key, and set your client's base URL to the
gateway. Memory, security, and caching switch on for every call. No SDK, no rewrite.
Memory is declared, not harvested — Iconia never quietly reads your prompts into storage. A system prompt is configuration, not knowledge, and mixing the two is what makes retrieval degrade.
Memory that survives a fresh session is the whole point — so teach it something, start over in a new session, and watch it remember.
Do not ask your agent whether Iconia is working. It will say no, and it will be
wrong: memory arrives inside the context it receives, so it uses the facts with no notion
of where they came from — asked directly it may hunt for a local install and report
one missing. Judge it by the headers below, and by whether a fresh session knows something
it was never told.
Proof it's real: remove the base URL and ask again in a fresh session — the model won't
know. The codeword only appears when Iconia is in the path. Prefer a zero-cost check
first? The dashboard's Verify button stores and recalls a memory with no model call.
Works in any client that reads a custom Anthropic base URL. Some IDE agents pin their own endpoint and won’t honor ANTHROPIC_BASE_URL — if yours does, reach out and we’ll help you wire it up.
Nous Research's Hermes agent talks to any OpenAI-compatible endpoint. Point it at Iconia
in ~/.hermes/config.yaml — memory turns on across every Hermes surface
(terminal, desktop, and the chat gateways).
Settings → Models → OpenAI API → enable a custom base URL.
Model calls always run on your own provider account — Iconia never pays for inference and never substitutes a key of its own. There are two ways to give Iconia your provider key:
1. Save it once in your dashboard (Settings → Your model provider). Every
request then uses it automatically — the only option for tools that hold a single key,
like Hermes or Cursor's custom provider, which only need your ick_ key.
2. Or send both keys with each request. Your Iconia key goes in its own header and buys the memory layer; your provider key travels where it always did, and your provider bills you directly.
# your Iconia key identifies the account X-Iconia-Key: ick_your_key # your provider key pays for the inference Authorization: Bearer sk-... # OpenAI-compatible x-api-key: sk-ant-... # Anthropic
Works on every route — /v1/chat/completions, /v1/messages,
/v1/models, and the transparent passthrough — in either header. A key is
only ever used with the provider it belongs to: present an OpenAI key for a Claude model
and it is passed over rather than forwarded to a certain rejection.
Send only your
ick_ key with no provider key saved and the request is answered with a
clear 402 provider_key_required message telling you exactly where to add
it — nothing is forwarded and nothing is billed.
Rather manage memory yourself? Every store is reachable directly with your ick_
key — store, list, export, delete. Same engine the gateway uses, no SDK required.
Base URL
https://www.iconia.tech — paths below are complete, copy them as written.
| POST /api/authority/store | save one memory — { text, label?, pinned? } |
| GET /api/authority/list | list your stored memories with metadata |
| GET /api/authority/stats | how much this tenant holds, and how often it is read |
| GET /api/authority/export | full portable JSON export — your memory is yours, always |
| DELETE /api/authority/delete/{id} | remove a memory by address prefix |
| POST /api/authority/conflicts | contradictions already sitting in your store |
| POST /api/authority/judge | rule your memory in a situation — { situation } |
| POST /platform/authority/backfeed | bulk-ingest conversation history to bootstrap a store |
Authenticate with
x-api-key: ick_... (or Authorization: Bearer ick_...). Every
read and write is isolated to your tenant.
Every response carries receipts — what happened, and how fast.
| x-iconia-augmented | 1 if memory was injected, else 0 |
| x-iconia-items-injected | how many memories were added to the call |
| x-iconia-retrieval-ms | retrieval time in milliseconds |
| x-iconia-cache | hit-semantic · miss · off |
| x-iconia-cache-latency-ms | total time when served from cache |
Repeated meaning shouldn't cost full price twice. Opt in per request with
x-iconia-cache: semantic — same-meaning questions answer from cache without a
model call. Opposite meanings and different questions always miss and go to the model.
When your memories change, affected answers invalidate automatically.
The engine is disk-backed and embedding-free, built to stay fast as memory grows — no vector database, no GPU, nothing to tune.
| Retrieval | ~1 ms, flat at any store size — bounded work, never a full scan |
| Cold start | ~0.5 s to first answer at 200k memories — sleep, restart, or redeploy without a warm-up penalty |
| Storage | lossless, byte-for-byte exact — about 4× smaller than a plain store, never summarized or approximated |
| Recovery | hourly backups; a restart re-attaches to persisted memory, byte-identical — it doesn't rebuild from scratch |
| Free tier | 1,000 requests/mo + 1,000 memories free, no card; unlimited on any paid plan |
Retrieval times are warm; cold readiness is stated separately. Every memory is recovered exactly — compression is lossless.