Docs — ICONIA

Get a key, point your client

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.

          # 1 — teach it something (any session)

          system: "Our launch window is Q3. Refunds within 30 days."

          # 2 — a later session recalls it automatically

          user: "When do we launch?"

          ← "Q3."  (you never re-sent it)

Verify it works — in 2 minutes

Memory that survives a fresh session is the whole point — so teach it something, start over in a new session, and watch it remember.

          # 1 — teach it, in any session

          "Remember this: my project codeword is BANANA-ROCKET-42."

          # 2 — open a BRAND-NEW session, then ask

          "What is my project codeword?"

          ← "BANANA-ROCKET-42."  (this session 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.

Claude Code / Anthropic-style

          ANTHROPIC_BASE_URL=https://www.iconia.tech/v1

          ANTHROPIC_API_KEY=ick_your_key

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.

OpenAI-compatible

          from openai import OpenAI

          client = OpenAI(

            base_url="https://www.iconia.tech/v1",

            api_key="ick_your_key"

          )

Hermes

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).

          # ~/.hermes/config.yaml

          model:

            provider: custom

            base_url: "https://www.iconia.tech/v1"

            api_key:  "ick_your_key"

Cursor

Settings → Models → OpenAI API → enable a custom base URL.

          # Cursor → Settings → Models → OpenAI API

          Base URL:  https://www.iconia.tech/v1

          API Key:   ick_your_key

BYOK — bring your own key

Prefer to keep inference billing on your own provider account? Send both keys. 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. Iconia never spends your model budget, and never substitutes its own key for yours.

# 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 and Iconia's provider account covers the call instead — the simplest way to start, and what the quickstart above shows.

Memory API — direct

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.

Response headers

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

Semantic 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.

Storage & speed

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	200 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.

Two lines to memory.