@dikolab/kbdb

파일 기반 지식 베이스로, 순위가 매겨진 키워드 및 시맨틱(하이브리드) 검색을 제공합니다. 문서를 학습한 후 관련 지식을 회상하세요. 외부 서버가 필요 없습니다. CLI 및 MCP 서버로 실행됩니다.

📖 문서 · MCP 설정 · CLI 참조

GitLab | NPM | JSR | 라이선스: AGPL-3.0

Node.js 20+ 또는 Deno 2.6+ 에서 실행됩니다. 데이터베이스 서버도, 클라우드 계정도 필요 없습니다. 디스크의 파일만 있으면 됩니다.

kbdb란 무엇인가요?

kbdb는 AI 에이전트에게 지속적이고 검색 가능한 두 번째 뇌를 제공합니다. Markdown 문서를 가리키면 문서를 파일 기반 지식 베이스로 인덱싱합니다. 그런 다음 에이전트(및 사용자)는 정확한 키 조회가 아닌 순위가 매겨진 키워드 및 시맨틱 검색으로 가장 관련성 높은 지식을 회상합니다. 이는 살아있는 저장소입니다. 에이전트는 새로운 사실을 학습하고, 업데이트하며, 세션 간에 회상합니다.

설치할 외부 서버도, 클라우드 계정도 없습니다. 디스크의 파일만 있으면 됩니다. Node.js 또는 Deno가 실행되는 어디서나 실행되며, MCP 서버로 작동하므로 Claude와 같은 에이전트가 메모리 도구로 연결할 수 있습니다.

검색 작동 방식: kbdb는 기본적으로 키워드 검색을 사용합니다. 동의어가 확장되고, 용어는 관련성에 따라 순위가 매겨지며, 제목은 점수에서 2배의 가중치를 갖습니다. 정확한 쿼리가 아무것도 찾지 못하면 kbdb는 자동으로 일치 조건을 완화하여 최상의 결과를 얻을 수 있게 합니다.

더 스마트한 결과를 원하시나요? --algo hybrid를 사용하여 키워드 일치와 유사도 검색을 결합하세요. 다른 단어가 같은 개념을 설명하더라도 결과를 찾을 수 있습니다. 기본 TF-IDF 임베딩 제공자는 설정 없이 오프라인으로 작동합니다. 더 풍부한 임베딩이 필요할 때 worker.toml에서 타사 제공자(로컬 ONNX 모델 또는 원격 API)로 교체할 수 있습니다.

지식은 최신 상태로 유지됩니다: 파일을 다시 학습하면 kbdb가 이전 버전을 자동으로 대체합니다. 유사 중복 감지는 이미 보유한 내용을 학습할 때 경고합니다. 임베딩 유사도를 기반으로 하므로, 동일한 바이트뿐만 아니라 다르게 표현된 동일한 사실도 감지합니다. kbdb contradictions는 같은 내용을 다루는 섹션을 보고하여 함께 읽을 수 있게 합니다. 무결성 검사는 체크섬, 고아 및 참조를 확인합니다. 신뢰도 점수는 에이전트가 강한 일치와 약한 일치를 구분하는 데 도움을 줍니다.

Related MCP server: Librarian

시작하기

필요한 것

다음 중 하나(이미 가지고 있는 것 선택):

• Node.js 버전 20 이상 -- 다운로드

• Deno 버전 2.6 이상 -- 다운로드 (2.6이 최소 버전입니다. 스토리지 엔진이 소스 단계 임포트를 통해 WebAssembly를 로드하므로, 한 번의 deno install 후 오프라인으로 실행할 수 있습니다. 이전 버전의 Deno는 존재하는 .wasm 파일을 가리키는 오해를 불러일으키는 Module not found 오류로 실패합니다.)

그게 전부입니다. 데이터베이스 서버도, 추가 도구도 필요 없습니다.

설치

Node.js 사용 시:

CLI 빌드는 NPM에서 호스팅됩니다.

npm install -g @dikolab/kbdb

Deno 사용 시:

CLI 빌드는 JSR에서 호스팅됩니다.

deno install -Agf jsr:@dikolab/kbdb/cli

사전 요구 사항 및 확인 단계는 CLI 설치 가이드를 참조하세요.

사용해 보기

1. 지식 베이스 만들기

kbdb db init --db ./my-kb

이렇게 하면 모든 데이터를 보관하는 .kbdb 폴더가 생성됩니다.

2. 문서 공급

kbdb learn ./docs

Markdown 파일 폴더를 가리키세요. kbdb는 파일을 읽고, 섹션으로 나누고, 검색 인덱스를 구축합니다. --tags design,v2를 추가하여 섹션에 태그를 지정하고 범위를 좁힐 수 있고, --replace로 동일한 소스의 기존 섹션을 업데이트하거나, --level 2로 계층 깊이를 설정할 수 있습니다 (1 = 가장 넓음, 6 = 가장 좁음). 디렉터리를 학습할 때 레벨은 폴더 깊이에서 자동으로 감지됩니다.

3. 검색

kbdb search "how does auth work"

결과는 관련성에 따라 순위가 매겨지며, 용어가 일치한 위치를 보여주는 스니펫이 포함됩니다. 출력은 기본적으로 --format rec (recfile: 각 줄에 field: value 형식)로 설정되어 grep에 용이합니다. 다른 형식: json(기계 판독 가능), text(번호 매기기 목록), mcp(JSON-RPC 2.0 봉투). --offset를 사용하여 큰 결과 집합을 페이지로 나눌 수 있습니다.

하이브리드 검색(키워드 + AI 유사도)을 시도하려면:

kbdb search "how does auth work" --algo hybrid

팁: CLI에서 --db는 선택 사항입니다. kbdb는 작업 디렉터리에서 가장 가까운 .kbdb 폴더까지 위로 이동하므로, 프로젝트 내 어디서든 명령이 작동합니다. 특정 베이스를 지정하려면 --db <dir>(.kbdb의 부모 디렉터리)을 사용하거나 KBDB_DB_DIR을 설정하세요. mcp 서버만 명시적인 --db가 필요합니다. 작업 디렉터리를 검색하지 않습니다.

베이스 간 검색: --other-db <dir>(반복 가능)을 사용하여 다른 데이터베이스의 읽기 전용 지식으로 결과를 보강하거나, --cascade를 추가하여 상위 디렉터리의 .kbdb 폴더에서도 가져올 수 있습니다:

kbdb search "how does auth work" \
   --other-db ~/shared-kb --cascade

모든 결과에는 source_db 필드가 포함됩니다. 이 필드는 결과가 나온 데이터베이스 루트를 나타내며, --db 또는 --other-db에 그대로 붙여넣을 수 있습니다.

스크립팅: --format json을 추가하여 파싱용 구조화된 JSON 출력을 얻으세요. CI 파이프라인에서 프롬프트를 억제하려면 --non-interactive를 사용하거나 KBDB_NON_INTERACTIVE=1을 설정하세요.

4. 컨텍스트 회상

kbdb recall <kbid> --depth 1

검색 결과의 kbid로 시작하여 컨텍스트를 점진적으로 확장하세요. 깊이 0은 섹션 내용을 제공하고, 깊이 1은 부모 문서와 역참조를 추가하며, 깊이 2는 형제 및 정방향 참조를 추가하고, 깊이 3은 참조된 섹션의 전체 텍스트를 포함합니다.

지식 베이스

지식 저장소를 구축, 검색 및 유지 관리합니다.

• 가져오기 -- 태그 및 소스 추적과 함께 Markdown 및 일반 텍스트 파일 가져오기

• 스마트 업데이트 -- 파일을 다시 학습하면 중복 대신 이전 버전을 대체합니다

• 기록 -- 대체된 섹션은 삭제되지 않고 은퇴합니다. kbdb history는 양쪽 끝에서 체인을 탐색하며, 이전 kb-id도 여전히 해석됩니다

• 검색 -- 세 가지 알고리즘: 키워드(기본), AI 유사도, 또는 하이브리드(둘 다)

• 자동 폴백 -- 정확한 쿼리가 아무것도 찾지 못하면 kbdb가 자동으로 일치 조건을 완화합니다

• 회상 -- 빠른 요약부터 전체 관련 콘텐츠까지, 또는 --max-tokens 예산이 허용하는 만큼 깊이, 점진적 컨텍스트로 섹션 회상

• 측정 -- 검색이 실제로 좋은지 측정. kbdb eval은 자체 데이터셋에 대해 Recall@k, MRR 및 nDCG@k를 점수화하고, 변경으로 순위가 나빠지면 0이 아닌 종료 코드를 반환합니다

• 이웃 -- kbdb neighbourhood는 섹션과 관련된 것과 그 방법을 알려줍니다. 8가지 유형의 엣지, 그중 7개는 기록된 사실이고 1개는 추론된 것입니다

• 통합 -- kbdb consolidate는 하나가 될 수 있는 섹션 그룹을 제안합니다. 제안만 하며, 병합은 직접 작성하고 적용해야 합니다

• 내보내기 -- 백업용 지식 베이스 스냅샷

• 검증 -- 데이터베이스 무결성 확인 및 오래된 데이터 정리

• 재구축 -- 문제가 발생하면 인덱스 재구축

전체 안내(내보내기 및 백업 포함)는 지식 베이스 가이드를 참조하세요.

에이전트 도구

kbdb를 AI 에이전트 및 사용자 지정 도구와 통합합니다.

MCP 빠른 시작(Claude CLI):

claude mcp add kbdb -- \
   npx @dikolab/kbdb mcp --db /path/to/project

Claude Code, VS Code 및 Claude Desktop 구성 파일과 문제 해결은 MCP 설치 가이드를 참조하세요.

• MCP 서버 -- 30개의 도구 제공: 검색, 회상, 학습, 수정, 공백, 모순, 내보내기, 스킬/에이전트 검색 등

• 스킬 -- 빈칸 채우기 인수를 가진 재사용 가능한 프롬프트 템플릿 저장

• 에이전트 -- 페르소나와 스킬을 결합한 AI 에이전트 프로필 생성

• 캡처 정책 -- 서버는 MCP 핸드셰이크 자체에서 에이전트에게 무엇을 저장할지 알려주므로 호스트별 구성이 필요 없습니다. 여섯 가지 조항 중 두 가지는 저장하지 말아야 할 것에 관한 것입니다: 채팅 요약, 추측, 비밀, 그리고 코드가 이미 말하는 것. kbdb는 정책을 전달합니다. 에이전트가 따르도록 강제할 수는 없습니다

• 자동 캡처 -- 호스트 자체 모델에게 저장할 가치가 있는 지식을 선택하도록 요청할 수 있습니다. MCP sampling 기능이 필요하며, Claude Code는 이를 광고하지 않으므로 자동 캡처는 거기서 비활성화됩니다. 이 목록의 다른 모든 기능은 영향을 받지 않습니다. 호스트 지원 참조

• 데몬 복원력 -- 구성 가능한 요청 시간 초과 및 데몬 재시작을 통한 자동 재시도

• 워커 데몬 수명 주기 관리 -- 백그라운드 프로세스 중지 및 재시작

• 세분화된 Deno 권한 -- 데몬은 --allow-all 대신 범위가 지정된 권한으로 실행됩니다

• 경로 제한 -- 데몬은 내보내기/가져오기에서 경로 탐색(..)을 거부합니다

서버가 에이전트에게 알리는 것. initialize 응답에는 instructions 문자열이 포함됩니다. 이는 모든 호환 MCP 호스트가 설정 없이 받는 유일한 채널입니다. kbdb는 이를 캡처 정책에 사용합니다. 답변 전에 검색하고, unanswered 판정을 추측 대신 조사할 공백으로 취급하며, 실제 노력이 필요한 결정과 수정을 저장하고, 코드가 이미 말하는 것을 저장하지 마십시오. 동일한 문장은 learn, revise 및 search 도구 설명에서 의역하지 않고 인용되므로, 모든 것에 대한 단일 소스가 있습니다.

MCP 설정, 스킬, 에이전트 및 라이브러리 API는 에이전트 도구 가이드를, 여섯 가지 조항 전체와 한 번 작성되는 이유는 캡처 정책을 참조하세요.

개발자용

라이브러리 API

Node.js 또는 Deno 프로젝트에서 kbdb를 프로그래밍 방식으로 사용하세요:

import { createWorkerClient } from '@dikolab/kbdb';

// Spawns a background worker if not already running
const client = await createWorkerClient({
   contextPath: '/path/to/.kbdb',
   requestTimeoutMs: 30_000,
});

const results = await client.search({
   query: 'authentication',
   limit: 10,
   offset: 0,
});

console.log(results.items);
client.disconnect();

contextPath(.kbdb 디렉터리 자체) 또는 dbPath(부모 디렉터리 -- kbdb가 내부에서 .kbdb를 발견)를 전달하세요.

전체 API는 라이브러리 API 참조를 참조하세요.

개발 설정

git clone https://gitlab.com/diko316/knowledge-base-db.git
cd knowledge-base-db
npm install
npm test

Docker

모든 빌드 도구(Node.js 및 Deno)가 포함된 Docker 설정이 포함되어 있습니다:

HOST_UMASK=$(umask) docker compose run --rm tool sh

make benchmark를 실행하여 대규모 검색 및 재구축 지연 시간을 측정하세요. 결과는 docs/benchmark/benchmark.md에 자동으로 기록됩니다.

사용 가능한 모든 빌드 대상은 Makefile을 참조하세요.

기여

1. 저장소를 포크합니다

2. 기능 브랜치를 만듭니다

3. 변경 사항을 적용하고 테스트를 추가합니다

4. npm test 및 npm run lint를 실행합니다

5. 병합 요청을 엽니다

문서

• Second Brain with Claude Code -- 공식 설정 가이드: 작업 공간 레이아웃, 올바른 명령어, MCP 연결

• CLI 설치 가이드 -- 사전 요구 사항, npm/JSR 설치, 검증

• Knowledge Base 가이드 -- 가져오기, 검색, 회상, 내보내기

• Agent Tooling 가이드 -- MCP, 스킬, 에이전트, 라이브러리 API

• CLI 참조 -- 예제가 포함된 전체 명령어 목록

• MCP 설치 가이드 -- Claude CLI, Claude Code, VS Code, Claude Desktop

• MCP Server 가이드 -- 설정, 도구, 환경 구성, 그리고 서버가 initialize 시 에이전트에게 전달하는 내용

• 호스트 지원 -- 캡처 정책을 전달하고 샘플링을 광고하는 MCP 호스트들, 추측이 아닌 측정 기반

• 캡처 정책 -- kbdb가 에이전트에게 저장하라고 지시하는 내용과 그 이유, 한 번만 명시되는 이유

• 검색 및 랭킹 -- 검색이 내부적으로 작동하는 방식

• 스토리지 아키텍처 -- 파일 형식, 디렉터리 레이아웃, 보존된 기록의 비용

• Deno 권한 -- kbdb에 필요한 권한 플래그와 그 이유

• 벤치마크 결과 -- 대규모 환경에서의 검색 및 재구축 지연 시간

• 학습 확장 -- 코퍼스 크기에 따라 학습 비용이 증가하는 방식

• 모순 신호 -- 1128개의 레이블링된 쌍을 대상으로 근접 중복 및 모순 임계값 보정

• 릴리스 노트

• 아키텍처 개요

검색 엔진

스토리지, 인덱싱 및 랭킹은 @dikolab/vdb에서 제공되며, 이는 같은 저자의 kbdb 자매 프로젝트입니다. 해당 문서는 검색 측면을 심층적으로 다룹니다:

• vdb 개요 -- 스토리지 모델, 파티션, BM25F, 벡터 및 하이브리드 검색

• vdb 예제 -- 실제 쿼리와 랭킹 동작

지원

kbdb는 무료 AGPL 라이선스 소프트웨어입니다. 업무 흐름에서 가치를 인정받았다면, PayPal을 통해 지속적인 개발을 지원할 수 있습니다.

라이선스

이 프로젝트는 이중 라이선스로 제공됩니다:

• 오픈 소스: GNU Affero General Public License v3.0 (AGPL-3.0-only) 조건에 따름

• 상용 라이선스: 폐쇄 소스 또는 SaaS 사용을 위해 제공

<= 0.5.0 버전은 ISC 라이선스로 유지됩니다.

자세한 내용 및 연락처는 LICENSING.md를 참조하세요.