Where Craft Agents Conversation History Is Stored: File Paths and JSON Format Explained

Craft Agents persists every session's conversation history as a JSON file located at ~/.craft-agent/workspaces/<workspace-id>/conversation.json by default.

The craft-ai-agents/craft-agents-oss repository handles conversation persistence through a predictable file-system structure. Understanding where Craft Agents conversation history lives and how it is formatted enables you to back up data, migrate workspaces, or build external analysis tools.

Global Configuration Root

All user-specific data resides under a global configuration directory defined in packages/shared/src/config/paths.ts:

// packages/shared/src/config/paths.ts
export const CONFIG_DIR = process.env.CRAFT_CONFIG_DIR || join(homedir(), '.craft-agent');

By default, this resolves to ~/.craft-agent on the user's home directory. The CRAFT_CONFIG_DIR environment variable overrides this path, which the Electron launcher uses automatically to support multi-instance development environments.

Workspace-Specific Storage Structure

Inside the global config directory, a workspaces folder contains sub-directories for each workspace identified by its UUID. The path construction logic lives in packages/shared/src/config/storage.ts:

// packages/shared/src/config/storage.ts
const WORKSPACES_DIR = join(CONFIG_DIR, 'workspaces');

For any given workspace, the conversation history is saved as conversation.json within that workspace's specific folder. The full path follows this pattern:

~/.craft-agent/workspaces/<workspace-uuid>/conversation.json

File Format and Schema

The conversation file conforms to the WorkspaceConversation interface defined in packages/shared/src/config/storage.ts. The JSON structure includes message arrays, token usage statistics, and timestamps:

// packages/shared/src/config/storage.ts
export interface WorkspaceConversation {
  messages: StoredMessage[];
  tokenUsage: {
    inputTokens: number;
    outputTokens: number;
    totalTokens: number;
    contextTokens: number;
    costUsd: number;
    cacheReadTokens?: number;
    cacheCreationTokens?: number;
  };
  savedAt: number;            // UNIX epoch ms when the file was written
}

• messages: An array of StoredMessage objects containing the full LLM message history, including tool calls and results.
• tokenUsage: Aggregated token counts and estimated costs for the conversation.
• savedAt: UNIX timestamp in milliseconds indicating when the file was last written.

The file is written using JSON.stringify with two-space indentation, making it human-readable and easy to parse with standard tools.

Reading and Writing Conversation History

The packages/shared/src/config/storage.ts module exposes three primary functions for managing conversation data programmatically.

Saving Conversations

Use saveWorkspaceConversation to persist messages and token statistics:

import { saveWorkspaceConversation } from '@craft-agent/shared/config';

const workspaceId = 'e07c2a7b-9f5e-4d12-a1b3-f9c8d2e4a6b9';
const messages = [
  { role: 'user', content: 'Hello', type: 'text' },
  { role: 'assistant', content: 'Hi! How can I help?', type: 'text' },
];
const tokenUsage = {
  inputTokens: 10,
  outputTokens: 12,
  totalTokens: 22,
  contextTokens: 0,
  costUsd: 0.0001,
};

saveWorkspaceConversation(workspaceId, messages, tokenUsage);

Loading Conversations

Retrieve existing history with loadWorkspaceConversation, which returns null if no file exists:

import { loadWorkspaceConversation } from '@craft-agent/shared/config';

const conv = loadWorkspaceConversation(workspaceId);
if (conv) {
  console.log('Loaded', conv.messages.length, 'messages');
  console.log('Total tokens:', conv.tokenUsage.totalTokens);
}

Clearing History

Remove a conversation file entirely using clearWorkspaceConversation:

import { clearWorkspaceConversation } from '@craft-agent/shared/config';

clearWorkspaceConversation(workspaceId);

Environment Configuration

The storage location remains flexible through environment variables. Setting CRAFT_CONFIG_DIR before launching the application redirects all workspace data—including conversation histories—to the specified directory. This mechanism supports isolated development environments and custom deployment configurations without modifying source code.

Summary

• Craft Agents stores conversation histories in ~/.craft-agent/workspaces/<workspace-id>/conversation.json by default.
• The WorkspaceConversation interface defines the JSON schema with messages, tokenUsage, and savedAt fields.
• Use saveWorkspaceConversation, loadWorkspaceConversation, and clearWorkspaceConversation from packages/shared/src/config/storage.ts to interact with data programmatically.
• Override the default storage location by setting the CRAFT_CONFIG_DIR environment variable.

Frequently Asked Questions

Can I manually edit the conversation.json file?

Yes. Because Craft Agents stores conversation history as pretty-printed JSON, you can manually edit the file using any text editor. However, ensure the JSON remains valid and conforms to the WorkspaceConversation interface structure to prevent runtime errors when the application loads the workspace.

Does Craft Agents encrypt conversation history files?

No. According to the source code in packages/shared/src/config/storage.ts, files are written using standard JSON.stringify without encryption. The conversation histories are stored as plain text JSON, so you should implement filesystem-level encryption if you require data protection for sensitive conversation content.

How do I migrate conversation history to another machine?

Copy the entire ~/.craft-agent/workspaces/ directory (or your custom CRAFT_CONFIG_DIR location) to the new machine. Each workspace's conversation.json file is self-contained and portable, requiring no database restoration or complex migration scripts.

What happens if the conversation.json file is corrupted?

The loadWorkspaceConversation function in packages/shared/src/config/storage.ts reads the file synchronously. If the JSON is malformed or the file is missing, the function will likely throw an error or return null depending on the implementation of readJsonFileSync. You should maintain backups of the workspace directories to prevent data loss from file corruption.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}