컨텍스트를 소유하세요. 메모리를 대여하세요.

당신의 노트는 당신이 소유한 일반적인 .md 파일로 유지됩니다 — 어떤 AI 모델이든 가져와서 원할 때마다 교체할 수 있습니다.

AI 에이전트에게 전달할 수 있는 로컬 우선 (local-first) 마크다운 볼트 (markdown vault) — 사용하면 할수록 더 좋아집니다. GitHub 파일 트리처럼 탐색하고, Notion처럼 편집하며, Claude, Cursor 또는 25개의 에이전트 도구로서의 모든 MCP 호스트에 연결하여 시맨틱(semantic) 및 하이브리드(hybrid) 검색, RAG 컨텍스트, 인용된 답변을 활용하세요. 볼트 자체적으로 개선됩니다: 초안에서 최종 편집본으로 넘어가는 과정을 통해 당신의 글쓰기 스타일을 학습하며, 깨진 링크, 고립된 파일(orphans), 중복 파일을 스스로 정리합니다 — 모든 변경 사항은 에이전트가 제안하고 당신이 결정하는 human-in-the-loop 검토 대기열에 기록됩니다. 일반 .md 파일이며, 오프라인에서 실행되고, API 키가 필요하지 않습니다.

만약 당신의 마크다운 콘텐츠가 다음과 같기를 원했다면:

탐색하기 쉬운 (저장소(repo)처럼),
편집하기 쉬운 (현대적인 문서 도구처럼),

• 그리고
  실제 파일로 저장되는 (데이터베이스에 갇히지 않고),

이 프로젝트는 당신을 위한 것입니다.

대부분의 노트/문서화 도구는 다음과 같은 트레이드오프(tradeoff)를 강요합니다:

• 훌륭한 UX, 하지만 독점적인 저장 방식.
• 훌륭한 저장 방식 (일반 파일), 하지만 불편한 UX.

이 리포지토리(repo)는 두 세계를 연결합니다:

• ✅ 익숙한 트리 기반 탐색

• ✅ 마크다운 우선 편집 및 미리보기

• ✅ 안전한 파일 시스템 기반 API

• ✅ 쉬운 확장을 위한 모노레포 (Monorepo) 구조

• GitHub와 유사한 파일 트리에서 마크다운 콘텐츠 탐색

• 파일을 열고 미리보기 (Preview) 및 편집 (Edit) 탭 간 전환

• 파일 및 폴더 생성, 이름 변경/이동, 삭제

• 낙관적 동시성 메타데이터 (etag / lastModified)를 사용하여 저장

• 설정 가능한 CONTENT_ROOT (볼트) 내에 콘텐츠 유지

• 노트 전체 검색 — 전체 텍스트 (full-text), 시맨틱 (semantic), 및 하이브리드 (hybrid) 검색 (Ctrl/Cmd-K)

• [[wikilinks]]로 노트 연결, 백링크 (backlinks) 탐색, 대화형 지식 그래프 (knowledge graph) 탐색

• 내장된 MCP 서버 (읽기 / 검색 / 패치 / 제안)를 통해 AI 에이전트에게 볼트 전달, 모든 에이전트의 쓰기 작업은 감사 로그(audit log)에 기록되어 사람이 무엇이 변경되었는지 확인할 수 있음

이것은 단순한 파일 브라우저가 아닙니다. 볼트(vault)는 사람이 항상 통제권을 갖는 가운데, AI 에이전트의 두뇌 (AI agent's brain) 역할을 겸하도록 설계되었습니다. 아래의 모든 기능은 **기본적으로 로컬 및 오프라인 (locally and offline by default)**으로 실행되며 (API 키가 필요 없음), 에이전트가 노트에서 변경하고자 하는 모든 사항은 **사용자가 승인하는 검토 대기열 (review queue you approve)**을 거칩니다.

🔎 스마트 검색 (Smart search). 단순히 정확한 단어가 아닌 **의미 (meaning)**를 통해 노트를 찾으세요. semantic 검색은 관련성에 따라 순위를 매기며, hybrid 검색은 키워드와 의미론적 결과를 결합합니다. "이 내용을 어딘가에 적어둔 것 같은데..."라고 생각할 때 매우 유용합니다.

💬 노트에 질문하기 (Ask your notes). 질문을 던지면 자신의 노트에서 조립된 **인용된 답변 (cited answer)**을 얻을 수 있습니다. 또한, 볼트가 완전히 답변할 수 없는 경우 공백 (gaps) 목록을 정직하게 제공하여 무엇이 누락되었는지 알 수 있게 합니다.

🔌 어떤 AI 에이전트든 연결 (MCP). 내장된 MCP 서버가 볼트 전체를 Claude, Cursor 또는 OpenClaw와 같은 에이전트에게 25개의 도구 (25 tools) (읽기, 검색, 패치, 제안 등)로서 전달합니다. 모든 에이전트의 쓰기 작업은 감사 로그 (audit trail)에 기록되며, 편집 사항은 사용자가 승인하는 제안 (proposals you approve) 형태로 전달됩니다. 에이전트는 제안만 할 뿐, 커밋(commit)은 오직 사용자만이 할 수 있습니다.

🧹 자가 정리 볼트 (유지보수). "드림 사이클 (dream-cycle)" 스캔을 통해 깨진 링크 (broken links), 고립된 노트 (orphaned notes), 유사 중복 (near-duplicates), 그리고 오래되었지만 중요한 노트 (stale-but-load-bearing notes) (링크는 많이 걸려 있지만 오랫동안 변경되지 않은 — "이 내용이 여전히 정확한가요?")를 찾아내고, 각 수정 사항을 제안으로 파일링합니다. 다시 실행해도 안전합니다. 검토 대기열을 스팸처럼 채우지 않으며, 사용자의 **취향을 학습 (learns your taste)**합니다. 사용자가 어떤 제안을 승인하고 거절하는지에 따라 중복 탐지 임계값이 스스로 조정됩니다.

🪄 신규 — 편집을 통한 학습 (피드백 루프). 에이전트가 X(구 트위터) 포스트, LinkedIn 메시지 또는 이메일과 같은 아웃리치(outreach) 초안을 작성했을 때, 사용자가 전송 전 이를 다시 작성한다면 그 편집은 가치 있는 신호가 됩니다. 스캔을 통해 **초안과 최종 버전 (draft vs. your final version)**을 비교하고, 무엇을 (그리고 왜) 변경했는지를 추출하여 재사용 가능한 **플레이북 레슨 (playbook lesson)**으로 만들고 이를 제안으로 파일링합니다. 시간이 흐를수록 볼트는 점점 사용자처럼 글을 쓰게 됩니다.

그 어떤 것도 자동으로 게시되거나 전송되지 않습니다. 볼트는 오직 사용자의 검토를 위한 제안만을 생성할 뿐입니다.

핵심 원칙: 에이전트가 제안하고, 당신이 결정합니다. 위험하거나 외부로 노출되는 변경 사항은 절대 자동으로 적용되지 않습니다. 대신 특정 이름의 액터(예: agent:maintenance, agent:feedback-loop)가 작성한 검토 가능한 제안(proposals)이 됩니다. 따라서 누가 무엇을 제안했는지 항상 확인할 수 있습니다.

30초 만에 이해하는 피드백 루프 (feedback loop):

• 에이전트가 social/x/drafts/launch.md에 게시물 초안을 작성합니다.

• 당신이 이를 편집하고 실제로 게시한 내용을 social/x/old-posts/launch.md에 저장합니다.

• 두 파일을 연결하는 아주 작은 "페어링(pairing)" 노트(frontmatter: type: feedback, channel: x, draftPath, finalPath, 그리고 선택 사항인 reviewReason)를 추가합니다.

• run_feedback 에이전트 도구(또는 POST /api/feedback/scan)를 실행합니다. 도구가 두 파일을 비교하여 교훈을 추출해 채널 **플레이북 (playbook)**으로 요약하고, 이를 검토(Review) 탭에서 당신이 승인할 수 있는 **제안 (proposal)**으로 등록합니다.

• 개인 지식 관리 (PKM)

• 팀 문서 포털

• 내부 런북/플레이북 (runbooks/playbooks)

• 제품/프로젝트 문서화

• 경량 마크다운 CMS 기반

apps/web (React + Vite)
├─ 파일 트리 + 에디터 / 미리보기 / 그래프 / 활동 UI
└─ HTTP/JSON을 통해 API 호출 (SSE를 통한 실시간 업데이트)
...

저장소 구조:

apps/
api/ # 백엔드 HTTP 서버 + 파일 시스템 저장소 (CONTENT_ROOT)
web/ # 프론트엔드 UI (React + Vite)
...

• Node.js 22.x - npm 10.x

npm install

터미널 A:

npm run dev:api

터미널 B:

npm run dev:web

• 웹 UI: http://localhost:5173
• API 상태 확인: http://localhost:3001/health

웹 UI를 건너뛰고 볼트(vault)를 MCP 인식 에이전트(OpenClaw, Claude Desktop, Claude Code, Cursor, …)에게 전달하세요:

git clone https://github.com/andylow92/file-system-like-github.git
cd file-system-like-github
npm install
...

fsbrain-mcp는 저장소 API를 프로세스 내에 내장(embeds)하고 ~/.fsbrain/vault 위치에 볼트를 자동으로 생성합니다 (CONTENT_ROOT=...로 재정의 가능). 이 도구는 25개의 볼트 도구(list_notes, read_note, create_note, patch_note, semantic_search, hybrid_search, think, get_graph, propose_edit 등)를 제공합니다.

run_maintenance,
list_skills,
run_feedback,
proposal_stats,

...) 및 에이전트의 모든 쓰기 작업을 <vault>/.fsbrain/audit.jsonl에 기록하여 에이전트가 무엇을 수행했는지 언제든 확인할 수 있습니다.

OpenClaw / Claude Desktop / Claude Code / Cursor를 위한 설정 스니펫 복사-붙여넣기는 docs/CONNECT.md에 있습니다.

이전 클론을 사용 중인 경우 주의하십시오. 기본 CONTENT_ROOT는 이제 ~/.fsbrain/vault입니다 (이전에는 <cwd>/content였습니다). 기존의 ./content 노트는 삭제되지 않지만, CONTENT_ROOT를 설정하지 않고 npm run dev:api / npm run dev:web / npm run start:agent를 실행하면 이제 새로운 경로를 읽게 됩니다. 이전 위치를 유지하려면 ( apps/api/.env 또는 셸에서) CONTENT_ROOT=./content로 설정하십시오.

apps/api용:

CONTENT_ROOT

• 마크다운 파일/디렉토리를 위한 기본 디렉토리 ("vault")입니다.
• 설정되지 않은 경우, ~/.fsbrain/vault가 기본값입니다 (첫 실행 시 자동 생성됨). 이전 클론의 위치를 유지하려면 CONTENT_ROOT=./content로 설정하십시오.

PORT

• API 서버 포트 (기본값: 3001).

예시:
CONTENT_ROOT=/absolute/path/to/vault PORT=3001 npm run dev:api

파일 및 트리 (Files & tree)

GET /health
GET /api/tree?path=...
GET /api/file?path=... (또는 ?id=...)
POST /api/file · PUT /api/file · PATCH /api/file (세부 작업)
POST /api/dir
PATCH /api/path (이동/이름 변경) · DELETE /api/path?path=...&recursive=true|false

링크, 그래프 및 블록 (Links, graph & blocks)

GET /api/backlinks · GET /api/graph
GET /api/block · GET /api/block-anchors

검색 및 검색 (Search & retrieval)

GET /api/search · GET /api/semantic-search · GET /api/hybrid-search
GET /api/context (RAG 번들) · GET /api/think (인용된 답변 키트)

출처, 검토 및 유지관리 (Provenance, review & maintenance)

GET /api/audit
GET /api/proposals · POST /api/proposals · POST /api/proposals/resolve (인간 전용)
GET /api/proposals/stats (검토 대기열 승인율 + 임계값 권고)
GET /api/maintenance · POST /api/maintenance/scan
GET /api/feedback · POST /api/feedback/scan

라이브 (Live)

GET /api/events

(Server-Sent Events (SSE))

엔드포인트 상세 정보 및 요청/응답 예시는 apps/api/README.md를 참조하세요.

.

에이전트(Agents)는 일반적으로 MCP 도구를 통해 여기에 도달합니다 — apps/mcp/README.md를 참조하세요.

.

npm test
npm run lint
npm run format

• API 경로 처리 시 트래버설 (traversal) 및 절대 경로를 거부합니다.
• 파일 작업은 마크다운 (markdown, .md)에 집중되어 있습니다.
• 스토리지 해결 (Storage resolution)을 통해 요청이 CONTENT_ROOT 내에 머물도록 보장합니다.

이는 파일 기반 워크플로를 가능하게 하면서도 호스트 파일 시스템을 보호하는 데 도움이 됩니다.

프로덕션 환경에서 콘텐츠를 영구적으로 보관하려면, 호스트 볼륨을 마운트하고 CONTENT_ROOT를 해당 볼륨으로 지정하세요.

이 README의 히스토리 및 백엔드 문서에서 전체 배포 예시를 확인하세요.

• ✅ 마크다운 파일 전반에 걸친 검색 (전체 텍스트, 시맨틱(semantic), 그리고 하이브리드 (hybrid) RRF)
• ✅ 대화형 지식 그래프 (knowledge graph) + 백링크 (backlinks)
• ✅ 내장된 MCP 서버 — 볼트(vault)를 에이전트의 두뇌로 사용
• ✅ 인용된 답변 + 오프라인 격차 분석 (think) 및 드림 사이클 (dream-cycle) 유지 관리
• ✅ 자기 개선형 아웃리치 피드백 루프 (feedback loop) — 초안에서 최종 편집까지 사용자의 말투를 학습
• ✅ Mermaid 다이어그램 + 실제 벡터 임베딩 (vector embeddings) (캐시된 인덱스가 이음새 역할을 함)
• ✅ Git 동기화 워크플로
• ✅ 다중 사용자 인증 (auth) + 권한
• ✅ 실시간 협업 편집
• ✅ 플러그형 스토리지 어댑터 (Pluggable storage adapters)

PR(Pull Requests)은 언제나 환영합니다. 기여하고 싶다면:

• 사용 사례/문제 정의를 포함한 이슈(issue)를 생성하세요.
• 테스트를 포함한 집중된 PR을 제출하세요.
• 마크다운/파일 안전 보장 기능을 온전하게 유지하세요.

AI 에이전트의 시작점: AGENTS.md — 리포지토리 진입점 + 도구/엔드포인트 빠른 참조

• 프로젝트 상태 / 로드맵 (신뢰할 수 있는 단일 출처, source of truth): docs/implementation.md
• 백엔드 API 상세 정보: apps/api/README.md
• 에이전트 도구 (MCP) + 쓰기 속성 (write attribution): apps/mcp/README.md
• MCP 호스트 연결 (OpenClaw / Claude / Cursor): docs/CONNECT.md
• 수동 통합 검증: docs/integration-test-plan.md

AI-native (AI 네이티브): MCP 서버 (MCP server), 모델 컨텍스트 프로토콜 (Model Context Protocol), AI 에이전트 도구 (AI agent tools), 에이전트 메모리 (agent memory), 자기 개선형 지식 베이스 (self-improving knowledge base), 편집으로부터 학습하는 피드백 루프 (learns-from-edits feedback loop), 자가 치유 유지보수 (self-healing maintenance), 에이전틱 RAG (agentic RAG), 검색 증강 생성 (retrieval-augmented generation), 시맨틱 검색 (semantic search), 하이브리드 검색 (hybrid search (RRF)), 벡터 준비 완료 지식 베이스 (vector-ready knowledge base), Claude / Cursor / OpenClaw 통합 (Claude / Cursor / OpenClaw integration), LLM을 위한 제2의 뇌 (second brain for LLMs), 인간 참여형 (human-in-the-loop), 에이전트 제안 및 감사 로그 (agent proposals & audit log), 인용된 답변 (cited answers).

Markdown workspace (마크다운 워크스페이스): GitHub 스타일의 파일 트리 (github-like file tree), Notion 스타일의 마크다운 에디터 (notion-style markdown editor), 로컬 우선 마크다운 볼트 (local-first markdown vault), 파일 시스템 CMS (filesystem CMS), 마크다운 지식 베이스 (markdown knowledge base), 위키링크 및 백링크 (wikilinks & backlinks), 지식 그래프 (knowledge graph), React 마크다운 에디터 (react markdown editor), Node 파일 시스템 API (node filesystem api), 개인 지식 관리 (PKM).