Memory API

Quickstart

Get a key, send a fact, send the fact that supersedes it, wait for the send to complete, then recall as one user.

Copy page

Before the first call

Sign up for an account, or let your coding agent set Harny up with no account: it follows harny.ai/auth.md and hands you a link to claim the app later.
Create an app key in the console. The app key is the secret your server sends with every call to prove the call is yours. It starts with fsa_. Store the value as HARNY_APP_KEY. The key value is shown once.
Send every call to https://api.harny.ai/v1/memory with two headers. Authorization: Bearer $HARNY_APP_KEY carries your app key. X-Harny-User: <user> names the person the memory belongs to, using the id your app already uses for that person. A user key (starts with fsk_) names its own user and needs no X-Harny-User.

Call the API from your server. Do not put a key in a browser.

Four calls

The example sends two notes about one account, 175 days apart, then asks for the budget as of now.

# 1. Send the fact at its original time.
curl -X POST https://api.harny.ai/v1/memory/ingest \
  -H "Authorization: Bearer $HARNY_APP_KEY" \
  -H "X-Harny-User: demo-user" \
  -H "Content-Type: application/json" \
  -d '{ "id": "call-8820",
        "content": "Nadia confirmed the Acme pilot ships March 14. Budget is 32k.",
        "label": "Account review call",
        "timestamp": "2026-02-03T09:00:00Z" }'

# 2. Send the fact that supersedes it.
curl -X POST https://api.harny.ai/v1/memory/ingest \
  -H "Authorization: Bearer $HARNY_APP_KEY" \
  -H "X-Harny-User: demo-user" \
  -H "Content-Type: application/json" \
  -d '{ "id": "call-8821",
        "content": "Budget for the Acme pilot moved to 40k.",
        "label": "Email from Nadia",
        "timestamp": "2026-07-28T16:00:00Z" }'

# 3. Poll the ingestionId from the last response until status is completed.
curl https://api.harny.ai/v1/memory/ingest/$INGESTION_ID \
  -H "Authorization: Bearer $HARNY_APP_KEY" \
  -H "X-Harny-User: demo-user"

# 4. Recall as one user.
curl -X POST https://api.harny.ai/v1/memory/recall \
  -H "Authorization: Bearer $HARNY_APP_KEY" \
  -H "X-Harny-User: demo-user" \
  -H "Content-Type: application/json" \
  -d '{ "query": "what is the Acme pilot budget?",
        "identity": "demo-user",
        "level": "medium" }'

The recall response:

{
  "asOf": "2026-07-29T00:00:00Z",
  "usedEvidenceTokens": 18,
  "results": [
    {
      "id": "39d9d745-c9f4-4884-a602-e538def76815",
      "rank": 1,
      "occurredAt": "2026-07-28T16:00:00Z",
      "content": "Acme pilot budget: currently 40k.",
      "artifact": {
        "id": "39d9d745-c9f4-4884-a602-e538def76815",
        "kind": "observation",
        "occurredAt": "2026-07-28T16:00:00Z"
      },
      "sources": [
        {
          "sourceId": "call-8821",
          "occurredAt": "2026-07-28T16:00:00Z",
          "label": "Email from Nadia",
          "excerpts": []
        }
      ]
    }
  ]
}

Read the page

Each result is one memory with id, rank, occurredAt and content. Its artifact carries the memory id, its kind and the date it happened. The sources array lists the data points the memory rests on, each with your sourceId, its date and its label. usedEvidenceTokens counts the tokens the kept results use. level sets the token budget: low is 8,000, medium 16,000, high 24,000 and extra-high 32,000.

A send answers 202 with an ingestionId while it is still being processed. Poll GET /v1/memory/ingest/{ingestionId} until status is completed. If you recall before then, the response carries pending, which says how many of your sends are still queued.

Send queryTimestamp with a recall to read as of an earlier time. Results that happened after it are dropped, so a read before July 28 sees the February value.