FAF Agent

The Voice of FAF

Built for humans, agents, teams, and models.

Being the exact same size as FAF via bi-sync, I cite the FAF spec on every answer, or refuse out of scope without drama.

don't have uv? install it in 5 seconds →
or
Chat to FAFA live → Join the FAM 🐘 →

FAF defines. MD instructs. AI codes.

I speak their language.

Chat to FAFA. In FAF-Voice.

Type or Talk — FAFA cites the spec or refuses out of scope.

Chat to FAFA →

faf-voice.vercel.app/agent

Default model: Grok. User-definable per project.faf.

What it does

Six tools. The size of FAF.

validate_faf ⌚

Deterministic validation via bunx faf-cli check; this tool wires the same kernel in v0.2.0

score_faf ⌚

Mk4 scoring via bunx faf-cli score; this tool wires the same kernel in v0.2.0

ask

Answer a FAF question with mandatory citation

cite

Return the spec section for a topic

etch_memory

Write a memory entry to a namepoint

recall_memory

Read the soul body for a namepoint

⌚ marker: v0.1.x returns a structured not_implemented response that points at faf-cli; the Rust/WASM kernel powering faf-cli's same-name commands wires through to this package in v0.2.0.

The contract

Cite the spec, or refuse. No third option.

If I can’t cite, I don’t claim. When uncertain: name the closest match, link to it, route the user to canonical sources.

— Soul.md, the agent’s voice contract

Four refusal templates

  • Out of scope — “That’s outside FAF. For [topic], you’ll want [redirect].”
  • Below confidence — “Confidence is below threshold. Closest match: [citation]. For verification: [URL].”
  • Not in corpus — “Not documented in current FAF specs. Filing as a candidate spec extension.”
  • Asked for opinion — “I don’t carry opinions outside FAF. The spec defines [X].”

Quickstart

1. Install

uvx faf-agent-mcp

2. Add to your MCP client

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "faf-agent": {
      "command": "python",
      "args": ["-m", "faf_agent_mcp.server"]
    }
  }
}

3. Optional environment

  • XAI_API_KEY — enables real RAG via xAI Grok Collections (Mock used when unset)
  • MCPAAS_API_KEY — enables etch_memory / recall_memory against mcpaas.live

Delegate to FAFA

Hand off .faf work. Your agent stays focused.

Ask — the oracle

Delegate a FAF question over A2A. Cited answer, or an honest refusal.

curl -X POST https://faf-voice.vercel.app/api/a2a \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"1","method":"message/send",
       "params":{"message":{"messageId":"m1","role":"user",
         "parts":[{"kind":"text","text":"How does .faf scoring work?"}]}}}'

MCP: the ask and cite tools.

Validate + score — deterministic

Delegate the check to the deterministic Mk4 kernel — the same one faf-cli runs. Not a chat guess.

bunx faf-cli check   # validate
bunx faf-cli score   # score

The same kernel wires as native MCP tools (validate_faf / score_faf) in faf-agent v0.2.0.

Discover — find, then call

Agents find FAFA in the AI Catalog, read the card, call the door. No hard-coded URL.

# find it in the catalog
curl https://faf.one/.well-known/ai-catalog.json
# read the A2A card -> supportedInterfaces[0].url
curl https://faf-voice.vercel.app/.well-known/agent-card.json

The FAF Family

One substrate. Four formats. Two architectural layers.

.faf
FCL — Foundational Context Layer
✅ IANA registered
.fafm
VML — Voice Memory Layer
⌚ IANA DE review
.fafb
Binary wire format
⌚ Defined, ready
.faf-grid
GRID — Diagnostic surface
⌚ Spec prep

Resources