Summary

This project addresses the common trade-off between user-friendly note-taking interfaces and secure, plain-file storage. It provides an AI-native markdown vault that functions as a local-first knowledge base, integrating seamlessly with AI agents via a built-in MCP server. The primary benefit is owning your data in plain .md files while leveraging AI for advanced search, content generation, and self-improvement, all under human control.

How It Works

The system comprises a React/Vite frontend for a GitHub-like file tree and Notion-style editor, backed by a Node.js HTTP API. This API manages markdown file CRUD operations, optimistic concurrency, and various search modalities (full-text, semantic, hybrid). Crucially, a built-in MCP server exposes the vault as 26 tools for AI agents (e.g., Claude, Cursor). Agents can interact with notes, with all agent-initiated writes logged and routed through a human-approved review queue, ensuring safety and control. The vault also features a "dream-cycle" maintenance scan for tidying and a feedback loop that learns the user's writing voice from edits.

Quick Start & Requirements

• Prerequisites: Node.js (22.x), npm (10.x).
• Installation: Run npm install in the repository root.
• Development: Launch the API with npm run dev:api and the web UI with npm run dev:web in separate terminals.
• Agent Mode: Build with npm run build then run the self-contained MCP server with npm run start:agent.
• Vault Location: Defaults to ~/.fsbrain/vault; configurable via CONTENT_ROOT.

Highlighted Details

• AI Agent Integration: Acts as an AI agent's "brain" via an MCP server, offering 26 tools with human-in-the-loop approval for all proposed changes.
• Self-Improving Vault: Features automated maintenance (broken links, orphans) and learns user writing style from draft-to-final edit comparisons.
• Advanced Search: Supports TF-IDF (offline) and optional, cached, real embeddings for semantic and hybrid search.
• Cited Answers: AI can generate answers from notes and explicitly state information gaps.
• Typed Notes: Schema packs (e.g., person, project) can be defined via frontmatter for structured data and agent understanding.

Maintenance & Community

The provided README does not detail specific community channels (like Discord/Slack), notable contributors, or sponsorship information.

Licensing & Compatibility

The repository's README does not specify a software license. This omission requires clarification for assessing commercial use or derivative works.

Limitations & Caveats

The project is actively developed, with features like real-time collaboration, multi-user authentication, and pluggable storage adapters listed as future roadmap items. The absence of a declared license is a significant blocker for adoption decisions.