{"openapi":"3.1.0","info":{"title":"Memoreal Cloud API & MCP Server","version":"1.0.0","description":"Hosted multi-tenant REST API and Streamable HTTP MCP endpoint for Memoreal Cloud. Organization isolation is enforced automatically via your API key; pass logical project/wing namespaces (never internal org: prefixes)."},"servers":[{"url":"https://memoreal.kolivri.com"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"mem_<tier>_<secret>"}}},"paths":{"/v1/health":{"get":{"summary":"Cloud engine health and active memory counts","description":"Return Memoreal Cloud engine status, tier distributions, and memory counts. Supports optional Bearer token to scope counts to your organization.","security":[{"BearerAuth":[]},{}],"responses":{"200":{"description":"Engine health status and memory distribution","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"memory_count":{"type":"integer","example":42},"edge_count":{"type":"integer","example":84},"tier_distribution":{"type":"object","properties":{"Episodic":{"type":"integer"},"Semantic":{"type":"integer"},"Core":{"type":"integer"},"Buffer":{"type":"integer"}}},"namespace_count":{"type":"integer","example":3}}}}}}}}},"/v1/openapi.json":{"get":{"summary":"OpenAPI 3.1.0 specification","description":"Fetch the machine-readable OpenAPI 3.1.0 schema for the Memoreal Cloud REST and MCP API.","security":[],"responses":{"200":{"description":"OpenAPI 3.1.0 JSON schema","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/docs":{"get":{"summary":"Redirect to API documentation","description":"Redirects to the interactive documentation and REST reference on the hosted portal.","security":[],"responses":{"302":{"description":"Found: redirect to /docs#rest","headers":{"Location":{"schema":{"type":"string","example":"/docs#rest"}}}}}}},"/v1/memories":{"post":{"summary":"Store a memory","description":"Store a single memory with tier classification (episodic, semantic, buffer, core), salience weight, and optional metadata context.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"Memory text to persist"},"namespace":{"type":"string","description":"Logical workspace or project namespace (e.g. \"my-project\")"},"type":{"type":"string","enum":["episodic","semantic","buffer","core"],"default":"episodic"},"salience":{"type":"number","minimum":0,"maximum":1,"default":0.5},"context":{"type":"array","items":{"type":"array"},"description":"Array of [key, value] metadata pairs"}}}}}},"responses":{"201":{"description":"Memory created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"namespace":{"type":"string"},"created_at":{"type":"string"},"salience":{"type":"number"},"tier":{"type":"string"}}}}}},"400":{"description":"Missing content or invalid body"},"401":{"description":"Unauthorized: missing or invalid Bearer token"},"402":{"description":"Quota exceeded for billing window"}}},"get":{"summary":"List organization memories","description":"List stored memories in the organization, optionally filtered by namespace.","security":[{"BearerAuth":[]}],"parameters":[{"name":"namespace","in":"query","schema":{"type":"string"},"description":"Filter by workspace namespace"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500},"description":"Max items to return"}],"responses":{"200":{"description":"Array of memories","content":{"application/json":{"schema":{"type":"object","properties":{"memories":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Unauthorized"}}}},"/v1/memories/{id}":{"delete":{"summary":"Forget a memory by ID","description":"Delete a specific memory and incident edges belonging to your organization.","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique memory ID"}],"responses":{"200":{"description":"Memory deletion status","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Memory does not belong to your organization"}}}},"/v1/memories/batch":{"post":{"summary":"Batch encode memories","description":"Atomically store up to 1000 memories in a single call (counts N calls against quota).","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["memories"],"properties":{"namespace":{"type":"string","description":"Default workspace namespace for items"},"memories":{"type":"array","items":{"type":"object","required":["content"],"properties":{"content":{"type":"string"},"type":{"type":"string","enum":["episodic","semantic","buffer","core"]},"salience":{"type":"number","minimum":0,"maximum":1},"namespace":{"type":"string"},"context":{"type":"array"}}}}}}}}},"responses":{"201":{"description":"Batch encoded IDs","content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"encoded":{"type":"integer"}}}}}}}}},"/v1/memories/recall":{"post":{"summary":"Recall ranked memories","description":"Retrieve top memories ranked deterministically by BM25 lex hits, salience, tier boost, and freshness.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"namespace":{"type":"string"},"query":{"type":"string"},"min_salience":{"type":"number","minimum":0,"maximum":1},"limit":{"type":"integer","default":20}}}}}},"responses":{"200":{"description":"Scored memory results and recall trace ID","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object"}},"total_candidates":{"type":"integer"},"latency_ms":{"type":"number"},"trace_id":{"type":"string","nullable":true}}}}}}}}},"/v1/memories/search":{"post":{"summary":"Search memories (alias for recall)","description":"Semantic search over memories in a workspace namespace; equivalent to /v1/memories/recall.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"namespace":{"type":"string"},"query":{"type":"string"},"min_salience":{"type":"number"},"limit":{"type":"integer"}}}}}},"responses":{"200":{"description":"Scored memory results"}}}},"/v1/memories/context":{"post":{"summary":"Build token-budgeted memory context block","description":"Assemble a formatted <memory_context> block combining Core rules, Semantic facts, and Episodic history within a token budget.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"namespace":{"type":"string"},"query":{"type":"string"},"token_budget":{"type":"integer","default":4096}}}}}},"responses":{"200":{"description":"Formed memory context string","content":{"application/json":{"schema":{"type":"object","properties":{"context":{"type":"string"},"memories_used":{"type":"integer"}}}}}}}}},"/v1/context":{"post":{"summary":"Build token-budgeted session context (alias)","description":"Assemble a structured <memory_context> block; alias for /v1/memories/context.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"namespace":{"type":"string"},"query":{"type":"string"},"token_budget":{"type":"integer","default":4096}}}}}},"responses":{"200":{"description":"Formed context string and memories count"}}}},"/v1/memories/feedback":{"post":{"summary":"Submit retrieval feedback (alias)","description":"Record utility feedback on a memory to adjust salience; alias for /v1/feedback.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","useful"],"properties":{"id":{"type":"string","description":"Memory ID"},"useful":{"type":"boolean","description":"Whether the recalled memory was helpful"}}}}}},"responses":{"200":{"description":"Feedback update status"}}}},"/v1/feedback":{"post":{"summary":"Record memory retrieval feedback","description":"Mark a recalled memory as useful or noisy to adjust its ranking and salience.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","useful"],"properties":{"id":{"type":"string"},"useful":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Feedback status","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"boolean"}}}}}}}}},"/v1/consolidate":{"post":{"summary":"Consolidate workspace memories","description":"Trigger memory consolidation in a namespace: merge duplicates and promote high-salience episodic memories to semantic tier.","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"namespace":{"type":"string"}}}}}},"responses":{"200":{"description":"Consolidation status","content":{"application/json":{"schema":{"type":"object","properties":{"namespace":{"type":"string"},"consolidated":{"type":"boolean"}}}}}}}}},"/v1/reflect":{"post":{"summary":"Reflect over memories in namespace","description":"Synthesize established facts and core invariants for higher-order reasoning.","security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"namespace":{"type":"string"},"query":{"type":"string"}}}}}},"responses":{"200":{"description":"Synthesized reflection results"}}}},"/v1/extract":{"post":{"summary":"Extract structured memories from unstructured text","description":"Parse raw notes, markdown headings, or conversational turns and encode them as structured memories.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string"},"namespace":{"type":"string"},"type":{"type":"string","enum":["episodic","semantic","core"],"default":"semantic"}}}}}},"responses":{"201":{"description":"Extracted and encoded memory IDs"}}}},"/v1/stats":{"get":{"summary":"Namespace memory and quota statistics","description":"Return memory counts and 30-day API call quota usage for a workspace namespace.","security":[{"BearerAuth":[]}],"parameters":[{"name":"namespace","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Namespace stats and usage","content":{"application/json":{"schema":{"type":"object","properties":{"namespace":{"type":"string"},"memory_count":{"type":"integer"},"used_calls_30d":{"type":"integer"},"api_call_limit":{"type":"integer","nullable":true}}}}}}}}},"/v1/namespaces":{"get":{"summary":"List active namespaces","description":"List distinct workspace namespaces stored under the authenticated organization.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"List of namespace strings","content":{"application/json":{"schema":{"type":"object","properties":{"namespaces":{"type":"array","items":{"type":"string"}}}}}}}}}},"/v1/export":{"get":{"summary":"Export memories","description":"Export all stored memories for the organization, optionally filtered by namespace.","security":[{"BearerAuth":[]}],"parameters":[{"name":"namespace","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Exported memories array","content":{"application/json":{"schema":{"type":"object","properties":{"memories":{"type":"array","items":{"type":"object"}}}}}}}}}},"/v1/memories/import":{"post":{"summary":"Import Markdown or JSON memories","description":"Import Markdown rulebooks (e.g. CLAUDE.md, .cursorrules, AGENTS.md) or Mem0/Zep JSON exports into your namespace.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"namespace":{"type":"string"},"type":{"type":"string","enum":["semantic","core","episodic"],"default":"semantic"},"content":{"type":"string"},"memories":{"description":"Raw markdown string or JSON array of memories"}}}}}},"responses":{"201":{"description":"Imported memory IDs","content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}},"imported":{"type":"integer"},"namespace":{"type":"string"}}}}}}}}},"/v1/import":{"post":{"summary":"Import memories (alias)","description":"Import Markdown or JSON memories; alias for /v1/memories/import.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"namespace":{"type":"string"},"type":{"type":"string"},"content":{"type":"string"},"memories":{}}}}}},"responses":{"201":{"description":"Imported memory IDs"}}}},"/v1/graph":{"get":{"summary":"Interactive memory knowledge graph","description":"Retrieve graph nodes and semantic, supersedes, and temporal edges for visualization.","security":[{"BearerAuth":[]}],"parameters":[{"name":"namespace","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Graph nodes and edges","content":{"application/json":{"schema":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object"}},"edges":{"type":"array","items":{"type":"object"}}}}}}}}}},"/v1/trace/recent":{"get":{"summary":"Recent recall trace inspector","description":"Inspect recent query recall latency, candidate scores, and token activations.","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Recent recall traces","content":{"application/json":{"schema":{"type":"object","properties":{"traces":{"type":"array","items":{"type":"object"}}}}}}}}}},"/v1/rooms/handoff":{"post":{"summary":"Multi-agent specialist wing handoff","description":"Record a structured handoff into a specialist agent wing (architect, reviewer, qa, security, ops).","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["summary"],"properties":{"wing":{"type":"string","enum":["architect","reviewer","qa","security","ops"]},"from_agent":{"type":"string"},"summary":{"type":"string"},"task":{"type":"string"},"files":{"type":"array","items":{"type":"string"}},"memory_ids":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Created handoff memory ID"}}}},"/v1/webhooks/github":{"post":{"summary":"GitHub push and PR review webhook","description":"Receive GitHub push events to index commit blast-radius or PR events to verify against team memory rules.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Webhook processed"},"201":{"description":"Push commits indexed"}}}},"/v1/mcp":{"post":{"summary":"JSON-RPC 2.0 Streamable HTTP MCP Endpoint","description":"JSON-RPC 2.0 Streamable HTTP MCP endpoint exposing the 14 Cloud MCP tools from MCP_TOOL_DEFS: encode_memory, batch_encode, recall_memories, build_context, forget_memory, delete_by_context, feedback, consolidate, health, stats, search_code, explain_code, list_agent_wings, handoff_to_agent. Supports initialize, tools/list, tools/call, resources/list, resources/read, prompts/list, and prompts/get.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"method":{"type":"string","example":"tools/call"},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response result or error","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{},"result":{"type":"object"},"error":{"type":"object"}}}}}},"401":{"description":"Unauthorized"},"402":{"description":"Payment required: API quota exceeded"}}},"get":{"summary":"Streamable HTTP MCP GET handler","description":"Returns HTTP 405 Method Not Allowed per MCP Streamable HTTP specification (send JSON-RPC 2.0 requests via POST /v1/mcp).","security":[],"responses":{"405":{"description":"Method Not Allowed"}}}}}}