api-reference

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

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

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

Retrieve: POST /v1/memories/retrieve

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

Search: POST /v1/memories/search

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

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

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

Correct by Query: POST /v1/memories/correct

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

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

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

{ "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:

{ "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:

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

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

{ "detail": "Error message" }

Status codes: 400 (validation), 401 (auth), 403 (forbidden), 404 (not found), 409 (conflict), 429 (rate limit), 500 (internal).