HaBraid/docs/plans/PLAN-v2.md

PLAN: habraid 독립 아키텍처

User 승인 후 진행

목표

habraid를 MemPalace 없이도 완전 동작하는 독립 위키 엔진으로 만든다. MemPalace가 있으면 추가 데이터 소스로 활용하고, 없으면 자체 기능으로 동작한다.

현재 상태

• MemPalace ChromaDB에서만 데이터 읽음 (의존적)
• 검색 기능 없음 (MemPalace에 위임)
• KG 없음
• 세션 수집 없음
• LLM 위키 생성만 가능

변경 아키텍처

┌─────────────────────────────────────────────────┐
│                 habraid                    │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ Sources  │  │  Core DB │  │   Wiki Gen    │  │
│  │          │  │ (SQLite) │  │   (LLM)       │  │
│  │ • CLI    │  │          │  │               │  │
│  │ • MCP    │  │ • items  │  │ • Incremental │  │
│  │ • File   │  │ • KG     │  │ • Batch       │  │
│  │ • MemPal │  │ • Search │  │ • Fallback    │  │
│  └──────────┘  └──────────┘  └───────────────┘  │
│                                                  │
│  ┌──────────────────────────────────────────────┐│
│  │              Vault (Obsidian)                ││
│  │  raw/  →  wiki/  →  index.md + overview.md  ││
│  └──────────────────────────────────────────────┘│
└─────────────────────────────────────────────────┘

Phase 1: 자체 DB + 아이템 관리 (핵심)

1.1 자체 SQLite DB 생성

경로: ~/.local/share/habraid/habraid.db

테이블:

-- 모든 지식 아이템 (drawer의 일반화)
CREATE TABLE items (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  content TEXT NOT NULL,
  source TEXT NOT NULL DEFAULT 'manual',  -- manual, mempalace, cli, file, session
  category TEXT,                           -- projects, topics, decisions, people, infrastructure, guides
  tags TEXT,                               -- JSON array
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  metadata TEXT                            -- JSON blob for source-specific data
);

-- FTS5 전문 검색
CREATE VIRTUAL TABLE items_fts USING fts5(title, content, tags, content=items, content_rowid=rowid);

-- 자동 동기화 트리거
CREATE TRIGGER items_ai AFTER INSERT ON items BEGIN
  INSERT INTO items_fts(rowid, title, content, tags) VALUES (new.rowid, new.title, new.content, new.tags);
END;
CREATE TRIGGER items_ad AFTER DELETE ON items BEGIN
  INSERT INTO items_fts(items_fts, rowid, title, content, tags) VALUES('delete', old.rowid, old.title, old.content, old.tags);
END;
CREATE TRIGGER items_au AFTER UPDATE ON items BEGIN
  INSERT INTO items_fts(items_fts, rowid, title, content, tags) VALUES('delete', old.rowid, old.title, old.content, old.tags);
  INSERT INTO items_fts(rowid, title, content, tags) VALUES (new.rowid, new.title, new.content, new.tags);
END;

1.2 MemPalace 어댑터 (선택)

// src/sources/mempalace.ts
interface SourceAdapter {
  name: string;
  isAvailable(): boolean;  // DB 파일 존재 여부
  fetchItems(since?: Date): Promise<Item[]>;
}

class MemPalaceSource implements SourceAdapter {
  isAvailable(): boolean {
    return existsSync(this.config.mempalace?.path + '/chroma.sqlite3');
  }
  
  async fetchItems(since?: Date): Promise<Item[]> {
    if (!this.isAvailable()) return [];
    // ChromaDB에서 drawer 읽기 → Item으로 변환
  }
}

1.3 MCP 툴 업데이트

기존 7개 + 새 툴:

툴	변경
hw_status	이름 변경 + 자체 DB 통계
hw_ingest	MemPalace + 다른 소스 통합
hw_add	신규 — 아이템 직접 추가
hw_search	신규 — FTS5 검색 (MemPalace 없이도 동작)
hw_generate	기존
hw_sync	기존
hw_read	기존
hw_lint	기존
hw_graph	신규 — KG 쿼리

hw_ prefix로 다른 MCP 툴이랑 충돌 방지

Phase 2: Knowledge Graph (선택)

자체 SQLite KG. MemPalace KG 있으면 참고, 없으면 자체.

CREATE TABLE kg_entities (
  id INTEGER PRIMARY KEY,
  name TEXT UNIQUE NOT NULL,
  type TEXT NOT NULL  -- person, project, technology, concept, server
);

CREATE TABLE kg_relations (
  id INTEGER PRIMARY KEY,
  subject_id INTEGER REFERENCES kg_entities(id),
  predicate TEXT NOT NULL,
  object_id INTEGER REFERENCES kg_entities(id),
  valid_from TEXT,
  valid_to TEXT,
  created_at TEXT NOT NULL
);

Phase 3: 세션 수집 (선택, seCall 기능)

나중에 Claude Code, Codex CLI 세션 로그를 직접 수집하는 기능. 지금은 Phase 1만 진행.

파일 구조 변경

src/
├── index.ts           # CLI
├── mcp-server.ts      # MCP 서버
├── config.ts          # 설정
├── types.ts           # 타입
├── errors.ts          # 에러
├── utils.ts           # 유틸
├── db/
│   ├── database.ts    # SQLite 연결 + 마이그레이션
│   ├── items.ts       # items CRUD + FTS5
│   └── kg.ts          # Knowledge Graph (Phase 2)
├── sources/
│   ├── adapter.ts     # SourceAdapter 인터페이스
│   ├── mempalace.ts   # MemPalace 연동 (선택)
│   ├── manual.ts      # 직접 추가
│   └── file.ts        # 파일 임포트 (향후)
├── vault/
│   ├── init.ts
│   ├── render.ts
│   ├── index.ts
│   └── log.ts
├── wiki/
│   ├── generator.ts
│   ├── llm.ts
│   └── prompts.ts
├── sync/
│   ├── git.ts
│   └── pipeline.ts
└── cli/
    └── commands.ts

설정 파일

~/.config/habraid/config.json

{
  "vault": { "path": "~/wiki", "branch": "main" },
  "db": { "path": "~/.local/share/habraid/habraid.db" },
  "mempalace": {
    "enabled": true,
    "path": "~/.mempalace/palace"
  },
  "llm": {
    "provider": "zai",
    "model": "glm-5.1",
    "api_url": "https://api.example.com/v1",
    "api_key_env": "GLM_API_KEY",
    "max_tokens": 4096
  },
  "sync": { "timezone": "Asia/Seoul" }
}

• mempalace.enabled: false → MemPalace 완전 무시
• mempalace.enabled: true + 경로 없음 → 자동으로 비활성화
• mempalace.enabled: true + 경로 있음 → 연동

작업 순서

1. db/ 모듈 작성 — SQLite 스키마, items CRUD, FTS5
2. sources/ 어댑터 작성 — SourceAdapter 인터페이스 + MemPalace 어댑터 + Manual 어댑터
3. MCP 핸들러 업데이트 — 기존 핸들러를 DB 기반으로 전환 + 새 툴 추가
4. ingest 재작성 — DB에서 raw/ 생성 (MemPalace 없이도 동작)
5. 검색 구현 — hw_search (FTS5)
6. 테스트 — MemPalace 있을 때 / 없을 때 모두
7. CLI 업데이트 — 새 명령어 반영

완료 기준

• MemPalace 없이 hw_add + hw_search + hw_generate 동작
• MemPalace 있을 때 자동 감지 + 연동
• 기존 raw/ 503개 데이터 마이그레이션
• MCP 9개 툴 모두 정상