harnyMemory API
Apps, data points, memories, audiences, users and traits
The five nouns of every call, the memories that recall returns, and every limit in one place.
Copy page
App
An app is the isolation boundary. An app key selects the app, and the app holds its own data points, memories and audiences. The app key starts with fsa_. Send it as Authorization: Bearer $HARNY_APP_KEY.
Responses that name the app return it in the projectId field. The value is the app id. The field name stays projectId.
Usage is read with the app key only (GET /v1/memory/usage).
Data point
A data point is one piece of raw text and its time. It is the unit of replacement and deletion.
| Field | Type | Limit | Meaning |
|---|---|---|---|
id | string | no /, at most 512 characters | Source id. Defaults to the lowercase SHA-256 of content. Returned as sourceId. |
content | string | required, non-blank, no U+0000, at most 500,000 characters | The text to store. |
label | string | at most 200 characters | A short label for the data point. |
timestamp | string | ISO 8601 with a time zone | When the content happened. Defaults to the stored value, else now. |
metadata | object | JSON object, at most 64 KiB serialized | Free-form metadata. |
audience | string | omitted or project only | Audience slug. Other values return 400 audience-unknown. |
identity | string | at most 200 characters | The user this data point is for. |
idempotencyKey | string | at most 200 characters | Makes a retry safe. See Idempotency below. |
An unknown field returns 400 invalid-ingestion.
Send a data point with POST /v1/memory/ingest. It returns 202 with status: "queued", or 200 with status: "completed" and unchanged: true when the content, label, metadata and timestamp match the stored data point.
Sending the same id with any change creates a new revision. Harny deletes the memories built on the old revision, then ingests the new text. Fields you leave out of the resend keep their stored values. If the new text is refused, the data point has no memories until you send it again, and that resend counts as a change. A deleted id that is sent again returns 409 data-point-deleted.
Memory
A memory is a short statement derived from a data point. It keeps a link to the data points it rests on.
Memories are created when a data point is ingested. Deleting a data point deletes the memories that the send created. A send that created none, because its text overlapped existing facts, leaves existing memories in place.
Recall returns memories as results. Each result has an id, a rank, an occurredAt, the content, an artifact object and a sources list.
Audience
An audience is a named group of users in an app.
Audience kinds are fixed, rule and default. A fixed audience names its users. A rule audience matches all or any of 1 to 20 trait conditions. You choose the match mode.
Every data point goes to the project audience, which is the default and holds every user. The audience field on a data point takes only project or nothing, so a group you create does not yet limit who reads a data point. Use one app for each customer whose memory must stay apart.
Create, read, replace, delete and recompute audiences by slug with /v1/memory/audiences. The API reference lists each route. Access control shows how to keep customers apart.
User
A user is the person whose memory is read or written. The API field is identity.
For a recall, the user is the person the answer is given as. Requests that use an app key must name the user in the X-Harny-User: <user> header. A user key (starts with fsk_) names its own user and needs no X-Harny-User header.
A body identity cannot select a different user. If you send one, it must equal the acting user's identifier or id. Otherwise the API returns 403 identity-mismatch.
Trait
A trait is a string attribute of a user. The key can be up to 200 characters. The value can be up to 2,000 characters.
Set traits when you create or update a user with /v1/memory/identities. Audience rules match on them.
Metadata
metadata on a data point is a JSON object of up to 64 KiB when serialized. Recall returns it in each result's sources[].metadata.
What recall returns for a user
POST /v1/memory/recall answers as the user named by identity, or by the X-Harny-User header.
Request fields: query (required), identity (required), limit (1 to 200, default 100), level (low 8,000 default, medium 16,000, high 24,000, extra-high 32,000) or maxTokens (never both; floor 256), queryTimestamp, occurredFrom, occurredTo (inclusive), sort (relevance default, or chronological).
Response fields: asOf, usedEvidenceTokens, results[] (id, rank, occurredAt, content, artifact{id, kind, occurredAt, supersededAt}, sources[]{sourceId, occurredAt, label, metadata, excerpts}), and pending while the user has queued items.
queryTimestamp removes results that occurred later. Unknown times are kept. occurredFrom and occurredTo keep only results inside the window, and unknown times are dropped. occurredFrom after occurredTo returns 400 recall-range-invalid.
excerpts is always []. kind is always observation.
Limits
| Limit | Value |
|---|---|
content | at most 500,000 characters |
label | at most 200 characters |
id | at most 512 characters |
metadata | at most 64 KiB serialized |
identity | at most 200 characters |
idempotencyKey | at most 200 characters |
| Batch items | 1 to 1,000 per batch |
| Batch size | at most 16 MiB UTF-8 in total |
| Trait key | at most 200 characters |
| Trait value | at most 2,000 characters |
| Audience rule conditions | 1 to 20 |
Recall limit | 1 to 200 (default 100) |
Recall level | low 8,000 (default), medium 16,000, high 24,000, extra-high 32,000 |
Recall maxTokens | floor 256 |
| Delete ids (bulk) | 1 to 1,000 |
A call over the per-minute limit returns 429 with an empty body and a Retry-After header. Rates and allowances per person and per app are on the Limits page.