Kumiho 메모리 도구

kumiho_memory_* MCP 도구 전체 레퍼런스: engage, reflect, consolidate, recall, store 등.

[kumiho].enabled = true로 설정하면 Revka는 내부 에이전트를 제외한 모든 에이전트에 Kumiho MCP 사이드카를 주입하며, 사이드카는 해당 에이전트의 도구 카탈로그에 kumiho_memory_* 도구 집합을 게시합니다. 이 도구들은 에이전트가 자체 LLM 루프 중에 그래프 기반 메모리 백엔드를 읽고 쓸 때 호출하는 도구입니다. 이 페이지는 각 도구의 레퍼런스로, 각 도구의 역할, 파라미터, 반환 형식, 그리고 사용 시점을 다룹니다.

메모리 개요에서 no-op 런타임 바인딩과 Kumiho의 개념적 구분을 확인하고, Kumiho 설정에서 사이드카 설치 및 인증 토큰 구성 방법을 확인하세요. 에이전트 루프 전체 흐름은 Kumiho 그래프 메모리를 참고하십시오. 스페이스, 아이템, 리비전, kref, 엣지 등 기반 데이터 모델은 그래프 모델: 스페이스, 아이템 & 출처를 참고하십시오.

두 가지 반사 패턴

거의 모든 Revka 에이전트 루프는 동일한 구조를 따릅니다. 응답 전에 engage로 메모리를 조회하고, 응답 후에 reflect로 기록합니다. 이 패턴을 담당하는 두 도구가 있으며, 이 페이지의 나머지 도구들은 이 두 도구의 심화 변형이거나 유지보수 작업입니다.

응답 전, kumiho_memory_engage를 사용자의 현재 메시지에서 도출한 쿼리와 함께 한 번 호출합니다. 관련 메모리를 불러와 프롬프트에 주입 가능한 context 문자열과 source_krefs를 반환합니다.
응답 후, kumiho_memory_reflect를 응답 텍스트와 구조화된 captures와 함께 한 번 호출합니다. engage에서 받은 source_krefs를 전달하면, 새로운 캡처가 영감을 준 기존 메모리에 DERIVED_FROM 엣지로 연결됩니다.

user message
   │
   ▼
kumiho_memory_engage   ──►  context + source_krefs
   │
   ▼
(agent reasons, responds)
   │
   ▼
kumiho_memory_reflect  ──►  captures stored, DERIVED_FROM edges created

오퍼레이터 측 메모리 도구

오퍼레이터 MCP가 실행 중이면, 오퍼레이터 자체(스폰된 서브 에이전트가 아닌)도 그래프를 engage하고 쓸 수 있도록 사이드카 도구를 미러링한 자체 메모리 도구 집합을 노출합니다. 이 도구들은 kumiho_ 접두사 없이 memory_engage, memory_reflect 등으로 명명되며, 대부분 사이드카 파라미터를 공유합니다. 설정에서 두 가지 제한이 오퍼레이터 측에 적용됩니다.

min_score는 [memory].min_relevance_score로 하한이 설정됩니다.
limit은 [kumiho].memory_retrieval_limit으로 상한이 설정됩니다(기본값 3).

오퍼레이터 도구	역할 / 목적
`memory_engage`	조회 + 컨텍스트 생성 → `{ context, results, source_krefs, count }`.
`memory_reflect`	출처 엣지와 함께 구조화된 캡처를 저장합니다.
`memory_retrieve`	시맨틱 검색.
`memory_search`	`context_filter`, `name_filter`, `kind_filter`로 구조화 검색.
`memory_fulltext`	전문 키워드 검색.
`memory_get_item`	kref로 아이템을 가져옵니다.
`memory_resolve_kref`	kref를 구체적인 식별자로 변환합니다.
`memory_get_revision_by_tag`	태그(기본값 `"published"`)로 리비전을 가져옵니다.
`memory_store`	자동 스택 기능으로 메모리 번들을 저장합니다.
`memory_graph`	포스-그래프 시각화를 위한 노드 + 엣지를 집계합니다.

이 페이지의 나머지 부분은 사이드카의 kumiho_memory_* 도구를 상세히 설명합니다. 오퍼레이터 측 동등 도구는 별도로 명시하지 않는 한 동일한 핵심 인수를 받습니다.

kumiho_memory_engage

응답 전에 메모리를 확인합니다. 조회와 컨텍스트 생성을 하나의 호출로 결합합니다. 그래프를 검색하고, 컨텍스트 요약을 생성하며, reflect에 전달할 source kref를 반환합니다.

파라미터

파라미터	타입	기본값	설명
`query`	string	— (필수)	사용자의 현재 메시지에서 도출한 자연어 쿼리.
`limit`	number	`5`	반환할 최대 결과 수.
`graph_augmented`	boolean	`false`	간접적이거나 의사결정 체인 질문에 대한 그래프 증강 조회 활성화.
`space_paths`	string[]	—	검색을 이 스페이스 경로로 제한합니다(예: `["CognitiveMemory/Skills"]`).
`memory_types`	string[]	—	메모리 타입으로 필터링합니다(예: `["decision", "preference"]`).
`min_score`	number (0–1)	`0`	컨텍스트 생성 전에 이 임계값 미만의 결과를 제외합니다.
`recall_mode`	`"full"` \| `"summarized"`	`"summarized"`	`summarized`는 제목 + 요약만 반환하고, `full`은 아티팩트 콘텐츠를 포함합니다.

반환값

context — 미리 작성된 프롬프트 주입용 자연어 요약.
results — 메타데이터(제목, 타입, created_at)를 포함한 원시 메모리.
source_krefs — 매칭되는 reflect에 전달할 불투명 식별자.

예시

{
  "tool": "kumiho_memory_engage",
  "args": {
    "query": "transport choice for the operator-daemon channel",
    "graph_augmented": false,
    "limit": 5,
    "space_paths": ["Revka/AgentPool", "CognitiveMemory/Skills"]
  }
}

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

kumiho_memory_reflect

응답 후에 중요한 내용을 캡처합니다. 단일 호출로 어시스턴트 응답을 세션 연속성을 위해 버퍼링하고, 각 구조화된 캡처를 그래프 메모리로 저장하며, 기본적으로 기존 메모리에 대한 엣지 탐색을 실행합니다. 에이전트 자체 LLM이 기억할 내용을 식별하므로 외부 API 키가 필요하지 않습니다.

파라미터

파라미터	타입	기본값	설명
`session_id`	string	— (필수)	세션 식별자.
`response`	string	— (필수)	버퍼링할 어시스턴트 응답 텍스트.
`captures`	object[]	—	저장할 구조화된 사실(아래 참고). 사소한 교환은 `[]`를 전달하거나 생략하면 응답만 버퍼링됩니다.
`source_krefs`	string[]	—	engage 결과의 kref — 소스 메모리에 `DERIVED_FROM` 엣지를 생성합니다.
`space_path`	string	—	자체 `space_hint`가 없는 캡처의 기본 스페이스 경로.
`discover_edges`	boolean	`true`	저장된 캡처에 엣지 탐색을 실행합니다. 서버 측 LLM이 없으면 자동으로 건너뜁니다.

captures의 각 항목은 다음 필드를 가집니다.

필드	타입	설명
`type`	string	— (필수) 캡처 타입: `decision`, `preference`, `fact`, `correction`, `architecture`, `implementation`, `synthesis`, `reflection`, `summary`, `skill`.
`title`	string	— (필수) 절대 날짜를 사용한 짧은 제목(예: `"Chose gRPC on Mar 27"`).
`content`	string	— (필수) 저장할 콘텐츠.
`space_hint`	string	캡처별 스페이스 재정의. 최상위 `space_path`보다 우선합니다.
`tags`	string[]	분류 태그.

예시

{
  "tool": "kumiho_memory_reflect",
  "args": {
    "session_id": "sess-2026-06-18-001",
    "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/transport"
      }
    ],
    "source_krefs": ["kref://Revka/AgentPool/transport?r=4"],
    "discover_edges": true
  }
}

kumiho_memory_recall

시맨틱 쿼리로 장기 메모리를 검색합니다. engage보다 가볍습니다. 아무것도 버퍼링하지 않고 reflect 라운드트립을 위한 source kref를 생성하지 않으며, 매칭된 메모리만 반환합니다. engage와 동일한 5초 중복 제거 가드를 공유합니다.

파라미터

파라미터	타입	기본값	설명
`query`	string	— (필수)	자연어 검색 쿼리.
`limit`	number	`5`	반환할 최대 결과 수.
`graph_augmented`	boolean	`false`	벡터 검색이 놓치는 연결된 메모리를 찾기 위한 다중 쿼리 재구성 + 엣지 탐색. `KUMIHO_GRAPH_AUGMENTED_RECALL=1` 환경 변수가 필요합니다.
`space_paths`	string[]	—	이 스페이스 경로로 검색을 제한합니다.
`memory_types`	string[]	—	메모리 타입으로 필터링합니다.
`min_score`	number (0–1)	`0`	이 점수 미만의 결과를 제외합니다.
`recall_mode`	`"full"` \| `"summarized"`	`"summarized"`	`full`은 원시 아티팩트 콘텐츠를 포함하고, `summarized`는 제목 + 요약만 반환합니다.

예시

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

kumiho_memory_retrieve

관련성 순위 및 자동 오타 허용 기능이 포함된 Google 스타일의 퍼지 검색으로 메모리를 검색합니다. 필요 시 번들 및 패턴 검색으로 폴백합니다. engage/recall의 엄격한 시맨틱 조회 대신 유연한 키워드 스타일 매칭이 필요할 때 사용하십시오.

파라미터

파라미터	타입	기본값	설명
`query`	string	—	자연어 쿼리. 퍼지 다중 단어 매칭을 지원합니다.
`project`	string	`"CognitiveMemory"`	프로젝트 이름.
`space_paths`	string[]	—	특정 스페이스 경로로 검색을 제한합니다.
`memory_types`	string[]	—	메모리 타입으로 필터링합니다(예: `["decision", "summary", "error"]`).
`keywords`	string[]	—	검색에 포함할 추가 키워드.
`topics`	string[]	—	검색할 토픽 이름.
`bundle_names`	string[]	—	특정 번들 내에서 검색합니다.
`mode`	string	`"search"`	`search`(퍼지), `first`(날짜순 가장 오래된 항목), 또는 `latest`.
`memory_item_kind`	string	`"conversation"`	메모리 항목의 아이템 종류.
`include_revision_metadata`	boolean	`true`	더 깊은 매칭을 위해 리비전 메타데이터도 검색합니다.
`limit`	number	`5`	반환할 최대 결과 수.

kumiho_fulltext_search

관련성 순위 및 자동 오타 허용 기능이 포함된 아이템 전체 전문 퍼지 검색. 상위 Kumiho 티어에서는 리비전 메타데이터를 스캔할 때 하이브리드 검색(전문 + 벡터 유사도)을 사용합니다. 자연어 쿼리에는 원시 아이템 검색보다 이 도구를 우선 사용하십시오.

파라미터

파라미터	타입	기본값	설명
`query`	string	— (필수)	검색어(퍼지, 오타 허용).
`context`	string	`""`	kref 접두사로 검색을 제한합니다(예: `"CognitiveMemory/Skills"`). 비어 있으면 전체 검색.
`kind`	string	`""`	정확한 종류 매칭(예: `"conversation"`, `"bundle"`).
`limit`	number	`20`	반환할 최대 결과 수.
`include_deprecated`	boolean	`false`	소프트 삭제된 아이템을 포함합니다.
`include_metadata`	boolean	`false`	결과에 전체 아이템 메타데이터를 포함합니다.
`include_revision_metadata`	boolean	`false`	리비전 태그/메타데이터도 검색합니다(속도가 느리지만 더 철저합니다).
`include_artifact_metadata`	boolean	`false`	아티팩트 이름/메타데이터도 검색합니다(속도가 느립니다).

kumiho_memory_store

하나의 호출로 메모리 항목을 저장합니다. 스페이스, 아이템, 리비전, 아티팩트, 번들, 엣지를 함께 생성하거나 재사용합니다. 기본적으로 유사한 기존 아이템을 찾아 중복을 생성하는 대신 새 리비전을 스택합니다. engage/reflect 흐름 외부에서 직접적인 구조화 쓰기를 수행할 때 사용하십시오.

파라미터 (선택)

파라미터	타입	기본값	설명
`user_text`	string	— (필수)	저장할 사용자 측 텍스트.
`assistant_text`	string	—	어시스턴트 측 텍스트.
`title`	string	—	아이템 제목.
`summary`	string	—	아이템 요약.
`memory_type`	string	`"summary"`	`summary`, `decision`, `fact`, `reflection`, 또는 `error`.
`project`	string	`"CognitiveMemory"`	프로젝트 이름.
`space_path`	string	—	전체 분류 스페이스 경로.
`space_hint`	string	—	`space_path`가 생략된 경우의 짧은 분류 힌트.
`bundle_name`	string	—	번들 이름(기본값은 토픽 슬러그).
`tags`	string[]	—	분류 태그.
`source_revision_krefs`	string[]	—	출처 엣지를 위한 소스 kref.
`edge_type`	string	`"DERIVED_FROM"`	출처 링크의 엣지 타입.
`stack_revisions`	boolean	`true`	true이면 유사한 아이템을 찾아 리비전을 스택하고, `false`이면 항상 새 아이템을 생성합니다.
`metadata`	object	—	추가 메타데이터(문자열 값만).

kumiho_memory_ingest

사용자 메시지를 인지 메모리에 수집합니다. 메시지를 워킹 메모리 스토어에 버퍼링하고, 관련 장기 메모리를 조회한 다음, 워킹 메모리와 장기 컨텍스트를 모두 반환합니다. engage/reflect 패턴 대신 ingest → respond → add_response 루프 전체를 구동하는 에이전트를 위한 메시지 수준 진입점입니다.

파라미터

파라미터	타입	기본값	설명
`user_id`	string	— (필수)	안정적인 사용자 식별자.
`message`	string	— (필수)	사용자 메시지 텍스트.
`session_id`	string	—	기존 세션 ID. 생략 시 자동 생성됩니다.
`context`	string	`"personal"`	메모리 컨텍스트(예: `personal`, `work`).
`recall_limit`	number	`5`	조회할 최대 장기 메모리 수.
`working_memory_limit`	number	`10`	반환할 최대 워킹 메모리 메시지 수.

kumiho_memory_add_response

어시스턴트 응답을 워킹 메모리의 세션 버퍼에 추가합니다. ingest 기반 루프를 사용할 때 응답을 생성한 후 호출합니다(reflect의 경량 대응으로, reflect는 버퍼링과 캡처를 모두 수행합니다).

파라미터

파라미터	타입	설명
`session_id`	string	`ingest`에서 받은 세션 식별자.
`response`	string	어시스턴트 응답 텍스트.

kumiho_memory_store_execution

도구 또는 명령어 실행 결과를 구조화된 메모리로 저장합니다. 성공한 실행은 action 타입으로, 실패한 실행은 error 타입으로 저장됩니다. 캡처된 stdout/stderr는 아티팩트가 되어 에이전트가 실제로 실행한 내용에 대한 감사 추적 구축에 유용합니다.

파라미터

파라미터	타입	기본값	설명
`task`	string	— (필수)	실행된 내용 설명(예: `"git push origin main"`).
`status`	`done` \| `failed` \| `error` \| `blocked`	`"done"`	실행 결과.
`exit_code`	number	—	프로세스 종료 코드(0 = 성공).
`duration_ms`	number	—	실행 소요 시간(밀리초).
`stdout`	string	—	캡처된 표준 출력.
`stderr`	string	—	캡처된 표준 오류.
`tools`	string[]	—	사용된 도구 이름.
`topics`	string[]	—	분류 토픽.
`space_hint`	string	—	정리를 위한 스페이스 경로 힌트.

kumiho_memory_consolidate

대화 세션을 장기 메모리로 통합합니다. 사이드카가 LLM으로 대화를 요약하고, PII를 삭제하며, 로컬 아티팩트를 기록하고, 요약을 그래프에 저장한 다음, 세션의 워킹 메모리를 초기화합니다. 약 20회의 교환 후 또는 세션 종료 시 트리거하십시오. Revka 데몬도 세션 종료 시 자동으로 실행하지만, 장시간 실행 에이전트는 주기적으로 직접 트리거해야 합니다.

파라미터

파라미터	타입	설명
`session_id`	string	통합할 세션.

{
  "tool": "kumiho_memory_consolidate",
  "args": { "session_id": "sess-2026-06-18-001" }
}

kumiho_memory_discover_edges

새로 저장된 메모리에서 관련 기존 메모리로의 엣지를 탐색하고 생성합니다. 서버는 메모리가 관련성이 있을 미래 시나리오인 “함의 쿼리”를 생성하고 매칭되는 메모리에 연결합니다. consolidate 또는 store 이후에 실행하는 것이 가장 좋습니다.

파라미터

파라미터	타입	기본값	설명
`revision_kref`	string	— (필수)	엣지를 탐색할 리비전의 kref.
`summary`	string	— (필수)	함의 쿼리 생성에 사용할 요약 텍스트.
`edge_type`	string	`"REFERENCED"`	생성할 엣지 타입.
`max_edges`	number	`3`	생성할 최대 엣지 수.
`max_queries`	number	`5`	생성할 최대 함의 쿼리 수.
`min_score`	number	`0.3`	엣지 후보의 최소 유사도 점수.
`space_paths`	string[]	—	검색을 제한합니다. 생략 시 `revision_kref`에서 자동 도출됩니다.

kumiho_memory_dream_state

Dream State 통합 사이클을 실행합니다. 이것은 Kumiho의 백그라운드 “수면” 유지보수 패스입니다. 새 이벤트를 재생하고, LLM으로 메모리를 평가하며, 전체 프로젝트에 걸쳐 더 이상 사용되지 않는 메모리 표시, 태깅, 메타데이터 보강, 관계 연결을 적용합니다. skill 타입 캡처가 정제되고 오래된 메모리가 시간이 지나며 폐기되는 방식입니다. dry_run: true로 쓰기 없이 미리 보기를 실행할 수 있습니다.

파라미터

파라미터	타입	기본값	설명
`project`	string	`"CognitiveMemory"`	처리할 Kumiho 프로젝트.
`dry_run`	boolean	`false`	변경 사항을 적용하지 않고 미리 봅니다.
`batch_size`	number	`20`	LLM 평가 배치당 메모리 수.
`max_deprecation_ratio`	number (0.1–0.9)	`0.5`	실행당 폐기할 최대 메모리 비율.
`allow_published_deprecation`	boolean	`false`	게시된 아이템 폐기를 허용합니다(주의하여 사용).
`provider`	`openai` \| `anthropic` \| `gemini`	env	LLM 공급자. `KUMIHO_LLM_PROVIDER`로 폴백.
`model`	string	env	평가 모델. `KUMIHO_LLM_MODEL`로 폴백.
`base_url`	string	env	OpenAI 호환 기본 URL. `KUMIHO_LLM_BASE_URL`로 폴백.
`api_key`	string	env	LLM API 키. `KUMIHO_LLM_API_KEY`로 폴백.

유지보수 및 조회 도구

핵심 메모리 도구 외에도 사이드카는 메모리를 확인, 검사, 폐기하는 데 필요한 그래프 기본 도구를 노출합니다. 이 도구들은 오래된 조회를 처리할 때 가장 유용합니다(아래 주의 사항 참고).

도구	목적
`kumiho_resolve_kref`	kref URI를 아티팩트 또는 리비전의 기본 아티팩트의 구체적인 파일 위치로 변환합니다.
`kumiho_get_edges`	`direction`(`outgoing` / `incoming` / `both`) 및 `edge_type`으로 필터링 가능한 리비전의 엣지를 가져옵니다.
`kumiho_get_revision_by_tag`	태그(기본값 `"published"`)로 리비전을 가져옵니다.
`kumiho_deprecate_item`	아이템의 폐기 상태를 설정합니다. 폐기된 아이템은 검색에서 숨겨집니다. `deprecated: false`로 복원할 수 있습니다.

전체 아이템 / 리비전 / 엣지 / 번들 / 아티팩트 CRUD 인터페이스 및 kref 형식(kref://space/item?r=N)은 그래프 모델: 스페이스, 아이템 & 출처와 메모리 그래프 & 에셋 브라우저 API를 참고하십시오.

Kumiho 메모리 도구

두 가지 반사 패턴

오퍼레이터 측 메모리 도구

kumiho_memory_engage

kumiho_memory_reflect

kumiho_memory_recall

kumiho_memory_retrieve

kumiho_fulltext_search

kumiho_memory_store

kumiho_memory_ingest

kumiho_memory_add_response

kumiho_memory_store_execution

kumiho_memory_consolidate

kumiho_memory_discover_edges

kumiho_memory_dream_state

유지보수 및 조회 도구

관련 페이지

시작하기

핵심 개념

가이드

CLI 참조

게이트웨이 API

대시보드

채널

프로바이더 및 모델

도구

메모리

워크플로우 및 SOP

크론 및 스케줄링

보안 및 감사

배포 및 운영

하드웨어

MCP 및 확장성

에코시스템

참조