---
title: "Ingest a memory fragment into the active episodic store"
method: POST
path: "/active-memory/ingest"
tags: ["active-memory"]
---

# Ingest a memory fragment into the active episodic store

`POST /active-memory/ingest`

## Request

- Base URL: `https://api.getmetacognition.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getmetacognition.com/active-memory/ingest`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/metacognition/apis/tex-api/docs/active-memory/ingest/post.ts> (a function with typed inputs; its response is checked against the schema)

Embed `body.text` and write the vector + text to the Cloudflare Active Memory
Worker (KV for text, Durable Object for vector).

The fragment is keyed by `fragment_id` (idempotent upsert).
If `fragment_id` is not provided, a deterministic UUID is generated from
(org_id, episode_id, text) so duplicate POSTs with the same text are idempotent.

## Request body

- ActiveFragmentIngestRequest: Ingest a single memory fragment into the active (short-term) episodic store.
  - `agent_id` string, required: Agent identifier
  - `user_hash` string, nullable: Hashed user ID (never raw PII). If omitted, backend derives it from authenticated org_id + user_id.
  - `episode_id` string, required: Logical episode/conversation ID
  - `fragment_id` string, nullable: Idempotency key; auto-generated UUID if omitted
  - `text` string, required: Raw fragment text (1–4096 chars, not blank)
  - `entities` string[], nullable: Extracted entity strings
  - `skip_enrichment` boolean: Skip LLM enrichment (entities/inference) for benchmark throughput runs
  - `timestamp_ms` integer, nullable: Fragment timestamp (ms since epoch); server time if omitted
  - `metadata` object, nullable: Opaque metadata forwarded to the vector store
  - `scope` string, nullable: Optional explicit write scope "<kind>:<value>" (kinds: user/team/org/project). Must be within the caller's visible scopes; defaults to user:<user_id>.
  - `inactivity_timeout_seconds` integer, nullable: Idle time in seconds after which this active-memory episode is closed and consolidated into long-term memory. Stored on the episode (later writes without it keep it). Omitted: the org default, else 1800 (30 min). Bounds: 300-86400.

## Response `200`

Successful Response

- ActiveFragmentIngestResponse
  - `ok` boolean, required
  - `fragment_id` string, required
  - `episode_id` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/metacognition/apis/tex-api.md) - [All operations](https://skmtc.dev/metacognition/apis/tex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/metacognition/apis/tex-api/revisions/3bef47e50f2e?raw)