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

> Discover where Craft Agents conversation history is stored in JSON format at ~/.craft-agent/workspaces/<workspace-id>/conversation.json. Understand your agent's memory.

- Repository: [Craft Ai Agents/craft-agents-oss](https://github.com/craft-ai-agents/craft-agents-oss)
- Tags: internals
- Published: 2026-07-04

---

**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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/config/paths.ts):

```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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/config/storage.ts):

```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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/config/storage.ts). The JSON structure includes message arrays, token usage statistics, and timestamps:

```ts
// 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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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:

```ts
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:

```ts
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`:

```ts
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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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.