기록과 출처
기록과 출처
이 페이지는 영어 원문을 기계 번역한 것이며, 영어 원문이 기준입니다. 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).