whorl

Whorl

A whorl is a tool that allows you to make your interactions with chatbots more personalized. It scalably ingest all your personal documents (journals, writing, things you've read, etc...) into one centralized place (a whorl) and then give the AIs you interact with access that information.

In doing so, you can effectively personalize your interactions with models, by making them query and get information from your whorl. Whorl gives AIs tools to fetch this knowldge, and also optionally uses AI to make your whorl artifact automatically more structured, by triggering workflows whenever you add to your whorl - eg keeping lists of tasks, media recommendations, or ideas that might be worth exploring.

Whorl is designed to be simple, basically just exposing a file system for you to upload things to, an MCP for your models to call that info, and a frontend for you to access everything.

Getting started

Install:

pip install whorled
# or
uv tool install whorled

Setup default configuration:

whorl init

If you want AI features, set your anthropic API key in .env or environment:

export ANTHROPIC_API_KEY="your-anthropic-key"  # for AI features

Running the Server

whorl server

The web UI will be available at http://localhost:8000.

Authentication

By default, if no password is configured, Whorl allows unauthenticated access. This is convenient for local development.

To enable authentication, set a password via environment variable or settings:

export WHORL_[REDACTED:Password]

Or add to ~/.whorl/settings.json:

{
  "password": "your-password"
}

Important: Always set a password when deploying Whorl on a public server.

Ingestion

Now you will want to upload data to Whorl.

It is all stored in ~/.whorl/docs (or $WHORL_HOME/docs) in any kind of flat or foldered structure you want, so you can also just move files there.

If you have a folder with your notes, journals, etc... you can use the CLI:

whorl upload ~/notes --context "personal-notes"

Otherwise, use an agent with the whorl MCP server, or just move files into the docs directory.

The ingest API is:

curl -X POST http://localhost:8000/api/ingest \
  -H "Content-Type: application/json" \
  -H "X-Password: $WHORL_PASSWORD" \
  -d '{"content": "Your note content here", "title": "Note Title", "metadata": {}}'

Feel free to tell your agent.

Whorl is also a PWA, so you can add it to your phone and then select text -> share to whorl.

Workflows

You can configure automated workflows that agents execute whenever you upload to whorl. These agents run bash commands on your files, so be careful with your data!

You can add some defaults using whorl init, which sets up:

• automatically summarizing and tagging new notes
• extracting todos and tasks into tasks.md
• gathering media references into media.md
• collecting ideas into ideas.md

Then, in docs/index.md, you can reference these files (renders on the whorl homepage):

[[ideas.md]]
[[media.md]]
[[tasks.md]]

This is very flexible - go wild! Let me know what you find useful, I've just started experimenting with this.

CLI Usage

whorl server                     # start server on :8000
whorl server --port 3000         # custom port
whorl server --reload            # dev mode with auto-reload

whorl upload <dir>               # upload text files from directory
whorl upload <dir> -f            # flat (non-recursive)
whorl upload <dir> -e "*.draft"  # exclude pattern
whorl upload <dir> -c "source"   # add source context

whorl sync                       # run missing agents on all docs
whorl init                       # set up default prompts and index

MCP Integration

Whorl exposes an MCP server at /mcp for integration with Claude Code and other MCP-compatible tools.

Add to your Claude MCP configuration (e.g. .mcp.json):

{
  "mcpServers": {
    "whorl": {
      "url": "http://localhost:8000/mcp/",
      "type": "http"
    }
  }
}

If you have authentication enabled, add headers:

{
  "mcpServers": {
    "whorl": {
      "url": "http://localhost:8000/mcp/",
      "type": "http",
      "headers": {
        "X-Password": "your-whorl-password"
      }
    }
  }
}

Available MCP tools:

• ingest - Add content to knowledge base
• text_search - Full-text search
• agent_search - AI search
• bash - Run commands in the docs directory

You can add something to your global system prompt with the MCP, and then tell your chat assistant to use these tools when it might benefit from context about you.

Custom Ingestion Agents

Create markdown prompts in ~/.whorl/prompts/ingestion/ to process documents during ingestion. Each prompt file becomes an agent that runs on ingested content.

Example prompt (~/.whorl/prompts/ingestion/summarize.md):