긴 AI 답변과 웹 리서치 산출물을 브라우저에서 독립적으로 읽히는 HTML evidence card로 보관하고, 출처·근거 관계를 그래프로 탐색하는 local-first 지식관리 앱.
이 리포지토리는 Phase 1 샘플 vault 검증과 Phase 2 CLI core까지의 결과물입니다.
| Phase | 상태 | 산출물 |
|---|---|---|
| Phase 0. 제품 wedge 고정 | ✅ | docs/implementation-plan-v0.3.html |
| Phase 1. 샘플 vault + 결정 게이트 | ✅ (G1/G2-Q1/G2-Q2 통과, G2-Q3 보류) | sample-vault/ |
| Phase 2. CLI core (init/list/validate) | ✅ | cli/ |
| Phase 2 follow-up (create/graph/backup) | ⏳ | — |
| Phase 3+ | ⏳ | — |
| 질문 | 상태 | 근거 |
|---|---|---|
| Q1. 주장의 근거 출처 3개? | pass | google-drive-later 노드의 outgoing cites = 3 |
| Q2. 출처를 인용한 다른 리포트? | pass | source-obsidian-vault-types 노드의 incoming cites = 2 |
| Q3. 서로 모순되는 주장 쌍? | hold | 샘플 데이터셋에 진짜 AI 의견 충돌 없음. Phase 1 종료 전 1쌍 추가 필요 |
외부 리뷰에서 발견한 정합성 문제 4개를 수정했습니다.
- edge type 분리: 기술적 의존성을
contradicts에서 분리해risks로 신설. AI 산출물이 product 문서의 방향을 형성한 관계는supports에서 분리해informs로 신설. - G2-Q3 보류 명시: 진짜 모순 케이스 부족을 hold 상태로 기록. 그래프 모델은 그대로 유지.
- Reader mockup 정합성: Layer 4(출처)를 main column에 추가. Claim 5에 대응하는 Evidence 5 추가. TL;DR을 본문 주제와 정렬.
- non-5-layer 콘텐츠 정책:
argument,walkthrough,comparison,decision-tree,note5개 card type을 정의. 각 type별 필수/선택 layer를 명시.
HTMLvault/
├── README.md # 이 파일
├── docs/
│ └── implementation-plan-v0.3.html # 전체 Phase 계획 v0.3
├── sample-vault/ # Phase 1 검증용 vault (v0.3.1)
│ ├── README.md # vault 가이드
│ ├── manifest.json # 백업 무결성 manifest (42 files, sha256)
│ ├── notes/ # HTML evidence card 11개
│ ├── meta/ # 대응 metadata JSON 11개
│ ├── index/
│ │ ├── graph.json # 노드 11 + 엣지 16
│ │ ├── manual-graph-sketch.html # G2 검증 시각화
│ │ └── search_stub.json # Phase 4 search index 스텁
│ ├── prototypes/
│ │ └── reader-view-mockup.html # G1 검증 reader UI
│ ├── docs/ # 결정 기준, 체크리스트
│ ├── decisions/ # ADR-004~007
│ ├── assets/ # 이미지/첨부 빈 폴더
│ ├── backups/ # zip 백업 저장 위치
│ └── .hkv/ # 앱 설정, 워크스페이스, 템플릿
└── cli/ # Phase 2 CLI core
├── bin/hkv # 실행 launcher
├── src/
│ ├── index.ts # arg parser + dispatcher
│ ├── lib/{vault,html,types}.ts # vault/HTML/타입 유틸
│ └── commands/{init,list,validate}.ts # 명령어 구현
├── package.json
└── tsconfig.json
요구사항: Node 22.6.0+ (TypeScript 소스를 --experimental-strip-types로 직접 실행).
cd cli
npm install # dev deps만 설치 (typescript, @types/node). 런타임 의존성 없음.
# 새 vault 만들기
./bin/hkv init ~/my-vault
# 문서 목록
./bin/hkv list ../sample-vault
./bin/hkv list ../sample-vault --format json
./bin/hkv list ../sample-vault --format ids
# 검증 (HTML 구조, link, graph, manifest hash)
./bin/hkv validate ../sample-vault
./bin/hkv validate ../sample-vault --no-manifest| 명령어 | Phase 2 상태 | 설명 |
|---|---|---|
init |
✅ | vault 폴더 구조 + 기본 config + 빈 graph 생성 |
list |
✅ | notes/ + meta/ 결합해서 카드 목록 출력 (table/json/ids) |
validate |
✅ | HTML data-hkv-id, 깨진 링크, orphan meta, graph 정합성, manifest sha256 |
create |
⏳ | Phase 2 follow-up |
graph |
⏳ | Phase 2 follow-up (graph.json 자동 갱신) |
backup |
⏳ | Phase 2 follow-up (zip + manifest 생성) |
META_MISSING(error): HTML은 있는데 JSON이 없음ORPHAN_META(warning): JSON은 있는데 HTML이 없음ID_MISMATCH(error):data-hkv-id와 파일명 불일치META_ID_MISMATCH(error): meta.id와 파일명 불일치HTML_NO_ARTICLE(warning):<article>루트 누락HTML_NO_DATA_HKV_ID(warning):data-hkv-id속성 누락BROKEN_LINK(warning): notes 안의 상대 링크가 존재하지 않는 파일 가리킴EDGE_BAD_TYPE/EDGE_BAD_SOURCE/EDGE_BAD_TARGET(error): graph 정합성EDGE_NO_REASON(warning): edge.reason 비어 있음GRAPH_MISSING_NODE(info): note는 있는데 graph 노드 없음GRAPH_DANGLING_NODE(warning): graph 노드는 있는데 note 파일 없음MANIFEST_HASH_MISMATCH(error): manifest의 sha256과 실제 파일 hash 불일치MANIFEST_FILE_MISSING(error): manifest에 있는데 disk에 없음MANIFEST_OK(info): 모든 파일 hash 일치
종료 코드: error 있으면 1, 없으면 0.
- G2-Q3 보류 해소: ChatGPT/Claude/타 AI가 같은 주제에 다른 결론을 낸 실제 사례 1쌍을 샘플에 추가하고
contradictsedge 1개로 모델링. - Phase 2 follow-up:
create,graph,backup명령어 구현. - Phase 3: Tauri 데스크톱 UI에 reader view + 검색/백링크 우선 통합.
- 전체 Phase 계획:
docs/implementation-plan-v0.3.html - Reader UX 정의 + non-5-layer 정책:
sample-vault/docs/reader-ux-definition.md - Graph 검증 질문:
sample-vault/docs/graph-value-test-questions.md - ADR:
sample-vault/decisions/ADR-004 ~ ADR-007
HTML Knowledge Vault (HKV) is a local-first knowledge management prototype for preserving long AI answers, research notes, and source-backed conclusions as browser-readable HTML evidence cards. It is designed for people who need durable research memory: AI automation builders, developers, analysts, writers, and product researchers who want AI outputs to remain inspectable after a chat session ends.
HKV solves a specific problem: long AI and web research answers are easy to lose, hard to re-read, and often disconnected from their supporting sources. HKV stores each note as portable HTML, pairs it with JSON metadata, and uses a document-level claim/source graph so a reader can move from a conclusion to its evidence and related decisions.
Current repository status: this is not a finished desktop app or hosted SaaS. The repository currently contains a Phase 1 sample vault and a Phase 2 CLI core. The CLI can initialize vault folders, list cards, and validate the sample vault structure, links, graph references, and manifest hashes. Planned but not yet implemented commands include create, graph, backup, and restore; the Tauri desktop UI is also future work.
What is verifiable now:
sample-vault/contains HTML evidence cards, metadata JSON, a graph sketch, a reader-view mockup, ADRs, and a manifest.cli/contains the@hkv/clipackage withinit,list, andvalidatecommands.- Validation can check HTML card IDs, metadata pairing, local links, graph edge consistency, and manifest SHA-256 hashes.
Reproducible validation commands:
cd cli
npm ci
npm run typecheck
npx -y node@22 --experimental-strip-types --no-warnings src/index.ts validate ../sample-vault
npx -y node@22 --experimental-strip-types --no-warnings src/index.ts list ../sample-vault --format jsonPublic documentation entry points:
- AI crawler summary:
llms.txtanddocs/llms.txt - FAQ:
docs/faq.md - Demo scenario:
docs/demo-scenario.md - Portfolio summary:
docs/portfolio.md - Static Pages landing page:
docs/index.html