Memory API quickstart

Create one in your dashboard under API keys. It is shown once, so put it in your environment now rather than after you have closed the dialog.

export PERSISTMEMORY_API_KEY="pm_..."

The health endpoint needs no credential, so it separates a network problem from a key problem before you have spent any time on either.

curl -s https://api.persistmemory.com/health/ready
# {"status":"ready","checks":{"database":"ok"}}

Post text to the remember endpoint. What comes back is not a memory: it is a job. Extraction, entity resolution, deduplication and conflict detection all run afterwards, and one paragraph may produce several memories or none.

curl -s https://api.persistmemory.com/api/v1/remember \
  -H "authorization: Bearer $PERSISTMEMORY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"text":"Marcus Reid quoted 2340 for the boiler on 3 August. Price holds 30 days."}'

# {"status":"accepted","jobId":"job_...","note":"..."}

This is the step everybody trips on. A 202 means accepted, not stored. Searching immediately afterwards returns nothing, and it is easy to conclude the write failed when it simply has not finished.

Poll the job instead of sleeping. Ingestion takes a second or two for text and longer for audio or a scanned PDF, so a fixed sleep is either wasteful or wrong.

curl -s https://api.persistmemory.com/api/v1/jobs/job_... \
  -H "authorization: Bearer $PERSISTMEMORY_API_KEY"

Search ranks by relevance and returns each memory with its score, its sources and its timestamps. Read `diagnostics.degraded`: search falls back to deterministic retrieval when embeddings are unavailable, so it answers in a narrower way rather than failing.

curl -s -G https://api.persistmemory.com/api/v1/search \
  -H "authorization: Bearer $PERSISTMEMORY_API_KEY" \
  --data-urlencode "query=boiler quote" --data-urlencode "limit=5"

Both SDKs retry idempotent requests with backoff and raise a typed error per status, so a rate limit is distinguishable from a bad key without reading a message string.

import { PersistMemory } from "@persistmemory/sdk";

const client = new PersistMemory({ apiKey: process.env.PERSISTMEMORY_API_KEY! });

await client.memories.remember({
  text: "Marcus Reid quoted 2340 for the boiler on 3 August."
});

const found = await client.search.query({ query: "boiler quote", limit: 5 });
for (const { memory, score } of found.results) {
  console.log(score.toFixed(2), memory.content);
}