KektorDB
AI 에이전트를 위한 인지 기억 계층입니다.
<p align="center">
<img src="https://raw.githubusercontent.com/sanonone/kektordb/HEAD/docs/images/logo.png" alt="KektorDB Logo" width="500">
</p>
GitHub Sponsors
Ko-fi
Go Reference
PyPI version
License
<p align="center">
<a href="DOCUMENTATION.md">문서(Documentation)</a> •
<a href="CONTRIBUTING.md">기여 방법(Contributing)</a> •
<a href="docs/guides/zero_code_rag.md">GraphRAG 가이드</a>
</p>
English | Italiano
KektorDB는 데이터를 저장하는 데이터베이스가 아니라, 자신이 무엇을 저장하는지 이해하는 엔진인 AI 메모리 시스템입니다. 이 시스템은 고성능 벡터 검색(HNSW)과 시간적 지식 그래프를 결합하고 있으며, 사용자의 데이터를 지속적으로 분석하여 모순을 감지하고, 중요도를 추적하며, 관련 없는 정보는 자연스럽게 사라지도록 합니다.
<p align="center">
<img src="https://raw.githubusercontent.com/sanonone/kektordb/HEAD/docs/images/kektordb-demo.gif" alt="KektorDB Demo" width="800">
</p>
30초 만에 - AI 에이전트에 영구 메모리를 부여하세요:
kektordb setup opencode
...
이제 사용자의 에이전트는 save_memory, recall_memory, start_session 및 기타 46개의 도구를 호출할 수 있습니다. 메모리는 세션 전반에 걸쳐 지속되며, 사용되지 않으면 자연스럽게 소멸하고, 인지 엔진은 모순을 감지하고 사용자 프로필을 자율적으로 구축합니다.
49개의 에이전트 도구는 다음을 포괄합니다: 메모리 CRUD (save_memory, recall_memory, adaptive_retrieve), 그래프 연산 (connect_entities, find_path, explore_connections), 세션 관리 (start_session, end_session), 인지 기능 (check_subconscious, get_user_profile, ask_meta_question), 지식 컴파일 (아티팩트 캐싱을 포함한 request_knowledge) 외에도 인덱싱, 설정(config), KV 스토어 도구가 포함됩니다. 전체 57개 도구를 사용하려면 --tools=all을 실행하세요.
KektorDB가 하는 일
인지 및 메모리 엔진 (Cognitive & Memory Engine)
Gardener - 자체 관리 메모리(Self-Managing Memory). 지식 그래프를 지속적으로 분석하는 백그라운드 프로세스입니다 (기본, 고급, 메타의 3가지 모드). 중복된 메모리를 통합하고, 새로운 사실이 기존 사실과 모순되는지 감지하며, 지식 격차를 식별하고, 11개의 전문화된 탐지기를 통해 통찰력을 표면으로 끌어냅니다. --cognitive-config cognitive.yaml로 활성화할 수 있습니다.
Epistemic Engine - 자신이 아는 것을 알기(Know What You Know). 세 가지 기둥으로 이루어진 수학적 프레임워크 (합의 40%, 안정성 30%, 마찰 30%)가 모든 메모리에 신뢰도 점수를 할당합니다. 어떤 사실이 결정화되었는지(crystallized), 안정적인지(stable), 휘발성이 있는지(volatile), 또는 *논란의 여지가 있는지(contested)*를 식별할 수 있습니다. POST /vector/actions/belief-assessment를 통해 쿼리합니다.
모순 감지 (Contradiction Detection) - 충돌 조기 감지. Gardener는 LLM 기반 분석을 사용하여 새로운 정보가 확립된 사실과 충돌하는 경우를 탐지합니다. 고급 모드에서는 해결책을 제안하고 사소한 모순은 자동 해결할 수 있습니다. 에이전트는 check_subconscious를 통해 보류 중인 모순을 확인합니다.
Semantic Git - 덮어쓰지 말고 진화시키기(Evolve, Don't Overwrite). 메모리에 대한 버전 관리 시스템입니다. 정보가 변경되면, VEvolve는 이전 버전에 연결된 새로운 버전을 생성하며, 이는 superseded_by/evolves_from 간선으로 연결됩니다. _is_historical 마커를 통해 전체 기록이 보존됩니다. 특정 시점의 지식 상태를 쿼리할 수 있습니다.
사용자 프로파일링(User Profiling) - 사용자를 파악하세요(Know Your Users). KektorDB는 사용자 프로필을 자율적으로 구축하고 유지합니다. 여기에는 커뮤니케이션 스타일, 언어 선호도, 전문 분야, 싫어하는 것, 진술된 행동 대 관찰된 행동 등이 포함됩니다. 프로필은 설정 가능한 상호작용 임계치(configurable threshold) 이후에 업데이트됩니다. get_user_profile을 통해 쿼리할 수 있습니다.
지식 엔진(Knowledge Engine) - 사전 컴파일된 아티팩트(Pre-Compiled Artifacts). 내장 템플릿(entity_card, topic_overview, user_profile, timeline, session_summary)을 사용하여 그래프 쿼리로부터 구조화된 지식 아티팩트를 컴파일합니다. 필드는 결정론적으로 또는 LLM(대규모 언어 모델)을 통해 계산됩니다. 이 아티팩트들은 캐시되며(<50ms 히트, 토큰 소비 없음) 소스 데이터가 변경될 때 통합된 Artifact Watcher를 통해 자동으로 재컴파일됩니다. MCP에서 request_knowledge를 호출하거나 REST에서 POST /compile을 통해 컴파일을 트리거할 수 있습니다.
시간 인식 메모리(Time-Aware Memory) - 감쇠 및 강화(Decay & Reinforcement). 단기 기억과 장기 기억을 통합합니다. 노드는 접근되지 않으면 시간이 지남에 따라 관련성이 떨어지며, 검색 시 강화됩니다. 핵심 사실은 소실되는 것을 방지하기 위해 고정(Pin)할 수 있습니다. 에피소드적(episodic), 의미론적(semantic), 절차적(procedural) 메모리 레이어별로 지수형(exponential), 선형(linear), 단계형(step), 또는 Ebbinghaus 모델을 사용하여 감쇠율을 설정할 수 있습니다.
그래프 및 검색 (Graph & Search)
지식 그래프(Knowledge Graph) - 관계를 일급 시민으로(Relationships as First-Class Citizens). 양방향 탐색, 시간 여행(임의 시점의 쿼리 상태), N-홉 순회(N-hop traversal), 양방향 BFS 경로 찾기 기능을 갖춘 가중치 속성 그래프입니다. 자동 연결 규칙은 메타데이터 필드(parent_id → child_of)로부터 연결을 생성합니다. 그래프 엔티티는 벡터 없이도 존재할 수 있으며, 사용자, 세션 또는 추상적 개념을 나타낼 수 있습니다.
하이브리드 검색(Hybrid Search) - 벡터 + 키워드 + 그래프. HNSW 벡터 유사성 검색과 BM25 키워드 매칭, 그리고 roaring bitmaps를 이용한 메타데이터 필터링을 결합합니다. 그래프 인식 검색은 결과를 루트 노드에서 도달 가능한 서브그래프(subgraphs)로 제한합니다. 적응형 검색(Adaptive retrieval)은 토큰 예산 내에서 의미론적 이웃(semantic neighbors)을 따라 컨텍스트를 확장합니다.
엔지니어링 (Engineering)
신뢰할 수 있는 영속성(Persistence) 구현. 하이브리드 AOF + 스냅샷 아키텍처를 사용합니다. lazy AOF 라이터가 주기적인 fsync와 함께 작업을 배치 처리하여 (처리량 10~100배 향상) 효율성을 높입니다. CRC32 무결성 검사를 사용하는 이진 TLVC 프레이밍을 채택했습니다. 자동 손상 복구(crash recovery) 시 동기화(resync) 기능을 제공하여, AOF 파일이 부분적으로 손상되어도 유효한 데이터가 보존됩니다. 스냅샷 모드를 사용한 AOF 재작성을 통한 백그라운드 압축(compaction)은 유지보수 중 데이터 손실을 방지합니다.
JWT 인증. 역할 기반 접근 제어(role-based access control) (관리자(admin), 쓰기(write), 읽기(read)) 및 선택적 네임스페이스 격리 기능을 갖춘 자체 포함형 ES256 (ECDSA P-256) 토큰을 사용합니다. 제3자 검증을 위한 JWKS 엔드포인트가 제공됩니다. 토큰 무효화(revocation)를 위해 jti 블랙리스트를 지원합니다. 서버 측에 토큰을 저장하지 않으며, 토큰 자체가 클레임(claims)을 가집니다.
자체 최적화 그래프. 백그라운드 유지보수는 인덱스를 건강하게 유지합니다: Vacuum은 삭제된 노드의 메모리를 회수하고 그래프 연결을 복구합니다. Refine은 시간이 지남에 따라 검색 재현율(search recall)을 개선하기 위해 그래프 연결을 지속적으로 재평가합니다. — KektorDB를 오래 실행할수록 검색 결과가 더 좋아집니다. 이 두 기능 모두 인덱스별로 구성 가능하며 자율적으로 실행됩니다.
원하는 방식으로 사용하기. 독립형 REST 서버, 임베디드 Go 라이브러리(네트워크 오버헤드 없음), AI 에이전트를 위한 MCP 서버, 제로 코드 RAG를 위한 AI 게이트웨이/프록시 또는 이들의 모든 조합으로 사용할 수 있습니다. Python, TypeScript, Go 클라이언트 SDK가 제공됩니다. 제로 설정 로컬 임베딩을 위해 내장 ONNX 임베더(all-MiniLM-L6-v2, 384 차원)를 갖추고 있습니다. 외부 CLI 도구는 SmartLoader를 통해 복잡한 문서를 구문 분석할 수 있습니다. — vectorizers.yaml에 명령어 템플릿을 구성하면, 실패 시 KektorDB가 내장 파서로 폴백(fallback)합니다.
KektorDB 사용 방법
| 모드 | 명령어 | 최적 용도 |
|---|
| MCP 서버 | kektordb --mcp --tools=agent | AI 에이전트 메모리 (Claude, Cursor, Codex, Gemini CLI, OpenCode) |
| ... | | |
빠른 시작
5초 만에 사용해 보기 (설정 불필요)
http://127.0.0.1:9091에서 시드된 샘플 메모리, 하나의 엔티티(entity), 그리고 그래프 링크를 포함하는 임시 데모 서버를 시작합니다. 모든 데이터는 임시 디렉터리에 저장되며 종료 시 폐기됩니다. 벡터 검색은 별도의 설정 없이 작동하며, 텍스트 검색(query_text) 또한 임베더가 사용 가능할 때 (Ollama 또는 내장 ONNX 런타임) 작동합니다:
curl -X POST http://127.0.0.1:9091/vector/actions/search-with-scores \
-d '{"index_name":"mcp_memory","k":5,"query_text":"how does the gardener work?"}'
Python (REST API)
from kektordb_client import KektorDBClient
from kektordb_client.cognitive import CognitiveSession
...
Go (Embedded)
package main
import (
...
다운로드 및 실행
wget https://github.com/sanonone/kektordb/releases/latest/download/kektordb-linux-amd64
chmod +x kektordb-linux-amd64
...
벤치마크 (Benchmarks)
데스크톱 하드웨어(Intel i5-12500, 소비자용 SSD)를 기준으로 Qdrant 및 ChromaDB와 Docker 호스트 네트워킹을 통해 비교했습니다.
| 데이터베이스 | NLP QPS | Vision QPS | Recall@10 |
|---|
| KektorDB | 1073 | 881 | 0.97 |
| ... | | | |
KektorDB는 임베디드(embedded), 단일 노드 시나리오에 최적화되어 있습니다. 수십억 규모의 분산 배포를 고려한다면 전문 솔루션을 검토하십시오. 전체 보고서 →
내장 임베딩 (Built-in Embedding) (선택 사항)
KektorDB는 Rust/Candle 기반의 선택적 내장 ONNX 임베더(all-MiniLM-L6-v2, 384 차원)를 포함하고 있어, 별도의 설정 없이 로컬 임베딩을 수행할 수 있으며 Ollama가 필요하지 않습니다.
Rust 지원으로 빌드하기:
make build-rust-native
make run-rust
ONNX 모델(~90 MB)은 첫 실행 시 HuggingFace에서 SHA256 검증과 함께 자동으로 다운로드됩니다.
| 모드 | 설명 |
|---|
auto | 자동 감지: 사용 가능한 로컬 ONNX를 우선 사용하고, Ollama를 대체(fallback)로 사용합니다 (기본값) |
| ... | |
에코시스템
| 리소스 | 설명 |
|---|
| 문서화 | 전체 기술 참고 자료: 아키텍처, API, 구성 |
| ... | |
로드맵 (Roadmap)
v0.6.1 (현재 버전)
- 엔진 안정성: 6개의 P1+P2 버그 수정 - 메모리-before-AOF 재정렬, nil-pointer Stat(), AOF 손상 복구, 종료 시 무음 데이터 손실, taskIDCounter 경쟁 조건(race), 비동기 작업 누수(async task leak)
- MCP: 57개 도구 (에이전트 49개 + 관리자 8개),
memory_instructions 프롬프트, Gemini API 지원
- 인증(Auth): JWT ES256 토큰, RBAC(역할 기반 접근 제어), JWKS 엔드포인트,
jti 블랙리스트
- 복구: 손상 후 AOF 재동기화, 스냅샷 모드를 사용한 RewriteAOF
향후 계획 (On the Horizon)
- 대화형 설정 마법사 (
kektordb init) — 30초 만에 모든 구성 가능
- Docker Compose 스택
- Git 동기화 (장치 간 메모리 푸시/풀)
- 더 많은 거리 측정 지표를 위한 SIMD/AVX 최적화
- 네이티브 백업/복원 API
로드맵에 영향을 미치려면 이슈(Issue) 열기하세요.
기여 (Contributing)
경쟁 조건(race conditions), 놓친 최적화, 또는 관용적이지 않은 Go 패턴을 발견했다면, 이슈(Issue)나 PR을 열어주세요 — 모든 기여를 환영합니다.
빌드 지침 및 코드 규칙은 CONTRIBUTING.md를 참조하세요.
현재 제한 사항 (Current Limitations)
단일 노드(Single-node): KektorDB는 클러스터링을 지원하지 않습니다. 단일 머신의 한계 내에서 수직적으로 확장됩니다.
라이선스 (License)
Apache 2.0 - LICENSE 참조.
지원 (Support)
<a href="https://ko-fi.com/sanon">
<img src="https://ko-fi.com/img/githubbutton_sm.svg" alt="ko-fi" width="180">
</a>
