AIFS

AIFS is the Aionis File Surface. It mirrors governed Runtime output into a read-only .aionis/ directory so coding agents can consume Aionis through normal file reads instead of custom tools.

Use AIFS when the host agent can reliably read project files, but you do not want to write a full SDK adapter yet.

The main product effect is simple: Aionis compiles governed context once, then the agent reads a stable file surface. This is useful for agents that already inspect project files but do not have a native Aionis plugin.

What It Writes

.aionis/
  README.md
  AGENT_INSTRUCTIONS.md
  guide.md
  current_active_path.md
  inspect_before_use.md
  do_not_use.md
  rehydrate_needed.md
  receipts/latest.json
  snapshots/latest.json
  manifest.json

These files are generated from Runtime APIs. They are not the source of truth. The source of truth remains the Aionis Runtime.

AGENT_INSTRUCTIONS.md is the first file to show to an agent. It tells the agent to treat current_active_path.md as the active route, do_not_use.md as blocked memory, and rehydrate_needed.md as pointer-only evidence.

Install

npx @aionis/aifs@latest init \
  --base-url http://127.0.0.1:3001 \
  --scope my-project
 
npx @aionis/aifs@latest doctor \
  --base-url http://127.0.0.1:3001 \
  --scope my-project
 
npx @aionis/aifs@latest refresh \
  --base-url http://127.0.0.1:3001 \
  --scope my-project \
  --query "Continue the current task without repeating failed branches."

init creates the local .aionis/ read surface. doctor checks Runtime reachability and local file health. refresh writes the governed context files.

If you are installing Aionis from scratch, the installer can add the AIFS package:

npx @aionis/create@latest my-aionis --with-aifs

AIFS still runs from the agent project you want to expose .aionis/ inside. The Runtime install directory and the agent workspace can be different directories.

Execution Memory Mode

When you have a known run and task signature, ask AIFS for role-specific execution context:

npx @aionis/aifs@latest refresh \
  --base-url http://127.0.0.1:3001 \
  --scope my-project \
  --run-id run-001 \
  --task-signature checkout-migration \
  --role worker \
  --query "Continue from the accepted route."

The generated files separate:

Refresh Summary

By default refresh prints a human-readable summary:

Aionis AIFS refreshed
Output: /repo/.aionis
Guide trace: guide-...
Prompt chars: 4210
Snapshot: written
Surface counts:
- use_now: 2
- inspect_before_use: 1
- do_not_use: 3
- rehydrate: 1

Use --json when another script needs the raw result contract.

How Agents Should Read It

Give the agent this short instruction:

Before continuing, read .aionis/AGENT_INSTRUCTIONS.md and follow the Aionis file-surface order.
Use .aionis/current_active_path.md as the active route.
Treat .aionis/do_not_use.md as blocked memory.
Rehydrate pointers in .aionis/rehydrate_needed.md before exact edits.

This keeps Aionis visible through ordinary file operations while preserving the same admission contract as SDK, HTTP, MCP, and native plugins.

Options

When To Use Another Path