recall · Getting started · API
Thin clients for the API, in Python and TypeScript. They add no behaviour of their own: they build the request, carry your key, raise on a refusal, and follow a cursor when a feed is paged. Both depend on nothing but their language's standard library.
Both clients carry the whole surface below, call for call, over the same routes — Python in snake_case, TypeScript in camelCase. A test in the service's own suite fails if one of them drifts ahead of the other.
pip install recall-sdk # Python 3.10+ npm install recall-sdk # Node 18+, or any runtime with fetch
from recall_sdk import Recall
r = Recall(url="https://<your host>", key="rk_...") # an agent key is bound to its workspace
# r = Recall(url=..., key="st_...", workspace="acme") # a user token names the workspace
ctx = r.context("bk_123", "migrate the billing tables to Postgres 17")
print(ctx["text"]) # paste straight into the prompt
r.remember("bk_123", "Decision", "Named volumes only",
"Every app mounts named volumes.",
reason="anonymous ones vanished on redeploy", area="infrastructure")
print(r.plan_check("bk_123", "drop the anonymous volumes and redeploy")["consider"])
TypeScript is the same surface in camelCase:
import { Recall } from "recall-sdk";
const r = new Recall({ url: "https://<your host>", key: "rk_..." });
const ctx = await r.context("bk_123", "migrate the billing tables");
| Reading | context · team_context · brief · recall · read · expand · plan_check · timeline · activity |
|---|---|
| Writing | remember · ingest · job · outcome · forget · move · promote · route |
| Settling | contradictions · assign_contradiction · resolve_contradiction |
| Rules | constraints · lift_constraint |
| The space | buckets · export · analytics · vocabulary · set_profile · me |
| Events | events (one page) · all_events (follows the cursor) · webhooks · add_webhook · verify_signature |
Workspace administration, billing and platform operations are deliberately absent. They exist on the API and are not part of the supported client surface.
from recall_sdk import RecallError
try:
r.read("bk_123", "Decision", "something that is not there")
except RecallError as e:
print(e.status, e.detail) # 404 'memory not found'
Every non-2xx answer raises RecallError(status, detail) carrying the server's own words. A refusal is never turned into an empty result — if your scope does not cover a record, you get the refusal, not silence.
for ev in r.all_events(since=last_id):
handle(ev)
A page can come back empty and still not be the end, because what may be returned is decided per event. all_events follows the cursor until the feed says it is exhausted, and refuses to loop on a server that offers no way forward.
from recall_sdk import verify_signature
if not verify_signature(secret, request.body, request.headers["X-Recall-Signature"]):
return 401
The clients are MIT. That licence covers the client library only — recall itself is a separate commercial service and is not licensed by it. The package holds no part of the product: it is an HTTP client, and everything that makes recall work stays on the server.
The client's version tracks the shape of the API it speaks, not the service's release number. A method is never removed in a patch release, and a route that moves keeps its old method working until the next major. Pin the minor version if you would rather approve changes yourself.