Skip to content
AugentaDocsOpen console ↗
Engrams

Documentation

API reference
View Markdown

Engrams

Read a Workspace's engrams and the claims each one holds.

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

EndpointPurpose
GET /v1/engramsList current Workspace Engrams.
GET /v1/engrams/{id}Retrieve one Engram with its initial Claim page.
GET /v1/engrams/{id}/claimsList 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
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
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:

json
{
  "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.

FieldMeaning
summaryReadable memory; can be null when unavailable.
label, labelSupportDistinctive 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, statusThe memory's classification and current status.
strengthThe engram's strength, or null when unavailable.
heatShareIts 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.
claimCountThe number of claims the engram holds now.
claimTokenCountRetained claim-text tokens, or null when unavailable. This is not source-input usage or a model bill.
bornAtWhen this Engram ID was first published, or null when its history is unknown.
updatedAtThe 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
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.

FilterSupported values
strengthA non-negative numeric range.
heatShare, labelSupportNumeric ranges from 0 to 1.
memoryClassAn exact string, such as semantic.
labelOne 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
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"
json
{
  "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
}
FieldMeaning
idThe claim's clm_… id.
textThe statement.
experienceThe exp_… id of the experience it came from.
atWhen it was observed.
sourceOptional 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.