The memory API for agents that need to remember

What a memory API does that a vector database does not

A vector database stores embeddings and returns similar chunks. A memory API stores what an agent learned about a person, an account, a project or a decision, then returns the small set of facts that should influence the next response.

That difference matters in production. Documents do not change when a customer upgrades a plan. A memory does. A document does not become wrong when a decision is reversed. A memory should. A document is usually shared by everyone. A memory has an owner, a scope and a retention policy.

AI Memory handles the write path and the read path. On write, it extracts facts, preferences, decisions, constraints and episodes, merges them with what is already known, and compresses the episode down to its signal. On read, it scores semantic similarity, recency, memory kind and the entity graph together, then reranks the result against a token budget.

The five operations behind the API

Most integrations only need add and search. The other operations exist because memory has to be correctable, portable and removable.

The public examples on the AI Memory home page use POST https://api.ai-memory.lol/v1/memories and POST https://api.ai-memory.lol/v1/search. The Python and TypeScript SDKs wrap the same contract.

Scopes are enforced at query time

A memory layer is only safe if one user cannot retrieve another user’s context. AI Memory carries four scopes on every write and filters on them at read time.

Python: add an event, then search it back

The write is deliberately boring. Send the messages you already have, attach the ids you already use, and let the extraction pass decide what deserves to persist.

from aimemory import Memory

memory = Memory(api_key="aim_live_...")

memory.add(
    messages=[{"role": "user", "content": "we moved to the Scale plan"}],
    user_id="dana",
    agent_id="support-bot",
    metadata={"tenant": "northwind"},
)

context = memory.search(
    "how does Northwind like to be contacted?",
    user_id="dana",
    agent_id="support-bot",
    limit=5,
)

TypeScript: the same contract in the browser-adjacent stack

The TypeScript SDK is useful when the agent runs in a Next.js app, an edge function or a Node service. Keep the API key on the server and pass only the ids your application already trusts.

import { Memory } from '@aimemory/sdk';

const memory = new Memory({ apiKey: process.env.AI_MEMORY_KEY });

await memory.add({
  messages: [{ role: 'user', content: 'the audit starts in March' }],
  userId: 'dana',
  metadata: { tenant: 'northwind' },
});

const context = await memory.search({
  query: 'what constrains the migration?',
  userId: 'dana',
  rerank: true,
});

Compression is part of the contract

A memory API that only appends is a transcript with a search box. The useful version has to collapse near-duplicates, resolve contradictions and keep the numbers, decisions and constraints that change behavior.

AI Memory keeps superseded facts as versions instead of silently overwriting them, and it preserves verbatim quotes when the exact wording carries the meaning. The result is a smaller prompt, a lower token bill and fewer cases where the model repeats an old truth.

• Deduplicate and merge updates instead of appending every message.
• Resolve contradictions to the newest truth while keeping an audit trail.
• Apply a per-request token budget so retrieval cannot quietly grow without limit.
• Export the graph as JSON when you need a copy outside the service.

What to check before you adopt any memory API

Memory is more sensitive than a document index because it contains conclusions about people and accounts. Ask hard questions before you send production data.

• Can the provider filter by user, agent, session and tenant at read time?
• Can you delete one memory, one user or one tenant without breaking the graph?
• Can you see the source, scope and timestamp behind a memory?
• Can you export the graph and replay it somewhere else?
• Can you self-host or bring your own database if your data residency rules require it?
• Does the provider use your content for model training? The answer should be no.