Folderbase documentation

Start with local files, understand the deployed database roadmap, and plan for sharing and sync.

Storage for agents. Folderbase is being built for apps and agents that use ordinary JSON, Markdown, and other files as persistent data.

Start with the local file foundation today. The next milestones add a shared application data contract, durable access from deployed apps, and sharing and sync. Your files remain normal files; a small .folderbase/ directory holds engine-managed state.

Beta status: Folderbase is under active development. Compatibility Contract v1 names the stable portable records and CLI behavior. Everything else must be treated as Beta, and optional capabilities marked Experimental are the most likely to change between releases.

What are you building?

Use JSON and Markdown as your app’s database

Tasks, notes, and attachments that your app and agent can use. Local file operations are available; record schemas and field queries are planned.

Keep deployed app data durable and accessible

Keep the same data available across app restarts and instances. Hosted database access is in development.

Share data and sync across people, agents, and devices

Give others access and continue on another machine with visible conflicts. Hosted sharing and device sync are planned.

Read the three use cases for concrete examples, current availability, and the next step for each.

Start locally

Install Folderbase

Choose npx, a native release binary, or Cargo.

Five-minute quickstart

Inspect, preview, initialize, and validate a folder.

Explore the Folderbase App

See the native alpha and distinguish current workflows from planned sharing and transfer.

Query metadata (Unstable Beta)

Filter live or historical file metadata without searching file contents.

Keep an active session fresh

Give an App or agent one root-pinned query session with bounded filesystem-change hints.

Expand from a template

Preview and apply additive guidance without replacing existing work.

Work through Change Sets

Give an agent a scoped ordinary folder and merge reviewable work safely.

Sync an agent workspace (Planned)

See the accepted two-device owner-sync journey and its V0/V1 pilots.

Experimental migration

Generate a reviewable organization plan without applying it.

Operate from an agent

List, read, and save files with explicit concurrency control.

Integrate with TypeScript

Use @folderbase/sdk without duplicating Core or reading private records.

What Core 0.7.2 guarantees

A stable discoverable CLI JSON contract.
A compatibility contract for portable records and extension preservation.
A universal executable seam for TypeScript, native apps, and remote agent VMs.
Review-first initialization with approval bound to the exact plan digest.
Local-first operation without a Folderbase account.
Native binaries for macOS and Linux through verified release artifacts.

Read what the compatibility contract protects or see what shipped in Core 0.7.2.

Folderbase in one minute

npx @folderbase/cli inspect . --json
npx @folderbase/cli init . --dry-run --json
npx @folderbase/cli init . --expected-plan-digest DIGEST_FROM_DRY_RUN --json
npx @folderbase/cli validate . --json

Folderbase adds its protocol surface alongside your existing work:

project/
├── .folderbase/
│   └── manifest.json
└── …your existing files

That manifest is the only default write. Narratives, a root .folderbaseignore override, agent adapters, and template artifacts are explicit optional additions. The manifest itself always contains Core's required capture-policy fields.