Sessions

Resonant tracks conversations through a session and thread system that maintains continuity across restarts and days.

Sessions

A session represents a continuous interaction period. Sessions are stored in SQLite alongside all conversation messages.

Managing Sessions

From the web UI or chat commands:

Command	What It Does
/session list	Browse past sessions with timestamps and message counts
/session new [name]	Start a new named session
/session switch <id>	Switch to a different session
/session rename <name>	Rename the current session

Continuity

When Resonant restarts, it picks up where you left off. The Claude Agent SDK’s native memory system preserves context across sessions, so your companion doesn’t lose track of ongoing conversations.

Threads

Threads organise conversations within sessions:

• Daily threads — automatically rotate each day, keeping conversations contextually grouped
• Named threads — create threads for ongoing topics (“project planning”, “reading list”)
• Pinning — pin important threads to keep them accessible
• Archiving — archive old threads without deleting them

Search

Two types of search are available:

Keyword Search (Ctrl+K)

Fast, indexed search across all messages. Good for finding specific phrases, names, or commands.

Semantic Search

Meaning-based search using local ONNX embeddings. Finds messages even when the exact words don’t match.

For example, searching “that time we talked about feeling overwhelmed” will find relevant conversations even if the word “overwhelmed” was never used.

See docs/semantic-search.md for setup details and usage.

Canvas

The canvas is an in-chat editor for collaborative content creation:

• Markdown — write and preview documents together
• Code — syntax-highlighted code editing
• Text — plain text editing
• HTML — live HTML preview

Your companion can create, edit, and display canvas items during conversation. Useful for drafting documents, reviewing code, or building content together.

Deployment

Development

npm run dev              # Backend with hot reload (tsx watch)
npm run dev:frontend     # Vite dev server with proxy

Production with PM2

For production use, PM2 keeps your companion running and restarts it automatically:

npm run build
pm2 start ecosystem.config.cjs
pm2 save
pm2 startup              # Auto-start on boot

Key PM2 commands:

pm2 status               # Check if running
pm2 logs resonant        # View logs
pm2 restart resonant     # Restart the process
pm2 stop resonant        # Stop without removing

Updating

Your data (data/, resonant.yaml, CLAUDE.md, .mcp.json, .env) is gitignored and won’t be affected by updates.

cd resonant
git pull
npm install
npm run build
pm2 restart resonant

To update to a specific version:

git fetch --tags
git checkout v1.4.1      # Replace with desired version
npm install
npm run build

Check the Releases page for changelogs and migration notes.