rhanka/engram-memory

Engram-Speicher über MCP

Grundwahrheit: @sentropic/engram 0.22.0-Kandidat (fb223377), Anbieter sentropic.engram.memory, Connector engram-memory, Vertrag 1.0.0. Alles, was als unverified markiert ist, ist nicht durch die am Ende aufgeführten Quellen belegt.

0. Was der Host besitzt (zuerst lesen)

• Nie in Argumenten: tenant, workspace, scope, principal, agent_id, session, credential, auditId, deadline, cancellation, confirmation (elicitationRef). Der Host bindet sie pro Aufruf. Jedes Eingabeschema ist geschlossen (additionalProperties: false): ein zusätzliches Feld ergibt INVALID_SCHEMA. Optionale Felder weglassen; niemals null senden.
• Mandanten- und Arbeitsbereichsisolierung: jeder Aufruf ist an einen genauen, vom Host gewählten Gültigkeitsbereich gebunden; Argumente enthalten keine Bereichsauswahl. Berechtigungen sind pro {tenantId, workspaceId} definiert, und ein fremder Bereich wird abgelehnt. Du siehst niemals die Erinnerungen eines anderen Mandanten: ein unbekanntes Ziel und ein Ziel außerhalb deines Bereichs geben beide NOT_FOUND zurück.
• purpose_ref (suchen, abrufen, aufzeichnen) muss dem vom Host gebundenen Zweck entsprechen; eine Abweichung ist eine Protokollverweigerung. Wie der Host dem Agenten seinen purpose_ref mitteilt, ist unverified: wenn du ihn nicht hast, frage den Host-Betreiber.
• Zustandsändernde Aufrufe (capture, request_admission, withdraw, forget) durchlaufen die Host-Mutationssperre (Idempotenz-Reservierung und Operations-Digest). withdraw und forget erfordern immer die Host-Bestätigungssperre (eine menschliche Genehmigung, gebunden an Fähigkeit, Ziel und Operations-Digest, TTL maximal 300 s, Ausführung innerhalb von 30 s). Capture und request_admission erfordern sie, wenn die Host-Auswahl Bestätigung als erforderlich markiert. Du kannst nicht in eigenem Namen bestätigen: ein vom Modell geschriebenes confirmed: true hat keine Wirkung.
• Wartung ist niemals eine Agentenfähigkeit: Admin, Bootstrap, Rotieren, Widerrufen, Backup, Wiederherstellen, Migrieren, Projektionsinvalidierung, Ersetzen, Anfechten, Zurückspulen, Ablaufen, Historie oder Kandidateninspektion liegen außerhalb der sechs Tools. Die Wartungsberechtigung (['read','maintain']) ist nur für den Host und erreicht niemals den Agentenpfad.
• Jedes Tool wird unabhängig erkannt und autorisiert; die Aktivierung des Speichers gewährt nicht alle sechs. Ein fehlendes Tool bedeutet, dass dir diese Fähigkeit fehlt; überhaupt keine Speichertools bedeutet, dass der Speicher für dich deaktiviert ist (standardmäßig deaktiviert; Host und Mandant müssen zustimmen). Suche nicht nach einem anderen Weg.
• Protokollfehler sind keine Speicherantworten: -32603 Trusted invocation context unavailable (fehlender oder nicht vertrauenswürdiger Host-Kontext, Zweck, Principal, Mandant oder Quellenkonflikt, fehlende Bestätigungsreferenz) und -32602 Unknown tool. Stoppe, melde es dem Host-Betreiber, wiederhole es nicht mit geänderten Argumenten.

1. Wann der Speicher verwendet werden soll und wann nicht

Verwende ihn für dauerhaftes, wiederverwendbares Wissen, das es wert ist, in einer späteren Sitzung oder von einem anderen Agenten wiedergefunden zu werden: Entscheidungen mit Begründung, verifizierte Fakten über ein System mit einer zitierbaren Quelle, Konventionen, wiederkehrende Fallstricke und deren Behebung, Übergabe-Fakten.

Verwende ihn nicht für: temporären oder in Arbeit befindlichen Zustand, Chat-Transkripte, rohe Tool-Ausgabe, aufgabenspezifische Notizen, Spekulationen oder alles in §4. Suche und Abruf geben nur accepted_current-Datensätze preis; ausstehende, abgelehnte, zurückgezogene, angefochtene, historische, abgelaufene, vertrauensungültige und gelöschte Datensätze werden niemals zurückgegeben.

2. Die sechs Tools

Jedes Ergebnis ist ein Umschlag. Erfolg: {ok: true, output: {schema_version: 1, value}, auditId, redactionClass: "high"}. Fehler: {ok: false, auditId, redactionClass: "high", error: {code, message, retriable}}. Es wird in structuredContent mit einer identischen JSON-Textkopie übertragen; isError entspricht !ok. Nachrichten sind konstante bereinigte Zeichenfolgen: handle nach code und retriable, niemals nach der Nachricht.

Gemeinsame Kodierungen. Undurchsichtige Referenzen (purpose_ref, component_id, primary_component_id, citation_id, source_ref, evidence_ref, reason_ref) sind NFC-Zeichenfolgen von 1 bis 512 UTF-8-Bytes. Kopiere candidate_id, record_id und page_cursor genau so, wie sie zurückgegeben werden. Zeitpunkte (observed_at, expires_at) sind YYYY-MM-DDTHH:mm:ss.sssZ (kanonische UTC, Millisekundengenauigkeit). Das serialisierte Argumentobjekt ist maximal 1.048.576 UTF-8-Bytes groß.

engram_memory_search (schreibgeschützt): Finde aktuelle Erinnerungen mit Zitaten und einem Rangbeleg.

• Eingabe: query (1 bis 8.192 UTF-8-Bytes), purpose_ref. Optional: limit (1 bis 50, Standard 10), max_packet_bytes (4.096 bis 1.048.576, Standard 65.536), capability_policy {minimum_channels: "lexical" | "lexical_and_semantic", network: "forbid" | "allow"} (Standard lexikalisch / verbieten; allow gewährt nichts), page_cursor (der vorherige next_page_cursor, gleiche Abfrage und Parameter).
• Ausgabe: {records[], rank_receipt, next_page_cursor?, response_digest}; jedes Datenpaket ist {record, redacted_fields, redaction_receipt_digest, score, rank}. record ist geschwärzt; record.record_id ist immer vorhanden.
• Typische Fehler: STALE_PAGE (starte eine neue Suche ohne page_cursor), RANKING_UNAVAILABLE (ein erforderlicher semantischer Kanal ist ausgefallen; kein stiller Fallback; wiederholen oder lexikalisch anfordern), PROJECTION_OVERSIZED / RESULT_TOO_LARGE (verringere limit oder passe max_packet_bytes an). Eine leere records-Liste bedeutet keine Übereinstimmung: Infrastrukturfehler werden niemals als leerer Erfolg zurückgegeben.

engram_memory_get (schreibgeschützt): Lies einen bekannten aktuellen Datensatz ohne Rangfolge.

• Eingabe: record_id (Muster ^mem_[a-z2-7]+$), purpose_ref. Optional: max_packet_bytes.
• Ausgabe: {record, redacted_fields, redaction_receipt_digest, read_receipt, packet_digest}; read_receipt enthält record_id, record_digest, valid_as_of, system_as_of, validated_through_cursor, authorization_receipt_digest, revalidation_receipt_digest, checked_at, receipt_digest.
• Typische Fehler: NOT_FOUND (unbekannt, außerhalb deines Bereichs oder nicht aktuell berechtigt; absichtlich nicht unterscheidbar; teste keine Varianten), PROJECTION_OVERSIZED.

engram_memory_capture (anhängen): Reiche zitiertes Material als verschlüsselten ausstehenden Kandidaten ein.

• Eingabe: idempotency_key, payload, evidence.
  • payload: schema_version: 2, purpose_ref, valid_time {t, t_end?} (sichere Ganzzahlen, t_end >= t; verwende Epochen-Millisekunden: der ausgelieferte aktuelle-Lese-Pfad vergleicht sie mit Date.parse-Instanzen, daher kann eine andere Einheit einen begrenzten Datensatz hinterlassen, der nie aktuell ist), components (1 bis 64 von {component_id, kind: "context" | "decision" | "evidence", text (1 bis 65.536 Bytes), citation_ids (1 bis 256, eindeutig)}), primary_component_id, primary_event {at, type_ref, citation_id} (at ist eine sichere Ganzzahl; seine Einheit ist unverified), citations (1 bis 256 von {citation_id, source_ref, locator {scheme, value}, content_digest, observed_at? (Instant)}). Optional: retention {derivative_rule: "retain" | "make-ineligible", expires_at? (Instant, strikt nach Aufnahmezeitpunkt, innerhalb der Host-Obergrenze)}, reconciliation {family_refs} (sortiert, eindeutig, maximal 64).
  • Querverweise: citation_id-Werte sind eindeutig; component_id-Werte sind eindeutig; jede Komponentenzitation wird in citations aufgelöst; primary_component_id wird in components aufgelöst; primary_event.citation_id ist in citations und in der primären Komponente.
  • evidence: {evidence_ref, evidence_digest, citation_ids (1 bis 256, eindeutig), attestation?}; citation_ids müssen in payload.citations aufgelöst werden; attestation maximal 4.096 Bytes.
• Ausgabe: {status: "committed_pending" | "duplicate_exact", candidate_id, record_digest?, cursor, transaction_receipt_digest}. duplicate_exact ist die Wiederholung derselben Idempotenzidentität mit identischem Inhalt.
• Typische Fehler: INVALID_SCHEMA (einschließlich eines expires_at, das nicht nach dem Aufnahmezeitpunkt liegt); UNAUTHORIZED (keine Aufnahmeberechtigung, retain nicht durch Host-Richtlinie erlaubt, expires_at jenseits der Host-Obergrenze, eine Abgleichsfamilie ohne Host-Zustimmung); DIGEST_CONFLICT; MUTATION_OUTCOME_UNKNOWN; POLICY_UNAVAILABLE.

engram_memory_request_admission (Zustandsübergang): Frage die Aufnahmerichtlinie des Hosts, um über einen ausstehenden Kandidaten zu entscheiden.

• Eingabe: candidate_id, idempotency_key.
• Ausgabe: {outcome: {status: "accepted" | "rejected" | "pending_adjudication" | "duplicate_exact", candidate_id, record_id?, cursor, decision_receipt_digest, transaction_receipt_digest}, replayed}. accepted erfordert record_id. Die integrierte Engine gibt es bei Annahme aus; das veröffentlichte Schema erlaubt ein optionales record_id bei anderen Status. Interpretiere outcome.status und replayed, nicht nur das Vorhandensein von Feldern; die Semantik von duplicate_exact-Aufnahme bleibt unverified. rejected und pending_adjudication sind erfolgreiche Domänenergebnisse, keine Fehler.
• Typische Fehler: NOT_FOUND, POLICY_STALE (wiederholbar), DIGEST_CONFLICT, MUTATION_OUTCOME_UNKNOWN.

engram_memory_withdraw (Zustandsübergang, bestätigungsgeschützt): Beende einen ausstehenden Kandidaten.

• Eingabe: candidate_id, idempotency_key, reason_ref (undurchsichtige Referenz, 1 bis 512 Bytes).
• Ausgabe: {receipt: {event_id, operation: "withdraw", from_state: "pending", to_state: "withdrawn", cursor, event_digest, authorization_receipt_digest, transaction_receipt_digest}, replayed, key_destruction: "pending" | "complete"}.
• Typische Fehler: gate_failed (keine gültige Host-Bestätigung), NOT_FOUND, DIGEST_CONFLICT, MUTATION_OUTCOME_UNKNOWN.

engram_memory_forget (Zustandsübergang, bestätigungsgeschützt): Mache einen aufgenommenen Datensatz endgültig unzulässig.

• Eingabe: record_id, idempotency_key, reason_ref.
• Ausgabe: {receipt: {..., operation: "tombstone", from_state: einer von accepted_current | accepted_disputed | historical | expired | trust_invalid, to_state: "tombstoned"}, replayed, projection_invalidation: "pending" | "complete", coverage_receipt_digest?}.
• Typische Fehler: wie bei withdraw.

Fehlercodes und was zu tun ist. Wenn retriable true ist, backe aus und wiederhole; bei einer Mutation wiederhole mit dem gleichen idempotency_key und identischen Argumenten. Wenn false, wiederhole nicht unverändert.

Code	Aktion
INVALID_SCHEMA, INVALID_DIGEST	Korrigiere die Argumente gemäß dem geschlossenen Schema (Grenzen, NFC, Querverweise, Digest-Format sha256: + 64 Kleinbuchstaben Hex).
UNAUTHORIZED, AUTHORIZATION_EXPIRED, AUTHORIZATION_REVOKED	Stoppe. Dir fehlt die Berechtigung. Melde es dem Host; wiederhole es niemals unter einer anderen Identität.
NOT_FOUND	Behandle das Ziel als für dich nicht verfügbar. Untersuche nicht.
DIGEST_CONFLICT	Der Schlüssel wurde bereits mit anderem Inhalt oder Ziel verwendet. Finde heraus, warum; verwende einen neuen Schlüssel nur für einen wirklich neuen Vorgang.
ILLEGAL_TRANSITION, ALREADY_TERMINAL	Der Lebenszyklus-Zustand verbietet es. Überprüfe mit Suche oder Abruf; führe keine Schleife aus.
MUTATION_OUTCOME_UNKNOWN	Es könnte ausgeführt worden sein. Wiederhole mit demselben Schlüssel und denselben Argumenten, bis ein eindeutiges Ergebnis vorliegt. Gehe niemals davon aus, dass nichts passiert ist.
gate_failed	Bestätigungs- oder Richtliniengatter nicht erfüllt. Frage den Menschen über den Host.
STALE_PAGE	Neue Suche ohne page_cursor.
RESULT_TOO_LARGE, PROJECTION_OVERSIZED	Verringere limit oder passe max_packet_bytes innerhalb der Grenzen an.
RATE_LIMITED, DEADLINE_EXCEEDED, CANCELLED, STORE_UNAVAILABLE, FENCE_LOST, CURSOR_GAP, POLICY_UNAVAILABLE, POLICY_STALE, PROJECTION_STALE, RANKING_UNAVAILABLE	Wiederholbar: backe aus, wiederhole (gleicher Schlüssel für Mutationen). Melde, wenn anhaltend.
CAPABILITY_UNAVAILABLE, JOURNAL_CORRUPT, BLOB_MISSING, REGISTRY_VERSION_UNAVAILABLE, BACKUP_INVALID, RESTORE_REFUSED, MIGRATION_LEDGER_INVALID	Betriebsfehler. Stoppe und melde es dem Host-Betreiber.

3. Disziplin

1. Suche vor der Aufnahme. Der duplicate_exact-Status der Aufnahme deckt nur eine Wiederholung desselben Schlüssels mit demselben Inhalt ab; es ist keine semantische Dublettenprüfung. Wenn ein gleichwertiger aktueller Datensatz existiert, zitiere seine record_id, anstatt erneut aufzunehmen.
2. Aufnahme erstellt einen verwalteten Entwurf. Der Kandidat ist ausstehend und verschlüsselt; er ist nicht durchsuchbar oder lesbar, und eine candidate_id ist keine record_id.
3. Aufnahme wird beantragt, niemals angenommen. Du kannst die Entscheidung nicht liefern. Melde das genaue Ergebnis. Vergessener Inhalt: Eine erneute Aufnahme gibt immer noch committed_pending zurück. Bei request_admission wird eine ansonsten annehmende Entscheidung als pending_adjudication gehalten, wenn der effektive Nutzlast-Digest mit einem gelöschten Datensatz im selben Bereich übereinstimmt; eine normale Richtlinienablehnung gibt immer noch rejected zurück. Die Wiederverwendung des ursprünglichen Aufnahmeschlüssels mit demselben Inhalt ist eine Aufnahmewiederholung (duplicate_exact), keine neue Beurteilung. Melde das zurückgegebene Ergebnis; verändere oder formuliere vergessenen Inhalt niemals um, um diesen Schutz zu umgehen.
4. Herkunft. Jede Komponente zitiert mindestens eine Zitation; content_digest ist ein sha256:-Digest des zitierten Inhalts (exakte Kanonisierung unverified). Zitationen, Beweise und Gründe bleiben Behauptungen, bis der Host-Prüfer sie überprüft; die Vertrauensklasse wird vom Host zugewiesen, niemals von dir. Deine Akteursidentität ist der host-gebundene Principal, agent_id und Sitzung; ein in text geschriebener Name hat keine Autorität.
5. Idempotenz. Mutierende Aufrufe benötigen einen NFC-idempotency_key von 16 bis 256 UTF-8-Bytes (verwende mindestens 16 ASCII-Zeichen; das veröffentlichte JSON Schema minLength ist lockerer als die Laufzeitprüfung). Ein Schlüssel pro logischem Vorgang, beschränkt auf deinen Principal. Zeichne ihn vor dem Aufruf auf, damit eine Wiederholung ihn wiederverwendet. Gleicher Schlüssel und gleicher Inhalt: Wiederholung (duplicate_exact oder replayed: true). Gleicher Schlüssel und anderer Inhalt, Ziel oder Tool: DIGEST_CONFLICT. Der Speicher bindet jede Commit-Identität an einen internen Absichts-Hash; du sendest ihn niemals, und eine Abweichung erscheint als DIGEST_CONFLICT. Wiederholungen verwenden die bei der ersten Aufnahme aufgelöste Aufbewahrung.
6. Aufbewahrung. Lasse retention weg, sofern nicht angewiesen. Die Standardableitungsregel ist make-ineligible; retain benötigt eine explizite Host-Erlaubnis; ein expires_at jenseits der Host-Obergrenze wird mit UNAUTHORIZED abgelehnt. Es gibt keinen eigentümergenehmigten Aufbewahrungswert in den Quellen: Aufbewahrung ist ein offener, eigentümerebener Punkt.

4. Was niemals gespeichert werden darf

• Geheimnisse, Anmeldeinformationen, Token, API- oder Signaturschlüssel, Passwörter, Verbindungszeichenfolgen, .env-Werte, Sitzungscookies und die eigenen Bindungsdaten des Hosts