Kumiho 그래프 메모리

Revka는 모든 영속적 크로스 세션 메모리를 Kumiho에 위임합니다. Kumiho는 Model Context Protocol을 통해 접근하는 그래프 기반 인지 메모리 백엔드입니다. 상태가 없는 LLM 호출은 응답을 반환하는 순간 모든 것을 잊어버리지만, Kumiho는 모든 에이전트에게 크로스 세션 연속성, 타입이 지정된 출처 엣지를 통한 그래프 구조 회상, 그리고 여러 에이전트가 읽고 쓸 수 있는 공유 기반을 제공합니다. 이 가이드에서는 표준 두 반사 패턴 — 응답 전 engage, 응답 후 reflect — 을 사용하여 에이전트를 해당 백엔드에 연결하는 방법과 저장하는 내용을 라우팅, 링크, 통합하는 방법을 설명합니다.

Kumiho MCP 사이드카가 설치된 후 에이전트에서 실제로 사용하려면 이 페이지를 참고하세요. 사이드카 설치 및 [kumiho] 블록 구성은 Kumiho 설정과 Python MCP 사이드카 설치를 참고하세요. 기본 데이터 모델은 그래프 모델: 스페이스, 아이템 & 출처를 참고하세요.

참고

Revka는 메모리를 로컬에 저장하지 않습니다. 런타임 메모리 바인딩은 no-op이며, 영속성은 Kumiho의 역할입니다. Kumiho 컨트롤 플레인(FastAPI + Neo4j)은 사용자 머신에 설치되지 않습니다. ~/.revka/kumiho/run_kumiho_mcp.py의 로컬 사이드카는 컨트롤 플레인과 통신하는 클라이언트 스텁입니다. 메모리 개요를 참고하세요.

사전 요구사항

1. Kumiho MCP 사이드카가 설치되어 실행 중이어야 합니다. 설치 시 ~/.revka/kumiho/venv/에 Python venv가 생성되고 ~/.revka/kumiho/run_kumiho_mcp.py에 실행 심이 생성됩니다. Python MCP 사이드카 설치를 참고하세요.

2. ~/.revka/config.toml에 [kumiho]가 구성되어 있어야 합니다. api_url, 인증 토큰, space_prefix가 필요합니다.

   [kumiho]
   enabled = true
   mode = "cloud"                 # or "local_ce" for self-hosted Community Edition
   mcp_path = "~/.revka/kumiho/run_kumiho_mcp.py"
   api_url = "https://api.kumiho.cloud"
   space_prefix = "Revka"
   memory_project = "CognitiveMemory"
   harness_project = "Revka"
   memory_retrieval_limit = 3

   인증은 환경에서 읽습니다. KUMIHO_AUTH_TOKEN(권장, 로컬 SDK 브리지에서 사용)이 KUMIHO_SERVICE_TOKEN(FastAPI 헤더)보다 우선합니다. revka onboard가 이 값을 ~/.revka/.env에 기록합니다.

3. MCP 도구가 표시되어야 합니다. http://127.0.0.1:42617/tools(또는 GET /api/tools)의 도구 카탈로그를 확인하여 에이전트에 실제로 메모리 도구가 있는지 확인하세요 — kumiho_memory_* 도구가 표시되어야 합니다. 표시되지 않으면 ~/.revka/logs/에서 Kumiho MCP stderr 로그를 확인하세요. 일반적인 원인은 토큰 누락이나 접근 불가능한 api_url입니다. Kumiho 사이드카 및 백엔드 상태에 대한 구조화된 점검은 revka doctor를 실행하세요.

주의

고급 반사(engage, reflect, recall, consolidate, DreamState)는 kumiho[mcp]만이 아닌 kumiho_memory 패키지가 필요합니다. revka doctor에서 kumiho_memory가 누락되었다는 경고가 표시되면 런타임이 lite 부트스트랩 프롬프트로 폴백됩니다. 다음 명령으로 수정하세요:

~/.revka/kumiho/venv/bin/python -m pip install 'kumiho_memory>=0.5.0'

두 반사 패턴

거의 모든 에이전트 루프는 동일한 형태를 따릅니다: 응답 전 engage, 응답 후 reflect. 이것이 표준 통합 패턴입니다.

Engage — 응답 전

요청이 이력이 있을 수 있는 내용과 관련될 경우, kumiho_memory_engage를 정확히 한 번 호출하세요. 이전에 검색했던 내용이 아니라 사용자의 현재 메시지에서 쿼리를 도출하세요.

{
  "tool": "kumiho_memory_engage",
  "args": {
    "query": "<query derived from the user's message>",
    "graph_augmented": false,
    "limit": 5,
    "space_paths": ["Revka/AgentPool", "CognitiveMemory/Skills"]
  }
}

호출 결과로 반환되는 항목:

• context — 프롬프트에 삽입하기 적합한 자연어 요약.
• results — 메타데이터(제목, 타입, created_at)가 포함된 원본 메모리.
• source_krefs — 새 캡처가 영감을 받은 메모리와 연결되도록 매칭 reflect에 전달하는 불투명 식별자.

대화에서 답변이 이미 명확한 경우 engage를 건너뜨세요 — 불필요한 engage는 토큰을 낭비하고 그래프를 저신호 쿼리로 오염시킵니다.

참고

서버는 engage에 5초 중복 제거 윈도우를 적용합니다. 턴당 최대 한 번만 호출하세요. 같은 윈도우 내의 두 번째 engage는 슬롯을 낭비하거나 캐시된 결과를 반환합니다.

Reflect — 응답 후

실질적인 응답 이후, 응답 텍스트와 보존하려는 구조화된 캡처를 포함하여 kumiho_memory_reflect를 한 번 호출하세요.

{
  "tool": "kumiho_memory_reflect",
  "args": {
    "session_id": "<session id>",
    "response": "<your response text>",
    "captures": [
      {
        "type": "decision",
        "title": "Chose gRPC over REST on Jun 18",
        "content": "Picked gRPC for the operator <-> daemon channel for bidirectional streaming; REST was rejected as backpressure-blind.",
        "space_hint": "Revka/Plans/gateway"
      }
    ],
    "source_krefs": ["<from engage results>"],
    "discover_edges": true
  }
}

단일 reflect 호출은 세 가지 작업을 수행합니다:

1. 세션 연속성을 위해 어시스턴트 응답을 버퍼링하여 같은 세션의 다음 engage에서 해당 내용을 볼 수 있게 합니다.
2. 각 캡처를 제공된 source_krefs에 대한 DERIVED_FROM 엣지와 함께 그래프 메모리로 저장합니다.
3. discover_edges: true(기본값)일 경우, 서버 측 LLM 패스를 실행하여 기존 메모리와의 비명시적 연결을 찾습니다.

captures: []로 reflect를 호출해도 응답은 버퍼링되므로, 연속성은 필요하지만 영속 메모리가 필요 없는 간단한 교환에 사용하세요.

주의

사용자가 “이거 기억해줘”, “염두에 두세요”, “메모해줘” 또는 이에 준하는 표현을 사용할 경우, 반드시 reflect를 통해 캡처해야 합니다. 명시적인 기억 요청을 무언으로 건너뛰지 마세요. 반대로, 자격 증명, 비밀, 민감한 페이로드는 캡처 내용에 절대 넣지 마세요 — 요약과 구조화된 캡처만 컨트롤 플레인에 도달하고, 원본 트랜스크립트는 로컬에 유지됩니다.

캡처 타입

저장하는 내용에 맞는 type을 선택하세요. 타입은 검색 순위와 DreamState 통합 동작에 영향을 줍니다.

타입	사용 시점	제목 예시
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”

팁

캡처 제목에는 항상 절대 날짜를 사용하세요("on Jun 18", "today" 아님). 메모리는 세션보다 오래 유지되며, 상대적 시간은 회상 시 무의미해집니다.

출처 엣지

출처는 그래프 메모리를 단순한 메모와 구별하는 요소입니다. 메모리는 계층적 스페이스의 아이템으로 저장되며, 각각 변경 불가능한 리비전을 가지고 리비전은 타입이 지정된 엣지를 포함합니다. Revka는 다음 엣지 타입을 사용합니다:

엣지	의미	생성 방법
DERIVED_FROM	새 캡처가 각 출처에서 파생됨.	reflect에 source_krefs를 전달하면 암시적으로 생성.
DEPENDS_ON	B는 A가 완료되어야 시작 가능 (계획 순서).	kumiho_create_edge로 명시적으로 설정.
REFERENCED	약한 포인터; 하나의 메모리가 다른 메모리를 언급.	발견되거나 명시적으로 설정.
CONTAINS	번들/멤버십; 세션이 캡처를 포함.	발견되거나 명시적으로 설정.
CREATED_FROM	하나의 아이템이 다른 아이템의 포크 또는 변환 버전.	명시적으로 설정.
BELONGS_TO	소유권 또는 범위; 아티팩트를 프로젝트, 실행 또는 에이전트에 연결.	명시적으로 설정.
HANDED_OFF_TO	공유 기반에서의 에이전트 간 핸드오프.	멀티 에이전트 플로우에서 명시적으로 설정.

확신이 없으면 reflect의 discover_edges: true가 엣지를 추론하도록 두세요. LLM이 추론할 수 없는 의미 정보가 있을 때만 수동으로 엣지를 생성하세요 — DEPENDS_ON 순서가 대표적인 경우입니다. 아이템은 kref://space/item?r=N 형식의 kref로 주소 지정됩니다.

스페이스 라우팅

Kumiho는 계층적 스페이스로 메모리를 구성합니다. Revka의 접두사는 Revka/...이고, CognitiveMemory/... 트리는 Revka와 형제 에이전트 간에 공유됩니다. engage에 space_paths를 전달하여 읽기를 라우팅하고, 개별 캡처에 space_hint를 설정하여 쓰기를 라우팅하세요 (캡처별 타겟팅이 일괄 기본값보다 우선합니다).

스페이스	목적
Revka/AgentPool	에이전트별 상태 — 정체성, 전문성, 어조, 허용된 도구.
Revka/Plans/<project>	Operator가 프로젝트를 위해 분해한 계획.
Revka/Sessions	활성 및 과거 채팅 세션.
Revka/Goals	에이전트가 달성하려는 장기 목표.
Revka/AgentTrust	에이전트별 신뢰 점수 및 최근 결과 버퍼.
Revka/ClawHub	마켓플레이스 카탈로그 상태 (스킬, 에이전트, 워크플로우).
Revka/Teams	팀 구성 및 위임 토폴로지.
Revka/WorkflowRuns	Operator 워크플로우 실행 상태 및 이력.
Revka/Outcomes	신뢰 점수 계산에 반영되는 실행별 결과.
CognitiveMemory/Skills	공유 스킬 라이브러리 — 에이전트 간 재사용 가능한 절차.

스킬 발견

스킬은 CognitiveMemory/Skills에 저장된 재사용 가능한 절차입니다. 익숙하지 않은 절차를 즉흥적으로 처리하기 전에 먼저 해당 스페이스를 engage하세요:

{
  "tool": "kumiho_memory_engage",
  "args": {
    "query": "creative output tracking",
    "space_paths": ["CognitiveMemory/Skills"]
  }
}

스킬이 매칭되면 이를 따르고 세션의 나머지 동안 작업 컨텍스트에 캐시하세요. 매칭되는 것이 없어 즉흥으로 절차를 처리한 경우, space_hint: "CognitiveMemory/Skills"와 함께 skill 타입 메모리로 캡처하여 DreamState가 나중에 다듬을 수 있게 하세요.

통합

약 20회 교환 후, 또는 세션이 종료될 때 통합을 트리거하세요:

{
  "tool": "kumiho_memory_consolidate",
  "args": { "session_id": "<session id>" }
}

이 작업은 세션에 버퍼링된 응답을 영속 요약으로 압축하고, 세션의 새 캡처에 대해 엣지 발견을 실행하며, 세션 버퍼를 비웁니다. Revka의 데몬은 세션 종료 시 이를 자동으로 수행하지만, 장기 실행 에이전트는 주기적으로 직접 트리거해야 합니다.

engage/reflect 사이클 외부에서 직접 조회하려면 kumiho_memory_recall을 사용하세요:

{
  "tool": "kumiho_memory_recall",
  "args": { "query": "gRPC decision" }
}

DreamState

DreamState는 kumiho_memory_dream_state 도구를 통해 실행되는 Kumiho의 야간 유지보수 패스입니다. 오래된 메모리를 폐기하고, 메타데이터를 보강하며, 태그를 추가하고, 관련 메모리를 연결하여 그래프가 성장해도 일관성을 유지합니다.

revka onboard는 Kumiho 메모리 백엔드를 선택할 때 DreamState를 야간 cron 작업으로 설치할지 제안합니다. 실행 시간(자정, 오전 2시, 기본값 오전 3시, 오전 4시, 또는 오전 6시)을 선택할 수 있습니다. 나중에 revka cron으로 추가하거나 변경하세요:

revka cron list
revka cron add "0 3 * * *" --tz UTC "revka agent -m 'run DreamState memory consolidation'"

스케줄링 구문은 revka cron을, 설치 시 프롬프트는 온보딩 마법사를 참고하세요.

점진적 성능 저하 및 주의사항

• 무음 저하 모드. 컨트롤 플레인에 접근할 수 없으면 Kumiho MCP는 폐쇄 실패합니다 — engage와 reflect가 오류를 반환하며, 에이전트는 차단되지 않고 영속성 없이 계속 동작해야 합니다. 운영자 검토를 위해 오류를 ~/.revka/logs/에 기록하세요.
• 오래된 메모리. 파일, 함수, 플래그를 명명하는 메모리는 작성 당시 해당 대상이 존재했다는 주장입니다. 회상된 메모리에 따라 행동하기 전에 대상이 아직 존재하는지 확인하세요. 없어졌다면 kumiho_deprecate_item으로 아이템을 폐기하거나 업데이트하세요.
• Kumiho가 정규 저장소. 크로스 세션 지식에 프로세스 내 상태를 의존하지 마세요. 세션 간에 기억해야 할 내용은 Kumiho에 도달해야 합니다.
• 전송 폴백. 읽기는 낮은 지연을 위해 프로세스 로컬 SDK 브리지를 우선적으로 사용하며, 자동으로 호스팅된 FastAPI로 폴백합니다. REVKA_KUMIHO_SDK_BRIDGE=0으로 호스팅 경로를 강제 사용할 수 있습니다.

그래프 검사

대시보드는 /memory에서 Kumiho 메모리를 강제 지향 그래프로 렌더링합니다 — 종류 또는 스페이스별로 필터링하고 개별 노드를 검사할 수 있습니다. 백엔드 엔드포인트는 GET /api/memory/graph로, 노드, 엣지, 스페이스를 하나의 페이로드로 반환합니다. GET /api/kumiho/{*path}의 읽기 전용 프록시는 모든 Kumiho GET 엔드포인트를 전달합니다. 두 엔드포인트 모두 게이트웨이 베어러 인증이 필요합니다. 에셋 & 메모리 탐색기와 메모리 그래프 & 에셋 브라우저 API를 참고하세요.

CLI에서 revka memory는 Kumiho 기반 Memory 스페이스를 직접 검사합니다:

revka memory stats
revka memory list --category core --limit 20
revka memory get my-decision-key

전체 명령 세트는 revka memory & estop를 참고하세요.

통합 검증

새로운 Kumiho 인식 에이전트 경로에 대한 빠른 스모크 테스트:

1. 도구 표시. GET /api/tools가 kumiho_memory_engage, kumiho_memory_reflect, kumiho_memory_recall, kumiho_memory_consolidate를 최소한 반환해야 합니다.

2. Engage 왕복. 이전에 저장된 내용에 히트해야 하는 쿼리로 kumiho_memory_engage를 호출하고 results가 비어 있지 않은지 확인하세요.

3. 캡처와 함께 Reflect. 하나의 캡처로 kumiho_memory_reflect를 호출하고, kref가 반환되며 /memory에 캡처가 나타나는지 확인하세요.

4. 엣지 형성. engage → reflect 쌍이 새 캡처에서 출처 kref로의 DERIVED_FROM 엣지를 생성하는지 확인하세요. kumiho_get_edges 또는 /memory 강제 그래프로 검사하세요.

여기서 실패하는 경우는 거의 항상 다음 중 하나입니다: 인증 토큰 누락, 접근 불가능한 컨트롤 플레인, MCP 사이드카 미시작, 또는 데몬의 [kumiho] 구성이 실행 중인 사이드카의 환경과 불일치.

다음 단계

Kumiho 설정 사이드카를 설치하고, [kumiho] 블록을 구성하고, revka doctor로 검증하세요.

그래프 모델: 스페이스, 아이템 & 출처 Kumiho 데이터 모델: 스페이스, 아이템, 리비전, kref, 신뢰.

Kumiho 메모리 도구 모든 kumiho_memory_* MCP 도구와 파라미터에 대한 레퍼런스.

메모리 개요 Kumiho가 정규 저장소인 이유와 런타임 바인딩 동작 방식.