Recall

Time-travel for your dev workflow. Recall is a local-first CLI that automatically records your development activity and lets you search it in plain English.

recall today

recall timeline

---

Quick Start

pip install dev-recall
recall init
source ~/.zshrc  # or ~/.bashrc

recall init will:

1. Create ~/.local/share/dev-recall/ and ~/.config/dev-recall/
2. Initialize the SQLite database + FAISS vector index
3. Install the zsh/bash shell hook (appends source line to your rc file)
4. Set git config --global core.hooksPath to capture all commits
5. Start the background daemon (via systemd user service or subprocess)

---

Commands

Command	Description
recall init	First-time setup
recall ask "<query>"	Natural language search with LLM answer
recall today	Summary of today's activity
recall week	Summary of this week's activity
recall timeline	Chronological event list for a day
recall search "<query>"	Raw hybrid search (no LLM)
recall repos	List all tracked repos
recall stats	Capture statistics
recall export	Export events as JSON or CSV
recall config	View/edit configuration
recall privacy list	Show what's captured
recall privacy delete	Delete captured events
recall privacy ignore --cmd "pattern"	Add a privacy filter
recall daemon start/stop/status/logs	Manage the background daemon
recall mcp-serve	Start MCP server (for Claude Code / Copilot)
recall vscode install	Build and install VS Code extension

---

Architecture

🔒Privacy-first by design - Everything is stored locally

Collectors (shell hook, git hooks, VS Code ext, AI log watcher)
    ↓ events (TSV files + HTTP POST)
Daemon (FileWatcher → Enricher → SessionDetector → DB insert → Embedder)
    ↓
Storage (SQLite events.db + FTS5, FAISS vectors.faiss)
    ↓
Query (Hybrid FAISS+FTS5 → RRF → LLM via OpenRouter)
    ↓
CLI + MCP Server

---

Data Sources

Shell commands (zsh / bash)

Add to ~/.zshrc (done automatically by recall init):

source ~/.config/dev-recall/hook.zsh

Git commits

recall init sets core.hooksPath globally — all future commits in any repo are captured.

VS Code activity

Install the extension:

recall vscode install

AI chat sessions

Automatically scanned from:

• GitHub Copilot Chat: ~/.config/Code/User/workspaceStorage/*/GitHub.copilot-chat/debug-logs/
• Claude Code: ~/.claude/projects/*/sessions/
• Aider: .aider.chat.history.md in git repos
• Cursor: ~/.config/Cursor/User/workspaceStorage/

---

LLM Integration

Recall uses OpenRouter for the ask command and daily summaries.

export OPENROUTER_API_KEY=sk-or-...
recall ask "what was I debugging yesterday?"

Without an API key, recall ask falls back to --no-llm mode (shows retrieved events directly). Search never downloads an embedding model: it uses a locally cached model when available and otherwise falls back to SQLite full-text search. Use recall today --raw or recall week --raw to skip LLM summaries explicitly.

---

MCP Server

Use Recall as a context source in Claude Code or VS Code Copilot:

Claude Code (~/.config/claude/mcp.json):

{
  "mcpServers": {
    "dev-recall": {
      "command": "recall",
      "args": ["mcp-serve"]
    }
  }
}

VS Code / Copilot (.vscode/mcp.json):

{
  "servers": {
    "dev-recall": {
      "type": "stdio",
      "command": "recall",
      "args": ["mcp-serve"]
    }
  }
}

Available MCP tools: recall, today_summary, recent_repos, find_command, timeline

---

Privacy

• Commands matching *password*, *secret*, *token* etc. are dropped before storage
• AI chat messages are truncated to 200 characters (intent only, not full content)
• File events store only paths + language, never file content; ignored file patterns apply to saves, creates, deletes, and both sides of renames
• Captured data is stored locally. When an OpenRouter key is configured, ask, today, week, and enabled automatic summaries send selected event snippets to OpenRouter. Their raw/no-LLM modes stay local.
• Default retention: 90 days (configurable)

recall privacy list           # see what's captured
recall privacy delete --before 2026-01-01
recall privacy ignore --cmd "*mycompany*"

---

Configuration

Config file: ~/.config/dev-recall/config.json

recall config                          # show all settings
recall config daemon_port 8080        # change port
recall config retention_days 30       # shorter retention

Key settings:

{
  "daemon_port": 27182,
  "embedding_model": "all-MiniLM-L6-v2",
  "llm_model": "anthropic/claude-sonnet-4",
  "retention_days": 90,
  "capture": {
    "terminal": true,
    "git": true,
    "vscode": true,
    "ai_chat": true,
    "window_tracking": false,
    "session_events": false,
    "container_events": false,
    "process_tracking": false
  },
  "summary": { "auto_generate": true, "time": "23:30" },
  "search": { "default_top_k": 10, "rrf_k": 60, "session_idle_minutes": 30 }
}

The summary time and calendar commands use the machine's local timezone.

---

Data Storage

~/.local/share/dev-recall/
├── events.db       # SQLite (events + FTS5 + sessions + daily_summaries)
├── vectors.faiss   # FAISS vector index
├── shell.tsv       # shell hook ring buffer
├── git.tsv         # git hook ring buffer
└── daemon.pid      # running daemon PID

~/.config/dev-recall/
├── config.json
├── hook.zsh / hook.bash
└── git-hooks/post-commit + post-checkout

---

Development

git clone <repo>
cd dev-recall
pip install -e ".[dev]"
pytest

Sandbox testing

recall init makes system-wide changes (modifies ~/.zshrc, sets a global git config core.hooksPath, starts a background daemon). Use the provided Docker sandbox to test safely without touching your host environment.

Prerequisites: Docker

# Interactive shell — explore freely
./sandbox.sh

# Run the full test suite
./sandbox.sh test

# Run `recall init` and inspect every file it creates
./sandbox.sh init

# Run any arbitrary command
./sandbox.sh "recall --help"

What the sandbox isolates:

Risk	Mitigation
Modifies ~/.zshrc	Only affects the container's home directory
Sets global git config core.hooksPath	Sandboxed git config, discarded on exit
Starts a background daemon	Killed automatically when the container exits
Network calls to OpenRouter	Blocked via --network none
Privilege escalation	--cap-drop ALL --security-opt no-new-privileges

Alternatively, use a throwaway VM: multipass launch --name dev-recall-test

---

Roadmap

• v0.2 (current): Local capture, hybrid search, summaries, privacy controls, VS Code integration, and MCP tools
• v1.0: Cross-machine sync + web dashboard + Wakatime-compatible API

---

License

MIT