ReferenzREST-APISpeicher-API

REST API

Speicher-API

Lesen und schreiben Sie Speicher über die dokumentierten REST- und MCP-Verträge mit expliziten Bereichsgrenzen.

Öffentliche Speicher-Endpunkte und Berechtigungsbereiche

Die nachfolgenden Beispiele verwenden die /v1-Pfade, die im committeten OpenAPI-Vertrag vorhanden sind. Authentifizieren Sie sich mit X-API-Key (oder der vom Server akzeptierten Bearer-Form); Leseoperationen erfordern ein lesefähiges Token und Schreibvorgänge ein schreibfähiges Token. Das OpenAPI-Antwortschema ist für die meisten Speicher-Endpunkte absichtlich typlos gehalten, daher werden die dokumentierten Implementierungsschlüssel separat hervorgehoben, wo der Server sie derzeit zurückgibt. GET /v1/memories liefert derzeit ein Objekt mit memories (Array) und total (Zahl) zurück, diese Eigenschaften sind in OpenAPI jedoch nicht deklariert.

  • Erstellen/Erfassen: POST /v1/remember und POST /v1/memories (201).
  • Auflisten: GET /v1/memories mit limit, offset und path (200).
  • Suchen: GET /v1/memories/search; GET /v1/recall ist dieselbe Suchoperation (200).
  • Kontext zusammenstellen: POST /v1/recall/context (200).
  • Aktualisieren: PATCH /v1/memories/{memory_id}; Löschen: DELETE /v1/memories/{memory_id}.
  • Vergessen: POST /v1/memories/{memory_id}/forget; Wiederherstellen: POST /v1/memories/{memory_id}/restore; Erinnerung abschließen: POST /v1/reminders/{reminder_id}/complete.

Schemas für Erstellungsanfragen

POST /v1/remember akzeptiert MemoryRememberRequest; POST /v1/memories akzeptiert MemoryStoreRequest. Beide erfordern content (string) und path (string). Optionale Felder in den OpenAPI-Schemas umfassen metadata (Objekt), source (string oder null), logic_path (string oder null), embedding (Zahlen-Array oder null), bucket (string, Standard public), memory_id, semantic_key, memory_type, version, status, superseded_by, embedding_provider, embedding_model, embedding_dimension, importance, confidence, expires_at, scope, team_id und provenance. MemoryRememberRequest deklariert zusätzlich dedupe (boolean, Standard true); MemoryStoreRequest setzt memory_type standardmäßig auf semantic und importance/confidence auf 0.5/1.0.

POST /v1/remember
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "content": "The actual text to remember.",
  "path": "projects/memory-os/decisions",
  "scope": "memory-os",
  "source": "codex",
  "metadata": { "kind": "decision" }
}

Schemas für Erstellungsantworten

Der OpenAPI 201-Antwortinhalt ist für beide Erstellungsoperationen ein typloses JSON-Objekt. Die aktuelle remember-Implementierung liefert {id: string, status: "remembered"} zurück; die store-Implementierung liefert die erstellte Speicherkennung zurück. Behandeln Sie dies als Implementierungsverhalten und nicht als stärkeres Schema, als das committete OpenAPI-Dokument deklariert.

{
  "id": "<memory-id>",
  "status": "remembered"
}

Suche und Abruf

GET /v1/memories/search und GET /v1/recall teilen sich die Search Memories-Operation und geben Cache-Control: no-store, private zurück. Filter schränken den Abruf ein und können nicht erweitern, wozu das Token berechtigt.

GET /v1/memories/search?query=current%20MCP%20decision&limit=5&scope=memory-os&explain=true
X-API-Key: <your-assigned-api-key>

Suchanfrageparameter und Antwort

OpenAPI-Abfrageparameter sind query (string, erforderlich), limit (integer, Standard 5), threshold (number oder null), path (string, Standard %), bucket (string, Standard %), scope (string oder null), team_id (string oder null), memory_type (string, Standard %), status (string, Standard active), explain (boolean, Standard false), prefer_working (boolean, Standard false) und candidate_count (integer oder null). OpenAPI belässt die 200-Antwort als typloses JSON-Objekt; die Implementierung liefert derzeit results (Array) und coverage (number) zurück und kann gegebenenfalls keyguard_decrypt_grant_ids hinzufügen.

  • Aktuell beobachtete Antwortstruktur: { results: [...], coverage: number }.
  • Die Spezifikation deklariert kein Maximum für search limit oder candidate_count; Clients sollten konservative Werte verwenden und Validierungsfehler behandeln.

Schemas für Kontextanfragen und -antworten

POST /v1/recall/context akzeptiert RecallContextRequest. query (string) ist erforderlich; path und bucket stehen standardmäßig auf %, memory_type standardmäßig auf auto, status auf active, max_items auf 8, max_tokens auf 1500, prefer_working auf true, include_knowledge auf false, und scope, team_id, threshold und limit sind nullfähig. Die OpenAPI 200-Antwort ist ein typloses Objekt; die normale Implementierung für authentifizierte Eigentümer liefert ein value-density-v2-Kontextobjekt mit version, query, retrieval_plan, budget, items, context_text und answer_status zurück. Der Zweig für temporäre Agenten liefert version 1.0 mit denselben Feldern query/budget/items/context_text zurück.

POST /v1/recall/context
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "query": "recent progress on memory-os",
  "scope": "memory-os",
  "memory_type": "auto",
  "status": "active",
  "max_items": 8,
  "max_tokens": 1500,
  "prefer_working": true
}

Schemas für Speicheraktualisierung und -löschung

PATCH /v1/memories/{memory_id} akzeptiert MemoryUpdateRequest: Alle Felder sind optional, und content, path, metadata, source, logic_path, embedding, bucket, semantic_key, memory_type, status, superseded_by, embedding_provider, embedding_model, embedding_dimension, importance, confidence, expires_at, scope, team_id, provenance, supersession_reason, merge_metadata (Standard true), merge_provenance (Standard true) und detect_conflicts (Standard true) sind deklariert. DELETE /v1/memories/{memory_id} akzeptiert den Abfrageparameter mode (Standard soft_delete) und reason; mode=hard_delete und mode=redact sind unumkehrbar, und memory:write wird gemäß Kompatibilitätsregeln akzeptiert, sodass Schreib-Token Datensätze dauerhaft löschen können. POST /v1/memories/{memory_id}/forget akzeptiert MemoryForgetRequest mit mode (Standard soft_delete), reason, replacement_content und metadata. POST /v1/memories/{memory_id}/restore stellt vorläufig gelöschte Datensätze wieder her. Die 200-Antworten für diese Lebenszyklusoperationen sind im öffentlichen OpenAPI-Schema typisiert.

POST /v1/memories/<memory-id>/forget
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "mode": "soft_delete",
  "reason": "No longer needed"
}

Paginierung, Fehler und Rate-Limits

Nur GET /v1/memories bietet Listenpaginierung in OpenAPI: limit ist standardmäßig 100 und offset 0, mit einem optionalen path-Filter. Die Suche verwendet limit statt offset; der Kontext nutzt max_items/max_tokens anstelle von Seiten-Cursorn. Der dokumentierte Validierungsfehler ist HTTPValidationError: {detail: [{loc: (string|integer)[], msg: string, type: string}]}. Autorisierungsfehler zur Laufzeit nutzen den gemeinsamen Fehlervertrag auf der Authentifizierungsseite. Die Laufzeit wendet bei Aktivierung die memory_write-Richtlinie von 180 pro Minute auf Schreibvorgänge/Lebenszyklusmutationen und die memory_search-Richtlinie von 300 pro Minute auf Suche, Abruf, Kontext und Speicherlesevorgänge innerhalb eines 60-Sekunden-Fensters an; Kontingente sind konfigurierbar und fehlen in OpenAPI.

{
  "version": "value-density-v2",
  "query": "recent progress on memory-os",
  "retrieval_plan": {},
  "budget": {
    "max_items": 8,
    "max_tokens": 1500,
    "used_items": 3,
    "used_tokens": 412,
    "skipped_items": 0,
    "filtered_items": 0,
    "structured_skipped_items": 0,
    "budget_skipped_items": 0,
    "truncated_items": 0,
    "candidate_items": 3,
    "selection_strategy": "top-primary-plus-stable-value-density",
    "budget_tradeoff": false,
    "token_scope": "context_text"
  },
  "items": [],
  "context_text": "",
  "answer_status": "no_confirmed_answer"
}

Quelle: MCP-Tool-Oberfläche