brainforge-mcp

Turn your markdown notes into an AI-powered knowledge graph.

This project implements Andrej Karpathy's LLM Wiki pattern as an MCP server. It converts markdown wikis into knowledge graphs, allowing them to be explored and analyzed by any LLM client.

Core Idea

[원본 자료]  →  [AI가 유지하는 위키]  →  [지식 그래프]  →  [LLM이 탐색·분석]
 논문, 기사       sources/                 graph.json       MCP 도구로 질의
 메모, 영상       concepts/                                  인과 관계 추적
                  entities/                                  건강 진단

What MCP tools do: Knowledge graph exploration, node analysis, causal chain tracking, and wiki health diagnostics. What the LLM does: Read source → Summarize → Create wiki pages → Insert wikilinks/causal relationships.

In short, brainforge-mcp acts as the "eyes" of the wiki, while the LLM acts as the "hands" of the wiki.

Related MCP server: vault-master-mcp

A-to-Z Example: From a single paper to a knowledge graph

Step 0: Installation + Initialization

uvx brainforge-mcp init ~/my-brain

Generated structure:

my-brain/
├── raw/              # 불변 원본 (사용자가 넣는 곳)
│   ├── papers/
│   ├── articles/
│   ├── transcripts/
│   └── notes/
├── wiki/             # AI가 유지하는 위키
│   ├── sources/
│   ├── concepts/
│   ├── entities/
│   ├── syntheses/
│   ├── index.md
│   └── log.md
└── output/           # 블로그, 포트폴리오 등

Step 1: Register with an MCP client

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "wiki": {
      "command": "uvx",
      "args": ["brainforge-mcp", "--vault", "~/my-brain/wiki"]
    }
  }
}

Kiro / Cursor / VS Code (mcp.json):

{
  "mcpServers": {
    "wiki": {
      "command": "uvx",
      "args": ["brainforge-mcp", "--vault", "~/my-brain/wiki"]
    }
  }
}

Step 2: Add source material

Convert a research paper PDF to markdown and save it in raw/papers/:

# 예: marker로 PDF → 마크다운 변환
marker_single "lora-paper.pdf" --output_dir ~/my-brain/raw/papers/

Or save a web article directly as markdown:

<!-- raw/articles/2026-04-17_lora-explained.md -->
---
title: "LoRA 논문 쉽게 설명하기"
source: https://example.com/lora
date: 2026-04-17
type: article
---

# LoRA 논문 쉽게 설명하기
LLM의 가중치를 Freeze하고 저랭크 행렬만 학습하여...

Step 3: Request ingestion from the LLM (What the LLM does)

In chat:

"raw/articles/2026-04-17_lora-explained.md를 읽고 위키에 인제스트해줘"

The LLM reads the source and generates the following files:

wiki/sources/lora-explained.md (Source summary):

---
title: "LoRA 논문 쉽게 설명하기"
created: 2026-04-17
updated: 2026-04-17
tags: [LoRA, Fine-Tuning, PEFT]
sources: [raw/articles/2026-04-17_lora-explained.md]
---

# LoRA 논문 쉽게 설명하기

## Kernel
모델 가중치를 Freeze하고 저랭크 행렬만 학습하여 VRAM 절감.

## 핵심 주장
1. Fully Fine-Tuning 대비 VRAM 대폭 절감
2. 성능은 동등하거나 우수
...

wiki/concepts/lora.md (Concept page):

---
title: LoRA (Low-Rank Adaptation)
created: 2026-04-17
updated: 2026-04-17
tags: [개념, Fine-Tuning, PEFT]
sources: [raw/articles/2026-04-17_lora-explained.md]
---

# LoRA (Low-Rank Adaptation)

## Kernel
가중치 행렬 W를 직접 업데이트하지 않고, 저랭크 행렬 LoRA_A·LoRA_B만 학습.

> [!causal] 인과 관계
> [[lora]] →(가능하게 함)→ [[fine-tuning]]의 효율적 수행
> 신뢰도: 높음 | 출처: [[lora-explained]]

## 관련
[[fine-tuning]], [[transformer]], [[quantization]]

Step 4: Build the graph (MCP tool)

In chat:

"위키 그래프 재빌드해줘"

→ The rebuild_graph tool is called to parse wikilinks + causal relationships from the wiki/ markdown and generate graph.json.

Step 5: Explore knowledge (MCP tool)

Now that the graph exists, you can explore it:

"LoRA가 내 위키에서 어떤 위치야?"

→ explain_node("LoRA") is called:

## LoRA (Low-Rank Adaptation)
카테고리: concepts | 태그: Fine-Tuning, PEFT

### 위치 분석
- 연결도: 9 (상위 26%) → 중간 연결자
- 인과 역할: 기반 기술 — 다른 1개 개념을 가능하게 함

### 인과 요약
- LoRA →(가능하게 함)→ Fine-Tuning의 효율적 수행

### 성장 제안
- 인과 관계 callout 추가 권장 (현재 1개)

"위키 상태 어때?"

→ graph_summary() is called:

## 위키 건강 리포트

### 규모: 초기 단계
- 실제 페이지: 5개 (concepts 2, sources 1, entities 1)
- 밀도: 2.4 엣지/노드 → 낮은 밀도 — 위키링크 추가 권장

### 약점
- 미해결 노드 3개 (37.5%)
- 인과 비율 5.0% — callout 추가 권장

### 다음 행동
1. 미해결 페이지 생성: transformer(2연결), quantization(1연결)

Features

• 🔗 Automatic knowledge graph building based on wikilinks + causal relationships

• 🧠 Semantic interpretation — Contextual analysis like "top 26% intermediate connector" rather than just "9 connections"

• 📊 Health diagnostics — Concrete suggestions for the wiki's strengths/weaknesses/next steps

• ⚡ Causal chain tracking — Analyze the "why" of connections between concepts upstream/downstream

• 🔌 MCP standard — Works anywhere, including Claude Desktop, Cursor, Kiro, and VS Code

Tool List

Note: Creating/editing wiki pages is done directly by the LLM, not by MCP tools. brainforge-mcp specializes in "reading + analysis," while "writing" is the LLM's role.

Causal Relationship Notation

Wikilinks ([[]]) only represent connections. The "why" behind the connection is specified via causal callouts:

> [!causal] 인과 관계
> [[메타러닝]] →(가능하게 함)→ [[DiscoRL]]의 RL 규칙 자동 발견
> 신뢰도: 높음 | 출처: [[discovering-sota-rl-algorithms]]

Supported relationship types:

• →(enables)→ / →(improves performance)→ / →(degrades performance)→

• →(is based on)→ / →(advances)→ / →(replaces)→

• →(includes)→ / →(is applied to)→

Applying to an existing Obsidian vault

If you are already using Obsidian, you can create a wiki/ folder inside your vault and specify it with the --vault option. It will automatically parse existing [[wikilinks]].

License

MIT

Inspired by Andrej Karpathy's LLM Wiki idea.