Skip to main content

​
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: 
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.
FlagEffect
--newStart a fresh session instead of appending to the current one
--session <id>Append to a specific session
-v, --verbosePrint raw tool-call output alongside the final answer
--no-appHeadless: 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: 
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: 
xynthis resume            # most recent session
xynthis resume --id <id>  # a specific one
Manage sessions with the sessions subcommand: 
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), and lite-mode local providers skip memory injection entirely (see Local models).

​
Searching past sessions

Full-text search covers every saved session: 
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.