This guide shows how to give an agent persistent memory — the ability to
store facts, decisions, and context between invocations — using
mem0 as an external REST API that the
agent calls via curl from its bash tool.
- A running ainsel platform (operators, hub, frontend)
- The
bashshell tool available on the agent image - A mem0 REST API server reachable from the cluster (see below)
You need a mem0 instance with its REST API accessible from inside the Kubernetes cluster. There are several options:
The simplest option — sign up at
mem0.ai, create a project, and note your API key.
The base URL is https://api.mem0.ai.
Run the mem0 Python package as a REST API server. Install mem0 and launch the built-in OpenAI-compatible server:
pip install mem0ai
# mem0 ships a REST API server
mem0 runThis starts a FastAPI server (default port 8080) with endpoints under
/memories. Point it at a vector store (Qdrant, pgvector, etc.) and an
LLM provider via the
mem0 configuration.
Deploy it as a Kubernetes Deployment + Service in your cluster, or run it outside the cluster as long as agents can reach it.
Any service that implements the mem0 REST API contract works. The endpoints ainsel agents in this documentation will call are:
| Method | Path | Body / Query | Purpose |
|---|---|---|---|
POST |
/memories |
messages, user_id, metadata |
Store a memory |
GET |
/memories |
?user_id=X&limit=N |
List memories |
POST |
/search |
query, user_id, top_k |
Semantic search |
DELETE |
/memories/{id} |
— | Delete a memory |
# From inside the cluster
kubectl run curl-test --image=curlimages/curl --rm -it --restart=Never -- \
curl -s http://<your-mem0-host>:8080/memories?user_id=test
# Should return a JSON array (empty if no memories yet)The agent needs to know how to talk to mem0. That knowledge lives in a
skill — a markdown document the agent reads as instructions. The
skill below tells it where mem0 is, how to authenticate, and the exact
curl calls for storing, searching, listing, and deleting memories.
Create a skill named memory-management with the content below. How you
create it is up to you — the frontend Skills page, the hub Skills
API, or any tooling that writes to the hub. Those mechanisms are
documented in the Administrator Guide and the
API Reference; this guide only covers what the
skill should contain.
# Memory Management
You have persistent memory backed by a mem0 REST API. Use the `bash`
tool with `curl` to store and retrieve memories.
## Environment
- `$MEM0_API_URL` — base URL of the mem0 API
(e.g. `http://mem0.ainsel-dev.svc.cluster.local:8080`). No trailing
slash.
- `$MEM0_API_KEY` — (optional) bearer token, if the API requires authentication.
May be empty.
- `$AGENT_NAME` — your agent name (e.g. `code-reviewer`). Use it as
`user_id` so memories are scoped to you.
## Authentication
If `$MEM0_API_KEY` is set, pass it as a bearer token:
```bash
curl -s -H "Authorization: Bearer $MEM0_API_KEY" ...
```
If it is empty, omit the header.
## API Reference
### Store a memory
```bash
curl -s -X POST "$MEM0_API_URL/memories" \
-H "Content-Type: application/json" \
${MEM0_API_KEY:+-H "Authorization: Bearer $MEM0_API_KEY"} \
-d "{\"messages\": [{\"role\": \"user\", \"content\": \"The project uses Go 1.24 and k3s for development.\"}], \"user_id\": \"$AGENT_NAME\"}"
```
The `content` string is what mem0 extracts facts from. The LLM
distills the text into concise memory entries. The response contains
the created memory objects with their IDs.
### Search memories
```bash
curl -s -X POST "$MEM0_API_URL/search" \
-H "Content-Type: application/json" \
${MEM0_API_KEY:+-H "Authorization: Bearer $MEM0_API_KEY"} \
-d "{\"query\": \"what Go version does the project use\", \"user_id\": \"$AGENT_NAME\", \"top_k\": 5}"
```
Returns the top matching memories with relevance scores.
### List all memories
```bash
curl -s "$MEM0_API_URL/memories?user_id=$AGENT_NAME&limit=50"
```
Returns all stored memories for this agent. Use `limit` to control
page size.
### Delete a memory
```bash
curl -s -X DELETE "$MEM0_API_URL/memories/<memory_id>"
```
## When to use memory
- **At the start of a task**: Search for relevant context ("what do I
know about this repo?").
- **During work**: Store important decisions ("I chose approach X over
Y because Z").
- **At the end**: Store a summary of what was done and what was
learned.
- **When you learn a fact**: Store it so future invocations do not
have to rediscover it.
## Rules
- Always include `user_id` in every call. Without it, the API may
return an empty list or error.
- Use semantic search (`/search`) rather than listing all memories
when you need something specific.
- Keep memory content concise — mem0 extracts facts, so write
naturally, not as raw JSON.
- Do not store sensitive data (tokens, passwords, secrets) in
memories.
- Do not delete memories unless they are factually wrong. Prefer
adding a corrective memory.
## Example workflow
```bash
# 1. Recall context at the start
curl -s -X POST "$MEM0_API_URL/search" \
-H "Content-Type: application/json" \
-d "{\"query\": \"previous work on the API\", \"user_id\": \"$AGENT_NAME\", \"top_k\": 5}"
# 2. Do your task (read code, write code, etc.)
# 3. Store what you learned
curl -s -X POST "$MEM0_API_URL/memories" \
-H "Content-Type: application/json" \
-d "{\"messages\": [{\"role\": \"user\", \"content\": \"Refactored auth middleware to use OIDC. The old session-based auth was removed in commit abc123. Tests are in auth_oidc_test.go.\"}], \"user_id\": \"$AGENT_NAME\"}"
```Remember the skill id memory-management — you'll enable it in Step 3.
An agent image needs three things for its pods to use memory: the
bash tool (to run curl), the MEM0_API_URL env var (to find
mem0), and the memory-management skill enabled (so the SKILL.md is
mounted into the pod). The steps below assume the frontend Agent
Images page; you can equally edit the image through the hub API or a
CRD — see the Administrator Guide and the
CRD Reference.
- Open the agent image you want to add memory to, or create a new one.
- Under Tools, enable the bash (shell) tool.
- Under Environment, add:
MEM0_API_URL— the URL of your mem0 instance, e.g.http://mem0.ainsel-dev.svc.cluster.local:8080.MEM0_API_KEY(optional) — only if your mem0 instance requires authentication. Mark it as a secret.
- Under Skills, enable memory-management.
- Save.
The hub writes the skill into the shared skills store and the agent
operator mounts it into the pod; the env vars are injected from the
image spec. Within roughly a minute, new agent pods will have the
skill available at
/home/agent/.pi/agent/skills/memory-management/SKILL.md and
$MEM0_API_URL in their environment.
Point an agent at the memory-enabled image and, in its persona, tell it to actually use memory — an agent won't reach for a skill it doesn't know it should use. The steps below assume the frontend Agents page; the same result can be achieved through the hub API or a CRD (see the Administrator Guide and CRD Reference).
-
Open the agent you want to give memory, or create a new one.
-
Set Image to the agent image you configured in Step 3.
-
Set the Persona so the agent knows to use memory. Add lines like:
You have persistent memory. At the start of each task, search your memories for relevant context. At the end, store what you learned. Use the memory-management skill for the exact API calls. -
Save.
Tune the persona lines to your agent's voice — the only requirement is that they direct the agent to search and store memories through the skill.
Verify memory end-to-end through the agent's chat — no kubectl or
curl needed.
- Open a chat session with the agent.
- Tell it something worth remembering, for example: "Remember that
our production cluster is named
prod-us-eastand runs k3s 1.31." The agent should call the memory skill and store the fact. - Start a new turn (or a new chat session) and ask something that relies on it, for example: "What is the name of our production cluster?"
- The agent should search its memories and answer
prod-us-eastwithout you repeating it.
If it cannot recall, check that the persona (Step 4) actually tells the
agent to use memory, and that the skill is enabled and MEM0_API_URL
is set on the image (Step 3). The Troubleshooting
section has the deeper diagnostics.
┌──────────────────────────────────────────────────────┐
│ Agent Pod │
│ │
│ ┌─────────────┐ ┌──────────────────────────┐ │
│ │ Pi Runtime │ │ skills ConfigMap (mount) │ │
│ │ │ │ │ │
│ │ reads SKILL │←───│ memory-management/ │ │
│ │ .md │ │ SKILL.md │ │
│ │ │ └──────────────────────────┘ │
│ │ calls bash │ │
│ │ tool │ ┌──────────────────────────┐ │
│ │ │ │ env: │ │
│ └──────┬───────┘ │ MEM0_API_URL=… │ │
│ │ │ MEM0_API_KEY=… (opt.) │ │
│ ▼ │ AGENT_NAME=… │ │
│ ┌─────────────┐ └──────────────────────────┘ │
│ │ bash / curl │ │
│ └──────┬───────┘ │
└─────────┼─────────────────────────────────────────────┘
│
│ HTTP
▼
┌──────────────────┐ ┌──────────────────┐
│ mem0 REST API │────→│ Vector store │
│ (any provider) │ │ (Qdrant, │
│ │ │ pgvector, …) │
│ POST /memories │ │ │
│ GET /memories │ │ scoped by │
│ POST /search │ │ user_id = │
│ DEL /memories/:id│ │ agent name │
└──────────────────┘ └──────────────────┘
- The hub stores the skill in the database and renders it to the
skillsConfigMap. - The agent operator mounts the ConfigMap into the pod and injects the
MEM0_API_URL(and optionallyMEM0_API_KEY) env vars from the AgentImage spec. - The Pi runtime discovers the SKILL.md and uses it as instructions.
- When the agent needs to store or recall a memory, it calls
bashwithcurlto hit the mem0 REST API directly. - mem0 stores and retrieves vectors in its configured vector store,
scoped by
user_id(set to the agent's name).
- Check that the skill ID in
enabledSkillsmatches the skill'sid. - Check that the skill was created:
curl -s ${HUB_URL}/api/v1/skills/memory-management - Check the pod has the file:
kubectl exec deployment/<agent> -- ls /home/agent/.pi/agent/skills/ - Make sure the persona mentions memory — the agent won't use a skill it doesn't know it should use.
- Check the env var:
kubectl exec deployment/<agent> -- printenv MEM0_API_URL - Check the mem0 server is reachable from inside the cluster:
kubectl run curl-test --image=curlimages/curl --rm -it --restart=Never -- curl -sv http://<your-mem0-host>:8080/memories - If using mem0 Cloud, verify the API key is set and the URL is correct.
- Make sure
user_idis included in the API call. Without it, mem0 may return an empty list. - Check which user_id the agent is using:
kubectl exec deployment/<agent> -- printenv AGENT_NAME - Query with the right user_id:
curl -s "http://<mem0-host>:8080/memories?user_id=<agent-name>"
- If using mem0 Cloud or an authenticated instance, make sure
MEM0_API_KEYis set on the AgentImage as a secret env var. - Check that the key hasn't expired.
- Administrator Guide — agent, trigger, and MCP server configuration
- CRD Reference — Agent and AgentImage spec fields
- mem0 documentation — upstream mem0 setup, configuration, and API reference