llm-brain

Personal Knowledge Ontology

저장한 정보에, 다시 쓸 맥락을.

메모·문서·클리핑을 위키로 정리하고, 원문과 주장, 관련 지식과 사용한 절차를 함께 읽습니다. 사람은 근거와 맥락을 확인하고, 에이전트는 같은 Object·Relation·Action 계약으로 다음 작업에 필요한 지식을 참조합니다.

지식의 구조를 설명하는 일러스트레이션입니다. · 30초 영상 보기 · 제품 소개 · 빠른 시작

왜 필요한가 Why this exists

지난달 읽은 기사나 연구 메모를 오늘의 답변, 요약, 의사결정에 쓰려면 다시 확인해야 합니다. 원문은 어디 있는지, 어떤 문장이 현재 사용할 수 있는 주장인지, 관련 지식은 무엇인지, 이전 결과물은 어떤 맥락에서 만들어졌는지 살펴야 합니다.

llm-brain은 이 확인과 재사용을 하나의 흐름으로 연결합니다. 기존 ingest·curate·query·express·wiki-web·OKF를 사용하면서, 파일에 흩어진 개인 지식을 공통 ID와 타입으로 읽습니다. Ontology는 출처와 활용 관계를 설명하며, 관계 자체가 사실성을 인증하지는 않습니다.

정보를 다음 작업에 쓰는 흐름 An illustrative workflow

읽어둔 자료에서 찾은 문장을 새 요약이나 의사결정 메모에 활용하는 예시입니다.

1. 원문 확인. 보관한 기사나 연구 메모의 위치를 찾고, 재사용할 claim의 원문 위치와 kind, status, trust, 유효기간을 살핍니다.
2. 근거와 맥락 연결. Wiki의 “왜 이 지식인가?” 또는 ontology.py explain으로 출처와 관련 페이지를 읽습니다. 저장된 active + trusted 상태와 별개로 원문의 의미와 적용 범위를 검토합니다.
3. 관련 지식 재사용. 질문에는 query를, 요약·보고서 초안에는 express를 사용합니다. 필요한 페이지와 절차를 작업의 맥락으로 가져오고 결과를 검토합니다.
4. 활용 맥락 다시 읽기. 사용 관계가 기록된 경우, 산출물에서 활용한 페이지와 절차를 다시 따라갈 수 있습니다.

활용 관계는 기록된 근거가 있을 때 나타납니다. query는 현재 원본 해시와 유효기간 등을 다시 확인하며, 사용할 수 있는 근거가 없으면 답변을 보류합니다.

사람과 에이전트가 함께 읽는 지식

확인할 것	사람이 읽는 곳	에이전트·프로그램이 읽는 것
무엇을 근거로 삼았나	Wiki의 “왜 이 지식인가?”와 원문 위치	source·claim·knowledge_page의 ID와 관계
어떤 상태로 기록되어 있나	저장된 claim 상태·신뢰·유효기간	동일하게 저장된 claim 속성
어떻게 활용했나	기록된 결과물·페이지·절차 연결	artifact의 derived_from, guided_by 관계
어떤 작업이 가능한가	명령별 입력·출력·승인 안내	schema/actions.yaml의 Action catalog

Projection과 Explain은 저장된 claim 상태를 보여줍니다. 현재 raw의 hash 일치, 유효기간, trust 등 답변 근거로 사용할 수 있는지의 검사는 query 경로에서 수행합니다.

Action catalog는 ingest·curate·query·express·share의 입력, 출력, 승인과 evidence를 설명합니다. catalog를 읽는 것만으로 명령이나 외부 작업이 실행되지는 않습니다. 에피소드는 기록에 성공한 작업의 맥락이며, 필수 감사 원장이나 승인 근거가 아닙니다.

지식의 관계 Typed knowledge graph

다섯 객체와 방향이 정해진 관계로 지식의 근거와 활용을 구분합니다.

source ──supports──▶ claim ──compiled_into──▶ knowledge_page
                                               │
                                  links_to ───▶ knowledge_page

artifact ──derived_from──▶ knowledge_page
artifact ──guided_by─────▶ procedure

source는 원문 경로와 SHA-256, claim은 문장과 상태, knowledge_page는 정리된 지식, procedure는 재사용 절차, artifact는 만들어진 결과물입니다. 활용 관계는 기록된 근거가 있을 때만 나타납니다. 단순 wikilink 그래프와 달리 링크의 의미와 방향을 계약으로 읽습니다. 상세: Ontology schema, Action catalog.

작동 원리 How it works

1. 원본을 보존합니다. raw/를 근거로 wiki/를 정리하고 claims.jsonl에서 주장과 원문 연결을 관리합니다. 절차는 procedures/, 작업 이력은 episodes/, 결과물은 express/에 남습니다.
2. 파일에서 관계를 읽습니다. validate와 explain은 읽기 전용입니다. export는 기존 파일을 결정적으로 투영해 gitignored ontology/private-ontology.json을 만듭니다. 이 private bundle은 원본을 대체하지 않으며 다시 생성할 수 있습니다.
3. 같은 근거를 다시 사용합니다. 사람은 Wiki·CLI에서 설명을 읽고, 프로그램은 bundle의 객체·관계·Action 계약을 읽습니다. brain_context는 다음 작업에 관련된 페이지·이력·절차를 묶습니다.
4. 공유는 별도로 결정합니다. private projection은 공유 승인이 아닙니다. 공개 공유에는 기존 OKF의 사람 승인과 manifest gate를 사용합니다.

Projection과 Explain 자체는 모델을 호출하지 않습니다. AI 정리·생성·답변은 설정된 도구나 제공자에 선택된 내용을 전달할 수 있습니다. private bundle에는 claim 문장이 포함되므로 개인 파일로 관리해야 합니다. 범용 실행기와 조직 권한 관리는 확장 범위를 따릅니다.

---

미리보기 Preview

로컬 HTML 검색·페이지뷰 (브라우저에서 위키를 둘러보는 화면, uv run python -m wiki_app):

검색 + 페이지 뷰	본문 grep 자동 확장

결과 0개 → AI CTA	AI 답변 모달 (live)

한국어/영문 검색 · 결과 < 3개일 때 본문 grep(본문 전체 텍스트 검색) 자동 확장 · 페이지 뷰 + wikilink SPA 네비게이션(새로고침 없이 이동) · AI 답변 옵션 토글

---

준비물 Prerequisites

비전공자도 따라 할 수 있게, 필요한 세 가지를 하나씩 풀어 둔다.

1. AI 작업 도구 — Claude Code 또는 Codex — 이 위키를 정리·질문·글쓰기 작업으로 이끄는 도구입니다. Claude Code는 플러그인 슬래시 명령을, Codex는 이 저장소 안의 프로젝트 스킬을 사용합니다. Claude Code 설치·안내(공식): https://docs.claude.com/claude-code Codex 스킬 안내(공식): https://developers.openai.com/api/docs/guides/tools-skills

2. uv — 파이썬을 알아서 설치·실행해 주는 도구(복잡한 파이썬 환경 설정을 대행). 터미널에 아래 한 줄을 입력하면 설치된다:

curl -LsSf https://astral.sh/uv/install.sh | sh

3. git — 인터넷의 코드 저장소를 내 컴퓨터로 내려받는 도구. macOS·Linux는 보통 기본 설치돼 있다(macOS에 없으면 xcode-select --install).

용어 풀이:

• 레포(repository) = 코드가 모여 있는 온라인 저장소. 이 프로젝트가 사는 '집'.
• 클론(clone) = 그 레포를 통째로 내 컴퓨터에 복제하는 것. 명령은 git clone <주소>.

명령을 어디에 입력하나 Where to type

이 문서에는 두 종류의 명령이 섞여 나온다 — 입력하는 곳이 다르다.

• /llm-brain:... 처럼 슬래시로 시작하는 명령 → Claude Code 입력창(대화창)에 입력
• $llm-brain ... 또는 자연어 요청 → 이 저장소를 연 Codex 입력창에 입력. Codex는 .codex/skills/llm-brain/SKILL.md를 읽고 같은 안전 경로를 따른다.
• uv run ... · git clone ... · cp ... 같은 명령 → 터미널(명령줄, 곧 CLI)에 입력
  • 💡 터미널 여는 법: macOS는 ⌘+Space → Terminal 검색 → 실행. (Windows는 PowerShell.)

아래 모든 코드 블록 옆에 ▶ 표시로 "어디에 입력하는지"를 적어 둔다.

---

설치 Install

▶ Claude Code 입력창에 아래 두 줄을 한 줄씩, 순서대로 입력합니다. 첫 줄이 끝난 뒤 두 번째 줄을 입력합니다.

1. 마켓플레이스 추가

/plugin marketplace add kimsanguine/llm-brain

2. 플러그인 설치

/plugin install llm-brain@llm-brain

설치하면 컴파일러 커맨드가 추가된다 — /llm-brain:ingest·/llm-brain:curate·/llm-brain:express·/llm-brain:query·/llm-brain:okf · 설치 점검 /llm-brain:doctor · 웹 UI /llm-brain:wikiweb.

자기 지식 데이터를 다루려면 레포를 클론해 raw/ 소스를 등록한다(아래 빠른 시작). 플러그인은 컴파일러 커맨드를, 클론은 자기 데이터를 제공한다.

Codex에서 사용하기

▶ 터미널에서 저장소를 클론한 뒤, 그 폴더를 Codex Desktop 또는 Codex CLI에서 엽니다. 별도 플러그인 설치는 필요 없습니다.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗