● v0.1 draft

The specification.

An open, minimum specification for portable AI grounding. Five primitives. Each does one job.

The minimum specification

1. Factlet record format

YAML canonical. Required fields: id, statement, confidence (0.0-1.0), sources (file:line, commit, doc). Optional: supersedes, merged_into, archived, archived_reason, retired_at, tags, scope_level. Renders per-vendor: structured XML for Claude, markdown for GPT, systemInstruction for Gemini. The renderer is a separate concern from the canonical store.

2. FactMap structural index

A spatial organization of factlets — per directory, per module, per domain, per customer, per feature. Implementations choose the structure that fits their domain. The contract is: given a query, return the relevant subset of factlets and the structural region they cover.

3. Factbook container

A packaged YAML container with schema_version, last_updated, and the content array of factlets. Portable across implementations. Versioned in git so the team owns the artifact and can roll back.

4. FactSignal scoring function

A function with signature factsignal(query, factmap) → bars (integer 0 to 5). Implementations may use embedding-based scoring, keyword scoring, graph scoring, or LLM scoring. The contract is the bars output, not the algorithm. Bars represent: 5 = dense coverage, 4 = good, 3 = mixed, 2 = sparse, 1 = thin, 0 = dead zone.

5. Low-FactSignal warning hook

A required runtime callback that fires when factsignal(query) < threshold (default 2). The hook receives the query, the FactSignal score, and the retrieved factlets. The consuming agent decides what to do: warn the user, escalate, refuse to answer, log the event. The protocol mandates the signal; the policy is the agent's.

Sample Factbook

schema_version: v1.0
content:
  - id: f001
    statement: "We use Stripe webhooks (not polling) for payment status updates."
    confidence: 0.95
    sources: ["docs/payments-arch.md:42", "commit:abc123"]
    tags: [payments, architecture]

  - id: f002
    statement: "Refunds older than 90 days require manual ops approval, never auto-processed."
    confidence: 1.0
    sources: ["docs/refund-policy.md:8"]
    tags: [payments, ops, compliance]

Full v0.1 spec

Coming soon. The full specification with edge cases, schema details, and interop rules is being finalized. To track progress or propose an RFC, see github.com/factlet-ai/spec and its Discussions.

Reference implementations