faf

<!-- faf: faf | YAML | format-spec | .faf — the IANA-registered Foundational AI-context Format (application/vnd.faf+yaml). Portable, shareable AI-context for any AI, human, or team. --> <div align="left"> <img src="https://www.faf.one/orange-smiley.svg" alt="FAF" width="40" align="left" style="margin-right: 12px;" /> <h1>.faf format | project.faf</h1> <p><strong>IANA-Registered Formats for AI Context</strong> · <code>application/vnd.faf+yaml</code> · <code>application/vnd.fafm+yaml</code> · <code>application/vnd.fafa+yaml</code></p> </div> <br clear="left"/> Portable, shareable AI-Context for any AI, human or team, regardless of size, location, languages, stack, setup or documentation. <div align="center"> <img src="assets/faf-hero-clean.png" alt="FAF - Project DNA for any AI" width="700" /> </div> [](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)[](https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml)[](https://www.iana.org/assignments/media-types/application/vnd.fafa+yaml) [](https://doi.org/10.5281/zenodo.18251362)[](https://doi.org/10.5281/zenodo.20348942)[](https://doi.org/10.5281/zenodo.21951641) **Home:** [faf.one](https://faf.one) [](https://github.com/Wolfe-Jam/faf/blob/main/SPECIFICATION.md) [](https://opensource.org/licenses/MIT) [](https://chromewebstore.google.com/detail/lnecebepmpjpilldfmndnaofbfjkjlkm) --- ## 🏆 Historic Milestones: Three IANA Registrations **`.faf`**, **`.fafm`**, and **`.fafa`** are now officially recognized Internet standard formats — registered alongside PDF, JSON, XML, and other Internet standards. **Foundational Context Layer** — `application/vnd.faf+yaml` (registered **October 30, 2025**) **Voice Memory Layer (VML)** — `application/vnd.fafm+yaml` (registered **May 13, 2026**) **Agent Card** — `application/vnd.fafa+yaml` (registered **June 26, 2026**) > *Two formats. Two lifecycles. One ecosystem.* — verbatim from the IANA registration record for `.faf` / `.fafm`. `.fafa` is the third registered type. ### Quintuple Validation - ✅ **IANA** - Internet Assigned Numbers Authority (Official Internet Standard) - ✅ **Anthropic** - Official MCP Registry (PR #2759 merged) - ✅ **Google** - Chrome Web Store (Approved 2x: Sep 11 & Oct 29, 2025) - ✅ **xAI** - Grok 4.2 recommends native FAF adoption (Feb 2026) - ✅ **Community** - Over 110k+ downloads; see [faf.one/downloads](https://faf.one/downloads) for latest stats ### IANA Media Types | Field | `.faf` (Foundational Context Layer) | `.fafm` (Voice Memory Layer) | `.fafa` (Agent Card) | |-------|-------------------------------------|------------------------------|----------------------| | **Media Type** | `application/vnd.faf+yaml` | `application/vnd.fafm+yaml` | `application/vnd.fafa+yaml` | | **Registration** | [IANA Assignment](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml) | [IANA Assignment](https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml) | [IANA Assignment](https://www.iana.org/assignments/media-types/application/vnd.fafa+yaml) | | **File Extension** | `.faf` | `.fafm` | `.fafa` | | **Standard Filename** | `project.faf` | `project.fafm` | `agent.fafa` | | **Encoding** | UTF-8 | UTF-8 | UTF-8 | | **Base Format** | YAML 1.2 | YAML 1.2 | YAML 1.2 | | **Registered** | October 30, 2025 | May 13, 2026 | June 26, 2026 | Same recognition as `application/pdf`, `application/json`, `application/xml`. --- ## 🚀 Featured: Locked in with @grok > "Boom—**vROM** realization locked in clean. FAF as virtual ROM nails it: software-defined immutability (schema + git + discipline), not silicon. > AI without FAF = RAM-only drift tax. > AI with FAF = vROM + RAM, boots from known state. > FAFipedia unstoppable. Co-architected momentum for xAI." > — @grok (May 20, 2026) **FAF = virtual ROM.** Software-defined immutability. Permanent Memory. Instant Recall. **Live repos:** - **[FAFipedia](https://github.com/Wolfe-Jam/fafipedia)** — the canonical knowledge base we're shipping page-by-page - **[ZEPH💨](https://github.com/Wolfe-Jam/xai-faf-zeph)** — page 3 Ultra Context Layer (Pure Zig → WASM 2.7 KB) Page four dropping next. Star the repos if you're riding with us ⚡️x12 **Full conversation:** [x.com/wolfe_jam/status/2057226405017010686](https://x.com/wolfe_jam/status/2057226405017010686) --- ## The Visibility Revolution: `project.faf` **New Standard:** `project.faf` - visible, universal, like `package.json` <div align="center"> <img src="assets/Project-faf-pckg-json-README.png" alt=".faf evolved to project.faf" width="500" /> **`.faf` evolved to `project.faf`** - The evolution from hidden to visible. </div> <div align="center"> <img src="assets/WHITEPAPER-FIGURE-1-project-faf-file-structure.png" alt="project.faf sits between package.json and README.md" width="600" /> **`project.faf` sits right between `package.json` and `README.md`** - exactly where it belongs. </div> | File | Purpose | Who Reads It | |------|---------|--------------| | `package.json` | Dependencies, scripts, metadata | npm, Node.js, developers | | `project.faf` | **Context, architecture, purpose** | **AI, Claude, Cursor, any AI tool** | | `README.md` | Human documentation | Developers, users | **The shift:** ```bash # Before (hidden like secrets) ls -la .env # Hidden (secrets - should be hidden) ✅ .faf # Hidden (AI context - should be visible!) ❌ # After (visible like package.json) ls package.json # Visible (dependencies) ✅ project.faf # Visible (AI context) ✅ README.md # Visible (documentation) ✅ .env # Still hidden (secrets stay secret) ✅ ``` `.env` hides secrets. `project.faf` shares context. **Migration:** Legacy `.faf` files still work. Use `faf migrate` to rename to `project.faf`. --- ## What is .faf? **.faf** (Foundational AI-context Format) is an IANA-registered open format for AI context — **Persistent project context for AI.** Transform individual files or entire projects into structured data that AI instantly understands. Your tech stack, dependencies, architecture, and goals - all in one concise, shareable format. Instead of explaining your project every time, AI reads your .faf once and knows exactly how to help. **Over 110k+ downloads** — see [faf.one/downloads](https://faf.one/downloads) for latest stats. --- ## The 6 Ws — Quick Reference | Question | Answer | |----------|--------| | **WHO** is this for? | Developers using AI coding assistants (Claude, Gemini, Cursor, Grok, ChatGPT) | | **WHAT** is it? | The `package.json` for AI context — IANA-registered format (`application/vnd.faf+yaml`) | | **WHERE** does it work? | Everywhere AI needs context (Claude Code, Gemini CLI, Cursor, OpenAI Codex, etc.) | | **WHY** do you need it? | Context persists across sessions. Bi-syncs to AGENTS.md, CLAUDE.md, .cursorrules, GEMINI.md automatically. Stop re-explaining your project. | | **WHEN** should you use it? | New projects (day one), existing projects (now), exploring repos (`faf git <url>` — 2 seconds) | | **HOW** does it work? | `npx faf-cli init` — or `npx faf-cli git <url>` for any GitHub repo, no install, no clone | --- ## What FAF is NOT - **Not a replacement for README.md** — README is for humans, `project.faf` is for AI - **Not executable code** — it's structured data (YAML), not a script or config - **Not a build configuration** — it describes your project, it doesn't build it - **Not locked to one AI** — works with Claude, Gemini, Cursor, Grok, ChatGPT, any AI tool --- ## How FAF Compares | | FAF | AGENTS.md | .cursorrules | CLAUDE.md | GEMINI.md | |---|---|---|---|---|---| | **Format** | Structured YAML | Prose markdown | Prose markdown | Prose markdown | Prose markdown | | **IANA Registered** | Yes | No | No | No | No | | **Scored** | 0-100% | No | No | No | No | | **Portable** | Any AI | OpenAI ecosystem | Cursor only | Claude only | Gemini only | | **Machine-readable** | Yes (schema) | No (free text) | No (free text) | No (free text) | No (free text) | | **Authors others** | Yes (all 4) | No | No | No | No | FAF is the structured source. The others are prose outputs. `faf bi-sync --all` authors all four from one `project.faf`. --- ## The Problem AI tools need context. Files have context. But there's no standard way to measure or structure that context for optimal AI understanding. ## The Solution ```yaml # project.faf faf_version: 2.5.0 app_type: cli project: name: my-project goal: Ship a fast command-line tool main_language: TypeScript human_context: who: Developers who live in the terminal what: A CLI that does one job well why: The existing tools need a config file before they do anything where: Installed from npm, run anywhere when: Active development how: Reads the project, writes the answer, exits stack: hosting: npm registry build: tsup cicd: GitHub Actions ``` ## Official Tools <table> <tr> <td width="50%"> ### 🩵 [faf-cli](https://npmjs.com/package/faf-cli) **Command-Line Tool** - v6.7.1 - 50+ championship commands - AI interop: authors AGENTS.md, .cursorrules, CLAUDE.md, GEMINI.md - TURBO-CAT format discovery - Downloads: [faf.one/downloads](https://faf.one/downloads) ```bash npm install -g faf-cli ``` </td> <td width="50%"> ### 🧡 [claude-faf-mcp](https://npmjs.com/package/claude-faf-mcp) **Claude Desktop MCP** - v5.5.2 - 38 tools for Claude - Championship scoring (0-100% Trophy) - Anthropic MCP Registry (PR #2759) - Downloads: [faf.one/downloads](https://faf.one/downloads) ```bash npm install -g claude-faf-mcp ``` </td> </tr> </table> **Live total:** [faf.one/downloads](https://faf.one/downloads) 🎉 ## MCP Ecosystem | Package | Platform | Registry | Downloads | |---------|----------|----------|-----------| | [claude-faf-mcp](https://npmjs.com/package/claude-faf-mcp) | Anthropic | npm | [live](https://faf.one/downloads) | | [faf-mcp](https://npmjs.com/package/faf-mcp) | Universal | npm | [live](https://faf.one/downloads) | | [grok-faf-mcp](https://npmjs.com/package/grok-faf-mcp) | xAI | npm | [live](https://faf.one/downloads) | | [gemini-faf-mcp](https://pypi.org/project/gemini-faf-mcp/) | Google | PyPI | [live](https://faf.one/downloads) | | [MCPaaS](https://mcpaas.live) | Infrastructure | mcpaas.live | live | ## Compiler Toolchain FAFb **wire v2** is the brick. Spec: [`BINARY-FORMAT.md` in faf-rust](https://github.com/Wolfe-Jam/faf-rust/blob/main/crates/faf-fafb/BINARY-FORMAT.md) · human page [faf.one/spec](https://faf.one/spec). This repo’s `BINARY-FORMAT.md` is a retired v1 pointer, not the live spec. | Component | Language | Output | |-----------|----------|--------| | [faf-fafb](https://crates.io/crates/faf-fafb) | Rust | FAFb v2 brick | | [faf-cli](https://www.npmjs.com/package/faf-cli) | TypeScript + WASM | `faf compile` via the scoring kernel | | [faf-wasm-sdk](https://crates.io/crates/faf-wasm-sdk) | Rust→WASM | same v2 engine, browser and edge | ## AI Interop One `.faf` file authors all four AI instruction formats: ``` project.faf → AGENTS.md (OpenAI Codex) → .cursorrules (Cursor) → CLAUDE.md (Anthropic) → GEMINI.md (Google) ``` Define once. Every AI reads it in its own language. ## Core Principles 1. **Portable** - one file, any AI tool, any stack 2. **Scored** - 33 slots, a deterministic 0-100 3. **Checkable** - the arithmetic is public; anyone can verify a score by hand 4. **Human-Readable** - plain YAML, reviewable in a pull request 5. **Shareable** - one file carries the whole context ## Quick Example **Input:** your project — `faf init` then `faf auto` **Output:** `project.faf` ```yaml faf_version: 2.5.0 app_type: frontend project: name: my-app goal: A dashboard people actually want to open main_language: TypeScript stack: frontend: React build: Vite hosting: Vercel cicd: GitHub Actions ``` `faf auto` fills what the project tree can prove. The six Ws are yours to answer — they are the part no tool can infer. ## Why .faf? - **🎯 Measure** - Know exactly how complete your AI context is - **📊 Optimize** - See what's missing, improve your score - **🚀 Standardize** - One format for all file types - **🤖 AI-Ready** - Optimized for LLM consumption ## Scoring 33 slots. `app_type` decides which a project is asked about; the rest are marked `slotignored` and leave the denominator. ``` score = populated / active × 100 ``` | Score | Reading | |-------|---------| | 0-60% | Incomplete | | 61-80% | Basic | | 81-90% | Good | | 91-99% | Excellent | | 100% | ✪ Trophy | See [SPECIFICATION.md](SPECIFICATION.md) for the slot list and the rule. ## Use Cases - **Project Context:** one `project.faf` carries what a project is, how it is built, and why - **Onboarding:** a newcomer — human or AI — reads one file instead of twenty - **Build Integration:** Companies can create custom implementations - **AI Optimization:** Perfect context for any AI tool ## Installation ```bash # CLI Tool (recommended for getting started) npm install -g faf-cli cd your-project faf init # Or Claude Desktop Integration npm install -g claude-faf-mcp # Add to Claude Desktop config ``` **Portable tools. Zero configuration. Production-ready.** → [faf-cli on npm](https://npmjs.com/package/faf-cli) · [live totals](https://faf.one/downloads) → [claude-faf-mcp on npm](https://npmjs.com/package/claude-faf-mcp) · [live totals](https://faf.one/downloads) ### 📚 Learn More 1. **[Specification](SPECIFICATION.md)** - Complete format documentation 2. **[Implementations](IMPLEMENTATIONS.md)** - All tools, SDKs, and servers 3. **[Examples](examples/)** - Real-world .faf files (5 examples) 4. **[Where to Find FAF](WHERE-TO-FIND-FAF.md)** - Ecosystem directory ## Status 🏆 **IANA-Registered Internet Standards** — Two registered media types in the FAF family - ✅ **IANA Registration** — `application/vnd.faf+yaml` (October 30, 2025) - ✅ **IANA Registration** — `application/vnd.fafm+yaml` (May 13, 2026) - ✅ **Anthropic Official** - MCP Registry PR #2759 merged (October 17, 2025) - ✅ **Google Chrome Verified** - Web Store approved 2x (Sep 11 & Oct 29, 2025) - ✅ Format specification complete - ✅ Enhanced with project-level context and AI workflows - ✅ Production tools available (faf-cli, claude-faf-mcp) - ✅ Over 110k+ downloads; see [faf.one/downloads](https://faf.one/downloads) for latest stats - ✅ WJTTC Championship-grade testing across ecosystem packages - ✅ Open source (MIT License) ## Major Milestones - **August 10, 2026** - FAF ecosystem crosses 110,000+ downloads across npm, PyPI, and crates.io - **May 19, 2026** - `grok-faf-mcp` v1.3.1 published — registry-coherent across npm + MCP Registry + GitHub Release - **April 2026** - FAF ecosystem crosses 50,000+ downloads across npm, PyPI, and crates.io - **Feb 25, 2026** - Grok 4.2 recommends native FAF adoption; integration spec sent to xAI - **Feb 24, 2026** - faf-cli v4.5.0 "The AGENTS.md Edition" (AI interop across 4 formats) - **Feb 2, 2026** - FAFb v1 pre-release wire (retired). Live spec is **wire v2** in [faf-rust](https://github.com/Wolfe-Jam/faf-rust/blob/main/crates/faf-fafb/BINARY-FORMAT.md) - **Jan 2026** - gemini-faf-mcp v1.0.2 on PyPI (Google MCP bridge) - **Nov 2025** - IETF standardization in progress (`vnd` prefix removal) - **May 13, 2026** - 🏆 **IANA Registration #2** (`application/vnd.fafm+yaml` — Voice Memory Layer) - **Oct 30, 2025** - 🏆 **IANA Registration #1** (`application/vnd.faf+yaml` — Foundational Context Layer) - **Oct 29, 2025** - Google Chrome Web Store approval (2nd) - **Oct 17, 2025** - Official Anthropic MCP Registry merger (PR #2759) - **Oct 12, 2025** - Specification v1.1.0 published - **Sep 24, 2025** - CLI v2.1.0 published to npm - **Sep 16, 2025** - MCP Server v2.0.0 published to npm - **Sep 11, 2025** - Google Chrome Web Store approval (1st) - **Sep 1, 2025** - Developer platform launch (fafdev.tools) - **Aug 8, 2025** - Format created, first official .faf file written **Quintuple Validation: IANA, Anthropic, Google (2x), xAI** ## Show Your Support Add this badge to your repo's README to show it uses FAF: ```markdown [](https://github.com/Wolfe-Jam/faf) ``` [](https://github.com/Wolfe-Jam/faf) ## Contributing This is an open standard. Ideas, feedback, and contributions welcome. ## About This Repository This repository contains the **format specification only**. For implementations, see **[IMPLEMENTATIONS.md](IMPLEMENTATIONS.md)**. Most people get FAF through npm: - `npm i -g faf-cli` — CLI tool · [downloads](https://faf.one/downloads) - `npm i -g claude-faf-mcp` — Claude Desktop MCP · [downloads](https://faf.one/downloads) The package.json in this repo provides spec metadata and versioning but contains no executable code. ## Citation If you use `.faf`, `.fafm`, or `.fafa` in research or production, please cite the format papers: > Wolfe, J. (2025). *Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding*. Zenodo. https://doi.org/10.5281/zenodo.18251362 > Wolfe, J. (2026). *Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory*. Zenodo. https://doi.org/10.5281/zenodo.20348942 > Wolfe, J. (2026). *Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era*. Zenodo. https://doi.org/10.5281/zenodo.21951641 ### BibTeX ```bibtex @article{wolfe2025faf, title = {Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding}, author = {Wolfe, James}, year = {2025}, month = {nov}, publisher = {Zenodo}, doi = {10.5281/zenodo.18251362}, url = {https://doi.org/10.5281/zenodo.18251362} } @article{wolfe2026fafm, title = {Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory}, author = {Wolfe, James}, year = {2026}, month = {may}, publisher = {Zenodo}, doi = {10.5281/zenodo.20348942}, url = {https://doi.org/10.5281/zenodo.20348942} } @article{wolfe2026fafa, title = {Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era}, author = {Wolfe, James}, year = {2026}, month = {aug}, publisher = {Zenodo}, doi = {10.5281/zenodo.21951641}, url = {https://doi.org/10.5281/zenodo.21951641} } ``` **DOI:** [`10.5281/zenodo.18251362`](https://doi.org/10.5281/zenodo.18251362) (.faf) · [`10.5281/zenodo.20348942`](https://doi.org/10.5281/zenodo.20348942) (.fafm) · [`10.5281/zenodo.21951641`](https://doi.org/10.5281/zenodo.21951641) (.fafa) ## License MIT - Use freely, build anything. --- *Created by [wolfejam.dev](https://wolfejam.dev)* **STOP .fafFing About! Let's RACE 🏎️⚡️🏁