> ## 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.

# Project-Scoped Sessions

> Sessions are remembered per project, with cumulative token and cost tracking across all runs

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

agent = Agent(name="project-agent", instructions="Manage project-scoped agent sessions.")
agent.start("Load my marketing-campaign project session and continue where we left off.")
```

The user resumes work in the same project folder; prior turns and cumulative usage load automatically.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
cd ~/code/my-app && praisonai run "Build a TODO app"
praisonai run --continue "Add a delete endpoint"
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Project Session Flow"
        A[📁 Project A] --> B[🗂️ Sessions A]
        C[📁 Project B] --> D[🗂️ Sessions B]
        B --> E[🔄 --continue]
        D --> F[🔄 --continue]
        E --> G[📊 A history only]
        F --> H[📊 B history only]
    end

    classDef project fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef sessions fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef operation fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class A,C project
    class B,D sessions
    class E,F operation
    class G,H result
```

## Quick Start

<Steps>
  <Step title="Start in your project root">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    cd ~/code/my-app && praisonai run "Build a TODO app"
    ```

    Project context comes from the git root (or current directory if not in a repo).
  </Step>

  <Step title="Continue later">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai run --continue "Add a delete endpoint"
    ```

    Prior user and assistant messages replay before your new prompt — no need to summarise what happened last time.
  </Step>

  <Step title="List this project's sessions">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai session list
    ```

    Shows every session `--continue` could resume for this project — the project's own sessions **plus** any globally-stored sessions (from `chat`, gateway, TUI, API, or a bare `Agent(session_id=...)`). Duplicates are collapsed; the freshest record wins.
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant CLI
    participant PS as Project session store
    participant GS as Global default store
    participant Agent

    User->>CLI: praisonai run --continue "..."
    CLI->>PS: list_sessions(limit)
    CLI->>GS: list_sessions(limit)
    Note over CLI: merge + dedup by session_id, freshest wins, prefer root sessions
    CLI-->>CLI: last root session id
    CLI->>Agent: restore history, run prompt
    Agent->>PS: append new messages
    Agent-->>User: response

    classDef cli fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef store fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class User,CLI cli
    class PS,GS store
    class Agent result
```

`find_last_session()` merges the **project-scoped store** and the **global default store** so `--continue` resolves the most-recent session regardless of how it was created (`run`, `chat`, gateway, TUI, API, or a bare `Agent(session_id=...)`). Sub-agent / forked children are skipped — the last **root** session wins. It falls back to a child only if the project has none. Each store is scanned with a `limit` window (default `50`).

| Where you are      | Project ID from                          |
| ------------------ | ---------------------------------------- |
| Inside a git repo  | `git rev-parse --show-toplevel`          |
| Outside a git repo | Current working directory                |
| Stored hash        | First 8 chars of `sha256(absolute_path)` |

History restore and save wiring landed in [PR #1963](https://github.com/MervinPraison/PraisonAI/pull/1963). If no prior session exists, a warning appears and a new session starts.

***

## Persisted usage shape

Every session stores a `usage` blob in `~/.praisonai/sessions/projects/<project_id>/<session_id>.json`. Config-driven consumers and scripts can read this directly.

| Key             | Type    | Notes                                                                                                                                  |
| --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `input_tokens`  | `int`   | Cumulative prompt tokens                                                                                                               |
| `output_tokens` | `int`   | Cumulative completion tokens                                                                                                           |
| `cached_tokens` | `int`   | Cumulative cached / prefix-hit tokens (when provider reports them)                                                                     |
| `total_tokens`  | `int`   | `input + output` (cached not double-counted); mirrored to flat `total_tokens` on session metadata for back-compat with `list_sessions` |
| `cost`          | `float` | USD, priced via `get_pricing(model)`; mirrored to flat `cost`                                                                          |
| `requests`      | `int`   | Count of `agent.start()` runs that produced usage                                                                                      |

The flat `total_tokens` and `cost` fields at the session root are mirrors kept for backwards compatibility with any code reading the old schema.

**SDK helpers (praisonaiagents 1.6.85+):**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.cli.state.project_sessions import (
    read_session_usage,
    format_usage_footer,
    accumulate_session_usage,
)

usage = read_session_usage(session_id="abc12345")
print(usage)
# {"input_tokens": 10000, "output_tokens": 2345, "cached_tokens": 0,
#  "total_tokens": 12345, "cost": 0.014, "requests": 3}

footer = format_usage_footer(usage)
print(footer)
# "10,000 in / 2,345 out · $0.0140"

updated = accumulate_session_usage(session_id="abc12345", model="gpt-4o-mini")
```

***

## Configuration Options

| Flag                    | Description                                                                                                                 |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `--continue`            | Resume the most recent **root** session for this project — searches both the project store **and** the global default store |
| `--session <id>`        | Resume a specific session                                                                                                   |
| `--fork --session <id>` | Branch a session to try alternatives                                                                                        |
| `--no-save`             | One-off prompt — nothing persisted                                                                                          |
| `session list --all`    | List sessions across all projects                                                                                           |

***

## Best Practices

<AccordionGroup>
  <Accordion title="Run from the project root">
    Start `praisonai run` from the repo root so git detection stays consistent — subdirectories still resolve to the same project.
  </Accordion>

  <Accordion title="Use --fork for risky experiments">
    Try alternatives without altering the main thread: `praisonai run --fork --session abc123 "try Redis instead"`.
  </Accordion>

  <Accordion title="Use --no-save for throwaway prompts">
    Quick questions or PII-sensitive input: `praisonai run --no-save "How do I hash passwords?"`.
  </Accordion>

  <Accordion title="Clean up with session list --all">
    Review and delete stale sessions across projects periodically.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Run Command" icon="play" href="/docs/cli/run">
    Complete `praisonai run` with session flags and usage footer
  </Card>

  <Card title="Session Management" icon="clock-rotate-left" href="/docs/cli/session">
    Session commands, new table columns, and resume panel
  </Card>

  <Card title="Cost Tracking" icon="dollar-sign" href="/docs/cli/cost-tracking">
    Per-session persistence, `/cost` command, and pricing table
  </Card>
</CardGroup>