에셋 및 메모리 탐색기

두 개의 대시보드 라우트를 통해 Kumiho 그래프 메모리를 확인할 수 있습니다. Assets 페이지(/assets)는 project → space → item → revision → artifact 계층 구조를 탐색하고 편집할 수 있는 전체 에셋 관리자이며, Memory 페이지(/memory)는 지식 그래프 자체를 Obsidian 스타일의 힘-방향 그래프로 렌더링합니다. 특정 엔티티를 생성·검사·버전 관리·연결하려면 Assets 페이지를 사용하고, 그래프의 전체적인 형태 — 어떤 노드가 존재하는지, 종류별로 어떻게 클러스터를 이루는지, 서로 어떻게 연결되는지 — 를 시각적으로 파악하려면 Memory 페이지를 사용하세요.

두 페이지는 동일한 Kumiho 스토어에 대한 읽기/쓰기 뷰입니다. 두 페이지 모두 Memory graph & Asset Browser API에 문서화된 게이트웨이 엔드포인트 위에 구축되어 있으므로, 여기서 수행하는 모든 작업은 스크립트로도 자동화할 수 있습니다. space, item, revision, kref, bundle, edge, provenance 등 기반 개념에 대해서는 그래프 모델: spaces, items & provenance를 참고하세요.

참고

Revka는 그래프를 로컬에 저장하지 않습니다. 두 페이지 모두 게이트웨이를 통해 Kumiho와 통신하며, 게이트웨이는 Kumiho 컨트롤 플레인으로 요청을 프록시합니다. Kumiho 사이드카가 설치되지 않았거나 토큰이 누락된 경우 이 페이지들은 비어 있거나 일부 기능이 제한됩니다 — Kumiho 설정을 참고하세요.

Assets 페이지

사이드바의 Operations 섹션에서 /assets로 이동합니다. 이 페이지는 Kumiho 에셋 관리자로, project·space·item·revision·artifact·bundle·edge를 탐색하고 생성할 수 있으며, 힘-방향 의존성 그래프, 아티팩트 콘텐츠 에디터, 리비전 태깅, 번들 멤버십 관리 기능을 제공합니다.

?project=<name> 쿼리 파라미터를 사용하여 특정 프로젝트로 딥 링크할 수 있습니다:

/assets?project=CognitiveMemory

Kumiho 계층 구조

Assets 페이지는 Kumiho의 데이터 모델을 그대로 반영합니다. 브레드크럼을 사용하여 계층을 탐색하거나 상위 레벨로 이동할 수 있습니다:

project  →  space  →  item  →  revision  →  artifact

레벨	설명
Project	최상위 컨테이너 (예: 메모리용 CognitiveMemory, 운영 데이터용 Revka).
Space	프로젝트 내의 계층형 폴더로, 관련 아이템을 묶어 범위를 지정합니다.
Item	kref로 식별되는 단일 주소 지정 가능 객체 — 결정, 사실, 스킬, 문서 등.
Revision	아이템의 불변 버전. 편집하면 기존 버전을 수정하는 대신 새 리비전이 생성됩니다.
Artifact	리비전에 첨부된 파일 (마크다운 노트, 이미지, 보고서 등).

각 레벨은 탐색 시 온디맨드로 데이터를 가져옵니다:

GET /api/kumiho/projects
GET /api/kumiho/spaces?parent_path=<path>
GET /api/kumiho/items?space_path=<path>&kind=<kind>
GET /api/kumiho/revisions?item_kref=<kref>
GET /api/kumiho/artifacts?revision_kref=<kref>
Authorization: Bearer <token>

이 읽기 요청은 읽기 전용 Kumiho 프록시를 통해 처리됩니다. 쓰기 요청은 아래에서 설명하는 타입이 지정된 /api/assets/* 라우트를 통해 처리됩니다.

엔티티 생성

각 엔티티 유형(project, space, item, bundle, revision, artifact, edge, tag)에는 전용 생성 모달이 있습니다. 생성 작업은 타입이 지정된 Asset Browser 쓰기 API에 직접 매핑됩니다:

POST /api/assets/projects        { "name": "CognitiveMemory" }
POST /api/assets/spaces          { "parent_path": "/CognitiveMemory", "name": "Decisions" }
POST /api/assets/items           { "space_path": "/CognitiveMemory/Decisions", "item_name": "chose-grpc", "kind": "decision" }
POST /api/assets/revisions       { "item_kref": "kref://CognitiveMemory/Decisions/chose-grpc" }
POST /api/assets/artifacts       { "revision_kref": "<rev kref>", "name": "NOTES.md", "content": "..." }
Authorization: Bearer <token>

검색 바를 사용하면 현재 프로젝트의 아이템에 대해 텍스트 검색을 실행할 수 있어, 트리 전체를 탐색하지 않고도 원하는 아이템으로 바로 이동할 수 있습니다.

노드 종류 및 엣지 타입

아이템을 생성할 때 kind를 설정합니다 — Kumiho가 아이템을 분류하는 데 사용하는 시맨틱 레이블입니다. Kind는 의존성 그래프와 메모리 그래프의 색상, 그리고 적용할 수 있는 필터를 결정합니다. 주요 kind는 다음과 같습니다:

conversation, decision, fact, preference, summary, reflection, plan, synthesis, correction, error, skill, architecture, document, bundle, implementation, action, instruction, conditional, space, skilldef.

아이템은 provenance를 나타내는 타입이 지정된 엣지로 연결됩니다. 엣지는 아이템 kref가 아닌 revision kref를 연결합니다. 사용 가능한 엣지 타입은 다음과 같습니다:

엣지 타입	의미
DEPENDS_ON	소스가 완료될 때까지 타겟을 시작할 수 없습니다.
DERIVED_FROM	타겟이 소스에서 파생되었습니다 (source_krefs에서 자동 생성).
REFERENCED	리비전 간의 소프트 포인터.
CONTAINS	멤버십 관계 — 예를 들어 세션이 자신의 캡처를 포함합니다.
CREATED_FROM	포크되거나 변환된 버전.
BELONGS_TO	아티팩트를 프로젝트, 워크플로우, 또는 에이전트에 연결합니다.
SUPERSEDES	소스가 타겟을 대체합니다.
MEMBER	번들 멤버십 관계.
USED_TEMPLATE	소스가 템플릿으로부터 생성되었습니다.

엣지 모달을 통해 Assets 페이지에서 엣지를 생성하거나, API를 통해 직접 생성할 수 있습니다:

POST /api/assets/edges
{ "source_kref": "<rev kref>", "target_kref": "<rev kref>", "edge_type": "DERIVED_FROM" }
Authorization: Bearer <token>

의존성 그래프 뷰어

선택한 리비전에 대해 Assets 페이지는 힘-방향 의존성 그래프를 렌더링하여, 해당 노드가 무엇에 의존하는지, 무엇이 해당 노드에 의존하는지 확인할 수 있습니다. 세 가지 컨트롤로 탐색 범위를 조정합니다:

• Direction — upstream, downstream, both 중 선택.
• Depth — 중심 노드에서 몇 개의 엣지 홉까지 탐색할지 지정 (최대 3).
• Edge type filter — 특정 엣지 타입으로만 탐색을 제한하거나, 모두 표시.

뷰어는 다음 엔드포인트를 사용합니다:

GET /api/assets/dependency-graph?revision_kref=<kref>&direction=both&depth=2&edge_type=all
Authorization: Bearer <token>

노드 수 제한(node_limit, 기본값 100, 최대 200)에 도달하면 응답 확장이 중단되고 truncated 플래그가 설정되므로, 매우 큰 이웃 그래프도 렌더링 가능한 상태로 유지됩니다.

아티팩트 에디터

아티팩트를 클릭하면 아티팩트 뷰어/에디터 모달이 열립니다. 모달은 본문 텍스트를 가져와 렌더링하며, 편집 가능한 아티팩트의 경우 콘텐츠를 인라인으로 수정하고 저장할 수 있습니다.

GET /api/artifact-body?location=<uri>
PUT /api/assets/artifacts/content
{ "artifact_kref": "<artifact kref>", "revision_kref": "<rev kref>", "content": "updated body" }
Authorization: Bearer <token>

주의

아티팩트 본문을 편집하면 새 리비전이 자동으로 생성될 수 있습니다. 기반 리비전이 미게시 상태이면 파일이 제자리에서 덮어씌워집니다. 이미 게시된 리비전의 경우, 게시된 이력은 불변이므로 게이트웨이는 새 리비전을 생성하고 새 콘텐츠를 버전 지정된 파일에 기록한 뒤 다른 아티팩트를 앞으로 복사합니다. 응답의 created_revision 플래그를 통해 어떤 경로가 사용되었는지 확인할 수 있습니다.

리비전 이력 스트립은 선택한 아이템의 모든 리비전, 각 리비전의 태그, 그리고 어떤 리비전이 게시되었는지를 표시합니다. 여기서 태깅·태그 제거·게시·폐기를 수행할 수 있습니다:

POST   /api/assets/revisions/publish   { "kref": "<rev kref>" }
POST   /api/assets/revisions/tags      { "kref": "<rev kref>", "tag": "milestone" }
DELETE /api/assets/revisions/tags      { "kref": "<rev kref>", "tag": "milestone" }
POST   /api/assets/items/deprecate
POST   /api/assets/revisions/deprecate
POST   /api/assets/artifacts/deprecate
Authorization: Bearer <token>

번들 관리자

번들은 Kumiho의 그룹화 구조로, 하나의 단위로 처리되는 아이템 집합입니다(팀, 캐논 세트, 세션 캡처 등). 번들 관리자를 통해 번들 생성, 멤버 추가·제거, 멤버별 kind 칩이 포함된 멤버 목록 확인이 가능합니다.

GET    /api/assets/bundles?project=<name>&space_path=<path>
GET    /api/assets/bundles/members?bundle_kref=<kref>
POST   /api/assets/bundles
POST   /api/assets/bundles/members   { "bundle_kref": "...", "item_kref": "..." }
DELETE /api/assets/bundles/members   { "bundle_kref": "...", "item_kref": "..." }
Authorization: Bearer <token>

kref 복사

선택한 모든 엔티티에는 해당 kref://... 식별자를 클립보드에 복사하는 kref 복사 버튼이 노출됩니다. Kref는 Kumiho가 모든 것을 주소 지정하는 방식입니다 — 복사한 kref를 딥 링크 생성, 엣지 연결, 또는 MCP 도구나 API 호출에 전달하는 데 활용하세요. 형식은 kref://<space>/<item>?r=<N>이며, 선택적인 ?r=N 셀렉터로 특정 리비전을 고정할 수 있습니다.

Memory / 지식 그래프 페이지

사이드바의 Inspection 섹션에서 /memory로 이동합니다. (레거시 /memory-auditor URL은 이 페이지로 리디렉션됩니다.) 이 페이지는 Kumiho 메모리 그래프를 인터랙티브한 2D 힘-방향 그래프로 렌더링합니다. 각 노드는 kind에 따라 색상이 지정된 메모리 아이템이며, 엣지는 아이템 간의 관계를 나타냅니다. 에이전트가 기억한 내용과 그 연결 관계를 감사하는 데 활용하세요.

그래프 로드 및 필터링

그래프는 단일 집계 페이로드로 가져옵니다:

GET /api/memory/graph?limit=100&kinds=decision,fact&space=CognitiveMemory/Skills
Authorization: Bearer <token>

파라미터	타입	기본값	설명
limit	int	100 (최대 500)	포함할 최대 아이템 수 — 노드 제한 슬라이더로 조정.
kinds	string	—	쉼표로 구분된 kind 필터, kind 칩으로 설정.
space	string	—	space-path 접두사 필터, 스페이스 드롭다운으로 설정.

왼쪽 필터 패널에서 다음 작업을 수행할 수 있습니다:

• Kind로 필터링 — kind 칩을 토글하여 노드 세트를 좁힙니다.
• Space로 필터링 — 드롭다운에서 스페이스를 선택하여 그래프 범위를 지정합니다.
• 노드 제한 설정 — 슬라이더를 25~500 노드 사이로 조정합니다.
• 검색 — 검색 박스에 텍스트를 입력하면 일치하는 노드가 강조 표시됩니다 (입력은 디바운스 처리되며, 일치 항목은 제거되지 않고 강조만 됩니다).

참고

그래프 엔드포인트는 대용량 그래프 조립에 시간이 걸리므로 충분한 타임아웃을 설정합니다. 대시보드는 일시적인 게이트웨이 오류(408, 502, 503, 504) 발생 시 최대 두 번까지 재시도한 후 실패를 표시합니다. 엣지는 두 엔드포인트가 모두 반환된 노드 세트에 포함된 경우에만 렌더링되므로, 노드 제한을 높이면 더 작은 세트에서는 보이지 않던 연결이 드러날 수 있습니다.

노드 종류 및 색상

노드는 kind에 따라 색상이 지정되어 클러스터를 한눈에 파악할 수 있습니다. Assets 페이지에서 설정하는 것과 동일한 kind가 여기에 색상 계열별로 그룹화되어 나타납니다 — 예를 들어 conversation, skill, architecture, document는 하나의 계열을 공유하고, decision, action, instruction, conditional는 다른 계열을 형성하며, correction과 error는 위험으로 표시되고, bundle/implementation은 활성 상태로 강조됩니다. 엣지는 의존성 그래프와 동일한 provenance 타입을 사용합니다 (DEPENDS_ON, DERIVED_FROM, REFERENCED, CONTAINS, CREATED_FROM, BELONGS_TO, SUPERSEDES, MEMBER, USED_TEMPLATE).

노드 검사

노드를 클릭하면 오른쪽 레일에 상세 정보가 표시됩니다. 레일에는 노드의 메타데이터(제목, 요약, kind, space, 생성 시간)와 해당 노드의 revision kref를 복사하는 kref 복사 버튼이 표시됩니다. bundle 노드의 경우 레일에서 번들 멤버를 조회하여 목록으로 보여줍니다:

GET /api/kumiho/revisions?item_kref=<kref>
GET /api/kumiho/bundles/members?bundle_kref=<kref>
Authorization: Bearer <token>

1. /memory를 열고 그래프가 로드될 때까지 기다립니다.
2. kind 칩, 스페이스 드롭다운, 또는 노드 제한 슬라이더로 노드 세트를 좁힙니다.
3. 검색 박스에 텍스트를 입력하여 노드를 찾습니다. 일치하는 노드는 제자리에서 강조 표시됩니다.
4. 노드를 클릭하면 오른쪽 레일에서 메타데이터를 검사할 수 있습니다.
5. kref를 복사하여 딥 링크 생성, Assets 페이지에서 엣지 연결, 또는 API 호출에 활용합니다.

관련 페이지

Memory graph & Asset Browser API 두 페이지가 구축된 게이트웨이 엔드포인트와 전체 요청 및 응답 형식.

그래프 모델: spaces, items & provenance 모든 project, space, item, revision, edge, kref의 기반이 되는 데이터 모델.

Kumiho 그래프 메모리 Revka가 Kumiho를 통해 메모리를 저장하고 회상하는 방법에 대한 운영자 가이드.

Kumiho 설정 Kumiho 사이드카를 설치하고 토큰을 구성하여 이 페이지에 데이터를 표시합니다.