AFS

AFS is a CLI-first, local-first workspace memory kernel for agents.

It gives a repository an inspectable .afs/ workspace for memory records, search, sessions, attachments, snapshots, and proof-oriented workflows without requiring a daemon or hosted control plane.

What AFS supports today

• workspace bootstrap and inspection (afs init, afs status)
• memory CRUD with append-only history
• text search with the current DSL (afs search query ... --dsl) and explain output
• explicit sessions and attachments
• export/import, event journaling, and adapter loading
• optional local surfaces for serve, sync, workflow, trace/eval, checkpoints, snapshots, and ops reporting

AFS stays inspect-first: filesystem state is the source of truth, indexes are rebuildable, and optional surfaces remain explicit commands rather than background automation.

Install

AFS is currently source-first. Install it from a local checkout:

python -m pip install -e .
python -m afs --help

After the editable install, the afs console command should also be available:

afs --help

Quickstart

Initialize a workspace, store one memory, search it back, and inspect the stored state:

afs init
afs status

afs memory create \
  --kind fact \
  --body "JWT auth is enabled" \
  --tag auth \
  --meta project=afs \
  --json

afs search query "jwt kind:fact tag:auth meta.project=afs" --dsl --explain --json

afs memory show <memory-id> --json
afs memory history <memory-id> --json

afs session create --json
afs session add <session-id> --role user --content "Summarize the auth note"
afs session show <session-id> --json

Use python -m afs instead of afs if you prefer the module entrypoint during local development.

Documentation

• public docs overview: website/docs/overview.md
• install guide: website/docs/getting-started/install.md
• quickstart: website/docs/getting-started/quickstart.md
• architecture reference: docs/architecture.md
• historical planning docs: docs/archive/

Development

Run the test suite:

pytest tests -v

Recommended local development entrypoint:

python -m pip install -e .[dev]
python -m afs --help

Public documentation source lives under website/docs/.