Agentic.AgentFS (agentic v0.3.0)

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

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

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.

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

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

bind_mounts(ctx)

Get the bind mount specification for the sandbox runner.

mount(ctx)

Mount the agent filesystem overlay before starting a CLI session.

unmount(ctx)

Unmount the agent filesystem overlay after a CLI session ends.

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

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

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

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

@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.

@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.

@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.