Omni.Session.Stores.FileSystem (Omni Agent v0.4.0)

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_dir>/
  <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_dir — required. Must be an absolute path.

Example:

{Omni.Session.Stores.FileSystem, base_dir: "/var/data/sessions"}

For paths relative to an OTP application's install directory, resolve them before constructing the store:

base = Application.app_dir(:my_app, "priv/sessions")
{Omni.Session.Stores.FileSystem, base_dir: base}

Encoding