// the weave format

Knowledge your agents can trust - and you can take with you.

Weave is signed Markdown: every fact your agents rely on carries provenance, a hash of the code it describes, and an Ed25519 signature anyone can verify offline. When the code moves on, the fact flags itself stale.

Export a sample Weave See Mind, which writes it →

architecture.weave.md

--- fact: Auth uses device flow (RFC 8628) source: acme/api@a91f code_hash: a91f…3c2 ✓ fresh --- fact: Legacy webhook path /hooks/v0 code_hash: 2b7e…901 ⚠ STALE ---

Portable, signed, offline-verifiable.surfilpkg

The format

This is a Weave file

Frontmatter carries the trust machinery; the body is ordinary Markdown any agent - or human - can read.

architecture.weave.md

--- id: wv_arch status: active provenance: acme/api@a91f3c2 # repo@commit this fact came from code_hash: a91f3c2 # mismatch with HEAD → STALE, automatically signature: { epoch: 7, sig: 77be…901 } # Ed25519, offline-verifiable --- The API uses a hexagonal architecture. Adapters live in /adapters; domain logic never imports from the transport layer.

ⓘ surfil verify architecture.weave.md → VALID · works fully offline, no account required.

What each piece does

Six properties, one trustworthy fact

Together they answer the question agents can't answer alone: is this still true, and says who?

Signed Markdown

A Weave fact is a plain .md file with frontmatter - readable by you, by any agent, and by anything that parses Markdown. No proprietary binary blob.

Provenance

Every fact names its source: repo@commit. You always know where a piece of knowledge came from and when it was true.

code_hash

Each fact carries a hash of the code it describes. When the code changes underneath it, the mismatch is detected automatically.

STALE auto-flag

A code_hash mismatch flips the fact's status to STALE - agents stop trusting it and re-verify instead of acting on outdated knowledge.

Ed25519 signature

Facts are signed with epoch-versioned keys. Verification runs offline against the public key - no account, no API call.

Open format

The format is documented so other tools can read, write and verify Weave files. Your knowledge isn't hostage to Surfil.

Staleness

Facts that know when they've expired

The failure mode of every knowledge base is silent rot. Weave makes rot loud.

~/acme/api - surfil export

$ surfil mind stats ✓ 38 facts active ⚠ 3 facts STALE (code_hash changed since signing) · rate-limits.weave.md - /auth/limits.rs modified · queue-config.weave.md - file deleted · db-schema.weave.md - migration applied # stale facts are excluded from agent context until re-verified

Portability

Yours to keep - .surfilpkg export

Weave is designed to outlive your subscription. Export everything, verify it forever.

Portable

surfil export packages your whole Weave - facts, receipts, signatures - as one .surfilpkg. It works after you cancel.

Verifiable forever

Signatures verify offline against published epoch keys. An exported receipt is proof for as long as you keep the file.

Open

The format is documented so other tools can build on it. Knowledge in Weave is never locked in.

See a Weave file from your own repo

Install Core - it bootstraps Weave on your first run. Export a sample anytime with surfil export.

Export a sample Weave Install Core →