Bevia Protocol

The open specification for the doors of a Bevia engine — how evidence goes in, and how understanding comes back out. If you can read or write a JSON file, you can build against Bevia.

• SPEC.md — the capture protocol (v1, the way in): capture body, drop-file convention, location object, behavioral guarantees. Versioned, additive-only.
• SPEC-EXPORT.md — the export protocol (v1.1, the way out): export records, drop-file and pull conventions, provenance guarantees.
• schema/ — JSON Schemas for validation.
• examples/ — real capture files (a chat session, a robot maintenance session, a captured note) and a matching export.
• tools/ — zero-dependency conformance tools: check-capture.mjs validates your capture bodies against the spec, and fake-engine.mjs is a local test double (HTTP + drop-file watcher) that answers honestly — what landed, what deduped, why something was rejected — so you can build a sensor without an engine.
• SENSOR-CHECKLIST.md — the five honesty rules every sensor should meet, with a troubleshooting table for "my data isn't landing."
• reference/ — reference sensor implementations.

The one-paragraph version

Bevia turns observed work — conversations, sessions, notes — into a navigable, queryable memory. This repo specifies the doors. In: the shape of a capture, how a file in a watched folder becomes evidence (*.bevia-capture.json — the file's content is the request body), and how a sensor stamps where knowledge happened. Out: the export record, how the engine's understanding lands as files or answers a pull (*.bevia-export.jsonl), and the guarantee that every record traces back to evidence. Everything here is open and free to implement, forever.

What this repo is not: the engine. How captures become understanding — the compilation, the cartography, the narration — is proprietary and is the product. Implementing this spec requires no license; running an engine does. Open doors, paid brain.

Quick start

In (sensor):

1. Write a capture file (copy one from examples/).
2. Name it anything.bevia-capture.json.
3. Put it in a folder your Bevia app watches.

Out (consumer):

1. Point your Bevia app's export at a folder.
2. Read *.bevia-export.jsonl — one record per line, deduped by id.

That's the whole integration, both directions. For a continuous sensor, see the reference implementations.

License

The spec, schemas, and examples in this repository are MIT-licensed. Bevia engines (Bevia Local, Bevia Cloud) are separate, proprietary products and are not covered by this license.