Own the context. Rent the memory.
Your notes stay plain .md files you own — bring any AI model and swap it whenever you like.

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 25 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…".
• 💬 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 server hands the whole vault to agents like Claude, Cursor, or OpenClaw as 25 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, and stale-but-load-bearing notes (heavily linked yet long unchanged — "is this still accurate?") 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 — 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

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 25 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:

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

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

---

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, …):

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 25 vault tools (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, …) 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.

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.

---

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).

Example:

CONTENT_ROOT=/absolute/path/to/vault PORT=3001 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/feedback · POST /api/feedback/scan

Live

• GET /api/events (Server-Sent Events)

For endpoint details and request/response examples, see apps/api/README.md. Agents typically reach these via the MCP tools — see apps/mcp/README.md.

---

Local quality checks

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
• Mermaid diagrams + 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 — repo entry point + a tool/endpoint quick-reference
• Project state / roadmap (source of truth): docs/implementation.md
• Backend API details: apps/api/README.md
• Agent tools (MCP) + write attribution: apps/mcp/README.md
• Connect an MCP host (OpenClaw / Claude / Cursor): docs/CONNECT.md
• Manual integration validation: 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.