> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations, Projects & Search

> Organize chats into projects, search everything, fork, and delete turns

Every conversation is an append-only transcript you can group into projects, search full-text, fork from any turn, or trim a message at a time.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
)
# Each Desktop conversation is one transcript this agent appends to.
agent.start("Start a new conversation")
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Chats[💬 Conversations] --> Projects[📁 Projects]
    Chats --> Search[🔍 ⌘K Search]
    Chats --> Fork[🌿 Fork]

    classDef chats fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef proj fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef search fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef fork fill:#10B981,stroke:#7C90A0,color:#fff

    class Chats chats
    class Projects proj
    class Search search
    class Fork fork
```

## Quick Start

<Steps>
  <Step title="Group into a project">
    Right-click a conversation and choose **Move to project** to group related chats.
  </Step>

  <Step title="Search everything">
    Press `⌘K` and type — the app searches every conversation's text and jumps to the first match.
  </Step>

  <Step title="Fork from a turn">
    Fork any turn to branch a new conversation without changing the original.
  </Step>
</Steps>

***

## How It Works

Transcripts are append-only JSON on disk, written with a write-then-rename pattern so a crash mid-write can never truncate an existing chat.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Turn[💬 Completed turn] --> Tmp[(chat.tmp)]
    Tmp --> Rename[rename → chat.json]
    Rename --> Store[(📁 chats/)]

    classDef turn fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tmp fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef store fill:#10B981,stroke:#7C90A0,color:#fff

    class Turn turn
    class Tmp,Rename tmp
    class Store store
```

Transcripts live at `~/Library/Application Support/PraisonAI/chats/` as one JSON file per conversation.

<Note>
  A transcript is written only after a run completes — never per token — so a chat app never burns through an SSD's write endurance.
</Note>

***

## Actions

| Action          | Endpoint                       | Effect                                                |
| --------------- | ------------------------------ | ----------------------------------------------------- |
| Search          | `GET /search?q=`               | Full-text across every conversation                   |
| Fork            | `POST /fork/{cid}/{idx}`       | Copies the transcript up to message N into a new chat |
| Delete message  | `DELETE /messages/{cid}/{idx}` | Removes one exchange (a user turn and its reply)      |
| Move to project | `POST /project/{cid}`          | Assigns the conversation to a project                 |
| Delete chat     | `DELETE /chats/{cid}`          | Removes the whole conversation                        |

<Warning>
  A corrupt transcript is surfaced in the sidebar as "(unreadable)" rather than hidden — a chat you can see is recoverable; one silently omitted looks like data loss.
</Warning>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Fork instead of editing history">
    A fork copies the transcript up to a chosen turn into a new conversation and leaves the original untouched — branch an idea without losing the thread.
  </Accordion>

  <Accordion title="Group with projects">
    Move related conversations into a project so the sidebar stays legible as chats accumulate.
  </Accordion>

  <Accordion title="Trust auto-titling">
    With `auto_title` on, the first message becomes the chat title. Leave it on and rename only the few that need it.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Data & Privacy" icon="lock" href="/docs/features/desktop/data">
    Where transcripts live and how to export them
  </Card>

  <Card title="Chat & Streaming" icon="comments" href="/docs/features/desktop/chat">
    Per-turn actions like Fork and Delete
  </Card>
</CardGroup>