응답 캐시, 하드웨어 RAG, 격리

Kumiho 그래프 외에도, Revka는 클라우드 컨트롤 플레인과 무관한 로컬 워크스페이스별 메모리 기능을 몇 가지 제공합니다. 동일한 프롬프트에 대한 중복 과금을 방지하는 옵트인 LLM 응답 캐시, 보드 핀 조회를 위한 하드웨어 데이터시트 RAG 인덱스, 그리고 에이전트나 클라이언트 간의 메모리 혼용을 차단하는 정책/격리 메커니즘입니다. 이 페이지에서는 이 네 가지 기능과 GDPR 데이터 이동성을 위한 Memory::export 경로를 모두 다룹니다.

먼저 메모리 개요에서 [memory] 섹션 전체와 영속 메모리가 Kumiho에 저장되는 이유를 확인하세요. 이 페이지의 내용은 별도로 명시하지 않는 한 ~/.revka/config.toml의 [memory](및 [memory.policy]) 하위에 위치합니다.

참고

응답 캐시, 하드웨어 RAG, 네임스페이스 정책, 내보내기 경로는 모두 로컬 제어 항목입니다. 이 설정들은 어떤 메모리 백엔드를 사용하든 적용되며, Kumiho가 저장하는 내용에는 영향을 주지 않습니다. Kumiho의 수명 주기 관리(폐기, 보강)는 DreamState가 별도로 처리합니다.

LLM 응답 캐시 (ResponseCache)

응답 캐시는 2계층 캐시로, 동일한 LLM 프롬프트와 모델 조합에 대한 중복 과금을 방지합니다. 기본값은 비활성화이므로 직접 옵트인해야 합니다.

• 핫 티어 — 가장 최근에 사용된 항목을 보관하는 인메모리 LRU 캐시입니다.
• 웜 티어 — <workspace_dir>/memory/response_cache.db에 위치한 WAL 모드 SQLite 데이터베이스입니다.

각 항목은 (model || system_prompt || user_prompt)의 SHA-256 해시를 키로 사용합니다. 캐시 미스 시 Revka는 SQLite를 조회하고 히트된 항목을 인메모리 티어로 승격합니다. 히트 시에는 해당 항목의 hit_count를 증가시키고 accessed_at을 갱신합니다.

활성화 및 튜닝

[memory]
response_cache_enabled = true        # default: false (opt-in)
response_cache_ttl_minutes = 60      # entry expiry
response_cache_max_entries = 5000    # SQLite warm-tier cap before LRU eviction
response_cache_hot_entries = 256     # in-memory hot-tier size

키	타입	기본값	의미
response_cache_enabled	bool	false	마스터 스위치. 캐싱을 활성화하려면 true로 설정해야 합니다.
response_cache_ttl_minutes	int	60	항목당 만료 시간(분).
response_cache_max_entries	int	5000	웜 티어(SQLite) 최대 항목 수. 초과 시 LRU 방출이 적용됩니다.
response_cache_hot_entries	int	256	인메모리 핫 티어 크기.

캐시는 내부적으로 전체 항목 수, 총 히트 수, 절감된 토큰 수를 추적하지만, 현재 CLI를 통해 이 수치를 직접 확인할 수는 없습니다.

주의

response_cache_max_entries = 0으로 설정하면 모든 항목이 방출됩니다. 이는 상한선을 제거하는 것이 아니라 사실상 웜 티어를 비활성화하는 효과를 냅니다. 캐시를 완전히 끄려면 response_cache_enabled = false로 설정하세요.

데이터베이스 경로가 <workspace_dir> 하위에 있으므로, 캐시는 워크스페이스 단위로 동작합니다. 워크스페이스 격리가 활성화된 경우 각 클라이언트는 자체 response_cache.db를 갖게 되며, 다른 클라이언트의 캐시된 응답에 접근할 수 없습니다.

하드웨어 RAG (HardwareRag)

HardwareRag는 하드웨어 데이터시트에 대한 로컬 검색 인덱스입니다. 에이전트가 핀 조회나 보드 기능 같은 하드웨어 관련 질문에 답할 때, Revka는 일치하는 데이터시트 내용과 핀 별칭을 검색해 에이전트의 컨텍스트에 삽입합니다. 완전히 로컬에서 동작하므로 데이터시트 텍스트는 외부로 전송되지 않습니다.

구성된 디렉터리에서 .md 및 .txt 파일(그리고 rag-pdf 기능이 있으면 .pdf도)을 로드하여 키워드 겹침 정도로 점수를 매기고, 조회 대상 보드에 태그된 청크에 가중치를 부여합니다.

데이터시트 디렉터리 설정

페리페럴이 워크스페이스 기준의 상대 경로로 데이터시트 디렉터리를 가리키도록 설정합니다.

[[peripherals]]
datasheet_dir = "datasheets"   # relative to the workspace dir

보드당 파일 하나씩 배치합니다. 파일명(확장자 제외)이 보드 태그가 됩니다.

workspace/
  datasheets/
    nucleo-f401re.md    # board tag = "nucleo-f401re"
    rpi-gpio.txt        # board tag = "rpi-gpio"
    generic.md          # no board tag — matches all queries

하나 이상의 보드로 범위를 한정한 쿼리(boards: &[String])에서는 일치하는 청크에 +2.0 점수 가중치가 부여됩니다. generic*으로 명명되거나 _generic/ 하위 디렉터리에 있는 파일은 보드 태그가 없어 모든 쿼리에 매칭되므로, 보드 공통 컨텍스트에 활용하세요.

datasheet_dir이 없거나 디렉터리가 존재하지 않으면 RAG는 오류 없이 빈 결과를 반환합니다.

참고

현재 청킹은 스텁 구현이므로 각 문서가 단일 청크로 처리됩니다. 진정한 서버 측 청킹과 시맨틱 검색이 필요하다면 Kumiho 그래프 메모리를 사용하세요. HardwareRag는 빠른 로컬 보드/핀 조회에 특화되어 있습니다.

핀 별칭 테이블

데이터시트에서 명명된 핀 별칭을 선언하면 에이전트가 red_led를 핀 번호로 직접 해석할 수 있습니다. 핀 별칭 컨텍스트는 청크 검색과 별도로 구성되므로, 일치하는 보드에 대해 별칭은 항상 사용 가능합니다. 두 가지 형식을 지원합니다.

Pin Aliases 제목 하위의 키-값 라인 형식:

## Pin Aliases
red_led: 13
builtin_led: 13

또는 마크다운 테이블 형식:

## Pin Aliases
| alias    | pin |
|----------|-----|
| red_led  | 13  |

rag-pdf 기능

PDF 수집은 pdf_extract 크레이트를 포함하는 rag-pdf Cargo 기능 뒤에 게이팅되어 있습니다.

cargo build --features hardware,rag-pdf

rag-pdf 없이는 .pdf 데이터시트가 인덱싱에서 제외되며, datasheet 도구의 read 액션은 추출된 텍스트 대신 수동 참조용 파일 경로를 반환합니다. 관련 설정 플래그인 [hardware].workspace_datasheets = true는 이 RAG 기반 핀 조회를 위해 워크스페이스의 PDF를 인덱싱합니다.

소형 모델을 위한 compact_context

소형 로컬 모델을 사용할 경우 [agent]에 compact_context를 설정하세요. 다양한 컨텍스트 축소 효과 중에서도 특히 RAG 청크 한도를 2개로 제한하여 데이터시트 검색이 좁은 컨텍스트 윈도우를 잠식하지 않도록 합니다.

[agent]
compact_context = true   # recommended for models ≤13B

소형 모델 전반의 튜닝 방법은 커스텀 프로바이더 & 로컬 LLM을, 이 인덱스에 데이터를 공급하는 데이터시트 다운로드 워크플로우는 Aardvark I2C/SPI/GPIO & 데이터시트를 참고하세요.

네임스페이스 격리

모든 메모리 항목은 에이전트와 컨텍스트 간의 격리를 위한 namespace 필드를 갖습니다. 네임스페이스를 지정하지 않은 항목은 default_namespace로 분류됩니다. 메모리 정책을 통해 네임스페이스 또는 카테고리별 최대 항목 수를 제한하거나, 네임스페이스를 읽기 전용으로 지정하거나, 카테고리별 보존 기간을 재정의할 수 있습니다.

[memory]
default_namespace = "default"

[memory.policy]
max_entries_per_namespace = 1000
max_entries_per_category = 0                 # 0 = unlimited
read_only_namespaces = ["system_facts"]
retention_days_by_category = { core = 365, daily = 30, conversation = 7 }

키	타입	기본값	의미
default_namespace	string	"default"	네임스페이스를 지정하지 않은 항목에 할당되는 네임스페이스.
max_entries_per_namespace	int	0	네임스페이스당 최대 항목 수. 0 = 무제한.
max_entries_per_category	int	0	카테고리당 최대 항목 수. 0 = 무제한.
read_only_namespaces	array	[]	해당 네임스페이스에 대한 쓰기가 거부됩니다.
retention_days_by_category	table	미설정	카테고리별 보존 기간 재정의 (카테고리 이름을 키로 사용).

참고

네임스페이스 격리는 단일 메모리 데이터베이스 내에서 동작하며, 네임스페이스별 검색 시 클라이언트 측에서 적용됩니다. 테넌트 간 더 강력한 경계가 필요하다면 워크스페이스 격리를 사용하세요. 각 워크스페이스에 별도의 데이터베이스 파일이 할당됩니다.

멀티-클라이언트 워크스페이스 메모리 격리

하나의 Revka 인스턴스를 여러 클라이언트에 사용하는 경우, 워크스페이스 격리는 각 클라이언트 인게이지먼트에 <workspaces_dir>/<client>/memory/ 하위의 별도 메모리 데이터베이스를 제공합니다. 특정 워크스페이스로 범위가 한정된 요청은 다른 워크스페이스의 항목에 접근할 수 없습니다. 이것이 네임스페이스만으로는 제공할 수 없는 강력한 경계입니다.

[workspace]
enabled = true
isolate_memory = true          # default: true when workspaces are enabled
cross_workspace_search = false # security default — no cross-tenant reads

키	타입	기본값	의미
isolate_memory	bool	true	워크스페이스별 별도 메모리 데이터베이스 사용.
cross_workspace_search	bool	false	워크스페이스 간 읽기 허용. 클라이언트 간 메모리 혼용을 방지하려면 false로 유지하세요.

격리는 데이터베이스 파일 수준에서 동작하므로, 응답 캐시도 분리됩니다. 각 워크스페이스는 자체 memory/response_cache.db를 갖게 됩니다. 전체 [workspace] 스키마 및 프로필별 설정은 Config: 게이트웨이, 메모리, 보안 & 플랫폼을 참고하세요.

주의

cross_workspace_search = false는 의도적인 보안 기본값입니다. 이를 활성화하면 메모리 검색이 클라이언트 워크스페이스 전체에 걸쳐 수행됩니다. 모든 워크스페이스가 실제로 동일한 신뢰 경계를 공유하는 경우에만 활성화하세요.

GDPR 데이터 이동성 내보내기

Memory 트레이트의 export 메서드는 GDPR 제20조 데이터 이동성을 위한 메모리 항목의 대량 필터링 내보내기를 지원합니다. 임베딩을 제외하고 생성 시간순(오름차순)으로 정렬된 항목을 반환하며, 네임스페이스, 세션, 카테고리, 시간 범위로 필터링할 수 있습니다.

필터 형태 (ExportFilter):

필드	타입	의미
namespace	Option<String>	특정 네임스페이스로 제한.
session_id	Option<String>	특정 세션으로 제한.
category	Option<MemoryCategory>	core, daily, conversation 또는 사용자 정의 레이블로 제한.
since	Option<String>	RFC 3339 하한값(timestamp 포함).
until	Option<String>	RFC 3339 상한값(timestamp 포함).

let filter = ExportFilter {
    namespace: Some("default".to_string()),
    session_id: None,
    category: Some(MemoryCategory::Core),
    since: Some("2026-01-01T00:00:00Z".to_string()),
    until: Some("2026-12-31T23:59:59Z".to_string()),
};
let entries = memory.export(&filter).await?;

기본 트레이트 구현은 list()와 클라이언트 측 필터링으로 위임하며, 네이티브 쿼리를 지원하는 백엔드는 효율을 위해 이를 재정의합니다.

참고

export는 현재 Rust 트레이트 확장 포인트로만 존재하며 CLI나 HTTP 인터페이스는 없습니다. 향후 revka memory export 명령이 진입점으로 계획되어 있습니다. 현재 Kumiho에 저장된 메모리를 추출하려면 revka memory CLI (list, get, stats)와 메모리 그래프 API를 사용하세요.

관련 페이지

• 메모리 개요 — 전체 [memory] 섹션, NoneMemory 바인딩, 카테고리, 감쇠.
• Kumiho 설정 — 사이드카 설치 및 클라우드 vs 커뮤니티 에디션 선택.
• 그래프 모델: 스페이스, 아이템 & 출처 — 영속 메모리를 지원하는 Kumiho 데이터 모델.
• Aardvark I2C/SPI/GPIO & 데이터시트 — 하드웨어 RAG 인덱스에 데이터를 공급하는 datasheet 도구.
• Config: 게이트웨이, 메모리, 보안 & 플랫폼 — 전체 [memory], [memory.policy], [workspace] 스키마.
• revka memory & estop — CLI에서 메모리 검사 및 관리.