|
| 1 | +--- |
| 2 | +name: rekal |
| 3 | +description: | |
| 4 | + Use this skill when working in a repo with Rekal initialized (.rekal/ exists). |
| 5 | + Rekal gives you memory of prior AI sessions — who changed what, why, and when. |
| 6 | + Start with `rekal "keyword"` to search, then drill into sessions with |
| 7 | + `rekal query --session <id>`. Run `rekal <command> --help` for full details. |
| 8 | +--- |
| 9 | + |
| 10 | +# Rekal — Session Memory |
| 11 | + |
| 12 | +Rekal captures AI coding sessions (conversation turns, tool calls, file changes) and stores them in a local DuckDB database. Use it to understand prior context before modifying code. |
| 13 | + |
| 14 | +## When to Use |
| 15 | + |
| 16 | +- Before modifying a file — check what prior sessions touched it |
| 17 | +- When you need context about why code looks the way it does |
| 18 | +- When the user asks about prior session history |
| 19 | +- When working on files that were recently changed by AI agents |
| 20 | + |
| 21 | +## Workflow |
| 22 | + |
| 23 | +### 1. Search — find relevant sessions |
| 24 | + |
| 25 | +```bash |
| 26 | +rekal "JWT expiry" # keyword search (BM25 + LSA hybrid) |
| 27 | +rekal --file src/auth/ "token refresh" # filter by file path (regex) |
| 28 | +rekal --actor agent "migration" # filter by actor type |
| 29 | +rekal --author alice@co.com "billing" # filter by author |
| 30 | +rekal -n 5 "error handling" # limit results |
| 31 | +``` |
| 32 | + |
| 33 | +Output is scored JSON with session IDs, snippets, and metadata. |
| 34 | + |
| 35 | +### 2. Drill down — progressive context loading |
| 36 | + |
| 37 | +Always start small to minimize token cost, then load more only when needed. |
| 38 | + |
| 39 | +```bash |
| 40 | +# Step 1: Start with human turns only — understand the intent cheaply |
| 41 | +rekal query --session 01JNQX... --role human |
| 42 | + |
| 43 | +# Step 2: If you need more detail, fetch a small page around a relevant turn |
| 44 | +# (search results include turn indices — use them as offset) |
| 45 | +rekal query --session 01JNQX... --offset 5 --limit 5 |
| 46 | + |
| 47 | +# Step 3: Only fetch full output when you actually need tool calls and files |
| 48 | +rekal query --session 01JNQX... --full |
| 49 | +``` |
| 50 | + |
| 51 | +Output includes `total_turns`, `offset`, `limit`, and `has_more` for navigation. |
| 52 | + |
| 53 | +Do NOT load all turns or use `--full` by default. The search results from step 1 give you |
| 54 | +enough context to decide what slice to load next. |
| 55 | + |
| 56 | +### 3. Raw SQL — for edge cases |
| 57 | + |
| 58 | +```bash |
| 59 | +rekal query "SELECT id, user_email, branch FROM sessions ORDER BY captured_at DESC LIMIT 5" |
| 60 | +rekal query --index "SELECT * FROM file_cooccurrence WHERE file_a LIKE '%auth%' ORDER BY count DESC" |
| 61 | +``` |
| 62 | + |
| 63 | +Run `rekal query --help` for the full data DB and index DB schemas. |
| 64 | + |
| 65 | +## Filters (root command) |
| 66 | + |
| 67 | +| Flag | Description | |
| 68 | +|------|-------------| |
| 69 | +| `--file <regex>` | Filter by file path (regex, git-root-relative) | |
| 70 | +| `--commit <sha>` | Filter by git commit SHA | |
| 71 | +| `--author <email>` | Filter by author email | |
| 72 | +| `--actor <human\|agent>` | Filter by actor type | |
| 73 | +| `-n`, `--limit <n>` | Max results (default: 20, 0 = no limit) | |
| 74 | + |
| 75 | +## Self-Service |
| 76 | + |
| 77 | +Run `rekal <command> --help` for detailed help on any command, including |
| 78 | +the full DB schemas (`rekal query --help`). |
| 79 | + |
| 80 | +## Guidelines |
| 81 | + |
| 82 | +- Search before modifying files that have prior session history |
| 83 | +- Start with `rekal "keyword"` — only drop to raw SQL when the search workflow doesn't cover your need |
| 84 | +- Human turns contain the intent; assistant turns contain the reasoning |
| 85 | +- `actor_type` distinguishes human-initiated sessions from automated agent sessions |
| 86 | +- Join `turns` with `tool_calls` via `session_id` to get context around file changes |
0 commit comments