# 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](https://augenta.pages.dev/docs/experiences.md) or
[Workspace Consolidate](https://augenta.pages.dev/docs/consolidate.md#workspace-processing), 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](https://augenta.pages.dev/docs/api-reference/engram-object.md) for its available operations, all attributes and an example object.

## Endpoints

| Endpoint                                                                                     | Purpose                                          |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| [GET /v1/engrams](https://augenta.pages.dev/docs/api-reference/list-engrams.md)                     | List current Workspace Engrams.                  |
| [`GET /v1/engrams/{id}`](https://augenta.pages.dev/docs/api-reference/get-engram.md)                | Retrieve one Engram with its initial Claim page. |
| [`GET /v1/engrams/{id}/claims`](https://augenta.pages.dev/docs/api-reference/list-engram-claims.md) | List and filter its current Claims.              |

Engrams are derived through [Consolidate](https://augenta.pages.dev/docs/consolidate.md) 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:

```bash 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](https://augenta.pages.dev/docs/events.md) 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](https://augenta.pages.dev/docs/quickstart.md), 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.

```bash 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.

| 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:

```bash 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.

| 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`:

```bash 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
}
```

| 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](https://augenta.pages.dev/docs/pagination.md).

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](https://augenta.pages.dev/docs/events.md) for types, scope and payload fields.

See the generated reference for [listing engrams](https://augenta.pages.dev/docs/api-reference/list-engrams.md),
[reading one](https://augenta.pages.dev/docs/api-reference/get-engram.md), [its claims](https://augenta.pages.dev/docs/api-reference/list-engram-claims.md) and
[listing events](https://augenta.pages.dev/docs/api-reference/list-events.md).

## 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.
