Content
<!-- faf: faf | YAML | format-spec | .faf — the IANA-registered Foundational AI-context Format (application/vnd.faf+yaml). Universal, 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"/>
Universal, 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
# example.faf
version: 1.0
score: 85
type: package
confidence: 0.92
content:
name: "my-project"
dependencies: ["react", "typescript", "vite"]
scripts: ["dev", "build", "test"]
metadata:
source: "package.json"
processed: "2024-01-26T12:00:00Z"
engine: "faf-v1"
```
## 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
FAF compiles to multiple targets:
| Component | Language | Output |
|-----------|----------|--------|
| [xai-faf-rust](https://github.com/Wolfe-Jam/xai-faf-rust) | Rust | Native + .fafb binary |
| [xai-faf-zig](https://github.com/Wolfe-Jam/xai-faf-zig) | Zig→WASM | 2.7KB ghost binary |
| [faf-wasm-sdk](https://github.com/Wolfe-Jam/faf-wasm-sdk) | Rust→WASM | 211KB browser runtime |
## 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. **Universal** - 153+ file types supported
2. **Scored** - 0-100% context completeness score
3. **AI-Optimized** - Structured for maximum AI comprehension
4. **Human-Readable** - Simple, structured format
5. **Shareable** - One file contains complete context
## Quick Example
**Input:** `package.json`
```json
{
"name": "my-app",
"version": "1.0.0",
"dependencies": {
"react": "^18.0.0"
}
}
```
**Output:** `package.faf` (85% context score)
```yaml
version: 1.0
score: 85
type: package
content:
name: "my-app"
version: "1.0.0"
dependencies: ["react@^18.0.0"]
metadata:
processed: "2024-01-26"
```
## 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
## File Scoring
| Score | Meaning | AI Readiness |
|-------|---------|--------------|
| 0-60% | Incomplete | Poor context |
| 61-80% | Basic | Acceptable |
| 81-90% | Good | Recommended |
| 91-99% | Excellent | Optimal |
| 100% | Perfect | Maximum context |
## Use Cases
- **File Conversion:** Transform any file type into .faf format
- **Project Context:** Create a single .faf file for your entire project
- **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
```
**Universal 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 binary format v1.0 (Rust + Zig compilers shipping)
- **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 generated
**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 🏎️⚡️🏁
