Skip to content
Back to search

file-system-brain-mcp

Self-improving, AI-native markdown vault you hand to an AI agent. GitHub-style file tree + Notion editing, exposed to Claude/Cursor via a built-in MCP server (24 tools): semantic & hybrid search, RAG, cited answers. Learns your voice from your edits; human-approved review queue. Local-first .md.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/andylow92--file-system-brain-mcp/badge.svg)](/listings/andylow92--file-system-brain-mcp)

HTML

<a href="/listings/andylow92--file-system-brain-mcp"><img src="/api/listings/andylow92--file-system-brain-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1) Prerequisites

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

2) Install

npm install

3) Run API + Web (two terminals)

Terminal A:

npm run dev:api

Terminal B:

npm run dev:web

4) Open the app

- Web UI: `http://localhost:5173` - API health: `http://localhost:3001/health`

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 431 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="apps/web/public/logo.svg" alt="fsbrain — AI-native markdown vault" width="520" />
  3. </p>
  4. <p align="center">
  5. <strong>Own the context. Rent the memory.</strong><br />
  6. <em>Your notes stay plain <code>.md</code> files you own — bring any AI model and swap it whenever you like.</em>
  7. </p>
  8. # fsbrain — an AI-native markdown vault (MCP server + second brain)
  9. > **A local-first markdown vault you can hand to an AI agent — and it gets better
  10. > the more you use it.** Browse it like a **GitHub file tree**, edit it like
  11. > **Notion**, and plug it into Claude, Cursor, or any **MCP** host as **27 agent
  12. > tools** — semantic & hybrid search, RAG context, and cited answers. The vault
  13. > **self-improves**: it learns your writing voice from your draft→final edits and
  14. > self-tidies broken links, orphans, and duplicates — every change lands in a
  15. > **human-in-the-loop review queue** where agents propose and you decide. Plain
  16. > `.md` files, runs offline, no API key required.
  17. [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](#)
  18. [![React](https://img.shields.io/badge/React-18-61DAFB?logo=react&logoColor=000)](#)
  19. [![Node.js](https://img.shields.io/badge/Node.js-22.x-339933?logo=node.js&logoColor=white)](#)
  20. [![Vite](https://img.shields.io/badge/Vite-5.x-646CFF?logo=vite&logoColor=white)](#)
  21. If you’ve ever wanted your markdown content to be:
  22. - **easy to navigate** like a repo,
  23. - **easy to edit** like a modern docs tool,
  24. - and **stored as real files** (not locked in a database),
  25. this project is for you.
  26. ---
  27. ## Why this project exists
  28. Most note/documentation tools force a tradeoff:
  29. - Great UX, but proprietary storage.
  30. - Great storage (plain files), but clunky UX.
  31. This repo bridges both worlds:
  32. - ✅ Familiar tree-based navigation
  33. - ✅ Markdown-first editing and preview
  34. - ✅ Safe filesystem-backed API
  35. - ✅ Monorepo structure for easy extension
  36. ---
  37. ## What you can do with it
  38. - Browse markdown content in a GitHub-like file tree
  39. - Open files and switch between **Preview** and **Edit** tabs
  40. - Create, rename/move, and delete files and folders
  41. - Save with optimistic concurrency metadata (`etag` / `lastModified`)
  42. - Keep your content under a configurable `CONTENT_ROOT` (the "vault")
  43. - Search across notes — **full-text**, **semantic**, and **hybrid** (Ctrl/Cmd-K)
  44. - Link notes with `[[wikilinks]]`, browse **backlinks**, and explore an
  45. interactive **knowledge graph**
  46. - Hand the vault to an AI agent through a built-in **MCP server**
  47. (read / search / patch / propose), with every agent write attributed in an
  48. audit log so the human can see what changed
  49. ---
  50. ## 🤖 AI & agent features
  51. This isn't just a file browser — the vault is built to double as **an AI agent's
  52. brain**, with a human always in control. Everything below runs **locally and
  53. offline by default** (no API key needed), and anything an agent wants to change
  54. in your notes goes through a **review queue you approve**.
  55. - **🔎 Smart search.** Find notes by **meaning**, not just exact words —
  56. `semantic` search ranks by relevance and `hybrid` search fuses keyword +
  57. semantic results. Great for _"I know I wrote this somewhere…"_. Runs offline
  58. on a built-in TF-IDF ranker by default; flip on **real embeddings** (below)
  59. when you want stronger synonym/paraphrase matching.
  60. - **💬 Ask your notes (`think`).** Ask a question and get a **cited answer**
  61. assembled from your own notes — plus an honest list of **gaps** when the vault
  62. can't fully answer, so you know what's missing.
  63. - **🔌 Plug in any AI agent (MCP).** A built-in
  64. [MCP](https://modelcontextprotocol.io) server hands the whole vault to agents
  65. like Claude, Cursor, or OpenClaw as **27 tools** (read, search, patch,
  66. propose…). **Every agent write is logged** to an audit trail, and edits land as
  67. **proposals you approve** — the agent suggests, only you commit.
  68. - **🧹 Self-tidying vault (maintenance).** A "dream-cycle" scan finds **broken
  69. links, orphaned notes, near-duplicates, stale-but-load-bearing notes**
  70. (heavily linked yet long unchanged — "is this still accurate?"), **and schema
  71. issues** (a note typed wrong, or a relation pointing at the wrong kind of note)
  72. and files each fix as a proposal. Re-running is safe — it never spams your
  73. review queue, and it **learns your taste**: the duplicate-detection bar
  74. self-tunes from which proposals you approve vs. reject.
  75. - **🏷️ NEW — Typed notes (schema packs).** Give a note a `type:` (person,
  76. meeting, project, idea…) and the graph **colours it by what it is**, agents
  77. learn the canonical types to author well-formed notes, and the maintenance scan
  78. flags notes that break the vocabulary — all from plain frontmatter, no database.
  79. - **🧠 NEW — Real embeddings (opt-in).** Semantic search is TF-IDF by default —
  80. fully offline, no key. Set `FSBRAIN_EMBEDDINGS=on` with an API key and the same
  81. search routes rank by **dense vector similarity** instead, so paraphrases and
  82. synonyms that share no keywords still match. It's a **drop-in swap**: nothing
  83. downstream (`semantic`/`hybrid` search, `think`, RAG context) changes, only the
  84. scoring improves. Vectors are **cached to `.fsbrain/embeddings.json`** so a
  85. restart re-embeds only changed notes, and the engine **falls back to TF-IDF**
  86. on any provider outage — "off" is always a working search. See the
  87. `FSBRAIN_EMBEDDINGS` env vars below.
  88. - **🪄 NEW — Learns from your edits (feedback loop).** When an agent drafts
  89. outreach — an **X post, LinkedIn message, or email** — and you rewrite it
  90. before sending, that edit is valuable signal. A scan compares the **draft vs.
  91. your final version**, distills _what you changed (and why)_ into a reusable
  92. **playbook lesson**, and files it as a proposal. Over time the vault writes
  93. more like _you_. **Nothing is ever auto-posted or sent** — it only proposes
  94. notes for your review.
  95. > **The throughline: agents propose, you decide.** Risky or outward-facing
  96. > changes are never applied automatically — they become reviewable proposals
  97. > attributed to a named actor (e.g. `agent:maintenance`, `agent:feedback-loop`),
  98. > so you always see who suggested what.
  99. **The feedback loop in 30 seconds:**
  100. 1. An agent drafts a post at `social/x/drafts/launch.md`.
  101. 2. You edit it and save what you actually shipped to `social/x/old-posts/launch.md`.
  102. 3. You add a tiny "pairing" note linking the two (frontmatter: `type: feedback`,
  103. `channel: x`, `draftPath`, `finalPath`, and an optional `reviewReason`).
  104. 4. Run the `run_feedback` agent tool (or `POST /api/feedback/scan`). It compares
  105. the two, distills the lesson into a channel **playbook**, and files it as a
  106. **proposal** you approve in the Review tab.
  107. ---
  108. ## Built for real-world use cases
  109. - Personal knowledge management (PKM)
  110. - Team docs portals
  111. - Internal runbooks/playbooks
  112. - Product/project documentation
  113. - Lightweight markdown CMS foundations
  114. ---
  115. ## Architecture at a glance
  116. ```txt
  117. apps/web (React + Vite)
  118. ├─ File tree + editor / preview / graph / activity UI
  119. └─ Calls the API over HTTP/JSON (live updates over SSE)
  120. apps/api (Node HTTP server)
  121. ├─ Validates and resolves logical paths (sandboxed to CONTENT_ROOT)
  122. ├─ Markdown-focused file CRUD + optimistic concurrency
  123. └─ Search (text/semantic/hybrid), backlinks, graph, think, audit, proposals
  124. apps/mcp (MCP stdio server)
  125. ├─ Exposes the vault to AI agents as 27 tools
  126. └─ Embeds the API in-process — one self-contained command for an MCP host
  127. packages/shared
  128. └─ Shared TypeScript contracts + pure helpers (markdown, search, graph, …)
  129. ```
  130. Repository structure:
  131. ```txt
  132. apps/
  133. api/ # Backend HTTP server + filesystem storage (CONTENT_ROOT)
  134. web/ # Frontend UI (React + Vite)
  135. mcp/ # MCP stdio server — the vault as agent tools (embeds the API)
  136. packages/
  137. shared/ # Shared types/contracts + pure helpers
  138. docs/
  139. implementation.md # Source of truth for project state
  140. CONNECT.md # Connect an MCP host (OpenClaw / Claude / Cursor)
  141. integration-test-plan.md # Manual integration checks
  142. AGENTS.md # Start here if you are an AI agent working in this repo
  143. ```
  144. ---
  145. ## Quick start (under 5 minutes)
  146. ### 1) Prerequisites
  147. - Node.js **22.x**
  148. - npm **10.x**
  149. ### 2) Install
  150. ```bash
  151. npm install
  152. ```
  153. ### 3) Run API + Web (two terminals)
  154. Terminal A:
  155. ```bash
  156. npm run dev:api
  157. ```
  158. Terminal B:
  159. ```bash
  160. npm run dev:web
  161. ```
  162. ### 4) Open the app
  163. - Web UI: `http://localhost:5173`
  164. - API health: `http://localhost:3001/health`
  165. ---
  166. ## Use it as an agent's brain (clone & run)
  167. Skip the web UI and hand the vault to an MCP-aware agent (OpenClaw, Claude
  168. Desktop, Claude Code, Cursor, …):
  169. ```bash
  170. git clone https://github.com/andylow92/file-system-like-github.git
  171. cd file-system-like-github
  172. npm install
  173. npm run build # produces apps/mcp/dist/server.js
  174. npm run start:agent # launches the self-contained fsbrain-mcp on stdio
  175. ```
  176. `fsbrain-mcp` embeds the storage API in-process and auto-creates the vault
  177. at `~/.fsbrain/vault` (override with `CONTENT_ROOT=...`). It exposes 27
  178. vault tools (`list_notes`, `read_note`, `create_note`, `patch_note`,
  179. `semantic_search`, `hybrid_search`, `think`, `get_graph`, `propose_edit`,
  180. `run_maintenance`, `list_skills`, `curate_skills`, `run_feedback`, `proposal_stats`, …) and records every agent write to
  181. `<vault>/.fsbrain/audit.jsonl` so you can always see what the agent did.
  182. **Copy-paste config snippets** for OpenClaw / Claude Desktop / Claude Code
  183. / Cursor are in **[`docs/CONNECT.md`](docs/CONNECT.md)**.
  184. > **Heads-up if you have an older clone.** The default `CONTENT_ROOT` is now
  185. > `~/.fsbrain/vault` (previously `<cwd>/content`). Existing `./content`
  186. > notes aren't deleted, but `npm run dev:api` / `npm run dev:web` /
  187. > `npm run start:agent` without `CONTENT_ROOT` set will now read the new
  188. > path. Set `CONTENT_ROOT=./content` (in `apps/api/.env` or your shell) to
  189. > keep the old location.
  190. ---
  191. ## Optional integrations
  192. ### RocketReach (prospect research)
  193. An **opt-in** integration that lets connected agents run structured, auditable
  194. prospect research. It is **disabled by default** — vaults that do no prospect
  195. research never see the tools or get asked to configure anything.
  196. - **Enable it** from the web UI: the ⚙ **Settings** button in the top bar →
  197. **Integrations** → toggle RocketReach on, paste your
  198. [RocketReach API key](https://rocketreach.co/api), and **Test connection**. The
  199. key is stored only in `<vault>/.fsbrain/integrations.json` (owner-only, never in
  200. a note, never committed) and is never shown again once saved.
  201. - **Then restart the MCP server** (`npm run start:agent`) and reconnect your
  202. agent. The server decides which tools to register at startup, so the
  203. `rocketreach_*` tools do not appear in an already-running session. Turning the
  204. integration _off_ needs no restart — calls fail closed immediately.
  205. - **Agent tools** (exposed only while enabled): `rocketreach_get_account_status`,
  206. `rocketreach_start_intake` (standardized intake questions to ask before
  207. spending credits), `rocketreach_search_contacts` (search-only — no paid
  208. lookups), and `rocketreach_lookup_contacts` (paid enrichment, which **requires
  209. an explicit `maxLookups` cap** and never exceeds it).
  210. - **Safety:** every call **fails closed** if the integration is disabled or the
  211. key is missing — even if it was turned off after the MCP server started. API
  212. keys are redacted from all responses, errors, and logs. Runs can be saved into
  213. the vault as `prospects/…` notes with full provenance (actor, timestamp,
  214. normalized parameters, credit deltas).
  215. ---
  216. ## Environment variables
  217. For `apps/api`:
  218. - `CONTENT_ROOT`
  219. - Base directory (the "vault") for markdown files/directories.
  220. - If unset, defaults to `~/.fsbrain/vault` (auto-created on first run).
  221. - Set `CONTENT_ROOT=./content` to keep an older clone's location.
  222. - `PORT`
  223. - API server port (default: `3001`).
  224. - `FSBRAIN_EMBEDDINGS`
  225. - Opt-in switch for the **embedding** retrieval engine. Off by default
  226. (`1`/`true`/`on`/`yes` turns it on); when off, semantic search uses the
  227. fully-offline TF-IDF engine — no network, no key, exactly as before.
  228. - When on, needs a key: `EMBEDDINGS_API_KEY` (falls back to
  229. `OPENROUTER_API_KEY`). If the provider is unreachable or misconfigured,
  230. retrieval automatically falls back to TF-IDF, so "off" is always a working
  231. search — flip the flag off and restart to revert entirely.
  232. - Optional overrides: `EMBEDDINGS_MODEL` (default
  233. `openai/text-embedding-3-small`), `EMBEDDINGS_URL` (any OpenAI-compatible
  234. `/v1/embeddings` endpoint; default OpenRouter), `EMBEDDINGS_BATCH_SIZE`
  235. (default `96`).
  236. - Vectors are cached to `<CONTENT_ROOT>/.fsbrain/embeddings.json` so a restart
  237. re-embeds only changed notes. The file is safe to delete (it rebuilds on
  238. demand) and is tagged with the model, so switching `EMBEDDINGS_MODEL`
  239. invalidates it automatically.
  240. Example:
  241. ```bash
  242. CONTENT_ROOT=/absolute/path/to/vault PORT=3001 npm run dev:api
  243. # Opt into embedding-based semantic search:
  244. FSBRAIN_EMBEDDINGS=on EMBEDDINGS_API_KEY=sk-... npm run dev:api
  245. ```
  246. ---
  247. ## API snapshot
  248. **Files & tree**
  249. - `GET /health`
  250. - `GET /api/tree?path=...`
  251. - `GET /api/file?path=...` (or `?id=...`)
  252. - `POST /api/file` · `PUT /api/file` · `PATCH /api/file` (granular ops)
  253. - `POST /api/dir`
  254. - `PATCH /api/path` (move/rename) · `DELETE /api/path?path=...&recursive=true|false`
  255. **Links, graph & blocks**
  256. - `GET /api/backlinks` · `GET /api/graph`
  257. - `GET /api/block` · `GET /api/block-anchors`
  258. **Search & retrieval**
  259. - `GET /api/search` · `GET /api/semantic-search` · `GET /api/hybrid-search`
  260. - `GET /api/context` (RAG bundle) · `GET /api/think` (cited answer kit)
  261. **Provenance, review & maintenance**
  262. - `GET /api/audit`
  263. - `GET /api/proposals` · `POST /api/proposals` · `POST /api/proposals/resolve` (human-only)
  264. - `GET /api/proposals/stats` (review-queue approval rates + threshold nudges)
  265. - `GET /api/maintenance` · `POST /api/maintenance/scan`
  266. - `GET /api/skills/curator` (report-only skill-library curator)
  267. - `GET /api/feedback` · `POST /api/feedback/scan`
  268. **Live**
  269. - `GET /api/events` (Server-Sent Events)
  270. For endpoint details and request/response examples, see [`apps/api/README.md`](apps/api/README.md).
  271. Agents typically reach these via the MCP tools — see [`apps/mcp/README.md`](apps/mcp/README.md).
  272. ---
  273. ## Local quality checks
  274. ```bash
  275. npm test
  276. npm run lint
  277. npm run format
  278. ```
  279. ---
  280. ## Security model (important)
  281. - API path handling rejects traversal and absolute paths.
  282. - File operations are markdown-focused (`.md`).
  283. - Storage resolution ensures requests remain within `CONTENT_ROOT`.
  284. This helps protect the host filesystem while still enabling file-based workflows.
  285. ---
  286. ## Deployment note
  287. For persistent content in production, mount a host volume and point `CONTENT_ROOT` to it.
  288. See the full deployment examples in this README’s history and backend docs.
  289. ---
  290. ## Roadmap ideas
  291. - ✅ Search across markdown files (full-text, semantic, and **hybrid** RRF)
  292. - ✅ Interactive knowledge graph + backlinks
  293. - ✅ Built-in MCP server — use the vault as an agent's brain
  294. - ✅ Cited answers + offline gap analysis (`think`) and dream-cycle maintenance
  295. - ✅ Self-improving outreach **feedback loop** — learns your voice from draft→final edits
  296. - ✅ Typed page types / **schema packs** — canonical `type:`s, graph colouring, validation
  297. - ✅ Mermaid diagrams — fenced ` ```mermaid ` blocks render as SVG in the preview
  298. - Real vector embeddings (the cached index is the seam)
  299. - Git sync workflows
  300. - Multi-user auth + permissions
  301. - Real-time collaborative editing
  302. - Pluggable storage adapters
  303. ---
  304. ## Contributing
  305. PRs are welcome. If you want to contribute:
  306. 1. Open an issue with the use case/problem statement.
  307. 2. Submit a focused PR with tests.
  308. 3. Keep markdown/file safety guarantees intact.
  309. ---
  310. ## Extra docs
  311. - **AI agents start here:** [`AGENTS.md`](AGENTS.md) — repo entry point + a
  312. tool/endpoint quick-reference
  313. - Project state / roadmap (source of truth): [`docs/implementation.md`](docs/implementation.md)
  314. - Backend API details: [`apps/api/README.md`](apps/api/README.md)
  315. - Agent tools (MCP) + write attribution: [`apps/mcp/README.md`](apps/mcp/README.md)
  316. - Connect an MCP host (OpenClaw / Claude / Cursor): [`docs/CONNECT.md`](docs/CONNECT.md)
  317. - Manual integration validation: [`docs/integration-test-plan.md`](docs/integration-test-plan.md)
  318. ---
  319. ## Keywords (for discoverability)
  320. **AI-native:** MCP server, Model Context Protocol, AI agent tools, agent memory,
  321. self-improving knowledge base, learns-from-edits feedback loop, self-healing
  322. maintenance, agentic RAG, retrieval-augmented generation, semantic search, hybrid
  323. search (RRF), vector-ready knowledge base, Claude / Cursor / OpenClaw integration,
  324. second brain for LLMs, human-in-the-loop, agent proposals & audit log, cited answers.
  325. **Markdown workspace:** github-like file tree, notion-style markdown editor,
  326. local-first markdown vault, filesystem CMS, markdown knowledge base, wikilinks &
  327. backlinks, knowledge graph, react markdown editor, node filesystem api, PKM.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.