HaBraid/AGENTS.md

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로 완전 동작.

빠른 시작

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 독립 아키텍처 기획서