> ## 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.
# Search Sessions
> Ranked full-text search across past session transcripts from the terminal
Search every stored session transcript from the terminal โ ranked by relevance, with a snippet centred on each match.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Ranked Session Search"
Q[๐ฌ Query] --> S[๐๏ธ SqliteSessionStore]
S --> R{๐ฏ FTS5 + bm25}
R --> D[๐งน Cross-store dedup]
D --> O[๐ Ranked results + snippets]
end
classDef query fill:#8B0000,stroke:#7C90A0,color:#fff
classDef store fill:#189AB4,stroke:#7C90A0,color:#fff
classDef rank fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef result fill:#10B981,stroke:#7C90A0,color:#fff
class Q query
class S store
class R,D rank
class O result
```
## Quick Start
An agent recalls past sessions through the `session_search` tool โ the CLI reaches the **same engine** from your terminal.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="recall-agent",
instructions="Search past sessions when the user asks about earlier decisions.",
tools=["session_search"],
)
agent.start("What did we decide about the billing migration?")
```
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai session search "billing migration"
```
Prints a table of matching sessions ranked by score, each with a snippet centred on the match:
```
Search: billing migration
โโโโโโโโโโโโโโโโโโโโโโโโณโโโโโโโโโโโโโโโโโโณโโโโโโโโณโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโณโโโโโโโโโโโโโโโโโโโโ
โ ID โ Title โ Score โ Snippet โ When โ
โกโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฉ
โ zeta โ Zeta โ 5.0 โ we need a billing migration migration migrโฆ โ 2026-06-10T14:32โฆ โ
โ alpha โ Alpha โ 2.0 โ one mention of migration here โ 2026-06-09T11:04โฆ โ
โโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโดโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโ
```
An empty result prints:
```
No sessions matched: billing migration
```
Return more sessions and more context around each hit:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai session search "billing migration" --limit 10 --window 8
```
Add the global `--json` flag for a structured result:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai --json session search "billing migration"
```
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
"query": "billing migration",
"results": [
{
"session_id": "zeta",
"title": "Zeta",
"when": "2026-06-10T14:32:00Z",
"snippet": "we need a billing migration migration migrโฆ",
"score": 5.0,
"anchor_index": 12,
"messages": [
{"index": 11, "role": "user", "content": "...", "timestamp": "..."},
{"index": 12, "role": "assistant", "content": "...", "timestamp": "..."}
]
}
]
}
```
Each result is `SessionHit.as_dict()` โ the same shape as the [Cross-Session Recall Discovery return](/docs/features/cross-session-recall#return-shapes).
***
## How It Works
`session search` delegates to `SqliteSessionStore` โ the same FTS5/bm25 engine as the `session_search` agent tool โ instead of a substring scan.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant CLI as praisonai CLI
participant Stores as canonical_cli_stores()
participant Sqlite as SqliteSessionStore
User->>CLI: session search "billing migration"
CLI->>Stores: enumerate project + global stores
loop Each store
CLI->>Sqlite: SqliteSessionStore(session_dir=โฆ)
Sqlite-->>CLI: hits with FTS5/bm25 score + snippet
end
CLI->>CLI: collapse duplicates by session_id (keep higher score)
CLI->>CLI: sort by (score, when) desc, truncate to --limit
CLI-->>User: table (or JSON) of ranked hits
```
The command iterates the CLI's canonical stores via `canonical_cli_stores()` โ the same helper `session resume` / `show` / `delete` / `export` use โ so id resolution stays consistent across every sub-command. See [Session Resume](/docs/cli/session-resume).
| Step | What happens |
| ----------------- | ----------------------------------------------------------------------------------------- |
| Enumerate stores | Walks the project-scoped store then the global default store via `canonical_cli_stores()` |
| Index per store | Opens a `SqliteSessionStore(session_dir=โฆ)` and runs `search(query, limit, window)` |
| Rank | FTS5/bm25 scoring with snippets and lineage dedup, applied inside each store |
| Cross-store dedup | Collapses duplicate `session_id`s across stores, keeping the higher-scoring copy |
| Sort & truncate | Sorts by `(score desc, when desc)` and keeps the top `--limit` hits |
### Cross-store dedup
A session resumed from the global default store keeps a project-side shadow, so the **same id** can match in both canonical stores. Without dedup those duplicate rows each consume a slot of `--limit` and crowd out distinct sessions. The command collapses by `session_id`, keeping the higher-scoring copy โ mirroring the lineage dedup the store already applies inside a single directory.
Search never breaks: if a store can't be indexed, that store is skipped and the remaining hits are still returned.
***
## Flags
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai session search [--limit/-n N] [--window/-w N]
```
| Argument / Flag | Type | Default | Description |
| ----------------- | ---------------------------- | ------- | ----------------------------------------------------------- |
| `query` | `str` (positional, required) | โ | Free-text query to search across session transcripts |
| `--limit`, `-n` | `int` | `5` | Maximum number of matching sessions to return |
| `--window`, `-w` | `int` | `5` | Number of messages to include around each hit |
| `--json` (global) | flag | off | Print `{"query": ..., "results": [...]}` instead of a table |
**Text mode** prints a table with columns `ID | Title | Score | Snippet | When`. **JSON mode** prints `{"query": "...", "results": [...]}` where each result is `SessionHit.as_dict()`.
***
## Common Patterns
### From an agent tool to the terminal
The `session_search` agent tool and `praisonai session search` share the same store โ pick whichever fits your workflow.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Same engine (SqliteSessionStore / FTS5+bm25) โ from the terminal:
praisonai session search "billing migration" --limit 5 --window 5
```
### Pipe JSON into a script
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai --json session search "auth refactor" \
| jq -r '.results[] | "\(.score)\t\(.session_id)\t\(.snippet)"'
```
### Resume the top hit
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
SID=$(praisonai --json session search "billing migration" | jq -r '.results[0].session_id')
praisonai session resume "$SID"
```
***
## Best Practices
Start with the default `--window 5`. Widen only when you need more surrounding context after finding the right session โ then `session resume` it.
Scores are FTS5/bm25 ranks, not probabilities. A `5.0` beats a `2.0`, but says nothing absolute โ read the snippets to confirm the match.
Cross-store dedup collapses same-id shadows, but distinct sessions on the same topic still compete for slots. Raise `--limit` when a topic spans many sessions.
The `--json` output is `SessionHit.as_dict()` per result โ pipe it into `jq` to feed ids straight into `session resume`, `show`, or `export`.
***
## Related
List, resume, show, delete, export, and share sessions
Continue a session with full state restored
The same engine as an agent tool (`session_search`)
SqliteSessionStore โ FTS5 + bm25 recall index