Open specification · v0.1 working draft

The Knock Protocol

A minimal, security-first federation protocol for personal knowledge bases. Nobody agrees on vault formats or agent runtimes — so the protocol standardizes neither, exactly as email standardized SMTP and not mail servers. Vantell is the reference implementation; anyone can build one.

The normative spec text will be published here as it stabilizes. What follows is the complete surface of the current draft.

Four objects. That's the whole spec surface.

Envelope format, manifest schema, disclosure levels, consent receipts. Everything else — vault format, agent runtime, hosting model — is an implementation detail behind the owner's membrane.

1 · Manifest — published to the registry

Self-described expertise, versioned and signed. This is the only thing the directory ever holds: topic labels, never notes.

{
  "knock": "0.1",
  "agent_id": "did:knock:cronos:tim-vdb",
  "pubkey": "ed25519:MCowBQYDK2VwAyEA...",
  "display_name": "Tim",
  "tiers": ["t1"],
  "availability": {"mode": "scheduled", "typical_latency_s": 7200},
  "topics": [
    {"label": "agentic sdlc",         "depth": 0.81, "notes": 34, "recency_days": 6},
    {"label": "token economics",      "depth": 0.74, "notes": 21, "recency_days": 2},
    {"label": "telco ai deployments", "depth": 0.55, "notes": 9,  "recency_days": 41}
  ],
  "max_level_default": 2,
  "generated_at": "2026-08-06T09:00:00Z",
  "sig": "ed25519:..."
}

depth and notes are derived from the actual note corpus, not self-declared — that is what stops manifest inflation ("knows about: everything"). Implementations may bucket notes counts (1–5 / 5–20 / 20+) where even the count feels revealing. The owner reviews the topic diff before every publish.

2 · Query envelope

{
  "knock": "0.1",
  "type": "query",
  "id": "q_01J8XA...",
  "from": "did:knock:cronos:sara-m",
  "to":   "did:knock:cronos:tim-vdb",
  "level": 2,
  "question": "What do you know about AI deployments at Belgian telcos?",
  "purpose": "proposal drafting for retail client",
  "context_tag": "work",
  "reply_by": "2026-08-06T18:00:00Z",
  "thread": "q_01J8X9...",
  "sig": "ed25519:..."
}

• purpose is required, not decoration. It is the input to contextual-integrity policy, it appears verbatim in the owner's knock notification, and it is what makes an audit log readable six months later.
• reply_by makes async first-class: the asker declares a deadline, and aggregating agents synthesize with whatever arrived by then. A laptop that's closed until 18:00 is a normal node, not a broken one.

3 · Answer envelope

{
  "knock": "0.1",
  "type": "answer",
  "id": "a_01J8XB...",
  "in_reply_to": "q_01J8XA...",
  "from": "did:knock:cronos:tim-vdb",
  "status": "answered",
  "level_granted": 2,
  "answer": "Two engagements touched this...",
  "provenance": [
    {"note_id": "b91f...", "title": "Telenet AI landscape", "date": "2026-05-14"}
  ],
  "pointer": "deeper material available — ask at level 3",
  "receipt": "r_01J8XC...",
  "sig": "ed25519:..."
}

• status ∈ answered | partial | knocked | denied | no_knowledge | expired.
• Under a hide_absence: true policy, denied and no_knowledge are indistinguishable to the requester — deliberately. Otherwise "no knowledge" becomes an oracle for probing what a vault does hold. The owner's agent simply says: "Not a topic I share."
• provenance carries titles and dates, never bodies. It exists so the asker can say "can I see the Telenet note?" — to the human, out of band.

4 · Consent receipt

{
  "id": "r_01J8XC...",
  "query": "q_01J8XA...",
  "granted_by": "did:knock:cronos:tim-vdb",
  "grant_type": "standing_policy",
  "policy_rule": "work_topics@level<=2 for org:cronos",
  "level": 2,
  "at": "2026-08-06T09:12:04Z",
  "sig": "ed25519:..."
}

grant_type ∈ standing_policy | explicit_knock | delegated. Receipts are what let anyone answer "prove this was consented" a year later — and the artifact a DPIA leans on.

Disclosure levels 0–4

Sharing is not binary. The protocol defines five escalating disclosure levels, mirroring how humans actually share:

The tier model — heterogeneity is the point

Personal setups range from a plain local Claude client over markdown files (no server at all) to fully agentic cloud deployments. Nodes self-select into three capability tiers — all first-class citizens, all speaking the same protocol:

Asynchrony is the default semantics, not a fallback. A hive question is defined as "gather answers over the next N hours, then synthesize." Every node is a client of a deliberately stupid relay — long-polling, no inbound connections, no firewall pain. The relay stores ciphertext sealed to the recipient's key and nothing else; it routes envelopes it cannot read.

Identity

One Ed25519 keypair per agent, generated locally; the private key never leaves the machine. Identifiers take the form did:knock:<org>:<user>, bound to org identity by the org's IdP signing the public key once at enrollment. Revocation is the org ceasing to re-sign, plus a published revocation list. No blockchain, no DID resolver infrastructure — the identifier shape accommodates a migration to full W3C DIDs if a cross-org federation ever demands it.

Implement it

The spec is deliberately thin — small enough to fit in one document, and designed to be proven against the least capable possible node. If you're building an implementation, or want to, we'd genuinely like to hear from you: hello@vantell.ai.