How to use

Two ways to use pumaDB agent memory.

Use MCP when an agent client should discover pumaDB as a memory tool server. Use the REST API from trusted app backends, workers, serverless functions, CLIs, and scripts.

REST API

Best for small server-side apps, server-rendered apps, serverless routes, scripts, and services that can keep API keys secret.

Use the API

MCP

Best for Codex, ChatGPT, Claude, and other agent clients that can connect to hosted Streamable HTTP MCP servers.

Use MCP

API for apps

Call the agent memory API from your backend.

API keys are full-account bearer secrets. Keep puma_live_* keys in server-side environment variables; do not put them in React bundles, static sites, mobile apps, browser code, public repos, or other client-side surfaces.

[01]

Request and verify a magic link

Use your email to get an initial full-access API key.

curl -X POST https://api.pumadb.ai/auth/magic-link \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}'

curl -X POST https://api.pumadb.ai/auth/verify \
  -H 'Content-Type: application/json' \
  -d '{"token":"<token-from-magic-link>"}'

[02]

Create a named app key

Create one key per app and environment so it can be rotated independently.

curl -X POST https://api.pumadb.ai/v1/_keys \
  -H 'Authorization: Bearer $PUMADB_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-react-api-prod"}'

[03]

Write JSON rows

Send bearer auth and JSON from trusted server-side code.

const response = await fetch("https://api.pumadb.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PUMADB_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ title: "ship docs", status: "open" })
});

const row = await response.json();

[04]

Proxy browser apps

React/static apps should call your own API route first; the route calls pumaDB.

app.post("/api/tasks", async (req, res) => {
  const response = await fetch("https://api.pumadb.ai/v1/tasks", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PUMADB_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(req.body)
  });

  res.status(response.status).send(await response.text());
});

Base URL https://api.pumadb.ai Full API reference

Revision history

Updates and deletes keep a recovery trail.

Every row update or delete archives the prior row before changing it. pumaDB keeps the last 10 archived versions per row for 30 days, and version storage does not count against the account storage cap.

When versions are created

Versions are captured before update_row, update_where, delete, and REST update or delete calls overwrite the live row.

How restore works

Restoring writes the archived content back as the live row. If the row was deleted, restore recreates it.

Undo the undo

The current live value is archived before a restore, so a restore can itself be reversed while the archived version is retained.

[01]

List archived versions

Use REST from server-side code, or the MCP versions tool from an agent.

curl "https://api.pumadb.ai/v1/tasks/versions?id=<row-id>" \
  -H 'Authorization: Bearer $PUMADB_API_KEY'

[02]

Restore a version

Use REST from server-side code, or the MCP restore tool from an agent.

curl -X POST https://api.pumadb.ai/v1/tasks/restore \
  -H 'Authorization: Bearer $PUMADB_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"id":"<row-id>","version":1}'

MCP for agents

Connect agent clients to hosted MCP memory.

Remote MCP uses OAuth discovery and dynamic client registration. The agent signs in with the pumaDB magic-link flow, then gets MCP-scoped OAuth tokens for the hosted tool server.

[01]

Codex

Add the hosted MCP URL with the Codex CLI.

codex mcp add pumadb --url https://api.pumadb.ai/mcp

[02]

ChatGPT

Open ChatGPT in your browser.
Go to Settings > Apps & Connectors.
Open Advanced settings and turn on Developer mode.
Click Create or Create app.
Name it pumaDB and paste https://api.pumadb.ai/mcp.
Use dynamic OAuth if ChatGPT asks about authentication, then scan tools and create the app.

ChatGPT custom MCP app docs

[03]

Claude web

Open Customize > Connectors.
Click +, then Add custom connector.
Name it pumaDB and use https://api.pumadb.ai/mcp.
Leave OAuth client fields blank.

Claude custom connector docs

[04]

Any MCP client

Use this URL anywhere a hosted Streamable HTTP MCP server URL is accepted.

https://api.pumadb.ai/mcp

MCP tools

Agents get table tools, recovery tools, and safe memory helpers.

After setup, agents can add, query, update, delete, restore, open viewer links, and remember typed structured records through MCP. Prefer remember for new safe memory writes; use the docs page when you need the full tool-call reference.

Full MCP tool reference

addqueryupsertupdate_rowupdate_wherelist_tablescountdeleteversionsrestoreopen_rowopen_text_fieldrememberremember_*