Skip to content

semantic-reasoning/factlog

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

176 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

factlog

๐ŸŒ 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) ์ผ ๋ฟ์ž…๋‹ˆ๋‹ค.

๋™์ž‘ ๋ฐฉ์‹

factlog ๋™์ž‘ ๋ฐฉ์‹: Claude๊ฐ€ ์ œ์•ˆํ•˜๊ณ , ์—”์ง„์ด ๊ฒ€์ฆํ•˜๋ฉฐ, ์‚ฌ๋žŒ์ด ํ™•์ธํ•ฉ๋‹ˆ๋‹ค

ํ…์ŠคํŠธ ๋ฒ„์ „
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/

ํ™œ์„ฑ KB (์„ค์ •ํ•ด ๋‘” KB๋ฅผ ์–ด๋””์„œ๋“  ๋Œ€์ƒ์œผ๋กœ)

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)

์–ดํœ˜ ์‚ดํŽด๋ณด๊ธฐ (factlog vocab)

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 ์™€ ๋™์ผํ•œ ํƒ€์ดํ•‘).

ํƒ€์ž… ์ง€์ • ๊ด€๊ณ„ (policy/typed-relations.md)

์–ด๋–ค ๊ด€๊ณ„์˜ ๋ฆฌํ„ฐ๋Ÿด ๊ฐ์ฒด๋Š” ๋‹จ์ˆœ ๋งค์นญ์ด ์•„๋‹ˆ๋ผ ๋น„๊ต๋˜์–ด์•ผ ํ•ฉ๋‹ˆ๋‹ค โ€” ๊ทธ๋ž˜์•ผ ๊ฒฐ์ •๋ก ์  ์—”์ง„์ด ๊ทธ ๊ฐ’์„ ์ •๋ ฌ(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)

์ •ํ™•ํ•œ ์ด๋ฆ„์„ ๋ชจ๋ฅผ ๋•Œ๋Š” factlog search <term> ์ด ์ฃผ์–ด/๊ด€๊ณ„/๊ฐ์ฒด ์ „์ฒด์— ๋Œ€ํ•ด ๋Œ€์†Œ๋ฌธ์ž ๊ตฌ๋ถ„ ์—†๋Š” ๋ถ€๋ถ„ ๋ฌธ์ž์—ด ๋งค์นญ์„ ์ˆ˜ํ–‰ํ•˜๊ณ , ์ผ์น˜ํ•˜๋Š” ์‚ฌ์‹ค์„(์ƒํƒœ์™€ ์ถœ์ฒ˜ ์ˆ˜์™€ ํ•จ๊ป˜) ๋‚˜์—ดํ•ฉ๋‹ˆ๋‹ค. vocab ์€ ์ด๋ฆ„์„ ๋‚˜์—ดํ•˜๊ณ , search ๋Š” ์กฐ๊ฐ์œผ๋กœ ์‚ฌ์‹ค์„ ์ฐพ์œผ๋ฉฐ, provenance ๋Š” ์ •ํ™•ํ•œ ํŠธ๋ฆฌํ”Œ์„ ์ถ”์ ํ•ฉ๋‹ˆ๋‹ค.

factlog search fastapi   # case-insensitive; matches 'FastAPI'
factlog search acme      # partial โ€” every fact mentioning the fragment

์‚ฌ์‹ค์˜ ์ถœ์ฒ˜ ์ถ”์  (factlog provenance)

๋ชจ๋“  ์‚ฌ์‹ค์€ ์ž์‹ ์ด ์ถ”์ถœ๋œ ์†Œ์Šค๋ฅผ ๊ธฐ๋กํ•ฉ๋‹ˆ๋‹ค. 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>)๋ฅผ ๋‚˜์—ดํ•˜๋ฏ€๋กœ, ์ฟผ๋ฆฌ๋กœ ์ฐพ์€ ์‚ฌ์‹ค์„ ๊ทธ ์ž๋ฆฌ์—์„œ ์ถ”์ ํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.

์‚ฌ์‹ค ๊ฒ€ํ†  (factlog review / accept / reject)

์ถ”์ถœ์€ ์‚ฌ์‹ค์„ 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-run

accept/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 ๊ฐ€ ์—ฌ๋Ÿฌ๋ถ„์˜ ๊ฒฐ์ •์„ ๋˜๋Œ๋ฆฌ์ง€ ์•Š์Šต๋‹ˆ๋‹ค.

sync์—์„œ ์†Œ์Šค ์ œ์™ธํ•˜๊ธฐ (factlog ignore)

/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 pattern

policy/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) โ€” ingest ์˜ ์—ญ์—ฐ์‚ฐ

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

์‚ฌ์‹ค ํ•˜๋‚˜๋งŒ ์ œ๊ฑฐ (--fact)

์†Œ์Šค ์ž์ฒด๋Š” ๋ฉ€์ฉกํ•œ๋ฐ ์ถ”์ถœ๋œ ์‚ฌ์‹ค ํ•˜๋‚˜๊ฐ€ ์ž˜๋ชป๋œ ๊ฒฝ์šฐ, ๊ทธ ์‚ฌ์‹ค๋งŒ ํ๊ธฐํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค โ€” ์†Œ์Šค์˜ ๋ณ€ํ™˜๋ณธ๊ณผ ์›๋ณธ์€ ๊ทธ๋Œ€๋กœ ๋‚จ์Šต๋‹ˆ๋‹ค.

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

/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 layout

Windows Python ์‹คํ–‰ ํŒŒ์ผ

Windows์—์„œ๋Š” python3 ๋ช…๋ น์ด ์‹ค์ œ Python์ด ์•„๋‹ˆ๋ผ Microsoft Store stub์„ ๊ฐ€๋ฆฌํ‚ฌ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. ์ด ๊ฒฝ์šฐ python ๋˜๋Š” py๋Š” ์ •์ƒ์ด์–ด๋„ ํ”Œ๋Ÿฌ๊ทธ์ธ์˜ ๋ฒˆ๋“ค ์Šคํฌ๋ฆฝํŠธ๊ฐ€ ์‹คํŒจํ•  ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค.

๋จผ์ € ๋‹ค์Œ์„ ํ™•์ธํ•˜์‹ญ์‹œ์˜ค.

python3 --version
python --version
py -0p

python3 --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 ๋กœ์ง ์ฒดํฌ, ์ •์ฑ… ์ปดํŒŒ์ผ, ๊ฒ€์ฆ โ€” ๋ฅผ ๋ชจ๋ธ์˜ ํŒ๋‹จ์ด ์•„๋‹ˆ๋ผ ์Šคํ‚ฌ์ด ์‹คํ–‰ํ•˜๊ณ  ์‹ ๋ขฐํ•˜๋„๋ก ์ง€์‹œ๋ฐ›๋Š” ๋ฒˆ๋“ค ์Šคํฌ๋ฆฝํŠธ๋กœ ์œ ์ง€ํ•ฉ๋‹ˆ๋‹ค. ๋กœ์ง ์ฒดํฌ ๋ฆฌํฌํŠธ๋Š” ์–ธ์ œ๋‚˜ ์—”์ง„์ด ์ƒ์„ฑํ•˜๋ฉฐ, ๋ชจ๋ธ์ด ์„œ์ˆ ํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค.

AC4 โ€” ์˜ค๋ž˜๋œ ํŽธ์ง‘ ๋ฐฉ์ง€ (๋‘ ๋‹จ๊ณ„)

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) ๊ณ„์ธต์„ ๋‹ด๋‹นํ•ฉ๋‹ˆ๋‹ค.

๋ผ์ด์„ ์Šค

Apache-2.0 โ€” LICENSE ์™€ NOTICE ์ฐธ์กฐ.

About

Logic Augmented LLMWiki for Claude

Resources

License

Code of conduct

Stars

Watchers

Forks

Packages

 
 
 

Contributors