Personal Agent

Personal Agent is an open-source personal AI assistant built by Dominik Klesal (DomWane) that runs entirely on Cloudflare Workers infrastructure. It is designed to operate within Cloudflare's free tier, with every platform limit measured and documented. The project is licensed under MIT and is actively maintained on GitHub.

What It Is

Personal Agent is a self-hosted AI assistant framework built on Cloudflare's serverless edge platform. Each conversation runs in its own Durable Object, giving the agent persistent state, long-term memory stored as markdown in R2, and semantic recall powered by an embedding index in Durable Object SQLite. A deep-research mode fans out across child Durable Objects to gather and synthesize information from the web in parallel.

Architecture and Stack

The agent is built around a tool loop where one Durable Object per thread orchestrates all activity. Key architectural components include:

• Web chat over WebSocket — the Vue 3 UI holds no state; all state lives in the Durable Object and is broadcast to clients
• Deep research — the agent proposes a plan, then fans out one child Durable Object ("scout") per research angle, each with its own subrequest budget
• Long-term memory — stored as markdown in R2, with semantic recall via bge-m3 embeddings and a keyword fallback; every memory records the turn it came from
• History compaction — at 80% of the model's context window, oldest turns fold into a rolling summary and go to an append-only archive
• Self-written skills — multi-step workflows are saved as markdown skills in the vault and listed in every system prompt; unused skills are archived after 90 days
• MCP server support — added via a settings dialog with OAuth or bearer token; tools are available from the next message onward
• Scheduled work — reminders, recurring tasks, and nightly reflection passes run as Durable Object alarms, not inside chat turns

The full stack is: Cloudflare Workers, Agents SDK, Durable Objects, R2, Workers AI (or any OpenAI-compatible API), Zod, Vue 3, Vite, Tailwind, shadcn-vue, and Vitest.

Model Provider Flexibility

The agent defaults to Workers AI (using CF_ACCOUNT_ID and CF_API_TOKEN) but supports any OpenAI-compatible endpoint via LLM_BASE_URL. Verified models on the free plan include @cf/zai-org/glm-4.7-flash, @cf/openai/gpt-oss-120b, @cf/qwen/qwen3-30b-a3b-fp8, and @cf/meta/llama-3.3-70b-instruct-fp8-fast. The in-UI model picker reads the provider's catalogue and shows price, context window, and tool support per model. Tool calling is required — the agent is a tool loop.

Free-Tier Deployment Model

The project is explicitly designed to run within Cloudflare's free tier, and every limit it encounters is measured and documented. Notable constraints and how the agent handles them:

• 50 external subrequests per invocation — the agent counts every call and stops before the 51st, reporting the cutoff
• Browser Rendering (1 req/10s, 10 min/day) — falls back to Firecrawl; research reports count pages that could not be opened
• Workers AI (10,000 neurons/day) — a 429 response is reported as a failed turn, not a silent failure
• Keyless search — a refused search is a tool fault, never an empty result

The README notes that in a documented walkthrough, a deep research run lost 14 of 30 page reads to the Browser Rendering limit, completed successfully, and reported the shortfall.

Evaluation and Measurement Approach

The project includes a documented evaluation methodology that goes beyond typical open-source agents:

• A retrieval eval over 673 real exchanges with graded relevance shows dense retrieval (bge-m3) beats BM25 by +0.200 nDCG@10
• An independent replication of ThinkingCap's token-saving claim found 50.8% savings [43.2%, 57.7%] in Czech over real work
• A manual end-to-end walkthrough covers DOM and WebSocket seams that automated tests cannot reach, and documents three bugs found only by hand

Each write-up includes a section on how the measurement was wrong before it was corrected.

Setup Path

Deployment is available via a one-click "Deploy to Cloudflare" button (which clones the repo, creates R2 and Durable Object bindings, and prompts for secrets) or from the command line using pnpm and wrangler. Cloudflare Access is required in production — the Worker refuses to serve without it to protect the R2 vault.