# `Agentic.AgentFS`

Agent Filesystem Materialization API.

Provides a cross-platform way to expose skills and memories as real files
to CLI-based coding agents (Claude, OpenCode, Codex, etc.).

## How it works

1. Before starting a CLI agent session, `mount/1` creates a temp directory
   and populates it with skills and memories from the host application.
2. The overlay directory is bind-mounted into the sandbox at the agent's
   expected path (e.g. `~/.claude/skills`).
3. The agent reads/writes files normally.
4. After the session, `unmount/1` syncs back any agent-created skills/memories
   and cleans up the temp directory.

## Configuration

The host application provides a materializer module via ctx metadata:

    metadata: %{
      agent_fs_materializer: MyApp.AgentFS.Materializer,
      workspace: "my-project"
    }

Agent paths (skill_path, memory_path) come from the ACP Discovery database
or can be overridden per protocol.

# `agent_memory_path`

```elixir
@spec agent_memory_path(Agentic.Loop.Context.t()) :: String.t() | nil
```

Look up the agent's expected memory path from the discovery database.

# `agent_skill_path`

```elixir
@spec agent_skill_path(Agentic.Loop.Context.t()) :: String.t() | nil
```

Look up the agent's expected skill path from the discovery database.

# `bind_mounts`

```elixir
@spec bind_mounts(Agentic.Loop.Context.t()) :: [{String.t(), String.t()}]
```

Get the bind mount specification for the sandbox runner.

Returns a list of `{host_path, container_path}` tuples for bind-mounting
into the agent sandbox.

# `mount`

```elixir
@spec mount(Agentic.Loop.Context.t()) ::
  {String.t(), Agentic.Loop.Context.t()} | :noop
```

Mount the agent filesystem overlay before starting a CLI session.

Returns `{overlay_path, updated_ctx}` where overlay_path is the temp
directory containing skills and memories.

The overlay_path should be passed to the sandbox runner as an agent_dir
with a custom mount point.

# `unmount`

```elixir
@spec unmount(Agentic.Loop.Context.t()) :: :ok
```

Unmount the agent filesystem overlay after a CLI session ends.

Syncs back any agent-created skills and memories, then cleans up.

---

*Consult [api-reference.md](api-reference.md) for complete listing*