Knowledge Base

knowledge-base

여러 소스(문서, git 로그, Slack, …)의 팀 지식을 하나의 Postgres 임베딩 테이블로 수집하고, 하이브리드 검색(전문검색 + 벡터 + RRF 융합)을 MCP 도구로 노출하는 지식 베이스 서버.

> Inspired by Cerebras’ "How We Built Our Knowledge Base".

핵심 원칙:

• 정보가 사는 곳에서 그대로 추출 — 커넥터가 소스별로 행을 정규화해 같은 테이블에 쓴다.

테이블에 들어가면 즉시 같은 인터페이스로 검색된다.

• 하이브리드 검색 — 전문검색(정확 토큰: 에러 문자열·설정 키)과 벡터 검색(개념 질의)을

RRF(k=60)로 융합. Slack 문서에는 나이 감쇠("옛 답변은 만료된다") 적용.

• MCP에는 LLM-free 검색 프리미티브만 — 합성된 답이 아니라 원시 증거 행을 반환.

오케스트레이션과 답변 생성은 Claude Code 같은 클라이언트 에이전트의 몫.

• 에이전트가 쓰는 지식 베이스 — 개발 중 내린 의사결정(record_decision)과

삽질에서 얻은 교훈(record_learning)을 MCP로 직접 기록하면 즉시 팀 전체가 검색 가능. 작업 전 pitfalls로 과거에 밟은 문제를 확인해 같은 실수를 반복하지 않는다 → [팀 워크플로 가이드](docs/05-team-workflow.md).

 SOURCES        markdown · git log · Slack(export/실시간) · 코드 저장소 · GitHub PR · (커스텀)
    │ sync (커넥터가 SourceRow 방출)          ┌ 에이전트/사람이 MCP로 직접 기록
 PIPELINE       해시 dedup → [대화형: LLM 증류] → 청킹(헤딩 인지) → [문맥 생성] → 임베딩
    │ upsert                                  └ record_decision / learning / note
 POSTGRES       documents(원문+FTS) + chunks(임베딩+문맥) — 단일 임베딩 테이블
    │ query
 SEARCH         FTS(희귀토큰 OR/접두) + 벡터 + IDF + trigram + 문맥FTS → 가중 RRF(k=60)
    │           → 나이 감쇠 · boost/숨김 · supersede 감점 · 소스별 중복 상한
 INTERFACES     kb CLI · MCP 서버(stdio 로컬 / Streamable HTTP 원격 — 토큰 또는 OAuth 인증)
                읽기: search·get_document·list_sources·who_knows·recent_changes
                      ·search_code·subsystem_index·recent_prs
                쓰기: record_decision·learning·note·verify_note·search_feedback / 예방: pitfalls
                웹 대시보드(:8080) — 운영 헬스 · 모델/API 비용 · 쿼리 분석 · 질문(/ask)
                      · 노트 재검증/중복 큐 · 토큰/프로젝트 관리

---

1. 요구사항

| 항목 | 버전 | 비고 | |---|---|---| | Python | 3.11+ | tomllib 사용 | | PostgreSQL | 14+ (16에서 테스트) | | | pgvector | 0.5+ (0.6에서 테스트) | HNSW 인덱스 사용. halfvec(2000차원 초과·메모리 절감)은 0.7+, 필터 검색 리콜 보정(iterativescan)은 0.8+에서 자동 활성 | | pgtrgm | 선택 권장 | 한국어 복합어 내부 매칭(trigram 신호). Postgres 기본 동봉 확장 | | ripgrep (rg) | 선택 | search_code 도구용. 없으면 grep 폴백 | | claude CLI 또는 ANTHROPIC_API_KEY 또는 AWS 자격증명 | 선택 | LLM 기능(증류/요약/재순위/문맥/질문)용. 컨테이너 환경은 backend="anthropic"(공식 SDK) 또는 backend="bedrock"(Bedrock의 Claude, API 키 불필요) — §7.3 |

2. 설치

git clone https://github.com/riemannulus/knowledge-base && cd knowledge-base
python3 -m venv .venv && source .venv/bin/activate
pip install -e .            # 개발용은 pip install -e ".[dev]"

선택 기능은 extras로: [aws](Bedrock 임베딩) · [slack](실시간 수집) · [dashboard](웹 대시보드, §11) · [anthropic](LLM 기능 API 백엔드, §7.3). Docker 이미지는 네 개를 모두 포함한다.

Postgres에 pgvector가 없다면 (Debian/Ubuntu 예시):

sudo apt-get install postgresql-16-pgvector
createdb kb                 # 원하는 이름의 DB 생성

3. 빠른 시작 (5분)

> Postgres 설치 없이 바로 띄우려면 §4.1의 Docker Compose 경로를 쓰면 된다 — > cp .env.example .env && docker compose up -d --build 한 번으로 DB·MCP 서버·sync가 다 뜬다.

# 1) 설정 파일 작성
cp kb.toml.example kb.toml
$EDITOR kb.toml             # dsn, 커넥터 경로 수정

# 2) 스키마 마이그레이션 (Alembic — 멱등, 여러 번 실행해도 안전)
kb migrate

# 3) 동기화 (커넥터 전체 실행, 증분)
kb sync
# {"connector": "markdown:kb-docs", "emitted": 4, "upserted": 4, ...}
# {"connector": "gitlog:kb-repo", "emitted": 12, "upserted": 12, ...}

# 4) 검색해 보기
kb search "배포 락 타임아웃"
kb search "ERR_MANIFEST_TIMEOUT" --source slack --limit 5
kb search "재색인 주기" --json

kb sync는 커서 기반 증분이다: 다시 실행하면 변경된 것만 처리하고, 내용이 같으면(content_hash) 재임베딩도 건너뛴다. 주기 실행은 cron에 걸면 된다:

*/10 * * * *  cd /path/to/kb && .venv/bin/kb sync >> /var/log/kb-sync.log 2>&1

4. Claude Code / Claude Desktop에 MCP로 연결

두 가지 모드가 있다:

• 로컬(stdio) — 혼자 쓸 때. 아래처럼 명령으로 등록.
• 원격(Streamable HTTP) — 팀 공유. §4.1의 Docker 배포 후 URL로 등록.

Claude Code (로컬 stdio)

claude mcp add kb --env KB_CONFIG=/absolute/path/kb.toml -- /absolute/path/.venv/bin/kb mcp

또는 프로젝트의 .mcp.json:

{
  "mcpServers": {
    "kb": {
      "command": "/absolute/path/.venv/bin/kb",
      "args": ["mcp"],
      "env": { "KB_CONFIG": "/absolute/path/kb.toml" }
    }
  }
}

Claude Desktop (로컬 stdio)

claude_desktop_config.json의 mcpServers에 위와 동일한 블록을 추가한다.

4.1 팀 공유 원격 서버 (Docker Compose로 한 번에)

cp .env.example .env
$EDITOR .env                      # KB_AUTH_TOKEN만 채우면 됨 (openssl rand -hex 24)
docker compose up -d --build

# 확인: 401이 나오면 정상 (인증이 걸린 상태)
curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8000/mcp -d '{}'

db(pgvector) + migrate(Alembic 스키마 마이그레이션 — 1회 실행 후 종료) + mcp(HTTP :8000/mcp, 헬스체크 포함) + sync(주기 동기화, KB_SYNC_INTERVAL 기본 300초) + dashboard(웹 UI :8080, §11) 서비스가 뜨고 재시작 정책이 걸려 있다. 앱 서비스들은 migrate가 성공해야 시작되므로 스키마 업그레이드가 배포에 자동 포함된다 (k8s도 동일 — mcp/dashboard의 initContainer, sync CronJob의 선행 단계). 기본값 그대로면 이 저장소 자신(docs/ + git log)을 인덱싱하는 데모로 즉시 동작하고, 실데이터는 .env의 KB_DOCS_DIR/KB_REPO_DIR와 deploy/kb.docker.toml을 수정한다. 커넥터 하나가 실패해도 나머지 sync는 계속된다(실패 격리). DB 데이터는 kb-pgdata 볼륨에 보존되므로 docker compose down(­-v 없이)으로는 유실되지 않는다.

수동 실행도 가능: kb mcp --transport http --host 0.0.0.0 --port 8000 (KB_AUTH_TOKEN 환경변수가 있으면 Authorization: Bearer 검사).

팀원 등록 (Claude Code):

claude mcp add --transport http kb https://kb.example.com/mcp \
  --header "Authorization: Bearer "

프로젝트 공유는 .mcp.json으로 (토큰은 각자 환경변수로 — 커밋 금지):

{
  "mcpServers": {
    "kb": {
      "type": "http",
      "url": "https://kb.example.com/mcp",
      "headers": { "Authorization": "Bearer ${KB_AUTH_TOKEN}" }
    }
  }
}

플러그인으로 한 번에 (권장): 수동 mcp add 대신 kb-workflow 플러그인을 설치하면 KB 연결(+워크플로 스킬 kb-brief/kb-log/kb-wrap + 기록 유실 방지 훅)이 함께 배선된다. 설치 시 서버 URL/토큰을 물어본다 — 로컬(compose)은 기본값 엔터, 원격은 팀 서버 URL + kbt_ 토큰 입력(마스킹·보안 저장소 저장). 이후 전환·재설정은 /plugin 메뉴의 플러그인 설정 또는 /kb-workflow:setup 참고. 프로젝트 .mcp.json에 동명 kb 서버를 정의하면 플러그인 정의를 덮는다(완전 오버라이드). 상세: [plugins/kb-workflow/README.md](plugins/kb-workflow/README.md).

/plugin marketplace add riemannulus/knowledge-base
/plugin install kb-workflow@knowledge-base

claude.ai / Claude Desktop 커스텀 커넥터: 설정 → 커넥터 → 커스텀 커넥터에 https://kb.example.com/mcp 등록. 웹 커넥터 UI는 커스텀 헤더를 붙일 수 없으므로 OAuth로 붙인다 — §4.2. 자동화/봇은 Anthropic API MCP connector의 authorization_token에 kbt_ 토큰을 쓰면 된다. 상세 절차와 운영 팁: [docs/05-team-workflow.md](docs/05-team-workflow.md).

4.2 claude.ai 웹 커넥터 연결 (Google OAuth)

kb가 스스로 OAuth 2.1 인가 서버(AS)가 되고 "누구인가"만 Google에 위임한다. claude.ai가 커넥터를 연결할 때 브라우저로 Google 로그인을 띄우고, 허용 도메인 계정이면 kb가 자기 액세스 토큰을 발급한다. 팀원은 토큰을 복사·붙여넣을 일이 없다.

claude.ai ──OAuth 2.1(PKCE + 동적 등록)──▶ kb(/mcp)
                                            └─OIDC─▶ Google (허용 도메인만 통과)

Google이 아니라 kb가 AS인 이유: Google은 임의 리소스 서버를 위한 RFC 9728 리소스 메타데이터도, MCP 클라이언트의 동적 등록(RFC 7591)도 제공하지 않는다. MCP 스펙이 명시한 3rd-party IdP 위임 패턴이 이 구조다.

1) Google OAuth 클라이언트 만들기 (하나로 커넥터·대시보드 모두 커버)

Google Cloud Console → API 및 서비스 → 사용자 인증 정보 → OAuth 클라이언트 ID → 애플리케이션 유형 웹 애플리케이션. 승인된 리디렉션 URI에 둘을 등록한다 (외부에서 실제로 접속하는 주소여야 하고, 문자 하나까지 일치해야 한다):

https://kb.example.com/oauth/google/callback     # MCP 서버 (= KB_PUBLIC_URL + 고정 경로)
https://kb-dash.example.com/auth/callback        # 대시보드 (= KB_DASHBOARD_URL + 고정 경로)

2) 서버 환경변수 (5개가 모두 있어야 켜진다 — 일부만 채우면 기동 시 예외로 알려준다)

| 환경변수 | 값 | |---|---| | KB_GOOGLE_CLIENT_ID / KB_GOOGLE_CLIENT_SECRET | 위에서 만든 클라이언트 | | KB_OAUTH_ALLOWED_DOMAINS | 허용 Google Workspace 도메인 (예: example.com) | | KB_OAUTH_SECRET | state·세션 쿠키 서명 키. openssl rand -hex 32 (레플리카 전체 동일) | | KB_PUBLIC_URL | MCP 서버 공개 주소 (예: https://kb.example.com) |

선택: KB_OAUTH_ALLOWED_EMAILS(도메인 밖 개별 허용), KB_OAUTH_TOKEN_TTL(기본 3600), KB_OAUTH_REFRESH_TTL(기본 30일). 설치는 pip install -e ".[oauth]" (Docker 이미지에는 포함, compose는 .env만 채우면 된다).

3) 팀원 연결: claude.ai 설정 → 커넥터 → 커스텀 커넥터에 https://kb.example.com/mcp 입력 → 연결 → Google 계정 선택. 끝. Claude Desktop·MCP Inspector·Claude Code (claude mcp add --transport http kb https://kb.example.com/mcp)도 같은 흐름을 탄다.

동작 확인:

# 무인증 요청은 401 + AS 위치를 알려주는 헤더를 돌려준다 (클라이언트가 이걸로 발견)
curl -si -X POST https://kb.example.com/mcp -d '{}' | grep -i www-authenticate
# WWW-Authenticate: Bearer error="invalid_token",
#   resource_metadata="https://kb.example.com/.well-known/oauth-protected-resource/mcp"

curl -s https://kb.example.com/.well-known/oauth-authorization-server | jq .issuer

노출되는 엔드포인트: /.well-known/oauth-authorization-server(RFC 8414), /.well-known/oauth-protected-resource/mcp(RFC 9728), /register(RFC 7591 동적 등록), /authorize, /token, /revoke(RFC 7009), /oauth/google/callback.

권한 모델: 허용 도메인 계정 = 팀 전체 접근(프로젝트 스코프 없음), 쓰기는 kb.write 스코프에 달려 있다(기본 발급에 포함 — 읽기 전용 클라이언트는 kb.read만 요청하면 된다). 신원 이름은 이메일이라 record_*의 author와 query_log에 그대로 남는다. 세부 스코프가 필요하면 kbt_ 토큰(§8.1)을 계속 쓰면 된다 — 두 경로는 공존한다.

운영: 등록된 커넥터와 활성 세션은 대시보드 토큰 페이지에서 보고 폐기한다 (kb oauth clients|sessions|revoke-client|revoke-user도 같은 일을 한다). 퇴사자 처리는 Google 계정 정지 + kb oauth revoke-user . 액세스 토큰은 만료가 짧고(기본 1시간), 리프레시는 회전할 때 옛 쌍이 함께 폐기된다.

⚠ OAuth를 켜면 "등록 토큰 0개 = 무인증 admin" 완화가 꺼진다 (§8.1) — 토큰 없는 요청은 항상 401이다. HTTPS는 여전히 reverse proxy/터널 몫이다: OAuth 토큰은 베어러라 평문 HTTP로 노출하면 그대로 유출된다.

연결 후 이렇게 물어보면 된다:

> "kb에서 검색해줘: staging 배포가 락 때문에 멈추는 문제 예전에 어떻게 해결했지?"

에이전트가 search → get_document를 호출해 근거 문서(document_id, URL)를 인용하며 답한다.

MCP 도구 레퍼런스

| 도구 | 파라미터 | 설명 | |---|---|---| | search | query, source?, project?, limit=10, rerank=false, expand=0 | 하이브리드 검색. expand=1~2면 매치 청크의 이웃을 context로 복원. 노트 결과의 project는 기록 시 명시한 소속 프로젝트(null=팀 공용) — 스코프 검색에서 타 프로젝트 노트는 하향 + other-project 표시. 반환: documentid/score/title/url/snippet/matched/context/project | | get_document | document_id, context=0 | 원문 전체 + (Slack이면) 증류 결과. context=1이면 헤딩 청크 목록 포함. 열람은 감사 로그에 남는다 | | list_sources | — | 소스/구획별 문서 수·최근 갱신·설명("무엇을 잘 답하나"), 프로젝트 목록. 도구 선택 전 상황 파악용 | | subsystem_index | query, limit=10 | 파일별 요약 인덱스 — "어느 파일에 구현돼 있나" 류 질문 (filesummary/file_head 대상) | | recent_prs | query?, days=14, limit=10 | 최근 PR 목록/검색 (github_prs 커넥터 필요) | | who_knows | topic, limit=5 | 주제 관련 스레드 참여자·커밋 작성자 집계 → 실증 전문가 | | recent_changes | source?, days=7, limit=20 | 최근 갱신 문서 (커밋/스레드/문서) | | search_code | pattern, repo?, regex=false, limit=30 | [code_repos] 위 ripgrep 정확 매칭 | | search_feedback | document_id, useful, query? | 검색 결과 품질 피드백 — 골든셋/큐레이션 재료 | | record_decision | title, decision, context?, alternatives?, tags?, author?, project?, code_refs?, supersedes? | 쓰기: 의사결정 기록. supersedes로 옛 결정 대체(번복 추적), code_refs의 파일이 바뀌면 재검증 대상 표시. 프로젝트 한정 결정이면 project 명시(미지정 = 팀 공용) | | record_learning | title, problem, root_cause?, solution?, prevention?, tags?, author?, project?, code_refs?, supersedes? | 쓰기: 삽질/버그 교훈 기록. prevention이 핵심. 특정 프로젝트에서만 성립하는 교훈이면 project 명시 | | record_note | title, content, tags?, author?, project? | 쓰기: 일반 지식 메모 | | stale_notes | days=90, limit=20, reason? | 재검증 큐 (대시보드와 동일): 참조 코드 변경(code) 우선, 90일+ 미검증(age) 다음. counts로 전체 규모 동봉 — 일일 재검증 루틴의 입력 | | verify_note | document_id | 쓰기: 노트 재검증 표시 (stale 플래그 해제) | | pitfalls | topic, limit=5, project? | 작업 전 사전 점검: 주제 관련 과거 교훈·결정 조회. 대체된 노트 제외, stale=true는 참조 코드가 변경됨 표시. 결과의 project는 소속 프로젝트(null=팀 공용), 스코프와 다른 프로젝트의 노트는 하향 + other_project=true |

모든 읽기 도구는 LLM을 호출하지 않아 빠르고 싸다. 쓰기 도구의 기록은 즉시 청킹·임베딩되어 바로 검색된다. record_* 응답의 similar_existing은 비슷한 기존 기록이 이미 있다는 신호다 — 같은 문제라면 새 제목 대신 기존 제목으로 갱신하거나 supersedes를 쓰라. 단 후보의 project가 다르면 같은 증상이라도 원인이 다를 수 있다 — 힌트에 경고가 붙으니 같은 근본 원인임을 확인한 경우에만 갱신하고, 아니면 별도 기록을 유지하라.

record*의 project는 등록된 프로젝트 이름 기준으로 해석된다: 등록명은 그대로, 저장소 이름(모노레포 하위 저장소 등 project_sources의 sourcekey)은 소유 프로젝트로 자동 교정, 등록되지 않았거나 여러 프로젝트에 걸려 모호한 이름은 라벨을 버리고 팀 공용으로 기록한다 — 잘못된 라벨은 자기 프로젝트 스코프 검색에서 억울한 감점을 만들기 때문. 결과는 응답의 project(최종 저장값)와 project_hint(교정/폐기 사유)로 알 수 있고, 같은 제목으로 다시 기록하면 갱신되므로 즉시 교정 가능하다. 에이전트가 이 루프(작업 전 pitfalls → 작업 후 record)를 스스로 돌게 만드는 CLAUDE.md 스니펫은 [docs/05-team-workflow.md](docs/05-team-workflow.md) §3에 있다.

5. kb.toml 레퍼런스

[database]
dsn = "host=127.0.0.1 port=5432 user=kb dbname=kb"  # $KB_DSN이 있으면 그것이 우선

[embedding]
backend = "hashing"   # 'hashing' | 'openai' | 'bedrock'
dim = 1024
model = ""            # openai: 기본 text-embedding-3-small / bedrock: 기본 amazon.titan-embed-text-v2:0
region = ""           # bedrock 전용 AWS 리전 (비우면 $AWS_REGION)

[distill]
backend = "none"      # 'none' | 'claude-cli'
model = "claude-haiku-4-5-20251001"

[[connector]]         # 소스 하나당 하나. type: markdown | gitlog | slack_export
type = "markdown"
root = "docs"         # 상대 경로는 kb.toml 위치 기준
source_key = "kb-docs"
url_prefix = "https://github.com/org/repo/blob/main/docs"   # 선택: 결과 URL 생성

[[connector]]
type = "gitlog"
repo = "."
source_key = "kb-repo"
url_prefix = "https://github.com/org/repo/commit"

[[connector]]
type = "slack_export"
root = "/data/slack-export"      # 워크스페이스 export(zip 해제) 디렉터리
channels = ["deploy", "infra"]   # 생략 시 전체 채널
workspace_url = "https://your.slack.com"   # 선택: 스레드 딥링크 생성

[[connector]]
type = "github_prs"   # PR 본문+코멘트를 대화형 문서로 수집 (증류 경로 적용)
repo = "org/repo"     # $GITHUB_TOKEN 권장
source_key = "prs"

[code_repos]          # search_code(ripgrep) 대상
platform = "/srv/repos/platform"

이 밖에 [context](청크 문맥 생성 — Contextual Retrieval), [ask](대시보드 질문 페이지), [rerank] pool, [chunking] max_chars, [search](RRF 가중치·다양성 캡), [pricing](단가 오버라이드), 커넥터 description(소스 카탈로그) 옵션이 있다 — 전체 주석은 [kb.toml.example](kb.toml.example) 참고. LLM 백엔드는 공통으로 'none' | 'claude-cli' | 'anthropic' | 'bedrock'이며, API 백엔드는 컨테이너/k8s에서도 동작한다 (pip install '.[anthropic]', bedrock은 [anthropic,aws]).

[context]는 프롬프트 캐싱으로 동작한다: 문서 본문을 캐시 프리픽스로 한 번 기록(1.25×)한 뒤 나머지 청크가 캐시 적중(0.1×)으로 돌아, 청크마다 문서를 풀프라이스로 재전송하는 것 대비 첫 백필 비용이 ~85% 절감된다. 캐시 프라이밍 후 청크 호출은 4-way 병렬이라 백필 속도도 그만큼 빨라진다 (API 백엔드 한정 — claude-cli는 캐싱 제어가 없어 프리픽스를 이어붙여 실행).

환경변수: KB_CONFIG(설정 파일 경로), KB_DSN(DSN 오버라이드), OPENAI_API_KEY/OPENAI_BASE_URL(openai 임베딩), ANTHROPIC_API_KEY(anthropic LLM 백엔드), GITHUB_TOKEN(github_prs 커넥터).

6. CLI 레퍼런스

| 명령 | 설명 | |---|---| | kb migrate (별칭 init-db) | 스키마를 최신 Alembic 리비전으로 (멱등). 구 init-db 스키마는 자동으로 baseline stamp 후 편입. compose/k8s 배포는 자동 실행 | | kb sync [--connector 이름] | 전체(또는 특정) 커넥터 증분 동기화. 이름은 markdown:kb-docs 형식 | | kb search "질의" [--source S] [--project P] [--limit N] [--rerank] [--expand N] [--json] | 하이브리드 검색. --expand는 매치 청크 이웃 복원, --rerank는 LLM 재채점 | | kb eval golden.jsonl [--k 10] | 골든셋 검색 품질 평가 (Recall@k/MRR/nDCG). 모든 검색 튜닝의 판정 기준 | | kb eval --bootstrap out.jsonl [--days 30] | query_log에서 골든셋 스켈레톤 생성 (expect는 사람이 라벨링) | | kb notes stale [--days 90] | 재검증 필요 노트 (참조 코드 변경 또는 장기 미검증) | | kb notes dedup [--threshold 0.85] | 유사 노트 쌍(병합 후보) — 자동 병합 안 함 | | kb notes verify / kb notes supersede | 노트 재검증 / 대체 표시 | | kb token create/list/revoke [--default-project P] | 사용자별 접근 토큰 관리 (§8.1). default-project는 soft 기본 스코프 | | kb oauth clients\|sessions\|revoke-client\|revoke-user\|prune | OAuth 커넥터 등록·사용자 세션 조회/폐기 (§4.2). 대시보드 토큰 페이지와 같은 조작의 헤드리스 경로 | | kb stats [--days N] | 쿼리 로그 분석 — 무응답 질의(커넥터/골든세트 백로그 후보), 상위 질의, 클라이언트별 사용량 | | kb reindex | 전 문서 재청킹·재임베딩 — 임베딩 백엔드/차원 변경 후 필수 | | kb gc [--connector 이름] [--dry-run] | 소스에서 사라진 문서(유령) 수거. sync에도 포함되므로 평소엔 불필요 — 미리보기/수동용 | | kb slack-listen | Slack Socket Mode 실시간 수집 (SLACK_BOT_TOKEN, SLACK_APP_TOKEN 필요, §7.2) | | kb mcp [--transport stdio\|http] [--host H] [--port P] | MCP 서버 실행. http면 /mcp 경로, KB_AUTH_TOKEN 설정 시 베어러 인증 | | kb dashboard [--host H] [--port P] | 웹 대시보드 (기본 :8080) — 운영 헬스/모델·비용/검색/관리 (§11) |

공통 옵션: --config /path/kb.toml.

6.1 원본이 바뀌거나 사라지면 (드리프트 처리)

| 원본 변화 | 동작 | |---|---| | 내용 수정 | 커서에 걸려 재방출 → content_hash 비교 후 변경분만 재청킹·재임베딩 (같으면 스킵) | | 파일 삭제 | sync 말미의 reconcile이 소스의 현재 목록(current_ids)과 대조해 유령 행 삭제 | | 파일 이름변경/이동 | 새 경로로 재인덱싱 + 옛 경로 유령 삭제 (파일별 mtime 커서라 rename도 감지) | | Slack 메시지 수정 (답글 없이) | edited.ts가 커서에 반영되어 스레드 전체 재수집 | | git 히스토리 리라이트 (force

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: riemannulus
• Source: riemannulus/knowledge-base
• License: MIT

Install and usage instructions live in the source repository linked above.