Sessions

A session is a saved conversation with an agent. On a local install they are JSON files in ~/.muaz/sessions/ — one per session, chmod 600 — with an index.json beside them holding the metadata the session list shows.

A shared deployment can keep them in a database instead, where they are listed by recency directly and there is no index document to maintain. Nothing on this page changes with the backend: a session resumes the same way, carries the same working directory, and belongs to the same tenant either way.

Resuming and browsing

• Pass --session <id> on startup to resume a specific session:

  muaz chat --session 3f9c1a2e-...

• Use /sessions inside the REPL to browse recent sessions and pick one to resume.

• Use /session to print the current session’s metadata (id, model, message count).

Working directory

Every session has one working directory, fixed at open: the built-in file tools are confined to it, shell runs in it, and project-tier skills and project memory are keyed by it. It resolves in order:

1. an explicit choice (the working-directory field on the UI’s new-chat page, or working_dir on the session-create API),
2. the agent’s configured workspace_root (its default),
3. workspace_root in config.yaml — worth setting for a long-lived gateway, which would otherwise inherit whatever directory it was started in,
4. the directory muaz was started in (the CLI’s natural behaviour — muaz works wherever you launch it).

Resuming a session reuses its original working directory, no matter where muaz is later launched from — the transcript’s file references only make sense there. If that directory no longer exists, the resume fails with an actionable error instead of silently falling back. In the browser UI the active directory is shown as a chip in the chat header; click it to edit the project’s memory notebook.

When the deployment fixes it

A deployment can pin workspace_root (MUAZ_WORKSPACE_ROOT, or the instance config file — see Deployment settings). The pin contains every rung above: a directory inside it is still yours to choose, and anything outside it is not. Asking for a directory outside the pin is refused with an error naming it; a directory that merely resolved to somewhere outside (a session recorded before the pin, an agent’s own workspace_root) is quietly pulled back to the pin instead, so an old session never becomes unopenable.

Hosted sandboxes pin /workspace. It is scratch space: a sandbox is reclaimed after a period of idleness, and everything in /workspace goes with it. Anything you want to keep should leave through the conversation itself or a git push. The team-server image uses the same /workspace, where an operator can make it durable by mounting a volume there.

Incognito mode

To hold a conversation without persisting it to disk:

muaz chat --incognito

Or toggle it mid-session with /incognito. An incognito session is never persisted at all — not to disk, and not to a database behind a shared deployment.