Build with the AI

Memories

Save and manage the durable facts the AI remembers about you.

A memory is an explicitly-saved fact about you — “prefers TypeScript over JavaScript”, “timezone is CET”, “deploys on Fridays”. Unlike a conversation turn, a memory is user-global: it is not tied to any single chat, guild, or persona, and it follows you across every AI surface on your account. The /api/v1/memories endpoints let you read, create and delete these facts programmatically, the same store the AI itself writes to when it decides something is worth remembering.

How memories work

Three properties are worth internalizing before you write against this API:

• User-global, not per-conversation. Facts are stored with no channel, guild, or persona binding. A fact saved from anywhere is recalled everywhere for that owner. There is deliberately no “save this only for this thread” option — for conversation-scoped context, keep it in your chat completions messages array instead.
• Plain-text, capped and truncated. A memory is a single free-text string — there is no key/value structure. Content is trimmed of surrounding whitespace and then hard-truncated to a maximum length (500 characters by default, set by the AI_MEMORY_FACT_MAX_CHARS server config). Truncation is silent: over-length input is accepted and stored as its first N characters (re-trimmed), never rejected. Save one crisp fact per call, not a multi-paragraph summary.
• Governed by the account memory switch. If memory is turned off for the account, saving a fact is refused with 409 memory_disabled. Reading and deleting are unaffected. See Saving with memory off.

To steer how the AI reasons rather than what it knows about you, attach your own persona to a request — personas and memories are independent and compose freely.

Scopes

Each memory operation requires the matching scope on your API key:

A request missing the required scope returns 403 insufficient_scope with the needed scope echoed in error.required_scope. Grant scopes when you mint a key in the Developer console; see Scopes and Authentication.

The memory object

Every endpoint that returns a memory serializes it with exactly these fields:

Responses use the native Krallo envelope: successful bodies are wrapped as { "data": …, "meta": { "request_id": … } }. Errors are { "error": { "code", "message", … }, "meta": … }. See Errors for the full contract.

List memories

Returns your saved facts as a JSON array, newest first (by creation time, ties broken by descending id). Requires memories:read.

Query parameters

Request

curl "https://exe.krallo.com/api/v1/memories?limit=10" \
  -H "Authorization: Bearer krallo_live_..."

Response

{
  "data": [
    {
      "id": 8241,
      "content": "Prefers TypeScript and pnpm; deploys are gated behind CI.",
      "created_at": "2026-07-14T18:32:05Z"
    },
    {
      "id": 8109,
      "content": "Primary timezone is CET (Europe/Berlin).",
      "created_at": "2026-07-11T09:14:47Z"
    }
  ],
  "meta": { "request_id": "5f3a91c0-b2d4-4e16-9a58-c07d2f4b8e31" }
}

An owner who has never saved a fact receives "data": [] with a 200 status.

Save a memory

Saves a single user-global fact and returns it. Requires memories:write. Responds 201 Created on success.

Body parameters

Request

curl https://exe.krallo.com/api/v1/memories \
  -H "Authorization: Bearer krallo_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "content": "Prefers TypeScript and pnpm; deploys are gated behind CI." }'

Response

{
  "data": {
    "id": 8241,
    "content": "Prefers TypeScript and pnpm; deploys are gated behind CI.",
    "created_at": "2026-07-14T18:32:05Z"
  },
  "meta": { "request_id": "9c1e77aa-04f3-4b8d-a25c-6e19d0b74f82" }
}

Saving with memory off

If memory is disabled for the account, a save is refused with 409 memory_disabled and nothing is stored. This is checked before the call is billed, and re-checked at write time to close the race where the switch is toggled off mid-request:

{
  "error": {
    "code": "memory_disabled",
    "message": "Memory is disabled for this account. Enable it before saving facts."
  },
  "meta": { "request_id": "2b40de19-f7a6-4c53-8d90-1e4b7a2c5f68" }
}

Re-enable memory in your account’s AI privacy settings, then retry the save.

Delete a memory

Permanently deletes one saved fact by id. Requires memories:write. Deletion is owner-scoped: you can only delete your own facts, and an id that does not exist (or belongs to another owner) returns 404 not_found rather than revealing anything about it.

Path parameters

Request

curl -X DELETE https://exe.krallo.com/api/v1/memories/8241 \
  -H "Authorization: Bearer krallo_live_..."

Response

{
  "data": { "id": 8241, "deleted": true },
  "meta": { "request_id": "e70b2c88-15d9-4a37-b642-90c1f5e8a3d4" }
}

Billing & rate limits

Every memory call — list, save, and delete — is a flat metered request. Calls first draw down your app’s free daily allowance; once that is exhausted, and if wallet billing is enabled, each call debits a small, fixed number of credit units from the owner’s balance. If the wallet cannot cover a billable call, the request returns 402 insufficient_credits with required_units and balance in the error body, and nothing is changed. Refused or errored calls are refunded and do not burn quota. See Billing for the full model.

Requests are rate-limited per key by your app’s tier. Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers (pre-auth 401/403 responses do not); exceeding the limit returns 429 with a Retry-After header. See Rate limits.

Errors

Memory endpoints can return the following errors, in addition to the standard bearer-auth failures:

Apart from the 429 — written by the shared rate limiter as a bare { "error": "rate_limited", "hint", "retryAfterSeconds" } body — all errors share the native envelope shape. For status semantics and retry guidance, see Errors. Related reading: Personas, Chat completions, and Authentication.