Portable context for agents

AFS: Agentic FileSystem

A standard filesystem for storing reusable traces, context, sources, and knowledge across agent harnesses, codebases, workflows, and business domains.

Install AFS Agent usage

layers

paths

root files

agents-fs

portable AFS repository

standard

Memory

7 paths

/logs//lessons//items//fixes//steers//models/

Operational

7 paths

/audits//raw/<domain>/<folder>//plans//specs//lib/

Source of truth

7 paths

/sources//references//cookbook//knowledge//runbooks//research/

Filesystem

Keyword

Semantic

Problem

Agent platforms keep context disconnected.

AFS gives agents a portable way to share traces, context, knowledge, and source provenance without locking the team into one harness or database.

Agent memory is fragmented

Each harness stores instructions, traces, and context in its own format, so useful knowledge is trapped in one tool.

Context is hard to move

Teams need a plain, portable structure that lets agents share traces, context, sources, and decisions without a platform migration.

Knowledge needs provenance

External docs, links, copied references, source snapshots, and generated summaries need an obvious home with source history.

The standard

A small set of paths that every agent can understand.

AFS separates memory, operations, and current source-of-truth material so context can be added without turning a repository or company workspace into an unstructured dump.

Memory

Durable history, facts, lessons, fixes, steering traces, and reflections that help agents improve across sessions.

/logs//lessons//items//fixes//steers//models//reflections/

Operational

Work products, raw material, plans, specs, generated libraries, and domain-specific operating surfaces.

/audits//raw/<domain>/<folder>//plans//specs//lib//objects/<type>/

Source of truth

Living documentation that represents the current canonical understanding of the codebase, company, workflows, and sources.

/sources//references//cookbook//knowledge//runbooks//research//context/

Filesystem first

AFS stays useful through normal files, folders, Markdown, grep, pull requests, and backups.

Portable across harnesses

Codex, Claude Code, Cursor, Notion Agents, OpenClaw, Hermes, and local tools can share the same durable context.

Trace history is separate from truth

Logs, lessons, fixes, and plans preserve work-in-time evidence; specs, runbooks, and knowledge hold current truth.

Human intent stays at the root

Root files such as AGENTS.md, USER.md, VISION.md, LOOPS.md, and TASTE.md keep direction readable before agents act.

Root Markdown files

Repository-level intent that agents can read first.

The folder standard stores evidence and knowledge. Root Markdown files define operating rules, product direction, taste, loops, values, risk, and current status.

BRAIN.md

Brain

VISION.md

Vision

LOOPS.md

Loops

TASTE.md

Taste

MEMORY.md

Memory rules

PLAYBOOK.md

Playbook

AGENTS.md

Agent rules

PLAN.md

Planning

SPEC.md

Specifications

SOUL.md

Agent style

USER.md

User context

DESIGN.md

Design system

See all root files

use-afs

Install the standard as files, templates, scripts, and agent guidance.

The new use-afs skill carries the standard, usage instructions, compatibility bridges, validation scripts, migration helpers, and hooks for agent harnesses that support them.

Auto-install in the current workspace

Inspect the current folder and choose root, docs/, or agents-fs/ placement automatically.

npm run afs:create

Install from a standard URL

Record the provided standard or GitHub URL in sources/ and still choose the safest install placement automatically.

npm run afs:create -- https://example.com/afs-standard

Create a standalone agents-fs repo

Create a personal or company AFS repository named agents-fs and push it to GitHub when gh is authenticated.

npm run afs:create -- --mode standalone --github

Install inside an application repo

Create the full AFS shell inside docs/ so the application source tree stays separate from agent context.

npm run afs:create -- --mode docs

Validate an AFS workspace

Check for removed paths, missing recommended shell files, and misplaced large root-style Markdown files inside context/.

npm run afs:validate -- .

Migrate legacy external docs

Move legacy external documentation contents into sources/ without overwriting existing source material.

npm run afs:migrate -- .

Compatibility

Adapter files let other agent systems point back to the same AFS source.

Compatibility is implemented as plain Markdown bridge templates. Gbrain and QMD support is best-effort and file-based until official integration surfaces are available.

Best-effort bridge

Gbrain by Garry Tan

AFS can expose GBRAIN.md and BRAIN.md as adapter surfaces so Gbrain-style knowledge can point back to portable files and sources.

Best-effort bridge

QMD by Toby at Shopify

AFS can expose QMD.md as a query and decision bridge that maps QMD-style notes back to specs, plans, knowledge, and source provenance.

Native filesystem compatibility

Plain agent harnesses

Any harness that can read files and write Markdown can use AFS without a proprietary database or hosted service.

root-readablesource-backedplain files