@henryqw/pi-session-recall 0.1.5 → 0.1.7

package/README.md

@@ -27,12 +27,18 @@ pi install npm:@henryqw/pi-session-recall
 
 **Browse** — recent sessions: path, name, cwd, started date, preview.
 
-Query syntax: FTS5 over a trigram index — multi-word = AND by default, `OR` for breadth, quoted phrases for exact match, `NOT` to exclude. Wildcards only help stems ≥3 chars. Only user/assistant text is indexed; thinking blocks and tool output are not searchable. For message text over the 20,000-character indexing budget, only first/last regions are indexed and the middle is omitted; phrases and `NEAR` cannot cross those regions, but ordinary AND terms can. `sessionId` must be a `.jsonl` file under the Pi sessions directory.
+Query syntax: Prefer distinctive identifiers, package names, issue numbers, or uncommon terms; use quoted phrases only when exact wording is known. FTS5 over a trigram index — multi-word = AND by default, `OR` for breadth, quoted phrases for exact match, `NOT` to exclude. Wildcards only help stems ≥3 chars. Only user/assistant text is indexed; thinking blocks and tool output are not searchable. For message text over the 20,000-character indexing budget, only first/last regions are indexed and the middle is omitted; phrases and `NEAR` cannot cross those regions, but ordinary AND terms can. `sessionId` must be a `.jsonl` file under the Pi sessions directory.
 
 Hits inside the current session's live context are suppressed; compacted-away or inactive-branch history stays discoverable. Forked sessions collapse into their parent when both match.
 
 If the lazy index sync before browse/discovery cannot fully enumerate the session tree, or throws entirely, results are still served from the current index — potentially partially updated and stale: files discovered before the failure may already reflect their new content, while rows for files the walk never reached remain stale — and carry a top-level `syncWarning`: `{kind:"incomplete-walk"}` for a partial walk (indexed-but-unseen paths are never purged in that case), or `{kind:"sync-failed", error}` with the capped failure message. The warning is omitted once a sync completes.
 
+## State
+
+| Path | Purpose |
+| --- | --- |
+| `~/.pi/agent/config/pi-session-recall/index.db` | Derived SQLite search index, maintained by the extension. |
+
 ## Deliberate exclusions
 
 Session directories whose encoded path starts with `--tmp-` or `--private-tmp-` (sessions run from `/tmp` or `/private/tmp`) are never indexed. Session files over 32 MiB are excluded from indexing and hydration: discovery cannot newly find them; READ/SCROLL return an explicit size error, while a stale discovery hit retained from before the file grew is returned as metadata with empty messages and that error.
@@ -40,19 +46,3 @@ Session directories whose encoded path starts with `--tmp-` or `--private-tmp-`
 ## Storage & privacy
 
 The SQLite index lives at `~/.pi/agent/config/pi-session-recall/index.db`. It is derived state: delete it and it rebuilds from your session files. Everything stays local — transcripts are read in place and nothing leaves the machine beyond what tool results already show the model.
-
-## Remove
-
-```bash
-pi remove npm:@henryqw/pi-session-recall
-```
-
-Delete `~/.pi/agent/config/pi-session-recall/` to reclaim index disk space.
-
-## Development
-
-```bash
-npm test --workspace @henryqw/pi-session-recall
-npm run typecheck --workspace @henryqw/pi-session-recall
-npm run pack:check --workspace @henryqw/pi-session-recall
-```

package/extensions/session-recall.ts

@@ -85,30 +85,12 @@ interface ToolParams {
 	detail?: "adaptive" | "full";
 }
 
-const DESCRIPTION = `Search past Pi sessions stored on disk (FTS5-backed over a local SQLite index), or inspect one session in detail. No LLM calls — every shape returns actual messages.
+const DESCRIPTION = `Search past Pi sessions locally with FTS5; returns stored messages.
 
-FOUR CALLING SHAPES
-
-  1) DISCOVERY — pass \`query\`:
-     session_search(query="auth refactor", limit=3)
-     Runs FTS5 search and returns the top N sessions with metadata, match snippet, and messages around each match. Adaptive detail (default): the top-ranked result carries a ±5 message window plus first/last bookend messages; lower-ranked results carry only the anchor message. Pass \`detail="full"\` to hydrate every result fully.
-
-  2) SCROLL — pass \`sessionId\` + \`aroundMessageId\`:
-     session_search(sessionId="...", aroundMessageId="e07", window=10)
-     Returns ±window messages centered on the anchor (clamped to [1,20]). Use after discovery when you need more context than the default ±5 window. To scroll forward/backward, pass the last/first message entryId of the previous window back as aroundMessageId; messagesBefore/messagesAfter tell you where you are. Across forks, re-anchoring on a shared ancestor can jump branches — pass the previous response's branchTip as the branchTip argument (aroundMessageId only moves the center) to stay on that branch.
-
-  3) READ — pass \`sessionId\` only:
-     session_search(sessionId="...")
-     Returns the session's active branch (first 20 + last 10 messages when large).
-
-  4) BROWSE — no args:
-     session_search()
-     Returns recent sessions: name, cwd, start time, first-user-message preview. Use when asked "what was I working on" without a topic.
-
-Mode is inferred from args; precedence: scroll > read > browse > discovery.
-
-FTS5 SYNTAX
-  AND is the default — multi-word queries require all terms. Use OR for broader recall (\`alpha OR beta\`), quoted phrases for exact match (\`"docker networking"\`), NOT to exclude (\`python NOT java\`). Wildcards work only as stem expansion of tokens ≥3 chars (trigram tokenizer); very short terms fall back to substring matching. The index covers user/assistant message text only — thinking, tool calls/results are not searchable.`;
+- \`query\`: discover matches. Prefer distinctive identifiers or uncommon terms; multi-word queries are AND. Use \`OR\`/\`NOT\` for Boolean queries and quotes only when exact wording is known.
+- \`sessionId\` + \`aroundMessageId\`: scroll ±\`window\`; retain \`branchTip\` across forks.
+- \`sessionId\` alone: read; no args: browse recent sessions.
+- Discovery is adaptive; use \`detail: "full"\` to hydrate every result.`;
 
 export default function (pi: ExtensionAPI): void {
 	// Best-effort sync at startup, deferred so the synchronous walk + SQLite

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@henryqw/pi-session-recall",
-	"version": "0.1.5",
+	"version": "0.1.7",
 	"description": "FTS5 search over past Pi sessions: single tool, four arg-inferred modes (discovery/scroll/read/browse), zero LLM calls.",
 	"keywords": [
 		"pi-package",