Project-Scoped Sessions

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

from praisonaiagents import Agent, MemoryConfig

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.

cd ~/code/my-app && praisonai run "Build a TODO app"
praisonai run --continue "Add a delete endpoint"

Quick Start

1. Start in your project root

   cd ~/code/my-app && praisonai run "Build a TODO app"

   Project context comes from the git repository — its remote or root commit — falling back to a path hash only outside a repo.

2. Continue later

   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.

3. List this project's sessions

   $ praisonai session list
   Project: my-app (ID: a1b2c3d4, identity: git-remote)
   ...

   The identity: label tells you which resolver won — useful when explaining why two clones share sessions or why a fresh repo has none.

   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( memory=MemoryConfig( session_id=..., ))). Duplicates are collapsed; the freshest record wins.

How It Works

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( memory=MemoryConfig( 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).

The CLI now follows the repository, not the folder — cloning, moving, or git worktree-ing a repo keeps the same session history.

All four sources collapse to the same 8-char sha256 short hash, so the on-disk session layout is unchanged.

What survives

Session history follows the repository, not the folder.

Upgrading from an earlier CLI? Your existing project sessions are stored under a directory named after a hash of the repo’s absolute path. On the first --continue / praisonai run after upgrading, sessions are copied (not moved) into the new identity-based directory automatically. No configuration, no data loss — just re-run in the same repo and prior history is there.

After upgrading, the first resolve in each git repo also writes a small .git/praisonai-root-commit file next to the existing .git/praisonai-project. Both are internal to PraisonAI, shared across all worktrees of the repo, and safe to commit or leave untracked — deleting either just causes the next run to recompute and re-pin.

History restore and save wiring landed in PR #1963. If no prior session exists, a warning appears and a new session starts.

Reading the identity source programmatically:

from praisonai_code.cli.utils.project import (
    get_project_id,
    get_project_identity_source,
    resolve_project_identity,
)

pid = get_project_id()                     # 8-char hash — unchanged public API
source = get_project_identity_source()     # "git-remote" / "root-commit" / "cached-id" / "path"
pid, source = resolve_project_identity()   # both in one call

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.

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+):

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

Works with YAML / team runs

The same four flags apply to praisonai run agents.yaml, so an AgentTeam resumes exactly like a single-agent prompt.

sequenceDiagram
    participant User
    participant Adapter
    participant Team as AgentTeam
    participant Store as Session store

    User->>Adapter: praisonai run agents.yaml --continue
    Adapter->>Team: restore_session_state(id)
    Team->>Team: rehydrate per-agent chat_history (deduped)
    Adapter->>Team: astart()
    Adapter->>Team: capture chat_history into state
    Adapter->>Store: save_session_state(id)
    Adapter-->>User: response

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

    class User,Adapter actor
    class Team process
    class Store result

Per-agent chat_history is captured into team state on save (under the reserved key _cli_session_chat_history) and re-injected on restore, so a resumed YAML team continues the actual conversation — not just team bookkeeping.

Best Practices

Related