api-reference

Category: Testing & Security | Uploader: matrixorigin | Downloads: 0 | Version: v1.0（Latest）
Memoria REST API endpoints, request/response formats, auth, rate limits. Use when calling or implementing API endpoints.
Changelog: Source: GitHub https://github.com/matrixorigin/Memoria
Directory Structure

Current level: skills/api-reference/
📄 SKILL.md 5.7 KB
SKILL.md

---
name: api-reference
description: Memoria REST API endpoints, request/response formats, auth, rate limits. Use when calling or implementing API endpoints.
---

## Memory CRUD

### List: `GET /v1/memories?limit=50&cursor=...&memory_type=semantic`

Response: `{ "items": [...], "next_cursor": "..." }`

### Store: `POST /v1/memories`

```json
{ "content": "...", "memory_type": "semantic", "session_id": null }
```
Returns `201` with `MemoryResponse`.

Types: `semantic` (default), `profile`, `procedural`, `working`, `tool_result`

### Batch Store: `POST /v1/memories/batch`

```json
{ "memories": [{ "content": "..." }, { "content": "...", "memory_type": "profile" }] }
```

### Retrieve: `POST /v1/memories/retrieve`

Hybrid vector + fulltext search, ranked by relevance.

```json
{ "query": "...", "top_k": 10, "memory_types": ["semantic"], "session_id": null, "explain": false }
```

`explain`: `false` | `true` (timing) | `"verbose"` (detailed) | `"analyze"` (full diagnostics)

### Search: `POST /v1/memories/search`

```json
{ "query": "...", "top_k": 10, "explain": false }
```

Same as retrieve but without session prioritization.

### Correct by ID: `PUT /v1/memories/{id}/correct`

```json
{ "new_content": "...", "reason": "..." }
```

### Correct by Query: `POST /v1/memories/correct`

```json
{ "query": "...", "new_content": "...", "reason": "..." }
```

Finds best match via semantic search, corrects it. Response includes `matched_memory_id`.

### Delete: `DELETE /v1/memories/{id}?reason=...`

### Bulk Purge: `POST /v1/memories/purge`

```json
{ "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": "..." }`

### Observe: `POST /v1/observe`

```json
{ "messages": [{ "role": "user", "content": "..." }] }
```

### Profile: `GET /v1/profiles/me`

## Snapshots

| 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 |

## Branches

| 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 |

## Governance

| Endpoint | Cooldown | Description |
|----------|----------|-------------|
| `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) |

LLM-free alternatives: `POST /v1/reflect/candidates`, `POST /v1/extract-entities/candidates` — return raw data for the calling agent to process.

## Episodic Memory

### Generate Summary: `POST /v1/sessions/{session_id}/summary`

```json
{ "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.

### Poll Task: `GET /v1/tasks/{task_id}`

Response: `{ "task_id": "...", "status": "completed|processing|failed", "result": {...} }`

## Auth

| 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 |

## Admin (Master key required)

| 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`) |

## Plugin Admin (Master key required)

| 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 |

## Health (no auth)

| Endpoint | Response | Use |
|----------|----------|-----|
| `GET /health` | `"ok"` | Liveness probe |
| `GET /health/instance` | `{ "status": "ok", "instance_id": "..." }` | Readiness probe |

## Rate Limits

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.

## Error Format

```json
{ "detail": "Error message" }
```

Status codes: 400 (validation), 401 (auth), 403 (forbidden), 404 (not found), 409 (conflict), 429 (rate limit), 500 (internal).
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
api-reference

Directory Structure

SKILL.md

Report

Notice
