crispy-recall 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sylvester Wong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# crispy-recall
+
+Searchable memory for your Claude Code and Codex sessions. Local, fast, no daemon.
+
+**Status:** in development.
+
+A standalone spin-off of the recall feature from [Crispy](https://github.com/TheSylvester/crispy). See the parent project for the broader multi-agent orchestration GUI.
+
+## Install
+
+Install the command globally, then run the one-time setup:
+
+```bash
+npm install -g crispy-recall
+recall install
+```
+
+`recall install` is the resident setup step. It scaffolds `~/.recall/` (the
+llama embedding binary, the model, and the SQLite DB), wires a Stop hook into
+Claude Code so your transcripts are indexed automatically as sessions end, and
+installs the `recall` skill. If Codex is detected it also gets the `recall`
+skill (so the agent can search), but not an automatic per-turn hook in v0.1.0 —
+index Codex history with `recall backfill --vendor codex`. After that, recall
+runs passively — you only invoke `recall` directly for `status`, `doctor`,
+`repair`, or `uninstall`.
+
+Run it in the environment where you actually use Claude Code: **WSL and
+Windows-native are separate installs.** If you use both, run the install in each
+— the installer only configures the environment it is invoked in.
+
+> **Don't install via `npx`.** recall must stay resident. `npx` runs from an
+> ephemeral cache and leaves no `recall` command on your PATH, so follow-up
+> commands (`recall status` / `doctor` / `repair` / `uninstall`) and the
+> installed skill's command contract have nothing to call. Use the global
+> install above.
+
+Prerequisites: Node ≥ 20 and Claude Code installed. If Codex is detected
+(`~/.codex/` exists), recall installs the `recall` skill into Codex (so the
+agent can search) and you can index your Codex history with
+`recall backfill --vendor codex`. Real-time per-turn Codex indexing is **not**
+in v0.1.0.
+
+## What it does
+
+- A **Stop hook** ingests every turn into a local SQLite DB the moment a session ends — no daemon, no background polling.
+- The CLI **searches** your history two ways at once: FTS5 full-text and semantic vectors (Nomic Embed Text v1.5, run locally via llama.cpp).
+- A **`recall` skill** is dropped into Claude Code so the agent discovers and invokes it on its own — you rarely type `recall` yourself.
+- Works in **any project**. Claude Code sessions are indexed automatically; Codex transcripts are searchable too via `recall backfill --vendor codex`.
+
+## How an agent uses it
+
+Two steps. First, search for the relevant session:
+
+```bash
+$RECALL_BIN "the thing you're trying to remember"
+```
+
+That returns a table of matching sessions. Then read one, centered on the match:
+
+```bash
+$RECALL_BIN <session-id> <message-id>
+```
+
+The skill's frontmatter teaches Claude *when* to reach for this (before
+non-trivial tasks, architectural decisions, or work with obvious prior
+history), so in practice the agent calls it for you.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `recall install` | One-time setup: scaffold `~/.recall/`, wire the Stop hook, install the skill. |
+| `recall uninstall` | Reverse the install (skill, hook, CLAUDE.md block). `--purge` also removes `~/.recall/`. |
+| `recall status` | DB size, message count, last ingest, embedding gap, active backfill PID, GPU/CPU backend. |
+| `recall doctor` | Read-only health check (the install pre-flight suite). `--integrity` runs DB + FTS5 checks. |
+| `recall repair --fts \| --vectors \| --full` | Rebuild the FTS index, re-embed vectors, or full reingest from JSONL. |
+| `recall backfill [--auto-embed] [--vendor <v>] [--detach]` | Index historical transcripts. |
+
+## Where things live
+
+- `~/.recall/` — the DB, model, binary, logs, and `config.json` (the resolved GPU/CPU embedder mode).
+- `~/.claude/skills/recall/SKILL.md` — the auto-discovered skill.
+- A hook entry in `~/.claude/settings.json`.
+
+`recall uninstall` reverses all three. `recall uninstall --purge` also removes `~/.recall/`.
+
+## Privacy
+
+Everything is local. No telemetry, no network calls except the one-time
+binary + model download at install. The DB is plain SQLite — open it with any
+SQLite browser if you want to poke around.
+
+## Troubleshooting
+
+Run `recall doctor` — it reports platform, harness, runtime, disk, network, and
+the resolved embedding backend, with remediation hints for anything off.
+
+## Attribution
+
+Lifted and adapted from the recall subsystem of
+[Crispy](https://github.com/TheSylvester/crispy), the Claude Code / Codex GUI.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/THIRD-PARTY-LICENSES

@@ -0,0 +1,164 @@
+THIRD-PARTY LICENSES — crispy-recall
+=====================================
+
+crispy-recall is MIT-licensed (see LICENSE). It bundles or downloads the
+third-party components below. All production npm dependencies are permissive
+(MIT / ISC / BSD / BlueOak-1.0.0).
+
+Bundled-via-download artifacts (not npm packages):
+  - llama-embedding (from the llama.cpp project) ............ MIT
+  - Nomic Embed Text v1.5 (model weights, Nomic AI) ......... Apache-2.0
+  - node-sqlite3-wasm ...................................... MIT
+  - SQLite (compiled into node-sqlite3-wasm) ............... Public Domain
+  - libggml-cuda.so (built from llama.cpp @ b5300, GPU only)  MIT
+
+Regenerate after a production-dependency change with:
+  npx license-checker-rseidelsohn --production --out THIRD-PARTY-LICENSES
+
+npm production dependencies (transitive closure):
+  @anthropic-ai/claude-agent-sdk-linux-x64-musl@0.2.114  —  Custom: LICENSE.md
+  @anthropic-ai/claude-agent-sdk-linux-x64@0.2.114  —  Custom: LICENSE.md
+  @anthropic-ai/claude-agent-sdk@0.2.114  —  Custom: README.md
+  @anthropic-ai/sdk@0.81.0  —  MIT
+  @babel/runtime@7.29.2  —  MIT
+  @clack/core@0.3.5  —  MIT
+  @clack/prompts@0.7.0  —  MIT
+  @hono/node-server@1.19.14  —  MIT
+  @isaacs/cliui@8.0.2  —  ISC
+  @modelcontextprotocol/sdk@1.29.0  —  MIT
+  @pkgjs/parseargs@0.11.0  —  MIT
+  @types/node@20.19.41  —  MIT
+  @types/yauzl@2.10.3  —  MIT
+  accepts@2.0.0  —  MIT
+  ajv-formats@3.0.1  —  MIT
+  ajv@8.20.0  —  MIT
+  ansi-regex@5.0.1  —  MIT
+  ansi-regex@6.2.2  —  MIT
+  ansi-styles@4.3.0  —  MIT
+  ansi-styles@6.2.3  —  MIT
+  balanced-match@1.0.2  —  MIT
+  body-parser@2.2.2  —  MIT
+  brace-expansion@2.1.0  —  MIT
+  buffer-crc32@0.2.13  —  MIT
+  bytes@3.1.2  —  MIT
+  call-bind-apply-helpers@1.0.2  —  MIT
+  call-bound@1.0.4  —  MIT
+  color-convert@2.0.1  —  MIT
+  color-name@1.1.4  —  MIT
+  content-disposition@1.1.0  —  MIT
+  content-type@1.0.5  —  MIT
+  content-type@2.0.0  —  MIT
+  cookie-signature@1.2.2  —  MIT
+  cookie@0.7.2  —  MIT
+  cors@2.8.6  —  MIT
+  crispy-recall@0.1.0  —  MIT
+  cross-spawn@7.0.6  —  MIT
+  debug@4.4.3  —  MIT
+  depd@2.0.0  —  MIT
+  dunder-proto@1.0.1  —  MIT
+  eastasianwidth@0.2.0  —  MIT
+  ee-first@1.1.1  —  MIT
+  emoji-regex@8.0.0  —  MIT
+  emoji-regex@9.2.2  —  MIT
+  encodeurl@2.0.0  —  MIT
+  end-of-stream@1.4.5  —  MIT
+  es-define-property@1.0.1  —  MIT
+  es-errors@1.3.0  —  MIT
+  es-object-atoms@1.1.1  —  MIT
+  escape-html@1.0.3  —  MIT
+  etag@1.8.1  —  MIT
+  eventsource-parser@3.0.8  —  MIT
+  eventsource@3.0.7  —  MIT
+  express-rate-limit@8.5.2  —  MIT
+  express@5.2.1  —  MIT
+  extract-zip@2.0.1  —  BSD-2-Clause
+  fast-deep-equal@3.1.3  —  MIT
+  fast-uri@3.1.2  —  BSD-3-Clause
+  fd-slicer@1.1.0  —  MIT
+  finalhandler@2.1.1  —  MIT
+  foreground-child@3.3.1  —  ISC
+  forwarded@0.2.0  —  MIT
+  fresh@2.0.0  —  MIT
+  function-bind@1.1.2  —  MIT
+  get-intrinsic@1.3.0  —  MIT
+  get-proto@1.0.1  —  MIT
+  get-stream@5.2.0  —  MIT
+  glob@10.5.0  —  ISC
+  gopd@1.2.0  —  MIT
+  has-symbols@1.1.0  —  MIT
+  hasown@2.0.3  —  MIT
+  hono@4.12.19  —  MIT
+  http-errors@2.0.1  —  MIT
+  iconv-lite@0.7.2  —  MIT
+  inherits@2.0.4  —  ISC
+  ip-address@10.2.0  —  MIT
+  ipaddr.js@1.9.1  —  MIT
+  is-fullwidth-code-point@3.0.0  —  MIT
+  is-promise@4.0.0  —  MIT
+  is-unicode-supported@1.3.0  —  MIT
+  isexe@2.0.0  —  ISC
+  jackspeak@3.4.3  —  BlueOak-1.0.0
+  jose@6.2.3  —  MIT
+  json-schema-to-ts@3.1.1  —  MIT
+  json-schema-traverse@1.0.0  —  MIT
+  json-schema-typed@8.0.2  —  BSD-2-Clause
+  lru-cache@10.4.3  —  ISC
+  math-intrinsics@1.1.0  —  MIT
+  media-typer@1.1.0  —  MIT
+  merge-descriptors@2.0.0  —  MIT
+  mime-db@1.54.0  —  MIT
+  mime-types@3.0.2  —  MIT
+  minimatch@9.0.9  —  ISC
+  minipass@7.1.3  —  BlueOak-1.0.0
+  ms@2.1.3  —  MIT
+  negotiator@1.0.0  —  MIT
+  node-sqlite3-wasm@0.8.57  —  MIT
+  object-assign@4.1.1  —  MIT
+  object-inspect@1.13.4  —  MIT
+  on-finished@2.4.1  —  MIT
+  once@1.4.0  —  ISC
+  package-json-from-dist@1.0.1  —  BlueOak-1.0.0
+  parseurl@1.3.3  —  MIT
+  path-key@3.1.1  —  MIT
+  path-scurry@1.11.1  —  BlueOak-1.0.0
+  path-to-regexp@8.4.2  —  MIT
+  pend@1.2.0  —  MIT
+  picocolors@1.1.1  —  ISC
+  pkce-challenge@5.0.1  —  MIT
+  proxy-addr@2.0.7  —  MIT
+  pump@3.0.4  —  MIT
+  qs@6.15.2  —  BSD-3-Clause
+  range-parser@1.2.1  —  MIT
+  raw-body@3.0.2  —  MIT
+  require-from-string@2.0.2  —  MIT
+  router@2.2.0  —  MIT
+  safer-buffer@2.1.2  —  MIT
+  send@1.2.1  —  MIT
+  serve-static@2.2.1  —  MIT
+  setprototypeof@1.2.0  —  ISC
+  shebang-command@2.0.0  —  MIT
+  shebang-regex@3.0.0  —  MIT
+  side-channel-list@1.0.1  —  MIT
+  side-channel-map@1.0.1  —  MIT
+  side-channel-weakmap@1.0.2  —  MIT
+  side-channel@1.1.0  —  MIT
+  signal-exit@4.1.0  —  ISC
+  sisteransi@1.0.5  —  MIT
+  statuses@2.0.2  —  MIT
+  string-width@4.2.3  —  MIT
+  string-width@5.1.2  —  MIT
+  strip-ansi@6.0.1  —  MIT
+  strip-ansi@7.2.0  —  MIT
+  toidentifier@1.0.1  —  MIT
+  ts-algebra@2.0.0  —  MIT
+  type-is@2.1.0  —  MIT
+  undici-types@6.21.0  —  MIT
+  unpipe@1.0.0  —  MIT
+  vary@1.1.2  —  MIT
+  which@2.0.2  —  ISC
+  wrap-ansi@7.0.0  —  MIT
+  wrap-ansi@8.1.0  —  MIT
+  wrappy@1.0.2  —  ISC
+  yauzl@2.10.0  —  MIT
+  zod-to-json-schema@3.25.2  —  ISC
+  zod@4.4.3  —  MIT

package/dist/SKILL.md.template

@@ -0,0 +1,212 @@
+---
+name: recall
+description: >-
+  USE PROACTIVELY to load relevant past session context before non-trivial
+  tasks, architectural decisions, or any implementation with likely prior
+  history. Also use when the user says "recall", "remember", "what did we
+  do", "find that session", "what was I working on", or references past
+  conversations.
+when_to_use: >-
+  Trigger for phrases like "remind me about", "pick up where we left off",
+  "continue from last time", or when starting complex work in an area with
+  obvious prior sessions. Skip for simple lookups and trivial questions.
+allowed-tools: Bash, Agent, Read
+---
+
+# Recall
+
+Unified tool for session transcript memory — search, read, and browse.
+
+## The two-step pattern
+
+**Step 1: Search.** Every search result includes a matched message ID.
+
+```bash
+$RECALL_BIN "your query here"
+```
+
+**Step 2: Read the matched message.** Do NOT read the session from the top.
+
+```bash
+$RECALL_BIN <session-id> <message-id>
+```
+
+This auto-centers on the match with ~30% context before and ~70% after,
+filling up to the output budget. The footer tells you the exact `--offset`
+to continue reading forward.
+
+**NEVER start a session read from the top after searching.** The search
+already found the relevant message — go directly to it. Only use
+`$RECALL_BIN <id>` (no message-id) when you genuinely need to start
+from the beginning of a session.
+
+## Confidence tags
+
+Search results are tagged by how they were found:
+- `[FTS5+SEMANTIC]` — Both keyword and meaning matched. High confidence.
+- `[SEMANTIC-ONLY]` — Found by meaning, not exact words. Vocabulary mismatch discovery.
+- `[FTS5-ONLY]` — Exact keyword match only. May be coincidental.
+
+## Sub-agent pattern (recommended for deep research)
+
+For questions requiring multiple searches or reading session content, launch a sub-agent.
+The agent prompt **must** include full CLI instructions — sub-agents don't see this skill file.
+
+```
+Agent(prompt: "You have a recall CLI for searching and reading past session transcripts.
+Use ONLY `$RECALL_BIN` for all transcript access — do NOT read .jsonl files directly,
+do NOT use Grep/Glob/find to locate transcripts.
+
+CLI usage:
+  $RECALL_BIN \"query\"                    Search (returns session IDs + matched message IDs)
+  $RECALL_BIN <session-id> <message-id>   Read centered on matched message (use this after search)
+  $RECALL_BIN <session-id>                Read from beginning (only when you need full arc)
+  $RECALL_BIN <session-id> --offset N     Continue reading from offset N (shown in output footer)
+  $RECALL_BIN --list --since YYYY-MM-DD   List recent sessions
+  $RECALL_BIN --help                      Full flag reference
+
+DATE HANDLING: Any date the user mentions MUST become a flag — never search text:
+  --since YYYY-MM-DD   Only sessions on or after this date
+  --until YYYY-MM-DD   Only sessions on or before this date (inclusive)
+  --recent             Boost recent sessions (use when user says 'recently', 'latest')
+  Example: \"what happened April 10\" → $RECALL_BIN --list --since 2026-04-10 --until 2026-04-10
+
+CRITICAL READING RULE: After searching, ALWAYS read the matched message:
+  $RECALL_BIN <session-id> <message-id>
+This auto-centers on the match and shows surrounding turns. The output
+footer shows the --offset to continue reading forward. NEVER read sessions
+from the beginning after a search — the match is already found for you.
+
+Task: [describe what to find]. Run these searches: [list queries].
+Search EXHAUSTIVELY — do not stop after the first promising result. Run all
+listed queries, read into multiple results, and only report findings after
+you have checked every search path. Cross-reference results and summarize.",
+mode: "auto")
+```
+
+## Other reading modes
+
+| Mode | Command | When to use |
+|------|---------|-------------|
+| **Matched message** | `$RECALL_BIN <id> <msg-id>` | **Always use this after search** — auto-centers on match |
+| Full session | `$RECALL_BIN <id>` | Only when you need the overall arc, not a specific answer |
+| Continue | `$RECALL_BIN <id> --offset N` | Continue from where the last read left off |
+| Newest first | `$RECALL_BIN <id> --reverse` | Looking for recent content in a long session |
+
+## Commit attribution (`--commit` / `--blame`)
+
+Find the session(s) that produced a given commit, or the session(s)
+responsible for specific code in a file. Matches by structurally comparing
+session Edit/Write/MultiEdit tool calls against the commit's diff (tri-gram
+intersection), not by clock proximity. Results include both top-level
+sessions and Task-tool subagent leaves (`agent-<hash>`) with
+`parent_session_id` set.
+
+```bash
+# Sessions that produced one commit
+$RECALL_BIN --commit 864f569
+$RECALL_BIN --commit 864f569 --raw                     # full JSON
+
+# Sessions responsible for a file (HEAD-relative blame)
+$RECALL_BIN --blame src/webview/components/FlexAppLayout.tsx
+
+# Sessions responsible for one line — narrowest, most precise lookup
+$RECALL_BIN --blame src/foo.ts:42
+
+# Sessions responsible for a line range
+$RECALL_BIN --blame src/foo.ts:42-100
+
+# Multiple specs in one query (unioned)
+$RECALL_BIN --blame src/foo.ts:42 src/bar.ts:10-20 --limit 20
+```
+
+`--blame` is HEAD-relative: it runs `git blame` to find the commits
+responsible for the current state of the file (or line range) and
+attributes each. Sessions whose work was overwritten by a later commit
+won't appear — for the full historical iteration set, use `git log` and
+pass each commit to `--commit` separately.
+
+### When to use
+
+- **"Who produced this commit?"** — `--commit <hash>`. Returns the session(s)
+  that typed the edits. Multiple matches mean nested/sequential work.
+- **"Why is this line / block of code here?"** — `--blame <path>:<line>`
+  or `--blame <path>:<L1>-<L2>`. The narrowest, most precise lookup —
+  go straight to the session that authored the line you're staring at.
+- **"What sessions are responsible for this file's current state?"** —
+  `--blame <path>` (no line). Returns one row per (commit, session) for
+  every commit whose lines still live in HEAD.
+- **"Why is this code shaped this way?"** — When refactoring, debugging a
+  regression, or reviewing a legacy pattern, look up the originating session
+  before reasoning from the code alone. The session usually has rejected
+  approaches and constraints that the final code does not.
+
+### Reading the results
+
+Sessions are listed chronologically (oldest first). **The most recent is
+usually the load-bearing one for current code; earlier sessions show
+evolution.** Each row exposes:
+
+- `session` — top-level UUID or `agent-<hash>` subagent leaf
+- `parent_session_id` — set when the match is a subagent; follow this to
+  reach the parent's rationale conversation
+- `content_hits` — tri-gram intersections with the commit's added lines
+- `surviving_in_commit` / `surviving_ratio` — how much of the session's
+  work made it into the commit's final state (low ratio = iterated heavily
+  or was partly overwritten by a later session)
+- `matched_files` — commit-touched files this session edited in window
+- `last_edit_at` — ISO timestamp used for chronological sort
+
+Once you have a session ID, pass it back into recall to read the conversation:
+
+```bash
+$RECALL_BIN <session-id>                        # full session, oldest first
+$RECALL_BIN <session-id> --reverse              # newest first (faster for recent context)
+$RECALL_BIN "rationale keyword" --since DATE    # search within window
+```
+
+**For in-progress sessions**, the Stop hook that indexes a session hasn't
+fired yet — wait a few seconds after the turn finishes, then search again.
+
+## Date handling
+
+**Any date or time indication from the user MUST be translated into date flags.**
+Do NOT put dates into the search query text — dates in FTS5 produce false matches.
+
+```bash
+# Single day — use --since and --until together
+$RECALL_BIN --list --since 2026-04-10 --until 2026-04-10
+$RECALL_BIN "scroll bug" --since 2026-04-10 --until 2026-04-10
+
+# Open range — just one flag
+$RECALL_BIN "recall improvements" --since 2026-04-01
+$RECALL_BIN "old bug" --until 2026-03-15
+```
+
+- `--since DATE` — only sessions on or after this date
+- `--until DATE` — only sessions on or before this date (inclusive of the day)
+- Both accept ISO-8601 dates (YYYY-MM-DD)
+- Both work in search and list modes
+
+**Example:** "What did we work on April 10?" →
+`$RECALL_BIN --list --since 2026-04-10 --until 2026-04-10` to find all sessions,
+then search with topic keywords + date flags if needed.
+
+## Recency boost
+
+When the user says "recently", "latest", "last few days", or otherwise indicates
+they want recent results, add `--recent` to strongly boost newer sessions:
+
+```bash
+$RECALL_BIN "scroll bug fix" --recent
+```
+
+This increases the recency decay from ~50% penalty at 50 days to ~50% at 10 days,
+pushing recent sessions to the top of results. Combine with `--since` for best results.
+
+## Tips
+
+- **Search is cheap, reading is expensive.** Run 3-5 varied queries before committing to reading sessions.
+- **Message IDs are stable.** You can reference them across searches.
+- **Use `--since` / `--until` to scope.** Both search and list modes accept date flags.
+- **Raw JSON output** (`--raw`) is available for programmatic processing.