---
title: "Extract sourced memories from a bounded conversation"
method: POST
path: "/v1/extract_memories"
tags: ["memory"]
---

# Extract sourced memories from a bounded conversation

`POST /v1/extract_memories`

## Request

- Base URL: `https://api.contextdb.ai`
- URL: `https://api.contextdb.ai/v1/extract_memories`
- Auth: HTTP bearer

Runs a bounded, extractive formation loop over PII-processed turns.
Every candidate cites an exact quote and turn index. `propose` returns
candidates without writing; `commit` writes validated candidates
through the same scoped trust and slot-deduplication path as remember.

Provider failures return a well-formed terminal run result with a
named status. No raw transcript is stored in the formation-run ledger.

## Headers

- `Idempotency-Key` string

## Request body

- ExtractMemoriesRequest
  - `user_id` string, required: End-user memory partition key. Not an identity assertion.
  - `turns` FormationTurn[], required
    - `speaker` 'user' | 'agent' | 'third_party', required
    - `content` string, required
  - `mode` 'propose' | 'commit'
  - `source_id` string, nullable
  - `max_memories` integer

## Response `200`

Formation completed or found no durable memories

- FormationResponse
  - `run_id` string, required
  - `status` 'completed' | 'no_memories' | 'provider_unavailable' | 'provider_error' | 'invalid_output' | 'timed_out' | 'budget_exhausted' | 'storage_error' | 'internal_error' | 'interrupted', required
  - `mode` 'propose' | 'commit', required
  - `attempts` integer, required
  - `candidates` FormationCandidate[], required
    - `content` string, nullable, required
    - `quote` string, nullable, required: Exact PII-processed quote supporting the candidate
    - `turn_indexes` integer[], required
    - `source` 'user_stated' | 'agent_inferred' | 'third_party', required: Who vouches for the claim. Required on writes.
    - `confidence` number, required
    - `action_relevant` boolean, required
    - `entity` string, nullable, required
    - `attribute` string, nullable, required
    - `operation` 'add' | 'update' | 'delete' | 'noop', required
    - `target_memory_id` string, nullable, required
    - `noop_reason` string, nullable, required
    - `candidate_key` string, required
  - `memories` Memory[], required
    - `id` string, required
    - `content` string, required: Stored content with PII redacted as `[TYPE]` placeholders
    - `user_id` string, nullable, required
    - `epistemic_source` 'user_stated' | 'agent_inferred' | 'third_party', required: Who vouches for the claim. Required on writes.
    - `confidence` number, required
    - `corroboration_count` integer, required
    - `action_relevant` boolean, required
    - `requires_confirmation` boolean, required
    - `confirmed` boolean, required
    - `independent_corroboration` integer, required
    - `injection_suspect` boolean, required
    - `entity_key` string, nullable, required
    - `attribute_key` string, nullable, required
    - `valid_until` string, date-time, nullable, required
    - `superseded_by` string, nullable, required
  - `memory_ids` string[], required
  - `operation_results` FormationOperationResult[], required
    - `candidate_key` string, required
    - `requested_operation` 'add' | 'update' | 'delete' | 'noop', required
    - `applied_operation` 'add' | 'update' | 'delete' | 'noop', required
    - `outcome` 'added' | 'updated' | 'deleted' | 'noop' | 'contested', required
    - `memory_id` string, nullable, required
    - `previous_memory_ids` string[], required
    - `deleted_memory_ids` string[], required
    - `target_memory_id` string, nullable, required
    - `noop_reason` string, nullable, required
  - `operation_counts` FormationOperationCounts, required
    - `added` integer, required
    - `updated` integer, required
    - `deleted` integer, required
    - `noop` integer, required
  - `memory_version` integer, nullable, required
  - `primary_wal_lsn` string, nullable, required
  - `error_code` string, nullable, required
  - `request_id` string, required

## Other responses

- `400`: Malformed request or failed validation
- `401`: Missing, malformed, unknown, or revoked API key
- `403`: Authenticated but not allowed (entitlement or billing state)
- `409`: The key was reused with a different request, an identical request is still running, or a previous process ended with an ambiguous outcome.
- `413`: Body or batch exceeds the configured cap
- `429`: The client IP/project exceeded its request rate, or the project's idempotency retention capacity is full until older keys expire.
- `502`: Provider failed or returned invalid output after bounded retry
- `503`: Provider unavailable, queue exhausted, or storage failed
- `504`: Provider timed out within the formation budget

---

[API](https://skmtc.dev/contextdb/apis/contextdb-cloud-data-plane-api.md) · [All operations](https://skmtc.dev/contextdb/apis/contextdb-cloud-data-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contextdb/apis/contextdb-cloud-data-plane-api/revisions/9e441d2e21a7?raw)