cogpit-memory 0.1.1 → 0.1.2

package/README.md

@@ -2,6 +2,8 @@
 
 CLI tool that gives any AI assistant memory of past [Claude Code](https://docs.anthropic.com/en/docs/claude-code) sessions. Retrieve conversation history, tool usage, thinking blocks, sub-agent activity, and full-text search across all sessions.
 
+All output is JSON to stdout — designed for programmatic consumption by AI agents.
+
 ## Install
 
 ```bash
@@ -35,17 +37,10 @@ cogpit-memory search "authentication"
 ### `sessions` — Discover sessions
 
 ```bash
-# Recent sessions (last 7 days)
-cogpit-memory sessions
-
-# Filter by project directory
-cogpit-memory sessions --cwd /path/to/project
-
-# Get most recent session for a directory
-cogpit-memory sessions --current --cwd /path/to/project
-
-# Custom time window and limit
-cogpit-memory sessions --max-age 30d --limit 50
+cogpit-memory sessions                              # Recent sessions (last 7 days)
+cogpit-memory sessions --cwd /path/to/project       # Filter by project
+cogpit-memory sessions --current --cwd /path/to/project  # Most recent for a project
+cogpit-memory sessions --max-age 30d --limit 50     # Custom window
 ```
 
 | Flag | Default | Description |
@@ -55,50 +50,28 @@ cogpit-memory sessions --max-age 30d --limit 50
 | `--max-age` | `7d` | Time window (`7d`, `12h`, `30d`) |
 | `--current` | — | Most recent session for `--cwd` |
 
-### `context` — Browse session content (layered)
+### `context` — Layered session drill-down
 
-Three layers of detail — start at L1, drill down as needed.
-
-**Layer 1 — Session overview** (always start here):
-
-```bash
-cogpit-memory context <sessionId>
-```
+Three layers of detail. Start at L1, drill down only as needed.
 
-Returns every turn with user prompt, assistant reply, tool usage summary, and sub-agent list.
-
-**Layer 2 — Turn detail:**
-
-```bash
-cogpit-memory context <sessionId> --turn 3
-```
-
-Returns thinking blocks, full tool call inputs/outputs, and sub-agent summaries in chronological order.
-
-**Layer 3 — Sub-agent detail:**
-
-```bash
-# Sub-agent overview (same shape as L1)
-cogpit-memory context <sessionId> --agent <agentId>
+| Layer | Command | What you get |
+|-------|---------|-------------|
+| **L1** — Overview | `cogpit-memory context <sessionId>` | Every turn: user prompt, assistant reply, tool summary, sub-agent list |
+| **L2** — Turn detail | `cogpit-memory context <sessionId> --turn 3` | Thinking blocks, full tool call I/O, sub-agent summaries (chronological) |
+| **L3** — Sub-agent | `cogpit-memory context <sessionId> --agent <agentId>` | Full sub-agent conversation (same shape as L1) |
+| **L3** — Sub-agent turn | `cogpit-memory context <sessionId> --agent <agentId> --turn 0` | Sub-agent turn detail (same shape as L2) |
 
-# Sub-agent turn detail (same shape as L2)
-cogpit-memory context <sessionId> --agent <agentId> --turn 0
-```
+**Discovery flow:** L1 gives you `turnIndex` and `agentId` values → use those to drill into L2/L3.
 
 ### `search` — Full-text search with FTS5
 
-```bash
-# Search across all recent sessions
-cogpit-memory search "authentication"
-
-# Scope to a single session
-cogpit-memory search "auth" --session <sessionId>
-
-# Custom time window
-cogpit-memory search "bug" --max-age 30d --limit 50
+Searches everything: user messages, assistant responses, thinking blocks, tool call inputs/outputs, sub-agent content, and compaction summaries.
 
-# Case-sensitive
-cogpit-memory search "AuthProvider" --case-sensitive
+```bash
+cogpit-memory search "authentication"                        # Cross-session search
+cogpit-memory search "auth" --session <sessionId>            # Single session
+cogpit-memory search "bug" --max-age 30d --limit 50          # Custom window
+cogpit-memory search "AuthProvider" --case-sensitive          # Case-sensitive
 ```
 
 | Flag | Default | Description |
@@ -108,31 +81,51 @@ cogpit-memory search "AuthProvider" --case-sensitive
 | `--limit` | `20` | Max returned hits |
 | `--case-sensitive` | `false` | Case sensitivity |
 
-Searches everything: user messages, assistant responses, thinking blocks, tool call inputs/outputs, sub-agent content, and compaction summaries.
+Each hit includes a `location` string (e.g. `turn/3/assistantMessage`, `agent/a7f3bc2/toolCall/tc1/result`) that maps directly to L2/L3 drill-down commands.
 
 ### `index` — Manage the FTS5 search index
 
 ```bash
-cogpit-memory index stats     # Show index stats
+cogpit-memory index stats     # Show index stats (session count, DB size, staleness)
 cogpit-memory index rebuild   # Rebuild from scratch
 ```
 
-## Output
+## Performance
+
+Benchmarked against a real Claude Code history: **765 sessions, 1,745 sub-agents, 210K indexed rows, 1.4 GB index**.
+
+| Operation | Time | Notes |
+|-----------|------|-------|
+| `sessions --limit 20` | **38ms** | File-system scan, no DB needed |
+| `context <sessionId>` (L1) | **34ms** | Single JSONL file parse |
+| `context <sessionId> --turn N` (L2) | **35ms** | Same file, filtered to one turn |
+| `search "keyword"` (cross-session) | **56–200ms** | FTS5 trigram across 210K rows |
+| `search "keyword" --session <id>` | **30ms** | Scoped to single session |
+| `index stats` | **50ms** | Single DB query |
 
-All output is JSON to stdout, designed for programmatic consumption by AI agents.
+### Scaling characteristics
+
+| History size | Sessions | Indexed rows | DB size | Cross-session search |
+|-------------|----------|-------------|---------|---------------------|
+| Light (3 months) | ~200 | ~50K | ~350 MB | <50ms |
+| Moderate (6 months) | ~800 | ~210K | ~1.4 GB | 50–200ms |
+| Heavy (1 year) | ~2,000 | ~500K | ~3.5 GB | 100–400ms |
+| Power user (2+ years) | ~5,000 | ~1.2M | ~8 GB | 200–800ms |
+
+FTS5 trigram search is sublinear — doubling the index size does not double query time. The index uses SQLite WAL mode for concurrent reads and is incrementally updated.
 
 ## How It Works
 
-cogpit-memory reads Claude Code's JSONL session files from `~/.claude/projects/`. It parses the conversation structure and provides a layered drill-down interface.
+cogpit-memory reads Claude Code's JSONL session files from `~/.claude/projects/`. It parses the conversation structure (turns, tool calls, thinking blocks, sub-agents) and provides a layered drill-down interface.
 
-For search, it maintains an FTS5 trigram index at `~/.claude/cogpit-memory/search-index.db` for fast full-text search across all sessions.
+For search, it maintains an FTS5 trigram index at `~/.claude/cogpit-memory/search-index.db`. The trigram tokenizer enables substring matching (not just whole-word) — searching for `"auth"` matches `"authentication"`, `"OAuth"`, and `"AuthProvider"`.
 
 ## Development
 
-Requires [Bun](https://bun.sh) for development (source uses `bun:sqlite`). The npm build uses `better-sqlite3` for Node.js compatibility.
+Requires [Bun](https://bun.sh) for development (source uses `bun:sqlite`). The npm build uses `better-sqlite3` for Node.js compatibility via an esbuild alias.
 
 ```bash
-# Run tests
+# Run tests (82 tests)
 bun test
 
 # Build compiled binary (Bun, uses bun:sqlite)
@@ -142,6 +135,20 @@ bun run build
 bun run build:npm
 ```
 
+## Claude Code Skill
+
+cogpit-memory ships with a [Claude Code skill](https://docs.anthropic.com/en/docs/claude-code/skills) that teaches Claude how to use it automatically — layered drill-down, search workflows, and all command options.
+
+```bash
+# Install the skill into the current project
+npx cogpit-memory install-skill
+
+# Or specify a project directory
+npx cogpit-memory install-skill --cwd /path/to/project
+```
+
+This creates `.claude/skills/cogpit-memory/SKILL.md` in your project. Once installed, Claude Code will automatically use `cogpit-memory` when it needs to recall past session context or search conversation history.
+
 ## License
 
 MIT

package/dist/cli.js

@@ -2064,6 +2064,43 @@ async function indexRebuild(dbPath) {
   return { status: "rebuilt", stats };
 }
 
+// src/commands/install-skill.ts
+var import_node_fs4 = require("node:fs");
+var import_node_path8 = require("node:path");
+var import_node_url = require("node:url");
+var import_meta = {};
+function findSkillContent() {
+  const candidates = [];
+  if (typeof __dirname !== "undefined") {
+    candidates.push((0, import_node_path8.join)(__dirname, "..", "skill", "SKILL.md"));
+    candidates.push((0, import_node_path8.join)(__dirname, "..", "..", "skill", "SKILL.md"));
+  }
+  try {
+    const thisDir = (0, import_node_path8.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
+    candidates.push((0, import_node_path8.join)(thisDir, "..", "skill", "SKILL.md"));
+    candidates.push((0, import_node_path8.join)(thisDir, "..", "..", "skill", "SKILL.md"));
+  } catch {
+  }
+  for (const candidate of candidates) {
+    try {
+      if ((0, import_node_fs4.existsSync)(candidate)) {
+        return (0, import_node_fs4.readFileSync)(candidate, "utf-8");
+      }
+    } catch {
+    }
+  }
+  throw new Error("Could not find SKILL.md \u2014 try reinstalling cogpit-memory");
+}
+function installSkill(cwd) {
+  const root = cwd ?? process.cwd();
+  const skillDir = (0, import_node_path8.join)(root, ".claude", "skills", "cogpit-memory");
+  (0, import_node_fs4.mkdirSync)(skillDir, { recursive: true });
+  const content = findSkillContent();
+  const dest = (0, import_node_path8.join)(skillDir, "SKILL.md");
+  (0, import_node_fs4.writeFileSync)(dest, content);
+  return { installed: true, path: skillDir };
+}
+
 // src/cli.ts
 function parseArgs(argv) {
   const command = argv[0];
@@ -2126,6 +2163,16 @@ function parseArgs(argv) {
       args.subcommand = argv[1] ?? "stats";
       break;
     }
+    case "install-skill": {
+      for (let i = 1; i < argv.length; i++) {
+        switch (argv[i]) {
+          case "--cwd":
+            args.cwd = argv[++i];
+            break;
+        }
+      }
+      break;
+    }
   }
   return { command, args };
 }
@@ -2183,6 +2230,9 @@ async function main() {
         result = await indexStats();
       }
       break;
+    case "install-skill":
+      result = installSkill(cmd.args.cwd);
+      break;
     default:
       console.error(JSON.stringify({ error: `Unknown command: ${cmd.command}` }));
       printUsage();
@@ -2212,6 +2262,8 @@ Commands:
 
   index stats                 Show index stats
   index rebuild               Rebuild full index
+
+  install-skill [--cwd path]  Install Claude Code skill to .claude/skills/
 `);
 }
 var isBunCompiled = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cogpit-memory",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "CLI tool for Claude Code session introspection — search, browse, and drill into past sessions",
   "main": "./dist/index.js",
   "types": "./src/index.ts",
@@ -8,7 +8,8 @@
     "cogpit-memory": "./dist/cli.js"
   },
   "files": [
-    "dist/"
+    "dist/",
+    "skill/"
   ],
   "scripts": {
     "test": "bun test",

package/skill/SKILL.md

@@ -0,0 +1,342 @@
+---
+name: cogpit-memory
+description: CLI tool for Claude Code session introspection -- retrieves conversation history, tool calls, thinking, sub-agent/team activity, full-text search, and session discovery. All output is JSON to stdout.
+---
+
+# Cogpit Memory -- Session Context CLI
+
+CLI tool that gives any AI assistant memory of past Claude Code sessions. Retrieve conversation history, tool usage, thinking, and sub-agent activity via a layered command structure. **Also supports full-text search across all sessions** and session discovery/listing.
+
+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
+
+```bash
+bunx cogpit-memory --help
+```
+
+If this prints usage info, proceed to Step 2. If `bunx` is not available, install the package globally:
+
+```bash
+npm install -g cogpit-memory
+```
+
+Then use `cogpit-memory` directly instead of `bunx cogpit-memory`.
+
+## Step 2 -- Find sessions
+
+### List recent sessions
+
+```bash
+# List recent sessions (default: last 7 days, up to 20 results)
+bunx cogpit-memory sessions
+
+# Filter by working directory
+bunx cogpit-memory sessions --cwd /path/to/project
+
+# Customize limit and time window
+bunx cogpit-memory sessions --limit 50 --max-age 30d
+```
+
+Options:
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--limit` | `20` | Max results |
+| `--max-age` | `7d` | Time window: `7d`, `12h`, `30d` |
+| `--cwd` | all | Filter by working directory |
+
+Response: array of session summaries with `sessionId`, `cwd`, `model`, `firstMessage`, `lastMessage`, `turnCount`, `status`, `mtime`.
+
+### Get current session for a directory
+
+```bash
+bunx 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).
+
+## Step 3 -- Layer 1: Get session overview (ALWAYS call this first)
+
+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>
+```
+
+Response shape:
+```json
+{
+  "sessionId": "abc-123",
+  "cwd": "/path/to/project",
+  "model": "claude-opus-4-6",
+  "branchedFrom": null,
+  "compacted": false,
+  "turns": [
+    {
+      "turnIndex": 0,
+      "userMessage": "Fix the auth bug",
+      "assistantMessage": "I found the issue...",
+      "toolSummary": { "Edit": 2, "Read": 3 },
+      "subAgents": [
+        {
+          "agentId": "a7f3bc2",
+          "name": "researcher",
+          "type": "Explore",
+          "status": "success",
+          "durationMs": 12300,
+          "toolUseCount": 8,
+          "isBackground": false
+        }
+      ],
+      "hasThinking": true,
+      "isError": false,
+      "compactionSummary": null
+    }
+  ],
+  "stats": {
+    "totalTurns": 5,
+    "totalToolCalls": 23,
+    "totalTokens": { "input": 45000, "output": 12000 }
+  }
+}
+```
+
+Key fields:
+- `userMessage` -- the human's full prompt text (`null` for synthetic turns, images shown as `[image attached]`)
+- `assistantMessage` -- the AI's full text response (`null` if only tools ran)
+- `toolSummary` -- tool name to count (e.g., `{"Read": 5, "Edit": 2}`)
+- `subAgents` -- summary of sub-agents that ran in this turn. Fields `status`, `durationMs`, `toolUseCount` may be `null` for older sessions
+- `hasThinking` -- whether thinking blocks exist (boolean only; full text is in Layer 2)
+- `compacted` -- `true` if the session was compacted (early context compressed)
+
+## Step 4 -- Layer 2: Get turn detail (one turn at a time)
+
+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>
+```
+
+Response shape:
+```json
+{
+  "sessionId": "abc-123",
+  "turnIndex": 0,
+  "userMessage": "Fix the auth bug",
+  "contentBlocks": [
+    { "kind": "thinking", "text": "Let me analyze...", "timestamp": "..." },
+    { "kind": "text", "text": "I found the issue.", "timestamp": "..." },
+    {
+      "kind": "tool_calls",
+      "toolCalls": [
+        { "id": "tc1", "name": "Edit", "input": { "file_path": "/a.ts" }, "result": "done", "resultTruncated": false, "isError": false }
+      ],
+      "timestamp": "..."
+    },
+    {
+      "kind": "sub_agent",
+      "agents": [
+        { "agentId": "a7f3bc2", "name": "researcher", "type": "Explore", "prompt": "Find auth files", "resultText": "Found 3 files...", "status": "success", "durationMs": 12300, "toolUseCount": 8, "isBackground": false }
+      ],
+      "timestamp": "..."
+    }
+  ],
+  "tokenUsage": { "input": 8000, "output": 2500 },
+  "model": "claude-opus-4-6",
+  "durationMs": 15000
+}
+```
+
+Key details:
+- `contentBlocks` kinds: `thinking`, `text`, `tool_calls`, `sub_agent`, `background_agent`
+- 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
+
+**Make separate requests per turn** -- do not try to batch multiple turns in one call.
+
+## Step 5 -- Layer 3: Get sub-agent / team member detail
+
+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>
+```
+
+Get the `AGENT_ID` from Layer 1's `subAgents[].agentId` field.
+
+Response shape:
+```json
+{
+  "sessionId": "abc-123",
+  "agentId": "a7f3bc2",
+  "name": "researcher",
+  "type": "Explore",
+  "parentToolCallId": "tc5",
+  "isBackground": false,
+  "teamContext": null,
+  "overview": {
+    "turns": [ "..." ],
+    "stats": { "..." }
+  }
+}
+```
+
+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>
+```
+
+This returns the same shape as Layer 2.
+
+### Team context
+
+If the sub-agent is a team member, `teamContext` will be populated:
+```json
+{
+  "teamContext": {
+    "teamName": "admin-ui-redesign",
+    "role": "layout-dev",
+    "currentTask": { "id": "3", "subject": "Redesign layout.tsx", "status": "in_progress" }
+  }
+}
+```
+
+**Note:** Team members using `tmux` backend are not accessible via this command (they run as separate sessions).
+
+## Discovery chain
+
+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
+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.
+
+**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
+
+### Basic usage
+
+```bash
+# Search across all recent sessions (last 5 days)
+bunx cogpit-memory search "authentication"
+
+# Search within a specific session
+bunx 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
+
+# Case-sensitive search
+bunx cogpit-memory search "AuthProvider" --case-sensitive
+```
+
+### Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--session` | all sessions | Scope to single session |
+| `--max-age` | `5d` | Time window: `5d`, `12h`, `30d` |
+| `--limit` | `20` | Max returned hits |
+| `--case-sensitive` | `false` | Case sensitivity |
+
+### Response shape
+
+```json
+{
+  "query": "authentication",
+  "totalHits": 47,
+  "returnedHits": 20,
+  "sessionsSearched": 8,
+  "results": [
+    {
+      "sessionId": "abc-123",
+      "hits": [
+        {
+          "location": "turn/3/userMessage",
+          "snippet": "...need to fix the authentication flow before...",
+          "matchCount": 2
+        },
+        {
+          "location": "turn/5/toolCall/tc_abc/result",
+          "toolName": "Read",
+          "snippet": "...export function authentication(req, res)...",
+          "matchCount": 1
+        },
+        {
+          "location": "agent/a7f3bc2/turn/1/assistantMessage",
+          "agentName": "researcher",
+          "snippet": "...found 3 authentication-related files in...",
+          "matchCount": 1
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Location format
+
+Locations map directly to Layer 2/3 drill-down commands -- use them to fetch full context:
+- `turn/{i}/userMessage` -- user prompt -> drill with `--turn {i}`
+- `turn/{i}/assistantMessage` -- AI response -> drill with `--turn {i}`
+- `turn/{i}/thinking` -- thinking blocks -> drill with `--turn {i}`
+- `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}`
+
+### Typical workflow
+
+1. Search for keyword: `bunx 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`
+
+### Performance notes
+
+- 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
+
+## 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.
+
+```bash
+# Show index stats (session count, staleness, DB size)
+bunx cogpit-memory index stats
+
+# Rebuild the full index from scratch
+bunx 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` |
+
+**Default to Layer 1 only. Drill into Layer 2/3 only when you have a specific reason.**