# Engramme API Docs - Full Agent Context

This file is a compact, agent-readable reference for the public Engramme memory API docs. Use it when generating code, examples, tests, or integration guidance.

## Product Summary

Engramme turns source content into structured memories. Developers upload documents or text with `/v1/memorize`, then retrieve relevant memory results with `/v1/memories/recall`.

The public docs are B2B/developer API docs. The Engramme app at `app.engramme.com` is used for setup tasks such as creating API keys, choosing source access, and connecting hosted integrations.

## Base URL

```text
https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev
```

Use this base URL in public REST examples.

Do not use the webapp backend URL in public REST examples unless specifically documenting app-internal flows.

## Authentication

Authenticated API requests use the `x-api-key` header.

```bash
curl -X POST https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev/v1/memories/recall \
  -H "x-api-key: $ENGRAMME_API_KEY" \
  -F "text=team meetings"
```

API keys are created and managed in `app.engramme.com`.

API key behavior:
- Maximum 5 API keys per account.
- Keys are shown once at creation.
- Keys should be stored in an environment variable or secret manager.
- Do not expose keys in client-side browser code.
- Keys can be all-source or source-scoped.
- New keys require a billing account in the app flow.
- The default key cannot be deleted, but can be regenerated.

## Source Access

API keys can restrict access by source type.

Access modes:
- All Sources: key can access all supported source types.
- Specific Sources: key can access only selected source types.
- Empty selected list: key has no file/source access.

If a request uses a source outside the key's allowed list, expect `403`.

## Source Types

Use these values for `source_type` on uploads and `source` filters on recall:

```text
text, email, pdf, stream, browser, vscode, calendar, github, slack,
asana, claude_code, cursor, codex, google_meets, technical_docs,
weekly_updates, gdocs, tasks, contacts, youtube, photos, books, fit,
ms-outlook, ms-calendar, ms-teams, ms-onedrive, ms-sharepoint
```

Notes:
- If `source_type` is omitted on upload, the backend defaults to `text`.
- For quickstart examples, use `source_type=text`.
- Integration provider IDs and API source types are related but not always identical.
- Hosted integrations are connected through the app UI, not by using worker endpoints.

## Hosted Integrations

Normal users connect hosted integrations through `app.engramme.com`.

Currently exposed app integrations:
- Gmail
- Drive
- Calendar
- Asana
- Outlook
- Microsoft Calendar
- OneDrive

Do not document internal integration worker/process endpoints in public REST docs.

## Primary Endpoints

### Health

`GET /v1/health`

No auth required.

```bash
curl https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev/v1/health
```

Expected shape:

```json
{
  "status": "healthy",
  "message": "Memory Machines Platform API is running."
}
```

### Memorize

`POST /v1/memorize`

Use this endpoint to upload content for memory extraction.

Auth:
- `x-api-key` required.

Request:
- `multipart/form-data`
- `file` required for normal uploads
- `user_name` required
- `source_type` optional, defaults to `text`
- `item_id` optional

Example:

```bash
curl -X POST https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev/v1/memorize \
  -H "x-api-key: $ENGRAMME_API_KEY" \
  -F "file=@meeting-notes.txt" \
  -F "user_name=Jane Doe" \
  -F "source_type=text"
```

Response shape:

```json
{
  "status": "success",
  "user_id": "user_abc123",
  "item_id": "meeting-2025-01-15",
  "workflow_execution": "projects/.../executions/exec123"
}
```

Important:
- `/v1/memorize` returns when processing starts, not when memories are definitely recallable.
- `workflow_execution` is a backend processing reference; most clients do not need it.
- Recall may return no results immediately after upload.
- Retry recall after a short delay.

Upload limits:
- Text and most files: 10MB.
- PDFs: 20MB.
- `item_id`: max 500 characters.
- `item_id` may contain word characters plus `-`, `_`, `=`, `!`, and `:`.

Conflict behavior:
- User-provided `item_id` can return `409` while the same item is processing.
- Use generated IDs for simple uploads.
- Use stable unique IDs for dedupe/idempotency.

### Recall

`POST /v1/memories/recall`

Use this endpoint to retrieve ranked memory results for a query.

Auth:
- `x-api-key` required.

Request:
- `multipart/form-data`
- `text` required for normal live recall
- `source` optional source filter

Example:

```bash
curl -X POST https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev/v1/memories/recall \
  -H "x-api-key: $ENGRAMME_API_KEY" \
  -F "text=team meetings"
```

Response shape:

```json
{
  "trace_id": "9b1c2d3e-4f56-7890-abcd-1234567890ef",
  "memories": [
    {
      "custom_id": "meeting-jan15_memory_0",
      "item_id": "meeting-jan15",
      "score": 0.94,
      "source": "text",
      "content": {
        "headline": "Weekly team sync",
        "body": "I attended the weekly team sync...",
        "participants": ["Sarah", "Mike"],
        "when": "January 15, 2025",
        "where": "Conference Room B",
        "tags": ["meeting", "roadmap"]
      }
    }
  ],
  "qa": [],
  "chunks": []
}
```

Query limits:
- `text`: max 1,000 characters.

Empty results can mean:
- Processing has not finished.
- No memories match the query.
- The key is source-scoped away from relevant data.
- The uploaded content was too short or synthetic to produce a recallable memory.

### Files

File endpoints require an API key with access to the relevant source.

List files:

```bash
curl "https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev/v1/files/list?source_type=text" \
  -H "x-api-key: $ENGRAMME_API_KEY"
```

Download file:

```bash
export ITEM_ID="YOUR_ITEM_ID"
export SOURCE_TYPE="text"

curl "https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev/v1/files/download?item_id=$ITEM_ID&source_type=$SOURCE_TYPE" \
  -H "x-api-key: $ENGRAMME_API_KEY"
```

Delete file:

```bash
export ITEM_ID="YOUR_ITEM_ID"
export SOURCE_TYPE="text"

curl -X DELETE "https://memorymachines-gateway-prod-btf57kda.uc.gateway.dev/v1/files/$SOURCE_TYPE/$ITEM_ID" \
  -H "x-api-key: $ENGRAMME_API_KEY"
```

## Common Response Fields

Memorize:
- `status`: upload status.
- `user_id`: user associated with the API key.
- `item_id`: uploaded item identifier.
- `workflow_execution`: backend processing reference.

Recall:
- `trace_id`: recall request identifier.
- `memories`: ranked memory results.
- `qa`: Q&A-style results when available.
- `chunks`: raw chunk results when available.

Memory result:
- `custom_id`: unique memory identifier.
- `item_id`: source item that produced the memory.
- `score`: relevance score.
- `source`: source type.
- `content`: structured memory content.

Content object may include:
- `headline`
- `body`
- `narrative`
- `participants`
- `when`
- `where`
- `tags`
- `entities`
- `other_entities`

Build clients defensively because some fields are source-dependent.

## Errors and Limits

Rate limits:
- Public gateway currently enforces 1,000 requests per minute per project.
- Requests are also subject to application-level limits.
- On `429`, retry with exponential backoff.

Application-level rate limit body shape can be:

```json
{
  "detail": "RATE_LIMIT_EXCEEDED"
}
```

Common status codes:
- `400`: invalid request parameters or malformed input.
- `401`: missing or invalid API key.
- `402`: billing or usage check failed.
- `403`: key does not have access to the requested source or endpoint.
- `404`: resource not found.
- `409`: conflict, such as an item currently being processed.
- `429`: rate limit exceeded.
- `500`: internal server error.
- `503`: service temporarily unavailable.

## What Not To Use From Public REST Docs Yet

Do not use these in public REST examples:
- `POST /v1/memories/feedback`: this route is not exposed by the public REST API. Feedback is handled by app/SDK flows.
- `POST /v1/memories/ask`: available, but not part of the primary tested quickstart path yet.
- Integration worker/process endpoints: normal hosted integration setup is app-managed through `app.engramme.com`.
- Internal entity resolution, recent-people, admin finetune, GCS/KMS, Cloud Run, or worker queue details.

## Key Human Docs

- `/introduction`
- `/quickstart`
- `/authentication`
- `/console-setup/api-keys`
- `/console-setup/source-access`
- `/console-setup/integrations`
- `/reference/source-types`
- `/reference/errors-and-limits`
- `/reference/response-fields`
- `/api-reference/overview`
- `/api-reference/memorize/upload`
- `/api-reference/memories/recall`
- `/api-reference/files/overview`
- `/api-reference/health/check`