HippoBox는 개인 지식을 체계적으로 관리하고 AI Agent가 활용할 수 있도록 설계한 Knowledge Management Platform입니다.
FastAPI와 FastAPI-MCP를 기반으로 구축한 통합 지식 관리 서비스로, 지식 항목에 대한 CRUD(Create, Read, Update, Delete), 임베딩 기반 Semantic Search, MCP(Model Context Protocol) Tool Integration을 제공합니다. 이를 통해 Claude, Cursor, Codex 등 MCP를 지원하는 다양한 AI 클라이언트에서 동일한 Knowledge API를 일관된 방식으로 활용할 수 있습니다.
이 페이지에서는 HippoBox를 개발하게 된 목표와 시스템 아키텍처, 주요 기능 및 구현 과정, 그리고 프로젝트를 통해 얻은 결과와 경험을 소개합니다.
AI가 활용할 수 있는 지식은 사람도 쉽게 관리할 수 있어야 합니다.
AI 도구가 늘어날수록 지식은 여러 서비스에 분산되고, 같은 내용을 반복해서 관리해야 하는 문제가 발생합니다.
HippoBox는 하나의 Knowledge Base를 중심으로 사람과 AI가 동일한 지식을 함께 활용할 수 있는 환경을 목표로 시작한 프로젝트입니다.
이를 위해 FastAPI 기반의 Knowledge CRUD 서비스를 구축하고, FastAPI-MCP를 통해 동일한 기능을 MCP(Model Context Protocol) Tool로 제공합니다. 또한 Qdrant 기반의 임베딩 검색을 적용하여 AI가 단순 키워드가 아닌 의미 기반으로 지식을 검색하고 활용할 수 있도록 설계했습니다.
React
TypeScript
React와 TypeScript 기반의 모놀리식 프론트엔드입니다.
OpenAPI Generator를 통해 백엔드 API 클라이언트를 자동 생성하여 프론트엔드와 백엔드 간 인터페이스를 일관되게 유지했습니다. 배포 시에는 정적 파일을 모놀리식 애플리케이션에서 함께 제공하여 단일 서버만으로 서비스를 운영할 수 있도록 구성했습니다.
FastAPI
Knowledge API
MCP Server
FastAPI-MCP
SQLAlchemy
Data Access / ORM
Qdrant
Vector Index
Database
Knowledge Metadata
Claude
Cursor
Codex
Knowledge CRUD를 제공하는 FastAPI 기반 백엔드입니다.
FastAPI-MCP를 통해 REST API를 MCP(Model Context Protocol) 도구로 동시에 제공하여 AI Agent가 동일한 기능을 직접 호출할 수 있도록 구성했습니다. 이를 통해 Claude, Cursor, Codex 등 MCP를 지원하는 다양한 AI 클라이언트에서 별도의 API 구현 없이 동일한 Knowledge API를 활용할 수 있습니다. 또한 SQLAlchemy 기반으로 다양한 데이터베이스를 지원하며, Qdrant를 활용한 임베딩 기반 RAG 검색 기능을 제공합니다.
로컬 개발 환경과 CI 환경에서 동일한 빌드 과정을 사용할 수 있도록 배포 파이프라인을 구성했습니다.
Hatch를 공통 빌드 엔트리로 사용하여 Docker 이미지 생성과 GitHub Actions 기반 CI를 일관되게 관리하며, 빌드 결과물은 Docker Image, PyPI, GitHub Container Registry(GHCR)에 자동 배포됩니다.
Hatch Script
Shared Build Entry
Local Build
Docker Build
GitHub Actions
CI Build
Docker Image
Local
PyPI
Package
GHCR
Registry
1. 패키지 설치 및 실행
bash
pip install hippobox
hippobox run2. 백엔드 서버 실행
bash
cd src/backend
uv sync
uv run uvicorn hippobox.server:app --reload3. 프론트엔드 실행 및 빌드
bash
cd src/frontend
npm install
npm run dev
npm run dev:vite
npm run buildHippoBox는 저장된 지식을 사람이 직접 관리할 수 있는 Knowledge UI를 제공합니다. 지식은 Topic 단위로 분류되고, 제목·태그·본문을 함께 저장할 수 있으며, 본문은 Markdown 기반 지식으로 관리됩니다.
Hippo Search(VDB)는 저장된 지식을 임베딩한 뒤 의미 기반으로 검색하는 기능입니다. 단순 키워드 매칭이 아니라 질문의 의미와 가까운 지식을 찾아 AI Agent가 필요한 컨텍스트를 안정적으로 가져오도록 설계했습니다.
HippoBox는 FastAPI-MCP를 통해 Knowledge CRUD API를 MCP Tool로 제공합니다. Claude, Cursor, Codex 같은 MCP 클라이언트는 별도 전용 API 구현 없이 동일한 Knowledge API를 호출할 수 있습니다.
MCP 클라이언트에서 HippoBox 도구를 호출하면 Agent가 Knowledge API를 통해 실제 지식 항목을 생성하고 결과를 반환합니다. 터미널 출력에서는 Frontend / Backend 지식 항목 생성 흐름을 확인할 수 있습니다.
사람과 AI가 하나의 Knowledge Base를 함께 사용할 수 있도록 만들었습니다.
HippoBox는 제가 처음 목표로 했던 Local-first Knowledge Platform을 실제로 구현한 프로젝트입니다. Markdown 기반으로 지식을 관리하고, MCP를 통해 AI Agent와 연결하며, Semantic Search를 통해 필요한 지식을 의미 기반으로 찾을 수 있도록 구성했습니다.
사용자는 하나의 Knowledge Base만 관리하면 되고, Claude, Cursor, Codex 같은 AI Agent는 동일한 Knowledge API를 통해 같은 지식을 활용할 수 있습니다. 사람이 관리한 지식을 AI도 자연스럽게 활용하는 환경을 만드는 것이 HippoBox의 가장 큰 결과였습니다.
AI 기능을 만드는 것보다 AI가 활용하기 쉬운 구조를 만드는 것이 더 중요했습니다.
HippoBox를 개발하면서 FastAPI 기반 백엔드, MCP 서버, 그리고 RAG 기반 Semantic Search를 직접 설계하고 구현하며 AI 친화적인 서비스 구조를 고민할 수 있었습니다.
또 하나 크게 느낀 점은 에이전틱 코딩을 반복적으로 활용하려면 프로젝트를 처음부터 다시 만드는 것이 아니라, 인증, 배포, 프로젝트 구조 같은 기반이 미리 준비되어 있어야 한다는 것이었습니다. 그래서 HippoBox에서 얻은 경험을 바탕으로 AI 애플리케이션을 빠르게 시작할 수 있는 Blueprint4Agent(B4A) 프로젝트를 이어서 개발하게 되었습니다.