Storage Layout¶

Directory structure¶

~/.local/share/ai_ops/
├── user_skills/           # External markdown skills provided by the user
├── workspace/             # The live working directory for agent file operations
│   └── <session>/         # Per-session workspace (WriteFile, Terminal cwd)
├── sessions/              # Persisted sessions (one directory per session)
│   ├── index.json         # short_id -> session uuid map
│   └── <uuid>/
│       ├── messages.jsonl
│       └── events.jsonl
├── ai_ops.log             # Runtime logs generated by the application
└── agent_config.json      # optional user provided configuration for the agent

The sessions/ directory is created at startup by ai_ops.config.build_environment.

Session store¶

A session bundles a conversation's messages together with the structured event stream AgentRunner.arun yields (TextEvent, ToolCallEvent, ToolResultEvent, etc.). Both are handled through the single session store abstraction (ai_ops.core.storage), over a Session model:

class Session(BaseModel):
    uuid: str
    short_id: int
    events: List[AnyEvent] = []
    messages: List[Message] = []

Implementation	Persistence	Notes
`InMemorySessionStore`	None	Ephemeral; used by the test suite and `AI_OPS_STORAGE_STRATEGY=in_memory`
`JSONLSessionStore`	`sessions/<uuid>/messages.jsonl` + `sessions/<uuid>/events.jsonl`	Appends each message/event as a line (`model_dump_json()`); `sessions/index.json` maps the human-friendly `short_id` to the session `uuid`. Default of `get_session_store()`

Messages are appended with append_message, events with append_event; reads go through get_session_by_uuid (whole Session), get_messages_by_uuid, get_events_by_uuid, and get_session_uuid (short_id -> uuid).

Select the backing store explicitly via:

from ai_ops.core.storage import get_session_store, StorageStrategy

get_session_store(strategy=StorageStrategy.JSONL)