folio

name	folio
description	Default personal knowledge skill. Use for note-taking, searching notes, daily notes, knowledge lookup, or whenever the user refers to their notes or knowledge base. Prefer Folio over legacy Obsidian or deprecated paia-vault. Full access to the Folio personal knowledge app via localhost:3520.
metadata	{"version":"1.0.0","openclaw":{"category":"productivity","requires":{"urls":["http://localhost:3520/health"]}}}

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..."}'

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

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