### Install Recall Skill

Source: https://github.com/arjunkmrm/recall/blob/main/README.md

Install the Recall skill using npx. After installation, you can use the `/recall` command in Claude Code, Codex, or pi, or ask your agent to find past sessions.

```bash
npx skills add arjunkmrm/recall
```

--------------------------------

### Example Session Log

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/session-formats.md

A complete example demonstrating the sequence of entries in a Pi session log file, including session header, user messages, assistant responses, and other entry types.

```json
{"type": "session", "version": 3, "id": "019dfd8d-da36-7552-b0d5-dfa08528cf9b", "timestamp": "2026-05-06T13:50:25.335Z", "cwd": "/Users/alice/Vaults/blog"}
{"type": "message", "id": "u1", "parentId": null, "timestamp": "2026-05-06T13:52:11.384Z", "message": {"role": "user", "content": "Let's do a spring cleaning."}}
{"type": "message", "id": "a1", "parentId": "u1", "timestamp": "2026-05-06T13:52:12.000Z", "message": {"role": "assistant", "content": [{"type": "thinking", "thinking": "I should reason about this."}, {"type": "text", "text": "I will help you clean up."}]}
{"type": "custom", "id": "c1", "parentId": "a1", "customType": "my-extension"}
{"type": "message", "id": "u2", "parentId": "c1", "timestamp": "2026-05-06T13:52:20.000Z", "message": {"role": "user", "content": "second turn"}}
```

--------------------------------

### Session Metadata Example

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/types.md

An example of a session metadata dictionary. This shows the expected format and data types for each field.

```python
metadata = {
    'session_id': '0a1b2c3d-4e5f-6g7h-8i9j-0k1l2m3n4o5p',
    'source': 'claude',
    'file_path': '/Users/alice/.claude/projects/myproject/.sessionid.jsonl',
    'project': '/Users/alice/myproject',
    'slug': '2026-07-09-0a1b2c3d',
    'timestamp': 1752048000000  # 2026-07-09 in ms
}
```

--------------------------------

### FTS5 Prefix Query Example

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Use prefix queries to match terms that start with a specific string. This is applied after tokenization and is slower than exact matching.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "buffer*"
```

--------------------------------

### CLI Usage Examples

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/api-reference-read_session.py.md

Illustrates how to run the `read_session.py` script from the command line for JSON output, pretty-print output, and piping to `jq`.

```bash
# JSON output (default)
python3 ~/.claude/skills/recall/scripts/read_session.py /path/to/session.jsonl

# Pretty-print
python3 ~/.claude/skills/recall/scripts/read_session.py /path/to/session.jsonl --pretty

# Pipe to jq for further processing
python3 ~/.claude/skills/recall/scripts/read_session.py session.jsonl | jq '.[] | select(.role == "user") | .text'
```

--------------------------------

### Claude Code Session Example

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/session-formats.md

A complete example demonstrating a user message and an assistant response within the Claude Code session format. It includes essential fields like UUIDs and timestamps.

```json
{"type": "user", "uuid": "u1", "parentUuid": null, "timestamp": "2026-07-09T10:00:00.000Z", "cwd": "/Users/alice/myproject", "message": {"content": "What's the state machine?"}}
{"type": "assistant", "uuid": "a1", "parentUuid": "u1", "timestamp": "2026-07-09T10:00:01.000Z", "message": {"content": [{"type": "text", "text": "A state machine is a model..."}]}}
```

--------------------------------

### FTS5 OR Query Example

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Matches documents containing any of the specified terms. Keywords must be uppercase.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "tauri OR electron"
```

--------------------------------

### Message Tuple Example

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/types.md

An example of a list of conversational messages, represented as tuples of (role, text). This format is used for storing and processing chat history.

```python
messages = [
    ("user", "What does this code do?"),
    ("assistant", "This code implements a state machine."),
    ("user", "How would you optimize it?"),
]
```

--------------------------------

### Search Sessions by Criteria

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/examples.md

Find sessions matching specific criteria, such as a feature, project, and time range. This example searches for 'user authentication' in the '~/webapp' project within the last 14 days, limiting results to 10.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py '"user authentication"' \
  --project ~/webapp \
  --days 14 \
  --limit 10
```

--------------------------------

### Example Pretty-Print Output

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/api-reference-read_session.py.md

Shows the human-readable output format when the --pretty flag is used. Each message includes a role header and truncated text.

```text
---
--- user ---
Let's implement a state machine.

--- assistant ---
I'll start by defining the states and transitions. Here's a Python
...
```

--------------------------------

### Example JSON Output

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/api-reference-read_session.py.md

Demonstrates the default JSON array format for session messages, with each message containing a 'role' and 'text' field.

```json
[
  {
    "role": "user",
    "text": "Let's implement a state machine."
  },
  {
    "role": "assistant",
    "text": "I'll start by defining the states and transitions..."
  }
]
```

--------------------------------

### Example of Legacy Format Session Log

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/session-formats.md

A sample log demonstrating a sequence of entries in the legacy Codex session format, showing how metadata and messages were structured.

```json
{"timestamp": "2026-07-09T10:00:00.000Z", "id": "session-abc123", "instructions": {"role": "user"}, "cwd": "/Users/alice/project"}
{"timestamp": "2026-07-09T10:00:01.000Z", "role": "user", "content": "What's the state machine?"}
{"timestamp": "2026-07-09T10:00:02.000Z", "role": "assistant", "content": [{"type": "text", "text": "A state machine..."}]}
```

--------------------------------

### Example of Current Format Session Log

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/session-formats.md

A sample log demonstrating a sequence of entries in the current Codex session format, including metadata and user/assistant messages.

```json
{"timestamp": "2026-07-09T10:00:00.000Z", "type": "session_meta", "payload": {"id": "session-abc123", "cwd": "/Users/alice/project"}}
{"timestamp": "2026-07-09T10:00:01.000Z", "type": "response_item", "payload": {"role": "user", "content": "What's the state machine?"}}
{"timestamp": "2026-07-09T10:00:02.000Z", "type": "response_item", "payload": {"role": "assistant", "content": [{"type": "text", "text": "A state machine..."}]}}
```

--------------------------------

### Prefix search

Source: https://github.com/arjunkmrm/recall/blob/main/SKILL.md

Finds terms that start with a specified prefix, useful for matching variations of a word.

```bash
# Prefix search
python3 ~/.claude/skills/recall/scripts/recall.py "buffer*"
```

--------------------------------

### List Result Example

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/types.md

Demonstrates the structure of a SearchResult tuple when used in list mode, where the excerpt is empty and the rank is 0.0.

```python
result = (
    '0a1b2c3d-4e5f-6g7h-8i9j-0k1l2m3n4o5p',  # session_id
    'claude',                                   # source
    '/Users/alice/.claude/projects/proj/.sessionid.jsonl',  # file_path
    '/Users/alice/proj',                       # project
    '2026-07-09-0a1b2c3d',                     # slug
    1752048000000,                             # timestamp (ms)
    '',                                        # excerpt (empty in list mode)
    0.0                                        # rank (0.0 in list mode)
)
```

--------------------------------

### Search Result Example

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/types.md

Illustrates the structure of a SearchResult tuple as returned by a search operation, including session ID, source, file path, project, slug, timestamp, excerpt, and rank.

```python
result = (
    '0a1b2c3d-4e5f-6g7h-8i9j-0k1l2m3n4o5p',  # session_id
    'claude',                                   # source
    '/Users/alice/.claude/projects/proj/.sessionid.jsonl',  # file_path
    '/Users/alice/proj',                       # project
    '2026-07-09-0a1b2c3d',                     # slug
    1752048000000,                             # timestamp (ms)
    '**state** machine implementation...',    # excerpt (with ** highlighting)
    -2.3                                       # rank (negative = better)
)
```

--------------------------------

### Find All Sessions About a Topic using SQL

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/examples.md

Retrieve all sessions related to a specific topic by executing a SQL query directly against the Recall database. This example finds sessions containing 'buffer' in their messages and orders them by timestamp.

```python
import sqlite3
from pathlib import Path

# Connect to database
conn = sqlite3.connect(str(Path.home() / ".recall.db"))

# Search for a query
results = conn.execute("""
    SELECT DISTINCT s.session_id, s.source, s.file_path, s.project, s.slug
    FROM sessions s
    INNER JOIN messages m ON s.session_id = m.session_id
    WHERE m.text LIKE '%buffer%'
    ORDER BY s.timestamp DESC
""").fetchall()

for session_id, source, file_path, project, slug in results:
    print(f"{slug} [{source}] in {project}")

conn.close()
```

--------------------------------

### FTS5 Parentheses Workaround

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Illustrates the workaround for unsupported parentheses in FTS5 by relying on operator precedence. The example shows how 'a OR b AND c' is interpreted.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "a OR b AND c"  # Same as: a OR (b AND c)
```

--------------------------------

### Find Sessions from Specific Sources

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/examples.md

Filter sessions based on their source and time frame. This example finds sessions from the 'pi' source within the last 7 days, limiting results to 50.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py --source pi --days 7 --limit 50
```

--------------------------------

### FTS5 Operator Precedence Examples

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Illustrates implicit AND, NOT, and OR precedence. Avoid ambiguous syntax like 'NOT a b'.

```text
"a b" c        →  ("a b") AND c
a OR b AND c   →  a OR (b AND c)
a AND NOT b    →  a AND (NOT b)
NOT a b        →  NOT(a) b  (ambiguous; avoid)
```

--------------------------------

### FTS5 NOT Query Example

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Matches documents containing the first term but not the second. Keywords must be uppercase.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "concurrency NOT thread"
```

--------------------------------

### String Content Format

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/session-formats.md

Example of a message entry where the content is a simple string. This is used for straightforward text messages.

```json
{
  "message": {
    "role": "user",
    "content": "hello world"
  }
}
```

--------------------------------

### Array Content (Block Format)

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/session-formats.md

Example of a message entry where the content is an array of blocks. This format allows for richer message structures, including thinking steps, text, and tool calls.

```json
{
  "message": {
    "role": "assistant",
    "content": [
      {"type": "thinking", "thinking": "Let me think..."},
      {"type": "text", "text": "Here's my response"},
      {"type": "toolCall", "id": "t1", "name": "bash", "arguments": {"cmd": "ls"}}
    ]
  }
}
```

--------------------------------

### Querying Messages Table with FTS5

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/types.md

Shows how to perform a full-text search on the 'messages' table using FTS5. This example retrieves session ID, role, and text for messages matching a given query.

```sql
conn.execute("SELECT session_id, role, text FROM messages WHERE messages MATCH ?", (query,))
```

--------------------------------

### Boolean Complexity - Correct Usage

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Demonstrates a complex boolean query structure using parentheses for clarity, though FTS5 does not directly support parentheses. This example shows the intended logic.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "rust AND (async OR concurrency) NOT thread"
```

--------------------------------

### FTS5 CJK Query with Short Input

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

For CJK queries with fewer than 3 characters, FTS5 falls back to using LIKE for matching. This example demonstrates a 2-character query.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "issue化"  # 2 chars, uses LIKE
```

--------------------------------

### Combine Filters

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/examples.md

Combine multiple filters to refine search results. This example searches for 'buffer' within Claude Code sessions from the last 7 days in the '~/myproject' project, limiting results to 5.

```bash
# Search in last 7 days within a specific Claude Code project
python3 ~/.claude/skills/recall/scripts/recall.py "buffer" \
  --source claude \
  --project ~/myproject \
  --days 7 \
  --limit 5
```

--------------------------------

### Claude Code Format Array Content Example

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/session-formats.md

Shows how a message with multiple content blocks, including text and tool calls, is structured in the Claude Code session format. This allows for richer message content.

```json
{
  "message": {
    "content": [
      {"type": "text", "text": "Here's the first part"},
      {"type": "toolCall", "id": "t1", "name": "bash", "arguments": {"cmd": "ls"}},
      {"type": "text", "text": "And the second part"}
    ]
  }
}
```

--------------------------------

### Querying Messages CJK Table with FTS5

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/types.md

Demonstrates how to perform a full-text search on the 'messages_cjk' table, optimized for CJK characters using trigram indexing. This example retrieves session ID, role, and text for messages matching a query.

```sql
conn.execute("SELECT session_id, role, text FROM messages_cjk WHERE messages_cjk MATCH ?", (query,))
```

--------------------------------

### main()

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/api-reference-recall.py.md

The main entry point for the Recall CLI. Parses arguments, initializes the database, indexes sessions, and performs searches or lists sessions.

```APIDOC
## `main()`

### Description
Parses command-line arguments, initializes the database, indexes sessions, and performs searches or lists sessions.

### Signature
```python
def main() -> None
```

### Parameters
None. Reads from `sys.argv`.

### CLI Arguments
```
recall.py [QUERY] [--project PATH] [--days N] [--source claude|codex|pi] [--limit N] [--reindex]
```

| Argument | Type | Default | Description |
|----------|------|---------|-------------|
| query | str (positional) | None | Optional search query (omit for list mode) |
| --project | str | None | Project path prefix filter |
| --days | int | None | Time window in days |
| --source | str | None | Filter by source: "claude", "codex", or "pi" |
| --limit | int | 10 | Maximum results |
| --reindex | flag | False | Force full rebuild of index |

### Behavior
1. Parse arguments
2. Call `migrate_db_location()` to upgrade old database path if needed
3. Open (or create) `~/.recall.db` with restrictive permissions (0o600)
4. Set WAL journal mode and NORMAL synchronous mode for speed
5. Call `create_schema()` and `migrate_schema()`
6. Call `index_sessions()` (with `force=True` if `--reindex`)
7. If query provided, call `search()`; else call `list_sessions()`
8. Print header with result count and database stats
9. Print each result with index, date, slug, project, session ID, file path, and excerpt
10. Close connection

### Output Format
```
Found N sessions (index: M sessions, K messages):

[1] 2026-07-09 | 2026-07-09-abc12345 | project-name [claude]
    /path/to/project
    ID: 0a1b2c3d-4e5f-6g7h-8i9j-0k1l2m3n4o5p
    File: /Users/alice/.claude/projects/project/.sessionid.jsonl
    > snippet of the best-matching message...

[2] 2026-07-08 | 2026-07-08-def67890 | other-project [codex]
    ...
```

### Example
```bash
# List sessions from the last 7 days
python3 ~/.claude/skills/recall/scripts/recall.py --days 7

# Search for a keyword
python3 ~/.claude/skills/recall/scripts/recall.py "buffer"

# Phrase search with filters
python3 ~/.claude/skills/recall/scripts/recall.py '"state machine"' --source claude --days 30 --limit 5

# Force reindex
python3 ~/.claude/skills/recall/scripts/recall.py --reindex "test"
```
```

--------------------------------

### Index Tuple Definition and Example

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/types.md

Defines the `IndexStats` type as a tuple of integers representing indexing statistics. The example shows how to unpack the tuple returned by `index_sessions()` and interprets the meaning of each value.

```python
IndexStats = tuple[int, int, int, int]
```

```python
indexed, skipped, total_sessions, total_messages = index_sessions(conn)
# indexed=5, skipped=23, total_sessions=28, total_messages=1247
# Meaning: 5 new/modified files, 23 unchanged, 28 total sessions, 1247 messages
```

--------------------------------

### Create Database Schema

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/database-schema.md

Initializes the database by creating necessary tables for sessions and messages. Uses `CREATE VIRTUAL TABLE` for FTS5 indexing with different tokenizers.

```python
def create_schema(conn):
    conn.executescript("""
        CREATE TABLE IF NOT EXISTS sessions (
            session_id TEXT PRIMARY KEY,
            source TEXT,
            file_path TEXT,
            project TEXT,
            slug TEXT,
            timestamp INTEGER,
            mtime REAL
        );

        CREATE VIRTUAL TABLE IF NOT EXISTS messages USING fts5(
            session_id UNINDEXED,
            role,
            text,
            tokenize='porter unicode61'
        );

        CREATE VIRTUAL TABLE IF NOT EXISTS messages_cjk USING fts5(
            session_id UNINDEXED,
            role,
            text,
            tokenize='trigram'
        );
    """)
```

--------------------------------

### Find Implementation Details

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Search for implementation details using wildcard and boolean operators.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "struct* AND field*"
```

--------------------------------

### Backup Recall Database (Simple)

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/database-schema.md

Use this command to create a simple backup of the main database file. Ensure no Recall processes are running during the copy.

```bash
# Simple file copy (while no recall process is running)
cp ~/.recall.db ~/.recall.db.backup
```

--------------------------------

### Indexing Pipeline Flow

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/overview.md

Illustrates the steps involved in indexing session transcripts, from file discovery to database insertion and optimization.

```text
Discover files (glob)
       ↓
Check mtime (skip unchanged)
       ↓
Parse session (format-specific parser)
       ↓
Extract metadata (session_id, project, timestamp, source)
       ↓
Extract messages (user/assistant only; skip tools, thinking, images)
       ↓
Insert into FTS tables
    â–ª messages (Porter + unicode61)
    â–ª messages_cjk (trigram)
       ↓
Commit and optimize
```

--------------------------------

### create_schema(conn)

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/api-reference-recall.py.md

Initializes an empty FTS5 database with all required tables. It is safe to call multiple times due to the `IF NOT EXISTS` clause.

```APIDOC
## create_schema(conn)

### Description
Initializes an empty FTS5 database with all required tables.

### Signature
```python
def create_schema(conn: sqlite3.Connection) -> None
```

### Parameters
#### Path Parameters
- **conn** (sqlite3.Connection) - Required - Open database connection

### Behavior
Executes SQL to create:
1. **sessions** relational table with columns: session_id, source, file_path, project, slug, timestamp, mtime
2. **messages** FTS5 virtual table (Porter stemming + unicode61 tokenizer) with columns: session_id, role, text
3. **messages_cjk** FTS5 virtual table (trigram tokenizer) with columns: session_id, role, text

### Idempotent
Uses `IF NOT EXISTS` clause, safe to call multiple times.

### Example
```python
import sqlite3

conn = sqlite3.connect(":memory:")  # or "/path/to/recall.db"
create_schema(conn)
# Tables are now ready for use
```
```

--------------------------------

### Implementation Patterns Search

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Use prefix matching with the AND operator to find variations of related terms, such as 'pattern' and 'implementation'. This broadens the search to include related concepts.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "pattern* AND implement*"
```

--------------------------------

### Configure SQLite Connection Settings

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/database-schema.md

Establishes a SQLite connection, sets journal mode to WAL for concurrent access, and synchronous mode to NORMAL for a balance of speed and safety. Includes schema creation and migration steps.

```python
import sqlite3

# Connect (creates DB if missing)
conn = sqlite3.connect(str(DB_PATH))

# Set journal mode (WAL for concurrent access)
conn.execute("PRAGMA journal_mode=WAL")

# Set synchronous mode (NORMAL for speed + safety balance)
conn.execute("PRAGMA synchronous=NORMAL")

# Create schema if new
create_schema(conn)

# Migrate if upgrading
migrate_schema(conn)

# Use the connection...

# Close
conn.close()
```

--------------------------------

### Index Sessions Incrementally and Force Rebuild

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/api-reference-recall.py.md

Demonstrates how to use the `index_sessions` function for both incremental indexing, which skips unchanged files, and a full rebuild when `force=True`. Requires an active SQLite database connection.

```python
import sqlite3
from pathlib import Path

conn = sqlite3.connect(str(Path.home() / ".recall.db"))

# Incremental index (skip unchanged files)
indexed, skipped, total_sessions, total_messages = index_sessions(conn)
print(f"Indexed {indexed}, skipped {skipped}")
print(f"Database: {total_sessions} sessions, {total_messages} messages")

# Force full rebuild
indexed, skipped, total_sessions, total_messages = index_sessions(conn, force=True)

conn.close()
```

--------------------------------

### FTS5 Queries Requiring Escaping

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Examples of FTS5 queries that contain hyphens and thus require sanitization to avoid misinterpretation by the FTS5 parser.

```bash
ask-codex              # hyphenated word
user-facing            # hyphenated adjective
foo-bar-baz            # multiple hyphens
```

--------------------------------

### FTS5 Special Symbol Handling

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Explains how special symbols are treated as word delimiters in FTS5, not indexed separately. The example shows '@mention' indexing 'mention'.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "@mention"  # Indexes "mention" (@ is delimiter)
```

--------------------------------

### Create Recall Database Schema

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/api-reference-recall.py.md

Initializes an empty FTS5 database with the necessary tables for sessions and messages. Uses `IF NOT EXISTS` for idempotency, making it safe to call multiple times.

```python
import sqlite3

conn = sqlite3.connect(":memory:")  # or "/path/to/recall.db"
create_schema(conn)
# Tables are now ready for use
```

--------------------------------

### FTS5 Safe Queries (Pass Through)

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Examples of FTS5 queries that do not require sanitization and are passed through unchanged. These include quoted phrases, prefix searches, and boolean operations.

```bash
"exact phrase"         # quoted phrase
buffer*                # prefix
a AND b                # boolean
NOT deprecated         # not operator
```

--------------------------------

### Claude Code Format String Content Example

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/session-formats.md

Illustrates how a simple text message is represented within the Claude Code session format. The content is a single string.

```json
{
  "message": {
    "content": "What does this code do?"
  }
}
```

--------------------------------

### FTS5 CJK Query with Sufficient Length

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Queries with 3 or more characters containing CJK characters are processed using FTS5 trigram tokenization. This example uses a 4-character Japanese phrase.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "状態機械"  # 4 chars, uses FTS5
```

--------------------------------

### List Sessions with Time Window

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/api-reference-recall.py.md

Use the Recall CLI to list indexed sessions within a specified number of past days. Requires Python 3 execution.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py --days 7
```

--------------------------------

### Use Specific Queries

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/examples.md

Formulate precise queries to enhance search performance. Specific phrases are generally faster than broad terms.

```bash
echo "\"state machine\" is faster than just \"state\""
```

--------------------------------

### Define FTS5 Virtual Table with Tokenizer

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/types.md

Example of creating an FTS5 virtual table for messages, specifying the 'porter unicode61' tokenizer for English/ASCII text. This is used within the database schema.

```sql
CREATE VIRTUAL TABLE messages USING fts5(
    session_id UNINDEXED,
    role,
    text,
    tokenize='porter unicode61'
);
```

--------------------------------

### Parse CLI Arguments with Argparse

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/types.md

Demonstrates setting up an argument parser to handle various command-line options for the recall script, including positional arguments, filters, and flags.

```python
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("query", nargs="?")
parser.add_argument("--project")
parser.add_argument("--days", type=int)
parser.add_argument("--source", choices=["claude", "codex", "pi"])
parser.add_argument("--limit", type=int, default=10)
parser.add_argument("--reindex", action="store_true")
args = parser.parse_args()
# args.query, args.project, args.days, args.source, args.limit, args.reindex
```

--------------------------------

### Recall CLI Main Entry Point

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/overview.md

The main function for the recall CLI. It parses command-line arguments, triggers indexing if needed, and performs searches.

```python
def main():
    # CLI entry point; parse args, index, and search
    pass
```

--------------------------------

### Read Session CLI Main Entry Point

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/overview.md

The main function for the read_session CLI. It handles file input and options for displaying session data.

```python
def main():
    # CLI entry point for displaying a session
    pass
```

--------------------------------

### Programmatic Access to Recall

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/README.md

Demonstrates how to use the Recall library for indexing sessions and performing searches programmatically. Requires an SQLite database connection.

```python
import sqlite3
from pathlib import Path
from recall import search, index_sessions

conn = sqlite3.connect(str(Path.home() / ".recall.db"))
index_sessions(conn)  # incremental index
results = search(conn, "buffer", limit=10)
for session_id, source, file_path, project, slug, timestamp, excerpt, rank in results:
    print(f"{slug}: {excerpt}")
conn.close()
```

--------------------------------

### List Sessions from a Project

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/README.md

Retrieve a list of sessions associated with a particular project, with an option to limit the number of results.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py --project ~/myproject --limit 20
```

--------------------------------

### Initialize FTS5 Database

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/overview.md

Creates the necessary schema for an empty FTS5 database. This function is used to set up the database structure.

```python
def create_schema(conn):
    # Initialize empty FTS5 database
    pass
```

--------------------------------

### Perform a Simple Search

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/examples.md

Execute a basic search query to test functionality. This is useful when complex queries yield no results.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "test"
```

--------------------------------

### Filter by Project Path

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/configuration.md

Limit search results to sessions originating from a specific project directory. This uses a prefix match against the project column.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "test" --project ~/myproject
```

```bash
python3 ~/.claude/skills/recall/scripts/recall.py --project /Users/alice/work --days 7
```

--------------------------------

### Resume a Found Session

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/README.md

After finding a session ID, you can resume it using various command-line tools like 'claude', 'codex', or 'pi'. Navigate to your project directory first.

```bash
cd /path/to/project
claude --resume SESSION_ID                 # Claude Code
codex resume SESSION_ID                    # Codex
pi --session SESSION_ID                    # pi
```

--------------------------------

### Backup Recall Database (with WAL)

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/database-schema.md

Back up the main database file along with its Write-Ahead Logging (WAL) and Shared Memory (SHM) files. This provides a more complete backup, especially if transactions are in progress.

```bash
# Or with WAL files
cp ~/.recall.db ~/.recall.db.backup
cp ~/.recall.db-wal ~/.recall.db.backup-wal
cp ~/.recall.db-shm ~/.recall.db.backup-shm
```

--------------------------------

### Recall Query Process

Source: https://github.com/arjunkmrm/recall/blob/main/README.md

This diagram outlines the query process for Recall, showing how user queries are processed, CJK language detection is performed, and results are ranked using FTS5, BM25, and a recency boost before being presented.

```text
  Query ──▶ Detect CJK? ──▶ FTS5 Match ──▶ BM25 rank ──▶ Recency boost ──▶ Results
                │                           [half-life: 30 days]
                │
          ┌─────┴──────┐
          │            │
     No CJK        Has CJK
     porter         trigram
     unicode61      table
          │            │
          └─────┬──────┘
                ▼
         snippet extraction
         highlighted excerpts
```

--------------------------------

### Filter by Project

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/examples.md

Filter search results by project. Use `--project` followed by the project path. This can be an exact path or a prefix match for directory trees. You can also list all sessions from a project without a search query.

```bash
# Search within a specific project
python3 ~/.claude/skills/recall/scripts/recall.py "state machine" --project ~/myproject
```

```bash
# Search within a directory tree (prefix match)
python3 ~/.claude/skills/recall/scripts/recall.py "bug" --project /Users/alice/work
```

```bash
# List all sessions from a project (no search)
python3 ~/.claude/skills/recall/scripts/recall.py --project ~/myproject --limit 20
```

--------------------------------

### Integrate Recall Indexing and Searching into Python

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/examples.md

Programmatically index sessions and perform searches using the Recall Python API. This snippet demonstrates connecting to the database, performing an incremental index, and executing a search query.

```python
import sqlite3
from pathlib import Path
import sys

# Add scripts directory to path
sys.path.insert(0, str(Path.home() / ".claude" / "skills" / "recall" / "scripts"))
from recall import search, parse_pi_session, index_sessions

# Open database
conn = sqlite3.connect(str(Path.home() / ".recall.db"))

# Index (incremental)
indexed, skipped, total_sessions, total_messages = index_sessions(conn)
print(f"Indexed {indexed}, skipped {skipped}")

# Search
results = search(conn, "buffer", limit=10)
for session_id, source, file_path, project, slug, timestamp, excerpt, rank in results:
    print(f"{slug} [{source}]: {excerpt[:100]}")

conn.close()
```

--------------------------------

### Rebuild Recall Database from Scratch

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/database-schema.md

If the database is corrupted, remove the existing database files and use the --reindex flag to rebuild the entire index from original session files. This process recreates the database.

```bash
# Remove the database
rm ~/.recall.db ~/.recall.db-wal ~/.recall.db-shm

# Run recall with --reindex to rebuild
python3 ~/.claude/skills/recall/scripts/recall.py --reindex "test"
```

--------------------------------

### Search with Stop Words and Context

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Demonstrates how to work around stop word limitations by including indexed words in the search query. This ensures results are returned even if stop words are present.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "the state"  # "state" is indexed
```

--------------------------------

### Verify Database Content

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/examples.md

Use this command to check if your database contains any sessions. It limits the output to 10 sessions.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py --limit 10
```

--------------------------------

### Read Session Data (CLI)

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/configuration.md

Use this command to read and display session data from a .jsonl file. The --pretty flag changes the output format.

```bash
python3 ~/.claude/skills/recall/scripts/read_session.py /path/to/session.jsonl
```

```bash
python3 ~/.claude/skills/recall/scripts/read_session.py session.jsonl --pretty
```

```bash
python3 ~/.claude/skills/recall/scripts/read_session.py session.jsonl  # JSON
```

--------------------------------

### Create sessions Table

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/database-schema.md

Defines the 'sessions' table to store metadata for each indexed session, including session ID, source, file path, project, slug, and timestamps. Use this to create the primary table for session information.

```sql
CREATE TABLE IF NOT EXISTS sessions (
    session_id TEXT PRIMARY KEY,
    source TEXT,
    file_path TEXT,
    project TEXT,
    slug TEXT,
    timestamp INTEGER,
    mtime REAL
)
```

--------------------------------

### Accessing Sessions Table Data via SQL

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/types.md

Demonstrates how to retrieve all columns from the 'sessions' table using a SQL SELECT statement. This is useful for accessing session metadata like ID, source, file path, project, slug, timestamp, and modification time.

```sql
conn.execute("SELECT session_id, source, file_path, project, slug, timestamp, mtime FROM sessions")
```

--------------------------------

### Count Messages and Sessions by Source

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/database-schema.md

Calculate the number of messages and distinct sessions for each source. Uses a LEFT JOIN to include sources with no messages.

```sql
-- How many messages per source?
SELECT 
    s.source,
    COUNT(*) AS message_count,
    COUNT(DISTINCT s.session_id) AS session_count
FROM sessions s
LEFT JOIN messages m ON s.session_id = m.session_id
GROUP BY s.source;
```

--------------------------------

### Prefix Queries Performance

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/examples.md

Be aware that prefix queries, like using a wildcard at the end of a term, can be slower than exact matches.

```bash
echo "buffer* is slower than exact queries"
```

--------------------------------

### Run Recall Unit Tests

Source: https://github.com/arjunkmrm/recall/blob/main/README.md

Execute the unit tests for the Recall skill using Python's built-in unittest module. This command discovers and runs tests verbosely.

```bash
python3 -m unittest discover tests -v
```

--------------------------------

### Search Across Languages

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Perform keyword searches in English, Japanese, and Chinese.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "error*"         # English
```

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "エラー"         # Japanese
```

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "错误"          # Chinese
```

--------------------------------

### Filter search by project and recency

Source: https://github.com/arjunkmrm/recall/blob/main/SKILL.md

Narrows down search results to a specific project directory and within a defined time frame.

```bash
# Filter by project and recency
python3 ~/.claude/skills/recall/scripts/recall.py "state machine" --project ~/my-project --days 7
```

--------------------------------

### Recall Indexing Process

Source: https://github.com/arjunkmrm/recall/blob/main/README.md

This diagram illustrates how Recall indexes conversation logs from various AI agent session directories into a SQLite FTS5 database. The indexing process is incremental and based on file modification times.

```text
  ~/.claude/projects/**/*.jsonl ──┐
                                  │
  ~/.codex/sessions/**/*.jsonl ───┼─▶ Index ──▶ ~/.recall.db (SQLite FTS5)
                                  │   [incremental - mtime-based]
  ~/.pi/agent/sessions/**/*.jsonl ┘
```

--------------------------------

### Pretty-print a Session

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/README.md

Use the read_session script to pretty-print the content of a session JSONL file.

```bash
python3 ~/.claude/skills/recall/scripts/read_session.py /path/to/session.jsonl --pretty
```

--------------------------------

### List all sessions in the last day

Source: https://github.com/arjunkmrm/recall/blob/main/SKILL.md

Lists all sessions from the last 24 hours without performing a text search. Useful for a quick overview of recent activity.

```bash
# List every session in the last day (no text search)
python3 ~/.claude/skills/recall/scripts/recall.py --days 1
```

--------------------------------

### Phrase Search with Filters using Recall CLI

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/api-reference-recall.py.md

Perform a phrase search with specific filters for source and time window, and set a limit on the number of results. Requires Python 3 execution.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py '"state machine"' --source claude --days 30 --limit 5
```

--------------------------------

### Multi-Term Search with Exclusions

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/examples.md

Perform a search using multiple terms and exclusions. This command finds discussions about 'async' and 'await' but excludes any related to 'thread*'.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "async AND await NOT thread*"
```

--------------------------------

### migrate_db_location()

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/api-reference-recall.py.md

Moves the Recall database file from the old location (~/.claude/recall.db) to the new location (~/.recall.db). This operation renames files on disk and is a no-op if the old file doesn't exist or the new file already exists.

```APIDOC
## migrate_db_location()

### Description
Move the database from old location `~/.claude/recall.db` to new location `~/.recall.db`.

### Signature
```python
def migrate_db_location() -> None
```

### Parameters
None.

### Behavior
1. Checks if `~/.claude/recall.db` exists and `~/.recall.db` does not
2. If both conditions met, renames old file to new location
3. Also renames WAL/SHM files if present (SQLite temporary files)
4. No-op if old file doesn't exist or new file already exists

### Side Effects
- Renames files on disk
- No database modifications (only filesystem operations)

### Example
```python
from scripts import recall

recall.migrate_db_location()
# If upgrading from old version, db is moved to new location
```
```

--------------------------------

### Set Database PRAGMA Settings (Python)

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/configuration.md

These Python commands set the journal mode to WAL for improved read performance and synchronous mode to NORMAL for a balance between safety and performance.

```python
conn.execute("PRAGMA journal_mode=WAL")
conn.execute("PRAGMA synchronous=NORMAL")
```

--------------------------------

### Recall Skill Usage

Source: https://github.com/arjunkmrm/recall/blob/main/SKILL.md

This is the general usage command for the recall skill. It allows specifying a query and various filters.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py [QUERY] [--project PATH] [--days N] [--source claude|codex|pi] [--limit N] [--reindex]
```

--------------------------------

### Find Discussions About a Feature

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Use exact phrases to find specific discussions and avoid stemming variations. This is useful for precise searching.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py '"user authentication"'
```

--------------------------------

### Filter Sessions by Project and Time

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/database-schema.md

Find recent sessions from a specific project within the last 7 days. Orders results by timestamp in descending order.

```sql
-- Find recent sessions from a specific project
SELECT 
    session_id,
    source,
    slug,
    timestamp
FROM sessions
WHERE 
    project LIKE '/Users/alice/myproject%' 
    AND timestamp >= (strftime('%s', 'now') - 604800) * 1000  -- last 7 days
ORDER BY timestamp DESC
LIMIT 20;
```

--------------------------------

### Find Recent Work Across All Projects

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/examples.md

List the most recent sessions across all projects. This command retrieves the 20 most recent sessions from the last day.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py --days 1 --limit 20
```

--------------------------------

### index_sessions

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/api-reference-recall.py.md

Scans session directories and indexes new or modified files incrementally into the Recall database. It can also perform a full rebuild if the `force` option is enabled.

```APIDOC
## index_sessions(conn, force=False)

### Description
Scans session directories and indexes new/modified files incrementally. If `force` is True, it deletes all existing data and rebuilds the index from scratch.

### Method
Python Function

### Parameters
#### Function Parameters
- **conn** (sqlite3.Connection) - Required - An open database connection to the Recall database.
- **force** (bool) - Optional - If True, deletes all existing data and rebuilds the index from scratch. Defaults to False.

### Returns
Tuple `(indexed, skipped, total_sessions, total_messages)`:
- **indexed** (int) - Number of new or modified files processed.
- **skipped** (int) - Number of unchanged files that were not re-indexed.
- **total_sessions** (int) - Total number of sessions in the database after indexing.
- **total_messages** (int) - Total number of messages in the database after indexing.

### Behavior
1. Fetches mtime of all indexed files from the database.
2. Globs for JSONL files in `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/`.
3. Skips unchanged files unless `force=True`.
4. Parses each file using format-specific parsers.
5. Extracts metadata and messages (user/assistant only).
6. Inserts data into FTS tables (`messages` and/or `messages_cjk`).
7. Disables FTS5 automerge during bulk insert and optimizes at the end.
8. Commits the transaction.

### Side Effects
- Modifies the database by inserting/updating sessions and messages tables.
- Prints warnings to stderr for unreadable files.
- Optimizes the FTS5 segment tree after indexing.

### Example
```python
import sqlite3
from pathlib import Path

conn = sqlite3.connect(str(Path.home() / ".recall.db"))

# Incremental index (skip unchanged files)
indexed, skipped, total_sessions, total_messages = index_sessions(conn)
print(f"Indexed {indexed}, skipped {skipped}")
print(f"Database: {total_sessions} sessions, {total_messages} messages")

# Force full rebuild
indexed, skipped, total_sessions, total_messages = index_sessions(conn, force=True)

conn.close()
```
```

--------------------------------

### Basic Search Query

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/configuration.md

Perform a full-text search using a single keyword. This triggers a search using BM25 ranking.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "buffer"
```

--------------------------------

### Find Bugs by Keyword

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Search for specific keywords within the last 30 days.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "segmentation fault" --days 30
```

--------------------------------

### FTS5 Workaround for Complex Grouping

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Demonstrates how to achieve complex logic like (a OR b) AND (c OR d) by running multiple queries and manually intersecting results, as FTS5 does not support parentheses for explicit grouping.

```bash
# Instead of: (a OR b) AND (c OR d)
# Use two queries, or restructure
python3 ~/.claude/skills/recall/scripts/recall.py "a OR b"    # first query
python3 ~/.claude/skills/recall/scripts/recall.py "c OR d"    # second query
# Manually intersect results
```

--------------------------------

### Boolean Search: AND

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/examples.md

Finds sessions that contain both specified terms. Use the AND operator for strict matching.

```bash
# Both terms required
python3 ~/.claude/skills/recall/scripts/recall.py "rust AND async"
```

--------------------------------

### Restore Recall Database from Backup

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/database-schema.md

Restore the Recall database files from a previously created backup. It is crucial to stop any running Recall processes before performing the restore operation.

```bash
# Stop any running recall processes first
cp ~/.recall.db.backup ~/.recall.db
cp ~/.recall.db.backup-wal ~/.recall.db-wal
cp ~/.recall.db.backup-shm ~/.recall.db.backup-shm
```

--------------------------------

### Filter by Source

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/examples.md

Filter search results by source type. Use `--source` followed by the source name (e.g., `claude`, `codex`, `pi`). You can also list all sessions from a specific source without a search query.

```bash
# Claude Code only
python3 ~/.claude/skills/recall/scripts/recall.py "buffer" --source claude
```

```bash
# Codex only
python3 ~/.claude/skills/recall/scripts/recall.py "buffer" --source codex
```

```bash
# Pi only
python3 ~/.claude/skills/recall/scripts/recall.py "buffer" --source pi
```

```bash
# List all pi sessions (no search)
python3 ~/.claude/skills/recall/scripts/recall.py --source pi
```

--------------------------------

### FTS5 Asterisk Matching

Source: https://github.com/arjunkmrm/recall/blob/main/_autodocs/fts5-query-syntax.md

Demonstrates the use of the asterisk for prefix matching and how to escape it to treat it as a literal character in FTS5 queries.

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "buffer*"   # Prefix match
```

```bash
python3 ~/.claude/skills/recall/scripts/recall.py "buf\*fer"  # Literal asterisk in word
```