HOW fAI WORKS
No magic. Plain files, real git, and a loop you can inspect.
fAI runs alongside the tools you already use and keeps two things for you: a record of how you work that only ever grows, and a synthesis of it, rewritten in place so every tool starts already briefed. Here's the whole mechanism.
the record keeps history · the synthesis stays current
THE MECHANISM
Capture. Seal. Synthesize. Inject.
The record · only grows
Capture
A watch process polls your session transcripts as you work: every agent, Claude Code included. Each capture lands as its own commit. Nothing to configure.
Seal
On a cadence, each session journal seals into a git repo you own as a real merge, never a squash, so every capture stays reachable. You never do this by hand.
The synthesis · rewritten in place
Synthesize
The model you choose distills the record into decisions, patterns, context and petnames, and recompiles the pages they feed. Code, not the model, then assembles those pages into the fAI files.
Inject
fAI updates its own block in each agent's direction file (CLAUDE.md, AGENTS.md and the rest), pointing it at those files and leaving your own edits untouched. MCP serves the vault live to tools that speak it.
deno run -A "https://www.fathym.com/fai/install.deno"Install in seconds, free, open source, runs locally.
LAYER ONE · THE RECORD
The record only ever grows.
Every capture is its own commit, in plain JSONL, and every session seals back in as a real git merge. Nothing gets summarized away down here. Diff any two sessions, audit what changed, roll a capture back: the same moves you already trust for code, applied to your context.
Plain files. Git-backed. Yours forever.
LAYER TWO · THE SYNTHESIS
The files your AI starts every session with.
$ cat FAI-PROJECT.md## Decisions- Postgres over MySQL: row-level security drove it (2026-06-14) → decisions/postgres-over-mysql.md- JWT for auth: sessions stay stateless → decisions/jwt-auth.md## Patterns- Repository pattern for data access → patterns/repository-data-access.md- Errors: typed results, never thrown strings → patterns/typed-errors.md
No hidden store, no black box. Unlike the record, these files are rewritten in place: each pass recompiles them, so they stay current instead of growing forever. On startup your agent is pointed at three: FAI-SESSION.md for what you are doing now, FAI-PROJECT.md for what you are building, and FAI-PERSONAL.md for how you work. Your petnames sit beside them and reach your agents over MCP.
Here's the test: delete your .fai folder. You'll feel the regression immediately, the AI suddenly asking things it already knew, forgetting preferences you'd stopped thinking about. That gap is what fAI is filling.
Why a rewrite can't hollow it out
FAI-PROJECT.md and FAI-PERSONAL.md are never rewritten end to end by a model. The model compiles each section page; code then assembles those pages under fixed headings, in a fixed order. A thin section shows up as a thin section, not as a file that quietly reorganized itself overnight.
“No LLM: the primary is a deterministic assembly, so it never drifts and never hollows.”
WHAT SYNTHESIS PRODUCES
Decisions, patterns, context, and shorthands you reuse.
Decisions
What you chose and why, so nothing gets relitigated next session.
Patterns
The approaches you repeat, distilled from what you actually did.
Context
The living picture of the project and how you work, refreshed every pass.
Petnames
Reusable prompt shorthands: name a thing once, use it everywhere.
On the roadmap: crystallization goes further. Workflows you repeat become micro-agents: small, fast tools built from the way you already work. They run the routine jobs without a full model call, so you save the AI for the work that needs it.
SESSIONS
Named, resumable, never lost.
A session is the thread your work is captured into. Keep one running on a project for months, or start a fresh one and name it when you want a clean thread. Either way, when you run fai you choose where to carry on, and everything captured there is still there.
$ fai$ fai --auto$ fai sessions list$ fai? Resume a session❯ my-app · 4 months ago · active, 2 terminalsbilling · 3 months ago · 214 capturesStart new session
SHARING
Share it the way you share code.
Your vault is a git repo like any other, so sharing works the way you already know: push it to a private remote you control (GitHub, your own server), and a teammate pulls it to bring your context into their setup. You choose what to share and when: nothing propagates automatically. When your team wants shared, living context with review built in, that's OpenX →
See it run on your own project.
deno run -A "https://www.fathym.com/fai/install.deno"