Backend: `fs` (filesystem)

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

The default backend. Wraps `fs.promises` and writes plain files under a per-subsystem root.

When to use

• You want everything to "just work" with no setup. (This is the default.)
• You want to relocate a subsystem to a different filesystem path (different drive, network share, encrypted volume) without changing how AIWG accesses it.

Configuration

`fs` is the default for every subsystem when `.aiwg/storage.config` is absent. To explicitly select it:

{
  "version": "1",
  "backends": {
    "memory":       { "type": "fs" },
    "activity_log": { "type": "fs" }
  }
}

To redirect the physical location of an `fs`-backed subsystem, set `roots.<subsystem>`:

{
  "version": "1",
  "roots": {
    "research": "/mnt/archive/aiwg-research",
    "media":    "/mnt/archive/aiwg-media",
    "memory":   "~/vaults/aiwg-memory"
  }
}

Path expansion: `~/` is expanded to `$HOME`. Relative paths resolve against the project root (the directory containing `.aiwg/`). Absolute paths are used as-is.

Default subsystem roots (when no override)

Subsystem	Default
`memory`	`<project>/.aiwg/memory/`
`reflections`	`<project>/.aiwg/reflections/`
`kb`	`<project>/.aiwg/kb/`
`activity_log`	`<project>/.aiwg/activity.log` (single file)
`provenance`	`<project>/.aiwg/provenance/`
`research`	`<project>/.aiwg/research/`
`media`	`<project>/.aiwg/media/`
`sandbox_identity`	`~/.config/aiwg/sandbox-agents.json` (host-level)

Capabilities

Operation	Notes
`read`	Returns `null` for missing files (does not throw)
`write`	Idempotent; overwrites; auto-creates parent directories
`append`	Atomic via POSIX `O_APPEND`. Concurrent appenders interleave at line granularity
`list`	Recursive walk with optional prefix filter
`delete`	No-op for missing paths
`query`	Not implemented — filesystem has no semantic search

Path safety

The fs adapter rejects paths that:

• Contain `..` segments
• Start with `/` (absolute)
• Start with `~`
• Contain backslashes
• Are empty

These are tested in `test/unit/storage/fs.test.ts`.

Caveats

• No content addressability: re-writing the same logical artifact at a different path creates two files. Use the per-subsystem CLI's `delete` first, or run the agent-owned storage operation if you're moving things en masse.
• `activity_log` is a single-file subsystem. Its default "root" maps to a file path, not a directory. Don't the agent-owned activity-log operation arbitrary subpaths — append flows through the agent-owned activity-log operation which uses atomic O_APPEND.
• `sandbox_identity` defaults to a host-level path for backward compatibility. To redirect, set `roots.sandbox_identity` in `.aiwg/storage.config` — the file `sandbox-agents.json` will land in the configured directory.

Setup

None. The default is `fs` and AIWG creates per-subsystem directories on first write.

Verifying

Use AIWG to complete this documented outcome: Verifying
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.