AFS — Agentic File System

AFS is an orchestration layer for managing multi-agent systems and context directly within the filesystem. It treats documentation, tools, and memory as mountable context nodes, providing a structured surface for AI agents to operate within a repository.

AFS is an independent implementation and extension of the agentic file system abstraction from "Everything is Context" (arXiv:2512.05470) — see docs/LINEAGE.md for the concept mapping and where AFS goes beyond the paper.

Install

Fast path for a fresh checkout:

git clone https://github.com/scawful/afs.git
cd afs
make setup
./scripts/afs --help

Equivalent manual setup:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .

Use the wrapper script for reliable local development and agent invocation; it sets repo-local environment defaults before dispatching to the package:

./scripts/afs --help

Quick Start

make check                            # lint, tests, package smoke
./scripts/afs setup                   # Guided setup wizard
./scripts/afs guide                   # Friendly workflow menu
./scripts/afs init                    # Initialize config/v1; preserve existing v2
./scripts/afs context init --layout-version 2 --path "$PWD"  # Create/register v2
./scripts/afs start --path "$PWD"      # Start with current project context
./scripts/afs search "next step" --path "$PWD"  # Local scoped search
./scripts/afs insights research "retry policy" --path "$PWD"  # Refresh and search locally
./scripts/afs insights reflect --path "$PWD"  # Create reviewable learning candidates
./scripts/afs status --start-dir "$PWD"  # Show context, mount, and index health
./scripts/afs doctor                  # Diagnose issues (`--fix` applies supported repairs)
./scripts/afs health                  # Health check
./scripts/afs storage audit           # Online, read-only disk pressure report
./scripts/afs storage models          # Read-only model retention evidence

Refresh local agent harnesses, MCP setup, copied skills, hooks, and context indexes with a dry-run first:

./scripts/afs-upgrade-agent-setup --workspace ~/src
./scripts/afs-upgrade-agent-setup --workspace ~/src --apply --all

Branching and releases

AFS uses a staged integration flow across features, development, and main. See docs/development.md for PR target and promotion guidance, and RELEASE.md for the release/tag checklist.

Current release line: 0.2.x pre-1.0 core platform.

Core Concepts

Context Namespace — Version 1 project contexts remain supported. The opt-in central version 2 namespace has six human-facing categories: history, memory, scratchpad, knowledge, tools, and human. Internal registries, messages, and indexes stay under .afs/.

Session System — Token-budgeted context packs, bootstrap summaries, and client harness for Gemini, Claude, and Codex integrations.

Agent Operations — Optional run records, safe background job queues, and handoffs for work that spans turns or harnesses.

Workflow Assistant — Context-local people, relationship, review-route, approval, and activity records for documents, sheets, tickets, planning, and other non-technical workflows.

Messages — Scoped inter-agent coordination for tasks that need it. The old hivemind name remains a compatibility surface for one transition cycle.

Memory Consolidation — Event history rolled up into durable memory entries, with optional LLM-assisted summarization.

Profiles & Extensions — Profile-driven context injection via afs.toml. Extensions add domain-specific functionality without forking core.

Context Sources — Provider-neutral adapters for tasks, tickets, reviews, docs, messages, tests, hooks, and traces. Core AFS owns the normalized records; concrete source connectors live in extensions.

Insights — Scoped research plus deterministic, payload-free reflection of repeated failures. Successful completions and general activity are ignored; reflection produces pending candidates for human review and never promotes them automatically. Optional scheduled research/reflection agents are off by default and write only to scratchpad.

Optimization Evidence — Versioned, language-neutral evaluation and policy records plus a pure decision gate for bounded hill-climbing experiments. The gate can recommend human review but cannot execute or promote a candidate.

Policy-Checked Execution — Typed, hash-bound execution requests inspected against trusted policy before a portable process backend launches them. The current backend scrubs environment state and bounds time/output, but is not a security sandbox.

Storage Maintenance — Online, read-only allocated-byte auditing plus a narrow, expiring plan/apply workflow for rebuildable artifacts. Planning writes only the requested plan artifact. A separate model-retention audit classifies evidence as keep, review, or unknown, but cannot delete models or feed them into plan/apply. Archives, Trash, contexts, applications, and APFS snapshots also stay informational. Cleanup never stops running agents or model servers.

Professional/project docs

• Executive Summary
• Lineage
• Central Context Layout v2
• Insights
• Setup Guide
• Extension Authoring
• Autonomous Optimization Protocol
• Policy-Checked Execution
• Storage Maintenance
• Contributing
• Security
• Release Process
• Roadmap
• Changelog

Architecture

src/afs/
├── cli/              # 30+ CLI command groups
├── agents/           # optional background agents + supervisor
├── execution/        # typed policy checks + bounded process backend
├── mcp_server.py     # MCP prompts/tools/resources for external clients
├── context_index.py  # SQLite-backed context indexing and search
├── context_pack.py   # Token-budgeted context packs with caching
├── session_*.py      # Session bootstrap, harness, workflows
├── memory_*.py       # Memory consolidation and LLM summarization
├── messages.py       # Scope-aware inter-agent messages
├── hivemind.py       # Legacy message-bus compatibility
├── handoff.py        # Structured session handoff protocol
├── embeddings.py     # Embedding index with Gemini provider
├── services/         # launchd/systemd service adapters
├── training/         # Generic dataset/run/eval/feedback primitives
├── sources/          # Provider-neutral context source interfaces
├── mcp/              # MCP extension registry and shared schemas
├── protocols/        # Versioned, language-neutral JSON Schema contracts
└── ...

CLI

Context & Workspace

afs start --path "$PWD"                # Build the scoped session-start packet
afs search "search term" --path "$PWD" # Current project + common, local-first
afs insights research "question" --path "$PWD" # Refreshed local research
afs insights reflect --path "$PWD"     # Deterministic candidate generation
afs files list knowledge --path "$PWD" # Friendly alias for `afs fs`
afs notes draft "Investigation" --body-file notes.md
afs handoff threads --path "$PWD"
afs messages list --path "$PWD"
afs projects current --path "$PWD"
afs jobs status                       # Friendly alias for `afs agent-jobs`
afs missions list                     # Friendly alias for `afs mission`
afs check                             # Friendly alias for `afs health`
afs repair                            # Friendly alias for `afs doctor`
afs context discover                  # Find existing context roots
afs context init --layout-version 2 --path "$PWD" # Fresh central v2 root
afs layout audit --context-root ~/.context         # Read-only inspection
afs layout plan --context-root /path/to/v1-context \
  --destination-root /path/to/new-v2-context \
  --mapping-file /private/path/layout-mappings.json \
  --output /private/path/migration-plan.json        # Private, hash-bound plan
afs layout migrate --plan /private/path/migration-plan.json # Read-only preview
afs layout activate --plan /private/path/migration-plan.json \
  --state-dir /private/path/activation-state           # Read-only cutover preview
afs status --start-dir "$PWD"         # Show mount status and index health
afs context query "search term"       # Search the context index
afs sources list                      # Extension-owned context source providers
afs sources sync --provider NAME      # V1-only .context/items preview; v2 fails closed
afs context diff                      # Changes since last session
afs session pack --model gemini       # Local-first token-budgeted context export
afs session pack "query" --semantic   # Explicitly permit remote query embeddings

Layout migration only writes to a separate, nonexistent destination and never modifies or deletes the v1 source. Applying a reviewed plan requires afs layout migrate --plan PLAN --apply --because "..." plus controlling- terminal confirmation. A successful migrate apply creates a verified candidate; it does not activate or clean up context roots automatically. A separate layout activate command can atomically exchange a fresh, exclusion-free candidate into the stable configured path after another controlling-terminal decision. The original v1 tree remains intact at the candidate path, and layout rollback can exchange the roots back after its own human decision. Neither transition merges or deletes data. Mapping schema v2 can record reason-bearing retained_sources and retained_paths. These are source-only exclusions and are not copied into the candidate; plans containing them use schema v3, while mapping schema v1 and plan schema v2 remain supported. The whole-source fingerprint still includes excluded content or link metadata, so writers must be stopped. Candidate capacity and copy evidence use copy_bytes, not whole-source bytes. Links and non-portable names are allowed only inside explicit exclusions.

On Windows, audit and planning remain available but layout migrate is blocked until the executor can establish and verify private DACLs. Activation additionally requires a supported atomic directory-exchange syscall (renamex_np(RENAME_SWAP) on macOS or renameat2(RENAME_EXCHANGE) on Linux), same-parent roots, a private external state directory, stable configuration, and proof that no process has either tree open. Plans with any retained source or path are not activation-ready. See Central Context Layout v2 for mapping limits and failure handling. The example does not assert that a live ~/.context is ready or migrated.

Context-source sync is v1-only today. Version 2 keeps provider list/status read-only and rejects sync before provider invocation until scoped ingestion can target knowledge/projects/<project-id>/ or explicit knowledge/common/.

Insights research is scoped to the current project plus common; semantic retrieval and internet providers are separate, explicit opt-ins. See Insights for data-movement and human-review boundaries.

Execution & Verification

afs execution inspect --request request.json --allowed-root "$PWD" \
  --allowed-executable python3 --json
afs verify plan --cwd "$PWD" --json   # Inspect selected structured checks
afs verify run --cwd "$PWD" --json    # Run checks through the broker

Execution inspection never launches the request, and AFS intentionally exposes no generic execution CLI. Executable permission is explicit; omitting --allowed-executable returns a blocked inspection. See Policy-Checked Execution for the typed Python API and backend limits.

Agents

afs agents list                       # Available agents
afs agents ps                         # Running agents
afs agents run <name> [--prompt ...]  # Run an agent
afs agents capabilities               # Agent capability matrix
afs agent-manifest validate           # Validate harness/skill/MCP manifest
afs agent-manifest sync --apply       # Copy shared skills and write harness exports
afs agent-hooks install-shell --apply # Route harness commands through AFS wrappers
afs agent-hooks install-worker --apply --load  # Run queued jobs automatically
afs agent-runs start "task"           # Record a replayable agent run
afs agent-jobs create "task"          # Queue a markdown background job
afs agent-jobs status                 # Queue, worker, run, and watchdog status
afs agent-jobs inbox                  # Review completed, failed, stale, or blocked jobs
afs agent-jobs review <job-id>        # Inspect one job and its linked run record
afs agent-jobs promote <job-id> --to-handoff  # Save a durable, readable handoff
afs agent-jobs archive <job-id>       # Archive a handled job without deleting it
afs agent-jobs seed                   # Idempotently queue safe maintenance jobs
afs agent-jobs work --agent codex --command '...'  # Claim and execute queued jobs

session bootstrap includes manifest, run, and job state; MCP clients can use agent.manifest.show, agent.run.*, and agent.job.* directly.

Work Assistant

afs work                              # People/review/approval summary
afs work people list                  # Known work-scoped people
afs work reviewers --target-type docs # Suggested reviewers
afs work approvals list               # Pending external-write approvals
afs work approvals execute <id> --dry-run
afs work approvals execute <id> --executor "python3 scripts/afs-work-gws-executor.py"
afs work activity list                # Recent work-assistant activity

Work-assistant state is native to AFS and backed by the legacy global storage role (global/work_assistant.sqlite3 in v1 and .afs/compat/global/work_assistant.sqlite3 in v2). It creates approval records for external writes instead of editing shared docs, sheets, tickets, or messages directly. Approved actions can be handed to explicit local connector commands with afs work approvals execute.

Session

afs session bootstrap --json          # Full session context summary
afs session pack "task" --model gemini --json
afs session prepare-client --client codex --json

Memory & Events

afs memory status                     # Memory consolidation stats
afs memory consolidate                # Roll history into memory
afs events query --last 50            # Recent events
afs events analytics                  # Event statistics

Profiles

afs profile list                      # Available profiles
afs profile switch work               # Activate a profile
afs profile current                   # Show active profile

Embeddings

afs search "how to debug a sprite" --path "$PWD"           # local text retrieval
afs search "similar rendering failures" --path "$PWD" \
  --semantic --rebuild                                      # explicit vectors
afs embeddings search "how to debug a sprite"              # direct legacy collection API

afs search filters to the current project plus common before ranking. Cross-project search requires --all-projects. Semantic retrieval is opt-in; Gemini defaults to stable gemini-embedding-2 with 768-dimensional vectors.

Health & Diagnostics

afs doctor --fix                      # Diagnose and repair
afs health                            # System health check
afs services status --system          # Service status

MCP Server

AFS exposes a small recommended MCP surface for normal agent work, with broader agent, legacy-message, events, embeddings, and training tools available for harnesses that explicitly need them.

afs mcp serve                         # Start MCP server
# Or via direct module entrypoint (preferred for Claude Desktop):
.venv/bin/python -m afs.mcp_server

Recommended prompts include afs.session.bootstrap. The slim tool catalog contains scoped context read/query/search, messages.send/read, note.create/read/list, handoff.create/read/list, and skill.match/read. messages.*, note.*, and the version 3 handoff.* tools are the canonical new surfaces. hivemind.* is full-catalog compatibility only.

See docs/MCP_SERVER.md for configuration and tool reference.

Agents

Agent	Purpose
agent-supervisor	Lifecycle management, dependency graph, restart with backoff
context-warm	Background context warming and embedding indexing
mission-runner	TOML mission definitions with OODA execution phases
journal-agent	Draft hybrid weekly reviews from thoughts and active tasks
workspace-analyst	Codebase health, git drift, dependency scanning
gemini-workspace-brief	Gemini-powered workspace briefings
dashboard-export	Data export for status bar and dashboard surfaces
tether-bridge	Agent findings to ADHD-friendly capture items
history-memory	Consolidate event history into durable memory
context-audit	Audit contexts for missing directories
context-inventory	Inventory contexts and mount counts
index-rebuild	Refresh the knowledge/memory SQLite index after source changes
skills-mine	Mine repeated successful traces into reviewable skill candidates
morning-briefing	Write a network-free daily digest to the configured scratchpad
scribe-draft	Draft responses via configured chat model
researcher	Research agent with structured output

When the active profile has no agent_configs, the supervisor supplies a conservative four-agent default set. It performs a network-free daily context audit, watches the configured knowledge/memory roots, mines skills weekly, and writes a daily briefing. Existing custom agent lists are never augmented. Disable defaults with [agents] default_set = false or AFS_DEFAULT_AGENTS=off. Starting the supervisor remains explicit. The audit does not modify workspace source files, but supervisor snapshots and index-health reads may initialize SQLite metadata inside the configured context.

Gemini Integration

afs antigravity setup --scope project    # Preview Antigravity CLI MCP setup
afs gemini setup                         # Gemini CLI compatibility/API helper
afs antigravity models --json            # Parse the installed agy model list

Gemini CLI compatibility is retained for API-key/enterprise workflows, but the individual/free/Pro/Ultra public path moved to Antigravity CLI (agy) on 2026-06-18. AFS does not auto-install agy; run afs antigravity status or afs antigravity setup --json to inspect the local state. Current agy builds use ~/.gemini/config/mcp_config.json as the migrated MCP config path.

afs gemini status                     # Check API key, SDK, embeddings
afs gemini context "search query"     # Generate context for Gemini session
afs gemini context --include-content  # With full file content

Install: pip install -e ".[gemini]"

Client Wrappers

AFS ships wrapper scripts that inject session context into native clients:

./scripts/afs-claude --prompt "task description"
./scripts/afs-codex --prompt "task description"
./scripts/afs-gemini --prompt "task description"

Wrappers export AFS_SESSION_BOOTSTRAP_*, AFS_SESSION_PACK_*, AFS_SESSION_SYSTEM_PROMPT_* and emit lifecycle events (user_prompt_submit, turn_started, turn_completed).

Configuration

afs.toml in the project root:

[general]
context_root = "~/.context"

[profiles.work]
knowledge_mounts = ["~/docs/work"]
skill_roots = ["~/skills"]

[context_index]
enabled = true
auto_index = true
include_content = true

[hooks]
session_start = ["echo 'session started'"]

skill_roots are an instruction trust boundary: task-matched SKILL.md bodies can enter generated system prompts. Configure only roots whose content you trust. AFS delivers at most three bodies, capped at 2,000 characters each and 6,000 characters in aggregate; additional matches remain metadata-only. Skill files over 64,000 characters, names over 256 characters, or metadata lists over 16 items of 256 characters each are rejected during discovery so enforcement and verification rules are never silently clipped.

Extensions

Domain-specific functionality (model training, persona configurations, deployment playbooks) goes in extension packages. See docs/EXTENSION_MIGRATION.md.

Documentation

• docs/index.md — Documentation index
• docs/EXECUTIVE_SUMMARY.md — Shareable non-domain executive summary
• docs/LINEAGE.md — Research lineage and concept mapping to arXiv:2512.05470
• docs/ARCHITECTURE.md — System architecture
• docs/SETUP_GUIDE.md — Guided setup, shell helpers, and approachable onboarding
• docs/CLI_REFERENCE.md — Full CLI reference
• docs/AGENT_INTEGRATION_UPGRADE.md — Upgrade agent harnesses, MCP setup, hooks, and copied skills
• docs/AGENT_SURFACES.md — Agent system design
• docs/MCP_SERVER.md — MCP server setup and tools
• docs/PROFILES.md — Profile system
• docs/EMBEDDINGS.md — Embedding system
• docs/MEMORY_SYSTEM.md — Memory consolidation
• docs/EMACS_INTEGRATION.md — Emacs/Spacemacs helper

License

MIT