콘텐츠로 이동

번역되지 않은 페이지는 영어로 열리며 영어로 표시됩니다.

이 페이지는 영어 원문을 기계 번역한 것이며, 영어 원문이 기준입니다. Machine-translated from the English page, which is authoritative.

기록과 출처

메모리에 대한 모든 쓰기는 새 버전을 만들며, 어떤 것도 제자리에서 수정되지 않습니다. 버전은 추가 전용(append-only) 미러에 보관되므로, 백그라운드 병합이 일어나도 사실의 이력은 그대로 남습니다. 각 행에는 누가 작성했는지와 어떤 경로로 메모리에 들어왔는지가 기록되고, 파생된 행에는 그 출처가 기록되며, 사람이 해당 행이 사실임을 증명할 수 있습니다. 버전 미러가 동작하는 방식은 메모리 아키텍처에서 설명합니다.

대시보드에서 본 메모리의 출처와 버전 이력

작업

작업 역할 응답 내용
memory.history viewer 삭제 표시(tombstone)되거나 마스킹된 버전을 포함해, 키의 모든 버전을 최신순으로 반환합니다.
memory.provenance viewer 현재 행의 출처를 반환합니다: 소스 트레이스, 작성자, 소스 클래스, 추출된 대화.
memory.evidence viewer 사실이 추출된 소스 턴과 이를 뒷받침하는 구간, 각 연결이 만들어진 방식을 반환합니다.
memory.backlinks viewer 행을 가리키는 항목을 반환합니다: 버전, 다이제스트, 들어오고 나가는 타입 링크, 증거 수, 엔티티 이웃.
memory.lineage viewer 공유 메모리의 승격 경로를 반환합니다: 누가, 어떤 행에서, 어떤 검토를 거쳐 승격했는지.
memory.verify writer 로그인한 사용자 또는 서비스 계정의 자격으로 행이 사실임을 증명하거나, 그 증명을 철회합니다.
memory.redact admin 행과 감사 항목은 유지한 채, 과거 버전 하나의 값을 지웁니다.
namespace.rollback admin 네임스페이스의 모든 메모리 헤드를 특정 시점의 버전으로 되돌립니다.
namespace.snapshot admin 네임스페이스의 큐레이션된 상태를 JSON 페이로드로 내보냅니다.
namespace.restore viewer 스냅샷을 새 네임스페이스 또는 호출자가 관리하는 기존 네임스페이스로 가져옵니다. 컬렉션으로는 가져올 수 없습니다.

namespace.snapshot과 namespace.restore는 MCP 도구가 아닙니다. 필드 목록은 작업 레퍼런스의 메모리와 네임스페이스에 있습니다.

버전: memory.history

loom.memory는 현재 상태를 보관하며 FINAL로 읽으므로, 병합이 일어나면 각 행의 가장 최신 버전만 남습니다. loom.memory_versions는 모든 insert마다 materialized view가 채우는 추가 전용(append-only) 미러이며, memory.history, memory.redact, namespace.rollback이 읽는 기록(history)입니다.

history 행에는 version(쓰기 시점의 나노초 단위 epoch), written_at, value, confidence, pinned, expires_at, tombstoned_at, redacted_at, redaction_reason, content_sha256, agent, actor, source_class가 들어 있습니다. created_at은 해당 행을 처음 쓴 시점이며 모든 버전에서 같은 값이 반복됩니다. agent="*"는 해당 키를 쓴 모든 작성자를 대상으로 합니다.

from loom import Agent

async with Agent(org="acme", namespace="support", agent="auditor") as agent:
    for v in await agent.memory.history("customer/4812/plan", agent_id="*"):
        print(v["written_at"], v["actor"], v["source_class"], v["value"])

툼스톤(tombstone)도 하나의 버전이므로 삭제 내역이 history에 나타나고, memory.restore로 14일 이내에는 해당 키를 되살릴 수 있습니다. 현재 상태를 특정 시점 기준으로 읽으려면 memory.get, memory.search, memory.ask에서 as_of를 사용하세요 (유효 시간).

작성자: actor와 source class

서버는 토큰과 작업을 기반으로 모든 행에 actor(human:<subject> 또는 process:<subject>)와 source_class를 기록합니다. source_class 값은 메모리 개념에서 확인할 수 있습니다. 요청은 클래스를 external, imported, derived로만 낮출 수 있습니다.

memory.provenance는 두 값과 함께 다음을 반환합니다.

  • source_trace와 이를 바탕으로 도출한 source_kind(conversation, extracted, observed, consolidated, app, manual, other)
  • 작성자가 인용한 source_resource_id
  • 대화의 thread_id와 thread_exists(네임스페이스가 대화 내용을 기록하지 않거나 대화 내용이 삭제된 경우 false)
  • 해당 행과 연결된, 직접 작성한 링크(memory.link)

검색 결과에는 source_class와 verified가 포함되며, 선택 사항인 신뢰 항(LOOM_MEMORY_SEARCH_TRUST_WEIGHT)이 이 값을 읽습니다.

근거: 사실이 어떤 턴에서 나왔는가

추출은 각 사실을 loom.memory_belief_sources에 있는 해당 턴과 연결합니다. memory.evidence(memory_key)는 이러한 연결을 반환하며, 턴의 텍스트(최대 600자), 역할, 시간, 뒷받침하는 span, 그리고 연결이 만들어진 방식을 함께 제공합니다.

scope support_type 의미
cited extracted_from 추출기가 뒷받침하는 턴을 직접 지정했습니다.
lexical lexical_support 서버가 사실을 가장 잘 맞는 턴과 매칭했습니다.
window window 일치하는 항목이 없어 추출 윈도우 전체가 연결됩니다.
derived derived_from 통합 계보: 해당 항목은 원본 메모리의 텍스트입니다.

응답은 연결을 scope별로 집계하므로, 검사 시 직접 인용된 사실과 느슨하게 연결된 사실을 구분할 수 있습니다. 대화의 정확한 표현이 필요하면 memory.recall이 저장된 턴을 검색합니다 (추출).

계보

  • memory.consolidate와 기간별 다이제스트는 소스마다 derived_from 링크를 하나씩 loom.memory_belief_sources에 기록합니다. memory.evidence는 이 링크를 derived 항목으로 반환합니다.
  • 세션 다이제스트는 압축한 키 목록을 담고 있습니다(summary 히트의 derived_from).
  • memory.lineage(scope="shared")는 공유 메모리의 승격 과정을 따라갑니다. 승격 이벤트, 승격한 주체, 근거가 된 행, 일치하는 항목이 있을 경우 해당 메모리가 유래한 learnings 후보(match_confidence는 exact 또는 inferred), 그리고 감사 이벤트를 보여 줍니다. mechanism은 review, import, auto, unknown 중 하나입니다.
  • memory.backlinks는 그 반대 방향으로, 어떤 행을 가리키는 항목을 보여 줍니다.

memory.delete는 모든 소스가 사라진 통합 요약을 폐기하고, 소스가 남아 있는 통합 요약은 conflicted로 강등합니다.

증명: memory.verify

pinned와 confidence는 누가 사실을 확인했는지 알려 주지 않습니다. memory.verify는 이를 기록합니다. 호출자의 토큰에서 가져온 actor와 그가 증명한 콘텐츠 해시를 저장합니다. 행은 memory_id로 지정하거나, namespace와 memory_key를 writer 식별자와 함께 사용해 지정합니다. 해당 행의 네임스페이스에 대한 writer 권한이 필요합니다.

memory.get과 memory.get_by_id는 저장된 해시와 행의 현재 해시로부터 도출한 verification을 반환합니다.

verification 의미
human 사람이 증명했고 이후 콘텐츠가 변경되지 않았습니다.
process 서비스 계정이 증명했고 이후 콘텐츠가 변경되지 않았습니다.
stale 누군가 증명했지만 이후 콘텐츠가 변경되었습니다.
none 증명된 적이 없거나 철회되었습니다.
  • 편집해도 증명은 지워지지 않습니다. 누군가 다시 verify할 때까지 stale 상태가 됩니다.
  • revoke=true는 증명을 지웁니다. 변경되지 않은 행을 같은 actor가 다시 verify하는 것은 아무 동작도 하지 않습니다 (changed=false).
  • human: 접두사는 토큰에서 가져오므로, 에이전트는 자신이 쓴 내용을 human으로 표시할 수 없습니다. 본문의 actor는 인증이 없는 개발 모드에서만 읽습니다.
  • 스냅샷과 복원은 증명 컬럼을 그대로 유지하며, 복원이 verified_by를 제거하는 일은 없습니다.

기록 지우기: memory.redact

memory.redact(memory_id, version)는 과거 버전 하나의 텍스트를 복사된 모든 위치에서 지우고, 모델이 해당 메모리로부터 만든 모든 프로필 버전도 함께 지웁니다. redacted_at과 redaction_reason을 기록하며, 행과 감사 항목은 그대로 남깁니다. 이전 버전에 유출된 비밀 정보나 개인 정보를 지울 때 사용합니다.

위치 동작
loom.memory, loom.memory_versions value는 "[REDACTED]"가 되고, value_json, evidence, entities, concepts는 비워집니다.
loom.memory_embeddings, loom.memory_chunks 발췌문 또는 청크 해시가 현재 헤드의 것이 아닌 행은 삭제되고, 현재 헤드의 행은 남습니다.
해당 메모리로부터 만들어진 사용자의 프로필 버전 트레이스에 해당 메모리가 나오는 모든 버전이 같은 방식으로 지워집니다. 현재 헤드도 포함하며, 해당 키에서 파생된 행도 함께 지워집니다.
loom.shared, 키에서 승격된 복사본 value가 지워진 텍스트와 같은 모든 버전은 "[REDACTED]"가 되고, 해당 검색 행은 삭제됩니다. 현재 복사본은 관리자가 승격을 해제할 때까지 승격된 상태로 남습니다.

범위에서 제외되는 항목: 태그, 파일, content_sha256, loom.memory_evidence(삭제 기능이 관리), 계보 테이블(ID와 해시만 있음), 엔티티 그래프. 현재 헤드도 지워진 텍스트를 가지고 있는 경우(편집을 바이트 단위로 되돌린 경우)에는 공유 복사본을 그대로 둡니다.

  • 메모리의 현재 헤드는 거부합니다(refused_head=true). 먼저 키를 삭제하거나 다시 작성하세요. 지워진 현재 프로필은 워커가 다시 만들 때까지 렌더, 팩, 프로필 검색에서 제외됩니다.
  • 두 잠금 모드 모두 이를 거부합니다. 메모리 자체의 키와, 이 작업이 영향을 미치는 모든 프로필 키에 적용됩니다.
  • 해당 키 또는 공유 복사본의 키를 인용한 캐시된 memory.ask, code.ask 응답과 선례를 삭제합니다(cache_rows_deleted, precedent_rows_deleted). 영향을 미치는 프로필 키의 경우 삭제는 조직 전체에 적용됩니다. 모든 사용자의 프로필이 같은 키를 가지므로, 해당 키가 윈도에 들어 있던 조직 내 모든 캐시 응답과 선례가 모든 네임스페이스에서 삭제됩니다.
  • 네임스페이스는 조회 후에 확인합니다. 거부되면 403이 아니라 redacted=false로 응답합니다.
  • 존재하지 않는 버전에는 redacted=false로 응답하며 아무것도 지우지 않습니다. 프로필 버전도 지우지 않습니다.
  • 두 메모리 테이블에 대해(복사본이 아직 해당 텍스트를 가지고 있다면 loom.shared에도) 동기식 ALTER TABLE … UPDATE를 실행하고, 파생 행에 대해서는 경량 DELETE를 실행합니다. 즉, 관리용 호출입니다.

공유 복사본의 redact와 경합하는 쓰기:

  • 임베딩 워커가 정리 이후에, 그 이전에 읽은 스텁으로 기록한 검색 행은 해당 키를 다음에 redact할 때까지 남습니다.
  • 키를 승격하면 다시 승격될 때까지 해당 검색 행이 사라집니다.
  • 지우기 이전에 복사본을 읽은 승격 해제는 텍스트가 담긴 툼스톤을 기록하며, 이는 해당 버전을 다시 redact할 때까지 남습니다.

이후의 키 승격으로 대체되었고 그 뒤 loom.shared에서 병합되어 사라진 복사본은 더 이상 찾을 수 없습니다. FINAL이 더 이상 제공하지 않는 그 검색 행은 이후 해당 키를 정리할 때까지 남고, redact된 키가 아닌 다른 키로 저장된 캐시 응답은 만료될 때까지 남습니다.

값이 "[REDACTED]"인 복사본은 이전 redact가 지운 것으로 간주합니다. 따라서 그 텍스트 자체를 가지고 있으면서 승격된 메모리는, 해당 키를 다음에 redact할 때 검색 행을 잃습니다.

프로필 영향 범위와 그 한계는 보안에 있습니다. 특정 사람의 데이터를 모든 곳에서 제거하려면 삭제를 사용하세요.

네임스페이스 되돌리기: namespace.rollback

namespace.rollback(as_of)는 각 키에 대해 as_of 시점 또는 그 이전의 가장 높은 버전을 새로운 최신 버전(head)으로 다시 삽입하고, 그 이후에 생성된 키는 tombstone 처리합니다. 롤백 자체도 새로운 버전으로 기록되므로 같은 방법으로 되돌릴 수 있습니다.

  • 기본적으로 드라이 런으로 실행되며 reinstate, remove, sample을 보고합니다. dry_run=false를 지정하면 실제로 적용됩니다.
  • memory_keys(최대 500개)로 대상을 제한할 수 있습니다. max_keys(기본값 5,000)는 한 번의 호출에서 처리할 수 있는 키 수의 상한이며, truncated가 표시되면 다시 호출하라는 뜻입니다.
  • embedding_worker가 복원된 head를 다시 임베딩합니다.
  • 네임스페이스의 기록보다 오래되었거나 미래인 as_of는 거부됩니다.
curl -sX POST http://localhost:7777/v1/namespace.rollback \
  -H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"org":"dev","namespace":"local","as_of":"<YYYY-MM-DD>T09:00:00Z"}' \
  | jq '{reinstate, remove, truncated, sample}'

스냅샷: namespace.snapshot 및 namespace.restore

namespace.snapshot은 네임스페이스의 큐레이션된 상태를 JSON으로 내보냅니다. 내보내는 내용은 version, content_sha256, actor, source_class, 유효 기간 및 증명(attestation) 컬럼을 포함한 모든 메모리 행, 유형별 설정, 권한 부여(grant), 그리고 최대 include_audit_tail_n개의 최근 감사 행(기본값 1,000)입니다. include_embeddings는 기본적으로 false이므로, 대상 환경에서는 자체 모델로 다시 임베딩합니다.

namespace.restore(target_namespace, payload)는 페이로드를 버전 행으로 다시 기록합니다. snapshot_id 기준으로 멱등적입니다(다시 실행하면 restored=false로 응답합니다). 복원 대상은 새 네임스페이스이거나(호출자가 admin이 되며, 이미 데이터나 권한 부여가 있는 이름에 대해서는 호출자가 이미 해당 네임스페이스를 관리하는 경우가 아니면 거부됩니다) 호출자가 관리하는 네임스페이스입니다. rebind_agent는 모든 행의 작성자를 다시 지정합니다. 복원된 행은 imported로 표시됩니다.

스냅샷은 배포 백업이 아닙니다. 백업 및 복구를 참고하십시오.

감사 로그

메모리를 생성하거나 변경하는 모든 쓰기는 loom.audit_log에 해시만 담은 행을 하나씩 남깁니다 (키, id, 콘텐츠 해시, 행위자, 소스 클래스, 판정이 기록되며 값은 기록되지 않습니다). 매시간 생성되는 체크포인트가 로그를 체인으로 연결합니다. 감사를 참조하세요.

제한 사항

  • 병합되어 사라진 버전의 편집(redaction)은 최선의 노력(best effort)으로 처리됩니다. loom.memory에서는 그렇지만, 미러는 어느 경우에나 정리됩니다.
  • 기록은 미러만큼만 완전합니다. loom.memory에 추가한 컬럼은 같은 마이그레이션에서 loom.memory_versions와 해당 뷰에도 추가해야 합니다.
  • 유효성은 유효 시간(valid-time)만 다룹니다. knowledge_time은 created_at을 폐기(invalid_at) 및 삭제(tombstoned_at) 스탬프와 대조하여 재현하며, 별도의 트랜잭션 시간 테이블은 없습니다.
  • thread_exists=false는 오류가 아닙니다.
  • 롤백은 하드 삭제된 키를 복원하지 않습니다 (skipped_no_head).

관련 문서