api-reference

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

Branches

Governance

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

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

Admin (Master key required)

Plugin Admin (Master key required)

Health (no auth)

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