Omni.Session.Store.FileSystem (Omni Agent v0.3.1)

Reference Omni.Session.Store adapter using plain files on disk.

Designed for local development, single-node deployments, and as a worked example of the adapter contract. Writes assume a single writer per session id — safe within a single Omni.Session process, which serialises writes through its mailbox, but not across nodes or unrelated processes opening the same id. For multi-node deployments, implement a custom adapter against a shared store such as Postgres or S3.

Each session lives in its own directory with two files:

<base_path>/
  <session_id>/
    nodes.jsonl     # tree nodes, one JSON-encoded node per line
    session.json    # path, cursors, state fields, timestamps

nodes.jsonl is append-only when save_tree/4 is called with a :new_node_ids hint; otherwise it's rewritten from the full node set. session.json is a single merged file written by both save_tree and save_state — the two callbacks write disjoint keys, so the merge is read-modify-write with no conflict resolution.

Configuration

• :base_path — required. Absolute paths are used verbatim. Relative paths require :otp_app (see below) and are resolved via Application.app_dir/2.
• :otp_app — optional. When set together with a relative :base_path, the adapter resolves the absolute base via Application.app_dir(otp_app, base_path). This is CWD-independent and remains stable across the BEAM lifetime, unlike paths derived from File.cwd!/0 which can shift under code reloading or cd.

Examples:

# Absolute — used as-is
{Omni.Session.Store.FileSystem, base_path: "/var/data/sessions"}

# Relative under :my_app's priv directory
{Omni.Session.Store.FileSystem, base_path: "priv/sessions", otp_app: :my_app}

Passing a relative :base_path without :otp_app raises ArgumentError on first use — silent CWD-dependent storage is a foot-gun the adapter refuses to enable.

Encoding