HaBraid/docs/architecture.md

아키텍처 설계

핵심 철학

HaBraid는 memory backend 자체가 아니라 기억 시각화 계층이다.

• source of truth: MemPalace / mem0 / future memory backends
• expression layer: HaBraid wiki
• consumer: 사람 + AI

즉 HaBraid는 장기 기억을 사람이 읽기 좋고 AI가 다시 활용하기 좋은 위키 표현층으로 재구성한다.

데이터 흐름

memory backend (MemPalace / mem0 / future backends)
        │
        ▼ read-only / adapters
    ┌──────────┐
    │  ingest   │ source → raw/ + DB items
    └────┬─────┘
         │
         ▼
    ┌──────────┐
    │  wiki     │ items/raw → wiki/ (host-following LLM)
    └────┬─────┘
         │
         ▼
    ┌──────────┐
    │  sync     │ index/log/state + optional git sync
    └──────────┘

LLM 실행 계층

prompt builder
   ↓
LLM gateway
   ├─ host mode (default)
   │    └─ host가 실제 모델/정책 선택
   └─ standalone / fallback
        └─ openai | zai | ollama 직접 호출

원칙:

• HaBraid는 모델 선택보다 prompt orchestration에 집중한다.
• 가능하면 host가 실제 inference를 담당한다.
• host unavailable이면 configured fallback을 사용한다.

모듈 의존성

cli/commands.ts
    ├── sync/pipeline.ts
    │     ├── sync/git.ts
    │     ├── mempalace/ingest.ts
    │     │     └── mempalace/reader.ts
    │     └── wiki/generator.ts
    │           ├── wiki/llm.ts
    │           └── wiki/prompts.ts
    ├── vault/init.ts
    ├── vault/render.ts
    ├── vault/index.ts
    └── config.ts → types.ts

에러 처리

모든 모듈은 WikiEngineError 기반 커스텀 에러 사용.

대표 코드:

• VAULT_INIT_FAILED
• DB_READ_FAILED
• LLM_CALL_FAILED
• GIT_SYNC_FAILED
• LINT_FAILED
• CONFIG_LOAD_FAILED

동시성

• ingest: 순차 처리
• wiki generation: 순차 처리 (배치 단위)
• git sync: 순차 처리

현재 알려진 분리 이슈

• direct MemPalace ingest는 아직 Chroma schema mismatch 문제가 남아 있다.
• host-following LLM 전환은 이 ingest 버그와 별도 change set으로 유지한다.