cogpit-memory 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# cogpit-memory
+
+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.
+
+## Install
+
+```bash
+npm install -g cogpit-memory
+```
+
+Or run directly:
+
+```bash
+npx cogpit-memory sessions
+```
+
+## Quick Start
+
+```bash
+# List recent sessions
+cogpit-memory sessions
+
+# Get session overview
+cogpit-memory context <sessionId>
+
+# Drill into a specific turn
+cogpit-memory context <sessionId> --turn 3
+
+# Search across all sessions
+cogpit-memory search "authentication"
+```
+
+## Commands
+
+### `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
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--cwd` | all | Filter by working directory |
+| `--limit` | `20` | Max results |
+| `--max-age` | `7d` | Time window (`7d`, `12h`, `30d`) |
+| `--current` | — | Most recent session for `--cwd` |
+
+### `context` — Browse session content (layered)
+
+Three layers of detail — start at L1, drill down as needed.
+
+**Layer 1 — Session overview** (always start here):
+
+```bash
+cogpit-memory context <sessionId>
+```
+
+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>
+
+# Sub-agent turn detail (same shape as L2)
+cogpit-memory context <sessionId> --agent <agentId> --turn 0
+```
+
+### `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
+
+# Case-sensitive
+cogpit-memory search "AuthProvider" --case-sensitive
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--session` | all | Scope to single session |
+| `--max-age` | `5d` | Time window |
+| `--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.
+
+### `index` — Manage the FTS5 search index
+
+```bash
+cogpit-memory index stats     # Show index stats
+cogpit-memory index rebuild   # Rebuild from scratch
+```
+
+## Output
+
+All output is JSON to stdout, designed for programmatic consumption by AI agents.
+
+## 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.
+
+For search, it maintains an FTS5 trigram index at `~/.claude/cogpit-memory/search-index.db` for fast full-text search across all sessions.
+
+## Development
+
+Requires [Bun](https://bun.sh) for development (source uses `bun:sqlite`). The npm build uses `better-sqlite3` for Node.js compatibility.
+
+```bash
+# Run tests
+bun test
+
+# Build compiled binary (Bun, uses bun:sqlite)
+bun run build
+
+# Build for npm (Node.js, uses better-sqlite3)
+bun run build:npm
+```
+
+## License
+
+MIT