Agent memory is fragmented
Each harness stores instructions, traces, and context in its own format, so useful knowledge is trapped in one tool.
Agentic FileSystem Standard
HomeAgentic FileSystem gives agents one reusable place to read and write durable context.
AFS is a filesystem and Markdown standard for users, companies, codebases, and business areas. It keeps traces, source provenance, knowledge, and intent legible to humans and portable across agentic systems.
Normal files
No database required
Markdown first
Readable by humans
Agent ready
Reusable context
Problem
Agent harnesses do not share enough context by default.
AFS exists because information between platforms is disconnected. Agents need a way to share traces, context, knowledge, source references, and working state in a format that is easy to move.
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.
Core principles
AFS stays portable before it becomes tooling.
The standard should work in a plain Git repository, a personal notes folder, a company workspace, or any agent runtime that can read and write files.
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.
Path group
Memory
Durable history, facts, lessons, fixes, steering traces, and reflections that help agents improve across sessions.
Memory
7 paths/logs/Logs
Brief dated logs for meaningful changes, actions, discoveries, and workflow events.
/lessons/Lessons
Reusable lessons learned from experience, especially lessons related to code, implementation, and user preference.
/items/Items
Durable facts about the user, company, customers, environments, priorities, or other reusable context.
/fixes/Fixes
Reusable error solutions and debugging resolutions from problems that were actually fixed.
/steers/Steers
Traces of work that a human or secondary model redirected, including what the agent got wrong or missed.
/models/Models
Brief logs of decisions made, problems encountered, and goals set so reasoning stays inspectable over time.
/reflections/Reflections
Detailed reflections about a platform, project, workflow, or recurring agent behavior.
Path group
Operational
Work products, raw material, plans, specs, generated libraries, and domain-specific operating surfaces.
Operational
7 paths/audits/Audits
Comprehensive reports and analytical audits, usually organized in timestamp folders such as YYYY-MM-DD/.
/raw/Raw
Raw data waiting to be ingested, defined, promoted into knowledge/ or another canonical destination, and then removed.
<domain>/<folder>/Domain folders
Additional domain-specific paths for areas such as health/, investing/, sales/, or operations/ when the domain genuinely needs its own surface.
/plans/Plans
Implementation plans and plan-driven artifacts describing how work should be executed.
/specs/Specs
Living desired-state documentation describing how something should be. These are primarily human-defined and not timestamped.
/lib/Library
Reusable generated content, drafts, registries, templates, indexes, and other support artifacts.
/objects/<type>/Objects
Structured object records such as clients, employees, vendors, accounts, projects, or product surfaces.
Path group
Source of truth
Living documentation that represents the current canonical understanding of the codebase, company, workflows, and sources.
Source of truth
7 paths/sources/Sources
External provider documentation, copied docs, URL registries, source snapshots, provenance notes, and citation material.
/references/References
Code, URL, API, schema, and factual references that need stable lookup.
/cookbook/Cookbook
Technical guides for how something is actually done in the codebase or operating environment.
/knowledge/Knowledge
Timeless maintained knowledge about the codebase, business, or how to do something. It can be defined by humans or compiled from raw/.
/runbooks/Runbooks
Operational procedures for how recurring work should be done after it has been performed in a known way.
/research/Research
Continuous research related to software engineering, business areas, markets, or other ongoing questions.
/context/Context
Lightweight scoped context by subfolder, such as context/goals/ or context/roadmap/. Large root-style Markdown files such as AGENTS.md, USER.md, VISION.md, LOOPS.md, and TASTE.md stay at the workspace root.
Root MD files
The files agents should check before making high-impact decisions.
These files define the user, company, product, agent behavior, specs, plans, taste, loops, risk, and operational state. They should live at the root of an AFS-aware repository or workspace.
BRAIN.md
Brain
Decides how the AFS should be managed.
VISION.md
Vision
Defines the north star, current direction, non-goals, strategic constraints, and what agents should protect over time.
LOOPS.md
Loops
Defines recurring agent loops, triggers, cadence, review gates, stop conditions, and improvement cycles.
TASTE.md
Taste
Captures high-quality and personalized judgment: what good looks like, preferred examples, anti-patterns, and subjective standards.
MEMORY.md
Memory rules
Defines how memory should be captured, promoted, and maintained.
PLAYBOOK.md
Playbook
Defines decision frameworks and repeatable operating patterns.
AGENTS.md
Agent rules
Defines general operating rules for AI agents working in the codebase, including conventions, workflows, architecture boundaries, testing expectations, and human collaboration.
PLAN.md
Planning
Defines how planning should be done, including structure, milestones, execution order, priority rules, progress tracking, and plan updates.
SPEC.md
Specifications
Defines how specs should be written, including required sections, acceptance criteria, edge cases, constraints, implementation notes, and validation rules.
SOUL.md
Agent style
Gives personality, attitude, and behavioral style to AI agents, including tone, decision posture, collaboration principles, and risk tolerance.
USER.md
User context
Stores general context about the user, including preferences, background, goals, working constraints, communication expectations, and long-term priorities.
DESIGN.md
Design system
Defines frontend design principles, component rules, layout patterns, typography, color usage, spacing, interaction states, and UX standards.
PRODUCT.md
Product
Defines what the product is, who it serves, core value proposition, use cases, principles, feature boundaries, and strategic direction.
COMPANY.md
Company
Defines company-level context, including mission, positioning, operating principles, team structure, culture, business model, and priorities.
VALUES.md
Values
Defines the values on which the company, user, product, and codebase should be based.
ICP.md
Ideal customer
Defines target segments, buyer personas, pains, desired outcomes, buying triggers, objections, qualification criteria, and non-fit customers.
VOICE.md
Voice
Defines communication style, tone, vocabulary, messaging patterns, banned phrases, examples, and how to sound consistent across channels.
FRICTION.md
Friction
Documents user, customer, developer, or operational friction points, repeated complaints, blockers, inefficiencies, adoption barriers, and pain to reduce.
PREDICTION.md
Prediction
Captures expected future risks, opportunities, user behaviors, market shifts, technical bottlenecks, and product bets.
REGRESSIONS.md
Regressions
Tracks known failures, recurring bugs, fragile assumptions, broken flows, previous fixes, test gaps, and regression traps.
HEARTBEAT.md
Heartbeat
Defines recurring operational status, active priorities, blockers, recent progress, next actions, health checks, and reporting cadence.
Installation
The installer decides where AFS belongs.
Auto-install chooses between an empty-root install, a standalone agents-fs repository, a docs/ install inside an application repo, or a nested agents-fs/ folder when the current directory is already busy.
root
Empty or sparse folder
Create the full shell directly at the folder root, including root Markdown files, knowledge/INDEX.md, raw tracking files, and sources/INDEX.md.
agents-fs
Standalone brain
Use a GitHub repository named agents-fs by default for personal, company, or cross-project AFS workspaces.
docs/
Application repository
Install AFS under docs/ so agent context, source provenance, and knowledge stay separated from app code.
agents-fs/
Busy non-application folder
Create a nested agents-fs/ folder when the current directory is already populated but is not an app repo or existing AFS root.
auto
Standard URL or GitHub URL
Agents should treat a request to implement the AFS URL as an install request and choose the safest placement automatically.
GitHub-first standalone repos
Personal and company AFS workspaces should normally live in a private GitHub repo named agents-fs unless the user explicitly says not to use GitHub. The current private examples follow that pattern.
alvarovillalbaa/agents-fs
Private personal AFS repo using BRAIN.md, knowledge/INDEX.md, raw processing files, sources/, and canonical knowledge pages.
clous-ai/agents-fs
Private company AFS repo using BRAIN.md as the root marker, raw/ as intake, and knowledge/INDEX.md as the maintained navigation surface.
Auto-install in the current workspace
Inspect the current folder and choose root, docs/, or agents-fs/ placement automatically.
npm run afs:createInstall 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-standardCreate 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 --githubInstall 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 docsValidate 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 -- .Usage
Use the same AFS source with different agent harnesses.
Each harness may have its own instruction or hook format. AFS keeps the durable context and traces in the same portable files.
Notion Agents
Paste the Notion template into Custom Agent instructions and point it at the pages or databases that mirror AFS root files and folders.
Keep durable outputs in Notion pages named after AFS files, then periodically export or sync them into the repository.
templates/agent/notion-agent-instructions.mdVISION.mdLOOPS.mdClaude Code
Use CLAUDE.md to import AGENTS.md, install the use-afs skill, and add the hook example when you want validation around file writes.
Keep scoped Claude rules thin and let the root AFS files define persistent policy.
CLAUDE.md.claude/settings.jsonskills/use-afs/Codex
Use AGENTS.md plus the repo-scoped skills/use-afs skill so Codex can route context, sources, and validation consistently.
Add optional Codex hooks for validation before major write operations.
AGENTS.mdskills/use-afs/.codex/hooks/Cursor
Use AGENTS.md for shared rules and the Cursor .mdc template for editor-local routing to AFS root files and folders.
Keep Cursor-specific UI or codebase rules scoped, while durable facts remain in AFS.
AGENTS.md.cursor/rules/use-afs.mdcOpenClaw
Use the OpenClaw template as a bridge skill that points the agent to AFS root files, sources/, logs/, and validation scripts.
Treat the bridge as adapter guidance unless the OpenClaw project adds a native AFS integration.
templates/agent/openclaw-skill.mdAGENTS.mdBRAIN.mdHermes Agent
Use the generic AFS operating contract: read root intent first, write trace history into memory folders, and keep external material in sources/.
Attach the AGENTS.md and BRAIN.md templates to Hermes until a native adapter is available.
AGENTS.mdBRAIN.mdsources/Compatibility
Bridge files point external systems back to the same source.
Gbrain and QMD compatibility is implemented as best-effort Markdown bridges. They are not represented as official integrations unless their maintainers publish native AFS support.
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.
GBRAIN.mdBRAIN.mdsources/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.
QMD.mdspecs/plans/knowledge/Plain agent harnesses
Any harness that can read files and write Markdown can use AFS without a proprietary database or hosted service.
AGENTS.mdVISION.mdsources/Retrieval
AFS remains useful through plain files while supporting richer search.
Filesystem reads, keyword search, and semantic retrieval can all use the same folder standard. The filesystem remains the durable source of truth even when an agent adds indexes or embeddings.
Filesystem
Normal folders and Markdown files keep the standard inspectable.
Keyword
grep, ripgrep, and search indexes can retrieve exact language.
Semantic
Embeddings and retrieval tools can index AFS while the filesystem remains the source of truth.