5d5336757d
- Hybrid BM25 + HNSW vector search with context enrichment - Knowledge graph with entities, relations, and community detection - Host-following LLM route with fallback backends - 3-tier lint system (static + HNSW dup + contradiction detection) - Q&A Synthesis (Karpathy LLM Wiki pattern) - 16 MCP tools for agent-driven workflows - Incremental wiki generation with checkpointing - SQLite-backed item store with FTS5 + vector indexes
133 lines
4.6 KiB
Markdown
133 lines
4.6 KiB
Markdown
# AGENTS.md — habraid
|
|
|
|
> Codex 에이전트를 위한 프로젝트 지도. 상세한 내용은 docs/ 참조.
|
|
|
|
## 작업 시작 전 필수 읽기
|
|
|
|
1. `docs/specs/host-following-llm.md` (해당 변경 작업일 때)
|
|
2. `docs/architecture.md`
|
|
3. `docs/config-reference.md`
|
|
4. 관련 `PLAN*.md`
|
|
|
|
## 작업 규칙
|
|
|
|
- 구현 전에 관련 `docs/specs/*.md`를 먼저 읽고, 없으면 먼저 spec부터 작성한다.
|
|
- 프롬프트/요구사항 정리는 `Goal / Context / Constraints / Done when` 구조를 우선한다.
|
|
- 큰 변경은 탐색 → 설계 → 구현 → 검증 순서로 진행한다.
|
|
- HaBraid는 memory backend를 wiki 표현층으로 바꾸는 orchestration layer다.
|
|
- 모델 선택은 기본적으로 host가 담당하고, habraid는 host-following을 기본값으로 지향한다.
|
|
- standalone LLM backend는 fallback/독립 실행 용도로만 유지한다.
|
|
|
|
## 프로젝트 개요
|
|
|
|
**habraid**: Obsidian 마크다운 위키 엔진. 지식 아이템을 수집/검색/위키화.
|
|
MemPalace가 있으면 연동하고, 없어도 자체 SQLite DB로 완전 동작.
|
|
|
|
## 빠른 시작
|
|
|
|
```bash
|
|
npm install
|
|
npx tsx src/index.ts --help # 실행
|
|
npx tsx src/index.ts init # 볼트 초기화
|
|
npx tsx src/index.ts sync # 전체 동기화
|
|
```
|
|
|
|
## 아키텍처
|
|
|
|
```
|
|
src/
|
|
├── index.ts # CLI 진입점 (commander)
|
|
├── mcp-server.ts # MCP 서버 (stdio)
|
|
├── types.ts # 공통 타입
|
|
├── config.ts # 설정 로드 (JSON)
|
|
├── errors.ts # 커스텀 에러
|
|
├── utils.ts # 유틸
|
|
├── db/
|
|
│ ├── database.ts # SQLite 연결 + 마이그레이션
|
|
│ ├── items.ts # items CRUD + FTS5 검색
|
|
│ └── kg.ts # Knowledge Graph
|
|
├── sources/
|
|
│ ├── adapter.ts # SourceAdapter 인터페이스
|
|
│ ├── mempalace.ts # MemPalace 연동 (선택)
|
|
│ └── manual.ts # 직접 추가
|
|
├── vault/
|
|
│ ├── init.ts # 볼트 디렉토리 + SCHEMA.md 생성
|
|
│ ├── render.ts # 아이템 → 마크다운 렌더링
|
|
│ ├── index.ts # index.md 갱신
|
|
│ └── log.ts # log.md 갱신
|
|
├── wiki/
|
|
│ ├── generator.ts # 위키 생성 오케스트레이터
|
|
│ ├── llm.ts # z.ai API 클라이언트 (OpenAI 호환)
|
|
│ └── prompts.ts # 시스템 프롬프트
|
|
├── sync/
|
|
│ ├── git.ts # git pull/push (simple-git)
|
|
│ └── pipeline.ts # 전체 sync 파이프라인
|
|
└── cli/
|
|
└── commands.ts # CLI 명령어 정의
|
|
```
|
|
|
|
## 핵심 규칙
|
|
|
|
### 코딩 규칙
|
|
- TypeScript strict mode, ES2022 target, Node16 module resolution
|
|
- 모든 함수와 클래스에 JSDoc 주석
|
|
- 에러는 커스텀 에러 클래스로 래핑 (src/errors.ts)
|
|
- async 함수는 항상 try/catch로 감싸기
|
|
- 파일 경로는 항상 path.join() / path.resolve() 사용
|
|
|
|
### 볼트 규칙
|
|
- raw/ 아래 파일은 **절대 수정하지 않음** (불변)
|
|
- 모든 마크다운은 YAML frontmatter 포함
|
|
- Obsidian 호환: 백링크 `[[]]`, frontmatter `---`
|
|
- 한국어 본문, 코드/경로는 영어 원문 유지
|
|
|
|
### MemPalace 연동 (선택)
|
|
- `mempalace.enabled: true` + 경로 존재 시에만 활성화
|
|
- 없으면 자체 SQLite DB로 동작
|
|
- ChromaDB 직접 접근하지 않음 (Python 스크립트나 MCP 경유)
|
|
|
|
### Git
|
|
- 커밋 메시지: `type: description` (conventional commits)
|
|
- 볼트 변경 후 항상 index.md 갱신
|
|
|
|
## 의존성
|
|
|
|
| 패키지 | 용도 |
|
|
|--------|------|
|
|
| commander | CLI 프레임워크 |
|
|
| gray-matter | YAML frontmatter 파싱 |
|
|
| better-sqlite3 | 자체 DB + MemPalace DB 읽기 |
|
|
| simple-git | Git 조작 |
|
|
| chalk | 터미널 색상 |
|
|
| ora | 스피너 |
|
|
| @modelcontextprotocol/sdk | MCP 서버 |
|
|
| zod | MCP 툴 스키마 |
|
|
|
|
## MCP 툴
|
|
|
|
| 툴 | 설명 |
|
|
|----|------|
|
|
| `hw_status` | 볼트 + DB 통계 |
|
|
| `hw_ingest` | 소스 → raw/ 수집 (MemPalace + 기타) |
|
|
| `hw_add` | 아이템 직접 추가 |
|
|
| `hw_search` | FTS5 키워드 검색 |
|
|
| `hw_generate` | raw/ → wiki/ LLM 생성 |
|
|
| `hw_sync` | 전체 파이프라인 |
|
|
| `hw_read` | vault 내 파일 읽기 |
|
|
| `hw_lint` | 정합성 검사 |
|
|
| `hw_graph` | KG 쿼리 |
|
|
|
|
## 설정
|
|
|
|
기본 경로: `~/.habraid/data/config.json`
|
|
레거시 fallback: `~/.config/habraid/config.json`
|
|
|
|
## 상세 문서
|
|
|
|
- `docs/architecture.md` — 전체 아키텍처 설계
|
|
- `docs/vault-schema.md` — 볼트 디렉토리/파일 스키마
|
|
- `docs/wiki-generation.md` — 위키 생성 프롬프트 전략
|
|
- `docs/config-reference.md` — 설정 파일 레퍼런스
|
|
- `PLAN.md` — v1 기획서
|
|
- `PLAN-v2.md` — v2 독립 아키텍처 기획서
|