Folio

Folio — Personal Knowledge Management

Folio is the user's personal knowledge app. It stores notes with semantic search (pgvector), tags, collections, daily notes, wikilinks, annotations, and file attachments. The API runs on localhost:3520 with no authentication.

Base URL

http://localhost:3520/api/folio

All endpoints below are relative to this base. A /api/vault prefix also works (legacy alias).

Trigger Phrases

When the user says any of these, use this skill:

• "make a note (in folio)" / "add a note" / "note that down"
• "jot this down" / "save to folio"
• "look up in folio" / "search my notes" / "check my notes"
• "what was that note about..." / "find my note on..."
• "today's note" / "daily note"
• "tag it" (in context of notes)
• "what do I know about..." / "search my knowledge base"
• "folio" in any note/knowledge context

Default Preference

Folio is the canonical personal knowledge system. Prefer this skill over legacy Obsidian or deprecated paia-vault workflows unless the user explicitly asks to work with old Obsidian/MCP infrastructure.

Core Operations

Create a Note

curl -s -X POST http://localhost:3520/api/folio/notes \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Note Title",
    "content": "Markdown content here. Supports **bold**, [[wikilinks]], and YAML frontmatter.",
    "path": "Areas/Category/Note Title.md",
    "tags": ["tag1", "tag2"],
    "object_type": "note",
    "properties": {}
  }'

Fields: | Field | Required | Default | Description | |-------|----------|---------|-------------| | title | yes | — | Note title | | content | no | "" | Markdown content | | path | no | auto | Vault-relative path | | object_type | no | "note" | note, daily, person, concept, etc. | | properties | no | {} | Arbitrary JSONB properties |

Quick create (minimal — title only is fine):

curl -s -X POST http://localhost:3520/api/folio/notes \
  -H 'Content-Type: application/json' \
  -d '{"title": "Quick thought", "content": "The thing to remember"}'

Search Notes (Semantic + Full-Text)

curl -s "http://localhost:3520/api/folio/search?q=ai+agents+coordination"

Returns ranked results with rank (0-1 similarity score). Uses pgvector semantic search first, falls back to PostgreSQL full-text search.

List Notes (with filters)

# Recent notes
curl -s "http://localhost:3520/api/folio/notes?limit=20&offset=0"

# Filter by tag
curl -s "http://localhost:3520/api/folio/notes?tag=strategy&limit=20"

# Filter by path prefix (folder)
curl -s "http://localhost:3520/api/folio/notes?path_prefix=Areas/Companies&limit=20"

# Full-text search (non-semantic)
curl -s "http://localhost:3520/api/folio/notes?search=protein+interaction&limit=10"

# Pinned only
curl -s "http://localhost:3520/api/folio/notes?pinned_only=true&limit=10"

# Filter by object type
curl -s "http://localhost:3520/api/folio/notes?object_type=person&limit=20"

Get a Single Note

curl -s "http://localhost:3520/api/folio/notes/{note_id}"

Update a Note

# Partial update (PATCH — only send fields you want to change)
curl -s -X PATCH "http://localhost:3520/api/folio/notes/{note_id}" \
  -H 'Content-Type: application/json' \
  -d '{"content": "Updated content", "title": "New Title"}'

# Full replace (PUT)
curl -s -X PUT "http://localhost:3520/api/folio/notes/{note_id}" \
  -H 'Content-Type: application/json' \
  -d '{"title": "Replaced Title", "content": "All new content", "object_type": "note", "properties": {}}'

Delete (Archive) a Note

curl -s -X DELETE "http://localhost:3520/api/folio/notes/{note_id}"

This is a soft-delete (sets archived_at). The note still exists in the database.

Daily Notes

Get or Create Today's Note

curl -s "http://localhost:3520/api/folio/daily/2026-04-17"

Auto-creates with template (Tasks section, Notes section, frontmatter with date) if not found.

Get Daily Notes for a Range

curl -s "http://localhost:3520/api/folio/daily/range?start=2026-04-10&end=2026-04-17"

Tags

List All Tags

curl -s "http://localhost:3520/api/folio/tags"

Returns [{tag: "tag-name", count: N}, ...].

Add Tag to Note

curl -s -X POST "http://localhost:3520/api/folio/notes/{note_id}/tags" \
  -H 'Content-Type: application/json' \
  -d '{"tag": "project/alpha"}'

Supports Bear-style hierarchical tags: project/alpha, personal/journal, strategy.

Remove Tag from Note

curl -s -X DELETE "http://localhost:3520/api/folio/notes/{note_id}/tags/{tag_name}"

Get Tags for a Note

curl -s "http://localhost:3520/api/folio/notes/{note_id}/tags"

Filter Notes by Tag

curl -s "http://localhost:3520/api/folio/notes?tag=strategy&limit=20"

Links and Backlinks

Create a Link

curl -s -X POST "http://localhost:3520/api/folio/notes/{source_id}/links" \
  -H 'Content-Type: application/json' \
  -d '{"target_note_id": "target-uuid-here"}'

Get Backlinks (notes linking TO this note)

curl -s "http://localhost:3520/api/folio/notes/{note_id}/backlinks"

Get Outgoing Links (notes this note links TO)

curl -s "http://localhost:3520/api/folio/notes/{note_id}/links"

Wikilinks [[Note Title]] in content are automatically resolved to link records on create/update.

Pin/Unpin Notes

# Pin
curl -s -X POST "http://localhost:3520/api/folio/notes/{note_id}/pin"

# Unpin
curl -s -X DELETE "http://localhost:3520/api/folio/notes/{note_id}/pin"

Annotations (Agent Comments on Notes)

# Add an annotation
curl -s -X POST "http://localhost:3520/api/folio/notes/{note_id}/annotations" \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_name": "claude",
    "annotation_type": "comment",
    "content": "This note references an outdated API endpoint."
  }'

annotation_type options: comment, suggestion, link, highlight

# List annotations for a note
curl -s "http://localhost:3520/api/folio/notes/{note_id}/annotations"

Version History

# List versions
curl -s "http://localhost:3520/api/folio/notes/{note_id}/versions?limit=10"

# Get specific version content
curl -s "http://localhost:3520/api/folio/versions/{version_id}"

# Restore to a version
curl -s -X POST "http://localhost:3520/api/folio/notes/{note_id}/restore/{version_id}"

Folders

curl -s "http://localhost:3520/api/folio/folders"

Returns [{folder: "Areas/Companies", count: N}, ...].

Collections

# List collections
curl -s "http://localhost:3520/api/folio/collections"

# Get collection with resolved notes
curl -s "http://localhost:3520/api/folio/collections/{collection_id}/notes"

# Create a collection
curl -s -X POST http://localhost:3520/api/folio/collections \
  -H 'Content-Type: application/json' \
  -d '{"name": "Important", "collection_type": "manual", "icon": "star"}'

Common Agent Workflows

"Make a note of it"

1. Create note with title and content:

curl -s -X POST http://localhost:3520/api/folio/notes \
  -H 'Content-Type: application/json' \
  -d '{"title": "Subject of the note", "content": "What to remember..."}'

1. Optionally tag it:

curl -s -X POST "http://localhost:3520/api/folio/notes/{returned_id}/tags" \
  -H 'Content-Type: application/json' \
  -d '{"tag": "from-conversation"}'

"Add this to today's note"

1. Get or create daily note:

curl -s "http://localhost:3520/api/folio/daily/$(date +%Y-%m-%d)"

1. Append content to the daily note (PATCH with updated content):

# First GET the note to retrieve current content, then PATCH with appended content
EXISTING=$(curl -s "http://localhost:3520/api/folio/daily/$(date +%Y-%m-%d)")
# Extract id and content, then append
curl -s -X PATCH "http://localhost:3520/api/folio/notes/{daily_note_id}" \
  -H 'Content-Type: application/json' \
  -d '{"content": "EXISTING_CONTENT\n\n## Appended\n- New item to track"}'

"What did I note about X?"

curl -s "http://localhost:3520/api/folio/search?q=X"

Review top results and read the most relevant note:

curl -s "http://localhost:3520/api/folio/notes/{note_id}"

"Find notes related to this one"

# Get backlinks
curl -s "http://localhost:3520/api/folio/notes/{note_id}/backlinks"

# Semantic search for similar content
curl -s "http://localhost:3520/api/folio/search?q=$(curl -s http://localhost:3520/api/folio/notes/{note_id} | python3 -c 'import sys,json; print(json.load(sys.stdin)["title"])')"

Health Check

curl -s http://localhost:3520/health
# Returns: {"status": "ok"}

Tips

• No auth required — the API is open on localhost
• Content is Markdown — supports **bold**, # headings, [[wikilinks]], YAML frontmatter
• Tags auto-sync from frontmatter — if you put tags: [foo, bar] in YAML frontmatter, tags are created automatically
• Wikilinks auto-resolve — [[Other Note Title]] creates link records automatically on create/update
• Semantic search is the superpower — use GET /search?q=... for natural language queries, it uses 384-dim embeddings
• object_type can be: note, daily, person, concept, or any custom type
• Paths follow vault structure: Areas/Category/Title.md, Daily notes/2026-04-17.md, people/Name.md
• All write operations are immediate — no sync delay for API writes; Obsidian vault sync picks them up within 30 seconds

Vault Path Conventions

Areas/
  ├── Companies/       # Client and company notes
  ├── Tech/            # Technical notes, GenAI, development
  └── Projects/        # Active project notes
people/                # Contact and relationship notes
Daily notes/           # Daily notes (YYYY-MM-DD.md)
next_up/               # Action items, opportunities

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dbmcco
• Source: dbmcco/claude-agent-toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.