Session Commands

Sessions are persistent conversation threads that survive daemon restarts, system reboots, and terminal closures. Each session maintains isolated history stored in the local database, letting you run multiple independent conversations simultaneously. Every interaction—questions, answers, context—accumulates over time, making subsequent exchanges more relevant and coherent.

The Anatomy of a Session

Every session carries metadata that defines its identity and purpose. At minimum, it has a unique identifier that you use to reference it in commands. Sessions also belong to a workspace, which groups related conversations together—useful for keeping work projects separate from personal explorations. You can optionally assign a human-readable title that helps you remember what each conversation is about when you're browsing a long list of sessions.

The session type field classifies what kind of interaction the session supports. Most sessions use type "chat" for general conversation, but specialized types can enable different behaviors in the future. Creation and update timestamps track when sessions were born and last modified, helping you identify stale sessions you might want to clean up.

Listing Your Sessions

When you want to see all the conversations you've created, the lattice-ctl sessions list command provides an overview:

lattice-ctl sessions list

This shows every session the daemon knows about, displaying their IDs, titles, types, workspace associations, and timestamps. The list helps you understand your conversation landscape—which sessions are active, which are old, and how your work is organized across workspaces.

If you're working with many sessions spread across multiple workspaces, filtering by workspace cuts the noise significantly. Adding the --workspace flag restricts output to sessions belonging to that specific workspace:

lattice-ctl sessions list --workspace workspace_abc123

This focused view helps when you know which project you're working on but don't remember the exact session ID you need. You can scan just the relevant subset rather than wading through everything.

For programmatic use where you need structured data rather than human-readable text, adding --format json transforms the output into machine-parseable JSON. This format is essential for scripts that need to filter sessions, extract specific fields, or integrate session data into other tools:

lattice-ctl sessions list --format json

The JSON output includes all session metadata in a structured format that tools like jq can process easily. You can extract session IDs, filter by creation date, or build complex queries against your session database.

Inspecting Session Details

Sometimes you need more than a list—you need to dive deep into what a specific session contains. The lattice-ctl sessions get command retrieves comprehensive information about a single session:

lattice-ctl sessions get session_123abc

This command shows you everything the daemon knows about that session: its full metadata, message count, creation timestamp, last update time, and any associated configuration. When you're debugging why a conversation isn't working as expected or trying to understand the history of a particular interaction, this detailed view provides the necessary context.

The session ID you provide must match exactly—session IDs are case-sensitive and typically follow a pattern like session_ followed by a unique identifier. If you don't know the exact ID, use sessions list first to find it, then copy it precisely into the get command.

For scripts and programmatic analysis, use JSON format:

lattice-ctl sessions get session_123abc --format json

Creating New Sessions

Every conversation begins with creating a session. The lattice-ctl sessions create command establishes a new conversational space where you can interact with AI while maintaining persistent context:

lattice-ctl sessions create --workspace-id workspace_abc123

The workspace ID is mandatory because every session must belong to a workspace. Workspaces organize related conversations—you might have one workspace for work projects, another for personal exploration, and a third for experimentation. Keeping sessions properly organized within workspaces prevents confusion when you're managing many concurrent conversations.

Adding a descriptive title when creating sessions pays dividends later when you're scanning lists trying to remember which conversation is which:

lattice-ctl sessions create --workspace-id workspace_abc123 --title "Code Review Session"

A good title is concise but specific enough to distinguish this session from others. "Code Review Session" is better than just "Session" because it tells you the purpose at a glance. When you're looking at ten sessions trying to find the one about that specific bug, meaningful titles become crucial.

Session types classify what kind of interaction the session supports. The default "chat" type works for general conversation, but you can specify other types if needed:

lattice-ctl sessions create --workspace-id workspace_abc123 --title "Bug Analysis" --session-type analysis

Custom session types can enable specialized behaviors or configuration in the future. For now, sticking with "chat" works for most scenarios unless you have specific requirements.

When creating sessions programmatically, you often need to capture the session ID for subsequent operations. Using JSON output and piping through jq extracts just the ID:

SESSION_ID=$(lattice-ctl sessions create \
  --workspace-id workspace_abc123 \
  --title "My Session" \
  --format json | jq -r '.data.id')

echo "Created session: $SESSION_ID"

This pattern is essential for automation scripts that need to create a session and then immediately interact with it. The session ID captured in the variable becomes your handle for all future operations on this conversation.

Deleting Sessions

Eventually you'll accumulate sessions you no longer need—completed conversations, experimental chats, or outdated interactions that are just cluttering your session list. The lattice-ctl sessions delete command removes sessions permanently:

lattice-ctl sessions delete session_123abc

Deletion is irreversible and comprehensive. When you delete a session, the daemon removes all conversation history, every message exchanged, all metadata, and any associated data. There's no undo, no trash can, no way to recover deleted sessions. This finality makes deletion powerful but requires careful use—double-check the session ID before confirming deletion of important conversations.

Before deleting sessions with valuable history, consider whether you truly want them gone. If you're just trying to clean up a cluttered list, filtering by workspace or searching for specific titles might serve you better than permanent deletion. Save deletion for sessions you're genuinely finished with and have no reason to revisit.

Common Session Workflows

Understanding individual commands is useful, but seeing how they combine in real scenarios builds practical competence. Let's walk through typical session workflows.

When starting a new conversation, you create a session and then use it with whatever client tool you prefer—perhaps the ada CLI for interactive chat:

# Create session with a descriptive title
SESSION_ID=$(lattice-ctl sessions create \
  --workspace-id default \
  --title "New Chat" \
  --format json | jq -r '.data.id')

# Use the session with ada CLI
ada chat --session $SESSION_ID

This pattern establishes the conversational space first, captures its identifier, and then passes that identifier to your chat tool. The session persists all exchanges, letting you resume later even if you close the terminal.

Resuming a previous conversation requires knowing which session you want to continue. List your sessions to find the right one, then use its ID to resume:

# Browse your sessions
lattice-ctl sessions list

# Resume specific session with ada
ada chat --session session_123abc

The daemon loads all previous context from that session, ensuring the conversation continues naturally from where you left off. This persistent context is what makes sessions valuable—every interaction builds on what came before.

Cleaning up old sessions prevents your session list from growing unwieldy. You can delete sessions selectively based on age, workspace, or simply by scanning the list and removing ones you recognize as obsolete:

# List sessions to identify old ones
lattice-ctl sessions list --format json > sessions.json

# Delete specific old sessions
lattice-ctl sessions delete session_old123
lattice-ctl sessions delete session_old456

For bulk cleanup based on age or other criteria, you can combine JSON output with command-line tools to automate the filtering and deletion process. Be cautious with automation, though—it's easy to accidentally delete sessions you wanted to keep if your filtering logic isn't precise.

Filtering and Searching Sessions

As your session collection grows, finding specific conversations becomes challenging. Effective filtering helps you locate the session you need quickly.

The workspace filter is the most straightforward way to narrow down sessions. If you know which project or context you were working in, filtering by workspace immediately reduces the list to just relevant sessions:

lattice-ctl sessions list --workspace workspace_abc123

This shows only sessions belonging to that workspace, cutting out all the noise from other contexts. It's particularly useful when you have dozens or hundreds of sessions spread across multiple workspaces.

For more sophisticated filtering based on creation date, update time, or title content, you'll need to combine JSON output with tools like jq. Here's how to find sessions created on a specific date:

lattice-ctl sessions list --format json | \
  jq '.data.sessions[] | select(.createdAt | startswith("2024-01-15"))'

This extracts only sessions created on January 15, 2024. You can adjust the date string to match whatever timeframe you're interested in. Similarly, finding recently updated sessions helps you identify active conversations:

lattice-ctl sessions list --format json | \
  jq '.data.sessions[] | select(.updatedAt > "2024-01-15T00:00:00Z")'

Sessions with update timestamps after your specified date appear in the results. This filtering is useful for finding conversations you were recently working on.

Searching by title content requires a substring match in jq. For instance, finding all sessions with "bug" in the title:

lattice-ctl sessions list --format json | \
  jq '.data.sessions[] | select(.title | contains("bug"))'

This case-sensitive search returns sessions whose titles contain the substring "bug". Combine multiple filters for more precise queries—for example, sessions in a specific workspace created after a certain date with particular title keywords.

How Session Persistence Works

Understanding what happens to your sessions behind the scenes helps you trust the system and troubleshoot effectively when issues arise.

Sessions are stored in a SQLite database located at ~/.lovelace/lattice/state.db. SQLite provides a robust, serverless database that can handle concurrent access and crash recovery without requiring separate database server processes. Every time you create a session, send a message, or modify session metadata, those changes are written immediately to this database file.

The persistence model is comprehensive. Session metadata like titles, types, and timestamps are stored, along with the complete message history of every exchange. Workspace associations link sessions to their organizational context. Even custom session types and any future extensions to the session model will persist in this database.

State is saved continuously as you work, not just at shutdown. When you create a session, it's written to disk immediately. Each message gets persisted as it's processed. This write-through approach means that even if the daemon crashes unexpectedly, you won't lose any data beyond whatever operation was in flight at that exact moment.

Session recovery happens automatically when the daemon starts. During initialization, the daemon opens the state database and reads all existing sessions into memory. When you list sessions or get session details, the daemon serves that information from the loaded state. This recovery process ensures that restarting the daemon—whether for maintenance, after a crash, or following a system reboot—doesn't cause data loss.

Using Sessions Programmatically

While the CLI is great for interactive use, many workflows benefit from programmatic session management through code. Lattice provides client libraries for TypeScript and Rust that make this straightforward.

In TypeScript, the Lattice client exposes async methods for all session operations:

import { LatticeClient } from "@lovelace-ai/lattice-client";

const client = new LatticeClient();
await client.connect();

// Create session
const session = await client.createSession({
  workspaceId: "workspace_abc123",
  title: "My Chat",
  sessionType: "chat",
});

// List sessions
const sessions = await client.listSessions();

// Get session details
const details = await client.getSession(session.id);

// Delete session
await client.deleteSession(session.id);

The TypeScript API uses promises and async/await for clean asynchronous code. Error handling follows JavaScript conventions—wrap calls in try/catch blocks to handle failures gracefully. The client automatically manages connection state and reconnection, so you don't need to worry about daemon availability beyond the initial connection.

Rust code uses similar patterns but with Rust's ownership and error handling semantics:

use lattice_client::{LatticeDaemonClient, ClientConfig};

let config = ClientConfig::default();
let client = LatticeDaemonClient::connect(config).await?;

// Create session
let session = client.create_session(
    "workspace_abc123",
    Some("My Chat".to_string()),
    "chat"
).await?;

// List sessions
let sessions = client.list_sessions(None).await?;

// Get session
let details = client.get_session(&session.id).await?;

// Delete session
client.delete_session(&session.id).await?;

Rust's type system provides compile-time guarantees about correct usage. The Result types force explicit error handling, making it harder to accidentally ignore failures. The async/await syntax looks similar to TypeScript, but the underlying semantics follow Rust's zero-cost abstraction principles.

Troubleshooting Session Issues

When session operations fail or behave unexpectedly, a few common problems are worth checking.

If you try to get or delete a session but receive "session not found" errors, verify the session actually exists by listing all sessions and searching for the ID. Sessions are occasionally deleted without realizing it, or you might be using the wrong workspace filter that's hiding the session you're looking for. Double-check the exact session ID—a single character difference makes it a completely different identifier.

Session creation failures typically indicate workspace problems. The workspace ID must exist before you can create sessions in it. If you're specifying an invalid or non-existent workspace, the daemon rejects the request. Verify your workspace ID is correct, or try creating the session in the default workspace to isolate whether it's a workspace-specific issue.

If session listing returns no results when you expect to see sessions, check whether you're inadvertently filtering too aggressively. A workspace filter might be hiding sessions in other workspaces. Try listing without any filters first to see the complete picture. Also verify the database file exists at ~/.lovelace/lattice/state.db—if it's missing, the daemon has no session data to work with.

Database corruption is rare but can happen if the daemon crashes during a write or if the filesystem has issues. If you suspect database problems, check the daemon's logs for SQLite errors. In worst-case scenarios, you might need to delete the corrupted database file (losing all session data) and let the daemon create a fresh one. Always back up important session data before resorting to this.

Next Steps

Sessions are just one piece of how Lattice manages ongoing work. The agent commands guide explains how to launch autonomous agents that execute tasks in the background. The daemon control guide covers starting, stopping, and monitoring the daemon process that manages sessions. For programmatic integration details, see the programmatic usage guide, which walks through building applications that leverage session management. Finally, the configuration guide explains how to customize session behavior through configuration files.