๐ English | ํ๊ตญ์ด
facts + logic โ ๋งํฌ๋ค์ด ์์ค๋ฅผ **๊ฒ์ฆ ๊ฐ๋ฅํ๊ณ ์ถ์ฒ๋ก ๋ท๋ฐ์นจ๋๋ ์ฌ์ค(fact)**๋ก ๋ฐ๊ฟ ์ฃผ๋ Claude Code ์คํฌ์ ๋๋ค. LLM์ด ์ถ์ถํ๊ณ , ๊ฒฐ์ ๋ก ์ Datalog/wirelog ์์ง์ด ๊ฒ์ฆํฉ๋๋ค.
factlog๋ ๋งํฌ๋ค์ด ์ง์๋ฒ ์ด์ค(knowledge base)๋ฅผ ์ ์งํ๊ฒ ์ ์งํ๊ธฐ ์ํ Claude Code ์คํฌ์ ๋๋ค. ๋จ ํ๋์ ์์น์ ๋ฐ๋ฆ ๋๋ค.
์์ด์ ํธ๋ ๊ฒฐ๋ก ์ ๋ด๋ฆฌ์ง ์๋๋ค. ์์ด์ ํธ๋ ํ์ผ์ ๋ง๋ค๊ณ CLI๋ฅผ ํธ์ถํ๋ค. CLI๊ฐ ๊ฒ์ฆ ๊ฐ๋ฅํ ๋ฆฌํฌํธ๋ฅผ ๋๋ ค์ค๋ค.
- LLM(์ธ์
๋ด์ Claude)์ด ์ถ์ถํฉ๋๋ค โ
sources/์์ ํ๋ณด ์ฌ์ค์ ๋ฝ์๋ด๊ณ , ์์ฐ์ด ์ง๋ฌธ์ผ๋ก๋ถํฐ Datalog ์ฟผ๋ฆฌ ์ด์์ ์์ฑํ๋ฉฐ, ์ ํ๋ ๋ฒ์์ ์๊ธฐ ๊ต์ ์ ์๋ํฉ๋๋ค. - ๊ฒฐ์ ๋ก ์ ์์ง(pyrewire ๊ธฐ๋ฐ
wirelog)์ด ๊ฒ์ฆํฉ๋๋ค โ ํ์ ๋ ์ฌ์ค์ ์ปดํ์ผํ๊ณ , ๋ก์ง ์ฒดํฌ๋ฅผ ์คํํ๋ฉฐ,
์ ์ฑ
์๋ฐยท๋ชจ์ยท
review_requiredํญ๋ชฉ์ ๋๋ฌ๋ ๋๋ค.
๋ชจ๋ธ์ด ๋ง๋ค์ด ๋ธ ๊ฒ์ ๋ฌด์์ด๋ ์์ง๊ณผ ์ฌ๋์ด ํ์ธํ๊ธฐ ์ ๊น์ง๋ ํ๋ณด(candidate) ์ผ ๋ฟ์ ๋๋ค.
ํ ์คํธ ๋ฒ์
sources/ โ Claude extracts โ facts/candidates.csv, pages/, decisions/
candidates โ human review โ confirmed facts
confirmed โ compile (deterministic) โ facts/accepted.dl
questions โ Claude drafts query โ facts/query.dl
accepted + query โ wirelog logic check โ facts/logic_report.txt โ ๊ฒ์ฆ ๊ฐ๋ฅํ ๋ฆฌํฌํธ
review_required โ Claude repairs (gated) โ decisions/correction_trace.md
/factlog sync ๋ sources/ ์๋์ ๊ฐ ํ์ผ์ ์ธ์
๋ด์์ ํ
์คํธ๋ก ์ฝ์ด
์ฌ์ค์ ์ถ์ถํฉ๋๋ค. ๋ด์ฅ ์์ง(merge_candidates.py)์ ๋ชจ๋ ํ์ผ์ ์์ค ๊ฒฝ๋ก๋ก
์ถ์ ํ์ง๋ง ๋ด์ฉ์ ๊ฒฐ์ฝ ํ์ฑํ์ง ์์ต๋๋ค โ ๋ฐ๋ผ์ ์ถ์ถ ๊ณผ์ ์์ ํ
์คํธ๋ฅผ ์ฝ์ด๋ผ ์
์๋ ํ์ผ๋ง ์ ์ฌ๋ฉ๋๋ค. ๊ทธ๋ฌ๋ฏ๋ก ๋ฐ์ด๋๋ฆฌ ์๋ณธ(์: .docx)์ ๊ทธ ์์ฒด๋ง์ผ๋ก๋
์ฌ์ค์ ๋ง๋ค์ด ๋ด์ง ๋ชปํฉ๋๋ค.
| ํ์ | ์ํ | ๋น๊ณ |
|---|---|---|
.md, .markdown, .txt |
์ง์ ์ง์ | UTF-8 ํ ์คํธ, ์๋ ๊ทธ๋๋ก ์ฝ์. ๋ชจ๋ ์ถ์ถ ๊ธฐ์ค์ด ์ ์ ํ๋ ํ์์ ๋๋ค. |
๊ทธ ๋ฐ์ UTF-8 ํ
์คํธ (.rst, .org, .csv, ์์ค ์ฝ๋) |
ํ๋ฌธ์ผ๋ก ์ง์ | ๋ณ๋ ํ์ฑ ์์ด ์์ ํ ์คํธ๋ก ์ทจ๊ธ. |
.docx, ๋ฐ์ด๋๋ฆฌ .pdf, .odt, .epub, .html, .rtf |
์๋ ๋ณํ | factlog ingest ๊ฐ pandoc / textutil / pdftotext ๋ก ํ
์คํธ ๋ณํ. |
.hwpx (ํ์ปด OWPML) |
์๋ ๋ณํ | ๋ด์ฅ ์ถ์ถ๊ธฐ(์ธ๋ถ ๋๊ตฌ ๋ถํ์) โ zip ๋ด๋ถ Contents/section*.xml ํ
์คํธ๋ฅผ ์ฝ์. |
.hwp (๊ตฌํ ํ์ปด, HWP 5.x) |
์๋ ๋ณํ | hwp5html(pyhwp) โ pandoc โ markdown ๊ฒฝ๋ก, ํ ๋ณด์กด. pip install pyhwp + pandoc ํ์. ์์ผ๋ฉด ์๋ด ๋ฉ์์ง์ ํจ๊ป ๋ณด๊ณ . |
.pptx (PowerPoint) |
์๋ ๋ณํ | ๋ด์ฅ ์ถ์ถ๊ธฐ(์ธ๋ถ ๋๊ตฌ ๋ถํ์) โ zip ๋ด๋ถ ppt/slides/slideN.xml ์ ์ฌ๋ผ์ด๋ ํ
์คํธ๋ฅผ ์์๋๋ก ์ฝ๊ณ , ์ฌ๋ผ์ด๋๋น ํ ๋ธ๋ก์ผ๋ก ๋ณํ. ๋ฐํ์ ๋
ธํธ๋ ์ ์ธ, ํ ์
์ ์
๋น ํ ์ค๋ก ํผ์ณ์ง(ํ/์ด ๊ทธ๋ฃน ๊ตฌ์กฐ๋ ๋ณด์กด ์ ๋จ). |
.xlsx, ์ด๋ฏธ์ง |
๋ณํ ์ ๋จ | ๋ด์ฅ ๋ณํ๊ธฐ ์์ โ ์๋ด ๋ฉ์์ง์ ํจ๊ป ๋ณด๊ณ . ์๋ ๋ณํ ํ์. |
factlog ingest ๋ ๋ณํ๋ ํ
์คํธ๋ฅผ KB์ runs/sources/ ๋๋ ํฐ๋ฆฌ(๋ค๋ฅธ ์์ฑ
๋ฐ ์ํฐํฉํธ์ ๊ฐ์ ์์น)์ ๊ธฐ๋กํฉ๋๋ค โ ์ฌ์ฉ์์ ์๋ณธ์ด ๊ทธ๋๋ก ๋จ์ ์์ด์ผ ํ๋
sources/ ์๋ ๊ฒฐ์ฝ ์ฐ์ง ์์ต๋๋ค. ํ์ ๋๋ ํฐ๋ฆฌ์ ์๋ ์๋ณธ์ ๊ทธ ํ์
๊ตฌ์กฐ๋ฅผ ๊ทธ๋๋ก ๋ฏธ๋ฌ๋งํ๋ฏ๋ก(sources/sub/report.pdf โ runs/sources/sub/report.md),
์๋ก ๋ค๋ฅธ ํด๋์ ๋์ผ ์ด๋ฆ ํ์ผ์ด ์ถฉ๋ํ์ง ์์ต๋๋ค. ์๋ณธ์ ์๋์ง ์์ผ๋ฉฐ,
๋ณํ๋ณธ์๋ ์ถ์ฒ(provenance) ํค๋(์์ค, ๋ณํ๊ธฐ, ๋ ์ง)๊ฐ ๋ถ์ต๋๋ค. sources/ ์
runs/sources/ ๋ชจ๋ ์ถ์ถ์ด ์ฝ๋ ์ ํจํ ์์ค ๋ฃจํธ์
๋๋ค.
์ ๊ทธ๋ ์ด๋ ์๋ด: ํ์ ๋๋ ํฐ๋ฆฌ ๋ฏธ๋ฌ๋ง์ ๊ธฐ์กด์ ํ๋ฉด(flat) ๋ ์ด์์๋ณด๋ค ๋์ค์ ๋์ ๋์์ต๋๋ค. ์ด์ ์ ์ ์ฌ๋ KB๋ ์ค์ฒฉ ์๋ณธ์ ๋ํด ํ๋ฉด ๋ณํ๋ณธ (
runs/sources/report.md)์ ๊ฐ์ง๊ณ ์๋๋ฐ, ์ด๋ ๋ ์ด์ ์ง์ด ๋ง์ง ์์ผ๋ฏ๋ก ์ค์ฒฉ ๋ฐ์ด๋๋ฆฌ๊ฐ ์ปค๋ฒ๋ฆฌ์ง/factlog sources๋๋ฝ์ผ๋ก ๋ค์ ๋ํ๋ ์ ์์ต๋๋ค.factlog ingest --scan --force๋ฅผ ๋ค์ ์คํํด ๋ณํ๋ณธ์ ๋ฏธ๋ฌ๋ง๋ ๊ฒฝ๋ก๋ก ์ฎ๊ธฐ์ญ์์ค(์ดํ ๋จ์ ํ๋ฉด ๋ณํ๋ณธ์ ์ญ์ ). ์ต์์(๋น์ค์ฒฉ) ์์ค๋ ์ํฅ๋ฐ์ง ์์ต๋๋ค.
factlog ingest report.docx --target ~/wiki # โ ~/wiki/runs/sources/report.md (pandoc)
factlog ingest --scan --target ~/wiki # auto-convert every binary under sources/factlog init/setup(๋๋ factlog use <kb>) ์ดํ, ์ ํํ KB๊ฐ ํ์ฑ KB๋ก
๊ธฐ๋ก๋ฉ๋๋ค. ๊ทธ๋์ ingest/ask/sync ๋ฐ ๋๊ตฌ๋ค์ด ์ด๋ ์์
๋๋ ํฐ๋ฆฌ์์๋
๊ทธ KB๋ฅผ ๋์์ผ๋ก ๋์ํฉ๋๋ค โ --target/--wiki ๊ฐ ํ์ ์์ต๋๋ค.
factlog use ~/wiki # make ~/wiki the active KB (recorded in config)
factlog where # show the active KB and how it was resolved
factlog sources # list registered sources (original, conversion, fact count)
factlog status # KB state: facts by status, vocabulary, conflicts, logic freshness, engine
cd /anywhere && factlog ingest report.pdf # โ ~/wiki/runs/sources/report.txt
factlog eject report.pdf # inverse of ingest: remove the conversion + retire its facts
factlog ignore drafts/*.md # exclude sources from sync (re-extraction)
factlog provenance Acme uses FastAPI # trace a fact to its source(s)ask ์ provenance ๋ ์ ํํ ์ํฐํฐ/๊ด๊ณ ์ด๋ฆ์ ํ์๋ก ํฉ๋๋ค. factlog vocab
์ ์ด๋ฅผ ๋์ดํฉ๋๋ค โ ์ฌ์ฉ ํ์์ ํจ๊ป ์ํฐํฐ ์ด๋ฆ๊ณผ ๊ด๊ณ ์ด๋ฆ์ ๋ณด์ฌ ์ฃผ๋ฏ๋ก
๋ฌด์์ ์ง์ํ ์ ์๋์ง ์ ์ ์์ต๋๋ค.
factlog vocab # entities + relations (engine facts)
factlog vocab --entities # just entities
factlog vocab --relations # just relations (tagged [attribute] / [single-valued] / [typed:<type>])
factlog vocab --all # include non-engine names (candidate/needs_review/superseded)์ ์ธ๋ ์์ฑ(attribute) ๊ด๊ณ์ ๊ฐ์ฒด๋ ์ํฐํฐ๊ฐ ์๋๋ผ ๋ฆฌํฐ๋ด์ด๋ฏ๋ก ์ํฐํฐ ๋ชฉ๋ก์์
์ ์ธ๋ฉ๋๋ค(status ์ ๋์ผํ ํ์ดํ).
์ด๋ค ๊ด๊ณ์ ๋ฆฌํฐ๋ด ๊ฐ์ฒด๋ ๋จ์ ๋งค์นญ์ด ์๋๋ผ ๋น๊ต๋์ด์ผ ํฉ๋๋ค โ ๊ทธ๋์ผ
๊ฒฐ์ ๋ก ์ ์์ง์ด ๊ทธ ๊ฐ์ ์ ๋ ฌ(ordering)ํ๊ฑฐ๋ ์๊ณ๊ฐ(threshold)์ผ๋ก ๊ฑฐ๋ฅด๊ฑฐ๋
๋ฒ์(range)๋ก ์ง์ํ ์ ์์ต๋๋ค(์: "2030๋
์ดํ ์ถ์", "์์ <= 3"). ๊ทธ๋ฐ
๊ด๊ณ๋ policy/typed-relations.md ์ ์ ์ธํฉ๋๋ค. ๊ฐ์ฒด๊ฐ ๋ฆฌํฐ๋ด์ด๋ฏ๋ก ํด๋น ๊ด๊ณ๋
policy/attribute-relations.md ์๋ ํจ๊ป ์ ์ธํด์ผ ํฉ๋๋ค.
ํ ์ค์ ํ๋์ฉ ์ ์ธํฉ๋๋ค:
- `relation name` : <type> as <ascii_alias>
<ascii_alias> ๋ ๋น๊ต ๊ฐ๋ฅํ ๊ฐ์ ๋ด๋ ์์ง ์ฌ์ด๋ ๊ด๊ณ์ ์ด๋ฆ์ผ๋ก, ๊ด๊ณ ์ด๋ฆ์ด
๋นASCII ์ฌ๋ ํฉ๋ฒ์ ์ธ ์์ง ์๋ณ์๋ก ๋จ๋๋ก ์์ฑ์๊ฐ ์ง์ ๊ณ ๋ฅด๋ ASCII ์๋ณ์
([A-Za-z_][A-Za-z0-9_]*)์
๋๋ค. ๊ณต๋ฐฑ์ด ํฌํจ๋ ๊ด๊ณ ์ด๋ฆ์ ๋ฐฑํฑ์ผ๋ก ๊ฐ์๋๋ค.
๋ค ๊ฐ์ง ํ์ :
dateโ2030.1/2030-01-15โ ์ ๋ ฌ ๊ฐ๋ฅํ yyyymmdd. ์์ง ํฌ์ ์ง์ (์ ๋ ฌ/์๊ณ๊ฐ/๋ฒ์).ordinalโrank 3/3rdโ ์ ์ ์์. ์์ง ํฌ์ ์ง์.amountโ100์ต/1,000์โ ์ ์ ๊ธฐ๋ณธ ๋จ์. ์์ง ํฌ์ ์ง์. ๋จ์ ํ๊ฐ ํ์ํ๋ฉฐ, ์ค ๋์ ์ธ๋ผ์ธ์ผ๋ก ์ค ์ ์์ต๋๋ค:: amount as <alias> (์ต=1e8, ๋ง=1e4, ์=1)(๊ฐ์ ์์ ์ ์). ์ ์ ์๋ตํ๋ฉด ๊ธฐ๋ณธ ๋จ์ ํ๋ฅผ ์๋๋ค.numberโ1,000/3.5โ ์์น ํฌ๊ธฐ. ์์ง ํฌ์ ์ง์: ์ ๋ ฌ ๊ฐ๋ฅํ int64 ๋ก ร1000 ์ค์ผ์ผ๋ฉ๋๋ค(์์์ 3์๋ฆฌ).โ ๏ธ ๋น๊ต ์ ์ด์ ์๊ณ๊ฐ์ ๋ฐ๋์ ์ค์ผ์ผ๋ ๋จ์๋ก ์ ์ด์ผ ํฉ๋๋ค:version >= 2.0โversion_num(S, V), V >= 2000. ์์ 3์๋ฆฌ๋ฅผ ๋๋ ์ ๋ฐ๋๋ ๋ฐ์ฌ๋ฆผ๋ฉ๋๋ค(ROUND_HALF_UP).
์ถ์ถ๊ธฐ๋ ํ์
์ง์ ๋ฆฌํฐ๋ด ๊ฐ์ฒด๋ฅผ ๊ตฌ์กฐ๊ฐ ๋ณด์กด๋๋ compact compound term์ผ๋ก ์จ๋
๋ฉ๋๋ค: date(2030,1), date(2030,1,15), number(2.5), ordinal(3),
amount(100,"์ต"). relation/3 ์ ๊ฐ์ฒด๋ ์ด term ๋ฌธ์์ด์ ๊ทธ๋๋ก ๋ณด๊ดํ๊ณ ,
ํ์
์ง์ ์ฌ์ด๋ ๊ด๊ณ๊ฐ ๋น๊ต ๊ฐ๋ฅํ ์ค์นผ๋ผ๋ก ํฌ์ํฉ๋๋ค.
factlog vocab ์ ์ ์ธ๋ ํ์
์ง์ ๊ด๊ณ์ [typed:<type>] ํ๊ทธ๋ฅผ ๋ถ์ฌ ๋ณด์ฌ
์ค๋๋ค(์: [attribute, typed:date]).
์ ํํ ์ด๋ฆ์ ๋ชจ๋ฅผ ๋๋ factlog search <term> ์ด ์ฃผ์ด/๊ด๊ณ/๊ฐ์ฒด ์ ์ฒด์ ๋ํด
๋์๋ฌธ์ ๊ตฌ๋ถ ์๋ ๋ถ๋ถ ๋ฌธ์์ด ๋งค์นญ์ ์ํํ๊ณ , ์ผ์นํ๋ ์ฌ์ค์(์ํ์ ์ถ์ฒ ์์
ํจ๊ป) ๋์ดํฉ๋๋ค. vocab ์ ์ด๋ฆ์ ๋์ดํ๊ณ , search ๋ ์กฐ๊ฐ์ผ๋ก ์ฌ์ค์ ์ฐพ์ผ๋ฉฐ,
provenance ๋ ์ ํํ ํธ๋ฆฌํ์ ์ถ์ ํฉ๋๋ค.
factlog search fastapi # case-insensitive; matches 'FastAPI'
factlog search acme # partial โ every fact mentioning the fragment๋ชจ๋ ์ฌ์ค์ ์์ ์ด ์ถ์ถ๋ ์์ค๋ฅผ ๊ธฐ๋กํฉ๋๋ค. factlog provenance(๋ณ์นญ trace)
๋ ์ผ์นํ๋ ์ฌ์ค์ ๋ํด ๊ทธ ๊ทผ๊ฑฐ๊ฐ ๋๋ ๋ชจ๋ ํ์ ๋์ดํฉ๋๋ค โ ์์ค ๊ฒฝ๋ก, ์ํ,
์ ๋ขฐ๋, ๋
ธํธ(์ถ์ถ๋ ๋ฐ์ท๋ฌธ), ๊ทธ๋ฆฌ๊ณ ์์ค ํ์ผ์ด ๋์คํฌ์ ์์ ๋์ [stale]
ํ์๊น์ง. (superseded/needs_review ๋ฅผ ํฌํจํ) ๋ชจ๋ ์ํ๊ฐ ํ์๋๋ฏ๋ก,
ํ๊ธฐ๋ ๊ทผ๊ฑฐ๋ ๊ณ์ ๋ณด์
๋๋ค.
factlog provenance Acme uses FastAPI # exact triple
factlog provenance Acme uses # all objects for (subject, relation)
factlog provenance Acme # all facts about a subject
factlog provenance - uses # relation only ('-' wildcards a position)
factlog provenance - - FastAPI # object only์์น ์ธ์๋ (subject, relation, object) ์ ๋์ฌ์
๋๋ค. ๋ฆฌํฐ๋ด - ๋ ํด๋น ์์น๋ฅผ
์์ผ๋์นด๋ ์ฒ๋ฆฌํ๋ฉฐ, ์๋ต๋ ๋ค์ชฝ ์์น๋ ์์ผ๋์นด๋๋ก ์ทจ๊ธ๋ฉ๋๋ค(์์ผ๋์นด๋๊ฐ ์๋
ํญ๋ชฉ์ด ์ต์ ํ๋๋ ์์ด์ผ ํฉ๋๋ค). ๊ณต๋ฐฑ์ด ํฌํจ๋ ํญ๋ชฉ์ ๋ฐ์ดํ๋ก ๊ฐ์ธ์ญ์์ค.
/factlog ask ์ญ์ ๊ฒ์ฆ๋ ์์ง ๋ต๋ณ ์๋์ ๊ฐ ๊ทผ๊ฑฐ ์์ค ๊ฒฝ๋ก(โ <source>)๋ฅผ
๋์ดํ๋ฏ๋ก, ์ฟผ๋ฆฌ๋ก ์ฐพ์ ์ฌ์ค์ ๊ทธ ์๋ฆฌ์์ ์ถ์ ํ ์ ์์ต๋๋ค.
์ถ์ถ์ ์ฌ์ค์ candidate ๋๋ needs_review ๋ก ํ์ํ๋ฉฐ, confirmed/accepted
์ฌ์ค๋ง ์์ง ์
๋ ฅ์ด ๋ฉ๋๋ค. facts/candidates.csv ๋ฅผ ์ง์ ์๋์ง ์๊ณ ์น๊ฒฉํ๊ฑฐ๋
ํ๊ธฐํ ์ ์์ต๋๋ค.
factlog review # list the pending queue (candidate + needs_review)
factlog review --status needs_review # narrow to one pending status
factlog accept Acme uses FastAPI # pending โ accepted (compiled into accepted.dl)
factlog accept Acme # accept every pending fact about a subject ('-' wildcards a position)
factlog reject Acme uses Datadog # pending โ superseded (retired, kept for audit)
factlog accept Acme uses FastAPI --dry-runaccept/reject ๋ ๋๊ธฐ(pending) ํ๋ง ๋ณ๊ฒฝํฉ๋๋ค. confirmed/accepted/
superseded ์ ์ผ์นํ๋ ํญ๋ชฉ์ ๋ณด๊ณ ๋ง ๋๊ณ ๊ทธ๋๋ก ์ ์ง๋ฉ๋๋ค(๋๊ธฐ ์ํ๊ฐ ์๋
์ฌ์ค์ ํ๊ธฐํ๋ ค๋ฉด factlog eject ๋ฅผ ์ฌ์ฉ). ๋ ๋ค accepted.dl ์ ์ฌ์ปดํ์ผํฉ๋๋ค.
์ํ๊ฐ ์๋๋ผ ์ฌ์ค์ ๊ฐ ์์ฒด๋ฅผ ๊ต์ ํ๋ ค๋ฉด factlog amend ๋ฅผ ์ฌ์ฉํ์ญ์์ค.
factlog amend Widget codename Draft --set-object Falcon --set-note "name finalized" --accept
factlog amend Acme uses FastApi --set-object FastAPI # fix a typo์์น ํธ๋ฆฌํ์ด ์ฌ์ค์ ์๋ณํ๊ณ (์ ํํ ์ผ์น), --set-subject / --set-relation /
--set-object / --set-note ๊ฐ ์ ๊ฐ์ ์ค๋๋ค(์ต์ ํ๋, ๋๋ --accept). amend
๋ candidates.csv ์ ๊ทธ ๊ทผ๊ฑฐ๊ฐ ๋๋ runs/*.json ์ ๋ ๋ค ๊ฐฑ์ ํ๋ฏ๋ก
ํธ์ง์ด /factlog sync ํ์๋ ์ด์๋จ์ต๋๋ค(์ฌ์ค์ ๊ฐ์ runs/*.json ์ ์์ผ๋ฉฐ,
merge ๊ฐ ๊ทธ๋ก๋ถํฐ candidates.csv ๋ฅผ ์ฌ๊ตฌ์ฑํฉ๋๋ค). --accept ๋ accepted ๋ก
์น๊ฒฉ๊น์ง ํฉ๋๋ค. ์ ๋ขฐ๋๋ ํธ์งํ ์ ์์ต๋๋ค. --dry-run ์ผ๋ก ๋ฏธ๋ฆฌ ๋ณผ ์ ์์ต๋๋ค.
๋ด๊ตฌ์ฑ(durability): ์ฌ๋์ด ํ
accept(๋ฐamend --accept)๋reject/superseded์ ๊ฐ์ ๋ฐฉ์์ผ๋ก ์ฌ๋จธ์ง ํ์๋ ๋ณด์กด๋ฉ๋๋ค โ/factlog sync๊ฐ ์ฌ๋ฌ๋ถ์ ๊ฒฐ์ ์ ๋๋๋ฆฌ์ง ์์ต๋๋ค.
/factlog sync ๋ ๋งค ์คํ๋ง๋ค ๋ชจ๋ ์์ค๋ฅผ ๋ค์ ์ถ์ถํฉ๋๋ค. ํน์ ์์ค๋ฅผ
๊ทธ ๋์์์ ๋นผ๋ ค๋ฉด โ ์ด์, ์์
์ค์ธ ๋ฌธ์, ์ธ๋ถ ๋ฌธ์ ๋ฑ โ KB๋ณ sync-ignore
๋ชฉ๋ก(policy/sync-ignore.md)์ ์ถ๊ฐํ์ญ์์ค. ๋ฌด์๋ ์์ค๋ ์์ ๋๋๋ผ๋
/factlog sync, factlog ingest --scan, ์ปค๋ฒ๋ฆฌ์ง ๋๋ฝ ๋ณด๊ณ ์์ ๊ฑด๋๋๋๋ค. ์ด๋ฏธ
๋จธ์ง๋ ์ฌ์ค์ ๊ทธ๋๋ก ์ ์ง๋ฉ๋๋ค(์ฌ์ค์ ์ค์ ๋ก ์ ๊ฑฐํ๋ ค๋ฉด factlog eject ์ฌ์ฉ).
factlog ignore drafts/*.md sources/wip-notes.md # add pattern(s)
factlog ignore # list patterns + what they match
factlog ignore --remove drafts/*.md # remove a patternpolicy/sync-ignore.md ๋ ํ ์ค์ ๊ธ๋กญ(glob) ํ๋์ฉ ์ ์ต๋๋ค(๋ค๋ฅธ ์ ์ฑ
ํ์ผ๊ณผ
๊ฐ์ ๋๊ทธ๋ฌ์ด ํ์ โ # ์ฃผ์, - ๋ถ๋ฆฟ, ๋ฐฑํฑ ์ธ์ฉ ํญ๋ชฉ ์ง์. # ๋ก ์์ํ๋
ํจํด์ ๋ฐฑํฑ์ผ๋ก ๊ฐ์ธ์ญ์์ค). ํจํด์ ์์ค์ ์ ์ฒด ref(sources/... /
runs/sources/...) ๋๋ ์์ค ๋ฃจํธ ๋ด ๊ฒฝ๋ก๋ก ๋งค์นญ๋ฉ๋๋ค. ๊ธ๋กญ ์๋ฏธ:
* ์ ? ๋ ํ ๊ฒฝ๋ก ์ธ๊ทธ๋จผํธ ์์ ๋จธ๋ฌผ๊ณ (/ ๋ฅผ ๋์ง ์์), ** ๋
์ธ๊ทธ๋จผํธ๋ฅผ ๋์ผ๋ฉฐ, ๋์ / ๋ ๊ทธ ํ์ ํธ๋ฆฌ ์ ์ฒด๋ฅผ ๋ปํฉ๋๋ค.
| ํจํด | ๋งค์นญ ๋์ |
|---|---|
drafts/*.md |
sources/drafts/x.md โ ๋จ, sources/drafts/sub/x.md ๋ ์๋ |
drafts/** (๋๋ drafts/) |
sources/drafts/ ์๋ ์ ๋ถ |
**/*.md |
์์ ๊น์ด์ ๋ชจ๋ .md |
factlog sources ๋ ๋ฌด์๋ ์์ค๋ฅผ [ignored] ๋ก ํ์ํ๊ณ , ์ปค๋ฒ๋ฆฌ์ง๋ ์ด๋ฅผ ๋๋ฝ์ด
์๋๋ผ excluded ๋ก ๋ณด๊ณ ํฉ๋๋ค.
factlog eject <source> ๋ ์ ์ฌ(ingest)๋ฅผ ๋๋๋ฆฝ๋๋ค. runs/sources/ ๋ณํ๋ณธ์
์ญ์ ํ๊ณ , ํด๋น ์์ค์์ ์ถ์ถ๋ ํ์ runs/*.json ์์ ์ ๊ฑฐํ๋ฉฐ, ๊ทธ ์์ค๋ฅผ ์ธ์ฉํ๋
์ฌ์ค์ ํ๊ธฐํฉ๋๋ค. ์์ค๋ ํ์ผ๋ช
, ์ด๊ฐ(stem), ๋๋ KB ๊ธฐ์ค ์๋ ๊ฒฝ๋ก๋ก ์ง์ ํ ์
์์ต๋๋ค โ ๋ฐ์ด๋๋ฆฌ ์๋ณธ(์: report.pdf)์ ์ง์ ํ๋ฉด ๊ทธ runs/sources/<stem>
๋ณํ๋ณธ๋ ํจ๊ป ๋งค์นญ๋๊ณ , ์ด๊ฐ๋ง ์ฃผ๋ฉด ๊ฐ์ ์ด๊ฐ์ ๊ฐ์ง ๋ชจ๋ ์์ค๊ฐ ๋งค์นญ๋ฉ๋๋ค.
factlog eject report.pdf # delete conversion; mark citing facts superseded (kept for audit)
factlog eject report.pdf --purge # delete the citing candidate rows instead of superseding them
factlog eject report.pdf --delete-original # also delete the user's original under sources/
factlog eject report.pdf --dry-run # show the planned changes, modify nothing์์ค ์์ฒด๋ ๋ฉ์ฉกํ๋ฐ ์ถ์ถ๋ ์ฌ์ค ํ๋๊ฐ ์๋ชป๋ ๊ฒฝ์ฐ, ๊ทธ ์ฌ์ค๋ง ํ๊ธฐํ ์ ์์ต๋๋ค โ ์์ค์ ๋ณํ๋ณธ๊ณผ ์๋ณธ์ ๊ทธ๋๋ก ๋จ์ต๋๋ค.
factlog eject --fact "์์๋น์ค" "์ ์_์ด์" "2030.1" # retire one fact (mark superseded)
factlog eject --fact "๊ฐ๋ด" "ํตํฉ" "์์๋น์ค" --fact "๊ฐ๊ฐ" "๋์ฒด" "๊ฐ๋" # several at once
factlog eject --fact "์์๋น์ค" "์ ์_์ด์" "2030.1" --purge # delete the candidate row instead์ฌ์ค์ ๋ชจ๋ ์์ค์ ๊ฑธ์ณ ๊ทธ (subject, relation, object) ํธ๋ฆฌํ๋ก ๋งค์นญ๋ฉ๋๋ค.
๊ธฐ๋ณธ๊ฐ์ธ superseded ๋ runs/*.json ์ ๊ฑด๋๋ฆฌ์ง ์์ผ๋ฏ๋ก ํ๊ธฐ๊ฐ ๋ด๊ตฌ์ฑ์
๊ฐ์ง๋๋ค โ ์ดํ /factlog sync ๊ฐ ์์ค๋ก๋ถํฐ ์ฌ์ค์ ๋ค์ ์ฃผ์ฅํ๋๋ผ๋
merge_candidates ๊ฐ ๊ทธ๊ฒ์ ๊ณ์ superseded ๋ก ์ ์งํฉ๋๋ค. ๋ฐ๋ฉด --purge ๋ ํ์
์ญ์ ํ๊ณ runs/*.json ์์๋ ์ ๊ฑฐํฉ๋๋ค. ์์ค๊ฐ ์ฌ์ ํ ๊ทธ ์ฌ์ค์ ์ฃผ์ฅํ๋ค๋ฉด ์ฌ์ฑํฌ
์ ๋ค์ ์ถ์ถ๋๋ฏ๋ก, ์ฌ์ค์ ์๊ตฌํ ํ๊ธฐํ๋ ค๋ฉด ๊ธฐ๋ณธ๊ฐ์ ์ฌ์ฉํ์ญ์์ค. fact ๋ชจ๋์
source ๋ชจ๋๋ ์ํธ ๋ฐฐํ์ ์ด๋ฉฐ, --delete-original ์ --fact ์ ํจ๊ป ์ธ ์
์์ต๋๋ค.
๊ธฐ๋ณธ์ ์ผ๋ก ํ๊ธฐ๋ ์ฌ์ค์ superseded ๋ก ํ์๋์ด(๊ฐ์ฌ ๋ชฉ์ ์ผ๋ก
facts/candidates.csv ์ ๋จ์) sources/ ์๋ ์๋ณธ์ ์ ์ง๋ฉ๋๋ค โ ๋ฐ๋ผ์ ๋ค์
/factlog sync ๋ ๋ค์ ๋ณํ๋ฉ๋๋ค. ์๋ณธ๊น์ง ์ ๊ฑฐํ๋ ค๋ฉด --delete-original ์
๋๊ธฐ์ญ์์ค. accepted.dl ์ ์ฌ์ปดํ์ผ๋์ด ์์ง ์
๋ ฅ์์ ํ๊ธฐ๋ ์ฌ์ค์ด ์ฆ์
๋น ์ง๋๋ค.
runs/sources/ ๋ณํ๋ณธ์ ์ ์ฌ ์ถ์ฒ ํค๋๋ฅผ ํตํด ๊ทธ๊ฒ์ ๋ง๋ค์ด ๋ธ ์๋ณธ๊ณผ ๋ฌถ์ฌ
์์ผ๋ฏ๋ก, ๋ ์๋ณธ์ด ์ด๊ฐ์ ๊ณต์ ํ๋๋ผ๋ eject report.docx ๊ฐ report.pptx ์
๋ณํ๋ณธ์ ๊ฑด๋๋ฆฌ์ง ์์ต๋๋ค. pages/ ๋ eject ๋ก ์ฌ์์ฑ๋์ง ์์ต๋๋ค โ
/factlog sync ๋ฅผ ์คํํด ๋ง์ถ์ญ์์ค. ๊ธฐ๋ณธ๊ฐ superseded ๋ ํ์ฌ ์ํ ๊ธฐ์ค์
ํ๊ธฐ์
๋๋ค. ํ
์คํธ ์๋ณธ์ sources/ ์๋ ๊ทธ๋๋ก ๋๋ฉด ๋ค์ /factlog sync ๊ฐ
๊ทธ ์ฌ์ค์ ๋ค์ ์ถ์ถยท์ฃผ์ฅํ๋ฏ๋ก, ์์ค๋ฅผ ์๊ตฌํ ์ ๊ฑฐํ๋ ค๋ฉด --purge ์/๋๋
--delete-original ์ ๋๊ธฐ์ญ์์ค.
ํด์ ์ฐ์ ์์: --target/--wiki ํ๋๊ทธ > $FACTLOG_ROOT > ํ์ฑ KB ์ค์
(${XDG_CONFIG_HOME:-~/.config}/factlog/config.json) > ํ์ฌ ๋๋ ํฐ๋ฆฌ. ์ค์ ์ด ์์ผ๋ฉด
๋์์ ์ข
์ ๊ณผ ๊ฐ์ต๋๋ค(ํ์ฌ ๋๋ ํฐ๋ฆฌ ์ฌ์ฉ).
/factlog sync ๋ ์ฒซ ๋จ๊ณ๋ก factlog ingest --scan ์ ์คํํ๋ฏ๋ก, sources/ ์
๋ฃ์ด ๋ ๋ฐ์ด๋๋ฆฌ๋ ์๋์ผ๋ก ๋ณํ๋ฉ๋๋ค(๋ฉฑ๋ฑ์ ์ผ๋ก โ ๋ฐ๋์ง ์์ ํ์ผ์ ๊ฑด๋๋).
๋ฐ์ด๋๋ฆฌ์ runs/sources/ ๋ณํ๋ณธ์ด ์์ผ๋ฉด merge_candidates.py ๊ฐ ๊ฒฝ๊ณ ํ์ฌ,
์กฐ์ฉํ ๋น์ ์ฌ(non-ingestion)๊ฐ ๋๋ฌ๋๊ฒ ํฉ๋๋ค.
- Python 3.11+ (์์ง ์์กด์ฑ
pyrewire๊ฐ ์๊ตฌ) - pyrewire 1.0.1+ (
pip install -r requirements.txt) - Claude Code CLI
factlog๋ Claude Code ํ๋ฌ๊ทธ์ธ์ ๋๋ค. Claude Code ์ธ์ ์์ ์ด ์ ์ฅ์์ ๋ง์ผํ๋ ์ด์ค๋ก๋ถํฐ ์ค์นํฉ๋๋ค.
/plugin marketplace add https://github.com/semantic-reasoning/factlog
/plugin install factlog@semantic-reasoning
/reload-plugins
/factlog setup # one-shot: deps + doctor + init, in-session
์ ๋ช ๋ น์ ํ ์ค์ฉ ์คํํ์ญ์์ค. ์ฌ๋ฌ ์ค์ ํ ๋ฒ์ ๋ถ์ฌ ๋ฃ์ผ๋ฉด Claude Code๊ฐ ๋ง์ผํ๋ ์ด์ค ๋ฑ๋ก๊ณผ ์ค์น๋ฅผ ์์๋๋ก ์ฒ๋ฆฌํ์ง ๋ชปํ ์ ์์ต๋๋ค.
์ค์น๊ฐ ์ฑ๊ณตํด๋ ํ์ฌ ์ธ์
์๋ ์ /factlog ... ๋ช
๋ น์ด ์ฆ์ ๋ก๋๋์ง ์์ ์
์์ต๋๋ค. /plugin install ๋ค์์ /reload-plugins ๋ฅผ ์คํํ ๋ค /factlog setup
์ ์คํํ์ญ์์ค.
setup ์ doctor ์คํ, ์์ง ์์กด์ฑ(pyrewire) ์ค์น, KB ์ค์บํด๋ฉ, ํ๊ฒฝ ์ฌ์ ๊ฒ์
ํ ๋ช
๋ น์ผ๋ก ์ํํฉ๋๋ค.
๋ก์ปฌ ํด๋ก ์ ๋ํด ๊ฐ๋ฐํ๋ ค๋ฉด, ์์ ํธ๋ฆฌ ์์ฒด๋ฅผ ๋ง์ผํ๋ ์ด์ค๋ก ๋ฑ๋กํ์ญ์์ค.
/plugin marketplace add ~/git/semantic-reasoning/factlog
/plugin install factlog@semantic-reasoning
/reload-plugins
/factlog setup
setup ์ ์ด์ ์ ๋ถ๋ฆฌ๋ผ ์๋ ์ค์น ํ ๋จ๊ณ๋ค์ ํ ๋ช
๋ น์ผ๋ก ํฉ์นฉ๋๋ค. ์๋์ผ๋ก ํ๋ฉด
๋๋ฑํ๊ฒ ๋ค์๊ณผ ๊ฐ์ต๋๋ค.
pip install -r ~/git/semantic-reasoning/factlog/requirements.txt # pyrewire>=1.0.1,<2.0
python3 -m factlog doctor # checks Python 3.11+ and pyrewire
python3 -m factlog init --target ~/wiki # scaffold the KB layoutWindows์์๋ python3 ๋ช
๋ น์ด ์ค์ Python์ด ์๋๋ผ Microsoft Store stub์
๊ฐ๋ฆฌํฌ ์ ์์ต๋๋ค. ์ด ๊ฒฝ์ฐ python ๋๋ py๋ ์ ์์ด์ด๋ ํ๋ฌ๊ทธ์ธ์ ๋ฒ๋ค
์คํฌ๋ฆฝํธ๊ฐ ์คํจํ ์ ์์ต๋๋ค.
๋จผ์ ๋ค์์ ํ์ธํ์ญ์์ค.
python3 --version
python --version
py -0ppython3 --version์ด Python๋ง ์ถ๋ ฅํ๊ณ ์คํจํ๊ฑฐ๋ Microsoft Store๋ฅผ ์ฌ๋
์ํ๋ผ๋ฉด, factlog๊ฐ ์ฌ์ฉํ Python์ ๋ช
์ํ์ญ์์ค. venv๋ฅผ ์ฐ๋ ๊ฒฝ์ฐ:
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e <path-to-factlog-repo>
$env:FACTLOG_PYTHON = (Resolve-Path .\.venv\Scripts\python.exe).Pathํ๋ฌ๊ทธ์ธ์ hook๊ณผ skill ๋ช
๋ น์ ${CLAUDE_PLUGIN_ROOT}/tools/factlog_python.sh
๋ฅผ ํตํด $FACTLOG_PYTHON, python3, python, py ์์๋ก Python 3.11+
์คํ ํ์ผ์ ์ฐพ์ต๋๋ค.
์ฌ๋ฌ๋ถ์ Python์ด ์ธ๋ถ ๊ด๋ฆฌ(PEP 668) ์ํ๋ผ๋ฉด pip์ด ๊ทธ ์์ผ๋ก์ ์ค์น๋ฅผ
๊ฑฐ๋ถํฉ๋๋ค. ์ด๋ setup ์ ์ค์น๋ฅผ ๊ฐํํ๋ ๋์ venv ์๋ด๋ฅผ ์ถ๋ ฅํฉ๋๋ค. venv๋ฅผ
๋ง๋ค์ด ํ์ฑํํ ๋ค setup ์ ๋ค์ ์คํํ์ญ์์ค.
python3 -m venv ~/.factlog-venv && source ~/.factlog-venv/bin/activate
python3 -m factlog setup --target ~/wiki์ง์๋ฒ ์ด์ค ์์ Claude Code ์ธ์ ์์(ํ๋ฌ๊ทธ์ธ์ ๋ชจ๋ ์ธ์ ์์ ํ์ฑ):
/factlog sync # read sources/, extract candidate facts, update pages & decisions
/factlog query # translate policy/questions.md into facts/query.dl (Datalog query draft)
/factlog check # compile accepted facts, run the logic check over accepted + query, show the report
/factlog repair # attempt gated self-correction of review_required queries
/factlog ask # answer one question: deterministically routed to the engine (verified) or wiki exploration (unverified)
/factlog check ์ ์ /factlog query ๋ฅผ ์คํํ์ญ์์ค. ๋ก์ง ์ฒดํฌ๋
facts/query.dl ์ ์ฟผ๋ฆฌ ์ด์์ ํ๊ฐํ๋๋ฐ, ์ด ์ด์์ /factlog query ๊ฐ
policy/questions.md ์ ์์ฐ์ด ์ง๋ฌธ์ผ๋ก๋ถํฐ ์์ฑํฉ๋๋ค.
์คํฌ์ ๊ณง ํ๋กฌํํธ์ด๋ฏ๋ก, ๋ชจ๋ธ์ ๊ฐ ๋จ๊ณ๋ฅผ ์คํํ๋๋ก ์ ๋๋ ๋ฟ ๊ฐ์ ๋์ง๋ ์์ต๋๋ค. factlog๋ ์ ๋ขฐ์ฑ์ด ํ์์ธ ๋ชจ๋ ๋จ๊ณ โ ์ฌ์ค ์ปดํ์ผ, wirelog ๋ก์ง ์ฒดํฌ, ์ ์ฑ ์ปดํ์ผ, ๊ฒ์ฆ โ ๋ฅผ ๋ชจ๋ธ์ ํ๋จ์ด ์๋๋ผ ์คํฌ์ด ์คํํ๊ณ ์ ๋ขฐํ๋๋ก ์ง์๋ฐ๋ ๋ฒ๋ค ์คํฌ๋ฆฝํธ๋ก ์ ์งํฉ๋๋ค. ๋ก์ง ์ฒดํฌ ๋ฆฌํฌํธ๋ ์ธ์ ๋ ์์ง์ด ์์ฑํ๋ฉฐ, ๋ชจ๋ธ์ด ์์ ํ์ง ์์ต๋๋ค.
factlog๋ ๋ ๊ฐ์ง ์๋ก ๋ค๋ฅธ ๋ฉ์ปค๋์ฆ์ผ๋ก ์ ์ ๋(freshness)๋ฅผ ๊ฐ์ ํฉ๋๋ค.
| ๋จ๊ณ | ๋ฉ์ปค๋์ฆ | ๋ณด์ฅํ๋ ๊ฒ |
|---|---|---|
| ํ ์ผ๋ก ๊ฐ์ | facts/logic_report.txt ๊ฐ ์๊ฑฐ๋ ๋์ ํ์ผ๋ณด๋ค ์ค๋๋์์ ๋, PreToolUse ํ
์ด facts/accepted.dl ๋๋ facts/query.dl ๋ก์ ๋ชจ๋ Write/Edit ๋ฅผ ๊ฑฐ๋ถํฉ๋๋ค(/factlog check โ run_logic_check.py ๋ก ๊ฐฑ์ ) |
๋ก์ง ๋ฆฌํฌํธ๊ฐ ์ค๋๋ ์ํ์์๋ ์์ง์ ์ปดํ์ผ๋ ์ ๋ ฅ์ ๋ฎ์ด์ธ ์ ์์ต๋๋ค โ ํ ์ด ํ์ผ์ ์๋๊ธฐ ์ ์ ๋๊ตฌ ํธ์ถ์ ์ฐจ๋จํฉ๋๋ค |
| SKILL ๊ท์จ (์ต์ ๋ ธ๋ ฅ) | SKILL.md ๋ ์ด๋ค ๊ฒฐ๋ก ์ ๋งํ๊ธฐ ์ ์ Claude๊ฐ run_logic_check.py ๋ฅผ ์คํํ๊ณ facts/logic_report.txt ๋ฅผ ๊ทธ๋๋ก ๋ณด์ฌ ์ฃผ๋๋ก ์ง์ํฉ๋๋ค |
๋ชจ๋ธ์ ์์ง ๋ฆฌํฌํธ๋ฅผ ๋๋ฌ๋ด๋๋ก ์ ๋๋์ง๋ง ๊ฐ์ ๋ ์๋ ์์ต๋๋ค(R10: "์์ ํ ๋ณด์ฅํ ์ ์์") โ ์์ ๋ฆฌํฌํธ์ ๋ํ ์ฌ๋์ ๊ฒํ ๊ฐ ์ต์ข ๊ฒ์ฆ ๋จ๊ณ์ ๋๋ค |
์ด ๋ ๋จ๊ณ๋ ์ํธ ๋ณด์์ ์ ๋๋ค. ํ ์ ๊ฒฐ์ ๋ก ์ ๋นํ์ ๋ฉ์ฐ๊ณ , SKILL ๊ท์จ์ ์์ง๋์ด๋ง์ ๊ฐ์ ๊ฐ ๋ถ๊ฐ๋ฅํ ์์ (narration) ๊ณ์ธต์ ๋ด๋นํฉ๋๋ค.