Agent memory

An AI agent forgets everything between model calls unless something remembers for it. Agent memory keeps two kinds of memory for your agents, in one of your…

An AI agent forgets everything between model calls unless something remembers for it. Agent memory keeps two kinds of memory for your agents, in one of your KiviDB databases:

  • Working memory, per conversation (a session): the recent messages and a running summary of the older ones, so a long conversation fits in a prompt.
  • Long-term memory, per user (an actor): lasting facts, preferences and events, pulled out of conversations in the background and found again by meaning when they are relevant.

Everything a store remembers is kept in the database it lives in, under keys starting kividb:mem:. Nothing is stored anywhere else.

How it works

  1. After each turn, your agent adds the new messages to the session.
  2. Before the next model call, it asks for recall: the session's summary, its recent messages and the long-term memories most relevant to the user's latest message, as ready-to-use text.
  3. In the background, the store's language model reads the messages it has not read yet and keeps what is worth remembering. A session is due the extraction delay (five minutes by default) after its oldest unread message, not after it goes quiet: more messages do not push it back. The background pass runs every 30 seconds and takes the sessions that are due, so a message is usually read between the delay and the delay plus half a minute after the first unread one arrived. A session with 250 or more unread messages is read at the next pass, whatever the delay. A memory the same actor already has (by similarity, or the same text) is not kept twice.
  4. Once a session holds more messages than summarize after, the oldest are folded into its summary and only the most recent are kept as they are.

A session keeps at most 1,000 messages. With a language model, only messages extraction has read make way for new ones; if extraction falls 1,000 messages behind (its provider keeps failing, say), the oldest unread messages go, and this is never silent: the append response carries unread_dropped, the session shows messages_lost_before_extraction, and the store shows it as its last extraction error.

Actors. Long-term memories are kept per actor. Duplicates are only looked for among the same actor's memories, and recall and search only return one actor's: the actor_id you give (for recall, the session's actor if you give none). Memories kept without an actor are a scope of their own: they are only compared with, and found with, other memories without an actor. To search every actor's memories at once, as the console does, ask for "all_actors": true.

Memories have a type. Every store has semantic (a fact or preference: "The user deploys to eu-west-1") and episodic (something that happened: "The user migrated their cache on 12 October"). You can add up to three types of your own, each with a sentence describing what to extract, such as order_issue: "a problem the user had with an order, with the order number".

Models and keys

A store uses two models. Each is either hosted by KiviDB (kividb, billed per token, no API key) or called with your own API key, stored encrypted and never shown again:

Used forProviders
Language modelextracting memories and writing summariesKiviDB hosted (Amazon Nova Lite), OpenAI, Anthropic, or any HTTPS endpoint with OpenAI's /chat/completions shape
Embeddingsfinding memories by meaningKiviDB hosted (Amazon Titan Text Embeddings V2, 256, 512 or 1024 dimensions), OpenAI, or any HTTPS endpoint with OpenAI's /embeddings shape; or none, and you send vectors

Hosted models cost, per million tokens, $0.05 for embeddings and, for the language model, $0.15 read and $0.60 written. They are taken from your credit and shown on the Usage page by database. Text sent to them goes to Amazon Bedrock in AWS's us-east-1 region, whatever region your database is in; Bedrock does not store it or use it to train models. Your organization needs a month of its running databases plus $1 in credit to use them (insufficient_credits otherwise), and they are rate-limited per organization, at roughly 20 requests a second.

With your own keys, you pay your provider for what these calls use, and KiviDB adds no charge for agent memory beyond the database it lives in. With no language model, a store still keeps sessions and the memories you add yourself, but extracts and summarizes nothing. A custom endpoint must be HTTPS on a public address. Changing the embedding model or its dimensions needs a store with no memories: vectors from two models cannot be compared.

Personal data. By default, emails, phone numbers, payment card numbers, US social security numbers and IP addresses are replaced with markers such as [email] before a memory is kept. This is pattern matching: names and street addresses are not caught. Working memory keeps messages as you sent them.

In the console

The Agent memory section lists every store in your organization with the database it lives in; each database also has an Agent memory tab with its own stores. A store shows its sessions with their summaries and messages, its memories (browse, search, forget), when extraction last ran and why it failed if it did, and a place to try it. Agent memory is not available on sharded databases yet.

API

Authenticate with an API key, as for the rest of the API. {id} is the database, {store} the store's name, and {session} your own conversation id (letters, digits, ., _, :, @ and -).

Request
GET /agent-memoryevery store in the organization, with its database
GET /instances/{id}/agent-memorythis database's stores
PUT /instances/{id}/agent-memory/{store}create or change a store
GET /instances/{id}/agent-memory/{store}settings, and counts of sessions, memories and sessions waiting for extraction
DELETE /instances/{id}/agent-memory/{store}delete the store and everything it keeps
POST /instances/{id}/agent-memory/{store}/sessions/{session}/eventsadd messages: {"actor_id": "user-7", "events": [{"role": "user", "content": "..."}]}
GET /instances/{id}/agent-memory/{store}/sessionsa page of sessions, most recent first (?offset=)
GET /instances/{id}/agent-memory/{store}/sessions/{session}the summary and recent messages (?recent=50)
DELETE /instances/{id}/agent-memory/{store}/sessions/{session}forget a session's working memory
POST /instances/{id}/agent-memory/{store}/sessions/{session}/extractextract now instead of after the delay
POST /instances/{id}/agent-memory/{store}/recall{"session_id", "query"?, "actor_id"?, "limit"?}: summary, recent messages, relevant memories and a context string
POST /instances/{id}/agent-memory/{store}/memoriesadd a memory yourself: {"text", "type"?, "actor_id"?, "topics"?}
GET /instances/{id}/agent-memory/{store}/memoriesa page of every actor's memories, newest first
POST /instances/{id}/agent-memory/{store}/memories/search{"query", "mode": "semantic" | "keyword" | "hybrid", "actor_id"? or "all_actors"?, "types"?, "limit"?}
DELETE /instances/{id}/agent-memory/{store}/memories/{memory}forget one memory (?actor_id= to forget it only if it is that actor's)

Creating a store on hosted models:

curl -X PUT https://api.kividb.io/instances/$DB/agent-memory/support-agent \
  -H "Authorization: Bearer $KIVIDB_API_KEY" -H "Content-Type: application/json" \
  -d '{"llm_provider": "kividb", "embed_provider": "kividb", "dimensions": 1024}'

Or with your own OpenAI key:

curl -X PUT https://api.kividb.io/instances/$DB/agent-memory/support-agent \
  -H "Authorization: Bearer $KIVIDB_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "llm_provider": "openai", "llm_model": "gpt-4o-mini", "llm_api_key": "'"$OPENAI_API_KEY"'",
    "embed_provider": "openai", "embed_model": "text-embedding-3-small", "embed_api_key": "'"$OPENAI_API_KEY"'",
    "dimensions": 1536
  }'

A turn of a conversation, in Python:

import requests

API = f"https://api.kividb.io/instances/{DB}/agent-memory/support-agent"
H = {"Authorization": f"Bearer {KIVIDB_API_KEY}"}

def answer(session_id, user_id, user_message):
    memory = requests.post(f"{API}/recall", headers=H, json={
        "session_id": session_id, "actor_id": user_id, "query": user_message,
    }).json()
    reply = call_your_model(system=memory["context"], user=user_message)
    requests.post(f"{API}/sessions/{session_id}/events", headers=H, json={
        "actor_id": user_id,
        "events": [{"role": "user", "content": user_message}, {"role": "assistant", "content": reply}],
    })
    return reply

Settings

SettingDefault
extraction_delay_seconds300how long after a session's oldest unread message it is due for extraction (30 to 3600); the background pass runs every 30 seconds
summarize_after40summarize once a session holds more messages than this
keep_recent12messages kept as they are when summarizing
session_ttl_seconds3600a session is forgotten this long after its last message
memory_ttl_seconds31536000a long-term memory is kept this long (one year)
dedupe_threshold0.92a new memory at least this similar to one the actor has is a duplicate
custom_typesnoneup to three {"name", "description"}
redact_piitruereplace common personal identifiers before keeping a memory

From an AI assistant

The KiviDB MCP server has list_memory_stores, memory_add_messages, memory_recall, memory_search, memory_add and memory_forget, so an assistant can use a store you have made in the console.