MingaAgent.SessionStore (Minga v0.1.0)

Persists agent conversations to disk as JSON files.

Each session is saved as {session_id}.json in the sessions directory (~/.config/minga/agent/sessions/ by default). Files are written atomically via a temp file + rename to avoid corruption on crash. Manager-owned remote identity is stored separately under .remote_tokens/.

The store is stateless: all functions operate directly on the filesystem. The Session GenServer calls save/2 on a debounced timer, and the picker calls list/0 to scan the directory for past sessions.

Summary

Types

session_data()

Full session data for save/load.

session_meta()

Session metadata for the picker (without full message content).

Functions

clear_all(config_dir \\ nil)

Deletes all saved session transcripts. Durable remote identities are retained.

delete(session_id, config_dir \\ nil)

Deletes a saved session transcript. Durable remote identity is retained.

establish_remote_token(session_id, candidate, config_dir \\ nil)

Establishes manager-owned remote session identity.

list(config_dir \\ nil)

Lists all saved sessions as metadata (without full messages).

load(session_id, config_dir \\ nil)

Loads a persisted session transcript.

prune(days, config_dir \\ nil)

Prunes session transcripts older than days days.

save(data, config_dir \\ nil)

Saves a session to disk.

sessions_dir(config_dir \\ nil)

Returns the sessions directory path.

Types

session_data()

@type session_data() :: %{
  :id => String.t(),
  :timestamp => String.t(),
  :model_name => String.t(),
  :messages => [MingaAgent.Message.t()],
  :usage => MingaAgent.TurnUsage.t(),
  optional(:last_message_at) => String.t(),
  optional(:title) => String.t(),
  optional(:provider_name) => String.t(),
  optional(:branches) => [MingaAgent.Branch.t()],
  optional(:message_ids) => [pos_integer()],
  optional(:pinned_ids) => MapSet.t(pos_integer()),
  optional(:memory) => String.t() | nil
}

Full session data for save/load.

session_meta()

@type session_meta() :: %{
  id: String.t(),
  timestamp: String.t(),
  last_message_at: String.t(),
  title: String.t(),
  model_name: String.t(),
  provider_name: String.t(),
  preview: String.t(),
  recent_messages: String.t(),
  message_count: non_neg_integer(),
  turn_count: non_neg_integer(),
  cost: float()
}

Session metadata for the picker (without full message content).

Functions

clear_all(config_dir \\ nil)

@spec clear_all(String.t() | nil) :: :ok

Deletes all saved session transcripts. Durable remote identities are retained.

delete(session_id, config_dir \\ nil)

@spec delete(String.t(), String.t() | nil) :: :ok | {:error, term()}

Deletes a saved session transcript. Durable remote identity is retained.

establish_remote_token(session_id, candidate, config_dir \\ nil)

@spec establish_remote_token(String.t(), String.t(), String.t() | nil) ::
  {:ok, String.t()} | {:error, term()}

Establishes manager-owned remote session identity.

Existing canonical identity wins over legacy transcript identity and the candidate. A new identity is persisted before it is returned.

list(config_dir \\ nil)

@spec list(String.t() | nil) :: [session_meta()]

Lists all saved sessions as metadata (without full messages).

Returns sessions sorted by last message timestamp, most recent first.

load(session_id, config_dir \\ nil)

@spec load(String.t(), String.t() | nil) :: {:ok, session_data()} | {:error, term()}

Loads a persisted session transcript.

Returns {:ok, session_data} or {:error, reason}.

prune(days, config_dir \\ nil)

@spec prune(non_neg_integer(), String.t() | nil) :: non_neg_integer()

Prunes session transcripts older than days days.

Returns the number of transcripts deleted. Durable remote identities are retained.

save(data, config_dir \\ nil)

@spec save(session_data(), String.t() | nil) :: :ok | {:error, term()}

Saves a session to disk.

Creates the sessions directory if it doesn't exist. Writes atomically via a temp file to avoid corruption.

sessions_dir(config_dir \\ nil)

@spec sessions_dir(String.t() | nil) :: String.t()

Returns the sessions directory path.