mofa session

The mofa session command provides session management including listing, viewing, exporting, and deleting conversation sessions.

Subcommands

list

List all sessions

show

Show session details

export

Export session data

delete

Delete a session

mofa session list

List all conversation sessions with filtering options.

Usage

mofa session list [OPTIONS]

Options

`-a, --agent <AGENT_ID>`

Filter sessions by agent ID.

Type: String
Default: None (show all)

mofa session list --agent my-agent

`-n, --limit <N>`

Limit number of results.

Type: Integer
Default: All sessions

mofa session list --limit 10

Examples

List all sessions

mofa session list

Output:

→ Listing sessions

┌─────────────────────────┬─────────────────────┬───────────────┬─────────┐
│ session_id              │ created_at          │ message_count │ status │
├─────────────────────────┼─────────────────────┼───────────────┼─────────┤
│ agent-001:session-123   │ 2024-02-28 10:30:00 │ 12            │ active │
│ agent-001:session-124   │ 2024-02-28 11:45:00 │ 8             │ active │
│ agent-002:session-125   │ 2024-02-28 12:15:00 │ 5             │ active │
└─────────────────────────┴─────────────────────┴───────────────┴─────────┘

Filter by agent

mofa session list --agent agent-001

Output:

→ Listing sessions
  Filtering by agent: agent-001

┌─────────────────────────┬─────────────────────┬───────────────┬─────────┐
│ session_id              │ created_at          │ message_count │ status │
├─────────────────────────┼─────────────────────┼───────────────┼─────────┤
│ agent-001:session-123   │ 2024-02-28 10:30:00 │ 12            │ active │
│ agent-001:session-124   │ 2024-02-28 11:45:00 │ 8             │ active │
└─────────────────────────┴─────────────────────┴───────────────┴─────────┘

Limit results

mofa session list --limit 5

Output:

→ Listing sessions
  Limit: 5

┌─────────────────────────┬─────────────────────┬───────────────┬─────────┐
│ session_id              │ created_at          │ message_count │ status │
├─────────────────────────┼─────────────────────┼───────────────┼─────────┤
│ agent-001:session-123   │ 2024-02-28 10:30:00 │ 12            │ active │
│ agent-001:session-124   │ 2024-02-28 11:45:00 │ 8             │ active │
│ agent-002:session-125   │ 2024-02-28 12:15:00 │ 5             │ active │
│ agent-002:session-126   │ 2024-02-28 13:00:00 │ 3             │ active │
│ agent-003:session-127   │ 2024-02-28 14:20:00 │ 15            │ active │
└─────────────────────────┴─────────────────────┴───────────────┴─────────┘

JSON output

mofa session list --output-format json

Output:

[
  {
    "session_id": "agent-001:session-123",
    "created_at": "2024-02-28 10:30:00",
    "message_count": 12,
    "status": "active"
  },
  {
    "session_id": "agent-001:session-124",
    "created_at": "2024-02-28 11:45:00",
    "message_count": 8,
    "status": "active"
  }
]

mofa session show

Show detailed information about a specific session.

Usage

mofa session show <SESSION_ID> [OPTIONS]

Arguments

`<SESSION_ID>`

Required. Session identifier.

mofa session show agent-001:session-123

Options

`-f, --format <FORMAT>`

Output format.

Type: Enum
Values: json, table, yaml
Default: table
Alias: -o (for backward compatibility)

mofa session show session-123 --format json
mofa session show session-123 -o yaml

Examples

Show session (table format)

mofa session show agent-001:session-123

Output:

Session: agent-001:session-123
Created: 2024-02-28 10:30:00
Messages: 12
Status: active

Metadata:
  agent_id: agent-001
  user_id: user-456
  context: customer_support

Conversation:

┌─────────────┬─────────────────────┬──────────────────────────────────────────────────────────────────────┐
│ Timestamp   │ Role      │ Content                                                              │
├─────────────┼─────────────────────┼──────────────────────────────────────────────────────────────────────┤
│ 10:30:05    │ user      │ Hello, I need help with my order                                     │
│ 10:30:08    │ assistant │ I'd be happy to help! What's your order number?                     │
│ 10:30:15    │ user      │ ORD-12345                                                            │
│ 10:30:18    │ assistant │ I found your order. It's currently being processed. Expected...      │
└─────────────┴─────────────────────┴──────────────────────────────────────────────────────────────────────┘

Show session (JSON format)

mofa session show agent-001:session-123 --format json

Output:

{
  "session_id": "agent-001:session-123",
  "created_at": "2024-02-28T10:30:00Z",
  "message_count": 12,
  "status": "active",
  "metadata": {
    "agent_id": "agent-001",
    "user_id": "user-456",
    "context": "customer_support"
  },
  "messages": [
    {
      "timestamp": "2024-02-28T10:30:05Z",
      "role": "user",
      "content": "Hello, I need help with my order"
    },
    {
      "timestamp": "2024-02-28T10:30:08Z",
      "role": "assistant",
      "content": "I'd be happy to help! What's your order number?"
    }
  ]
}

Show session (YAML format)

mofa session show agent-001:session-123 --format yaml

Output:

session_id: agent-001:session-123
created_at: 2024-02-28T10:30:00Z
message_count: 12
status: active
metadata:
  agent_id: agent-001
  user_id: user-456
  context: customer_support
messages:
  - timestamp: 2024-02-28T10:30:05Z
    role: user
    content: Hello, I need help with my order
  - timestamp: 2024-02-28T10:30:08Z
    role: assistant
    content: I'd be happy to help! What's your order number?

mofa session export

Export session data to a file.

Usage

mofa session export <SESSION_ID> -o <OUTPUT> --format <FORMAT>

Arguments

`<SESSION_ID>`

Required. Session identifier to export.

mofa session export agent-001:session-123 -o session.json --format json

Options

`-o, --output <PATH>`

Required. Output file path.

Type: Path

mofa session export session-123 -o ./exports/session.json --format json

`-f, --format <FORMAT>`

Required. Export format.

Type: Enum
Values: json, yaml

mofa session export session-123 -o session.yaml --format yaml

Examples

Export to JSON

mofa session export agent-001:session-123 -o session.json --format json

Output:

→ Exporting session: agent-001:session-123
  Format: json
  Output: session.json
  ✓ Exported 12 messages
✓ Session exported successfully

File contents (session.json):

{
  "session_id": "agent-001:session-123",
  "created_at": "2024-02-28T10:30:00Z",
  "metadata": {
    "agent_id": "agent-001",
    "user_id": "user-456"
  },
  "messages": [
    {
      "role": "user",
      "content": "Hello",
      "timestamp": "2024-02-28T10:30:05Z"
    },
    {
      "role": "assistant",
      "content": "Hi! How can I help?",
      "timestamp": "2024-02-28T10:30:08Z"
    }
  ]
}

Export to YAML

mofa session export agent-001:session-123 -o session.yaml --format yaml

Output:

→ Exporting session: agent-001:session-123
  Format: yaml
  Output: session.yaml
  ✓ Exported 12 messages
✓ Session exported successfully

File contents (session.yaml):

session_id: agent-001:session-123
created_at: 2024-02-28T10:30:00Z
metadata:
  agent_id: agent-001
  user_id: user-456
messages:
  - role: user
    content: Hello
    timestamp: 2024-02-28T10:30:05Z
  - role: assistant
    content: Hi! How can I help?
    timestamp: 2024-02-28T10:30:08Z

mofa session delete

Delete a session and its conversation history.

Usage

mofa session delete <SESSION_ID> [OPTIONS]

Arguments

`<SESSION_ID>`

Required. Session identifier to delete.

mofa session delete agent-001:session-123

Options

`--force`

Skip confirmation prompt.

Type: Boolean flag
Default: false

mofa session delete session-123 --force

Examples

Interactive deletion

mofa session delete agent-001:session-123

Output:

→ Deleting session: agent-001:session-123

Session contains 12 messages.
This action cannot be undone.

Delete session? [y/N]: y

  Removing session data...
✓ Session deleted successfully

Force deletion

mofa session delete agent-001:session-123 --force

Output:

→ Deleting session: agent-001:session-123
  Removing session data...
✓ Session deleted successfully

Error Codes

Code	Description
`0`	Session deleted successfully
`1`	Session not found
`2`	Permission denied
`3`	Delete operation failed

Session Structure

Session Data Model

A session contains:

{
  "session_id": "unique-identifier",
  "created_at": "2024-02-28T10:30:00Z",
  "updated_at": "2024-02-28T12:45:00Z",
  "metadata": {
    "agent_id": "agent-001",
    "user_id": "user-456",
    "tags": ["customer-support", "order-inquiry"],
    "custom_field": "custom_value"
  },
  "messages": [
    {
      "role": "user",
      "content": "Message text",
      "timestamp": "2024-02-28T10:30:05Z"
    },
    {
      "role": "assistant",
      "content": "Response text",
      "timestamp": "2024-02-28T10:30:08Z"
    }
  ]
}

Message Roles

Role	Description
`user`	User input message
`assistant`	Agent response
`system`	System-level message
`tool`	Tool execution result

Common Workflows

Review recent conversations

# List recent sessions
mofa session list --limit 10

# View specific session
mofa session show agent-001:session-123

# Export for analysis
mofa session export agent-001:session-123 -o analysis.json --format json

Audit agent interactions

# List all sessions for an agent
mofa session list --agent my-agent

# Export all sessions
for session in $(mofa session list --agent my-agent --output-format json | jq -r '.[].session_id'); do
  mofa session export $session -o "exports/${session}.json" --format json
done

Clean up old sessions

# List all sessions
mofa session list

# Delete specific session
mofa session delete old-session-id

# Batch delete (with caution)
mofa session list --output-format json | \
  jq -r '.[].session_id' | \
  xargs -I {} mofa session delete {} --force

Debug conversation flow

# View session in detail
mofa session show session-123 --format json | jq

# Filter to user messages only
mofa session show session-123 --format json | \
  jq '.messages[] | select(.role == "user")'

# Count messages by role
mofa session show session-123 --format json | \
  jq '.messages | group_by(.role) | map({role: .[0].role, count: length})'

Storage

Sessions are stored in:

~/.local/share/mofa/sessions/
  ├── agent-001/
  │   ├── session-123.json
  │   └── session-124.json
  └── agent-002/
      └── session-125.json

Sessions are stored locally by default. For production deployments, configure persistent storage with a database backend.

Tips

Filtering: Use --agent to quickly find sessions for a specific agent.

Exporting: Export sessions regularly for backup and analysis.

JSON Processing: Pipe JSON output to jq for advanced filtering and analysis.

Cleanup: Regularly delete old sessions to save disk space.

Commands

​Subcommands

list

show

export

delete

​mofa session list

​Usage

​Options

​-a, --agent <AGENT_ID>

​-n, --limit <N>

​Examples

​List all sessions

​Filter by agent

​Limit results

​JSON output

​mofa session show

​Usage

​Arguments

​<SESSION_ID>

​Options

​-f, --format <FORMAT>

​Examples

​Show session (table format)

​Show session (JSON format)

​Show session (YAML format)

​mofa session export

​Usage

​Arguments

​<SESSION_ID>

​Options

​-o, --output <PATH>

​-f, --format <FORMAT>

​Examples

​Export to JSON

​Export to YAML

​mofa session delete

​Usage

​Arguments

​<SESSION_ID>

​Options

​--force

​Examples

​Interactive deletion

​Force deletion

​Error Codes

​Session Structure

​Session Data Model

​Message Roles

​Common Workflows

​Review recent conversations

​Audit agent interactions

​Clean up old sessions

​Debug conversation flow

​Storage

​Tips

​See Also

Build docs developers (and LLMs) love

Subcommands

mofa session list

Usage

Options

`-a, --agent <AGENT_ID>`

`-n, --limit <N>`

Examples

List all sessions

Filter by agent

Limit results

JSON output

mofa session show

Usage

Arguments

`<SESSION_ID>`

Options

`-f, --format <FORMAT>`

Examples

Show session (table format)

Show session (JSON format)

Show session (YAML format)

mofa session export

Usage

Arguments

`<SESSION_ID>`

Options

`-o, --output <PATH>`

`-f, --format <FORMAT>`

Examples

Export to JSON

Export to YAML

mofa session delete

Usage

Arguments

`<SESSION_ID>`

Options

`--force`

Examples

Interactive deletion

Force deletion

Error Codes

Session Structure

Session Data Model

Message Roles

Common Workflows

Review recent conversations

Audit agent interactions

Clean up old sessions

Debug conversation flow

Storage

Tips

See Also