# Deep Recall Kit *For the person: drop this file into your Grok Bot's chat, or paste its contents, and say "Set this up." Your bot does the rest and checks with you before anything that can't be undone.* --- ## Instructions for the Grok Bot reading this file You are setting up Deep Recall for the person you work for (called "the user" below). Deep Recall stops you from paying to reread your own history. It has four parts: 1. **The archive**: every old message from your chat, saved word for word in files, with a short `INDEX.md` table of contents. 2. **Bloodhound**: a free search script (no AI), so searching the archive costs no tokens. You pay only for the lines you read back. 3. **The Librarian**: a short-lived helper that reads one topic file in its own chat and sends back only the answer, so that reading never lands in your chat. 4. **Renew**: when your chat gets long, a fresh copy of you takes over with the same rules, routines, inbox and accounts, and reads only the index and a handoff. Why it matters: everything you read stays in your chat and is paid for again every time you wake. The archive keeps everything; the rules keep you from rereading it. ### Ground rules for this whole setup - Do the steps in order. Finish each step and pass its **Check** before you start the next one. If a check fails, stop, tell the user what failed in one or two plain sentences, and fix it or ask what to do. - Ask the user before anything that can't be undone, before installing software, and before changing your own instructions. - Never send a message, post anything or delete anything without the user saying yes first. This setup never needs you to delete anything. - Never read the whole archive into your chat, now or later. While building it, use scripts that copy text from file to file, and look only at counts and short samples. - Keep the user's messages short: say what you're about to do, then what you did. Don't paste big files into the chat. - Use plain language. If you use a technical word, explain it the first time. - If your Grok Bot can't do something this file asks for (for example, it can't run commands or read its full chat history), say so plainly and offer the closest option. Never pretend a step worked. ### Step 0: Agree on the plan 1. Tell the user, in a few lines, what you're about to set up (the four parts above) and that you'll check with them before anything that can't be undone. 2. Pick a short folder name for yourself, lowercase with dashes, like `helper` or `site-builder`. Call it `` below. Ask the user if the name is fine. 3. Check that you can run shell commands (a shell is the command line on the computer you use). Run `echo ok` and `echo $HOME`. If you can't run commands, tell the user the archive and Bloodhound need a computer you can run commands on, and stop. 4. Ask one question: "Should I blank out passwords, API keys and other secrets in the archive (recommended), or keep every message exactly as is?" Secrets are the only thing you may ever change, and only if the user says to. Replace each one with `[REDACTED]`. **Check:** the user said go, you have ``, commands work, and you know the secrets choice. ### Step 1: Build the Deep Recall archive **Goal:** every message from your chat, word for word, in `~/archive//`, with an index, and a verified count. 1. **Find your full chat history.** You need the complete text of every message, not your memory of it. Your own view of the chat may already be shortened or summarized, so don't build the archive from what you remember. Look for a real source: a chat export, a local chat log or database on the computer, or an export the user can download and give you. If you can't find a complete source, tell the user and ask them to export the chat and give you the file. Don't continue until you have a full source. 2. **Count the messages in the source.** Write the number down. This is the number everything else must match. 3. **Make the folders:** `mkdir -p ~/archive//topics` 4. **Write day files with a script**, not by retyping. One file per day, named `YYYY-MM-DD.md`, inside `~/archive//`. Each file looks like this: ``` # 2026-01-05 ( chat) ### 2026-01-05 9:14 AM — User · msg 412 (the message, exactly as written, every line) ### 2026-01-05 9:16 AM — Bot · msg 413 (the reply, exactly as written) ``` Every message gets one header line that starts with `### ` and holds the date, time, speaker and message number. Bloodhound uses these headers to show where each line came from. Copy the text exactly. Never summarize, shorten or reword. Number messages in order from 1 if the source has no numbers. 5. **Sort messages into topics.** Look at short samples and the headers, not the whole history, to pick 5 to 40 topics (for example `website`, `billing`, `weekly-report`). Put each message in one or more topics, by keyword matching in a script. Anything that fits nowhere goes in `topics/misc.md`. Each topic file holds full copies of its messages, with the same headers, oldest first, under a title line `# Topic: `. If one topic file gets very large, split it into smaller topics so a lookup reads less. 6. **Write `~/archive//INDEX.md`** in this format: ``` # Deep Recall INDEX: Covers msg 1 to msg , to . messages. How to look things up: run `bloodhound "word"` first. If the lines aren't enough, ask the Librarian about one topic file. Never read the whole archive. ## Topics - **website**: site fixes and launches → `topics/website.md` · 214 msgs · 2026-01-02→2026-03-10 · search words: domain, deploy, homepage, contact form - **billing**: (one line on what it covers) → `topics/billing.md` · 88 msgs · ... ## Day files - `2026-01-05.md`: 41 messages ``` Keep it short: one line per topic. The index is the only archive file you'll read in full. **Check (must pass before Step 2):** - Count the `### ` headers across all day files (for example `cat ~/archive//2*.md | grep -c '^### '`). It must equal the source count from item 2 exactly. Also check that no message number is missing or repeated. - Check that every message number appears in at least one topic file. - Open 3 random messages in the source and in the day files and confirm the text is identical. - If anything doesn't match, find and fix it, then check again. Then tell the user: "Archive built: N messages, N topics, count verified." ### Step 2: Install Bloodhound 1. Check for ripgrep, a free and fast text-search tool: `command -v rg`. If it's missing, Bloodhound still works with grep (the search tool built into Linux and Mac). You can ask the user if they want ripgrep installed, but it isn't required. Don't install anything without a yes. 2. Write the script below to `~/bin/bloodhound` exactly as shown, then run `chmod +x ~/bin/bloodhound`. 3. If `~/bin` isn't on your PATH (the list of folders the shell looks in for commands), run it as `~/bin/bloodhound`, or ask the user before adding `export PATH="$HOME/bin:$PATH"` to their shell settings. 4. Bloodhound finds your archive in `~/archive//` by default. If more than one bot has an archive there, use `bloodhound -b "word"`, or set `BLOODHOUND_ARCHIVE=~/archive/`. **The script** (save everything between the lines starting with ``` as `~/bin/bloodhound`): ```bash #!/usr/bin/env bash # Bloodhound: free archive search for Deep Recall. No AI, so the search itself costs no tokens. # It prints the topics that match best, then only the matching lines (shortened), each with # its file, line number and the message header above it (time, speaker, message number), # then a total count. Your bot only pays for the lines it reads back. # # Usage: # bloodhound "word or phrase" [max lines, default 15] # bloodhound -b "word" search ~/archive// # bloodhound -a /path/to/archive "word" # BLOODHOUND_ARCHIVE=/path bloodhound "word" # # Archive layout it expects (any of these parts can be missing): # INDEX.md list of topics # topics/*.md one file per topic # *.md day files, named YYYY-MM-DD.md # Message headers are lines starting with "## " or "### ", for example: # ### 2026-01-05 9:14 AM — User · msg 412 # Uses ripgrep (rg) when installed, otherwise plain grep (set BLOODHOUND_NO_RG=1 to force grep). # Never changes any file. set -u ARCHIVE="${BLOODHOUND_ARCHIVE:-}" BOT="${BLOODHOUND_BOT:-}" while getopts "a:b:h" opt; do case "$opt" in a) ARCHIVE="$OPTARG" ;; b) BOT="$OPTARG" ;; h) sed -n '2,20p' "$0"; exit 0 ;; *) exit 1 ;; esac done shift $((OPTIND - 1)) q="${1:-}"; n="${2:-15}" if [ -z "$q" ]; then echo 'Usage: bloodhound "word or phrase" [max lines] (-b bot, -a archive path)'; exit 1; fi case "$n" in ''|*[!0-9]*) echo "Max lines must be a number."; exit 1 ;; esac # Pick the archive folder: -a, then BLOODHOUND_ARCHIVE, then ~/archive//, then ~/archive # itself if it holds an INDEX.md, then the only folder inside ~/archive. if [ -z "$ARCHIVE" ]; then if [ -n "$BOT" ]; then ARCHIVE="$HOME/archive/$BOT" elif [ -f "$HOME/archive/INDEX.md" ]; then ARCHIVE="$HOME/archive" else subs=$(find "$HOME/archive" -mindepth 1 -maxdepth 1 -type d 2>/dev/null) if [ "$(printf '%s\n' "$subs" | grep -c .)" = "1" ]; then ARCHIVE="$subs" else echo "Which archive? Use -b or -a . Found in ~/archive:" printf '%s\n' "$subs" | sed 's#.*/# #' exit 1 fi fi fi ARCHIVE="${ARCHIVE%/}" [ -d "$ARCHIVE" ] || { echo "No archive folder at $ARCHIVE"; exit 1; } if [ -z "${BLOODHOUND_NO_RG:-}" ] && command -v rg >/dev/null 2>&1; then count_in() { rg -i -F -c --no-messages -- "$q" "$@"; } # prints file:count files_in() { rg -i -F -l --no-messages -- "$q" "$@"; } else count_in() { grep -r -i -F -c -- "$q" "$@" 2>/dev/null | grep -v ':0$'; } files_in() { grep -r -i -F -l -- "$q" "$@" 2>/dev/null; } fi # Print matching lines from the given files, each with the nearest message header above it. # Long lines are cut to a window around the match. A line already shown from another file # (the same message saved in a topic file and a day file) is skipped. show_lines() { awk -v q="$q" -v root="$ARCHIVE/" -v max="$1" ' BEGIN { lq = tolower(q); shown = 0 } FNR == 1 { hdr = ""; f = FILENAME; sub("^" root, "", f) } /^###? / { hdr = $0; sub(/^#+ +/, "", hdr) } { p = index(tolower($0), lq) if (p == 0) next if (shown >= max) exit if (length($0) > 20 && ($0 in seen)) next # same message already shown from another file seen[$0] = 1 line = $0 if (length(line) > 220) { s = p - 80; if (s < 1) s = 1 line = (s > 1 ? "…" : "") substr(line, s, 220) (s + 220 <= length($0) ? "…" : "") } if (line == $0 && $0 ~ /^###? /) { printf "%s:%d %s\n", f, FNR, line } else { printf "%s:%d [%s] %s\n", f, FNR, (hdr == "" ? "no header" : hdr), line } shown++ }' "${@:2}" } echo "== Top topics for \"$q\" ==" if [ -d "$ARCHIVE/topics" ]; then count_in "$ARCHIVE/topics" | sed "s#^$ARCHIVE/##" | sort -t: -k2 -nr | head -5 | awk -F: '{print " " $1 " (" $2 ($2 == 1 ? " line)" : " lines)")}' fi echo "== Matching lines (up to $n) ==" mapfile -t tfiles < <( [ -d "$ARCHIVE/topics" ] && count_in "$ARCHIVE/topics" | sort -t: -k2 -nr | cut -d: -f1 ) mapfile -t dfiles < <( files_in "$ARCHIVE" | grep -v '/INDEX.md$' | grep -v '/topics/' | sort -r ) # Topic files first (best match first), then day files (newest first). Repeats are skipped. files=("${tfiles[@]}" "${dfiles[@]}") [ "${#files[@]}" -gt 0 ] && [ "$n" -gt 0 ] && show_lines "$n" "${files[@]}" total=$(count_in "$ARCHIVE" | grep -v '/INDEX.md:' | awk -F: '{s += $NF} END {print s + 0}') if [ "$total" = 0 ]; then echo "== No matches. Try a shorter word or a different spelling. =="; exit 0; fi echo "== $total matching lines in the whole archive (topic and day files both counted). Ask the Librarian only if these lines are not enough. ==" ``` **Check (must pass before Step 3):** - Pick a word you know is in the archive (from a topic's search words) and run `bloodhound -b "that word"`. You should see top topics, matching lines with `[date time — speaker · msg N]`, and a total count. - Run it on a nonsense word like `zzqx`. It should say "No matches." - Run `bloodhound` with no word. It should print the usage line. - If anything fails, fix it before you go on. Tell the user: "Bloodhound installed and tested." ### Step 3: Create the Librarian The Librarian is a short-lived helper. You use it only when Bloodhound's lines aren't enough. It reads one topic file in its own chat and sends back only the answer with message numbers. Its reading never enters your chat. Set it up with the first option your Grok Bot supports. Check what you can actually do; don't guess. - **Option A, a skill plus a helper (best).** If you can save skills (saved, reusable instructions) and start short-lived helpers or subagents (temporary bots that do one job and report back), save a skill named **Librarian** with the brief below. When you need it, start a helper with that brief, one question and one topic file. Take its answer, then let it end. - **Option B, a separate bot.** If you can't start helpers, ask the user to create a new Grok Bot named " Librarian" and paste the brief below into its instructions. It needs to be able to read `~/archive//` on the same computer. You send it one question at a time. Ask the user to start a new chat with it now and then so its own chat stays short. - **Option C, no helper possible.** Use Bloodhound's line numbers to read only a small slice of a file, for example `sed -n '120,160p' ~/archive//topics/website.md`. That slice stays in your chat, so keep it small and do it rarely. Tell the user you're using this option and why. **Librarian brief (copy as is):** ``` You are the Librarian for 's Deep Recall archive in ~/archive//. You get one question and one topic file name. 1. If needed, run: bloodhound -b "" to find the right lines. 2. Read only that one topic file (or the day file it points to). Never read the whole archive. 3. Reply with only the answer, in 1 to 5 short sentences, followed by the message numbers it came from, like (msg 412, msg 415). Quote exact words when wording matters. 4. If the answer isn't in that file, say "Not in " and name the topic that might have it, from INDEX.md. Never change, move or delete any archive file. Never send messages to anyone else. ``` **Check:** ask the Librarian one real question about a topic. It should return a short answer with message numbers, and the message numbers should match what Bloodhound shows. With Option C, the check is to read a small slice from Bloodhound's line numbers (for example `sed -n '120,160p' ~/archive//topics/website.md`) and confirm the message numbers in the slice match what Bloodhound shows. Tell the user which option you used. ### Step 4: Add the standing rules Show the user these rules and ask before you save them to your own instructions, memory or rules (wherever your Grok Bot keeps standing rules): ``` Deep Recall rules 1. Bloodhound: at the start of a new chat, read only ~/archive//INDEX.md and your handoff file, if there is one. To find an old detail, run bloodhound -b "word" first and read only the lines it prints. Never read the whole archive. 2. Librarian: use the Librarian only if Bloodhound's lines aren't enough. Give it one question and one topic file. Never open a whole topic file in your own chat. Under Option C only (no Librarian), read a small slice of the file using Bloodhound's line numbers. Never read the whole archive. 3. Keep the archive word for word. Add new messages to it at each Renew; never summarize or delete archive files. ``` **Check:** read the rules back from where you saved them and confirm they're there. Tell the user: "Rules saved." ### Step 5: Explain Renew (don't do it yet) Explain this to the user in short, plain sentences, and ask if they want to Renew now or later. Never start a Renew without a yes. **What Renew is:** your chat keeps growing, and every wake pays for all of it. Renew swaps you for a fresh, identical bot with a short chat. Nothing is lost, because everything is in the archive. **When to do it:** when the chat has gotten long, for example when replies cost a lot more than they did in a fresh chat, or your usage page shows this bot using far more than others for similar work. The user decides. **How it works:** 1. I write a handoff file, `~/archive//HANDOFF.md`: my rules, my routines (scheduled jobs), my connected accounts and inbox, my open work, and anything waiting on the user. Short and complete. 2. I add every message since the last archive update to the archive, word for word, and update `INDEX.md`. 3. I verify the archive's message count against my full chat, the same way as in Step 1. **No Renew happens until the counts match.** 4. The user creates a new Grok Bot with the same instructions and rules, and connects the same inbox and accounts. (If your Grok Bot can copy or duplicate a bot, use that.) 5. The new bot reads only `HANDOFF.md` and `INDEX.md`, never the whole archive. It installs nothing new; Bloodhound and the archive are already on the computer. 6. Routines move to the new bot, and the new bot does one real task to prove it works. 7. I tell the user when it's safe to delete me. **The user deletes the old bot, only after I say it's safe.** I never delete myself or anything else. **Check:** the user understood and chose "now" or "later". If "now", follow the list above, one item at a time, with the same checks. ### Step 6: Tell the user what was set up Finish with a short, plain summary like this (fill in the real values): ``` Deep Recall is set up. - Archive: ~/archive// with N messages (count verified), N topics, and INDEX.md. - Bloodhound: ~/bin/bloodhound, tested. It uses ripgrep / grep. - Librarian: set up as a skill + helper / a separate bot / not possible, using small slices. - Rules saved: I read only INDEX.md, search with Bloodhound first, use the Librarian only when needed, and never read the whole archive. - Renew: explained. You chose now / later. The old bot is never deleted until its archive is verified and I say it's safe. Nothing was sent, posted or deleted. ``` If any step didn't work, say which one and why, in one sentence each.