API Reference

Turn raw content into a Unified Memory Object. Runs the pipeline (capture, normalize, extract, enrich, parse, embed, validate) and returns the new UMO with a quality score and a provenance receipt.

curl -X POST https://api.memoryintelligence.io/v1/process \
  -H "Authorization: Bearer $MI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Sarah proposed provenance hashing for the deck.","source":"meeting-notes"}'

{
  "umo_id": "019d9cd5-1be8-8d07-0f31-45018cfe4b68",
  "quality_score": 0.72,
  "created_at": "2026-07-05T19:05:05Z"
}

Capture many items in one call. Send an array of content items; each becomes its own UMO.

curl -X POST https://api.memoryintelligence.io/v1/batch \
  -H "Authorization: Bearer $MI_API_KEY" -H "Content-Type: application/json" \
  -d '{"items":[{"content":"First note."},{"content":"Second note."}]}'

{ "results": [
  { "index": 0, "success": true, "umo_id": "019d..." },
  { "index": 1, "success": true, "umo_id": "019e..." }
] }

Capture from a media file, sent as multipart form data.

curl -X POST https://api.memoryintelligence.io/v1/upload \
  -H "Authorization: Bearer $MI_API_KEY" -F "file=@notes.pdf"

{ "umo_id": "019d...", "summary": "Q3 review moved to the 15th.", "quality_score": 0.5 }

A paginated list of the authenticated user's UMOs. Use for browsing, sync, or building a custom UI.

curl -s "https://api.memoryintelligence.io/v1/memories?limit=20" \
  -H "Authorization: Bearer $MI_API_KEY"

{ "items": [
  { "umo_id": "019d...", "summary": "...", "quality_score": 0.75, "created_at": "..." }
], "total_count": 128, "has_more": true }

Semantic search: run a natural-language query and get back raw ranked UMOs, each with a citation to the source. No LLM is involved. For a written, synthesized answer instead, use POST /v1/ask. Naming note: the SDK verb mi.ask() maps to this endpoint (search), not to POST /v1/ask.

curl -X POST https://api.memoryintelligence.io/v1/memories/query \
  -H "Authorization: Bearer $MI_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"What do I know about funding?","limit":5}'

{ "results": [
  { "umo_id": "019d...", "content_text": "Sarah mentioned a seed round.", "score": 0.88 }
], "total_count": 1, "has_more": false }

Ask a question and get a written answer synthesized by an LLM, grounded in your memories and returned with inline citations. This is distinct from /v1/memories/query, which returns raw ranked results with no LLM. (The SDK's mi.ask() calls query, not this endpoint.)

curl -X POST https://api.memoryintelligence.io/v1/ask \
  -H "Authorization: Bearer $MI_API_KEY" -H "Content-Type: application/json" \
  -d '{"question":"What did Sarah propose?","model":"spaceagent"}'

{
  "answer": "Sarah proposed provenance hashing for the deck [1].",
  "citations": [
    { "index": 1, "umo_id": "019d...", "title": "Meeting notes", "snippet": "Sarah proposed...", "similarity": 0.88 }
  ],
  "confidence": 0.82,
  "method": "spaceagent",
  "question_type": "factual"
}

List the models available to /v1/ask, split into local (free, run on MI) and cloud (bring-your-own-key).

curl -s https://api.memoryintelligence.io/v1/ask/models \
  -H "Authorization: Bearer $MI_API_KEY"

{
  "local": [ { "id": "spaceagent", "default": true }, { "id": "mistral" } ],
  "cloud": [ { "id": "openai:gpt-4o-mini", "requires_key": true } ]
}

Fetch a single UMO by its umo_id.

curl -s https://api.memoryintelligence.io/v1/memories/$UMO_ID \
  -H "Authorization: Bearer $MI_API_KEY"

{
  "umo_id": "019d...",
  "summary": "Sarah proposed provenance hashing for the deck.",
  "entities": [ { "text": "Sarah", "type": "PERSON" } ],
  "svo_triples": [ { "subject": "Sarah", "verb": "PROPOSE", "object": "provenance hashing" } ],
  "topics": [ { "name": "deck" } ],
  "quality_score": 0.72
}

Compare two existing memories and get a similarity score plus relationship info. Useful for deduplication, linking related memories, or measuring drift.

curl -X POST https://api.memoryintelligence.io/v1/match \
  -H "Authorization: Bearer $MI_API_KEY" -H "Content-Type: application/json" \
  -d '{"source_ulid":"019d...","candidate_ulid":"019e..."}'

{ "score": 0.78, "similarity": 0.78, "relationship": "related" }

The receipt for a memory: its source, content hash, and provenance chain, cryptographically verifiable.

curl -s https://api.memoryintelligence.io/v1/memories/$UMO_ID/proof \
  -H "Authorization: Bearer $MI_API_KEY"

{
  "valid": true,
  "hash_chain_valid": true,
  "first_published": "2026-07-05T19:05:05Z",
  "audit_proof": {
    "content_hash": "024580fe...",
    "semantic_hash": "29825202...",
    "verification_mode": "cryptographic",
    "chain_tampered": false
  }
}

A plain-language explanation of what the pipeline pulled out and why a memory matched. The raw entities and relationships live on the UMO itself (see retrieve).

curl -s https://api.memoryintelligence.io/v1/memories/$UMO_ID/explain \
  -H "Authorization: Bearer $MI_API_KEY"

{
  "human": {
    "summary": "Sarah proposed provenance hashing for the deck.",
    "key_reasons": [ "Extracted 2 entities", "Identified 1 relationship (SVO triple)" ]
  },
  "audit": { "verification_mode": "cryptographic", "reproducible": true }
}

Delete a memory. Returns a deletion receipt so the removal itself is auditable.

curl -X DELETE https://api.memoryintelligence.io/v1/memories/$UMO_ID \
  -H "Authorization: Bearer $MI_API_KEY"

{ "forgotten": true, "umo_id": "019d...", "deleted_at": "...", "receipt": "58684dc7..." }

Status for the calling API key: its owner, plan tier, and quota limits. Authenticated with the API key itself — use it to confirm a key works and which account it belongs to.

curl -s https://api.memoryintelligence.io/v1/account \
  -H "Authorization: Bearer $MI_API_KEY"

{
  "account": { "user_id": "019d...", "workspace_id": null },
  "key": { "key_id": "key_...", "tier": "beta", "status": "active" },
  "plan": { "tier": "beta", "umo_limit": null, "search_limit": null, "beta": true }
}

Liveness check. No auth required.

curl -s https://api.memoryintelligence.io/health

{ "status": "healthy" }