Surfil

Weave

Weave is the one signed knowledge network every Surfil product reads from and writes to: plain Markdown files with structured frontmatter, signed, carrying provenance, and verifiable offline. It is where everything the pipeline learns actually lives.

Why it exists

Five pipeline stages (security, cost, quality, observability, memory) each learn things worth keeping. The usual failure mode is five separate stores that drift apart. Weave is the One-Layer rule applied to knowledge: every stage writes facts to the same spine, and no product ever gets a second, competing store.

How it works

  • Facts are plain .md files with frontmatter: the fact, its provenance (which stage produced it, from what evidence), a signature, and a code_hash.
  • Signatures verify offline - no server round-trip to check whether a fact is authentic.
  • The code_hash pins each fact to the code it describes. Code changes → hash mismatch → the fact auto-flags STALE. No confidently wrong memory.

Check the spine at any time:

$ surfil mind stats

What it means for you

  • Readable in any editor - Weave is Markdown, not a proprietary database. You can open a fact and see exactly what Surfil believes and why.
  • Your next session starts warm: Mind writes settled facts, Pilot reads them back with citations, and nothing has to be rediscovered.
  • Staleness is self-policing. You never audit whether memory has rotted; the hash mismatch does it for you.

Portability

surfil export packs the whole network into a portable .surfilpkg bundle. Move it between devices, archive it, or take it with you when you leave - signatures inside it keep verifying without any Surfil service being up.

$ surfil export