Agent Memory REST API: Store and Search in Minutes

The agent memory rest api is the plugin-free path to shared project memory: five mem0-like endpoints you can call from curl, any language, or a CI job. This walkthrough stores, recalls, maintains, and versions those calls so you can verify each step.

Agent memory rest api endpoints and planes

The agent memory rest api is the plugin-free path to shared project memory. You call five mem0-like endpoints over HTTPS, so any language, script, or CI job can store and recall facts without a coding-agent plugin.

The operations are add, search, list, update, and delete. They are Audaxic's own shapes, so verify each request body against the docs rather than assuming field-for-field compatibility with another provider. If you are coming from mem0, check endpoint shapes when coming from mem0 before you port client code. The data plane lives at https://api.memory.audaxic.com, while project and key management lives on the management plane at https://memory-api.audaxic.com.

Use the REST path when you work outside plugin editors, automate memory writes from CI, or build a wrapper in a language without a plugin. Plugins save facts as you work and inject recall at session start; the REST API gives you the same per-project store with explicit calls.

Data stays isolated per organization with namespace-scoped vector search. Audaxic never trains on customer data, and servers are located in the US and EU. That scoping is why the setup below uses one project per repo, as explained in Why Your Coding Agent Forgets Conventions.

Step 1: Create the project and grab an ak_ key

Sign in to the dashboard and create one project for the repo you are testing. One project per repo keeps recall precise: the agent retrieves that codebase's facts instead of blending context across repos. Name the project after the repo so the mapping stays obvious.

Generate an ak_... project key for that project. Data-plane calls use this project key as a Bearer token. Management-plane calls use a different credential: an at_... workspace auth token with scopes such as projects:read, projects:write, keys:read, and keys:write. The authentication docs describe which credential each plane expects; mixing them up is a common first-run failure.

Store the key as a secret, never in source control. Export it for the shell session and keep a second variable for the base URL so every snippet below works with copy and paste:

export MEMORY_BASE_URL="https://api.memory.audaxic.com"
export MEMORY_API_KEY="ak_..."
export MEMORY_API_VERSION="2026-09-25"

Verify the credential before you store anything. List the first page of the new project; it should succeed and return an empty set. If it does, your base URL, key, and headers are correct.

curl -s "$MEMORY_BASE_URL/list?limit=10&offset=0" \
  -H "Authorization: Bearer $MEMORY_API_KEY" \
  -H "X-Api-Version: $MEMORY_API_VERSION"

Give each machine or agent its own key for the same project instead of sharing one key. If a runner leaks a key, you rotate only that key.

Step 2: Store facts with POST /add

POST /add extracts memories from a message batch you send. You pass user and assistant messages in; discrete facts come out as stored memories. The add endpoint reference documents the request shape your client must send.

Store one concrete fact first, using a distinctive phrase you will search for later. This canary pattern — a unique string such as rest-quickstart canary — makes verification immediate because nothing else can match it:

curl -s -X POST "$MEMORY_BASE_URL/add" \
  -H "Authorization: Bearer $MEMORY_API_KEY" \
  -H "X-Api-Version: $MEMORY_API_VERSION" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "rest-quickstart canary: repo uses pnpm and vitest, deploys from main"}]}'

One call does not equal one stored fact. An add request is counted per memory extracted from a message batch: one /add call that extracts 5 memories counts as 5 add requests. A batch that mentions the package manager, test runner, and deploy branch can therefore produce three memories and consume three adds. See what add and retrieve requests cost when you estimate quota.

Write for retrieval from the start. Store one fact per idea, use the words a future session would type, and include the reason in one line. Short, keyword-rich memories rank better in search and are easier to correct.

The agent memory rest api fits automation because /add accepts whatever your script already knows. Keep the habit narrow: conventions, project decisions, constraints, and recurring gotchas belong in memory. Chatty acknowledgments and one-off debugging output do not.

Step 3: Recall with POST /search

POST /search takes a query string and returns the project memories relevant to it. Your agent calls it at task start — package manager, test command, last failure — instead of re-reading the repo or asking you again. The search endpoint reference documents the query shape.

Search for the canary with different words than you stored. This tests recall, not exact-match echo: you stored repo uses pnpm and vitest, now you ask about the package manager generically:

curl -s -X POST "$MEMORY_BASE_URL/search" \
  -H "Authorization: Bearer $MEMORY_API_KEY" \
  -H "X-Api-Version: $MEMORY_API_VERSION" \
  -H "Content-Type: application/json" \
  -d '{"query": "rest-quickstart canary package manager and test runner"}'

Expect the canary memory back with the pnpm and vitest facts. If it returns, your store-then-recall loop works end to end. If it does not, check the project key first — a different project holds a different memory set — then confirm the add call succeeded.

Retrieve counting is tiered, so plan query volume accordingly. The first 10 memories retrieved count as 1 request, and each additional 10 counts as 1 more, which means 25 memories count as 3 requests.

Shape queries the way your agent will ask. Lead with the decision you need — package manager, deploy branch, known gotcha — plus one scope word such as the repo name. When a first query returns too much, narrow with a second term rather than paging deeper. Record the queries that work; they become the checklist your agent runs before editing code.

Search is also how you audit quality. A weekly search for conventions and gotcha surfaces what the project remembers. Duplicates and stale notes show up here first, and the next section removes or fixes them.

Step 4: Maintain with list, update, and delete

Memory rots unless you maintain it. Conventions change, decisions get reversed, and provisional notes outlive the PR they described. Three endpoints handle cleanup: list to inspect, update to correct, and delete to retract. The list endpoint reference documents the pagination parameters the audit loop reuses.

Page through the project with GET /list using limit and offset. Small pages keep the review manageable and give you the memory IDs that update and delete require:

# first page
curl -s "$MEMORY_BASE_URL/list?limit=20&offset=0" \
  -H "Authorization: Bearer $MEMORY_API_KEY" \
  -H "X-Api-Version: $MEMORY_API_VERSION"

# second page
curl -s "$MEMORY_BASE_URL/list?limit=20&offset=20" \
  -H "Authorization: Bearer $MEMORY_API_KEY" \
  -H "X-Api-Version: $MEMORY_API_VERSION"

Fix wrong facts with PUT /update rather than adding a corrected duplicate. Two memories that contradict each other — one saying the repo uses npm, one saying pnpm — force every future search to guess. Updating the original entry keeps one authoritative text and keeps its ID for later recall.

Remove stale facts with DELETE /delete/{memory_id}, where the ID comes from a list or search response. Use it when the code the memory describes no longer exists or a provisional note has landed. Reserve DELETE /delete without an ID for clearing a whole project; it removes every memory in the project, so only use it on a test project.

Run a short hygiene pass after the walkthrough. List the first twenty memories, update the canary text, search to confirm recall returns the new text, then delete the canary and confirm search and list no longer return it. That five-call sequence proves every endpoint against your key, headers, and network path.

Make maintenance a habit, not a cleanup event. Whoever changes a convention updates the memory in the same session; whoever spots a duplicate deletes it when search surfaces it.

Pin X-Api-Version and handle 429 responses

Every request in this walkthrough sends the X-Api-Version header with the value 2026-09-25. That header is date-based versioning: it tells the API which response shape your client was built against. Pinning it keeps scripts and CI jobs reproducible until you deliberately upgrade.

Set the version in one place. The shell snippets above read it from MEMORY_API_VERSION; a Python or Node client should hold it in a single headers dictionary next to the base URL and credential. The API versioning docs describe the current version and upgrade behavior, so check them before changing the pinned value.

import os
import requests

BASE_URL = os.environ["MEMORY_BASE_URL"]  # https://api.memory.audaxic.com
HEADERS = {
    "Authorization": f"Bearer {os.environ['MEMORY_API_KEY']}",
    "X-Api-Version": os.environ.get("MEMORY_API_VERSION", "2026-09-25"),
    "Content-Type": "application/json",
}

resp = requests.get(f"{BASE_URL}/list", headers=HEADERS, params={"limit": 10, "offset": 0})
resp.raise_for_status()
print(resp.json())

Two rate limits apply, and both produce 429 responses your client should read rather than retry blindly. Management-plane create operations are limited to 100 per hour per IP, with RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and RateLimit-Policy headers describing the budget. Data-plane protection targets failed authentication: 100 failed attempts per 4 hours per IP, where 429 responses include a Retry-After header telling you how long to wait.

Handle 429 with backoff keyed off the headers. Read Retry-After and sleep that long before retrying; do not loop with a fixed short delay. On the data plane, a 429 usually means the credential is wrong — an at_... token sent to the data plane, a truncated ak_... key, or the wrong base URL — so fix the credential rather than retrying into the guard.

When any call fails, check three things in order. First, the base URL is the data plane for add, search, list, update, and delete. Second, the key is an ak_... project key, not a management token. Third, the X-Api-Version header is present with 2026-09-25. Those three checks, plus honoring Retry-After on 429, cover the documented failure modes for the agent memory rest api without guessing.

FAQ

Written by Efe — Oct 11, 2026 · More articles · X @AudaxicTech