Skip to main content

.faf format specification#

Illustration: a project's scattered facts (frameworks, tools, configuration, commands) gathered into one .faf file.

.faf is a YAML format for a project’s facts: its name, goal, main language, app type, stack, and the six W’s (who, what, why, where, when, how). The file is named project.faf and sits in the repository root, next to package.json. AI tools read it for context about the project.

This repository holds the specifications for .faf and its two sibling formats, with their JSON Schemas, conformance files and examples. It contains no executable code.

Media types#

The marks of the three formats: a smiley for .faf, an elephant for .fafm, a robot for .fafa.
FormatHoldsMedia typeStandard filenameRegistered with IANA
.fafproject factsapplication/vnd.faf+yamlproject.faf30 October 2025
.fafmmemoryapplication/vnd.fafm+yamlproject.fafm13 May 2026
.fafaan agent cardapplication/vnd.fafa+yamlagent.fafa26 June 2026

All three are UTF-8 encoded YAML 1.2.

Example#

A file is valid when it parses as YAML and has faf_version and project.name. Every other field is optional.

Scoring#

A .faf file has 33 slots. Each slot is populated, empty or slotignored. The app type (project.type) decides which slots are slotignored, and those leave the count.

ScoreTier
100%✪ Trophy
99%★ Gold
95%◆ Silver
85%◇ Bronze
70%● Green
55%● Yellow
1%○ Red
0%♡ White

The score is deterministic: the same file gets the same score from every conforming scorer. SPECIFICATION.md has the slot list and the rule.

Documents#

DocumentContents
SPECIFICATION.md.faf: fields, slots, scoring, validity
docs/EXAMPLES.mdone task per section: valid and invalid files, a 100% file, schema checks, .fafm, .fafa
MEMORY-FORMAT.md.fafm
AGENT-FORMAT.md.fafa
CONTEXT-INGESTION.mdhow a tool takes in .faf context
IMPLEMENTATIONS.mdtools that read or write the formats, with versions
schemas/JSON Schemas for .faf, .fafm and .fafa
conformance/files that must pass or fail, with the expected results
examples/example .faf and .fafm files

Tools#

faf-cli creates and scores project.faf:

FAF works with Claude, Cursor, Codex, Goose, OpenCode, Warp, Grok and Gemini, through the files each tool reads (project.faf, AGENTS.md, CLAUDE.md) or an MCP server. The MCP servers, a Rust implementation and the rest are listed in IMPLEMENTATIONS.md.

Citing#

CITATION.cff has the full records.

License#

MIT. Home: faf.one.