rhanka/engram-memory

MCP를 통한 엔그램 메모리

근거: @sentropic/engram 0.22.0 후보(fb223377), 공급자 sentropic.engram.memory, 커넥터 engram-memory, 계약 1.0.0. unverified로 표시된 것은 마지막에 나열된 출처에 의해 확립되지 않았습니다.

0. 호스트가 소유하는 것 (먼저 읽으십시오)

• 절대 인수에 포함하지 마십시오: 테넌트, 작업 공간, 범위, 주체, agent_id, 세션, 자격 증명, auditId, 마감일, 취소, 확인(elicitationRef). 호스트가 이를 호출별로 바인딩합니다. 모든 입력 스키마는 닫혀 있습니다(additionalProperties: false). 추가 필드는 INVALID_SCHEMA입니다. 선택적 필드는 생략하십시오. 절대 null을 보내지 마십시오.
• 테넌트 및 작업 공간 격리: 각 호출은 호스트가 선택한 하나의 정확한 범위에 바인딩됩니다. 인수는 범위 선택기를 전달하지 않습니다. 권한 부여는 {tenantId, workspaceId}별로 범위가 지정되며, 외부 범위는 거부됩니다. 다른 테넌트의 메모리를 절대 볼 수 없습니다. 알 수 없는 대상과 범위 밖의 대상 모두 NOT_FOUND를 반환합니다.
• purpose_ref (검색, 가져오기, 캡처)는 호스트가 바인딩한 목적과 일치해야 합니다. 불일치는 프로토콜 거부입니다. 호스트가 에이전트에게 purpose_ref를 알리는 방법은 unverified입니다. 이를 가지고 있지 않다면 호스트 운영자에게 물어보십시오.
• 변경 호출 (캡처, 승인 요청, 철회, 잊기)은 호스트 변경 보호(멱등성 예약 및 작업 다이제스트)를 통과합니다. 철회와 잊기는 항상 호스트 확인 보호(기능, 대상 및 작업 다이제스트에 바인딩된 인간 승인, TTL 최대 300초, 30초 이내 실행)가 필요합니다. 캡처 및 승인 요청은 호스트 선택이 확인을 필수로 표시할 때 필요합니다. 스스로 확인할 수 없습니다. 모델이 작성한 confirmed: true는 효과가 없습니다.
• 유지 관리는 절대 에이전트 기능이 아닙니다: 관리, 부트스트랩, 회전, 취소, 백업, 복원, 마이그레이션, 프로젝션 무효화, 대체, 분쟁, 되감기, 만료, 기록 또는 후보 검사는 여섯 가지 도구 밖에 있습니다. 유지 관리 권한 부여(['read','maintain'])는 호스트 전용이며 에이전트 경로에 절대 도달하지 않습니다.
• 각 도구는 독립적으로 발견되고 권한이 부여됩니다. 메모리를 활성화한다고 해서 여섯 가지 모두가 부여되는 것은 아닙니다. 도구가 없으면 해당 기능이 없다는 의미입니다. 메모리 도구가 전혀 없으면 메모리가 비활성화된 것입니다(기본적으로 비활성화, 호스트와 테넌트가 옵트인해야 함). 다른 경로를 찾지 마십시오.
• 프로토콜 오류는 메모리 답변이 아닙니다: -32603 신뢰할 수 없는 호출 컨텍스트를 사용할 수 없음 (누락되었거나 신뢰할 수 없는 호스트 컨텍스트, 목적, 주체, 테넌트 또는 출처 불일치, 확인 참조 누락) 및 -32602 알 수 없는 도구. 중지하고, 호스트 운영자에게 보고하고, 인수를 변경하여 재시도하지 마십시오.

1. 메모리를 사용해야 하는 경우와 사용하지 말아야 하는 경우

내구성이 있고 재사용 가능한 지식에 사용하십시오. 나중 세션이나 다른 에이전트가 다시 찾을 가치가 있는 지식: 근거가 있는 결정, 인용 가능한 출처가 있는 시스템에 대한 검증된 사실, 컨벤션, 반복되는 함정과 그 수정 방법, 핸드오프 사실.

다음에는 사용하지 마십시오: 스크래치 또는 작업 진행 중 상태, 채팅 기록, 원시 도구 출력, 작업-로컬 노트, 추측, 또는 §4의 모든 것. 검색 및 가져오기는 accepted_current 레코드만 공개합니다. 보류 중, 거부됨, 철회됨, 분쟁 중, 기록, 만료됨, 신뢰 무효 및 무덤 처리된 레코드는 절대 반환되지 않습니다.

2. 여섯 가지 도구

모든 결과는 봉투입니다. 성공: {ok: true, output: {schema_version: 1, value}, auditId, redactionClass: "high"}. 실패: {ok: false, auditId, redactionClass: "high", error: {code, message, retriable}}. 이는 structuredContent에 동일한 JSON 텍스트 사본과 함께 전달됩니다. isError는 !ok와 같습니다. 메시지는 일정하게 살균된 문자열입니다. code와 retriable에 따라 행동하고 메시지에는 절대 의존하지 마십시오.

공통 인코딩. 불투명 참조(purpose_ref, component_id, primary_component_id, citation_id, source_ref, evidence_ref, reason_ref)는 1~512 UTF-8 바이트의 NFC 문자열입니다. candidate_id, record_id 및 page_cursor를 반환된 그대로 복사하십시오. 인스턴트(observed_at, expires_at)는 YYYY-MM-DDTHH:mm:ss.sssZ(정규 UTC, 밀리초 정밀도)입니다. 직렬화된 인수 객체는 최대 1,048,576 UTF-8 바이트입니다.

engram_memory_search (읽기 전용): 인용 및 순위 영수증이 있는 현재 메모리를 찾습니다.

• 입력: query (18,192 UTF-8 바이트), purpose_ref. 선택 사항: limit (150, 기본값 10), max_packet_bytes (4,096~1,048,576, 기본값 65,536), capability_policy {minimum_channels: "lexical" | "lexical_and_semantic", network: "forbid" | "allow"} (기본값 어휘/금지, allow는 아무것도 부여하지 않음), page_cursor (이전 next_page_cursor, 동일한 쿼리 및 매개변수).
• 출력: {records[], rank_receipt, next_page_cursor?, response_digest}; 각 레코드 패킷은 {record, redacted_fields, redaction_receipt_digest, score, rank}입니다. record는 편집됩니다. record.record_id는 항상 존재합니다.
• 일반적인 오류: STALE_PAGE (page_cursor 없이 새 검색 시작), RANKING_UNAVAILABLE (필수 의미 채널이 다운됨, 자동 대체 없음, 재시도하거나 어휘 요청), PROJECTION_OVERSIZED / RESULT_TOO_LARGE (limit 낮추거나 max_packet_bytes 조정). 빈 records 목록은 일치하는 항목이 없음을 의미합니다. 인프라 오류는 빈 성공으로 반환되지 않습니다.

engram_memory_get (읽기 전용): 순위 없이 알려진 현재 레코드 하나를 읽습니다.

• 입력: record_id (패턴 ^mem_[a-z2-7]+$), purpose_ref. 선택 사항: max_packet_bytes.
• 출력: {record, redacted_fields, redaction_receipt_digest, read_receipt, packet_digest}; read_receipt는 record_id, record_digest, valid_as_of, system_as_of, validated_through_cursor, authorization_receipt_digest, revalidation_receipt_digest, checked_at, receipt_digest를 보유합니다.
• 일반적인 오류: NOT_FOUND (알 수 없거나, 범위 밖이거나, 현재 자격이 없음. 설계상 구별 불가능. 변형을 조사하지 마십시오), PROJECTION_OVERSIZED.

engram_memory_capture (추가): 인용된 자료를 암호화된 보류 후보로 제출합니다.

• 입력: idempotency_key, payload, evidence.
  • payload: schema_version: 2, purpose_ref, valid_time {t, t_end?} (안전한 정수, t_end >= t, 에포크 밀리초 사용. 출하된 현재 읽기 경로는 이를 Date.parse 인스턴트와 비교하므로, 다른 단위는 경계 레코드가 절대 현재가 되지 않게 할 수 있음), components (164개의 {component_id, kind: "context" | "decision" | "evidence", text (1~65,536 바이트), citation_ids (1~256, 고유)}), primary_component_id, primary_event {at, type_ref, citation_id} (at은 안전한 정수, 단위는 unverified), citations (1256개의 {citation_id, source_ref, locator {scheme, value}, content_digest, observed_at? (인스턴트)}). 선택 사항: retention {derivative_rule: "retain" | "make-ineligible", expires_at? (인스턴트, 캡처 시간 이후, 호스트 상한 내)}, reconciliation {family_refs} (정렬되고, 고유하며, 최대 64개).
  • 상호 참조: citation_id 값은 고유합니다. component_id 값은 고유합니다. 모든 구성 요소 인용은 citations에서 확인됩니다. primary_component_id는 components에서 확인됩니다. primary_event.citation_id는 citations와 기본 구성 요소에 있습니다.
  • evidence: {evidence_ref, evidence_digest, citation_ids (1~256, 고유), attestation?}; citation_ids는 payload.citations에서 확인되어야 합니다. attestation은 최대 4,096바이트입니다.
• 출력: {status: "committed_pending" | "duplicate_exact", candidate_id, record_digest?, cursor, transaction_receipt_digest}. duplicate_exact는 동일한 멱등성 ID와 동일한 내용의 재생입니다.
• 일반적인 오류: INVALID_SCHEMA (캡처 시간 이후가 아닌 expires_at 포함), UNAUTHORIZED (캡처 권한 없음, 호스트 정책이 허용하지 않는 retain, 호스트 상한을 초과하는 expires_at, 호스트 동의 없는 조정 패밀리), DIGEST_CONFLICT, MUTATION_OUTCOME_UNKNOWN, POLICY_UNAVAILABLE.

engram_memory_request_admission (상태 전환): 호스트의 채택 정책에 보류 후보에 대한 결정을 요청합니다.

• 입력: candidate_id, idempotency_key.
• 출력: {outcome: {status: "accepted" | "rejected" | "pending_adjudication" | "duplicate_exact", candidate_id, record_id?, cursor, decision_receipt_digest, transaction_receipt_digest}, replayed}. accepted는 record_id가 필요합니다. 내장 엔진은 승인 시 이를 내보냅니다. 게시된 스키마는 다른 상태에서 선택적 record_id를 허용합니다. 단순한 필드 존재가 아니라 outcome.status와 replayed를 해석하십시오. duplicate_exact 채택 의미는 unverified로 남아 있습니다. rejected와 pending_adjudication은 성공적인 도메인 결과이며 오류가 아닙니다.
• 일반적인 오류: NOT_FOUND, POLICY_STALE (재시도 가능), DIGEST_CONFLICT, MUTATION_OUTCOME_UNKNOWN.

engram_memory_withdraw (상태 전환, 확인 게이트): 보류 후보를 종료합니다.

• 입력: candidate_id, idempotency_key, reason_ref (불투명 참조, 1~512바이트).
• 출력: {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"}.
• 일반적인 오류: gate_failed (유효한 호스트 확인 없음), NOT_FOUND, DIGEST_CONFLICT, MUTATION_OUTCOME_UNKNOWN.

engram_memory_forget (상태 전환, 확인 게이트): 채택된 레코드를 최종적으로 자격을 상실하게 만듭니다.

• 입력: record_id, idempotency_key, reason_ref.
• 출력: {receipt: {..., operation: "tombstone", from_state: accepted_current | accepted_disputed | historical | expired | trust_invalid 중 하나, to_state: "tombstoned"}, replayed, projection_invalidation: "pending" | "complete", coverage_receipt_digest?}.
• 일반적인 오류: 철회와 동일.

오류 코드 및 조치. retriable이 true이면 백오프 후 재시도하십시오. 변경 작업의 경우 동일한 idempotency_key와 동일한 인수로 재시도하십시오. false이면 변경하지 않고 재시도하지 마십시오.

코드	조치
INVALID_SCHEMA, INVALID_DIGEST	닫힌 스키마(경계, NFC, 상호 참조, 다이제스트 형식 sha256: + 64자 소문자 16진수)에 대해 인수를 수정하십시오.
UNAUTHORIZED, AUTHORIZATION_EXPIRED, AUTHORIZATION_REVOKED	중지하십시오. 권한이 없습니다. 호스트에 보고하십시오. 다른 ID로 재시도하지 마십시오.
NOT_FOUND	대상을 사용할 수 없는 것으로 처리하십시오. 조사하지 마십시오.
DIGEST_CONFLICT	키가 다른 내용이나 대상과 이미 사용되었습니다. 이유를 찾으십시오. 진정으로 새로운 작업에만 새 키를 사용하십시오.
ILLEGAL_TRANSITION, ALREADY_TERMINAL	수명 주기 상태가 금지합니다. search 또는 get으로 다시 확인하십시오. 반복하지 마십시오.
MUTATION_OUTCOME_UNKNOWN	커밋되었을 수 있습니다. 명확한 결과가 나올 때까지 동일한 키와 인수로 재시도하십시오. 아무 일도 일어나지 않았다고 가정하지 마십시오.
gate_failed	확인 또는 정책 게이트가 충족되지 않았습니다. 호스트를 통해 인간에게 물어보십시오.
STALE_PAGE	page_cursor 없이 새 검색하십시오.
RESULT_TOO_LARGE, PROJECTION_OVERSIZED	limit을 낮추거나 max_packet_bytes를 범위 내에서 조정하십시오.
RATE_LIMITED, DEADLINE_EXCEEDED, CANCELLED, STORE_UNAVAILABLE, FENCE_LOST, CURSOR_GAP, POLICY_UNAVAILABLE, POLICY_STALE, PROJECTION_STALE, RANKING_UNAVAILABLE	재시도 가능: 백오프 후 재시도(변경의 경우 동일한 키). 지속되면 보고하십시오.
CAPABILITY_UNAVAILABLE, JOURNAL_CORRUPT, BLOB_MISSING, REGISTRY_VERSION_UNAVAILABLE, BACKUP_INVALID, RESTORE_REFUSED, MIGRATION_LEDGER_INVALID	운영 오류입니다. 중지하고 호스트 운영자에게 보고하십시오.

3. 규율

1. 캡처 전에 검색하십시오. 캡처의 duplicate_exact는 동일한 키와 동일한 내용의 재시도만 다룹니다. 의미상 중복 검사가 아닙니다. 동등한 현재 레코드가 존재하면 다시 캡처하는 대신 해당 record_id를 인용하십시오.
2. 캡처는 관리되는 초안을 생성합니다. 후보는 보류 중이며 암호화되어 있습니다. 검색하거나 읽을 수 없으며 candidate_id는 record_id가 아닙니다.
3. 채택은 요청되며 가정되지 않습니다. 결정을 제공할 수 없습니다. 정확한 결과를 보고하십시오. 잊혀진 내용: 새 캡처는 여전히 committed_pending을 반환합니다. request_admission에서, 유효한 페이로드 다이제스트가 동일한 범위의 무덤 처리된 레코드와 일치하면 그렇지 않으면 수락하는 결정이 pending_adjudication으로 유지됩니다. 일반 정책 거부는 여전히 rejected를 반환합니다. 동일한 내용으로 원래 캡처 키를 재사용하는 것은 캡처 재생(duplicate_exact)이지 새로운 판결이 아닙니다. 반환된 결과를 보고하십시오. 이 보호를 우회하기 위해 잊혀진 내용을 변경하거나 바꾸어 말하지 마십시오.
4. 출처. 모든 구성 요소는 적어도 하나의 인용을 인용합니다. content_digest는 인용된 내용의 sha256: 다이제스트입니다(정확한 표준화는 unverified). 인용, 증거 및 이유는 호스트 검증자가 확인할 때까지 주장으로 남아 있습니다. 신뢰 클래스는 호스트에 의해 할당되며, 사용자가 할당하지 않습니다. 사용자의 행위자 ID는 호스트 바인딩 주체, agent_id 및 세션입니다. text에 기록된 이름은 권한을 전달하지 않습니다.
5. 멱등성. 변경 호출에는 16~256 UTF-8 바이트의 NFC idempotency_key가 필요합니다(최소 16 ASCII 문자 사용, 게시된 JSON Schema minLength는 런타임 검사보다 느슨함). 논리적 작업당 하나의 키이며, 사용자의 주체로 범위가 지정됩니다. 호출하기 전에 기록하여 재시도가 이를 재사용하도록 하십시오. 동일한 키 및 동일한 내용: 재생(duplicate_exact 또는 replayed: true). 동일한 키 및 다른 내용, 대상 또는 도구: DIGEST_CONFLICT. 저장소는 각 커밋 ID를 내부 의도 해시에 바인딩합니다. 사용자는 이를 절대 보내지 않으며, 불일치는 DIGEST_CONFLICT로 표시됩니다. 재시도는 첫 번째 캡처에서 해결된 보존을 재사용합니다.
6. 보존. 지시가 없으면 retention을 생략하십시오. 기본 파생 규칙은 make-ineligible입니다. retain은 명시적인 호스트 허용이 필요합니다. 호스트 상한을 초과하는 expires_at은 UNAUTHORIZED로 거부됩니다. 소스에 소유자 승인 보존 값이 존재하지 않습니다. 보존은 공개된 소유자 수준 지점입니다.

4. 절대 저장하지 말아야 할 것

• 비밀, 자격 증명, 토큰, API 또는 서명 키, 비밀번호, 연결 문자열, .env 값, 세션 쿠키 및 호스트 자체 바인딩 크레