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.
Badge for your README
Markdown
[](/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
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)
- <p align="center">
- <img src="apps/web/public/logo.svg" alt="fsbrain — AI-native markdown vault" width="520" />
- </p>
- <p align="center">
- <strong>Own the context. Rent the memory.</strong><br />
- <em>Your notes stay plain <code>.md</code> files you own — bring any AI model and swap it whenever you like.</em>
- </p>
- # fsbrain — an AI-native markdown vault (MCP server + second brain)
- > **A local-first markdown vault you can hand to an AI agent — and it gets better
- > the more you use it.** Browse it like a **GitHub file tree**, edit it like
- > **Notion**, and plug it into Claude, Cursor, or any **MCP** host as **27 agent
- > tools** — semantic & hybrid search, RAG context, and cited answers. The vault
- > **self-improves**: it learns your writing voice from your draft→final edits and
- > self-tidies broken links, orphans, and duplicates — every change lands in a
- > **human-in-the-loop review queue** where agents propose and you decide. Plain
- > `.md` files, runs offline, no API key required.
- [](#)
- [](#)
- [](#)
- [](#)
- If you’ve ever wanted your markdown content to be:
- - **easy to navigate** like a repo,
- - **easy to edit** like a modern docs tool,
- - and **stored as real files** (not locked in a database),
- this project is for you.
- ---
- ## Why this project exists
- Most note/documentation tools force a tradeoff:
- - Great UX, but proprietary storage.
- - Great storage (plain files), but clunky UX.
- This repo bridges both worlds:
- - ✅ Familiar tree-based navigation
- - ✅ Markdown-first editing and preview
- - ✅ Safe filesystem-backed API
- - ✅ Monorepo structure for easy extension
- ---
- ## What you can do with it
- - Browse markdown content in a GitHub-like file tree
- - Open files and switch between **Preview** and **Edit** tabs
- - Create, rename/move, and delete files and folders
- - Save with optimistic concurrency metadata (`etag` / `lastModified`)
- - Keep your content under a configurable `CONTENT_ROOT` (the "vault")
- - Search across notes — **full-text**, **semantic**, and **hybrid** (Ctrl/Cmd-K)
- - Link notes with `[[wikilinks]]`, browse **backlinks**, and explore an
- interactive **knowledge graph**
- - Hand the vault to an AI agent through a built-in **MCP server**
- (read / search / patch / propose), with every agent write attributed in an
- audit log so the human can see what changed
- ---
- ## 🤖 AI & agent features
- This isn't just a file browser — the vault is built to double as **an AI agent's
- brain**, with a human always in control. Everything below runs **locally and
- offline by default** (no API key needed), and anything an agent wants to change
- in your notes goes through a **review queue you approve**.
- - **🔎 Smart search.** Find notes by **meaning**, not just exact words —
- `semantic` search ranks by relevance and `hybrid` search fuses keyword +
- semantic results. Great for _"I know I wrote this somewhere…"_. Runs offline
- on a built-in TF-IDF ranker by default; flip on **real embeddings** (below)
- when you want stronger synonym/paraphrase matching.
- - **💬 Ask your notes (`think`).** Ask a question and get a **cited answer**
- assembled from your own notes — plus an honest list of **gaps** when the vault
- can't fully answer, so you know what's missing.
- - **🔌 Plug in any AI agent (MCP).** A built-in
- [MCP](https://modelcontextprotocol.io) server hands the whole vault to agents
- like Claude, Cursor, or OpenClaw as **27 tools** (read, search, patch,
- propose…). **Every agent write is logged** to an audit trail, and edits land as
- **proposals you approve** — the agent suggests, only you commit.
- - **🧹 Self-tidying vault (maintenance).** A "dream-cycle" scan finds **broken
- links, orphaned notes, near-duplicates, stale-but-load-bearing notes**
- (heavily linked yet long unchanged — "is this still accurate?"), **and schema
- issues** (a note typed wrong, or a relation pointing at the wrong kind of note)
- and files each fix as a proposal. Re-running is safe — it never spams your
- review queue, and it **learns your taste**: the duplicate-detection bar
- self-tunes from which proposals you approve vs. reject.
- - **🏷️ NEW — Typed notes (schema packs).** Give a note a `type:` (person,
- meeting, project, idea…) and the graph **colours it by what it is**, agents
- learn the canonical types to author well-formed notes, and the maintenance scan
- flags notes that break the vocabulary — all from plain frontmatter, no database.
- - **🧠 NEW — Real embeddings (opt-in).** Semantic search is TF-IDF by default —
- fully offline, no key. Set `FSBRAIN_EMBEDDINGS=on` with an API key and the same
- search routes rank by **dense vector similarity** instead, so paraphrases and
- synonyms that share no keywords still match. It's a **drop-in swap**: nothing
- downstream (`semantic`/`hybrid` search, `think`, RAG context) changes, only the
- scoring improves. Vectors are **cached to `.fsbrain/embeddings.json`** so a
- restart re-embeds only changed notes, and the engine **falls back to TF-IDF**
- on any provider outage — "off" is always a working search. See the
- `FSBRAIN_EMBEDDINGS` env vars below.
- - **🪄 NEW — Learns from your edits (feedback loop).** When an agent drafts
- outreach — an **X post, LinkedIn message, or email** — and you rewrite it
- before sending, that edit is valuable signal. A scan compares the **draft vs.
- your final version**, distills _what you changed (and why)_ into a reusable
- **playbook lesson**, and files it as a proposal. Over time the vault writes
- more like _you_. **Nothing is ever auto-posted or sent** — it only proposes
- notes for your review.
- > **The throughline: agents propose, you decide.** Risky or outward-facing
- > changes are never applied automatically — they become reviewable proposals
- > attributed to a named actor (e.g. `agent:maintenance`, `agent:feedback-loop`),
- > so you always see who suggested what.
- **The feedback loop in 30 seconds:**
- 1. An agent drafts a post at `social/x/drafts/launch.md`.
- 2. You edit it and save what you actually shipped to `social/x/old-posts/launch.md`.
- 3. You add a tiny "pairing" note linking the two (frontmatter: `type: feedback`,
- `channel: x`, `draftPath`, `finalPath`, and an optional `reviewReason`).
- 4. Run the `run_feedback` agent tool (or `POST /api/feedback/scan`). It compares
- the two, distills the lesson into a channel **playbook**, and files it as a
- **proposal** you approve in the Review tab.
- ---
- ## Built for real-world use cases
- - Personal knowledge management (PKM)
- - Team docs portals
- - Internal runbooks/playbooks
- - Product/project documentation
- - Lightweight markdown CMS foundations
- ---
- ## Architecture at a glance
- ```txt
- apps/web (React + Vite)
- ├─ File tree + editor / preview / graph / activity UI
- └─ Calls the API over HTTP/JSON (live updates over SSE)
- apps/api (Node HTTP server)
- ├─ Validates and resolves logical paths (sandboxed to CONTENT_ROOT)
- ├─ Markdown-focused file CRUD + optimistic concurrency
- └─ Search (text/semantic/hybrid), backlinks, graph, think, audit, proposals
- apps/mcp (MCP stdio server)
- ├─ Exposes the vault to AI agents as 27 tools
- └─ Embeds the API in-process — one self-contained command for an MCP host
- packages/shared
- └─ Shared TypeScript contracts + pure helpers (markdown, search, graph, …)
- ```
- Repository structure:
- ```txt
- apps/
- api/ # Backend HTTP server + filesystem storage (CONTENT_ROOT)
- web/ # Frontend UI (React + Vite)
- mcp/ # MCP stdio server — the vault as agent tools (embeds the API)
- packages/
- shared/ # Shared types/contracts + pure helpers
- docs/
- implementation.md # Source of truth for project state
- CONNECT.md # Connect an MCP host (OpenClaw / Claude / Cursor)
- integration-test-plan.md # Manual integration checks
- AGENTS.md # Start here if you are an AI agent working in this repo
- ```
- ---
- ## Quick start (under 5 minutes)
- ### 1) Prerequisites
- - Node.js **22.x**
- - npm **10.x**
- ### 2) Install
- ```bash
- npm install
- ```
- ### 3) Run API + Web (two terminals)
- Terminal A:
- ```bash
- npm run dev:api
- ```
- Terminal B:
- ```bash
- npm run dev:web
- ```
- ### 4) Open the app
- - Web UI: `http://localhost:5173`
- - API health: `http://localhost:3001/health`
- ---
- ## Use it as an agent's brain (clone & run)
- Skip the web UI and hand the vault to an MCP-aware agent (OpenClaw, Claude
- Desktop, Claude Code, Cursor, …):
- ```bash
- git clone https://github.com/andylow92/file-system-like-github.git
- cd file-system-like-github
- npm install
- npm run build # produces apps/mcp/dist/server.js
- npm run start:agent # launches the self-contained fsbrain-mcp on stdio
- ```
- `fsbrain-mcp` embeds the storage API in-process and auto-creates the vault
- at `~/.fsbrain/vault` (override with `CONTENT_ROOT=...`). It exposes 27
- vault tools (`list_notes`, `read_note`, `create_note`, `patch_note`,
- `semantic_search`, `hybrid_search`, `think`, `get_graph`, `propose_edit`,
- `run_maintenance`, `list_skills`, `curate_skills`, `run_feedback`, `proposal_stats`, …) and records every agent write to
- `<vault>/.fsbrain/audit.jsonl` so you can always see what the agent did.
- **Copy-paste config snippets** for OpenClaw / Claude Desktop / Claude Code
- / Cursor are in **[`docs/CONNECT.md`](docs/CONNECT.md)**.
- > **Heads-up if you have an older clone.** The default `CONTENT_ROOT` is now
- > `~/.fsbrain/vault` (previously `<cwd>/content`). Existing `./content`
- > notes aren't deleted, but `npm run dev:api` / `npm run dev:web` /
- > `npm run start:agent` without `CONTENT_ROOT` set will now read the new
- > path. Set `CONTENT_ROOT=./content` (in `apps/api/.env` or your shell) to
- > keep the old location.
- ---
- ## Optional integrations
- ### RocketReach (prospect research)
- An **opt-in** integration that lets connected agents run structured, auditable
- prospect research. It is **disabled by default** — vaults that do no prospect
- research never see the tools or get asked to configure anything.
- - **Enable it** from the web UI: the ⚙ **Settings** button in the top bar →
- **Integrations** → toggle RocketReach on, paste your
- [RocketReach API key](https://rocketreach.co/api), and **Test connection**. The
- key is stored only in `<vault>/.fsbrain/integrations.json` (owner-only, never in
- a note, never committed) and is never shown again once saved.
- - **Then restart the MCP server** (`npm run start:agent`) and reconnect your
- agent. The server decides which tools to register at startup, so the
- `rocketreach_*` tools do not appear in an already-running session. Turning the
- integration _off_ needs no restart — calls fail closed immediately.
- - **Agent tools** (exposed only while enabled): `rocketreach_get_account_status`,
- `rocketreach_start_intake` (standardized intake questions to ask before
- spending credits), `rocketreach_search_contacts` (search-only — no paid
- lookups), and `rocketreach_lookup_contacts` (paid enrichment, which **requires
- an explicit `maxLookups` cap** and never exceeds it).
- - **Safety:** every call **fails closed** if the integration is disabled or the
- key is missing — even if it was turned off after the MCP server started. API
- keys are redacted from all responses, errors, and logs. Runs can be saved into
- the vault as `prospects/…` notes with full provenance (actor, timestamp,
- normalized parameters, credit deltas).
- ---
- ## Environment variables
- For `apps/api`:
- - `CONTENT_ROOT`
- - Base directory (the "vault") for markdown files/directories.
- - If unset, defaults to `~/.fsbrain/vault` (auto-created on first run).
- - Set `CONTENT_ROOT=./content` to keep an older clone's location.
- - `PORT`
- - API server port (default: `3001`).
- - `FSBRAIN_EMBEDDINGS`
- - Opt-in switch for the **embedding** retrieval engine. Off by default
- (`1`/`true`/`on`/`yes` turns it on); when off, semantic search uses the
- fully-offline TF-IDF engine — no network, no key, exactly as before.
- - When on, needs a key: `EMBEDDINGS_API_KEY` (falls back to
- `OPENROUTER_API_KEY`). If the provider is unreachable or misconfigured,
- retrieval automatically falls back to TF-IDF, so "off" is always a working
- search — flip the flag off and restart to revert entirely.
- - Optional overrides: `EMBEDDINGS_MODEL` (default
- `openai/text-embedding-3-small`), `EMBEDDINGS_URL` (any OpenAI-compatible
- `/v1/embeddings` endpoint; default OpenRouter), `EMBEDDINGS_BATCH_SIZE`
- (default `96`).
- - Vectors are cached to `<CONTENT_ROOT>/.fsbrain/embeddings.json` so a restart
- re-embeds only changed notes. The file is safe to delete (it rebuilds on
- demand) and is tagged with the model, so switching `EMBEDDINGS_MODEL`
- invalidates it automatically.
- Example:
- ```bash
- CONTENT_ROOT=/absolute/path/to/vault PORT=3001 npm run dev:api
- # Opt into embedding-based semantic search:
- FSBRAIN_EMBEDDINGS=on EMBEDDINGS_API_KEY=sk-... npm run dev:api
- ```
- ---
- ## API snapshot
- **Files & tree**
- - `GET /health`
- - `GET /api/tree?path=...`
- - `GET /api/file?path=...` (or `?id=...`)
- - `POST /api/file` · `PUT /api/file` · `PATCH /api/file` (granular ops)
- - `POST /api/dir`
- - `PATCH /api/path` (move/rename) · `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 bundle) · `GET /api/think` (cited answer kit)
- **Provenance, review & maintenance**
- - `GET /api/audit`
- - `GET /api/proposals` · `POST /api/proposals` · `POST /api/proposals/resolve` (human-only)
- - `GET /api/proposals/stats` (review-queue approval rates + threshold nudges)
- - `GET /api/maintenance` · `POST /api/maintenance/scan`
- - `GET /api/skills/curator` (report-only skill-library curator)
- - `GET /api/feedback` · `POST /api/feedback/scan`
- **Live**
- - `GET /api/events` (Server-Sent Events)
- For endpoint details and request/response examples, see [`apps/api/README.md`](apps/api/README.md).
- Agents typically reach these via the MCP tools — see [`apps/mcp/README.md`](apps/mcp/README.md).
- ---
- ## Local quality checks
- ```bash
- npm test
- npm run lint
- npm run format
- ```
- ---
- ## Security model (important)
- - API path handling rejects traversal and absolute paths.
- - File operations are markdown-focused (`.md`).
- - Storage resolution ensures requests remain within `CONTENT_ROOT`.
- This helps protect the host filesystem while still enabling file-based workflows.
- ---
- ## Deployment note
- For persistent content in production, mount a host volume and point `CONTENT_ROOT` to it.
- See the full deployment examples in this README’s history and backend docs.
- ---
- ## Roadmap ideas
- - ✅ Search across markdown files (full-text, semantic, and **hybrid** RRF)
- - ✅ Interactive knowledge graph + backlinks
- - ✅ Built-in MCP server — use the vault as an agent's brain
- - ✅ Cited answers + offline gap analysis (`think`) and dream-cycle maintenance
- - ✅ Self-improving outreach **feedback loop** — learns your voice from draft→final edits
- - ✅ Typed page types / **schema packs** — canonical `type:`s, graph colouring, validation
- - ✅ Mermaid diagrams — fenced ` ```mermaid ` blocks render as SVG in the preview
- - Real vector embeddings (the cached index is the seam)
- - Git sync workflows
- - Multi-user auth + permissions
- - Real-time collaborative editing
- - Pluggable storage adapters
- ---
- ## Contributing
- PRs are welcome. If you want to contribute:
- 1. Open an issue with the use case/problem statement.
- 2. Submit a focused PR with tests.
- 3. Keep markdown/file safety guarantees intact.
- ---
- ## Extra docs
- - **AI agents start here:** [`AGENTS.md`](AGENTS.md) — repo entry point + a
- tool/endpoint quick-reference
- - Project state / roadmap (source of truth): [`docs/implementation.md`](docs/implementation.md)
- - Backend API details: [`apps/api/README.md`](apps/api/README.md)
- - Agent tools (MCP) + write attribution: [`apps/mcp/README.md`](apps/mcp/README.md)
- - Connect an MCP host (OpenClaw / Claude / Cursor): [`docs/CONNECT.md`](docs/CONNECT.md)
- - Manual integration validation: [`docs/integration-test-plan.md`](docs/integration-test-plan.md)
- ---
- ## Keywords (for discoverability)
- **AI-native:** MCP server, Model Context Protocol, AI agent tools, agent memory,
- self-improving knowledge base, learns-from-edits feedback loop, self-healing
- maintenance, agentic RAG, retrieval-augmented generation, semantic search, hybrid
- search (RRF), vector-ready knowledge base, Claude / Cursor / OpenClaw integration,
- second brain for LLMs, human-in-the-loop, agent proposals & audit log, cited answers.
- **Markdown workspace:** github-like file tree, notion-style markdown editor,
- local-first markdown vault, filesystem CMS, markdown knowledge base, wikilinks &
- backlinks, knowledge graph, react markdown editor, node filesystem api, PKM.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.