The core surface: retrieve a governed bundle, write proposals, and manage records over their lifecycle.
POST/api/memory/retrieveKey optional
Governed retrieval → a token-budgeted, explainable context bundle. The one billable call.
Request
| Field | Type | Description |
|---|
| task_context * | string (1–4000) | The retrieval query. |
| project_id | string | Scope. Default project_memrails. |
| agent_id | string | Optional finer scope. |
| max_tokens | integer (1–8000) | Context token budget. |
| retrieval_mode | 'exact'|'tree'|'hybrid'|'hot'|'debug' | Default tree. |
| include_evidence | boolean | Attach evidence references. |
| include_disputed | boolean | Include disputed memories (off by default). |
| include_packet | boolean | Also synthesize a compressed packet. |
Response
{ context_bundle_id, retrieval_id, scope, mode,
memories: [{ memory_id, summary, content, confidence, reason_selected, score, tokens }],
omitted: [{ memory_id, reason }],
tokens_returned, token_budget, retrieval_trace, packet,
usage: { billable_retrievals, credits_remaining, credit_exhausted }, latency_ms }
POST/api/memory/writeAPI key
Governed write — deduplicated and contradiction-checked. Returns a record, not a silent mutation.
Request
| Field | Type | Description |
|---|
| content * | string (1–8000) | The memory body. |
| summary | string (≤400) | One-line summary. |
| memory_type | enum | decision · preference · note · summary · extraction · correction · constraint · claim. |
| confidence | number (0–1) | Calibrated confidence. |
| sensitivity | 'normal'|'sensitive'|'restricted' | Handling class. |
| tags | string[] | Retrieval labels. |
| index_path | string | MemoryIndex node path. |
| source | object | { type, id, ref, hash } provenance. |
Response
{ memory_id, status: "active" | "deduplicated", contradicts?: [], dedup_of?: "mem_…" }
GET/api/memory/{id}Key optional
Read a single memory record by id (scoped to the caller).
Response
MemoryRecord — { memory_id, scope, memory_type, status, confidence,
content, summary, tags, contradictions, index_path, current_version, created_at, … }
DELETE/api/memory/{id}API key
Tombstone a memory (soft delete; canonical body preserved for audit). Optional ?reason=.
Response
{ memory_id, status: "tombstoned" }
POST/api/memory/{id}/supersedeAPI key
Mark a memory superseded and optionally point it at a replacement (by id or inline).
Request
| Field | Type | Description |
|---|
| reason | string (≤500) | Why it was superseded. |
| new_memory_id | string | Existing replacement. Mutually exclusive with new_memory. |
| new_memory | object | Inline replacement (same shape as write). |
Response
{ superseded: "mem_…", replacement: "mem_…" | null }
POST/api/memory/{id}/disputeAPI key
Flag a memory as contested — halves confidence and excludes it from retrieval by default.
Request
| Field | Type | Description |
|---|
| reason * | string (1–500) | Why it is disputed. |
Response
{ memory_id, status: "disputed", confidence }
GET/api/memory/exportKey optional
Export the caller’s registry — memory is file-canonical and Git-versioned. No lock-in; read it all out any time.
Request
| Field | Type | Description |
|---|
| format | 'json' | 'jsonl' | 'markdown' | Query param. Default json. |
| project_id | string | Query param. Filter to one project. |
Response
json: { count, artifact_ref, records[] } · jsonl: ndjson stream · markdown: text/markdown
GET/api/memory/mapKey optional
Project the MemoryIndex tree for a project (?project_id=).
Response
{ project_id, map } — the nested index tree.
POST/api/memory/queryPublic
Synthesize a compressed packet over the curated corpus via the L1–L5 retrieval stack — cheap filters first, compression as last resort (public).
Request
| Field | Type | Description |
|---|
| query * | string (1–2000) | The question. |
| intent | 'answer'|'summarize'|'compare'|'extract'|'refactor'|'route' | Synthesis intent. |
| max_tokens | integer (1–2000) | Packet token cap. |
Response
{ packet_id, packet, confidence, tokens, contradictions_surfaced,
evidence: [{ claim_id, weight, source_file }], input_hash, output_hash, resolved_layer }