Cortex API

Recall the most relevant memories for a query, ranked relevance-first. Time words in the query are search text, not a date filter — pass a session_id to switch to a deterministic session transcript instead.

• items[] — most-relevant first. Every item carries a stable trio on every tier: content (string), entry_id (string — pass to memory.forget), source_tier (string, e.g. L1_pulse, L3_semantic, L3_archive). Optional per-tier fields: key, timestamp, category, confidence, outcome, action, access_count, context. Engine internals and any credential id are masked at the edge.
• degraded (bool) — true means retrieval did not complete reliably, so an empty items is not "no memories".
• store_status ∈ {populated, empty, unknown} — an empty result with a status other than populated may mean a wiped or absent store, not a genuine no-match.
• error (string, optional) — present on a 4xx / contract fault.

curl -sS "$CONDUIR_BASE/api/cortex/mcp" \
  -H "Authorization: ApiKey $CORTEX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"memory.recall","arguments":{"query":"pilot decision","max_results":5}}'

{ "result": {
    "items": [
      { "content": "The FTSE100 pilot prospect is confirmed.",
        "entry_id": "mcp_9f3c…", "source_tier": "L3_archive" }
    ],
    "degraded": false,
    "store_status": "populated"
} }

Write one durable checkpoint. Idempotent per idempotency_key. Store no secrets and no raw transcripts.

• status ∈ {persisted, rejected, unknown}. persisted only when the store reports episodes stored and not partial; a partial / zero / 4xx / 5xx write is rejected; a post-send timeout or transport error is unknown (the write may still have landed).
• memory_ids[]: Cortex's write path does not echo stored ids, so the edge derives the entry_id from the idempotency key (mcp_ + sha256). That is the id memory.recall returns for the row.
• outcome_known (bool, on unknown), reason (string), replay (bool — true when an idempotency-cache hit replays a prior persisted result).

curl -sS "$CONDUIR_BASE/api/cortex/mcp" \
  -H "Authorization: ApiKey $CORTEX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"memory.remember","arguments":{
        "content":"Cross-vendor memory proven via one key.",
        "idempotency_key":"note-2026-08-21-1",
        "content_kind":"decision"}}'

{ "result": {
    "idempotency_key": "note-2026-08-21-1",
    "status": "persisted",
    "memory_ids": ["mcp_1a2b…"]
} }

Suppress specific entries from future recall. This is a reversible, tenant-scoped un-index tombstone — it does not destroy the underlying records. Physical hard-deletion is a separate operator-governed capability.

• status ∈ {forgotten, not_forgotten}. forgotten only when the store confirms; an unreachable / 4xx / 5xx Cortex is not_forgotten, never laundered.
• Per-id counters that sum to requested: tombstoned, already_forgotten, not_found, unknown. results[] gives per-id {entry_id, status} in request order.
• activity_confirmed (bool, present when status == forgotten) — true = tombstone committed and its audit receipt was durably recorded; false = the rows ARE forgotten but the receipt could not be written (the delete is authoritative regardless).

curl -sS "$CONDUIR_BASE/api/cortex/mcp" \
  -H "Authorization: ApiKey $CORTEX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"memory.forget","arguments":{
        "entry_ids":["mcp_9f3c…"],
        "reason":"superseded"}}'

{ "result": {
    "status": "forgotten",
    "requested": 1, "tombstoned": 1,
    "already_forgotten": 0, "not_found": 0, "unknown": 0,
    "results": [ { "entry_id": "mcp_9f3c…", "status": "tombstoned" } ],
    "activity_confirmed": false
} }

Reachability check only. It does not prove a recall result exists or a write persisted.

None. additionalProperties: false, empty properties.

• status ∈ {ready, unavailable} — a bare reachability signal, no degraded or detail sub-state.

curl -sS "$CONDUIR_BASE/api/cortex/mcp" \
  -H "Authorization: ApiKey $CORTEX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"memory.health","arguments":{}}'

{ "result": { "status": "ready" } }

Search memory by time and session — the read memory.recall cannot do, because recall ranks by relevance and treats time words as text. Truly read-only: it does not bump access counts and records no activity receipt.

• episodes[] — each carries entryId, sessionId, agentName, action, content, outcome, timestamp, supersedesEntryId, originChannel. Credential ids are redacted at the edge.
• count, degraded, and an optional error.

curl -sS "$CONDUIR_BASE/api/cortex/mcp" \
  -H "Authorization: ApiKey $CORTEX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"cortex_search","arguments":{"limit":10,"order":"desc"}}'

{ "result": {
    "episodes": [
      { "entryId": "mcp_9f3c…", "sessionId": "sess-42",
        "agentName": "assistant", "action": "remember",
        "content": "Cross-vendor memory proven via one key.",
        "outcome": "persisted", "timestamp": 1755734400,
        "supersedesEntryId": null, "originChannel": "mcp" }
    ],
    "count": 1,
    "degraded": false
} }

Explore the entity relationship graph. Pure read — no reinforcement, no receipt.

• entities[] — name, entity_type, mention_count, first_seen, last_seen, related_episodes.
• relationships[] — source, target, type, weight.
• degraded, and an optional error.

curl -sS "$CONDUIR_BASE/api/cortex/mcp" \
  -H "Authorization: ApiKey $CORTEX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"cortex_entity","arguments":{"query":"pilot","top_n":3}}'

{ "result": {
    "entities": [
      { "name": "Pilot", "entity_type": "concept", "mention_count": 4,
        "first_seen": 1755648000, "last_seen": 1755734400,
        "related_episodes": ["mcp_9f3c…"] }
    ],
    "relationships": [
      { "source": "Pilot", "target": "Prospect", "type": "associated_with", "weight": 0.72 }
    ],
    "degraded": false
} }