🐸 kaeru
kaeru는 LLM 에이전트를 위한 크로스-에이전트 인지 엔진입니다. 이는 에이전트가 사고하는 타입 그래프(typed graph)와 장기적인 아이디어 및 결과물을 저장하는 회상 계층(recollection layer)으로 구성되어 있습니다. 각 에이전트별로 로컬 우선(Local-first) 방식을 채택하며, 선택적으로 공유 클라우드 티어(shared cloud tier)를 제공하여 팀 전체의 에이전트와 사람들이 서로의 기억을 바탕으로 구축할 수 있도록 합니다.
다중 세션, 다중 에이전트 연속성에 초점을 맞춰 설계되었습니다. 즉, 에이전트가 프로젝트를 열 때, 이전에 무엇에 대해 생각했는지에 대한 전체 컨텍스트(full context)를 가지고 있으며, 출처 추적 사슬(provenance chains)을 따라갈 수 있고, 결과물을 안정적인 장기 지식으로 통합할 수 있으며, 팀의 나머지 구성원이 공유한 내용을 가져올 수도 있습니다.
LLM-wiki 패턴(Karpathy, gist 442a6bf555914893e9891c11519de94f)에서 영감을 받았으며, Graphiti / Zep의 양방향 시간 지식 그래프 접근 방식(bi-temporal knowledge graph approach), Cognee의 큐레이터 주도형 지식 엔진(curator-driven knowledge engine), 그리고 PageIndex의 추론 기반 계층적 요약 탐색 패턴(reasoning-based hierarchical-summary navigation pattern)에서 영감을 받았습니다. 이는 해마/피질 분할에 근거한 2계층 설계입니다.
이름: 蛙 (kaeru,
접합 관계 패턴을 통한 개별 이니셔티브 서브그래프: 하나의 기질, 다수의 이니셔티브, 다중 멤버십. 프로젝트 A에서 작업하는 에이전트가 "지난번에 여기서 뭘 하고 있었지?"라고 질문하면 A에 국한된 답변을 받습니다. 동일한 노드는 한 번에 여러 이니셔티브에 속할 수 있습니다.
kaeru는 **강제자가 아니라 촉진자(facilitator)**입니다. 메모리 API는 35개의 명명된 작업(context, search, read, claim, synthesise, history, lifecycle, …)을 사용 가능한 도구로 노출합니다. 에이전트와 사용자가 언제 이를 호출할지 선택하며, 데몬은 힌트를 주지만 차단하지는 않습니다.
메모리 작업(Memory operations)
에이전트 API에는 35개의 명명된 도구가 있습니다: 16개의 빈번한 작업, 10개의 로컬 유지보수 작업, 그리고 9개의 선택적 클라우드 작업. API 참조에서 카탈로그, 공유 JSON 결과 및 페이지 매김에 대해 설명합니다. 쿼리 DSL은 없습니다.
MCP, HTTP 및 임베디드 Rig는 스키마와 로컬 명령어 구현을 공유합니다.
레코드는 운영(operational) 또는 아카이브(archival) 계층에 존재하며 다섯 개의 독립적인 검색 레이어에 있습니다. 명시적 타입 에지(typed edges)는 출처(provenance), 의심, 종속성 및 계승성을 보존합니다; 작성된 흔적(authored trails)은 결론에 도달한 이유를 유지합니다. context는 규칙, 현재 레코드 및 미완료 작업을 복원합니다. 일반적인 읽기 작업(reads)은 최신 상태(currentness), 충돌 및 저장된 추론을 담고 있습니다. reference는 제공된 원본 텍스트를 정확하게 보존하며, verdict는 증거와 상태를 원자적으로 기록할 수 있습니다.
임베디드 Cozo/RocksDB 기질은 기록된 단언(assertions)과 철회(retractions)를 보존합니다. history와 read(recorded_at=...)는 이전 콘텐츠를 검사합니다. 현재 메타데이터는 '현재'로 레이블링되며, 사실이 세상에서 참이었던 시점에 대한 별도의 축이 아니라 하나의 기록된 시간 축이 있습니다. 본질적인 변형(Intrinsic mutations), 감사 및 재생 레코드는 함께 커밋됩니다. 기존 볼트들은 히스토리를 제거하지 않고 열린 상태로 마이그레이션되며; 오래된 비범위화된 레코드(unscoped records)는 legacy-unscoped 아래에서 복구됩니다.
업데이트 확인(Update checks)
일일 업데이트 확인은 updates.lamantin-ai.com에 공개 GitHub 릴리스 목록을 요청하며, 해당 엔드포인트가 사용 불가능할 경우 GitHub로 폴백합니다. 사용자 에이전트(User-Agent)에는 kaeru 버전, OS/아키텍처, 설치 채널 및 환경 정보가 포함됩니다. 이 엔드포인트는 솔티드 IP/사용자 에이전트 지문(salted IP/User-Agent fingerprints)을 사용하여 일일 집계 카운트를 유지하며, 다음 스윕 시 일일 솔트와 해시를 삭제합니다. 볼트 내용은 전송되지 않습니다. 확인 기능을 비활성화하려면 KAERU_MCP_UPDATE_CHECK=0을 설정하십시오. 저장 및 카운팅 세부 정보는 업데이트 워커(update Worker)를 참조하십시오.
레이아웃 (Layout)
kaeru/
├── Cargo.toml ← 작업 공간 루트 (workspace root)
├── kaeru-core/ ← 라이브러리: substrate, schema, primitives
...
kaeru-rig은 rig 프레임워크 어댑터입니다. 이는 전체 큐레이터 명령어 세트(curator verb set)를 임베디드 Arc<Store>에 대한 이산적인 rig Tool로 구현하여, rig 에이전트가 하나의 볼트를 읽고 쓸 수 있게 합니다. 향후에는 kaeru-langchain(Python 브릿지)이 추가될 예정이며, 아직 시작되지 않았습니다.
설치 (Install)
1.0 알파 이전 버전. Substrate 스키마는 마이너 버전 간에 변경될 수 있으므로, 메모를 보관해야 하는 경우 마크다운으로 내보내십시오.
소스 빌드, MCP 데몬 설정 및 재진입 의식(re-entry ritual)은 QUICK_START.md를 참조하십시오.
빠른 둘러보기 (Quick tour) (MCP 도구)
context(initiative="auth-rewrite")
note(initiative="auth-rewrite", body="토큰 만료는 플랫폼마다 다름")
search(initiatives=["auth-rewrite"], text="expiry", prefix=true)
...
continuation.next_arguments를 따르고, 제한된 읽기 작업(bounded reads)에서 coverage를 검사하십시오. partial 뮤테이션은 커밋된 로컬 레코드를 포함할 수 있으며, 그 ID와 실패한 단계를 검사하십시오. 호스트는 불확실한 결과를 복구하기 위해 request_id를 제공할 수 있습니다.
네트워크 접근 없이 빌드 (Building without network access)
일부 기계에서는 crates.io에 도달할 수 없습니다. 각 릴리스의 종속성(dependencies)은 별도의 저장소인 LamantinAI/kaeru-vendor에 번들링되어 있으며, 릴리스별로 하나의 태그가 있습니다:
Rust만으로는 그 라인의 어느 쪽에서도 충분하지 않습니다. cozo는 RocksDB를 C++로, zstd/lz4는 C에서 빌드하기 때문에, 오프라인이든 아니든 C++ 툴체인과 libclang이 필요합니다. 플랫폼별 요구 사항과 모든 체크섬을 한 번에 실패시키는 Windows 줄 바꿈 트랩은 docs/offline-build.md를 참조하세요.
MCP 인식 에이전트 연결하기
kaeru-mcp는 장기 실행 HTTP 서비스입니다: 머신당 하나의 데몬이 기반을 소유하며, 임의의 수의 에이전트 세션(Claude Code, Opencode, Cursor 등)이 동시에 연결합니다. 이는 의도된 바입니다. RocksDB는 단일 작성자(single-writer)이기 때문에, 세션마다 서브프로세스를 포크하는 stdio MCP는 잠금 경합(lock contention)을 일으킬 것입니다. 시스템d/launchd 유닛 템플릿과 전체 HTTP 설정은 kaeru-mcp/README.md를 참조하세요.
데몬을 실행하거나 (contrib/install/에서 systemd 사용자 유닛을 설정):
그런 다음 에이전트를 이 데몬으로 지정하세요:
- Claude Code:
claude mcp add --transport http kaeru http://127.0.0.1:9876/mcp — 포터블 시스템 프롬프트 규칙은 skills/kaeru-skill/에서 확인하세요.
- 질문하기 전 메모리 확인 (Claude Code 및 Codex):
contrib/hooks/kaeru-first/는 에이전트가 사용자에게 무언가를 질문하려는 순간을 위한 하네스 훅입니다. kaeru를 최근에 읽지 않은 경우, 먼저 검색하도록 에이전트를 유도한 후, 사용자의 답변을 기록하도록 요청합니다. 표준 라이브러리 Python 기반이며, 실패 시 열려 있습니다(fails open). 자세한 내용은 README를 참조하세요.
- Opencode:
bash contrib/opencode/install-opencode.sh — 데몬을 연결하고, AGENTS.kaeru.md 규칙을 ~/.config/opencode/에 추가하며, /kaeru, /lesson, /recall 슬래시 명령어를 설치합니다. 기존 OSS 모델 제공업체 설정(Qwen / DeepSeek / GLM / Ollama)과 공존하도록 설계되었습니다. 자세한 내용은 contrib/opencode/README.md를 참조하세요.
- Cursor 및 기타 런타임:
skills/kaeru-skill/SKILL.md의 본문을 에이전트의 규칙/시스템 프롬프트 섹션에 붙여넣으세요. MCP 인식 클라이언트의 경우, 위의 데몬 URL을 직접 사용할 수 있습니다.
에이전트를 재시작하면 context, search, read, note, claim 및 기타 명명된 도구를 볼 수 있습니다. 일반적인 프로젝트 호출에는 initiative가 필요하며, 검색은 initiatives 목록을 사용합니다.
로컬 및 클라우드 — 팀 전반의 메모리 공유
kaeru는 **로컬 우선(local-first)**으로 작동합니다: 볼트가 사용자 장치에 존재하며 기본적으로 외부로 나가지 않습니다. 두 번째 선택적 계층인 kaeru-cloud는 신뢰할 수 있는 그룹(팀, 가족)을 위한 공유 저장소입니다. 각 이니셔티브는 지속적인 share_policy를 가집니다:
private(기본값) — 아무것도 외부로 나가지 않습니다; 개인 프로젝트.team — 명시적으로 shared로 표시된 노드는 클라우드와 동기화될 수 있습니다.
공유는 절대 자동으로 이루어지지 않으며 두 가지 게이트를 통과합니다: 이니셔티브 정책, 그리고 API 키, 토큰 또는 개인 키처럼 보이는 모든 것을 차단하는 결정론적 **사전 공유 비밀 보호 장치(pre-share secret guard)**입니다. 이 보호 장치는 깨끗한 콘텐츠에 대해서는 침묵하며 실제 위협이 감지될 때만 중단시킵니다.
동사(over MCP): policy (팀에 이니셔티브 표시), share (노드 푸시), cloud_recall (팀이 무엇을 가졌는지 보기), pull (공유된 노드를 로컬 그래프로 가져오기), link_cloud / cloud_links (복사 없이 클라우드 노드 참조), 그리고 sync_review (여전히 로컬인 노드 일괄 검토). note와 reference는 하나의 호출로 캡처하고 공유하기 위해 sharing: {visibility: "shared", cloud: "team"}를 사용합니다.
initiative와 id를 사용하는 cloud_recall은 참조 속성을 포함하여 전체 공유 기록을 가져오지만, 이를 임포트하지는 않습니다. 이니셔티브 멤버십은 본문을 반환하기 전에 확인됩니다. pull은 임포트된 노드의 인시던트 엣지(incident edges)만 복원하고 로컬 가중치와 명시적 언링크를 유지합니다. 노드 쓰기 후에 엣지 복원에 실패하면, 오류는 node_imported: true를 보고하며, 재시도 시 임포트를 완료할 수 있습니다. 취소는 협력적이며 커밋된 데이터를 되돌리지 않습니다. 원격 엣지 목록은 여전히 전체가 가져와집니다.
단일 데몬은 또한 clouds.toml 파일을 통해 여러 이름의 클라우드 (예: family와 work 클라우드)에 접근할 수 있으며, 이 경우 클라우드 동사는 선택적 cloud: <이름>을 사용하고 소프트 링크는 어느 클라우드를 가리키는지 기억합니다. 파일 형식은 kaeru-mcp/README.md를 참조하십시오.
사용자별 / 조직별 격리(멀티테넌트)는 향후 추가될 예정이며, 현재 각 클라우드는 이니셔티브에 의해 범위가 지정된 하나의 공유 공간입니다. kaeru-cloud/README.md를 참조하십시오.
로드맵
- 이니셔티브 온보딩(Initiative onboarding) — 에이전트가 프로젝트에 처음 진입할 때,
import 가이드의 정신을 담아 생성되는 "이 이니셔티브는 무엇이며 무엇을 포함하는지"에 대한 브리핑입니다. 이는 그래프 매커니즘(graph machinery)이 아닌 수집된 컨텍스트를 기반으로 하는 명령어 형태입니다.
- PostgreSQL 백엔드 — 임베디드 RocksDB 기본값과 함께 사용되는 서버 모드 기저 시스템입니다.
- 멀티테넌트 + 격리(Multi-tenant + isolation) — 공유 클라우드 내에서 사용자별/조직별 분리를 제공합니다.
- 교차 이니셔티브 링크(Cross-initiative links) — 옵트인 엣지이며, 여러 이니셔티브 사이를 가로질러 이동하는 리콜 기능을 의미합니다. 이니셔티브별 스코핑은 의도된 것이며 결함이 아닙니다. 이미
initiative_manage(action="attach") 명령어가 한 번에 여러 이니셔티브의 노드 멤버십을 제공하므로, 본 기능은 그 위에 경계를 넘나드는 엣지/리콜 기능을 추가하는 것입니다.
인스턴스 시각화기 (Instance visualizer)
MCP 인스턴스에서 /ui/로 접속하여 라이브 시각화기를 사용하십시오. 프론트엔드 에셋은 kaeru-mcp에 임베디되어 있어 Node.js나 그래프 익스포트가 필요 없습니다. 로컬 계정과 JWT 세션으로 선택적으로 보호하려면 kaeru-mcp --auth enabled를 사용하십시오. 에이전트 MCP 토큰은 별개로 유지됩니다. 설정, 접근 및 빌드 지침을 참조하십시오.
로컬 설치는 기본적으로 인증 기능이 비활성화되어 있으며, 활성화할지 여부를 묻습니다. 자동화를 위해 KAERU_SETUP_AUTH=yes/no를 사용하십시오. 보호 기능을 비활성화하면 호스팅 배포에 대한 경고가 표시됩니다. 인증 모드를 참조하십시오.
상태 (Status)
1.0 이전 버전입니다. 이 체크아웃은 축소된 API를 구현하고 오래된 에이전트 도구 이름과 HTTP 별칭을 제거했습니다. Vault 마이그레이션 및 기록된 히스토리는 계속 지원됩니다. 현재 메타데이터와 선택적 클라우드 동작을 포함한 실제적인 제한 사항에 대해서는 아키텍처와 API 레퍼런스를 참조하십시오.
라이선스 (License)
MIT — [LICENSE]를 참조하십시오.
스토어 검증 및 읽기 추적
