project-session-reader

List, search, and read Synapse agent sessions from another project's .synapse SQLite databases.

7|2|Updated Jul 21, 2026
One-click install
npx skills add https://github.com/alex8224/synapse-agent --skill project-session-reader-alex8224
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: project-session-reader
Source: https://github.com/alex8224/synapse-agent/tree/main/skills/project-session-reader
Command: npx skills add https://github.com/alex8224/synapse-agent --skill project-session-reader-alex8224

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? The built-in session tools only access the current workspace's own .synapse directory, so you cannot inspect conversation history belonging to a different project. This Skill reads sessions from any specified project's .synapse SQLite databases, enabling cross-project history lookup, search, and transcript review. ## Core Features & Use Cases - List recent sessions: Enumerate recent sessions of any project with title, model, summary, and timestamps from sessions.sqlite. - Search sessions: Search by title, summary, or model metadata, with optional full-text search over message bodies backed by a lazily synced search index. - Read transcripts with pagination: Read a session by thread_id with turn-based pagination (offset/limit), optional tool-call inclusion, and per-turn truncation to control output size. - Use Case: You want to find how a database migration was discussed in project F:\work\foo. Run the search command with --fulltext against that project's path, get the matching thread_id, then read the relevant turns of that session. ## Quick Start Ask the agent to list the recent sessions of the project at a given absolute path, for example: list the last 20 sessions of the project at F:\work\foo.

Frequently Asked Questions about project-session-reader

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I read sessions from another project's .synapse directory?▼

Run the helper script with the target project's absolute path so the database paths point to that project's .synapse folder. The built-in search_session and read_session tools only access the current workspace, so a script with explicit paths is required.

How to full-text search Synapse session messages?▼

Use the search mode with the --fulltext flag, which lazily syncs a search index from checkpoints.sqlite and matches message bodies. By default only the most recent 50 sessions are indexed; increase coverage with --max-sync=N.

Why does full-text search miss some sessions?▼

The search index is synced lazily and only covers the most recent 50 sessions by default, so older sessions may not be indexed. Re-run the search with a larger --max-sync value to expand coverage.

Can I read a large session transcript without dumping everything?▼

Yes, the read mode returns only the last 5 turns by default and supports max_turns, offset, and limit parameters for pagination. The --all flag dumps the full transcript but should only be used when explicitly requested.

Does reading another project's sessions modify its data?▼

Constructing the SessionStore may run an idempotent compatibility migration that adds columns to an older sessions.sqlite, which writes to the target project. For strict read-only access, copy the database files to a temporary directory first.