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.