"Your terminal has perfect memory. You no longer need to."
- Problem Statement
- Our Solution
- Architecture Overview
- User Personas
- Use Case Varieties
- Value Proposition
- Command Reference
- Security Model
- Getting Started
Every developer maintains a mental buffer of commands — kubectl rollout undo, that docker run with a dozen flags, the awk one-liner that took 45 minutes to write. This buffer is finite, fragile, and completely unindexed.
The result is Command Amnesia: the cognitive tax paid every time an engineer stops productive work to excavate a command they have already solved.
| Scenario | Real Cost |
|---|---|
| Broken deployment, roll-back command forgotten | 15–60 min of downtime hunting runbooks |
grep / awk / sed one-liner needed again |
10–30 min of Stack Overflow archaeology |
| Onboarding new engineer to a project | 2–5 hours of "ask a colleague" loops |
| Post-incident: "what did we run?" | Unreliable shell history, partial ~/.bash_history, no context |
docker run with 12 flags across 3 projects |
Copy-paste hell across 7 notes apps |
| Tool | Problem |
|---|---|
history / Ctrl+R |
Exact-match only. Requires you to remember the syntax you already forgot. |
| Notes apps (Notion, Obsidian) | Manual. Nobody updates them under pressure. |
| Shell aliases | Static. Cannot handle dynamic flags or context-aware variations. |
| AI assistants (ChatGPT, Copilot) | Require internet. Hallucinate flags. Cannot learn your commands. |
fzf + history |
Still exact-match. No semantic understanding. No context. |
The gap: no tool captures what you actually ran, indexes it by intent, filters secrets automatically, and retrieves it offline with natural language.
Recall is a 100% offline, privacy-first CLI tool that eliminates Command Amnesia permanently. It runs a background hook in your shell, silently capturing every command you execute into an encrypted local vault. When you need a command, you describe what you want in plain English — Recall finds it.
You ran it once. Recall remembers it forever.
You describe what you want. Recall finds it instantly.
┌──────────────────────────────────────────────────────────────┐
│ YOUR SHELL (zsh/bash) │
│ │
│ $ kubectl rollout undo deployment/api --to-revision=3 │
│ │ │
│ ▼ (shell hook fires automatically) │
│ ┌─────────────┐ │
│ │ CAPTURE │ ← filters secrets, noise, empty cmds │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ VAULT │ ← SQLCipher-encrypted, local-only │
│ │ (FTS5 + │ ← full-text indexed by intent │
│ │ metadata) │ ← cwd, git repo, exit code, timestamp │
│ └──────┬──────┘ │
│ │ │
│ ▼ (when you need it) │
│ $ recall "undo kubernetes deployment" │
│ ┌─────────────┐ │
│ │ SEARCH │ ← semantic FTS5 + frequency scoring │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ▸ kubectl rollout undo deployment/api --to-revision=3 94% │
└──────────────────────────────────────────────────────────────┘
| Principle | Implementation |
|---|---|
| Offline-first | Zero network calls. Everything runs on your machine. |
| Privacy-by-design | Secrets filtered before vault write. Vault optionally encrypted with SQLCipher (AES-256). |
| Zero friction | One-time setup. Hook fires automatically. No manual logging. |
| Intent search | FTS5 full-text search + relevance scoring. Describe what you want, not what you typed. |
| Context-aware | Stores cwd, git repo, git branch, exit code, duration alongside every command. |
recall/
├── cmd/ # Cobra CLI command definitions
├── internal/
│ ├── capture/ # Shell hook ingest + pre-flight secret filtering
│ ├── vault/ # SQLCipher database, schema migrations, FTS5 index
│ ├── intelligence/ # Semantic search engine (FTS5 + scoring)
│ ├── explain/ # Command breakdown (AST-level parsing)
│ ├── compose/ # Interactive command builder (TUI)
│ └── ui/ # Terminal UI rendering (Bubble Tea)
├── pkg/
│ ├── config/ # ~/.config/recall/config.toml
│ ├── shell/ # Shell detection (zsh/bash/fish)
│ └── logging/ # Structured logging
└── tests/ # Integration + security test suite
commands -- raw, binary_name, flags, category, frequency, first_seen, last_seen
contexts -- cwd, git_repo, git_branch, exit_code, duration_ms, session_id
knowledge -- built-in command descriptions, intents, examples
commands_fts -- FTS5 virtual table: raw, binary_name, subcommand, category
knowledge_fts -- FTS5 virtual table: command, description, intents"I just need it to work. I'll fix it properly later."
Profile: Full-stack developer, ships fast, context-switches constantly between 3+ projects. Forgetting commands is a daily occurrence. Has 47 tabs open and a Notion doc that hasn't been updated since Q2.
Pain Points:
- Reruns
history | grep docker10 times a day - Loses complex one-liners between project switches
- Spends 20 minutes recreating
ffmpegcommands from scratch
How Recall Helps:
# Monday: you ran this once on project A
$ docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=dev --name pg-dev postgres:15
# Friday: on project B, you need it again
$ recall "run postgres docker locally"
▸ docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=dev --name pg-dev postgres:15 89%Key Features Used: Search by intent, recall vault TUI browser, recall digest
"Every second of ambiguity during an incident costs money."
Profile: Senior SRE or Platform Engineer. Owns production stability. During incidents, command recall speed directly correlates with MTTR (Mean Time To Recovery). Runs across 5+ clusters, multiple cloud accounts, and ephemeral environments.
Pain Points:
- During a P0, blanks on the exact
kubectlrollback syntax - Post-incident reviews require reconstructing exactly what was run and when
- Onboarding runbooks are 6 months out of date
How Recall Helps:
# During P0: don't think, just search
$ recall "rollback kubernetes deployment"t
▸ kubectl rollout undo deployment/api --to-revision=3 94%
▸ kubectl rollout history deployment/api 91%
▸ helm rollback my-app 5 --namespace production 87%
# Post-incident reconstruction
$ recall context stats
# Shows cwd, git repo, exit codes, timestamps for every command run during incident windowKey Features Used: Context-aware search, recall export for incident reports, recall maintenance, encrypted vault for compliance
"I need to know we're not flying blind."
Profile: Non-hands-on-keyboard, but accountable for delivery velocity and system reliability. Needs confidence that the engineering team has guardrails in place. Tracks MTTR, deployment frequency, and incident rate.
Pain Points:
- Deployments fail because someone ran a one-off command that no one documented
- Knowledge walks out the door when engineers leave
- No audit trail for what was run in production during incidents
How Recall Helps:
| Metric | Before Recall | After Recall |
|---|---|---|
| Avg. time to find rollback command | 15–30 min | < 10 seconds |
| Command knowledge retention | Leaves with engineer | Stays in encrypted vault |
| Post-incident reconstruction | Manual, incomplete | Timestamped, context-aware |
| Onboarding time (command knowledge) | 2–5 hours/week | Import vault: instant |
| Secret leakage risk | Shell history in plaintext | Filtered before storage |
Key Features Used: recall export for knowledge transfer, recall digest for team insights, encrypted vault for security posture
Scenario: Production API deployment fails. Rollback command is buried in a week-old Slack thread.
$ recall "rollback api deployment production"
▸ kubectl rollout undo deployment/api-gateway --namespace=prod 94%
▸ helm rollback api-gateway 12 --namespace prod --wait 91%
▸ git revert HEAD~1 --no-edit && git push origin main 78%
# MTTR improvement: 30 min → 15 secondsScenario: "What exactly did we run at 2:47 AM during the outage?"
$ recall "database migration we ran last week"
▸ flyway migrate -url=jdbc:postgresql://prod-db/app -schemas=public 87%
▸ psql -h prod-db -U admin -d app -f migrations/v42_add_index.sql 84%
# Context: cwd=/srv/app, git_branch=hotfix/db-lock, exit_code=0, 2026-04-05 02:47:13Scenario: Senior engineer leaving the team. 3 years of tribal knowledge about Kubernetes and CI/CD.
# Engineer exports their vault on last day
$ recall export --output ~/team-knowledge-2026.enc
# New engineer imports it
$ recall import --input team-knowledge-2026.enc --merge
✅ Merged 4,312 commands from senior engineer's vault
# Instant access to 3 years of muscle memory
$ recall "deploy staging environment from scratch"Scenario: Developer switches between a Node.js micro-service, a Python ML pipeline, and a Go CLI tool daily.
$ recall "run tests"
▸ npm test -- --coverage [via vault, node project] 88%
▸ pytest tests/ -v --cov=src [via vault, python project] 85%
▸ go test -tags sqlite_fts5 ./... -race [via vault, go project] 82%
# Recall uses cwd + git repo context to surface the most relevant result firstScenario: Security team requests evidence that no credentials were logged to shell history.
# Recall's capture layer filters before storage
# Patterns filtered: password, token, secret, API_KEY, aws_secret, credentials, private_key
# Verify clean vault
$ python3 -c "
import sqlite3, os
c = sqlite3.connect(os.path.expanduser('~/.local/share/recall/vault.db'))
rows = [r[0] for r in c.execute('SELECT raw FROM commands').fetchall()]
for p in ['password=', 'AWS_SECRET', 'token=', '_KEY=']:
hits = [r for r in rows if p.lower() in r.lower()]
print(f'{'✅ CLEAN' if not hits else '❌ LEAKED'} {p}')
"
✅ CLEAN password=
✅ CLEAN AWS_SECRET
✅ CLEAN token=
✅ CLEAN _KEY=Scenario: Engineer types the same 3-step deploy sequence 10 times a day.
$ recall suggest-aliases
# Recall analyzes frequency patterns in your vault and suggests:
▸ Alias 'deploy-api' for: cd ~/services/api && docker build -t api . && kubectl apply -f k8s/
▸ Alias 'pg-local' for: docker run -d -p 5432:5432 --name pg-dev postgres:15Scenario: Working on a secure network with no internet access. AI assistants unavailable.
# No internet? No problem. Recall is 100% local.
$ recall "configure nginx reverse proxy ssl"
▸ nginx -t && systemctl reload nginx 91%
▸ certbot --nginx -d api.example.com --non-interactive 88%
▸ openssl req -x509 -nodes -days 365 -newkey rsa:2048 ... 82%
# Zero network calls. Zero telemetry. Works in air-gapped environments.Scenario: Distributed team needs to share a curated command knowledge base without exposing secrets.
$ recall sync --push
# Encrypts vault locally → pushes to private GitHub Gist
# Team members pull and merge:
$ recall sync --pull --merge
# End-to-end encrypted. GitHub sees only ciphertext.You will never lose a command again. Ever.
The cognitive overhead of managing commands — bookmarking, copy-pasting, digging through history — is permanently eliminated. Recall operates silently. The vault grows automatically. Search takes less than a second. The developer stays in flow state.
| Metric | Before Recall | After Recall | Improvement |
|---|---|---|---|
| Time to find a forgotten command | 5–30 min | < 10 sec | ~180x faster |
| Commands lost when machine wiped | All | 0 (export/import) | 100% retention |
| Secrets accidentally logged | Possible | Impossible (filtered) | Zero risk |
| Works offline | ✗ (AI tools require internet) | ✅ Always | 100% availability |
| Setup time | — | < 2 minutes | Zero friction |
| Privacy (data leaves machine?) | Yes (cloud AI) | Never | 100% private |
Institutional terminal knowledge stays inside the organization. Not in someone's head.
When an engineer leaves, their Recall vault can be transferred. When an incident occurs, the exact commands run (with timestamp, context, exit code) are retrievable. When a junior engineer joins, they inherit the senior's command vocabulary immediately.
| Risk | Without Recall | With Recall |
|---|---|---|
| MTTR during incident | High (command recall bottleneck) | Minimized |
| Knowledge loss on attrition | Complete | Transferable via encrypted export |
Secret leakage via history |
Possible | Blocked at capture layer |
| Compliance / audit trail | Manual, incomplete | Timestamped, context-attached |
| Onboarding ramp time | Weeks | Days (vault import) |
│ Works Offline │ Intent Search │ Auto-Capture │ Secret Filter │ Encrypted Vault
─────────┼─────────────────┼─────────────────┼────────────────┼─────────────────┼──────────────────
history │ ✅ │ ❌ │ ✅ │ ❌ │ ❌
fzf │ ✅ │ ❌ │ ❌ │ ❌ │ ❌
ChatGPT │ ❌ │ ✅ │ ❌ │ ❌ │ ❌
Notion │ ❌ │ ✅ │ ❌ │ ❌ │ ❌
RECALL │ ✅ │ ✅ │ ✅ │ ✅ │ ✅
| Command | Description | Example |
|---|---|---|
recall "<intent>" |
Search vault by natural language intent | recall "restart nginx" |
recall init |
First-time setup: install hook, create vault | recall init |
recall import-history |
Bootstrap vault from existing shell history | recall import-history |
recall explain "<cmd>" |
Break down a command into plain English | recall explain "awk '{print $2}' file" |
recall compose |
Build a command interactively step-by-step | recall compose |
recall vault |
Browse full vault in TUI | recall vault |
recall digest |
Weekly command summary and streak | recall digest |
recall wrapped |
Terminal Wrapped — annual usage summary | recall wrapped |
recall suggest-aliases |
AI-suggest shell aliases for repeated patterns | recall suggest-aliases |
recall export --output <file> |
Encrypted vault backup | recall export --output backup.enc |
recall import --input <file> |
Restore from encrypted backup | recall import --input backup.enc |
recall sync |
E2E encrypted GitHub Gist sync | recall sync --push |
recall share |
Generate shareable SVG card of a command | recall share "git stash pop" |
recall roast |
Get roasted for bad command habits | recall roast |
recall maintenance |
Rebuild FTS index, vacuum, repair | recall maintenance |
recall config |
View/edit configuration | recall config |
recall plugin list |
Manage recall plugins | recall plugin list |
| Threat | Mitigation |
|---|---|
| Secrets captured to vault | Pre-storage filter: password, token, secret, API_KEY, aws_secret, credentials, private_key blocked at ingest |
| Vault file read by attacker | SQLCipher AES-256 encryption (new vaults). File mode -rw------- (owner-only). |
| Vault backup intercepted | Exported files encrypted with Argon2-derived key (user password). Tamper detection built in. |
| Cloud sync intercepted | End-to-end encrypted before upload. Server sees only ciphertext. |
| Binary tampering | Build reproducibility via goreleaser. Can add binary signing in CI. |
| State | hexdump First 16 Bytes |
Status |
|---|---|---|
| Legacy unencrypted | SQLite format 3. |
Working. Warn shown. Run recall maintenance. |
| SQLCipher encrypted | Random bytes (AES-256) | Fully encrypted. Production target state. |
# 1. Build and install
cd recall/
make install
# → ✓ Installed to $GOPATH/bin/recall
# 2. Initialize (installs shell hook, creates vault)
recall init
# → ✅ Recall initialized successfully!
# 3. Import existing history (optional but recommended)
recall import-history
# → ✅ Imported 1,245 commands into vault
# 4. Reload your shell
source ~/.zshrc # or ~/.bashrc# From this point forward, every command you run is captured automatically.
# Search by describing what you want:
recall "find files modified in last 24 hours"
recall "docker remove all stopped containers"
recall "git cherry-pick without committing"
recall "kill process using port 8080"Config lives at ~/.config/recall/config.toml:
[vault]
path = "~/.local/share/recall/vault.db"
encrypt = true # enable SQLCipher encryption for new vaults
[capture]
enabled = true
noise_filter = true # filters cd, ls, pwd, clear, exit, history
secret_patterns = ["password", "token", "secret", "API_KEY", "aws_secret"]
exclude_commands = ["ls", "cd", "pwd", "clear", "exit", "history"]Recall is maintained at github.com/Om-Rohilla/recall
License: MIT · Built with Go, SQLCipher, Bubble Tea