Quickstart
Get an API key, store a memory, recall it, report an outcome and forget it — over REST, Node or Python.
This guide walks through the basic memory lifecycle: remember → recall → report → forget.
Prerequisites
You need three values:
| Value | Where it comes from |
|---|---|
| Base URL | https://memory.empecta.com for the hosted service, or the URL of your own deployment (for example http://localhost:5199 when running locally). |
| API key | Starts with amk_. Shown once when it is created. |
| Workspace ID | The GUID of the workspace (shown as a project in the console) the key belongs to. |
Get an API key
Sign in to the web console at /app/, open API Keys, and choose Create API Key. Pick the project (workspace), optionally an application, and the capabilities the key needs. The key is displayed exactly once — copy it now.
New keys can read, write, send feedback and curate by default. Deleting, sharing and promoting memories are off unless you enable them.
Install an SDK (optional)
npm install "$AGENT_MEMORY_BASE_URL/sdk/agentmemory-0.4.0.tgz"Both clients are version 0.4.0 and have no runtime dependencies. They are not on a public registry: every Agent Memory deployment serves them under /sdk/ (see Node and Python for installing from the repository instead). You can also call the REST API directly — every example below shows the equivalent curl.
Remember
Store one memory. userId is the end user the memory is about — never the agent. You do not send an agent ID: the API key decides which agent is acting.
Naming end users needs a key that may act for users
Keys are created without act for users by default, and a request that names a userId with such a key is refused with 403 policy_denied. Enable it when you create the key, or drop userId from the examples to store memories for the agent itself. See Authentication.
import { AgentMemoryClient } from 'agentmemory'
const memory = new AgentMemoryClient({
apiKey: process.env.AGENT_MEMORY_API_KEY,
baseUrl: process.env.AGENT_MEMORY_BASE_URL,
workspaceId: process.env.AGENT_MEMORY_WORKSPACE_ID,
})
const { id, operationId } = await memory.add('Alex is vegetarian', {
type: 'preference',
userId: 'alex',
runId: 'run-1',
sourceKind: 'user',
idempotencyKey: 'note-42',
})The response tells you what the write became: the memory id (if a near-duplicate already existed, this is the surviving memory and merged is true) and an operationId you can poll to see when indexing finished.
Recall
Search with a natural-language query. Keep the receiptId — it names exactly what was delivered.
const context = await memory.search('what can Alex eat?', { userId: 'alex', runId: 'run-1' })
console.log(context.workspaceEntries.map(e => e.content))
console.log(context.receiptId)Report the outcome
When you know how the run went, report it with the receipt and the same runId you recalled with. Memories that were delivered get credit for the result.
await memory.outcome({ runId: 'run-1', buildSuccess: true, receiptId: context.receiptId })Forget
Deleting needs a key with the delete capability. The result is one of deleted, pending, blocked, not_found or forbidden.
const { status } = await memory.delete(id) // 'deleted' | 'pending' | 'blocked' | ...
await memory.erasure(id) // { status: 'complete', ... }pending means the memory itself is already redacted and the copies derived from it are still being removed. blocked means other live memories derive from it — see Updating and forgetting.
Four rules to remember
- Don't send an agent ID. Your API key is bound to one or more agents and the key's default agent acts. Name an agent only when the key is bound to several; an agent the key isn't bound to is refused with
403. userIdis the person the memory is about, never the agent.- A receipt belongs to its run. Report outcomes and feedback with the receipt and the same
runIdyou recalled with. - Forget can be
pending. Check the erasure status to know when every derived copy is gone.