AKB: AI 에이전트를 위한 Git 기반 조직 지식베이스, MCP로 제공되는 지식 그래프

9bow · 5월 22, 2026, 12:30오후

AKB 소개

AKB(Agent Knowledgebase)는 AI 에이전트가 조직의 문서, 표, 파일을 일관된 방식으로 읽고 쓰도록 만들어진 지식베이스입니다. Confluence나 Notion 같은 사람용 UI 도구가 클릭과 페이지 트리에 최적화되어 있다면, AKB는 MCP 호출과 URI 그래프에 최적화된 형태로 같은 자리를 채우려는 시도입니다. 저장소는 Git bare 저장소, 검색·메타데이터의 단일 진실 공급원(Source of Truth)은 PostgreSQL 16, 벡터 인덱스는 드라이버 교체가 가능한 구조로 갈라져 있습니다.

핵심 차별점은 에이전트 친화적 인터페이스 와 플러그형 벡터 스토어 두 가지입니다. 에이전트는 akb_put, akb_search, akb_browse, akb_relations, akb_grep 같은 도구를 MCP(Model Context Protocol)로 한 번에 호출해 문서 CRUD, 하이브리드 검색, 지식 그래프 탐색, 권한 부여, 공개 발행까지 일관된 인터페이스로 처리합니다. 벡터 스토어는 기본값인 pgvector(PostgreSQL과 동일 컨테이너) 외에 qdrant, 관리형 seahorse-cloud, 자체 호스팅 seahorse-db, 실험적 seahorse-db-grpc 까지 다섯 개 드라이버 중 하나를 설정 한 줄로 고를 수 있습니다.

문서 수준에서도 에이전트가 다루기 쉬운 형태를 강제합니다. 모든 문서는 YAML frontmatter가 붙은 Markdown이고, akb://{vault}/{path} 형태의 URI로 식별됩니다. 프런트매터에 depends_on, related_to, implements 같은 관계 필드를 쓰면 그 자체로 지식 그래프의 엣지가 되며, akb_graph·akb_relations 도구로 탐색됩니다. 본 게시물에서는 AKB가 설계한 저장 구조, 하이브리드 검색의 LongMemEval 결과, 그리고 확장이 작은 코어 바깥에서 일어나도록 분리한 이벤트 모델을 정리합니다.

AKB의 3계층 아키텍처

AKB의 구조는 접근 계층(Access Layer) → 코어 서비스(Core Services) → 저장 계층(Storage Layer) 의 3계층으로 구성됩니다. 외부에서 보이는 면은 MCP 서버, REST API, 웹 UI 세 갈래이며, 그 아래에서 문서 CRUD, 하이브리드 검색, 관계 그래프, 세션, 공개 발행이 동일한 코어 서비스를 공유합니다. 저장 계층은 텍스트 본문을 보관하는 Git bare 저장소와 청크 텍스트·메타·BM25 어휘를 보관하는 PostgreSQL, 그리고 분리된 벡터 인덱스로 구성됩니다.

┌──────────────────────────────────────────────────────────┐
│                  Access Layer                            │
│   MCP Server  │  REST API  │  Web UI                     │
├──────────────────────────────────────────────────────────┤
│                  Core Services                           │
│   Document (Put/Get)  │  Search (Hybrid: dense+BM25)     │
│   Relations (graph)   │  Session  │  Publications        │
├──────────────────────────────────────────────────────────┤
│                  Storage Layer                           │
│   Git bare repos       │  PostgreSQL 16 (text + meta SoT)│
│                        │  Vector store (driver):         │
│                        │    pgvector        (default, PG)│
│                        │    qdrant          (optional)   │
│                        │    seahorse-cloud  (managed)    │
│                        │    seahorse-db     (self-hosted)│
│                        │    seahorse-db-grpc(experimental)│
└──────────────────────────────────────────────────────────┘

여기서 중요한 결정 하나는 PostgreSQL이 진실 공급원이고 벡터 스토어는 파생 인덱스라는 점입니다. 청크 텍스트와 메타데이터, BM25 어휘는 PG에 있고, 벡터 스토어에는 dense 임베딩과 corpus-side sparse 벡터만 들어갑니다. README에 따르면 벡터 스토어 전체가 손실되어도 chunks.vector_indexed_at = NULL 로 재설정하면 인덱싱 워커가 PG에서 다시 채워 넣을 수 있습니다. 운영 관점에서 벡터 인덱스를 복구 가능한 캐시 로 다룰 수 있다는 뜻입니다.

AKB의 Vault, Collection, Document 모델

저장 구조는 세 단계로 단순합니다.

Vault: Git bare 저장소 하나. 접근 제어와 물리적 격리의 단위입니다.
Collection: vault 안의 디렉토리. 주제별 묶음입니다.
Document: YAML frontmatter가 붙은 Markdown 파일. 에이전트 읽기·쓰기에 맞춰 다듬어진 형식입니다.

문서 프런트매터에는 단순한 메타 외에 관계 필드 가 1급 시민으로 존재합니다. README의 예시는 다음과 같습니다.

---
title: "Payment API v2 migration plan"
type: plan              # note | report | decision | spec | plan | session | task | reference
status: active          # draft | active | archived | superseded
tags: [payments, api]
domain: engineering
summary: "REST → gRPC transition plan."
depends_on: ["akb://eng/specs/payment-api-v2"]
related_to: ["akb://eng/meetings/2026-05-01-payments"]
---

# Payment API v2 migration plan
...

depends_on, related_to, implements 같은 필드는 본문 안의 free-form 멘션이 아니라 명시적 엣지 로 취급됩니다. akb_link / akb_unlink 도구로 갱신하고 akb_graph 로 탐색할 수 있어, 별도의 그래프 DB를 두지 않고도 문서끼리의 관계를 일관된 인터페이스로 다룹니다. URI 식별자(akb://{vault}/{path})는 모든 도구의 입력·출력에서 같은 핸들로 쓰이므로 에이전트가 헷갈릴 여지가 줄어듭니다.

AKB의 하이브리드 검색과 LongMemEval 결과

검색은 dense 임베딩 점수와 BM25 lexical 점수를 RRF(Reciprocal Rank Fusion)로 결합해 한 번의 호출로 돌려줍니다. 드라이버에 따라 RRF는 애플리케이션 단(pgvector)에서 돌거나 네이티브로 처리되며(qdrant의 Query API, Seahorse 계열의 서버사이드 BM25와 dense+sparse 하이브리드), 결과 인터페이스는 동일합니다. 임베딩 엔드포인트가 잠시 끊겨도 pgvector와 qdrant 드라이버는 BM25-only 렉시컬 검색으로 강등(degrade)되어 빈 결과 대신 키워드 검색이라도 돌려주므로, dense 검색은 끝단까지 선택 사항입니다. 다만 seahorse-db는 sparse 경로가 서버측 임베딩에 묶여 있어 이 폴백을 지원하지 않으므로, 이 드라이버에서는 임베딩 엔드포인트를 항상 살려 두어야 합니다.

저장소가 공개한 LongMemEval-S 벤치마크는 긴 컨텍스트 메모리에 대한 검색 품질 을 본 결과입니다. README 표는 다음과 같습니다.

시스템	R@5	n	Reranker	출처
AKB hybrid	98.4%	500	no	this repo
MemPalace hybrid + rerank	98.4%	450	yes	MemPalace
gbrain hybrid	97.6%	500	no	gbrain-evals
gbrain vector	97.4%	500	no	gbrain-evals

저자는 "리랭커(Reranker) 없이 동일 수준에 도달했다" 는 점을 강조합니다. 다만 README도 같이 적어두고 있듯이 임베딩 모델이 시스템마다 다르므로(AKB는 bge-m3@1024), 모델 단위 비교가 아니라 스택 단위 의 비교로 읽어야 합니다. 방법론과 카테고리별 점수, 재현 스크립트는 저장소의 eval/longmemeval/ 디렉토리에 정리되어 있습니다.

AKB의 MCP 도구 카탈로그

AKB는 다양한 종류의 작업을 묶어서 노출합니다. 도구 카탈로그의 일부는 다음과 같습니다.

도구	설명
`akb_list_vaults` / `akb_create_vault`	vault 관리
`akb_put` / `akb_get` / `akb_update` / `akb_delete`	문서 CRUD (Git 커밋 + 인덱싱)
`akb_put_file` / `akb_get_file` / `akb_delete_file`	파일 첨부 (로컬 파일시스템을 쓰는 프록시 측 도구)
`akb_create_table` / `akb_alter_table` / `akb_drop_table` / `akb_sql`	문서 단위의 표와 SQL
`akb_browse`	트리 탐색 (collection → docs)
`akb_search` / `akb_grep`	하이브리드 검색 / 리터럴 grep
`akb_drill_down`	섹션 단위 조회
`akb_relations` / `akb_link` / `akb_unlink` / `akb_graph`	지식 그래프
`akb_edit` / `akb_diff` / `akb_history`	인플레이스 편집, diff, Git 히스토리
`akb_grant` / `akb_revoke` / `akb_set_public`	사용자·조직·공개 단위 권한
`akb_publish` / `akb_unpublish`	공개 발행

예전 버전에서 MCP 도구로 노출되던 에이전트 메모리(akb_remember 등)와 세션 라이프사이클은 이제 MCP 도구가 아니라 전용 REST 경로(/api/v1/agent-sessions)로 분리되었고, akb-claude-code와 akb-cursor 같은 라이프사이클 플러그인이 에이전트의 SessionStart / PreCompact / SessionEnd 이벤트에 훅으로 붙어 구동합니다. 에이전트 자신의 메모리 볼트(agent-memory-{username})는 다른 볼트와 똑같이 표준 akb_search / akb_browse / akb_get 으로 열람할 수 있습니다.

전체 도구 목록은 MCP 클라이언트에서 akb_help() 로 받을 수 있다고 README가 안내합니다. Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Continue는 npm에 올라온 akb-mcp stdio 프록시를 통해 연결하고, 커스텀 에이전트는 Bearer 토큰으로 POST /mcp/ 를 직접 호출해도 됩니다.

AKB의 확장 모델, 작은 코어와 Redis 스트림 이벤트

AKB의 "디자인 철학(Design Philosophy)" 으로 명시된 "핵심은 작게 유지하고; 내부 자동화 없이, 확장 모듈을 통해 유연성을 가져갑니다(Core stays small; flexibility comes from extension, not built-in automation)"라는 문구는 흥미롭습니다. 자동 요약(consolidator), 정리 봇(knowledge gardener), 문서 노화 처리(doc-rot reaper) 같은 해석 영역의 기능은 코어에 포함하지 않습니다. 대신 모든 쓰기 작업이 구조화된 이벤트를 akb:events Redis Stream으로 흘려보내도록 해 두었고, 외부에서 이를 구독해 원하는 동작을 붙이도록 위임합니다.

이벤트 전달 자체도 단계가 분리되어 있습니다. PG의 events outbox는 항상 기록되며, redis_url 을 app.yaml 에 설정해두면 events_publisher 워커가 PG outbox를 비워가며 Redis Stream에 적재합니다. Redis가 없으면 PG의 LISTEN/NOTIFY 트리거 위에 SSE 같은 전달 계층을 직접 얹어도 됩니다. 즉, 코어는 read/write 저장소까지만 책임지고, 그 위에서 무엇을 할지는 운영자에게 맡긴다 는 설계 철학이 그대로 드러납니다.

AKB의 선택적 운영 기능, LLM 태깅과 감사 로그

같은 작은 코어 + 선택적 확장 기조는 운영 기능에도 그대로 적용됩니다. 문서 자동 태깅에 쓰는 LLM 호출은 외부 git 미러링으로 가져온 문서를 처리하는 metadata_worker 에서만 사용되며, 핵심 CRUD와 검색은 LLM 없이 동작합니다. 감사(audit) 로그도 기본값은 꺼짐이고, app.yaml 에서 audit.enabled: true 로 켜면 MCP 디스패치 길목에서 모든 읽기, 쓰기, 인증 거부를 해시 체인으로 연결된(hash-chained) append-only JSON Lines로 남깁니다. 각 줄에 직전 줄까지의 해시(sha256(prev || line))를 담아 누락이나 변조를 검증할 수 있고, AKB 자신은 생산자(producer) 역할만 해서 저장과 질의, 보존 정책은 Splunk나 Elastic 같은 외부 SIEM에 맡깁니다. 필요하면 하루 단위로 말린 로그 파일을 Object Lock이 걸린 WORM 버킷으로 넘겨 변경 불가능한 추적 로그를 만들 수도 있습니다.

AKB 설치 및 사용법

AKB는 PostgreSQL(with pgvector) + 백엔드 + 프런트엔드 세 컨테이너로 구성된 스택으로 배포됩니다. OpenAI 호환 임베딩 엔드포인트 하나만 외부에 두면 코어 CRUD와 검색은 동작합니다 (OpenAI, OpenRouter, 자체 호스팅 vLLM/TEI 등).

# 1. 설정
cp config/app.yaml.example   config/app.yaml
cp config/secret.yaml.example config/secret.yaml
$EDITOR config/secret.yaml   # embed_api_key 와 (배포 시) jwt_secret 설정

# 2. 실행
docker compose up -d

# 3. 접속
open http://localhost:3000

런타임 설정의 단일 진실 공급원은 config/app.yaml 과 config/secret.yaml 입니다. 백엔드는 환경 변수를 읽지 않고, 배포 시에는 config/ 디렉토리를 /etc/akb/ 에 마운트하라고 README가 안내합니다. Qdrant나 Seahorse Cloud로 벡터 스토어를 갈아끼우는 절차도 설정 한 줄과 docker compose 오버레이 수준입니다.

# Qdrant 사용
docker compose -f docker-compose.yaml -f docker-compose.qdrant.yaml up
# config/app.yaml: vector_store_driver: qdrant
#                   vector_url: http://qdrant:6333

임베딩 모델·차원도 embed_base_url / embed_model / embed_dimensions 설정으로 결정되며, 코드에는 하드코딩이 없습니다. pgvector + HNSW 환경에서는 embed_dimensions ≤ 2000 (또는 halfvec 사용 시 4000) 범위에서 인덱스를 쓰고, 그 이상은 exact scan으로 떨어집니다. Qdrant와 Seahorse는 이런 제한이 없다고 README에 명시되어 있습니다.

Kubernetes 배포는 저장소의 deploy/k8s/ 디렉토리에 일반화된 kustomize base가 들어 있습니다.

AKB의 라이선스

AKB의 백엔드, 프런트엔드, 배포 매니페스트는 Business Source License 1.1(BSL 1.1) 로 공개됩니다. 소스가 공개되는(source-available) 라이선스로, 추가 사용 허가(Additional Use Grant) 에 따라 좌석 수가 일정 수준 미만이면 상업적이든 비상업적이든 프로덕션에 쓸 수 있고, 각 버전이 처음 공개 배포된 시점으로부터 4년이 지나면 자동으로 Apache License 2.0 으로 전환됩니다. 이전 게시 시점의 PolyForm Noncommercial(비상업 전용)에서 BSL로 옮겨오면서, 무료 사용 범위가 상업적 프로덕션까지 넓어진 대신 좌석 수 상한과 재배포 제약이 들어갔습니다.

무료로 프로덕션에 쓸 수 있는 기준은 100 Named Seats 미만입니다. 여기서 Named Seat는 한 배포(deployment)의 users 테이블에 존재하는 고유 사용자 계정을 가리키며, 봇이나 CI 같은 서비스 계정과 최근 90일간 로그인 기록이 없는 계정은 집계에서 빠집니다. 100 Named Seats 이상으로 운영하거나, 좌석 수와 무관하게 AKB를 호스팅 서비스, 온프레미스 제품, 임베디드 구성요소, 리브랜딩 배포 형태로 제3자에게 제공하려면 별도 상업 라이선스가 필요합니다.

한편 npm으로 배포되는 akb-mcp 프록시(packages/akb-mcp-client/)는 별도로 MIT 라이선스라서, 어떤 에이전트 클라이언트에든 제약 없이 포함시킬 수 있습니다.

또한 "AKB", "Dnotitia", "Seahorse" 는 Dnotitia, Inc.의 상표이며 소프트웨어 라이선스에 상표권은 포함되지 않습니다. 포크나 파생물은 다른 이름으로 배포해야 한다고 저장소의 TRADEMARKS.md 가 안내합니다. 상업 라이선스, BSL 전환 배경, 상표 사용 문의는 LICENSE-CHANGE.md 또는 support@dnotitia.com 으로 하면 됩니다.

AKB 프로젝트 GitHub 저장소

AKB MCP 프록시 npm 패키지

https://www.npmjs.com/package/akb-mcp

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~