// Memoria REST API endpoints, request/response formats, auth, rate limits. Use when calling or implementing API endpoints.
Use Memoria as OpenClaw's durable memory slot. Triggers: "remember this", "save to memory", "what do you remember", "continue from last time", "forget this", "correct memory", "take a snapshot", "rollback memory", "branch memory", "merge memory", "use long-term memory".
Install Memoria and configure MCP for AI tools (Kiro, Cursor, Claude Code, Codex, Gemini CLI). Decision tree for Cloud vs self-hosted mode, database, embedding provider. Use when helping users set up Memoria.
Deploy Memoria with Docker Compose or Kubernetes. Environment variables, multi-instance setup, security. Use when deploying or configuring Memoria.
Memoria codebase structure, workspace layout, key traits, database tables, config patterns, and testing conventions. Use when navigating or modifying Memoria code.
Run embedding on-device with ONNX Runtime. Build from source, model selection, offline mode. Use when setting up local embedding without an API key.
Create, test, sign, and publish Memoria governance plugins. Covers Rhai and gRPC runtimes, manifest format, lifecycle. Use when developing or managing plugins.
| name | api-reference |
| description | Memoria REST API endpoints, request/response formats, auth, rate limits. Use when calling or implementing API endpoints. |
GET /v1/memories?limit=50&cursor=...&memory_type=semanticResponse: { "items": [...], "next_cursor": "..." }
POST /v1/memories{ "content": "...", "memory_type": "semantic", "session_id": null }
Returns 201 with MemoryResponse.
Types: semantic (default), profile, procedural, working, tool_result
POST /v1/memories/batch{ "memories": [{ "content": "..." }, { "content": "...", "memory_type": "profile" }] }
POST /v1/memories/retrieveHybrid vector + fulltext search, ranked by relevance.
{ "query": "...", "top_k": 10, "memory_types": ["semantic"], "session_id": null, "explain": false }
explain: false | true (timing) | "verbose" (detailed) | "analyze" (full diagnostics)
POST /v1/memories/search{ "query": "...", "top_k": 10, "explain": false }
Same as retrieve but without session prioritization.
PUT /v1/memories/{id}/correct{ "new_content": "...", "reason": "..." }
POST /v1/memories/correct{ "query": "...", "new_content": "...", "reason": "..." }
Finds best match via semantic search, corrects it. Response includes matched_memory_id.
DELETE /v1/memories/{id}?reason=...POST /v1/memories/purge{ "memory_ids": ["id1"], "memory_types": ["working"], "before": "2026-01-01T00:00:00", "reason": "..." }
All fields optional. Auto-creates safety snapshot. Response: { "purged": N, "snapshot_name": "..." }
POST /v1/observe{ "messages": [{ "role": "user", "content": "..." }] }
GET /v1/profiles/me| Endpoint | Description |
|---|---|
POST /v1/snapshots | Create: { "name": "...", "description": "..." } |
GET /v1/snapshots | List all |
GET /v1/snapshots/{name}?detail=brief&limit=50&offset=0 | Detail (brief/normal/full) |
DELETE /v1/snapshots/{name} | Delete |
GET /v1/snapshots/{name}/diff?limit=50 | Diff vs current state |
POST /v1/snapshots/{name}/rollback | Restore to snapshot |
| Endpoint | Description |
|---|---|
POST /v1/branches | Create: { "name": "..." } |
GET /v1/branches | List all |
POST /v1/branches/{name}/checkout | Switch to branch |
GET /v1/branches/{name}/diff | Preview changes vs main |
POST /v1/branches/{name}/merge | Merge into main: { "strategy": "append" } |
DELETE /v1/branches/{name} | Delete |
| Endpoint | Cooldown | Description |
|---|---|---|
POST /v1/governance?force=false | 1 hour | Quarantine low-confidence, cleanup stale |
POST /v1/consolidate?force=false | 30 min | Detect contradictions, fix orphans |
POST /v1/reflect?force=false | 2 hours | Synthesize insights (needs LLM) |
POST /v1/extract-entities | — | Extract entities, build graph (needs LLM) |
POST /v1/extract-entities/link | — | Manually link entities to memories |
GET /v1/entities | — | List user's entities |
LLM-free alternatives: POST /v1/reflect/candidates, POST /v1/extract-entities/candidates — return raw data for the calling agent to process.
Feedback signals improve retrieval ranking over time. The system learns which memories are useful/irrelevant for each user.
memory_retrieve or memory_searchmemory_feedback with signal based on outcomefeedback_weight parameter (auto-tuned daily by governance)Quantified Impact: With default feedback_weight=0.1, a memory with 3 useful signals scores ~1.3x higher; one with 2 wrong signals scores ~0.9x lower. At feedback_weight=0.3, these become ~1.9x and ~0.7x respectively.
POST /v1/memories/{id}/feedback{ "signal": "useful", "context": "helped answer the question" }
Signals: useful, irrelevant, outdated, wrong
Returns 201 with { "feedback_id": "..." }
Errors:
404: Memory not found422: Invalid signal valueGET /v1/feedback/statsReturns aggregated feedback counts:
{ "useful": 42, "irrelevant": 5, "outdated": 3, "wrong": 1 }
GET /v1/feedback/by-tierReturns feedback breakdown by trust tier (T1-T4).
POST /v1/retrieval-params/tuneManually adjust retrieval scoring weights:
{ "feedback_weight": 0.15 }
feedback_weight: 0.01–0.5 (default 0.1). Higher = feedback has more impact on ranking.
Auto-tuning: POST /v1/retrieval-params/tune with empty body triggers automatic tuning based on accumulated feedback.
Errors:
422: feedback_weight out of range200 with "message": Not enough feedback (requires ≥10 signals)GET /v1/retrieval-paramsReturns current retrieval parameters for the user.
| Tool | Relationship |
|---|---|
memory_retrieve / memory_search | Feedback affects their ranking results |
memory_correct | Use instead of wrong feedback when content needs fixing |
memory_purge | Use instead of outdated feedback when memory should be deleted |
memory_governance | Auto-tunes feedback_weight daily based on feedback patterns |
POST /v1/sessions/{session_id}/summary{ "mode": "full", "sync": true, "generate_embedding": true }
Modes: full (topic/action/outcome) | lightweight (3-5 bullets, max 3/session)
Requires LLM (LLM_API_KEY). Returns 503 without it.
GET /v1/tasks/{task_id}Response: { "task_id": "...", "status": "completed|processing|failed", "result": {...} }
| Endpoint | Auth | Description |
|---|---|---|
POST /auth/keys | Master | Create API key: { "user_id": "...", "name": "..." } |
GET /auth/keys | Bearer | List my keys |
GET /auth/keys/{id} | Bearer | Get key detail |
PUT /auth/keys/{id}/rotate | Bearer | Rotate (revoke old, issue new) |
DELETE /auth/keys/{id} | Bearer | Revoke |
| Endpoint | Description |
|---|---|
GET /admin/stats | System stats |
GET /admin/users?cursor=...&limit=100 | List users |
GET /admin/users/{id}/stats | User stats |
GET /admin/users/{id}/keys | User's API keys |
DELETE /admin/users/{id}/keys | Revoke all user keys |
DELETE /admin/users/{id} | Deactivate user |
POST /admin/governance/{id}/trigger?op=governance | Trigger governance (governance/consolidate/reflect) |
| Endpoint | Description |
|---|---|
GET/POST /admin/plugins/signers | List/add trusted signers |
POST /admin/plugins | Publish plugin (base64 files) |
POST /admin/plugins/:key/:ver/review | Review: { "status": "active" } |
POST /admin/plugins/:key/:ver/score | Score: { "score": 4.5 } |
GET/POST /admin/plugins/domains/:d/bindings | List/create binding rules |
POST /admin/plugins/domains/:d/activate | Activate binding |
GET /admin/plugins | List packages |
GET /admin/plugins/matrix | Compatibility matrix |
GET /admin/plugins/events | Audit events |
| Endpoint | Response | Use |
|---|---|---|
GET /health | "ok" | Liveness probe |
GET /health/instance | { "status": "ok", "instance_id": "..." } | Readiness probe |
Per API key, sliding window. Key limits: store 300/min, retrieve 300/min, batch 60/min, purge 30/min, consolidate/reflect 10/min. Returns 429 when exceeded.
{ "detail": "Error message" }
Status codes: 400 (validation), 401 (auth), 403 (forbidden), 404 (not found), 409 (conflict), 429 (rate limit), 500 (internal).