> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xynthis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chatting

> Interactive and one-shot chat, session management, and how memory reaches a conversation.

## Interactive and one-shot

Run `xynthis` with no arguments to open the interactive REPL. Plain text goes through the full agent loop: the model can call tools, read memory, and act. Lines starting with `/` are REPL commands that talk to the brain directly without an LLM call; `/help` lists them.

For a single turn, use `xynthis chat`:

```bash theme={null}
xynthis chat "summarize what I worked on yesterday"
```

`chat` runs one agent turn against the active model, prints the result, and exits. On macOS it also launches the menu-bar app and a background daemon so the GUI can show live agent activity. Pass `--no-app` (or set `XYNTHIS_NO_APP=1`) to run headless.

| Flag             | Effect                                                        |
| ---------------- | ------------------------------------------------------------- |
| `--new`          | Start a fresh session instead of appending to the current one |
| `--session <id>` | Append to a specific session                                  |
| `-v, --verbose`  | Print raw tool-call output alongside the final answer         |
| `--no-app`       | Headless: no app launch, no background daemon                 |

## Sessions

Every conversation is a session: an on-disk transcript at `~/.xynthis/sessions/<id>.json`. `xynthis chat` appends to the **current session** by default, the one you last chatted with or resumed. That means this works:

```bash theme={null}
xynthis chat "my deploy target is the staging VM"
xynthis chat "what's my deploy target?"
```

To pick up an earlier conversation in the REPL:

```bash theme={null}
xynthis resume            # most recent session
xynthis resume --id <id>  # a specific one
```

Manage sessions with the `sessions` subcommand:

```bash theme={null}
xynthis sessions list                      # newest first
xynthis sessions show <id>                 # full message history as JSON
xynthis sessions delete <id>
xynthis sessions archive --older-than-days 30 --run
```

`archive` moves old session files into `~/.xynthis/archive`. Without `--run` it is a dry run.

### Sessions in the app and the daemon

The macOS app sends a stable `sessionId` with every chat request. The daemon keeps a separate history per id, so switching between chat threads in the app never bleeds context from one conversation into another. The daemon exposes the same data over HTTP on `127.0.0.1:3939`: `GET /api/sessions` lists saved sessions (id, title, timestamps, message count) and `GET /api/session/transcript?id=<id>` returns the clean user/assistant transcript for rendering.

## How memory enters a conversation

Before each turn, the agent queries the brain for context relevant to your message and injects what it finds as a clearly labeled background block. The block is marked as prior-session context, and the model is instructed to treat it as awareness only: your current message stays the only authoritative instruction. When nothing relevant clears the recall gates, nothing is injected.

Two other memory surfaces feed the turn:

* **Working memory**: a per-session ledger of the last 30 tool actions, re-injected each turn so the agent knows what it already did in this conversation. It lives at `~/.xynthis/sessions/<id>.working_memory.json`.
* **Skill patterns**: distilled "for this kind of request, this tool worked" records the brain collects after successful turns. When one matches, it is surfaced ahead of the general memory block.

Two limits worth knowing: on the free tier, recall reaches back 7 days (see [Working with memory](/guides/memory)), and lite-mode local providers skip memory injection entirely (see [Local models](/guides/local-models)).

## Searching past sessions

Full-text search covers every saved session:

```bash theme={null}
xynthis search --index            # build the index (first time only)
xynthis search "postgres migration"
xynthis search "auth flow" --semantic
```

The default is keyword match over an FTS5 index that auto-updates after the first build. `--semantic` switches to vector search through the brain, which matches meaning rather than literal words: "auth flow" finds a login-token discussion. Semantic search requires the brain daemon to be running. `--top-k <n>` changes the hit count (default 10).

For a factoid answer straight from memory (no LLM call, no tokens), use `xynthis ask`. See [Working with memory](/guides/memory).