Managing Conversation History

Witsy automatically saves your conversations, allowing you to resume them later or reference past interactions. This section covers how to organize, search, and manage your chat history effectively.

Organizing Conversations with Folders

As your list of chats grows, you can group related conversations into folders to keep your workspace tidy.

Create a new folder

1. Open the Chat Sidebar on the left.
2. Click the + Folder icon at the top of the history list.
3. Enter a name for your folder and press Enter.

Move chats into folders

• Drag and Drop: Simply click and hold a conversation in the sidebar and drag it into the desired folder.
• Context Menu: Right-click a conversation, select Move to Folder, and choose the target folder from the list.

Set folder defaults

You can configure folders to use specific settings (like a preferred AI engine or system instructions) so that every new chat created inside that folder inherits those properties.

1. Right-click a folder and select Edit Folder.
2. Set the default Engine, Model, and System Instructions.
3. Toggle Enable Plugins if you want tools to be active by default for chats in this folder.

Searching Your History

To find a specific interaction from the past:

1. Locate the Search Bar at the top of the Chat Sidebar.
2. Type keywords from the conversation title or message content.
3. The list will filter in real-time. Click any result to jump directly into that chat.

Managing Individual Chats

Renaming a Chat

By default, Witsy generates a title based on the first few messages. To change it:

1. Right-click the chat in the sidebar.
2. Select Rename.
3. Enter the new title and save.

Deleting History

• Single Chat: Right-click a conversation and select Delete.
• Entire Folder: Right-click a folder and select Delete Folder. You will be asked if you want to delete the folder only (moving chats to the root) or delete the folder and all its contents.

Programmatic History Management (CLI/API)

If you are using Witsy's HTTP API or CLI, you can interact with the conversation history programmatically. This is useful for scripts that need to save results into the Witsy GUI for later review.

Saving a conversation via API

You can send a chat object to the /api/conversations endpoint to persist it in the local database.

// Example using the Witsy API Client
import { WitsyAPI } from './cli/api';

const api = new WitsyAPI();

const chatData = {
  title: "Research Notes",
  engine: "openai",
  model: "gpt-4",
  messages: [
    { role: "user", content: "Summarize the latest trends in MCP." },
    { role: "assistant", content: "The Model Context Protocol is evolving..." }
  ]
};

const chatId = await api.saveConversation(chatData);
console.log(`Conversation saved with ID: ${chatId}`);

Accessing CLI Configuration

To ensure your scripts are saving history to the correct location, you can query the current configuration:

# Get the path where Witsy stores user data and history
curl http://localhost:4321/api/cli/config

Best Practices for History Management

• Use Descriptive Folder Names: Instead of "Drafts," use project-specific names like "Project Phoenix - Documentation" to make searching easier.
• Archive via Context: If a folder is no longer active, you can move it to the bottom of the list or rename it with a prefix like [Done].
• Utilize "Experts": When starting a chat intended for long-term history, select an Expert (system prompt template) first. This ensures the history remains focused and high-quality when you refer back to it.