What is a Session, and how does it differ from a chat room?

Why Sessions become hard to manage

A new Pi Agent installation has an empty, tidy Session list. After a week, you may see problems like these:

• A lighting fault and a sunset automation share one Session, so unrelated context begins to affect the answer.
• You want to find last week's vacuum schedule, but several titles use only a vague first message and are hard to identify.
• You want to compare two models from the same starting point but keep copying and pasting the entire prompt.
• A long Session becomes slower and consumes more context.

These are organizational problems caused by putting too many unrelated topics in one Session. This chapter shows when to split or continue a Session, when to branch with Fork, and when to remove old work. Good organization also makes history, model comparisons, and backups easier to manage.

What is a Session?

A Pi Agent Session is more than a transcript. It is a package that can include:

• Every event in the conversation (your messages, model responses, reasoning data, tool cards, and diffs)
• Model information for the Session (including changes between configured model routes)
• Skills loaded for the Session (for example, tool activity and the settings used)
• The Session working directory (cwd) (the folder used for file operations)
• System instructions (the rules, role, and style supplied to the model)

In other words, a Session is an independent workspace with stored context. You can close the browser and reopen the Session later to continue from its saved state. That is stored context, not human-like memory. Available models and Skills may still change if their shared configuration changes.

How a Session differs from a messaging chat

A familiar messaging app is a useful starting analogy, but several differences matter:

Where Session files are stored

Pi Agent stores each Session as a .jsonl (JSON Lines) file, with one event per line. The add-on path is:

/data/pi-agent/sessions/<working-directory ID>/<timestamp>_<uuid>.jsonl

Each path segment has a purpose:

The /data/pi-agent/ directory may be included in a Home Assistant backup, depending on the add-on backup and restore behavior. Follow Chapter 20, create a test backup, and verify restoration rather than assuming these files are protected.

When to split or continue a Session

There is no single correct answer, but this table works for most situations:

Create, name, and classify a Session

Follow this sequence once, then use it whenever you start a new topic.

1. Select the new-Session control

   Depending on your pi-web version, it may say + New, New session, or show a plus icon. Selecting it should clear the conversation and Composer fields. The sidebar may show a temporarily untitled Session until you send a message.

2. Write a specific first message

   Your first message establishes the direction and may determine the Session's automatically generated title. “Find out why one of three living-room lights is unavailable” is a better starting point than “Check the light.” Some pi-web versions derive and truncate the sidebar title from this message.

3. Rename the Session if the control exists

   Open the Session row's ⋮ three-dot or context menu and look for Rename or Edit title. Use searchable wording such as “Living-room light 3 — unavailable.” If your version lacks this action, do not delete useful work merely to change a title; keep the Session and use the organization controls your version provides.

4. Add a tag only if your version supports tags

   Some pi-web versions offer Tag / Label in the Session menu. Possible categories include Home appliance, Automation, Questions and Answers, Video, and Backup/Maintenance. Other versions support only title or message search and have no separate tag field. If you cannot find tags, skip this step and use a consistent title prefix, such as “Appliance/Living-room light 3 — unavailable,” so related Sessions are easy to search.

5. Review the title when the work ends

   The actual cause may differ from your first guess—for example, a suspected lamp fault may turn out to be a Wi-Fi problem. Rename the Session to the result you will search for later.

What Fork or Duplicate does and when to use it

Where supported, pi-web can copy a Session at its current point. Later messages in the copy should not change the original. Depending on the version, this action may be called Fork, Duplicate, or Copy Session. The exact metadata copied can also vary. Exporting .jsonl creates an archive, not necessarily an equivalent branch or import workflow.

Useful cases include:

Typical path: Session row → three-dot or context menu → Fork, Duplicate, or Copy. Confirm the new entry, rename it, and test that a message in the copy does not appear in the original. Labels and list placement vary by pi-web version.

Export a Session

Export creates a file you can read or store outside pi-web. Use it for an offline copy, a support record, or a cleaned transcript.

Typical path: Session row → three-dot or context menu → Export or Download. Formats vary. If no Export action exists, advanced users may copy the relevant file from /data/pi-agent/sessions/<cwd>/ after following safe add-on file-access procedures. Copy the matching .jsonl file rather than modifying the original.

A Markdown export might resemble the example below. Layout and fields vary by version:

# Living-room light 3 offline troubleshooting
Model: provider/model-id
Exported: 2025-08-14

## User
Help me find out why one of the three living-room lights cannot connect.

## Assistant
First, confirm whether this light never worked or stopped working after a period of normal operation.
If it stopped working, check whether Home Assistant reports it as unavailable or off.

## User
It worked normally until yesterday. Its state is unavailable.

## Assistant
A network or firmware problem is likely. Try these steps:
1. Open the light's device page and check the last communication time.
2. Open the Wi-Fi router dashboard and confirm whether the light is still connected.
3. ...

Three ways to clean up Sessions

As Sessions accumulate, choose the least destructive cleanup method that meets your need:

1. Method 1: Delete one Session at a time

   Look for Delete. Read the confirmation carefully and export important work first. This is the safest method for routine cleanup.

2. Method 2: Use batch selection only if supported

   Some pi-web versions may offer multi-select with Ctrl/Cmd plus click, Shift plus click, or a separate selection mode. Selected rows may then expose batch actions. If your interface does not show this feature, delete Sessions individually instead.

3. Method 3: Remove files under /data/pi-agent/sessions/ only as an advanced recovery operation

   Do not run a broad rm command casually or directly remove .jsonl files without a plan. Important: direct file removal can leave indexes or cached entries inconsistent. Stop the add-on, make a verified backup, identify the exact files, and follow version-specific documentation.

How Sessions affect model “memory”

The key point is that the model does not remember a Session like a person. Pi Agent supplies relevant stored history with each new request, subject to context and implementation limits.

At a high level:

1. You send a message

   Pi Agent constructs a request containing the new message and relevant Session context, then sends it to the selected model provider.

2. The model processes the supplied context

   It generates the next response from that request; it does not independently recall your local Session file.

3. The next turn repeats the process

   Newly stored events may become part of the context supplied with the next request.

This has three direct consequences:

• Longer context can increase input usage and latency. More capable models cannot eliminate those physical limits.
• Earlier details can fall outside the effective context. Start a new Session with a verified summary when that happens.
• Deleting a local Session removes Pi Agent's copy. It does not make promises about a cloud provider's retention; consult that provider's current policy.

Common Session problems

1. I cannot find an old Session

   Search titles, message text, and tags if your version supports those fields. Then check likely dates. Before inspecting /data/pi-agent/sessions/, make a backup and follow safe file-access instructions. If the Session was deleted, recover it only from a verified backup.

2. A Session opens blank

   The file may be damaged. Check Settings → Add-ons → Woow HA Pi Agent → Log for a parse error or JSON error that identifies the affected file. Preserve the damaged file before deleting it if recovery matters; other Sessions should remain separate.

3. A fork produces a different answer

   That is expected. Model output can vary, and the model or route may have changed since the branch point. A branch preserves a starting state; it does not guarantee identical output or travel back in time.

4. I want to back up every Session

   Use Home Assistant's current Settings → Backups workflow and include the Pi Agent add-on data under /data/pi-agent/ if that option is available. Test the documented restore process rather than assuming the backup contains every Session and provider or Skill setting. Chapter 20 explains the backup workflow in detail.

5. The Session list is slow

   Export resolved work as .jsonl and verify the archive before removing entries you no longer need. Performance depends on your pi-web version and host, so there is no universal file-count threshold.

6. An old Session has no usable model

   The referenced model or provider route may have been removed. Re-add a valid route by following Chapter 6, or select another currently configured model. Future messages then use the newly selected route.

Session FAQ