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 ⌚

Schema validation — deferred to v0.2.0; use bunx faf-cli check today

score_faf ⌚

Mk4 scoring — deferred to v0.2.0; use bunx faf-cli score today

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

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