cogpit-memory 0.2.1 → 0.3.0

package/skill/SKILL.md

@@ -1,29 +1,31 @@
 ---
 name: cogpit-memory
-description: CLI tool for Claude Code and Codex session introspection -- retrieves conversation history, tool calls, thinking, sub-agent/team activity, full-text search, and session discovery. All output is JSON to stdout.
+description: CLI tool for Claude Code, Codex, and GitHub Copilot CLI session introspection -- retrieves conversation history, tool calls, thinking, full-text search, session discovery, and supported sub-agent/team activity. All output is JSON to stdout.
 ---
 
 # Cogpit Memory -- Session Context CLI
 
-CLI tool that gives any AI assistant memory of past Claude Code and Codex sessions. Retrieve conversation history, tool usage, thinking, and sub-agent activity via a layered command structure. Session discovery and layered context support both providers; cross-session full-text indexing currently covers Claude Code history, while `search --session` supports either provider.
+CLI tool that gives any AI assistant memory of past Claude Code, Codex, and GitHub Copilot CLI sessions. Retrieve conversation history, tool usage, thinking, and supported sub-agent activity via a layered command structure. Session discovery, root context and cross-session full-text indexing all cover every provider. Copilot nested activity is included inline in the root session, but `context --agent` is unavailable because Copilot CLI does not write separate sub-agent transcript files.
 
 Always start with session discovery or the overview (Layer 1), and drill into specific turns or sub-agents only as needed. Use search when you need to **find** content rather than browse known sessions.
 
-**Prerequisite:** Bun must be installed (uses bun:sqlite for FTS5 search).
-
-## Step 1 -- Verify the tool works
+## Step 1 -- Use the installed CLI
 
 ```bash
-bunx cogpit-memory --help
+command -v cogpit-memory
+cogpit-memory --help
 ```
 
-If this prints usage info, proceed to Step 2. If `bunx` is not available, install the package globally:
+If missing, install it once, wait for installation to finish, then use the installed command:
 
 ```bash
-npm install -g cogpit-memory
+bun install --global cogpit-memory
+cogpit-memory --help
 ```
 
-Then use `cogpit-memory` directly instead of `bunx cogpit-memory`.
+The npm package requires Node.js 20 or newer. If Bun's global bin directory is not on PATH, resolve it with `bun pm bin --global` and invoke `cogpit-memory` there. Do not run parallel `bunx cogpit-memory` installs: transient native-dependency installation can race. Parallel calls to the installed CLI do not reinstall anything.
+
+JSON goes to stdout. Keep stderr separate when piping to `jq` or Python; never merge it with `2>&1` before a JSON parser. A JSON `{ "error": ... }` response exits nonzero and is a failed lookup, not an empty successful result. Use complete session IDs from discovery or search, not abbreviated IDs.
 
 ## Step 2 -- Find sessions
 
@@ -31,13 +33,13 @@ Then use `cogpit-memory` directly instead of `bunx cogpit-memory`.
 
 ```bash
 # List recent sessions (default: last 7 days, up to 20 results)
-bunx cogpit-memory sessions
+cogpit-memory sessions
 
 # Filter by working directory
-bunx cogpit-memory sessions --cwd /path/to/project
+cogpit-memory sessions --cwd /path/to/project
 
 # Customize limit and time window
-bunx cogpit-memory sessions --limit 50 --max-age 30d
+cogpit-memory sessions --limit 50 --max-age 30d
 ```
 
 Options:
@@ -53,7 +55,7 @@ Response: array of session summaries with `sessionId`, `cwd`, `model`, `firstMes
 ### Get current session for a directory
 
 ```bash
-bunx cogpit-memory sessions --current --cwd /path/to/project
+cogpit-memory sessions --current --cwd /path/to/project
 ```
 
 Returns the most recently active session for the given working directory. The `--cwd` flag is required when using `--current` (defaults to the current working directory if omitted).
@@ -63,7 +65,7 @@ Returns the most recently active session for the given working directory. The `-
 This gives you every user prompt and AI reply, plus a tool usage summary per turn. **You must call this before Layer 2 or Layer 3** -- it provides the `turnIndex` and `agentId` values you need for drill-downs.
 
 ```bash
-bunx cogpit-memory context <SESSION_ID>
+cogpit-memory context <SESSION_ID>
 ```
 
 Response shape:
@@ -117,7 +119,7 @@ Key fields:
 Use this to drill into a specific turn. Get thinking, full tool call inputs/outputs, and sub-agent summaries in chronological order.
 
 ```bash
-bunx cogpit-memory context <SESSION_ID> --turn <TURN_INDEX>
+cogpit-memory context <SESSION_ID> --turn <TURN_INDEX>
 ```
 
 Response shape:
@@ -154,7 +156,7 @@ Key details:
 - `contentBlocks` kinds: `thinking`, `text`, `tool_calls`, `sub_agent`, `background_agent`, `queued_prompt`, `hook_event`, `plan_mode`, `recap`, `agent_message`
 - Tool call `result` is truncated at 10,000 chars -- check `resultTruncated: true`
 - Tool call `result` may be `null` if the tool hasn't returned yet
-- Sub-agent blocks show prompt + result text. For full sub-agent conversation, use Layer 3
+- Sub-agent blocks show prompt + result text. When the provider writes a separate sub-agent transcript, use Layer 3 for the full conversation
 
 **Make separate requests per turn** -- do not try to batch multiple turns in one call.
 
@@ -163,7 +165,7 @@ Key details:
 Drill into a specific sub-agent's full conversation. Returns the same shape as Layer 1 (an overview of the sub-agent's own turns).
 
 ```bash
-bunx cogpit-memory context <SESSION_ID> --agent <AGENT_ID>
+cogpit-memory context <SESSION_ID> --agent <AGENT_ID>
 ```
 
 Get the `AGENT_ID` from Layer 1's `subAgents[].agentId` field.
@@ -188,7 +190,7 @@ Response shape:
 The `overview` field has the exact same shape as Layer 1. You can then drill into specific sub-agent turns:
 
 ```bash
-bunx cogpit-memory context <SESSION_ID> --agent <AGENT_ID> --turn <TURN_INDEX>
+cogpit-memory context <SESSION_ID> --agent <AGENT_ID> --turn <TURN_INDEX>
 ```
 
 This returns the same shape as Layer 2.
@@ -214,32 +216,42 @@ The typical workflow for drilling into sub-agent activity:
 
 1. Call Layer 1 to get the session overview
 2. Look at `turns[].subAgents[]` to find agent IDs
-3. Call Layer 3 with the `--agent` flag to get that sub-agent's overview
+3. If the provider writes a separate sub-agent transcript, call Layer 3 with the `--agent` flag to get that sub-agent's overview
 4. Call Layer 3 + `--turn` to drill into a specific sub-agent turn
 5. If the sub-agent itself had sub-agents, repeat from step 2 using the sub-agent's overview
 
 ## Session Search -- Find keywords across sessions
 
-Search for keywords across all sessions or within a specific session. Searches **everything**: user messages, assistant responses, thinking blocks, tool call inputs/results, sub-agent messages, sub-agent tool calls, and compaction summaries.
+Cross-session search indexes every provider's history. With `--session`, Claude Code, Codex, and Copilot CLI sessions are all supported, including user and assistant messages, thinking, tool I/O, inline sub-agent content, and compaction summaries when the provider records them.
 
 **When to use search vs Layer 1:**
 - You know the session -> Use Layer 1 overview, then drill with Layer 2/3
 - You need to **find** which session discussed something -> Use search first, then drill into hits
 
+When recalling earlier work, exclude this session if its ID is known, so your search commands and copied results do not crowd out history:
+
+```bash
+cogpit-memory search "authentication" --max-age 90d --exclude-session "$COGPIT_SESSION_ID"
+```
+
+Only pass that flag when the environment variable is set, or supply a known full session ID. Do not guess that the most recently modified session is yours when agents share a project. Omit the flag when searching this session itself. The exclusion also covers its indexed subagents.
+
+Search automatically removes index entries for transcript files that no longer exist. It cannot recover deleted transcripts. If a file disappears between search and `context`, report that the source is unavailable and continue with other hits.
+
 ### Basic usage
 
 ```bash
-# Search across all recent sessions (last 5 days)
-bunx cogpit-memory search "authentication"
+# Search recent indexed sessions from all supported CLIs (last 5 days)
+cogpit-memory search "authentication"
 
 # Search within a specific session
-bunx cogpit-memory search "authentication" --session <SESSION_ID>
+cogpit-memory search "authentication" --session <SESSION_ID>
 
 # Search with custom time window and more results
-bunx cogpit-memory search "authentication" --max-age 30d --limit 50
+cogpit-memory search "authentication" --max-age 30d --limit 50
 
 # Case-sensitive search
-bunx cogpit-memory search "AuthProvider" --case-sensitive
+cogpit-memory search "AuthProvider" --case-sensitive
 ```
 
 ### Options
@@ -247,6 +259,7 @@ bunx cogpit-memory search "AuthProvider" --case-sensitive
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--session` | all sessions | Scope to single session |
+| `--exclude-session` | none | Omit one session and its subagents |
 | `--max-age` | `5d` | Time window: `5d`, `12h`, `30d` |
 | `--limit` | `20` | Max total hits returned |
 | `--session-limit` | all | Cap unique sessions in results |
@@ -298,48 +311,45 @@ Locations map directly to Layer 2/3 drill-down commands -- use them to fetch ful
 - `turn/{i}/toolCall/{id}/input` -- tool call input -> drill with `--turn {i}`
 - `turn/{i}/toolCall/{id}/result` -- tool call result -> drill with `--turn {i}`
 - `turn/{i}/compactionSummary` -- compaction summary -> drill with `--turn {i}`
-- `agent/{agentId}/...` -- sub-agent content -> drill with `--agent {agentId}` then `--agent {agentId} --turn {i}`
+- `agent/{agentId}/...` -- sub-agent content; drill with `--agent {agentId}` only when the provider writes a separate transcript
 
 ### Typical workflow
 
-1. Search for keyword: `bunx cogpit-memory search "auth"`
+1. Search for keyword: `cogpit-memory search "auth"`
 2. Pick a hit from results (e.g., `sessionId: "abc-123"`, `location: "turn/3/assistantMessage"`)
-3. Get full turn context: `bunx cogpit-memory context abc-123 --turn 3`
-4. If hit is in a sub-agent, get agent overview first: `bunx cogpit-memory context abc-123 --agent a7f3bc2`
+3. Get full turn context: `cogpit-memory context abc-123 --turn 3`
+4. If a hit is in a sub-agent with a separate transcript, get its overview: `cogpit-memory context abc-123 --agent a7f3bc2`
 
-### Performance notes
+### Search behavior
 
-- Cross-session search uses a raw-text pre-filter -- files that can't match are skipped before expensive parsing
-- Default 5-day window keeps search fast; increase `--max-age` only if needed
-- Single-session search (`--session` flag) is much faster than cross-session
-- Typical cross-session search: ~150 sessions in ~1-2 seconds
+Cross-session search uses an incrementally updated SQLite FTS5 index, with a raw-file fallback if the index is unavailable. The default window is 5 days. Increase `--max-age` for older work. FTS matches whole tokens, so `auth` does not match `authentication`. `--limit` is capped at 200; narrow a broad query or use `--session` to investigate further.
 
 ## Index management
 
-The search index is an FTS5 trigram database at `~/.claude/cogpit-memory/search-index.db`. Most commands work without the index (falling back to raw file scanning), but indexed search is significantly faster.
+The search index is an FTS5 database at `~/.claude/cogpit-memory/search-index.db`. Most commands work without the index (falling back to raw file scanning), but indexed search is significantly faster.
 
 ```bash
 # Show index stats (session count, staleness, DB size)
-bunx cogpit-memory index stats
+cogpit-memory index stats
 
 # Rebuild the full index from scratch
-bunx cogpit-memory index rebuild
+cogpit-memory index rebuild
 ```
 
 ## Quick reference
 
 | Goal | Command |
 |------|---------|
-| List recent sessions | `bunx cogpit-memory sessions` |
-| Sessions for a directory | `bunx cogpit-memory sessions --cwd <path>` |
-| Current session for a directory | `bunx cogpit-memory sessions --current --cwd <path>` |
-| Session overview (always first) | `bunx cogpit-memory context <sessionId>` |
-| Turn detail | `bunx cogpit-memory context <sessionId> --turn <N>` |
-| Sub-agent overview | `bunx cogpit-memory context <sessionId> --agent <agentId>` |
-| Sub-agent turn detail | `bunx cogpit-memory context <sessionId> --agent <agentId> --turn <N>` |
-| **Search across sessions** | `bunx cogpit-memory search "<query>"` |
-| **Search single session** | `bunx cogpit-memory search "<query>" --session <sessionId>` |
-| Index stats | `bunx cogpit-memory index stats` |
-| Index rebuild | `bunx cogpit-memory index rebuild` |
+| List recent sessions | `cogpit-memory sessions` |
+| Sessions for a directory | `cogpit-memory sessions --cwd <path>` |
+| Current session for a directory | `cogpit-memory sessions --current --cwd <path>` |
+| Session overview (always first) | `cogpit-memory context <sessionId>` |
+| Turn detail | `cogpit-memory context <sessionId> --turn <N>` |
+| Sub-agent overview | `cogpit-memory context <sessionId> --agent <agentId>` |
+| Sub-agent turn detail | `cogpit-memory context <sessionId> --agent <agentId> --turn <N>` |
+| **Search indexed sessions** | `cogpit-memory search "<query>"` |
+| **Search any single provider session** | `cogpit-memory search "<query>" --session <sessionId>` |
+| Index stats | `cogpit-memory index stats` |
+| Index rebuild | `cogpit-memory index rebuild` |
 
 **Default to Layer 1 only. Drill into Layer 2/3 only when you have a specific reason.**

package/dist/lib/token-costs.d.ts

@@ -1,27 +0,0 @@
-/**
- * Token display estimation and cost formatting.
- *
- * Pricing lives in shared/usageCost/pricing.ts, driven by LiteLLM's live rate
- * table — nothing here carries hardcoded rates. What remains is display-only
- * accounting of the thinking/visible output split.
- *
- * Claude Code 2.1.19x+ reports thinking tokens directly on the assistant
- * record, so that half of the split is now exact. Older transcripts recorded
- * only the message_start placeholder usage, so they still fall back to a
- * content estimate at ≈4 chars/token — as does the visible-output half, which
- * the CLI does not break out.
- */
-import type { Turn } from "./types";
-/** Approximate characters per token for content-based estimation. */
-export declare const CHARS_PER_TOKEN = 4;
-/**
- * Thinking tokens for a turn: the count the model reported when it is
- * available, falling back to a character estimate for older transcripts.
- *
- * A reported 0 is a fact — a turn that did no thinking — so presence is tested
- * rather than truthiness.
- */
-export declare function estimateThinkingTokens(turn: Turn): number;
-/** Estimate non-thinking output tokens (text + tool use JSON). */
-export declare function estimateVisibleOutputTokens(turn: Turn): number;
-export declare function formatCost(usd: number): string;