An engram groups related claims into memory your application can reuse. An experience's claims
appear in engrams once a Workspace consolidation covers it, when GET /v1/experiences/{id} reports
consolidated. That holds whether the input came through Experiences or
Workspace Consolidate, which returns before consolidation.
Your key needs access to the Workspace you select.
These routes read memory stored in a Workspace. One-shot Consolidate results are not retained and cannot be read here or searched through Recall.
See the Engram object for its available operations, all attributes and an example object.
Endpoints
| Endpoint | Purpose |
|---|---|
| GET /v1/engrams | List current Workspace Engrams. |
GET /v1/engrams/{id} | Retrieve one Engram with its initial Claim page. |
GET /v1/engrams/{id}/claims | List and filter its current Claims. |
Engrams are derived through Consolidate or background processing. There are no manual Engram create, edit or delete routes.
Engram IDs
id is the identifier Augenta assigns to an Engram, such as
eng_0bb057164abd44c5234ecd44. You receive it in data from a Workspace Engram list, or as engram_id on a Recall engram block; a one-shot Consolidate result's IDs can't be looked up. Keep the whole string; you do not
choose it when submitting source material.
For a Workspace, put this ID in the resource URL and select that same Workspace:
curl --fail-with-body -sS --get "https://api.augenta.ai/v1/engrams/$AUGENTA_ENGRAM_ID" \
-H "Authorization: AugentaKey $AUGENTA_API_KEY" \
--data-urlencode "workspace=$AUGENTA_WORKSPACE_ID"
A one-shot Engram has no standalone lookup URL. Its ID identifies an object only within that computation; add the input to a Workspace if you need to retrieve it later.
An Engram can keep its ID as its Claims change. Splitting or merging groups can create or retire IDs; Events describe those transitions. IDs belong to the memory that produced them. Sending the same source to a different Workspace or making a separate one-shot request does not promise the same IDs.
List and read memory
Set AUGENTA_API_KEY and AUGENTA_WORKSPACE_ID for your application. Use the
same key configuration as Hello world, with a Workspace assigned when creating
the key. The examples select the Workspace explicitly; it can be omitted only when the key has
exactly one assigned Workspace.
curl --fail-with-body -sS "https://api.augenta.ai/v1/engrams?workspace=$AUGENTA_WORKSPACE_ID&limit=100" \
-H "Authorization: AugentaKey $AUGENTA_API_KEY"
A page uses data for its resources and nextPageUrl for pagination. This is an illustrative
response; summaries, labels, counts and scores depend on the Workspace's memory:
{
"object": "list",
"url": "/v1/engrams",
"data": [
{
"object": "engram",
"id": "eng_0bb057164abd44c5234ecd44",
"summary": "Checkout retries a failed payment webhook three times before alerting.",
"label": "webhooks \u00b7 alerting",
"labelSupport": 1,
"memoryClass": "semantic",
"status": "active",
"strength": 1.5,
"heatShare": 0.04,
"bornAt": "2026-10-14T09:00:00.000Z",
"updatedAt": "2026-10-14T09:01:00.000Z",
"claimCount": 2,
"claimTokenCount": 28
}
],
"nextPageUrl": null
}
Read one engram with GET /v1/engrams/{id} and the same workspace selector. Its public
eng_… id stays stable as it is updated; a split or merge can produce other ids. Existing
Workspace memory receives public ids at consolidation, so older unpublished entries may not
appear until the next consolidation.
| Field | Meaning |
|---|---|
summary | Readable memory; can be null when unavailable. |
label, labelSupport | Distinctive terms joined by ·, and the mean share of claims containing each term. Support ranges from 0 to 1. An empty label means no term qualified; both can be null for older memory. |
memoryClass, status | The memory's classification and current status. |
strength | The engram's strength, or null when unavailable. |
heatShare | Its share of Workspace heat, from 0 to 1. Recall use raises heat and it decays over about 30 days; a low share means little recent use. This is relative activity, not confidence. Older values can be null. |
claimCount | The number of claims the engram holds now. |
claimTokenCount | Retained claim-text tokens, or null when unavailable. This is not source-input usage or a model bill. |
bornAt | When this Engram ID was first published, or null when its history is unknown. |
updatedAt | The last Claim-membership or summary-text change, or null when unknown. Reading or changing only scores does not advance it. |
Filter a list
Filters narrow results while preserving the list's ascending public-id order. Combine them to find, for example, engrams with low recent use and low strength:
curl --fail-with-body -sS -g "https://api.augenta.ai/v1/engrams?workspace=$AUGENTA_WORKSPACE_ID&heatShare[lte]=0.05&strength[lt]=2&limit=100" \
-H "Authorization: AugentaKey $AUGENTA_API_KEY"
-g prevents curl from treating the brackets as URL patterns.
| Filter | Supported values |
|---|---|
strength | A non-negative numeric range. |
heatShare, labelSupport | Numeric ranges from 0 to 1. |
memoryClass | An exact string, such as semantic. |
label | One label term, ignoring case. A term can contain two words, such as exact scan. |
Ranges use [gt], [gte], [lt] and [lte]. An engram without the filtered field does not
match the filter. Labels are fields on engrams; they are not separate resources or ids.
Read an engram's claims
The claims are the statements an engram was formed from. GET /v1/engrams/{id} returns the first
page in claims.data; use GET /v1/engrams/{id}/claims to page through all of them. Optional filters
select the source experience or an observation-time range on at:
curl --fail-with-body -sS -g "https://api.augenta.ai/v1/engrams/eng_0bb057164abd44c5234ecd44/claims?workspace=$AUGENTA_WORKSPACE_ID&at[gte]=2026-10-01T00:00:00Z&limit=100" \
-H "Authorization: AugentaKey $AUGENTA_API_KEY"
{
"object": "list",
"data": [
{
"id": "clm_f5168b66adedaa5aed8fa72a",
"text": "Checkout retries payment webhooks three times before alerting.",
"experience": "exp_8bffde38a944d051a6cb97a0",
"at": "2026-10-14T09:00:00.000Z",
"object": "claim"
}
],
"nextPageUrl": null
}
| Field | Meaning |
|---|---|
id | The claim's clm_… id. |
text | The statement. |
experience | The exp_… id of the experience it came from. |
at | When it was observed. |
source | Optional lineage, such as the source session or document path. |
A claim keeps the clm_… id returned by Consolidate. Its experience is the source id returned
by Experiences or Consolidate; it is null only for claims older than experience tracking.
Optional source contains lineage, such as the source session or document path.
A filtered claims page can be short or empty while claims.nextPageUrl is still present. Continue
until claims.nextPageUrl is null, rather than stopping at an empty claims array.
Pagination and events
Follow nextPageUrl unchanged for both Engram and Claim lists. URLs preserve Workspace,
filters, limits and inclusion settings. The default limit is 100 and the maximum is 500.
Editing a bound selection returns 400 invalid_cursor; a changed memory generation returns
409 cursor_stale, which means restart the initial read. See Pagination.
To track durable lifecycle events, use GET /v1/events and retrieve one recorded Event with
GET /v1/events/{id}. Each Event has its own evt_ ID and a recorded identity-lineage payload.
Follow its nextPageUrl until null, then use the separate since bookmark to poll for later
Events. See Events for types, scope and payload fields.
See the generated reference for listing engrams, reading one, its claims and listing events.
Paged claim content
List responses stay compact. Add include=claims to include each engram's initial claim page;
reading one engram includes it by default. claimCount is the full current membership count,
while claims.data.length is only the loaded page. Continue using claims.nextPageUrl; an empty or
short page can still have more results. claims is absent when it has not been loaded.
One-shot and Workspace operations return this same resource. Labels are relative to the
containing memory. One-shot strength and heat describe its recorded rebuild without recall
activations; Workspace values incorporate persisted activity. Neither is confidence.
bornAt is first public publication; updatedAt changes with membership or summary text,
including a delayed model summary. Unknown historical timestamps are null.
Recall's model-facing context blocks are separate representations, not Engram resources.