spooling 0.2.6__tar.gz → 0.2.7__tar.gz

{spooling-0.2.6/spooling.egg-info → spooling-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spooling
-Version: 0.2.6
+Version: 0.2.7
 Summary: Local session tracker and semantic search for AI coding assistants
 Author: Parsed Analytics, Inc.
 License: MIT
@@ -56,7 +56,7 @@ No Docker, no PostgreSQL, no Node.js required.
 
 ## How it works
 
-**Four commands. Zero cloud.**
+**Three steps. Local by default.**
 
 ### 01   Install
 
@@ -82,6 +82,8 @@ spooling sync      # embed every session for semantic search
 
 ```bash
 spooling search "that redis race condition"
+spooling session list                      # find a session and its id
+spooling session show ses_e6310bd1 -m      # read that session's full text
 spooling stats
 spooling mcp       # MCP server at http://127.0.0.1:3004/mcp
 ```
@@ -90,7 +92,7 @@ spooling mcp       # MCP server at http://127.0.0.1:3004/mcp
 
 ## Connect Spooling to your AI coding agent
 
-`spooling mcp` exposes an MCP server at `http://127.0.0.1:3004/mcp` (HTTP streamable transport). Any MCP-speaking agent can connect to it and pull context from your local KB mid-conversation. The agent gets tools like `spooling_search`, `spooling_recent_sessions`, `spooling_get_session`, `spooling_workspace_stats`, and `spooling_top_projects`.
+`spooling mcp` exposes an MCP server at `http://127.0.0.1:3004/mcp` (HTTP streamable transport). Any MCP-speaking agent can connect to it and pull context from your local KB mid-conversation. The agent gets tools like `search_sessions` (find a session), `get_session` (read its full conversation by id), `get_stats`, and `list_traces`. See [Tools exposed](#tools-exposed) for the full list.
 
 ### Cursor / Windsurf / Codex / Antigravity
 
@@ -117,7 +119,7 @@ curl -s http://127.0.0.1:3004/mcp \
   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq
 ```
 
-Should return the five `spool_*` tools. If you get "connection refused", `spooling ui` is not running (or its ports got squatted, run `lsof -ti :3004 | xargs kill -9` and retry).
+Should return the tools listed under [Tools exposed](#tools-exposed). If you get "connection refused", `spooling mcp` (or `spooling ui`) is not running, or something else is using port 3004. Find it with `lsof -i :3004`.
 
 ---
 
@@ -125,7 +127,7 @@ Should return the five `spool_*` tools. If you get "connection refused", `spooli
 
 ### `spooling init`
 
-Check database connection and show which AI coding tool providers are detected on your system. This scans default paths for Codex CLI, GitHub Copilot, Cursor, and Windsurf session data.
+Check that the local database opens and show which AI coding tool providers are detected on your system. This scans the default paths for every supported provider (see [Supported Providers](#supported-providers)).
 
 ```bash
 spooling init
@@ -154,17 +156,48 @@ spooling stats --days 30   # Last 30 days
 
 ### `spooling search <query>`
 
-Semantic search across all your session history using natural language.
+Semantic search across all your session history using natural language. Each result shows the session title **and its session id**, so you can open it with `spooling session show`.
 
 ```bash
 spooling search "snowflake connector"
 spooling search "authentication bug" -n 5
-spooling search "database migration" -p ~/myproject
+spooling search "database migration" -p myproject
+spooling search ses_e6310bd1                # a session id (or prefix) matches that session first
+spooling search "login issue" --cloud       # search your cloud workspace instead
 ```
 
+Session ids work in the query: a full id, a prefix such as `ses_e6310bd1`, or a UUID/hex prefix of 8+ characters. The matching session is ranked first and labelled `(id match)`. `--cloud` search is matched by the server, so ids are shown but not ranked first.
+
 Options:
 - `-n, --limit` - Number of results (default: 10)
-- `-p, --project` - Filter by project name
+- `-p, --project` - Filter by exact project name (see `spooling session list`)
+- `--cloud` - Search the cloud workspace instead of the local database
+
+### `spooling session`
+
+List sessions and read one back by id.
+
+```bash
+spooling session list                         # newest first, with full session ids
+spooling session list --title login -n 10     # filter by title substring
+spooling session list --id e6310bd1           # filter by id substring
+spooling session list --project myproject --cwd ~/code
+
+spooling session show ses_e6310bd1            # summary: model, tokens, cost, tools used
+spooling session show ses_e6310bd1 -m         # plus the full conversation text
+spooling session show ses_e6310bd1 -m --max-chars 300   # truncate each message
+```
+
+`session show` accepts a full session id or any unique prefix. If a prefix matches several sessions, it lists them and exits so you can pick one.
+
+### `spooling optimize`
+
+Compact the local database. Removes duplicated tool-call rows left by older versions (before 0.2.6), truncates oversized previews, embeds any messages missing from search, and runs `VACUUM`. A backup is written next to the database first, and it is safe to re-run. `spooling sync` prints a hint when it finds duplicates.
+
+```bash
+spooling optimize
+spooling optimize --no-backup --no-vacuum --no-embed   # skip individual steps
+```
 
 ### `spooling watch`
 
@@ -336,11 +369,15 @@ the CLI ships with a `spooling cloud` subcommand.
 Send the most recent local sessions up to the cloud:
 
 ```bash
-spooling push                 # 100 sessions, batches of 20
+spooling push                 # syncs local sessions first, then pushes 100 in batches of 20
 spooling push --limit 500     # bigger backfill
+spooling push --no-sync       # push only what is already in the local database
+spooling push --dry-run       # show what would be pushed
 ```
 
-The server upserts by session id, so re-running is safe.
+`push` ingests new provider sessions into the local database before uploading, so you don't need to run `spooling sync` first. The server upserts by session id, so re-running is safe.
+
+To bring sessions from the cloud back down, use `spooling cloud pull`, or `spooling cloud sync` for both directions.
 
 ### Watch (continuous push)
 
@@ -374,8 +411,8 @@ The cloud API at `api.spooling.ai` uses `/v1/` endpoints. Requests require a Bea
 curl -s "https://api.spooling.ai/v1/stats" \
   -H "Authorization: Bearer $SPOOLING_KEY"
 
-# Search (when deployed — falls back to local search on self-hosted)
-curl -s "https://api.spooling.ai/api/search?q=migration&limit=10" \
+# Search (matches session titles and ids)
+curl -s "https://api.spooling.ai/v1/search?q=migration&limit=10" \
   -H "Authorization: Bearer $SPOOLING_KEY"
 ```
 
@@ -450,7 +487,8 @@ the full config snippet so you don't have to remember it.
 |------|---------|
 | `list_traces` | Recent Spooling traces, filterable by provider/project |
 | `get_trace` | Full detail for one trace: header, spans, eval scores |
-| `search_sessions` | Semantic search over embedded session chunks |
+| `search_sessions` | Semantic search over embedded session chunks. Results include `session_id`; a session id in the query matches that session first |
+| `get_session` | Full detail for one session by id or unique prefix, including the conversation text (`include_messages`, `max_messages`, `max_chars`) |
 | `get_stats` | Top-line stats: traces, tokens, cost, errors |
 | `get_top_vendors` | Most-used external vendors by tool-call count |
 | `list_evals` | Recent eval runs, optionally filtered by rubric |
@@ -462,8 +500,15 @@ the full config snippet so you don't have to remember it.
 For MCP clients that only speak stdio, run `spooling mcp --stdio` and register
 it with the command-based form:
 
-```bash
-# MCP config for stdio transport
+```json
+{
+  "mcpServers": {
+    "spooling": {
+      "command": "spooling",
+      "args": ["mcp", "--stdio"]
+    }
+  }
+}
 ```
 
 ---
@@ -539,7 +584,9 @@ spooling/
 │   ├── parser.py            # Session JSONL parser
 │   ├── embeddings.py        # sentence-transformers (all-MiniLM-L6-v2)
 │   ├── ingest.py            # Sync pipeline
-│   ├── search.py            # Numpy cosine similarity search
+│   ├── search.py            # Numpy cosine similarity search (+ session-id matching)
+│   ├── sessions.py          # Session id lookup helpers
+│   ├── optimize.py          # Database dedupe / compaction
 │   ├── stats.py             # Usage statistics
 │   ├── watcher.py           # File watcher (watchdog)
 │   ├── agent.py             # Chat agent (Ollama + Anthropic)
@@ -583,7 +630,6 @@ All optional — defaults work out of the box.
 | `SPOOLING_DB` | `~/.local/share/spooling/spooling.db` | Path to the SQLite database file (`%APPDATA%\spooling\spooling.db` on Windows) |
 | `SPOOLING_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Sentence transformer model |
 | `SPOOLING_UI_HOST` | `127.0.0.1` | API server host |
-| `SPOOLING_UI_PORT` | `3001` | API server port (used by `spooling serve`) |
 | `SPOOLING_UI_DIR` | *(auto-detected)* | Path to the Next.js `ui/` directory (required for `spooling ui`) |
 | `ANTHROPIC_API_KEY` | - | Anthropic API key (alternative to setting in the GUI) |
 
@@ -604,5 +650,5 @@ All optional — defaults work out of the box.
 
 Run `spooling init` to see which providers are detected on your system.
 
-No data is sent to external servers. Everything runs locally.
+Nothing leaves your machine unless you opt in: Spooling Cloud (`spooling push`), a tunnel (`spooling tunnel`), or the Anthropic chat provider. `spooling pricing refresh` downloads public model prices but sends none of your data.
 

{spooling-0.2.6 → spooling-0.2.7}/README.md

@@ -20,7 +20,7 @@ No Docker, no PostgreSQL, no Node.js required.
 
 ## How it works
 
-**Four commands. Zero cloud.**
+**Three steps. Local by default.**
 
 ### 01   Install
 
@@ -46,6 +46,8 @@ spooling sync      # embed every session for semantic search
 
 ```bash
 spooling search "that redis race condition"
+spooling session list                      # find a session and its id
+spooling session show ses_e6310bd1 -m      # read that session's full text
 spooling stats
 spooling mcp       # MCP server at http://127.0.0.1:3004/mcp
 ```
@@ -54,7 +56,7 @@ spooling mcp       # MCP server at http://127.0.0.1:3004/mcp
 
 ## Connect Spooling to your AI coding agent
 
-`spooling mcp` exposes an MCP server at `http://127.0.0.1:3004/mcp` (HTTP streamable transport). Any MCP-speaking agent can connect to it and pull context from your local KB mid-conversation. The agent gets tools like `spooling_search`, `spooling_recent_sessions`, `spooling_get_session`, `spooling_workspace_stats`, and `spooling_top_projects`.
+`spooling mcp` exposes an MCP server at `http://127.0.0.1:3004/mcp` (HTTP streamable transport). Any MCP-speaking agent can connect to it and pull context from your local KB mid-conversation. The agent gets tools like `search_sessions` (find a session), `get_session` (read its full conversation by id), `get_stats`, and `list_traces`. See [Tools exposed](#tools-exposed) for the full list.
 
 ### Cursor / Windsurf / Codex / Antigravity
 
@@ -81,7 +83,7 @@ curl -s http://127.0.0.1:3004/mcp \
   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq
 ```
 
-Should return the five `spool_*` tools. If you get "connection refused", `spooling ui` is not running (or its ports got squatted, run `lsof -ti :3004 | xargs kill -9` and retry).
+Should return the tools listed under [Tools exposed](#tools-exposed). If you get "connection refused", `spooling mcp` (or `spooling ui`) is not running, or something else is using port 3004. Find it with `lsof -i :3004`.
 
 ---
 
@@ -89,7 +91,7 @@ Should return the five `spool_*` tools. If you get "connection refused", `spooli
 
 ### `spooling init`
 
-Check database connection and show which AI coding tool providers are detected on your system. This scans default paths for Codex CLI, GitHub Copilot, Cursor, and Windsurf session data.
+Check that the local database opens and show which AI coding tool providers are detected on your system. This scans the default paths for every supported provider (see [Supported Providers](#supported-providers)).
 
 ```bash
 spooling init
@@ -118,17 +120,48 @@ spooling stats --days 30   # Last 30 days
 
 ### `spooling search <query>`
 
-Semantic search across all your session history using natural language.
+Semantic search across all your session history using natural language. Each result shows the session title **and its session id**, so you can open it with `spooling session show`.
 
 ```bash
 spooling search "snowflake connector"
 spooling search "authentication bug" -n 5
-spooling search "database migration" -p ~/myproject
+spooling search "database migration" -p myproject
+spooling search ses_e6310bd1                # a session id (or prefix) matches that session first
+spooling search "login issue" --cloud       # search your cloud workspace instead
 ```
 
+Session ids work in the query: a full id, a prefix such as `ses_e6310bd1`, or a UUID/hex prefix of 8+ characters. The matching session is ranked first and labelled `(id match)`. `--cloud` search is matched by the server, so ids are shown but not ranked first.
+
 Options:
 - `-n, --limit` - Number of results (default: 10)
-- `-p, --project` - Filter by project name
+- `-p, --project` - Filter by exact project name (see `spooling session list`)
+- `--cloud` - Search the cloud workspace instead of the local database
+
+### `spooling session`
+
+List sessions and read one back by id.
+
+```bash
+spooling session list                         # newest first, with full session ids
+spooling session list --title login -n 10     # filter by title substring
+spooling session list --id e6310bd1           # filter by id substring
+spooling session list --project myproject --cwd ~/code
+
+spooling session show ses_e6310bd1            # summary: model, tokens, cost, tools used
+spooling session show ses_e6310bd1 -m         # plus the full conversation text
+spooling session show ses_e6310bd1 -m --max-chars 300   # truncate each message
+```
+
+`session show` accepts a full session id or any unique prefix. If a prefix matches several sessions, it lists them and exits so you can pick one.
+
+### `spooling optimize`
+
+Compact the local database. Removes duplicated tool-call rows left by older versions (before 0.2.6), truncates oversized previews, embeds any messages missing from search, and runs `VACUUM`. A backup is written next to the database first, and it is safe to re-run. `spooling sync` prints a hint when it finds duplicates.
+
+```bash
+spooling optimize
+spooling optimize --no-backup --no-vacuum --no-embed   # skip individual steps
+```
 
 ### `spooling watch`
 
@@ -300,11 +333,15 @@ the CLI ships with a `spooling cloud` subcommand.
 Send the most recent local sessions up to the cloud:
 
 ```bash
-spooling push                 # 100 sessions, batches of 20
+spooling push                 # syncs local sessions first, then pushes 100 in batches of 20
 spooling push --limit 500     # bigger backfill
+spooling push --no-sync       # push only what is already in the local database
+spooling push --dry-run       # show what would be pushed
 ```
 
-The server upserts by session id, so re-running is safe.
+`push` ingests new provider sessions into the local database before uploading, so you don't need to run `spooling sync` first. The server upserts by session id, so re-running is safe.
+
+To bring sessions from the cloud back down, use `spooling cloud pull`, or `spooling cloud sync` for both directions.
 
 ### Watch (continuous push)
 
@@ -338,8 +375,8 @@ The cloud API at `api.spooling.ai` uses `/v1/` endpoints. Requests require a Bea
 curl -s "https://api.spooling.ai/v1/stats" \
   -H "Authorization: Bearer $SPOOLING_KEY"
 
-# Search (when deployed — falls back to local search on self-hosted)
-curl -s "https://api.spooling.ai/api/search?q=migration&limit=10" \
+# Search (matches session titles and ids)
+curl -s "https://api.spooling.ai/v1/search?q=migration&limit=10" \
   -H "Authorization: Bearer $SPOOLING_KEY"
 ```
 
@@ -414,7 +451,8 @@ the full config snippet so you don't have to remember it.
 |------|---------|
 | `list_traces` | Recent Spooling traces, filterable by provider/project |
 | `get_trace` | Full detail for one trace: header, spans, eval scores |
-| `search_sessions` | Semantic search over embedded session chunks |
+| `search_sessions` | Semantic search over embedded session chunks. Results include `session_id`; a session id in the query matches that session first |
+| `get_session` | Full detail for one session by id or unique prefix, including the conversation text (`include_messages`, `max_messages`, `max_chars`) |
 | `get_stats` | Top-line stats: traces, tokens, cost, errors |
 | `get_top_vendors` | Most-used external vendors by tool-call count |
 | `list_evals` | Recent eval runs, optionally filtered by rubric |
@@ -426,8 +464,15 @@ the full config snippet so you don't have to remember it.
 For MCP clients that only speak stdio, run `spooling mcp --stdio` and register
 it with the command-based form:
 
-```bash
-# MCP config for stdio transport
+```json
+{
+  "mcpServers": {
+    "spooling": {
+      "command": "spooling",
+      "args": ["mcp", "--stdio"]
+    }
+  }
+}
 ```
 
 ---
@@ -503,7 +548,9 @@ spooling/
 │   ├── parser.py            # Session JSONL parser
 │   ├── embeddings.py        # sentence-transformers (all-MiniLM-L6-v2)
 │   ├── ingest.py            # Sync pipeline
-│   ├── search.py            # Numpy cosine similarity search
+│   ├── search.py            # Numpy cosine similarity search (+ session-id matching)
+│   ├── sessions.py          # Session id lookup helpers
+│   ├── optimize.py          # Database dedupe / compaction
 │   ├── stats.py             # Usage statistics
 │   ├── watcher.py           # File watcher (watchdog)
 │   ├── agent.py             # Chat agent (Ollama + Anthropic)
@@ -547,7 +594,6 @@ All optional — defaults work out of the box.
 | `SPOOLING_DB` | `~/.local/share/spooling/spooling.db` | Path to the SQLite database file (`%APPDATA%\spooling\spooling.db` on Windows) |
 | `SPOOLING_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Sentence transformer model |
 | `SPOOLING_UI_HOST` | `127.0.0.1` | API server host |
-| `SPOOLING_UI_PORT` | `3001` | API server port (used by `spooling serve`) |
 | `SPOOLING_UI_DIR` | *(auto-detected)* | Path to the Next.js `ui/` directory (required for `spooling ui`) |
 | `ANTHROPIC_API_KEY` | - | Anthropic API key (alternative to setting in the GUI) |
 
@@ -568,5 +614,5 @@ All optional — defaults work out of the box.
 
 Run `spooling init` to see which providers are detected on your system.
 
-No data is sent to external servers. Everything runs locally.
+Nothing leaves your machine unless you opt in: Spooling Cloud (`spooling push`), a tunnel (`spooling tunnel`), or the Anthropic chat provider. `spooling pricing refresh` downloads public model prices but sends none of your data.
 

{spooling-0.2.6 → spooling-0.2.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spooling"
-version = "0.2.6"
+version = "0.2.7"
 description = "Local session tracker and semantic search for AI coding assistants"
 readme = "README.md"
 authors = [{ name = "Parsed Analytics, Inc." }]

{spooling-0.2.6 → spooling-0.2.7}/spooling/cli.py

@@ -138,9 +138,13 @@ def search(query, limit, project, cloud_mode):
             f"[dim]{ts[:19]}[/dim]"
             + (f" [cyan](cloud)[/cyan]" if source == "cloud" else "")
         )
-        if r["title"]:
-            console.print(f"   [dim]Session:[/dim] {r['title']}")
-        console.print(f"   {r['content']}")
+        console.print(
+            f"   [dim]Session:[/dim] {r['title'] or '(untitled)'} "
+            f"[cyan]{r['session_id']}[/cyan]"
+            + (" [yellow](id match)[/yellow]" if r.get("match") == "session_id" else "")
+        )
+        if r.get("match") != "session_id":
+            console.print(f"   {r['content']}")
 
 
 @cli.command()
@@ -1141,8 +1145,9 @@ def session():
 @click.option("--project", "-p", default=None, help="Filter by exact project name")
 @click.option("--cwd", default=None, help="Filter by cwd substring")
 @click.option("--title", default=None, help="Filter by title substring")
+@click.option("--id", "id_part", default=None, help="Filter by session id substring")
 @click.option("--limit", "-n", default=20, help="Max sessions to return (default: 20)")
-def session_list(project, cwd, title, limit):
+def session_list(project, cwd, title, id_part, limit):
     """List local sessions with optional filters."""
     from spooling.db import get_connection
     from datetime import datetime as _dt
@@ -1159,6 +1164,9 @@ def session_list(project, cwd, title, limit):
     if title:
         wheres.append("title LIKE ?")
         params.append(f"%{title}%")
+    if id_part:
+        wheres.append("id LIKE ?")
+        params.append(f"%{id_part}%")
     where_clause = ("WHERE " + " AND ".join(wheres)) if wheres else ""
     params.append(limit)
 
@@ -1176,8 +1184,8 @@ def session_list(project, cwd, title, limit):
         return
 
     table = Table(title=f"Sessions ({len(rows)})", show_lines=False)
-    table.add_column("ID", style="dim")
-    table.add_column("Provider", style="cyan")
+    table.add_column("Session ID", style="cyan", no_wrap=True)
+    table.add_column("Provider")
     table.add_column("Project")
     table.add_column("Title")
     table.add_column("Started", style="dim")
@@ -1194,7 +1202,7 @@ def session_list(project, cwd, title, limit):
                 raw_ts = None
         ts = raw_ts.strftime("%m/%d %H:%M") if raw_ts else ""
         table.add_row(
-            (r["id"] or "")[:12],
+            r["id"] or "",
             r["provider_id"] or "",
             _clean_project(r["project"] or ""),
             (r["title"] or "")[:45],
@@ -1208,10 +1216,21 @@ def session_list(project, cwd, title, limit):
 
 @session.command("show")
 @click.argument("session_id")
-@click.option("--messages", "-m", is_flag=True, help="Show full message content")
-def session_show(session_id, messages):
-    """Show full detail for a session including messages and tool calls."""
+@click.option("--messages", "-m", is_flag=True, help="Print the full session text (all messages)")
+@click.option("--max-chars", default=0, type=int, help="Truncate each message to N chars (0 = no limit)")
+def session_show(session_id, messages, max_chars):
+    """Show a session by id (full id or unique prefix), optionally with its full text."""
     from spooling.stats import get_session_detail
+    from spooling.sessions import resolve_session_ids
+
+    matches = resolve_session_ids(session_id)
+    if len(matches) > 1:
+        console.print(f"[yellow]'{session_id}' is ambiguous; matches:[/yellow]")
+        for m in matches:
+            console.print(f"  {m}")
+        raise SystemExit(1)
+    if matches:
+        session_id = matches[0]
 
     detail = get_session_detail(session_id)
     if not detail:
@@ -1244,23 +1263,19 @@ def session_show(session_id, messages):
         console.print(table)
 
     if messages and detail["messages"]:
-        table = Table(title="Messages", show_lines=True)
-        table.add_column("Role", style="cyan", width=10)
-        table.add_column("Timestamp", style="dim", width=18)
-        table.add_column("Content")
         for m in detail["messages"]:
-            content = (m.get("content") or "")[:300]
+            role = m.get("role") or ""
+            color = "green" if role == "user" else "blue"
+            console.print(f"\n[{color}]{role}[/{color}] [dim]{str(m.get('timestamp') or '')[:19]}[/dim]")
+            content = m.get("content") or ""
+            if max_chars and len(content) > max_chars:
+                content = content[:max_chars] + "..."
+            console.print(content, markup=False, highlight=False)
             if m.get("tool_calls"):
                 tools = ", ".join(tc["name"] for tc in m["tool_calls"])
-                content += f"\n[dim]Tools: {tools}[/dim]"
-            table.add_row(
-                m.get("role", ""),
-                str(m.get("timestamp") or "")[:18],
-                content,
-            )
-        console.print(table)
+                console.print(f"Tools: {tools}", style="dim", markup=False)
     elif not messages and detail["messages"]:
-        console.print(f"[dim]{len(detail['messages'])} messages — pass --messages to show content[/dim]")
+        console.print(f"[dim]{len(detail['messages'])} messages — pass --messages to print the session text[/dim]")
 
 
 # ---------------------------------------------------------------------------

{spooling-0.2.6 → spooling-0.2.7}/spooling/mcp_server.py

@@ -10,6 +10,7 @@ Tools exposed:
   - list_traces(limit, provider, project)
   - get_trace(trace_id)
   - search_sessions(query, limit, project)
+  - get_session(session_id, include_messages)
   - get_stats()
   - get_top_vendors()
   - list_evals(rubric_id, limit)
@@ -306,6 +307,10 @@ def search_sessions(
 ) -> list[dict]:
     """Semantic search over Spooling's embedded session chunks. Returns ranked matches.
 
+    Each result includes ``session_id`` and ``title``. A session id (or prefix,
+    e.g. ``ses_e6310bd1``) in the query matches that session directly and ranks
+    first. Use ``get_session`` to read a result's full conversation.
+
     Falls back to Spooling Cloud ILIKE search when the local DB has no
     embedded results and a cloud API key is configured. Cloud results
     include a ``_source: "cloud"`` field.
@@ -374,6 +379,53 @@ def search_sessions(
     ]
 
 
+@mcp.tool()
+def get_session(
+    session_id: str,
+    include_messages: bool = True,
+    max_messages: int = 200,
+    max_chars: int = 4000,
+) -> dict:
+    """Fetch one session by id, including its conversation text.
+
+    Use after ``search_sessions`` (or ``list_traces``) to read what was said.
+    Accepts a full session id or a unique prefix (e.g. ``ses_e6310bd1``).
+
+    Args:
+        session_id: Full session id or unique prefix.
+        include_messages: Include the message text (default True).
+        max_messages: Max messages to return, oldest first (default 200).
+        max_chars: Truncate each message to this many characters (0 = no limit).
+    """
+    from spooling.sessions import resolve_session_ids
+    from spooling.stats import get_session_detail
+
+    matches = resolve_session_ids(session_id)
+    if not matches:
+        return {"error": f"session not found: {session_id}"}
+    if len(matches) > 1:
+        return {"error": f"ambiguous session id: {session_id}", "matches": matches}
+
+    detail = get_session_detail(matches[0])
+    if not detail:
+        return {"error": f"session not found: {session_id}"}
+
+    out: dict = {
+        "session": detail["session"],
+        "tool_summary": detail["tool_summary"],
+        "message_count": len(detail["messages"]),
+    }
+    if include_messages:
+        msgs = detail["messages"][: max(0, max_messages)]
+        for m in msgs:
+            content = m.get("content") or ""
+            if max_chars and len(content) > max_chars:
+                m["content"] = content[:max_chars] + "..."
+        out["messages"] = msgs
+        out["truncated"] = len(detail["messages"]) > len(msgs)
+    return out
+
+
 @mcp.tool()
 def get_stats() -> dict:
     """Top-line Spooling stats: total traces, spans, tools, llm calls, cost, errors.

{spooling-0.2.6 → spooling-0.2.7}/spooling/search.py

@@ -73,7 +73,40 @@ def _load_index(conn, dim: int) -> _Index:
 
 
 def search(query: str, limit: int = 10, project: str | None = None) -> list[dict]:
-    """Search session chunks by semantic similarity."""
+    """Search session chunks by semantic similarity.
+
+    Session ids (full or partial) found in the query are matched directly and
+    ranked first, so ids are searchable alongside titles and content.
+    """
+    id_hits = _id_matches(query, project)
+    results = _semantic_search(query, limit, project)
+    seen = {r["session_id"] for r in id_hits}
+    merged = id_hits + [r for r in results if r["session_id"] not in seen]
+    return merged[:limit]
+
+
+def _id_matches(query: str, project: str | None) -> list[dict]:
+    from spooling.sessions import find_sessions_by_id_in_query
+
+    out = []
+    for s in find_sessions_by_id_in_query(query):
+        if project and s["project"] != project:
+            continue
+        out.append({
+            "content": s["title"] or "(untitled)",
+            "role": "session",
+            "project": s["project"],
+            "timestamp": s["started_at"],
+            "session_id": s["id"],
+            "similarity": 1.0,
+            "title": s["title"],
+            "cwd": s["cwd"],
+            "match": "session_id",
+        })
+    return out
+
+
+def _semantic_search(query: str, limit: int = 10, project: str | None = None) -> list[dict]:
     query_arr = np.array(embed_text(query), dtype=np.float32)
 
     conn = get_connection()

spooling-0.2.7/spooling/sessions.py

@@ -0,0 +1,63 @@
+"""Session id helpers: resolve id prefixes and find ids mentioned in a search query."""
+
+import re
+
+from spooling.db import get_connection
+
+# Tokens that look like (part of) a session id:
+#   - opencode style ids: ``ses_...``
+#   - UUIDs or hex prefixes of at least 8 chars (dashes allowed)
+# Plain words and short numbers are never treated as ids.
+_ID_TOKEN = re.compile(r"[A-Za-z0-9][A-Za-z0-9_\-]{5,}")
+_HEX_ID = re.compile(r"^(?=.*\d)[0-9a-fA-F][0-9a-fA-F\-]{7,}$")
+
+
+def looks_like_session_id(token: str) -> bool:
+    if token.isdigit():
+        return False
+    return token.lower().startswith("ses_") or bool(_HEX_ID.match(token))
+
+
+def _like_escape(s: str) -> str:
+    return s.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+
+
+def resolve_session_ids(ref: str, limit: int = 10) -> list[str]:
+    """Resolve an exact id or id prefix to matching session ids."""
+    conn = get_connection()
+    try:
+        exact = conn.execute("SELECT id FROM sessions WHERE id = ?", (ref,)).fetchone()
+        if exact:
+            return [exact["id"]]
+        rows = conn.execute(
+            "SELECT id FROM sessions WHERE id LIKE ? ESCAPE '\\' ORDER BY started_at DESC LIMIT ?",
+            (_like_escape(ref) + "%", limit),
+        ).fetchall()
+        return [r["id"] for r in rows]
+    finally:
+        conn.close()
+
+
+def find_sessions_by_id_in_query(query: str, limit: int = 10) -> list[dict]:
+    """Find sessions whose id (or id prefix/substring) appears in a free-text query.
+
+    Lets semantic search accept a session id (full or partial) alongside or
+    instead of natural language.
+    """
+    tokens = {t for t in _ID_TOKEN.findall(query) if looks_like_session_id(t)}
+    if not tokens:
+        return []
+    clauses, params = [], []
+    for t in tokens:
+        clauses.append("id LIKE ? ESCAPE '\\'")
+        params.append(f"%{_like_escape(t)}%")
+    conn = get_connection()
+    try:
+        rows = conn.execute(
+            f"SELECT id, title, project, cwd, started_at FROM sessions WHERE {' OR '.join(clauses)} "
+            "ORDER BY started_at DESC LIMIT ?",
+            tuple(params) + (limit,),
+        ).fetchall()
+        return [dict(r) if not isinstance(r, dict) else r for r in rows]
+    finally:
+        conn.close()

{spooling-0.2.6 → spooling-0.2.7/spooling.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spooling
-Version: 0.2.6
+Version: 0.2.7
 Summary: Local session tracker and semantic search for AI coding assistants
 Author: Parsed Analytics, Inc.
 License: MIT
@@ -56,7 +56,7 @@ No Docker, no PostgreSQL, no Node.js required.
 
 ## How it works
 
-**Four commands. Zero cloud.**
+**Three steps. Local by default.**
 
 ### 01   Install
 
@@ -82,6 +82,8 @@ spooling sync      # embed every session for semantic search
 
 ```bash
 spooling search "that redis race condition"
+spooling session list                      # find a session and its id
+spooling session show ses_e6310bd1 -m      # read that session's full text
 spooling stats
 spooling mcp       # MCP server at http://127.0.0.1:3004/mcp
 ```
@@ -90,7 +92,7 @@ spooling mcp       # MCP server at http://127.0.0.1:3004/mcp
 
 ## Connect Spooling to your AI coding agent
 
-`spooling mcp` exposes an MCP server at `http://127.0.0.1:3004/mcp` (HTTP streamable transport). Any MCP-speaking agent can connect to it and pull context from your local KB mid-conversation. The agent gets tools like `spooling_search`, `spooling_recent_sessions`, `spooling_get_session`, `spooling_workspace_stats`, and `spooling_top_projects`.
+`spooling mcp` exposes an MCP server at `http://127.0.0.1:3004/mcp` (HTTP streamable transport). Any MCP-speaking agent can connect to it and pull context from your local KB mid-conversation. The agent gets tools like `search_sessions` (find a session), `get_session` (read its full conversation by id), `get_stats`, and `list_traces`. See [Tools exposed](#tools-exposed) for the full list.
 
 ### Cursor / Windsurf / Codex / Antigravity
 
@@ -117,7 +119,7 @@ curl -s http://127.0.0.1:3004/mcp \
   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq
 ```
 
-Should return the five `spool_*` tools. If you get "connection refused", `spooling ui` is not running (or its ports got squatted, run `lsof -ti :3004 | xargs kill -9` and retry).
+Should return the tools listed under [Tools exposed](#tools-exposed). If you get "connection refused", `spooling mcp` (or `spooling ui`) is not running, or something else is using port 3004. Find it with `lsof -i :3004`.
 
 ---
 
@@ -125,7 +127,7 @@ Should return the five `spool_*` tools. If you get "connection refused", `spooli
 
 ### `spooling init`
 
-Check database connection and show which AI coding tool providers are detected on your system. This scans default paths for Codex CLI, GitHub Copilot, Cursor, and Windsurf session data.
+Check that the local database opens and show which AI coding tool providers are detected on your system. This scans the default paths for every supported provider (see [Supported Providers](#supported-providers)).
 
 ```bash
 spooling init
@@ -154,17 +156,48 @@ spooling stats --days 30   # Last 30 days
 
 ### `spooling search <query>`
 
-Semantic search across all your session history using natural language.
+Semantic search across all your session history using natural language. Each result shows the session title **and its session id**, so you can open it with `spooling session show`.
 
 ```bash
 spooling search "snowflake connector"
 spooling search "authentication bug" -n 5
-spooling search "database migration" -p ~/myproject
+spooling search "database migration" -p myproject
+spooling search ses_e6310bd1                # a session id (or prefix) matches that session first
+spooling search "login issue" --cloud       # search your cloud workspace instead
 ```
 
+Session ids work in the query: a full id, a prefix such as `ses_e6310bd1`, or a UUID/hex prefix of 8+ characters. The matching session is ranked first and labelled `(id match)`. `--cloud` search is matched by the server, so ids are shown but not ranked first.
+
 Options:
 - `-n, --limit` - Number of results (default: 10)
-- `-p, --project` - Filter by project name
+- `-p, --project` - Filter by exact project name (see `spooling session list`)
+- `--cloud` - Search the cloud workspace instead of the local database
+
+### `spooling session`
+
+List sessions and read one back by id.
+
+```bash
+spooling session list                         # newest first, with full session ids
+spooling session list --title login -n 10     # filter by title substring
+spooling session list --id e6310bd1           # filter by id substring
+spooling session list --project myproject --cwd ~/code
+
+spooling session show ses_e6310bd1            # summary: model, tokens, cost, tools used
+spooling session show ses_e6310bd1 -m         # plus the full conversation text
+spooling session show ses_e6310bd1 -m --max-chars 300   # truncate each message
+```
+
+`session show` accepts a full session id or any unique prefix. If a prefix matches several sessions, it lists them and exits so you can pick one.
+
+### `spooling optimize`
+
+Compact the local database. Removes duplicated tool-call rows left by older versions (before 0.2.6), truncates oversized previews, embeds any messages missing from search, and runs `VACUUM`. A backup is written next to the database first, and it is safe to re-run. `spooling sync` prints a hint when it finds duplicates.
+
+```bash
+spooling optimize
+spooling optimize --no-backup --no-vacuum --no-embed   # skip individual steps
+```
 
 ### `spooling watch`
 
@@ -336,11 +369,15 @@ the CLI ships with a `spooling cloud` subcommand.
 Send the most recent local sessions up to the cloud:
 
 ```bash
-spooling push                 # 100 sessions, batches of 20
+spooling push                 # syncs local sessions first, then pushes 100 in batches of 20
 spooling push --limit 500     # bigger backfill
+spooling push --no-sync       # push only what is already in the local database
+spooling push --dry-run       # show what would be pushed
 ```
 
-The server upserts by session id, so re-running is safe.
+`push` ingests new provider sessions into the local database before uploading, so you don't need to run `spooling sync` first. The server upserts by session id, so re-running is safe.
+
+To bring sessions from the cloud back down, use `spooling cloud pull`, or `spooling cloud sync` for both directions.
 
 ### Watch (continuous push)
 
@@ -374,8 +411,8 @@ The cloud API at `api.spooling.ai` uses `/v1/` endpoints. Requests require a Bea
 curl -s "https://api.spooling.ai/v1/stats" \
   -H "Authorization: Bearer $SPOOLING_KEY"
 
-# Search (when deployed — falls back to local search on self-hosted)
-curl -s "https://api.spooling.ai/api/search?q=migration&limit=10" \
+# Search (matches session titles and ids)
+curl -s "https://api.spooling.ai/v1/search?q=migration&limit=10" \
   -H "Authorization: Bearer $SPOOLING_KEY"
 ```
 
@@ -450,7 +487,8 @@ the full config snippet so you don't have to remember it.
 |------|---------|
 | `list_traces` | Recent Spooling traces, filterable by provider/project |
 | `get_trace` | Full detail for one trace: header, spans, eval scores |
-| `search_sessions` | Semantic search over embedded session chunks |
+| `search_sessions` | Semantic search over embedded session chunks. Results include `session_id`; a session id in the query matches that session first |
+| `get_session` | Full detail for one session by id or unique prefix, including the conversation text (`include_messages`, `max_messages`, `max_chars`) |
 | `get_stats` | Top-line stats: traces, tokens, cost, errors |
 | `get_top_vendors` | Most-used external vendors by tool-call count |
 | `list_evals` | Recent eval runs, optionally filtered by rubric |
@@ -462,8 +500,15 @@ the full config snippet so you don't have to remember it.
 For MCP clients that only speak stdio, run `spooling mcp --stdio` and register
 it with the command-based form:
 
-```bash
-# MCP config for stdio transport
+```json
+{
+  "mcpServers": {
+    "spooling": {
+      "command": "spooling",
+      "args": ["mcp", "--stdio"]
+    }
+  }
+}
 ```
 
 ---
@@ -539,7 +584,9 @@ spooling/
 │   ├── parser.py            # Session JSONL parser
 │   ├── embeddings.py        # sentence-transformers (all-MiniLM-L6-v2)
 │   ├── ingest.py            # Sync pipeline
-│   ├── search.py            # Numpy cosine similarity search
+│   ├── search.py            # Numpy cosine similarity search (+ session-id matching)
+│   ├── sessions.py          # Session id lookup helpers
+│   ├── optimize.py          # Database dedupe / compaction
 │   ├── stats.py             # Usage statistics
 │   ├── watcher.py           # File watcher (watchdog)
 │   ├── agent.py             # Chat agent (Ollama + Anthropic)
@@ -583,7 +630,6 @@ All optional — defaults work out of the box.
 | `SPOOLING_DB` | `~/.local/share/spooling/spooling.db` | Path to the SQLite database file (`%APPDATA%\spooling\spooling.db` on Windows) |
 | `SPOOLING_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Sentence transformer model |
 | `SPOOLING_UI_HOST` | `127.0.0.1` | API server host |
-| `SPOOLING_UI_PORT` | `3001` | API server port (used by `spooling serve`) |
 | `SPOOLING_UI_DIR` | *(auto-detected)* | Path to the Next.js `ui/` directory (required for `spooling ui`) |
 | `ANTHROPIC_API_KEY` | - | Anthropic API key (alternative to setting in the GUI) |
 
@@ -604,5 +650,5 @@ All optional — defaults work out of the box.
 
 Run `spooling init` to see which providers are detected on your system.
 
-No data is sent to external servers. Everything runs locally.
+Nothing leaves your machine unless you opt in: Spooling Cloud (`spooling push`), a tunnel (`spooling tunnel`), or the Anthropic chat provider. `spooling pricing refresh` downloads public model prices but sends none of your data.
 

{spooling-0.2.6 → spooling-0.2.7}/spooling.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ spooling/schema.py
 spooling/sdk.py
 spooling/search.py
 spooling/server.py
+spooling/sessions.py
 spooling/stats.py
 spooling/subscription_pricing.py
 spooling/tracing.py
@@ -62,5 +63,6 @@ spooling/providers/opencode.py
 spooling/providers/session_file.py
 spooling/providers/windsurf.py
 tests/test_mcp_auth_middleware.py
+tests/test_session_ids.py
 tests/test_storage_optimizations.py
 tests/test_tunnel_auth.py

spooling-0.2.7/tests/test_session_ids.py

@@ -0,0 +1,135 @@
+"""Tests for session-id lookup: id detection, prefix resolution, id-aware search,
+the MCP get_session tool, and the `session` CLI commands."""
+
+from datetime import datetime, timezone
+
+import numpy as np
+import pytest
+from click.testing import CliRunner
+
+from spooling import db as db_mod
+from spooling import ingest, search as search_mod
+from spooling.parser import ParsedMessage, ParsedSession
+from spooling.sessions import (
+    find_sessions_by_id_in_query,
+    looks_like_session_id,
+    resolve_session_ids,
+)
+
+NOW = datetime(2026, 11, 2, tzinfo=timezone.utc)
+
+OC1 = "ses_e6310bd1fffezQhC7EHnDnrp3R"
+OC2 = "ses_e6310cafefffeAAAAAAAAAAAAA"
+UU1 = "0b104f33-1ffe-4a2b-9c3d-123456789abc"
+
+
+@pytest.fixture
+def conn(tmp_path, monkeypatch):
+    monkeypatch.setattr(db_mod, "DB_PATH", tmp_path / "spooling.db")
+    c = db_mod.get_connection()
+    for sid, title in [(OC1, "login issue"), (OC2, "other work"), (UU1, "uuid session")]:
+        ingest._store_session(c, ParsedSession(
+            session_id=sid, project="proj", started_at=NOW, ended_at=NOW,
+            messages=[
+                ParsedMessage(uuid=f"{sid}-1", session_id=sid, role="user", content=f"hello from {title}", timestamp=NOW),
+                ParsedMessage(uuid=f"{sid}-2", session_id=sid, role="assistant", content="reply " + "x" * 50, timestamp=NOW),
+            ],
+        ))
+        c.execute("UPDATE sessions SET title = ? WHERE id = ?", (title, sid))
+    c.commit()
+    yield c
+    c.close()
+
+
+@pytest.mark.parametrize("token,expected", [
+    ("ses_e6310bd1", True),
+    ("SES_E6310BD1", True),
+    ("e6310bd1fffe", True),
+    ("0b104f33-1ffe-4a2b", True),
+    ("password", False),
+    ("authentication", False),
+    ("deadbeef", False),     # hex-looking word, no digit
+    ("12345678", False),     # plain number
+    ("login-issue", False),
+])
+def test_looks_like_session_id(token, expected):
+    assert looks_like_session_id(token) is expected
+
+
+def test_resolve_exact_prefix_ambiguous_and_missing(conn):
+    assert resolve_session_ids(OC1) == [OC1]
+    assert resolve_session_ids("ses_e6310bd1") == [OC1]
+    assert sorted(resolve_session_ids("ses_e6310")) == sorted([OC1, OC2])
+    assert resolve_session_ids("nope") == []
+
+
+def test_resolve_escapes_like_wildcards(conn):
+    assert resolve_session_ids("%") == []
+    assert resolve_session_ids("ses_%") == []  # '%' is literal, not a wildcard
+
+
+def test_find_by_id_in_query(conn):
+    hits = find_sessions_by_id_in_query("what happened in ses_e6310bd1 yesterday")
+    assert [h["id"] for h in hits] == [OC1]
+    assert find_sessions_by_id_in_query("how do I fix authentication")  == []
+    assert [h["id"] for h in find_sessions_by_id_in_query("0b104f33-1ffe")] == [UU1]
+
+
+def test_search_ranks_id_match_first(conn, monkeypatch):
+    # Stub the semantic side so the test needs no embedding model.
+    monkeypatch.setattr(search_mod, "_semantic_search", lambda q, limit, project: [
+        {"content": "other", "role": "user", "project": "proj", "timestamp": "t",
+         "session_id": OC2, "similarity": 0.9, "title": "other work", "cwd": None},
+        {"content": "dup", "role": "user", "project": "proj", "timestamp": "t",
+         "session_id": OC1, "similarity": 0.5, "title": "login issue", "cwd": None},
+    ])
+    res = search_mod.search("ses_e6310bd1fffe", limit=5)
+    assert res[0]["session_id"] == OC1
+    assert res[0]["match"] == "session_id"
+    assert res[0]["similarity"] == 1.0
+    # no duplicate of the id-matched session from the semantic results
+    assert [r["session_id"] for r in res].count(OC1) == 1
+    assert len(res) == 2
+
+
+def test_search_id_match_respects_project_and_limit(conn, monkeypatch):
+    monkeypatch.setattr(search_mod, "_semantic_search", lambda q, limit, project: [])
+    assert search_mod.search("ses_e6310bd1", project="other") == []
+    assert len(search_mod.search("ses_e6310", limit=1)) == 1
+
+
+def test_mcp_get_session(conn):
+    from spooling import mcp_server
+
+    out = mcp_server.get_session("ses_e6310bd1")
+    assert out["session"]["id"] == OC1
+    assert out["message_count"] == 2
+    assert [m["role"] for m in out["messages"]] == ["user", "assistant"]
+
+    short = mcp_server.get_session(OC1, max_chars=5)
+    assert short["messages"][1]["content"].endswith("...")
+
+    capped = mcp_server.get_session(OC1, max_messages=1)
+    assert len(capped["messages"]) == 1 and capped["truncated"] is True
+
+    assert "messages" not in mcp_server.get_session(OC1, include_messages=False)
+    assert "ambiguous" in mcp_server.get_session("ses_e6310")["error"]
+    assert "not found" in mcp_server.get_session("zzz")["error"]
+
+
+def test_cli_session_show_and_list(conn):
+    from spooling.cli import cli
+
+    r = CliRunner()
+    res = r.invoke(cli, ["session", "show", "ses_e6310bd1", "-m"])
+    assert res.exit_code == 0, res.output
+    assert "hello from login issue" in res.output
+
+    res = r.invoke(cli, ["session", "show", "ses_e6310"])
+    assert res.exit_code == 1
+    assert OC1 in res.output and OC2 in res.output
+
+    res = r.invoke(cli, ["session", "list", "--id", "0b104f33"], env={"COLUMNS": "200"})
+    assert res.exit_code == 0
+    assert UU1 in res.output
+    assert OC1 not in res.output