AI에게 매번 반복 설명하는 번거로움을 해결하기 위한 메모리 그래프 구축기

모든 AI와의 대화는 제로(zero) 상태에서 시작됩니다. 당신은 자신의 아키텍처(architecture)를 설명합니다. 다음 날, 당신은 그것을 다시 설명합니다. 3주 전에 내렸던 결정을 설명합니다. 제약 사항을 명확히 합니다. 모델에게 당신의 프로젝트가 실제로 무엇인지 상기시킵니다. 당신은 AI를 사고 파트너(thinking partner)로 사용하고 있는 것이 아닙니다. 매 세션마다 새로운 투어가 필요한 매우 빠른 검색 엔진(search engine)으로 사용하고 있는 것입니다.

저는 이에 좌절감을 느꼈습니다. 그래서 무언가를 만들었습니다.

문제는 구조적입니다.
문제는 Claude나 GPT가 나쁜 모델이라는 것이 아닙니다. 문제는 컨텍스트(context)가 지속되지 않는다는 것입니다. 프롬프트(prompt) 창에 노트 폴더 전체를 쏟아부을 수는 있지만, 그것은 노이즈(noisy)가 많습니다. 모델이 무관한 텍스트에 파묻히게 됩니다. RAG (Retrieval-Augmented Generation)를 사용할 수도 있지만, 개인적인 워크플로우(workflow)를 위해 사용하기에는 무거운 인프라(infrastructure)입니다. 채팅 앱의 메모리 기능을 사용할 수도 있지만, 그것들은 출처(provenance)가 없는 블랙박스(black box)입니다. 왜 무언가가 기억되었는지, 혹은 그것이 여전히 사실인지 알 수 없습니다.

제가 실제로 원했던 것은 간단했습니다:

• 파일 더미가 아닌 개념, 결정, 목표 및 관계의 그래프(graph)
• 모든 주장이 출처 발췌본(source excerpt)에 의해 뒷받침되어 어디에서 왔는지 알 수 있음
• 어떤 것이 영구적으로 저장되기 전의 인간 검토(human review) — LLM (Large Language Model)이 제안하면, 제가 결정함
• 어떤 채팅, 어떤 모델, 어디에서든 붙여넣을 수 있는 아주 작은 컨텍스트 스냅샷(context snapshot)
• 클라우드(cloud) 없음. 저의 그래프는 제 컴퓨터에 있는 JSON 파일입니다.

knowledge-worker를 소개합니다.
knowledge-worker는 AI 세션 전반에 걸쳐 컨텍스트를 전달하기 위한 로컬 우선(local-first) 개인 지식 그래프(personal knowledge graph)입니다. 이것은 마크다운(markdown) 노트를 검토 가능한 개념, 결정, 목표 및 관계(출처 발췌본 포함)로 변환하며, Claude, GPT, Ollama 또는 다음 주에 당신이 사용하게 될 무엇이든 붙여넣을 수 있는 컴팩트한 스냅샷을 내보냅니다. 계정 없음. 동기화 없음. 텔레메트리(telemetry) 없음. 오직 JSON 파일과 CLI (Command Line Interface)뿐입니다.

작동 방식

파이프라인은 5단계로 구성됩니다: Markdown 노트 → LLM이 후보 노드(nodes)와 엣지(edges) 추출 → 검증기(Validator)가 형태, 출처(provenance), 발췌문(excerpts) 확인 → 사용자가 검토: 각 주장(claim)에 대해 수락 / 거절 / 수정 → 병합기(Merger)가 로컬 그래프에 기록 → 평가 로그(Eval log)가 결과 기록

1단계: 노트 가져오기 (Ingest)
mykg ingest ~/notes/architecture-decision.md
CLI가 사용자가 선택한 LLM (Claude, GPT 또는 로컬 Ollama)을 호출하여 후보 노드와 엣지의 구조화된 목록을 받아옵니다. 아직 아무것도 기록되지 않은 상태입니다.

2단계: 검토 (Review)
각 후보를 확인합니다:
CANDIDATE: decision — "JSON을 먼저 사용한다"
extcerpt: "제한 요소가 될 때까지 일반 JSON을 사용한다"
confidence: high
[A]ccept / [R]eject / [E]dit > _
LLM이 제안하고, 사용자가 결정합니다. 사용자의 명시적인 승인 없이는 어떤 것도 영구적인 메모리(durable memory)가 되지 않습니다.

3단계: 쿼리 및 내보내기 (Query and export)

# 그래프 검색
mykg query "provenance"

# 아이디어 간의 경로 찾기
mykg path goal:trusted-ai project:knowledge-worker

# LLM이 바로 사용할 수 있는 압축된 컨텍스트 스냅샷 내보내기
mykg context

context 명령은 다음과 같은 결과를 출력합니다:

[ knowledge-worker ] project — AI 세션 연속성을 위한 로컬 우선 지식 그래프 (local-first knowledge graph)
  → serves : goal:trusted-ai
  → has_idea : idea:provenance-first

[ decision ] Use JSON first — 제한 요소가 될 때까지 일반 JSON을 사용한다
  source : architecture-note.md
  confidence : high

이 내용을 새로운 채팅의 상단에 붙여넣으세요. 즉각적인 연속성이 확보됩니다.

API 키가 없어도 괜찮습니다.
이미 Claude 또는 ChatGPT 구독을 사용 중이라면 API 키가 전혀 필요하지 않습니다. 모델에게 노트로부터 *.candidates.json 파일을 생성하도록 요청하기만 하면 됩니다 (레포지토리에 스키마가 포함되어 있습니다). 그 다음 로컬 검증기를 실행하고 병합하세요:
mykg ingest notes.md --candidates-file notes.candidates.json

앱 구독을 통해 추출을 수행하고, 레포지토리는 그래프 검증 및 병합을 로컬에서 유지합니다.

그래프 시각화하기

독립적이고 오프라인에서 작동하는 HTML 뷰어를 생성합니다. D3 CDN, 외부 요청, 서버가 필요하지 않습니다:
mykg viz --graph examples/demo_graph.json --out /tmp/my-graph.html

렌더링된 공개 데모 그래프의 모습은 다음과 같습니다:

직접 시도해 보세요: 레포지토리에는 API 키나 설치 없이 로컬에서 실행할 수 있는 가상의 데모 그래프가 포함되어 있습니다.
git clone https://github.com/rahulmranga/knowledge-worker
cd knowledge-worker
MYGRAPH_PATH = examples/demo_graph.json
python3 mygraph/mygraph.py summary
MYGRAPH_PATH = examples/demo_graph.json
python3 mygraph/mygraph.py context
python3 mygraph/mygraph.py viz --graph examples/demo_graph.json --out /tmp/demo.html

설계 원칙 (소리 내어 말할 가치가 있는 것들)

출처(Provenance) 우선. 모든 지속적인 주장(claim)은 소스 문서와 실제 발췌문(excerpt)을 가리킵니다. 그래프는 근거가 있는 주장과 추측을 구분합니다.

병합 전 검토. LLM은 환각(hallucination)을 일으킵니다. LLM이 메모리 그래프에 직접 쓰도록 방치하면, 확신에 찬 헛소리가 컨텍스트(context)에 박혀버리는 결과를 초래합니다. 파이프라인은 인간의 검토를 강제합니다.

지루할 정도의 지속성. 그래프는 JSON 파일입니다. 구축해야 할 데이터베이스도, 실행해야 할 마이그레이션(migration)도, 인증해야 할 클라우드도 없습니다. 실제로 필요할 때 SQL 기반 저장소를 추가하세요.

로컬 우선. 당신의 개인적인 그래프는 레포지토리 외부에 존재하며, 절대 경로로 지정됩니다. 공개 레포지토리에는 코드, 문서, 그리고 가상의 데모 그래프만 포함됩니다.

모든 것과 호환됨

백엔드 설치
Claude (Anthropic API): pip install -e "[anthropic]"
GPT (OpenAI API): pip install -e "[openai]"
Ollama (로컬): pip install -e "[ollama]"
API 없음 (앱 세션): 설치 불필요 — candidates JSON 파일만 가져오면 됩니다.

ollama_proxy/ 패키지는 MCP 래퍼(server.py)도 함께 제공하므로 Claude/Cowork 스타일의 도구 사용(tool use)에 연결할 수 있습니다.

나를 놀라게 한 점

이것을 구축하면서 내가 실제로 알고 있는 것과 내 프로젝트에 대해 가정하고 있는 것 사이의 차이에 대해 솔직해질 수밖에 없었습니다. LLM이 추출한 각 주장을 수락하거나 거부하는 검토 단계는 그래프와는 별개로 그 자체만으로도 매우 유용하다는 사실을 알게 되었습니다.

이는 자신의 노트를 주의 깊게 읽고 결정하게 만드는 강제 함수 (forcing function) 역할을 합니다. 즉, '이것이 실제로 결정된 사항인가, 아니면 여전히 질문 상태인가?', '이 주장은 실제 근거에 기반하고 있는가, 아니면 단순히 내가 단언한 것인가?'를 판단하게 합니다. 그래프는 나의 사고 과정을 내가 읽을 수 있게(legible) 만들어 주었습니다. 이는 AI가 내 사고를 읽을 수 있게 만들었고, 결과적으로 AI가 두 번째, 세 번째, 그리고 쉰 번째 대화에서도 실제로 유용하게 쓰일 수 있도록 만들었습니다.

직접 시도해 보세요

git clone https://github.com/rahulmranga/knowledge-worker
cd knowledge-worker
MYGRAPH_PATH = examples/demo_graph.json
python3 mygraph/mygraph.py query provenance

API 키가 필요 없습니다. 별도의 설치도 필요 없습니다. 오직 Python 3.10+ 버전만 있으면 됩니다. 만약 일주일 동안 같은 맥락을 AI에게 세 번 이상 다시 설명한 적이 있다면, 제가 이 도구를 만든 이유는 바로 그 일을 멈추기 위해서였습니다.

GitHub: rahulmranga/knowledge-worker
MIT 라이선스. 로컬 우선 (Local-first). 표준 라이브러리(stdlib)만 사용하는 코어 구성.