Session

# List sessions for current project
praisonai session list

# List sessions across all projects
praisonai session list --all

# Start a new session
praisonai session start my-project

praisonai session start my-project

🆕 Starting new session: my-project

Session created successfully!
┌─────────────────────┬────────────────────────────┐
│ Property            │ Value                      │
├─────────────────────┼────────────────────────────┤
│ Session ID          │ my-project                 │
│ Created             │ 2024-12-16 15:30:00        │
│ Status              │ active                     │
│ Messages            │ 0                          │
└─────────────────────┴────────────────────────────┘

You can now run commands with this session context.
Use: praisonai "your prompt" --session my-project

praisonai session list

Project: my-app (ID: a1b2c3d4, identity: git-remote)
ID         Name            Status   Events  Tokens   Cost     Parent    Updated
abc12345   research-bot    active   12      12,345   $0.0140  -         2026-06-29 23:48 UTC
def67890   summariser      paused   3       420      $0.0004  abc12345  2026-06-29 21:11 UTC

praisonai session list --json

[
  {
    "id": "abc12345",
    "name": "research-bot",
    "status": "active",
    "parent_id": null,
    "events": 12,
    "usage": {
      "input_tokens": 10000,
      "output_tokens": 2345,
      "cached_tokens": 0,
      "total_tokens": 12345,
      "cost": 0.014,
      "requests": 3
    },
    "total_tokens": 12345,
    "cost": 0.014,
    "updated": "2026-06-29T23:48:00Z"
  }
]

{
  "sessions": [
    {
      "session_id": "session-abc123",
      "total_tokens": 5220,
      "cost": 0.014,
      "usage": {
        "input_tokens": 1240,
        "output_tokens": 3980,
        "cached_tokens": 0,
        "total_tokens": 5220,
        "cost": 0.014,
        "requests": 2
      }
    }
  ]
}

praisonai session list --all

praisonai session list --project a1b2c3d4

praisonai session rename 4f9a8c72-... "fix-auth-bug"

Renamed session 4f9a8c72-... to: fix-auth-bug

praisonai session rename 4f9a8c72-... ""

praisonai session list
# session-abc123     (no title)      2 hours ago
# session-def456     "Auth Refactor" yesterday

praisonai session rename session-abc123 "Deploy runbook draft"
# ✅ Renamed session-abc123 → "Deploy runbook draft"

praisonai session rename session-abc123 ""
# ✅ Cleared title for session-abc123

Session not found: 4f9a8c72-...
Use 'praisonai session list' to see available sessions

praisonai session rename 4f9a8c72-... "fix-auth-bug" --json

{"renamed": true, "session_id": "4f9a8c72-...", "title": "fix-auth-bug"}

praisonai session fork <session_id> [--at-message N] [--title "..."]

Forked session: sess_abc12345 -> sess_def67890
Resume the fork with: praisonai session resume sess_def67890

Session not found: sess_missing
Use 'praisonai session list' to see available sessions

--at-message 99 is out of range (session has 14 messages, valid 0..13)

praisonai session fork sess_abc12345 --at-message 8 --title "cookie-path" --json

{
  "forked": true,
  "parent_id": "sess_abc12345",
  "session_id": "sess_def67890",
  "from_message_index": 8,
  "title": "cookie-path"
}

praisonai session resume my-project

🔄 Session Resumed
┌─────────────────────────────────────────────┐
│ Session: my-project                         │
│ Model:   gpt-4o                             │
│ Messages restored: 12                       │
│ Usage:   10,000 in / 2,345 out · $0.0140   │
└─────────────────────────────────────────────┘

--- Restored Conversation ---
[user] Can you explain the authentication flow?
[assistant] Based on the code...

praisonai session resume my-project "Now refactor the auth module"

praisonai session resume my-project --transcript

praisonai session search "billing migration"
praisonai session search "billing migration" --limit 10 --window 8

{
  "session_id": "q3-review",
  "metadata": {
    "usage": {
      "input_tokens": 1240,
      "output_tokens": 3980,
      "cached_tokens": 0,
      "total_tokens": 5220,
      "cost": 0.014,
      "requests": 1
    },
    "total_tokens": 5220,
    "cost": 0.014
  }
}

1,240 in / 3,980 out · $0.0140

╭─ Session Resumed: q3-review ──────────────────────────╮
│ Session: q3-review                                    │
│ Model:  gpt-4o-mini                                   │
│ Messages restored: 3                                  │
│ Usage:  12,440 tokens · $0.0710 (3 requests)          │
╰───────────────────────────────────────────────────────╯

from praisonai.cli.state.project_sessions import (
    read_session_usage,
    format_usage_footer,
)

usage = read_session_usage("q3-review")
print(format_usage_footer(usage))
# 1,240 in / 3,980 out · $0.0140

print(f"Cumulative requests: {usage['requests']}")
print(f"Cached tokens: {usage['cached_tokens']:,}")

praisonai session show my-project

📊 Session Details: my-project

┌─────────────────────┬────────────────────────────┐
│ Property            │ Value                      │
├─────────────────────┼────────────────────────────┤
│ Session ID          │ my-project                 │
│ Agent               │ Researcher                 │
│ Model               │ gpt-4o                     │
│ Created             │ 2024-12-16 15:30:00        │
│ Updated             │ 2024-12-16 15:45:00        │
│ Messages            │ 12                         │
└─────────────────────┴────────────────────────────┘

Recent Messages:
────────────────────────────────────────────────────
[User] Can you explain the authentication flow?
[Agent] Based on the code, the authentication...
────────────────────────────────────────────────────
[User] How do I add OAuth support?
[Agent] To add OAuth support, you would need to...
────────────────────────────────────────────────────

praisonai session show <session-id> --recap

╭─ Session Recap ──────────────────────────────────────╮
│ 📌 Recap — where we were:                            │
│ [Previous conversation summary]                      │
│ User asked about deploy runbook; we outlined 1–3.    │
│ Recent:                                              │
│ • user: what about step 4?                           │
│ • assistant: step 4 covers rollback…                 │
╰──────────────────────────────────────────────────────╯

praisonai session show <session-id> --recap --json
# {"session_id": "...", "recap": "📌 Recap — where we were:\n..."}

praisonai session handoff <session-id>
praisonai session handoff <session-id> --json
praisonai session handoff <session-id> --copy

╭─ Session Handoff ────────────────────────────────────╮
│ You are resuming an interrupted run. Recover from     │
│ durable state; do not trust memory of a previous      │
│ conversation.                                         │
│                                                       │
│ GOAL: Ship the logging refactor                       │
│ DEFINITION OF DONE: All modules use structured logging│
│ PROGRESS: 3 of 5 workflow steps done; last completed: │
│ wire logger                                           │
│ RECENT ACTIONS (recap-derived):                       │
│ Recap — where we were: refactored logging in main.py  │
│ NEXT: continue toward the remaining work. First verify│
│ the current state on disk before acting.              │
╰───────────────────────────────────────────────────────╯

praisonai session handoff <session-id> --json
# {"session_id": "...", "handoff": "...", "has_goal": true, "has_checkpoint": true}

praisonai session export my-project --format md
praisonai session export my-project --format json

praisonai session delete my-project

Delete session my-project? [y/N]: y
✅ Deleted session: my-project

praisonai session delete my-project --yes

❌ Failed to delete session: my-project

# Print as markdown (default)
praisonai session export my-project

# Or as JSON
praisonai session export my-project --format json

# Save to a file
praisonai session export my-project --format md --output my-project.md

# Session: research-bot

- **Session ID**: my-project
- **Agent**: research-bot
- **Model**: gpt-4o
- **Created**: 2024-12-16 15:30:00
- **Updated**: 2024-12-16 15:45:00
- **Messages**: 12

## Conversation

### user

Can you explain the authentication flow?

### assistant

Based on the code, the authentication...

✅ Exported to: my-project.md

# Default — raw transcript, unchanged (may leak secrets)
praisonai session export my-project --format json

# Opt-in — secrets, paths, and cwd replaced with stable placeholders
praisonai session export my-project --format json --sanitise

# Same, US spelling
praisonai session export my-project --format md --sanitize

# Broader net (bearer tokens + PEM private-key blocks)
praisonai session export my-project --sanitise --redact-level strict

Before:   read /home/alice/project/config.yaml — api_key=sk-ABCDEF0123456789ABCDEF
After:    read [redacted:path:1] — api_key=[redacted:secret:1]

$ praisonai session export my-project --sanitise --redact-level loose
❌ Invalid --redact-level 'loose'. Choose one of: standard, strict.

from praisonai_code.cli.state.session_resolver import export_session

# Default — raw
raw = export_session("my-project", format="json")

# Opt-in — sanitised
safe = export_session("my-project", format="json", redact=True, redact_level="standard")

from praisonai_code.cli.state.redact import redact_transcript, REDACT_LEVELS

safe_payload = redact_transcript(
    payload,                          # dict from resolved.to_dict()
    level="standard",                 # or "strict"; must be in REDACT_LEVELS
    extra_secrets=["HUNTER2SECRET"],  # extra literal values to mask
)

# default: strict (safe for public sharing)
praisonai session share sess-abc123

# → ✅ Shared session: sess-abc123
# → ℹ Link: file:///Users/alice/.praisonai/shares/1a2b3c4d5e6f7a8b.html

# opt down to standard if the recipient is trusted
praisonai session share sess-abc123 --redact-level standard

# Revoke — deletes the shared HTML file
praisonai session unshare sess-abc123

# → ✅ Unshared session: sess-abc123

✅ Shared session: sess-abc123
ℹ Link: file:///Users/alice/.praisonai/shares/1a2b3c4d5e6f7a8b.html

{
  "session_id": "sess-abc123",
  "shared": true,
  "url": "file:///Users/alice/.praisonai/shares/1a2b3c4d5e6f7a8b.html",
  "path": "/Users/alice/.praisonai/shares/1a2b3c4d5e6f7a8b.html"
}

❌ Session not found: sess-abc123
Use 'praisonai session list' to see available sessions

~/.praisonai/
└── shares/                        # NEW — created on first share
    └── <sha256(id)[:16]>.html

praisonai session unshare sess-abc123

✅ Unshared session: sess-abc123

ℹ No shared transcript found for: sess-abc123

{"session_id": "sess-abc123", "revoked": true}

praisonai session import my-project.json

✅ Imported session: my-project

praisonai session help

Session Commands:

  praisonai session start <name>    - Start a new session
  praisonai session list            - List all sessions
  praisonai session resume <id> [prompt]      - Resume a session, optionally with a prompt
                                --transcript  - Show transcript only (legacy view)
  praisonai session search <query> [--limit N] [--window N]  - Ranked full-text search across sessions
  praisonai session show <name> [--recap]     - Show session details (or a read-only recap)
  praisonai session handoff <id> [--json] [--copy]  - Generate a continuation prompt from durable state
  praisonai session rename <id> "<title>"     - Give a session a human-readable title ("" clears it)
  praisonai session fork <id> [--at-message N] [--title "..."]  - Fork a session into a new child timeline
  praisonai session delete <name>   - Delete a session
  praisonai session export <name> [--format md|json] [--output FILE]
                                  [--sanitise|--sanitize] [--redact-level standard|strict]  - Export a session
  praisonai session share <id> [--redact-level standard|strict]       - Publish a redacted HTML transcript (file:// link); defaults to strict
  praisonai session unshare <id>                                      - Revoke a shared transcript
  praisonai session import <file>                                     - Import a session (JSON)
  praisonai session help            - Show this help

Using Sessions with Prompts:
  praisonai "prompt" --session <name>   - Run with session context

$ praisonai run "Summarise yesterday's PRs"
... (agent output) ...
1,240 in / 3,980 out · $0.0140

$ praisonai run --continue
Session: research-bot
Model:   gpt-4o-mini
Messages restored: 12
Usage:   12,345 in / 38,902 out · $0.0140

praisonai run --continue "Add tests for the new endpoint"

# First message
praisonai "What is Python?" --session learning

# Follow-up (context preserved)
praisonai "How do I install it?" --session learning

# Another follow-up
praisonai "Show me a hello world example" --session learning

📂 Session: learning (3 messages)

╭────────────────────────────────── Response ──────────────────────────────────╮
│ Based on our conversation about Python, here's a hello world example:        │
│                                                                              │
│ ```python                                                                    │
│ print("Hello, World!")                                                       │
│ ```                                                                          │
│                                                                              │
│ After installing Python as we discussed, save this to a file called         │
│ `hello.py` and run it with `python hello.py`                                │
╰──────────────────────────────────────────────────────────────────────────────╯

# Session with memory
praisonai "Remember my preferences" --session project --memory

# Session with knowledge
praisonai "Search the docs" --session project --knowledge

# Session with planning
praisonai "Plan the implementation" --session project --planning

# Start project session
praisonai session start website-redesign

# Multiple conversations over time
praisonai "What's the current design?" --session website-redesign
praisonai "Suggest improvements" --session website-redesign
praisonai "Create implementation plan" --session website-redesign

# Create learning session
praisonai session start learn-rust

# Progressive learning
praisonai "Explain ownership in Rust" --session learn-rust
praisonai "Show me an example" --session learn-rust
praisonai "What about borrowing?" --session learn-rust

# Start review session
praisonai session start pr-review-123

# Review conversation
praisonai "Review this PR" --session pr-review-123 --fast-context ./src
praisonai "What about security concerns?" --session pr-review-123
praisonai "Summarize the review" --session pr-review-123

# Auto-save session with each interaction
praisonai "Analyze this code" --auto-save my-project

# Continue the conversation (auto-saved)
praisonai "Now refactor it" --auto-save my-project

from praisonaiagents import Agent

from praisonaiagents.config import MemoryConfig

agent = Agent(
    name="Assistant",
    memory=MemoryConfig(auto_save="my-project")  # Auto-save session after each run
)

agent.start("Analyze this code")  # Session saved automatically

# Load history from last 5 sessions
praisonai "Continue our discussion" --history 5

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    memory=True,
    context=True,  # Enable context management for history
)

# Agent now has context from previous sessions
agent.start("What did we discuss yesterday?")

from praisonaiagents import AgentFlowManager

manager = WorkflowManager()

# Execute with checkpoints (saves after each step)
result = manager.execute(
    "deploy-workflow",
    checkpoint="deploy-v1"
)

# Resume from checkpoint if interrupted
result = manager.execute(
    "deploy-workflow",
    resume="deploy-v1"
)

# List all checkpoints
checkpoints = manager.list_checkpoints()

# Delete a checkpoint
manager.delete_checkpoint("deploy-v1")

~/.praisonai/
└── checkpoints/
    ├── deploy-v1.json
    └── build-v2.json

~/.praisonai/sessions/
├── projects/
│   ├── abc12345/          # Project sessions
│   │   ├── session-def789.json
│   │   └── session-ghi012.json
│   └── xyz98765/          # Another project
│       └── session-jkl345.json
└── global/                # Legacy global sessions
    ├── old-session.json
    └── another.json

~/.praisonai/sessions/projects/{project_id}/
└── {session_id}.json

~/.praisonai/
└── memory/
    └── praison/
        └── sessions/
            ├── my-project.json
            ├── research-task.json
            └── code-review.json

# List sessions with SQLite backend
praisonai session list --storage-backend sqlite --storage-path ~/.praisonai/sessions.db

# List sessions with Redis backend (for distributed systems)
praisonai session list --storage-backend redis://localhost:6379

# List sessions with file backend (default)
praisonai session list --storage-backend file --storage-path ~/.praisonai/sessions

# Terminal 1: keep the TUI open on a session
praisonai tui launch --session my-project

# Terminal 2: same session, ad-hoc message via --interactive
praisonai "Add a one-line summary" --interactive --session my-project

# Both messages end up in ~/.praisonai/sessions/my-project.json
# in arrival order — no silent drops.

# Windows (PowerShell)
praisonai session start my-project
praisonai "Analyze this file" --session my-project

# Same commands work identically on macOS / Linux