api-reference

## 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. ### Full-text Search: `POST /v1/memories/fulltext-search` Pure MatrixOne lexical full-text search with optional exact SQL pre-filters. It does not generate embeddings or run vector, graph, hybrid, temporal, or confidence scoring and is intentionally not exposed as an MCP tool. ```json { "query": "MatrixOne database", "extra_metadata_filter": {"scene": "incident", "rank": 2}, "subject_id": "subject-123", "memory_types": ["semantic"], "session_id": "session-123", "trust_tier": "T2", "branch": "main", "limit": 20 } ``` All supplied filters use `AND`. `session_id` is strict: unscoped memories with `session_id: null` are not included. This differs from retrieve/search session scoping, which can include unscoped memories. Metadata equality preserves JSON type families: number `2` may equal `2.0`, while string `"2"` does not equal number `2`. Query length is limited to 4096 UTF-8 bytes and `limit` to 1–100. Returns a plain memory array ordered by MatrixOne full-text score and then `memory_id`; each result exposes the score as `retrieval_score`. ### 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/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 & Adaptive Retrieval Feedback signals improve retrieval ranking over time. The system learns which memories are useful/irrelevant for each user. ### How It Works 1. User retrieves memories via `memory_retrieve` or `memory_search` 2. Agent uses memories to answer questions 3. Agent calls `memory_feedback` with signal based on outcome 4. System adjusts `feedback_weight` parameter (auto-tuned daily by governance) 5. Future retrievals rank memories higher/lower based on accumulated feedback **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. ### Record Feedback: `POST /v1/memories/{id}/feedback` ```json { "signal": "useful", "context": "helped answer the question" } ``` Signals: `useful`, `irrelevant`, `outdated`, `wrong` Returns `201` with `{ "feedback_id": "..." }` **Errors**: - `404`: Memory not found - `422`: Invalid signal value ### Get Stats: `GET /v1/feedback/stats` Returns aggregated feedback counts: ```json { "useful": 42, "irrelevant": 5, "outdated": 3, "wrong": 1 } ``` ### Get by Tier: `GET /v1/feedback/by-tier` Returns feedback breakdown by trust tier (T1-T4). ### Tune Parameters: `POST /v1/retrieval-params/tune` Manually adjust retrieval scoring weights: ```json { "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 range - `200` with `"message"`: Not enough feedback (requires ≥10 signals) ### Get Parameters: `GET /v1/retrieval-params` Returns current retrieval parameters for the user. ### Related Tools | 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 | ## 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 |