그래프 모델: 스페이스, 아이템, 출처
Kumiho 데이터 모델 — 프로젝트, 스페이스, 아이템, 리비전, 아티팩트, 번들, 엣지, kref, 신뢰도에 대한 참조 문서입니다.
Revka가 기억하는 모든 것은 그래프 네이티브 인지 메모리 백엔드인 Kumiho에 저장됩니다. Kumiho는 단순한 키-값 저장소가 아닙니다. 메모리는 계층적 스페이스 안의 아이템으로 존재하며, 각 아이템은 불변 리비전의 체인을 가지고, 아이템들은 출처를 인코딩하는 타입이 지정된 엣지로 연결됩니다. 이 페이지는 해당 데이터 모델에 대한 참조 문서입니다. 프로젝트/스페이스/아이템/리비전/아티팩트/번들 계층 구조, kref 주소 체계, Revka가 사용하는 엣지 및 캡처 타입, AgentTrust 스페이스, 그리고 이 모든 것을 읽고 쓰는 클라이언트 인터페이스(SDK 브리지와 KumihoClient)를 다룹니다.
메모리가 디스크에 어떻게 저장되는지 이해해야 할 때 이 페이지를 참고하십시오. 예를 들어 대시보드의 Memory Auditor를 탐색하거나, Asset Browser를 통해 데이터를 작성하거나, kref를 해석할 때 유용합니다. 에이전트 측 사용 패턴(응답 전 engage, 응답 후 reflect)은 Kumiho 그래프 메모리와 Kumiho 메모리 도구를 참고하십시오. NoneMemory와 Kumiho 간의 런타임 분리에 대해서는 메모리 개요부터 시작하십시오.
계층 구조
섹션 제목: “계층 구조”Kumiho의 객체 모델은 큰 단위에서 작은 단위로 중첩됩니다.
project (예: CognitiveMemory, Revka) └─ space (계층적 경로, 예: Revka/AgentPool) └─ item (이름이 있는 노드 — 하나의 결정, 에이전트, 스킬, …) └─ revision (불변 버전; 리비전은 변경되지 않고 추가됩니다) └─ artifact (리비전에 첨부된 파일/블롭, 예: SKILL.md)트리 전체에 걸쳐 적용되는 두 가지 교차 객체 타입이 있습니다.
- 번들 — 멤버십에 의해 다른 아이템을 그룹화하는 목적의 아이템입니다(팀은 소속 에이전트 멤버를 그룹화하고, 세션은 캡처를 그룹화합니다).
- 엣지 — 출처와 의존성을 인코딩하는, 아이템 간의 타입이 지정된 방향성 관계입니다.
| 객체 | 설명 | 주요 필드 |
|---|---|---|
| 프로젝트 | 최상위 네임스페이스입니다. Revka는 기본적으로 두 개를 사용합니다. CognitiveMemory(사용자 메모리, 세션, 압축)와 Revka(스킬 및 운영 데이터)입니다. | name, description, deprecated, created_at, metadata |
| 스페이스 | 프로젝트 내에서 아이템을 구성하는 계층적 경로입니다(예: Revka/AgentPool). 스페이스는 parent_path 아래에 중첩됩니다. | path, name, parent_path, created_at |
| 아이템 | 이름이 있는 노드입니다 — 하나의 결정, 사실, 에이전트, 스킬 등. kref와 슬러그화된 item_name으로 식별되며, 캡처 타입인 kind를 가집니다. | kref, name, item_name, kind, deprecated, metadata |
| 리비전 | 아이템의 불변 버전입니다. 새 쓰기는 증가하는 number와 함께 리비전을 추가하며, 최신 버전은 latest: true로 표시됩니다. 리비전은 tags(예: published)를 가집니다. | kref, item_kref, number, latest, tags, metadata |
| 아티팩트 | 리비전에 첨부된 파일 또는 블롭(예: SKILL.md, PNG)으로, 바이트가 위치한 곳을 가리키는 location URI를 가집니다. | kref, name, location, revision_kref, item_kref, metadata |
| 번들 | CONTAINS 스타일 멤버십으로 연결된 다른 아이템 kref를 멤버로 가지는 그룹화 아이템입니다. 팀과 세션이 번들입니다. | 번들 kref + members[] (item_kref, added_at, added_in_revision) |
| 엣지 | 두 아이템 간의 타입이 지정된 방향성 관계입니다. | source_kref, target_kref, edge_type, metadata |
kref — 그래프 주소 지정
섹션 제목: “kref — 그래프 주소 지정”kref(Kumiho 참조)는 그래프 내 모든 객체를 가리키는 URI입니다. 기본 형식은 프로젝트, 스페이스 경로, 슬러그화된 이름과 kind 접미사로 아이템을 지정합니다.
kref://CognitiveMemory/Skills/creative-memory.skill특정 리비전이나 아티팩트를 고정하려면 쿼리 파라미터로 선택자를 추가합니다.
kref://CognitiveMemory/Skills/creative-memory.skill?r=2 # 리비전 2kref://CognitiveMemory/Skills/creative-memory.skill?r=2&a=SKILL.md # 리비전 2 내의 아티팩트r=N— 리비전 번호N으로 고정합니다. 생략하면 아이템 자체를 가리키며, 호출자가latest또는 태그를 확인합니다.a=NAME— 해당 리비전 내의 이름이 있는 아티팩트로 고정합니다.
선택자가 포함된 kref를 아이템 수준 작업(deprecate, lookup)에 전달하면, Revka는 ?… 접미사를 제거하여 순수 아이템 kref로 자동으로 변환합니다. 따라서 …creative-memory.skill?r=2&a=SKILL.md와 …creative-memory.skill은 동일한 아이템을 가리킵니다. 이름은 kref에 안전하도록 슬러그화됩니다. 소문자로 변환되고 알파벳/숫자가 아닌 연속 문자는 단일 하이픈으로 축약됩니다("Chose gRPC over REST" → chose-grpc-over-rest).
kref를 구체적인 식별자로 확인하거나 참조된 객체를 가져오려면 kumiho_resolve_kref와 kumiho_get_item MCP 도구를 사용하거나, kumiho_get_revision_by_tag(기본 태그: published)로 태그가 지정된 리비전을 가져오십시오.
Revka 스페이스 계층 구조
섹션 제목: “Revka 스페이스 계층 구조”Revka는 자체 메모리를 Revka/… 접두사([kumiho] space_prefix로 구성 가능) 아래에 관리하고, CognitiveMemory/… 트리는 사용자 메모리와 에이전트 간 공유 지식을 보관합니다. Revka가 관례적으로 사용하는 스페이스는 다음과 같습니다.
| 스페이스 | 목적 |
|---|---|
Revka/AgentPool | 에이전트별 상태 — 정체성, 전문성, 어조, 허용 도구 목록. |
Revka/Plans/<project> | Operator가 프로젝트를 위해 분해한 계획. |
Revka/Sessions | 활성 및 과거 채팅 세션. |
Revka/Goals | 에이전트가 진행 중인 장기 목표. |
Revka/AgentTrust | 에이전트 템플릿별 신뢰 점수 및 최근 결과 버퍼. |
Revka/ClawHub | 마켓플레이스 카탈로그 상태(스킬, 에이전트, 워크플로). |
Revka/Teams | 팀 구성 및 위임 토폴로지. |
Revka/WorkflowRuns | Operator 워크플로 실행 상태 및 이력. |
Revka/Outcomes | 신뢰 점수 계산에 반영되는 실행별 결과. |
CognitiveMemory/Skills | 공유 스킬 라이브러리(에이전트 간 공유 프로시저). |
프로젝트 이름은 [kumiho] 설정에서 지정됩니다. memory_project의 기본값은 CognitiveMemory이고, harness_project의 기본값은 Revka입니다. 전체 설정 블록은 Kumiho 설정을 참고하십시오.
캡처 타입 (아이템 kind)
섹션 제목: “캡처 타입 (아이템 kind)”에이전트가 kumiho_memory_reflect를 통해 메모리를 저장할 때, 각 캡처에는 type이 부여되며 이것이 아이템의 kind가 됩니다. 타입은 검색 순위 및 DreamState 압축 동작을 결정합니다. Revka는 열 가지 타입을 사용합니다.
| 타입 | 사용 시점 | 예시 제목 |
|---|---|---|
decision | 미래 에이전트를 구속해야 하는 근거가 있는 선택. | ”Chose Axum over Actix on Mar 14” |
preference | 안정적인 사용자/운영자 선호도. | ”User wants tests run before commits” |
fact | 세계나 시스템에 대한 검증된 사실. | ”Daemon binds 0.0.0.0:42617 in network mode” |
correction | 잘못된 것으로 판명된 이전 메모리를 대체하는 수정. | ”Operator does NOT auto-restart on panic (correction)“ |
architecture | 높은 수준의 구조적 선택 또는 제약. | ”Operator/Rust split per ADR-005 on Apr 18” |
implementation | 구체적인 작동 방식에 대한 지식. | ”Skill kref resolution flow on Apr 20” |
synthesis | 여러 출처에서 도출된 집계된 인사이트. | ”Q1 channel error patterns rolled up Apr 27” |
reflection | 사후 검토 또는 교훈. | ”Postmortem: stash overlap on Apr 27” |
summary | 압축된 세션 또는 스레드 요약. | ”Apr 27 docs-restructure session summary” |
skill | 나중에 검색될 재사용 가능한 프로시저. | ”creative-memory” |
출처 엣지
섹션 제목: “출처 엣지”출처는 그래프 메모리를 단순한 메모와 구분하는 핵심 요소입니다. Revka는 여섯 가지 엣지 타입을 사용합니다.
| 엣지 타입 | 의미 | 생성 방법 |
|---|---|---|
DERIVED_FROM | 새 캡처가 각 출처에서 파생되었음을 나타냅니다. | kumiho_memory_reflect에 source_krefs를 전달하면 자동으로 추론됩니다. |
DEPENDS_ON | 단계/아이템 B는 A가 완료될 때까지 시작할 수 없음을 나타냅니다. | kumiho_create_edge를 통해 명시적으로 설정합니다. |
REFERENCED | 소프트 포인터 — 한 메모리가 의존하지 않고 다른 메모리를 언급합니다. | kumiho_create_edge 또는 자동 추론. |
CONTAINS | 번들/멤버십 — 세션이 캡처를 포함합니다. | 번들 멤버십. |
CREATED_FROM | 한 아이템이 다른 아이템을 포크하거나 변환한 버전임을 나타냅니다. | kumiho_create_edge. |
BELONGS_TO | 소유권/범위 — 아티팩트를 프로젝트, 워크플로 실행 또는 에이전트에 연결합니다. | kumiho_create_edge. |
권장 패턴: reflect의 discover_edges: true(기본값)를 사용하여 서버 측 LLM이 엣지를 자동으로 추론하도록 합니다. LLM이 추론할 수 없는 의미 정보를 직접 보유한 경우에만 수동으로 엣지를 생성하십시오. DEPENDS_ON 순서 지정이 일반적인 사례입니다. 엣지를 검사하려면 kumiho_get_edges를 사용하거나 Memory Auditor의 포스 그래프를 여십시오.
AgentTrust 스페이스
섹션 제목: “AgentTrust 스페이스”Revka/AgentTrust는 에이전트 템플릿별로 롤링 평판 신호를 보관합니다. 각 아이템은 /<harness>/AgentTrust/<template> 경로에 있으며(따라서 프로젝트는 harness_project, 기본값 Revka), 리비전 메타데이터에는 다음이 포함됩니다.
trust_score— 최신성 가중 평균 성공 비율, 소수점 셋째 자리까지 반올림.total_runs— 기록된 결과 수.total_score— 실행별 점수 가중치의 누적 합계.recent_outcomes— 최근 10개 결과의 링 버퍼, 각각outcome:summary:timestamp형식.last_run,template_name, 선택적last_agent_id.
결과는 고정 가중치로 점수에 반영됩니다. success = 1.0, partial = 0.5, failed = 0.0(인식되지 않는 레이블은 partial로 처리됩니다). 점수는 실행 전체에 걸쳐 해당 가중치의 평균입니다(total_score / total_runs).
신뢰도는 부작용으로 기록됩니다. wait_for_agent 이후 template_name과 status를 모두 포함하여 record_agent_outcome을 호출하면 결과 처리기가 인라인으로 신뢰도를 업데이트합니다. 별도의 “record trust” 도구는 없습니다. 신뢰도는 get_agent_trust 도구를 통해 읽으며, 이 도구는 trust_score 내림차순으로 정렬된 템플릿을 반환합니다. 오케스트레이션 패턴이 이를 활용합니다. refinement_loop은 템플릿의 신뢰도가 0.7 아래로 떨어지면 critic을 자동으로 전환합니다. 신뢰도 업데이트 실패는 치명적이지 않습니다. 쓰기가 실패하면 경고를 기록하지만 기본 결과 기록은 실패하지 않습니다.
신뢰도가 멀티 에이전트 오케스트레이션에 어떻게 활용되는지는 에이전트, 팀 & 스웜과 에이전트 스포닝 & 조정을 참고하십시오.
Revka가 그래프를 읽고 쓰는 방법
섹션 제목: “Revka가 그래프를 읽고 쓰는 방법”Revka는 두 가지 전송 방식을 통해 Kumiho에 접근하며, 둘 다 사용자에게 투명하게 작동합니다.
Kumiho SDK 브리지
섹션 제목: “Kumiho SDK 브리지”SDK 브리지는 프로세스 로컬 Python HTTP 사이드카로, 지연 시간을 낮추기 위해 호스팅된 FastAPI를 우회하고 루프백을 통해 Kumiho Python SDK를 노출합니다. KumihoClient는 이를 기본 전송으로 사용하며, 사용할 수 없는 경우 FastAPI로 폴백합니다.
- 기본적으로 활성화됩니다.
REVKA_KUMIHO_SDK_BRIDGE=0(false/no/off도 가능)으로 설정하여 비활성화할 수 있습니다. - 브리지 스크립트
kumiho_sdk_bridge.py는 처음 사용 시 임베디드 리소스에서~/.revka/kumiho/kumiho_sdk_bridge.py로 생성되며,127.0.0.1:<ephemeral-port>에서 수신 대기합니다. ~/.revka/kumiho/venv/에 Kumiho Python venv가 필요합니다. venv가 없으면 브리지가 시작에 실패하고 모든 요청이 호스팅된 FastAPI로 폴백됩니다(정상적인 동작).- 타임아웃: 시작 시 상태 확인에 10초, 요청당 10초. 프로세스가 종료되면 자동으로 재시작됩니다.
- 로그:
~/.revka/logs/kumiho-sdk-bridge.stdout.log및…stderr.log.
FastAPI로의 폴백은 error_code: "kumiho_sdk_bridge_unsupported"가 있는 HTTP 501 응답과 브리지에서의 서버 측 5xx 응답에서도 발생합니다. 특정 요청을 처리한 전송 방식은 Kumiho 프록시 응답의 X-Revka-Kumiho-Transport: sdk-bridge | fastapi 헤더를 통해 확인할 수 있습니다.
KumihoClient CRUD 인터페이스
섹션 제목: “KumihoClient CRUD 인터페이스”KumihoClient는 전체 Kumiho REST API를 래핑하며 게이트웨이 라우트, CLI 명령, 메모리 그래프 엔드포인트에서 사용됩니다. 객체 타입별로 그룹화된 메서드는 다음과 같습니다.
| 객체 | 메서드 |
|---|---|
| 프로젝트 | create_project, ensure_project |
| 스페이스 | create_space, ensure_space, ensure_child_space, list_spaces |
| 아이템 | create_item, list_items, list_items_paged, list_items_filtered, get_item_by_kref, search_items, deprecate_item, delete_item |
| 리비전 | create_revision, get_latest_revision, get_revision, get_revision_by_tag, list_item_revisions, tag_revision, untag_revision, deprecate_revision, batch_get_revisions |
| 아티팩트 | create_artifact, get_artifacts, get_artifacts_by_location, get_artifact_by_name |
| 번들 | create_bundle, get_bundle, delete_bundle, add_bundle_member, remove_bundle_member, list_bundle_members |
| 엣지 | create_edge, list_edges, delete_edge |
| 스킬 | create_skill, list_skills, search_skills, deprecate_skill |
알아두어야 할 동작:
- 인증. FastAPI 전송은
KUMIHO_SERVICE_TOKEN에서X-Kumiho-Token을 전송하고, 브리지는KUMIHO_AUTH_TOKEN을 사용합니다. 두 값은 다를 수 있습니다.KUMIHO_SERVICE_TOKEN이 설정되지 않은 경우KUMIHO_AUTH_TOKEN으로 폴백합니다. - 재시도. GET 요청은 재시도됩니다(3회 시도, 지터 적용 500ms/1500ms 백오프, HTTP 502/503/504/520/522/524에서, 총 15초 예산). 쓰기(POST/PUT/DELETE)는 절대 재시도하지 않습니다 — Kumiho에는 멱등성 키가 없으므로 create를 재시도하면 중복이 생길 수 있습니다.
- 오래된 캐시. 읽기는 10초 동안 신선하게 캐시됩니다. 업스트림 오류 발생 시 최대 120초까지 오래된 응답이 반환됩니다(
X-Revka-Cache: hit | stale로 표시됩니다). 캐시 키는(token_hash, url)이며, 계정 간 오염을 방지하기 위해 토큰 범위로 지정됩니다. - HTML 제거. 업스트림 HTML 오류 페이지(예: Cloudflare 502 스플래시)는 대시보드에 도달하기 전에 제거됩니다.
모델 위에서의 게이트웨이 라우트
섹션 제목: “모델 위에서의 게이트웨이 라우트”대시보드와 외부 클라이언트는 게이트웨이를 통해 동일한 모델에 접근합니다.
GET /api/kumiho/{*path}?param=valueAuthorization: Bearer <gateway token>읽기 전용 프록시입니다. GET 요청만 전달되고, 쿼리 파라미터는 그대로 전달되며, X-Revka-Cache / X-Revka-Kumiho-Transport 헤더는 요청이 처리된 방식을 설명합니다. 쓰기 작업은 타입이 지정된 Asset Browser 라우트(POST /api/assets/items, /api/assets/revisions, /api/assets/artifacts, /api/assets/bundles, /api/assets/edges, …) 또는 타입이 지정된 에이전트/스킬/팀 라우트를 통해 이루어집니다. Memory Auditor를 위한 집계 그래프 뷰는 GET /api/memory/graph입니다.