# Folio

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

- **Type:** Skill
- **Install:** `agentstack add skill-dbmcco-claude-agent-toolkit-folio`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dbmcco](https://agentstack.voostack.com/s/dbmcco)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dbmcco](https://github.com/dbmcco)
- **Source:** https://github.com/dbmcco/claude-agent-toolkit/tree/main/skills/folio

## Install

```sh
agentstack add skill-dbmcco-claude-agent-toolkit-folio
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
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):
```bash
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)

```bash
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)

```bash
# 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

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

### Update a Note

```bash
# 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

```bash
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

```bash
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

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

## Tags

### List All Tags

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

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

### Add Tag to Note

```bash
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

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

### Get Tags for a Note

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

### Filter Notes by Tag

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

## Links and Backlinks

### Create a Link

```bash
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)

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

### Get Outgoing Links (notes this note links TO)

```bash
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

```bash
# 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)

```bash
# 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`

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

## Version History

```bash
# 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

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

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

## Collections

```bash
# 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:
```bash
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:
```bash
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:
```bash
curl -s "http://localhost:3520/api/folio/daily/$(date +%Y-%m-%d)"
```

2. Append content to the daily note (PATCH with updated content):
```bash
# 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?"

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

Review top results and read the most relevant note:
```bash
curl -s "http://localhost:3520/api/folio/notes/{note_id}"
```

### "Find notes related to this one"

```bash
# 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

```bash
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](https://github.com/dbmcco)
- **Source:** [dbmcco/claude-agent-toolkit](https://github.com/dbmcco/claude-agent-toolkit)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dbmcco-claude-agent-toolkit-folio
- Seller: https://agentstack.voostack.com/s/dbmcco
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.