Storage & Data

Sidecar stores everything locally, inside your project. No cloud, no sync service, no external dependencies. Your project memory lives next to your code.

The .sidecar/ directory

All Sidecar data lives in a single folder at .sidecar/ in your project root.

.sidecar/
├── sidecar.db         # SQLite — all records
├── config.json       # Project metadata
├── preferences.json  # Project conventions
├── AGENTS.md         # Agent instructions
└── summary.md        # Generated project summary

sidecar.db — SQLite database

The primary data store is a SQLite database at .sidecar/sidecar.db. It holds all structured records:

• Decisions
• Work logs
• Tasks
• Notes
• Sessions
• Artifacts

SQLite was chosen because it's simple, local, zero-config, and durable. You can open sidecar.db with any SQLite viewer if you want to query it directly. The schema is intentionally stable and readable.

summary.md — Generated summary

.sidecar/summary.md is a structured, human-readable summary of recent project activity. It's generated from the SQLite database and refreshed on demand.

Refresh it any time:

$ sidecar summary refresh

Unlike freeform project notes, the summary is deterministic — it's built from structured records, not written by hand. Two runs with the same data produce the same output.

The summary is also what agents read when you want to give them a quick project orientation without running sidecar context.

config.json

Basic project metadata. Typically just the project name and Sidecar version. Managed automatically and rarely edited directly.

{
  "project": "my-project",
  "sidecarVersion": "1.0.0",
  "initialized": "2024-11-01T09:00:00Z"
}

Local-first by design

Sidecar never sends your data anywhere. Everything is local:

• No cloud sync
• No account required
• No telemetry
• No network requests

Your project memory is yours. You can back it up, version it in git, share it with a team, or inspect it directly at any time.

Should I commit .sidecar/ to git?

It's up to you. Both approaches are reasonable:

If you commit it, consider adding *.db-journal and *.db-wal to your .gitignore to avoid SQLite journal files.

Future UI

The CLI is the primary interface, but Sidecar's storage is designed so a future native or web UI can read the same SQLite database without any migration.

The data model is stable, and the schema is documented. If you build a UI on top of Sidecar data, the commands and stored structure will remain compatible.