Folio

A markdown-native knowledge and project management system, exposed as an MCP server. Folio stores all state as structured markdown files — human-readable, git-committable, and programmatically queryable.

Built with Sigil.

Install

sigil app install codeberg:sigil/folio \
 --mcp \
 --env FOLIO_ROOT=~/folio

This installs the folio binary, registers it as a user-level MCP server, and points it at ~/folio as the data directory. The folio directory will be created on first run.

To install for a specific project instead (registers in the project's .mcp.json):

cd ~/my-project
sigil app install codeberg:sigil/folio \
 --mcp \
 --mcp-scope project \
 --env FOLIO_ROOT=./folio

Or add to .mcp.json manually:

{
 "mcpServers": {
 "folio": {
 "command": "folio",
 "env": {
 "FOLIO_ROOT": "./folio"
 }
 }
 }
}

What it does

Folio gives AI agents structured access to tasks, projects, and notes through MCP tools. The agent gets clean operations; you get readable markdown files with clean git diffs.

Tasks

Checkbox items with inline metadata:

- [ ] Add contact lookup tool {id: t-a3f2, priority: high, due: 2026年03月20日}
- [x] Fix reply identity selection {id: t-b1c4, completed: 2026年03月13日}

Projects

One markdown file per project in projects/, with YAML frontmatter, a task list, and a reverse-chronological log:

---
status: active
goal: Add contact management and improve search
area: development
last-updated: 2026年03月13日
---
# Bureau v2

## Tasks

- [ ] Add contact lookup tool {id: t-a3f2, priority: high, due: 2026年03月20日}
- [ ] Improve search result ranking {id: t-b1c4, priority: medium}
## Log

### 2026年03月13日

Fixed identity selection for replies. Bureau now auto-detects the
correct sending identity from the original email's To field.

Notes

Atomic reference notes in notes/ with [[crosslinks]] between them:

---
tags:
 - fastmail
 - jmap
created: 2026年03月12日
last-updated: 2026年03月13日
---
# Fastmail JMAP Quirks

Fastmail rejects the `#draft` back-reference key in `onSuccessUpdateEmail`.
## Related

- [[caldav-discovery]] - CalDAV has similar redirect issues
- [[bureau-send-pipeline]] - Where these quirks manifest

Notes support subdirectories for organization: procedures/, contacts/, preferences/, etc. Crosslinks resolve across both notes and projects.

Inbox

A single inbox.md for capturing items before they're triaged into projects.

Directory structure

folio/
├── inbox.md
├── projects/
│ ├── bureau-v2.md
│ └── sigil-gc.md
├── notes/
│ ├── fastmail-jmap-quirks.md
│ ├── procedures/
│ │ └── email-triage.md
│ └── contacts/
│ └── alice.md
└── archive/
 ├── projects/
 └── notes/

MCP Tools

Overview

Tasks

Inbox

Projects

Notes

Development

Requires Sigil v0.9.0+.

# Install dependencies
sigil deps install
# Build
sigil build
# Test
sigil test
# Run locally
FOLIO_ROOT=/tmp/folio ./build/dev/bin/folio
# Build release bundle (standalone binary)
sigil build --config release
FOLIO_ROOT=/tmp/folio ./build/release/bin/folio

License

BSD-3-Clause