Vesper

Vesper is a user-owned, versioned filesystem and state layer for AI agents.

The agent is not the model, provider, harness, runtime, chatbot surface, or machine currently doing the work. Those are executors. The agent is the durable state that lets work continue: files, logs, memories, skills, prompts, permissions, connections, mirrors, traces, and the projections generated from them.

Vesper is meant to be the portable save file for every agent a person works with. Codex, Claude Code, Hermes on a VPS, Poke in iMessage, OpenCode, local agents, hosted chatbots, and future runtimes should all be able to attach to the same state and behave like they have been working with the user for years, because they have access to the same durable substrate.

Why This Exists

Today, agent continuity is fragile. Context gets lost in compaction. Personal connections are re-wired per agent. Skills live in tool-specific folders. Memories are copied by hand. Logs are treated as exhaust, not as the system.

Vesper inverts that.

VesperFS is the source of truth, backed by an append-only journal and content-addressed blobs. Transcripts, memory files, search indexes, vector stores, traces, wiki pages, skill exports, and adapter-specific context packs are projections. If a projection is wrong or stale, Vesper can rebuild it from the underlying filesystem, log, and source records. If a process dies, another executor can resume from the same state. If a user changes agents, the brain comes with them.

Core Ideas

• The filesystem is the agent. VesperFS holds the durable working state: files, skills, prompts, wiki, mirrors, logs, artifacts, and memory.
• The log is the journal. Every meaningful event is written to an append-only, structured, attributed history.
• Messages are state. User and agent messages are persisted as first-class log events, not left behind in runtime transcripts.
• Nothing valuable is overwritten. Files, skills, prompts, mirrors, wiki pages, and logs are versioned with content-addressed history.
• Executors are replaceable. Models, harnesses, machines, and chat surfaces read state, act, and append new events.
• Compaction is a projection. Summaries are useful, but lossy. They should not replace raw history.
• External effects are recorded, not reversed. Emails, file edits, GitHub issues, calendar changes, and similar actions are logged with permission and result metadata.
• Skills belong to the user. Agent skills should have one canonical home and be projected into whatever shape each runtime expects.
• Connections should not be reconnected per agent. Agents should ask Vesper for context or actions through one permissioned layer.
• Memory should be sourced and reviewable. Durable memories and wiki pages should point back to logs or mirrored source records where possible.

What Vesper Should Hold

Vesper is expected to manage several related forms of state:

• Versioned files and workspaces
• Agent event logs
• User messages, agent messages, model envelopes, and conversation history
• Session definitions and adapter metadata
• Tool calls, tool results, permission prompts, approvals, denials, and errors
• External-world action records
• Skills, skill versions, compatibility metadata, and usage history
• Personal context mirrors from systems such as Slack, Gmail, Calendar, GitHub, Strava, local files, and Markdown directories
• Permission policy by agent, source, action type, project, and sensitivity
• Generated projections such as memory files, LLM wiki pages, compacted context, search indexes, and adapter-specific exports
• Attachments and generated artifacts, with large objects stored outside the hot log
• V1 connection lanes matching Companion's provider surface, including Google, Slack, GitHub, Strava, Polar, Spotify, Grok/xAI, Plaid, Apple Maps Guides, Granola, Linear, Notion, Refero, Shopify MCPs, Open-Meteo, Airbnb, AgentCash, and custom MCP servers

Relationship To Companion

Companion proved several useful patterns:

• Durable object state can hold live conversation and tool trace data.
• A small set of prompt files and skill files can become runtime state, not just static repo assets.
• A "dream" process can synthesize logs and mirrored context into a living wiki.
• Provider connections work best when reads are bounded, mirrors are searchable, and writes go through explicit approval.
• Skills are more valuable when they are portable operational knowledge, not buried inside a single chat surface.
• Connection setup and control UI should be reused where it already works: provider cards, OAuth/API-key/Plaid/manual callback setup flows, sync status, account grouping, access review, approval gating, and diagnostics.

Vesper extracts those ideas into their own product. Companion can become one consumer of Vesper rather than the place where all state is trapped.

Architecture Direction

Vesper is Cloudflare-first. The hosted service should run on Workers, SQLite-backed Durable Objects, D1, R2, Queues/Workflows, and search/vector indexes where useful. The open-source project should keep the storage boundary clean enough that users can run local or self-hosted variants, but the first production-quality path targets Cloudflare because Durable Objects give Vesper the coordination primitive it needs.

The central runtime object is not one giant user agent. Vesper should split state by coordination boundary:

• A user vault object indexes workspaces, agent identities, policies, connections, skills, sessions, and projections.
• Workspace root objects own versioned VesperFS trees, file versions, content hashes, branch heads, and conflicts.
• Each session or branch has its own log object that owns the append-only event stream, ordered sequence numbers, idempotency keys, and live subscriptions.
• Connection lane objects own provider credentials, sync cursors, mirrored records, webhook dedupe, and permissioned provider actions.
• Skill and memory services maintain versioned artifacts and projections that can be exported into agent-specific shapes.

D1 is for routing, accounts, billing, membership, and other shared product metadata. It is not the primary store for logs, turns, memories, tool traces, or connection mirrors. R2 holds large payloads, attachments, raw provider blobs, snapshots, and export bundles.

Vesper should expose a small, stable state API and an MCP surface. Agents attach through adapters that can:

1. Identify the user, agent instance, runtime, and session definition.
2. Mount or materialize VesperFS state locally.
3. Append structured events to a durable log.
4. Read session projections suitable for the target model and harness.
5. Search and fetch raw mirrored personal sources.
6. Request permissioned actions.
7. Sync skills into the agent's expected local format.
8. Resume, hand off, or fork sessions.

The local attachment path is the Vesper CLI, published for remote shell-capable agents as vesper-cli. vesper bind creates or imports a durable binding, stores the token in the local profile, and prepares the workspace so Codex, Claude Code, Hermes, and OpenClaw can work normally through their usual files, skills, launch commands, and MCP config. The generated launchers run the real agent inside a Vesper-backed workspace, sync ordinary file changes into VesperFS, and append auditable lifecycle/file events. Native host hooks add higher-fidelity prompt, tool, and approval capture when a runtime supports them, but the basic product promise is simpler: bind once, work inside the bound workspace, and Vesper remembers. FUSE is used when available; Macs and hosted runtimes without FUSE use the production materialized sidecar path. See docs/cli.md.

The first implementation should stay narrow. Vesper is not initially a full agent runtime, model provider, chatbot, or workflow builder. It remembers, curates, routes context, manages skills, controls access, and preserves continuity.

See docs/architecture.md for the current technical shape, docs/design-system.md for the Artificial Illumination design direction, and docs/repo-investigation.md for lessons pulled from Companion, Magic Markdown, and Substrate.

MVP Shape

A credible first version should prove continuity across at least two executors.

Suggested MVP:

• Cloudflare Worker with SQLite-backed Durable Object log branches
• Versioned VesperFS workspace roots with content-addressed files
• .vesperignore and policy-based file tracking
• Local .vesper/ mount/control directory and vesperd POSIX-style materialization sidecar
• Append-only event log with sequence numbers, idempotency keys, and versioned event schema
• Session definition records and adapter registration
• Projection builder for recent context, compact memory, and transcript views
• Skill registry with export/sync into one or two agent formats
• Permission log for approvals and denials
• One personal context mirror or import path, likely GitHub, Markdown files, or local repo context before broader OAuth sources
• One adapter for Codex or Claude Code
• One handoff demo where a session starts in one executor and resumes in another

Product Spec

The full working spec lives in docs/product-brief.md. The UI/design direction lives in docs/design-system.md.

Repository Status

This repository is at the product-definition stage. The initial goal is to turn the lightweight thesis into a robust product spec, then carve out the smallest technical proof that demonstrates portable agent state in practice.