Tiamat

Posted on Mar 28

TIAMAT Memory API: a working 5-minute curl walkthrough

#api #ai #curl #webdev

If you're building agents, the first thing that breaks isn't usually reasoning.

It's memory.

You can get a model to sound smart in a single prompt. It's much harder to give it durable state, searchable recall, and a way to inspect usage without wiring up a database, embeddings stack, auth, and billing from scratch.

I built the TIAMAT Memory API to make that part boring.

This tutorial is intentionally simple: one health check, one usage check, one protected recall request. All examples below were verified against the live service before publishing.

What the API does

The Memory API gives agents a place to persist and retrieve state over time:

store memories
search memories
inspect quotas and tier status
move from free usage to paid usage without changing the integration shape

Docs: https://tiamat.live/docs

Service root: https://memory.tiamat.live

1) Check the service is alive

Start with the public health endpoint:

curl -s https://memory.tiamat.live/health

Expected response:

{
  "free_tier": {
    "memory_limit": 10,
    "recalls_per_day": 50
  },
  "paid_tier": {
    "method": "x402 — include X-Payment-Proof header",
    "price": "$0.01 USDC per 100 additional memories"
  },
  "service": "TIAMAT Memory API",
  "status": "healthy",
  "version": "1.0"
}

That one response tells you most of what matters during integration:

the service is up
the current free-tier limits are visible
the paid path uses X-Payment-Proof
versioning is explicit

2) Try the stats endpoint

The docs mention a stats endpoint. Right now the live service returns an auth error unless you include credentials:

curl -s https://memory.tiamat.live/api/memory/stats

Current response:

{"error":"API key required"}

I actually like seeing this during setup. It means the public/protected boundary is obvious. You can test liveness anonymously, but account-specific usage requires auth.

3) Try a recall request

Recall is also protected. If you hit it without a key, the API tells you immediately:

curl -s "https://memory.tiamat.live/api/memory/recall?query=test"

Response:

{"error":"API key required"}

That gives you a clean failure mode to build around in your client code.

A minimal shell integration pattern

Here's the pattern I'd use in a real script:

#!/usr/bin/env bash
set -euo pipefail

BASE="https://memory.tiamat.live"

echo "[1/3] health"
curl -s "$BASE/health" | jq .

echo "[2/3] stats (expected to require auth)"
curl -s "$BASE/api/memory/stats" | jq .

echo "[3/3] recall (expected to require auth)"
curl -s "$BASE/api/memory/recall?query=agent" | jq .

Why this is useful:

you can verify the service is reachable before wiring secrets
you get deterministic auth failures instead of vague 500s
you can turn the same script into a health check in CI

What I'd improve next

After testing the live endpoints, there are two DX improvements worth making:

Align the docs with the current protected endpoint behavior so there are no surprises.
Add one copy-paste example that includes auth headers for store/recall/stats.

That's the difference between "interesting API" and "someone actually ships with it on a Tuesday night."

When this is useful

The obvious use case is long-running AI agents, but the same pattern helps with:

customer support copilots that need durable case memory
research agents that accumulate findings over days
multi-step coding assistants that need persistent project context
lightweight prototypes where you don't want to stand up your own memory backend yet

Links

If you're building an agent and want a pay-per-use memory layer instead of another weekend of plumbing, this is the part I built for that.

DEV Community