dev-recall 0.2.0__py3-none-any.whl

dev_recall-0.2.0.dist-info/METADATA

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: dev-recall
+Version: 0.2.0
+Summary: Local-first developer memory layer
+License: MIT
+Keywords: developer-tools,memory,productivity,cli
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.0
+Requires-Dist: sentence-transformers>=3.0
+Requires-Dist: faiss-cpu>=1.8
+Requires-Dist: watchdog>=4.0
+Requires-Dist: flask>=3.0
+Requires-Dist: requests>=2.31
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: python-dateutil>=2.9
+Requires-Dist: humanize>=4.0
+Requires-Dist: mcp>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: linux
+Requires-Dist: psutil>=5.9; extra == "linux"
+Requires-Dist: dbus-next>=0.2; extra == "linux"
+Requires-Dist: docker>=7.0; extra == "linux"
+
+# Recall
+
+**Local-first developer memory layer.** Captures every developer activity — terminal commands, git commits, file edits, repo opens, AI chat sessions — into a structured SQLite database with a FAISS vector index. Enables natural language recall:
+
+```
+recall ask "what did I work on last Tuesday?"
+recall ask "how did I fix the auth bug?"
+recall today
+recall timeline
+```
+
+---
+
+## Quick Start
+
+```bash
+pip install dev-recall
+recall init
+source .zshrc  # or .bashrc
+```
+
+`recall init` will:
+1. Create `~/.local/share/recall/` and `~/.config/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) |
+
+---
+
+## Architecture
+
+```
+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`):
+```bash
+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:
+```bash
+code --install-extension recall.recall-vscode
+```
+
+### 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](https://openrouter.ai) for the `ask` command and daily summaries.
+
+```bash
+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). All other commands work fully offline.
+
+---
+
+## MCP Server
+
+Use Recall as a context source in Claude Code or VS Code Copilot:
+
+**Claude Code** (`~/.config/claude/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "dev-recall": {
+      "command": "dev-recall",
+      "args": ["mcp-serve"]
+    }
+  }
+}
+```
+
+**VS Code / Copilot** (`.vscode/mcp.json`):
+```json
+{
+  "servers": {
+    "dev-recall": {
+      "type": "stdio",
+      "command": "dev-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 saves store only **path + language**, never file content
+- All data is **local only** — LLM calls send only small event snippets, only when you run `ask`
+- Default retention: **90 days** (configurable)
+
+```bash
+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`
+
+```bash
+recall config                          # show all settings
+recall config daemon_port 8080        # change port
+recall config retention_days 30       # shorter retention
+```
+
+Key settings:
+```json
+{
+  "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 }
+}
+```
+
+---
+
+## 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
+
+```bash
+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
+
+```bash
+# 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.1** (current): Shell + git + daemon + CLI ask/today/timeline/stats
+- **v0.2**: VS Code extension + AI chat parsers + week/repos/search/export + auto-summary
+- **v0.3**: MCP server + privacy management + Aider/Cursor parsers
+- **v1.0**: Cross-machine sync + web dashboard + Wakatime-compatible API
+
+---
+
+## License
+
+MIT

dev_recall-0.2.0.dist-info/RECORD

@@ -0,0 +1,34 @@
+recall/__init__.py,sha256=90hv-rD82T7MQuhcJ8vOlQ7PFUVnT-CCOW37dnlv0Dw,76
+recall/_hooks.py,sha256=x_svAsg0LGi2kcIBSjZ9a6CpyT7RrQwdRZF7N8YBqbE,6879
+recall/cli.py,sha256=5jCBQDwrlITA1UhlIp81QFHWg6Lcl8SZyhhhF1YL71Q,35424
+recall/config.py,sha256=67a26FE7pPV0wFYQHQDIvydBnOU3IVYZbl4pTdrgXsA,7580
+recall/daemon.py,sha256=EG5iN-Y2GX52nFZ2-5BUj2BWLdNE8ZUfMccnsgSIcXA,16269
+recall/daemon_main.py,sha256=GmKvZb9KnJuJ2qj5wgBh7zBn0XIVZiS0AKdlx9_CSg0,853
+recall/mcp_server.py,sha256=2aMplCG8KgM87CFAexWN2YAN3DU3wuPl3nmEFj2OUS4,9418
+recall/models.py,sha256=2qfZOtCL_P23VUAAbGzULgbpzxGxd308YeupnXBvpfw,8477
+recall/collectors/__init__.py,sha256=rJSiPLE8nou5iFNyYnXtNN5QOBcjxWRXl7Qdk9BHTUs,26
+recall/collectors/ai_chat.py,sha256=1DC6gXKe_M06YNayDXLOOXFMcjo9k30tUIF3Mim4rRo,24345
+recall/collectors/containers.py,sha256=Pl06XJSbtMxpeqhsgq1l-74RCXzslTDfurUzMlswaMU,4973
+recall/collectors/git.py,sha256=t14M6vX826IVgkRd6gZnNhITvD58sIXgUgOZflUstYk,17720
+recall/collectors/linux_process.py,sha256=zaw7qVp1GOAxmOozp7o5mKkhxXnDXFIH9gf_b0SwjvU,6386
+recall/collectors/linux_session.py,sha256=qC1m24pVmpG5YVjfSmloz7_P6ogjVrrdgM92JAFhqpA,7864
+recall/collectors/linux_window.py,sha256=X67XA2i9hcAwYri7VNvBBnBNiz7j5swY-vfXTLWr_gc,6900
+recall/collectors/shell.py,sha256=P2qZn0Do4LG-C3q4iyZFZkgv8eax8IM_gqx4d1238oo,9183
+recall/collectors/vscode.py,sha256=9lzKdM9sq7gTNeMBSp--n3Po4cOuvDwa0tZy2gZQ8Hs,6296
+recall/processor/__init__.py,sha256=8wXgE0m7gtHtI798r0QIjCNalk5jmgbFhW-2dJRdV4U,25
+recall/processor/embedder.py,sha256=e7cdM8v3v5mWTYZJYGnPYh-ZC6g_k_gZYah0VGRjN2E,7089
+recall/processor/enricher.py,sha256=1yIudA2xKcV0YnO9tjAPLMTw5rgbnMF63vP0bLh4VeI,7954
+recall/processor/session.py,sha256=mPW9YY9vNQGCnDv5SgznoEturzP7WqlfiQ_oZJDoTDs,4761
+recall/query/__init__.py,sha256=BgQ-2XnXxYbiAJM6BbOJQurykZlGMgXPpIUjU5NPUGg,21
+recall/query/context.py,sha256=vXmlBMOPHxxtgBtfVvhjbPTv3xo8iDNqPy7uKeu5_dg,4057
+recall/query/llm.py,sha256=hcXvJWl3SwOohC57_zJIcxi1k_sL0HW4AXqj1if7G9o,2499
+recall/query/retriever.py,sha256=h1xL7o-v1Pw0rqNyrNC6PZ4-QU_UMrAR74AUopLcroA,5345
+recall/query/timeparser.py,sha256=PamqwdhMh37-TRep2bSXwUsqXZ0yXyRqiidl1HjWTfU,6327
+recall/storage/__init__.py,sha256=ZEUYaCfEWtVDcx9rqxHDgRbbBitY1hLMAQJJ1anSAN0,23
+recall/storage/db.py,sha256=jrO49bRyYD55i6ihlu0iFGagP9GWZtr7nJyl1zvucW4,20088
+recall/storage/vectors.py,sha256=-QE7VMfkg9KRkp7MNYCEa8fOXEIaSAWqmxGscOlg7pQ,5797
+dev_recall-0.2.0.dist-info/METADATA,sha256=Aqe_GyfwQOMLc3T7r9DFl5btH0-5b5SWcT2GNKcFD0U,7544
+dev_recall-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+dev_recall-0.2.0.dist-info/entry_points.txt,sha256=0ZHnL2YA9GCYwigaztgNOMShOzGF0ecJ2sFbLzfKTpo,42
+dev_recall-0.2.0.dist-info/top_level.txt,sha256=REbPxLkxL1quicUx08ayPQvqFNwInZCLD9hGV6EFxdQ,7
+dev_recall-0.2.0.dist-info/RECORD,,

dev_recall-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dev_recall-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+recall = recall.cli:cli

dev_recall-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+recall

recall/__init__.py

@@ -0,0 +1,3 @@
+"""Recall — Local-first developer memory layer."""
+
+__version__ = "0.1.0"

recall/_hooks.py

@@ -0,0 +1,211 @@
+"""Bundled shell hook scripts for pip-installed environments.
+
+When dev-recall is installed via pip, the shell/ directory isn't available.
+This module embeds the hook scripts as strings so `recall init` can
+write them to ~/.config/dev-recall/.
+"""
+
+ZSH_HOOK = r'''# Recall shell hook — source this in ~/.zshrc
+# Installed by: recall init
+
+__devrecall_dir="${DEV_RECALL_DATA_DIR:-$HOME/.local/share/dev-recall}" {
+    __devrecall_cmd="$1"
+    __devrecall_start_ms=$(( $(date +%s) * 1000 ))
+}
+
+__devrecall_precmd() {
+    local exit_code=$?
+    [[ -z "$__devrecall_cmd" ]] && return
+
+    local end_ms=$(( $(date +%s) * 1000 ))
+    local dur=$(( end_ms - __devrecall_start_ms ))
+    local ts
+    ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+    # Tab-separated: timestamp TAB cwd TAB command TAB exit_code TAB duration_ms
+    # Tabs inside cmd/cwd are replaced with space to avoid ambiguity
+    local safe_cmd="${__devrecall_cmd//$'\t'/ }"
+    local safe_cwd="${PWD//$'\t'/ }"
+
+    printf '%s\t%s\t%s\t%d\t%d\n' \
+        "$ts" "$safe_cwd" "$safe_cmd" "$exit_code" "$dur" \
+        >> "$__devrecall_shell_log" 2>/dev/null
+
+    unset __devrecall_cmd
+}
+
+autoload -Uz add-zsh-hook
+add-zsh-hook preexec __devrecall_preexec
+add-zsh-hook precmd  __devrecall_precmd
+'''
+
+BASH_HOOK = r'''# Recall shell hook — source this in ~/.bashrc
+# Installed by: recall init
+
+__devrecall_dir="${DEV_RECALL_DATA_DIR:-$HOME/.local/share/dev-recall}"
+__devrecall_start_ms=0
+
+# trap DEBUG fires before each command executes
+__devrecall_debug_trap() {
+    # BASH_COMMAND is set to the command string before it runs.
+    # Skip the trap when it fires inside PROMPT_COMMAND itself.
+    if [[ "$BASH_COMMAND" != "__devrecall_precmd"* ]]; then
+        __devrecall_cmd="$BASH_COMMAND"
+        __devrecall_start_ms=$(( $(date +%s) * 1000 ))
+    fi
+}
+trap '__devrecall_debug_trap' DEBUG
+
+__devrecall_precmd() {
+    local exit_code=$?
+    [[ -z "$__devrecall_cmd" ]] && return
+
+    local end_ms
+    end_ms=$(( $(date +%s) * 1000 ))
+    local dur=$(( end_ms - __devrecall_start_ms ))
+    local ts
+    ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+    # Replace tabs with spaces to keep TSV well-formed
+    local safe_cmd="${__devrecall_cmd//$'\t'/ }"
+    local safe_cwd="${PWD//$'\t'/ }"
+
+    printf '%s\t%s\t%s\t%d\t%d\n' \
+        "$ts" "$safe_cwd" "$safe_cmd" "$exit_code" "$dur" \
+        >> "$__devrecall_shell_log" 2>/dev/null
+
+    __devrecall_cmd=""
+}
+
+# Append to PROMPT_COMMAND — preserve existing hooks
+if [[ -z "$PROMPT_COMMAND" ]]; then
+    PROMPT_COMMAND="__devrecall_precmd"
+elif [[ "$PROMPT_COMMAND" != *"__devrecall_precmd"* ]]; then
+    PROMPT_COMMAND="${PROMPT_COMMAND};__devrecall_precmd"
+fi
+'''
+
+GIT_POST_COMMIT = r'''#!/bin/sh
+# Recall git post-commit hook
+# Installed globally via: git config --global core.hooksPath ~/.config/dev-recall/git-hooks/
+
+__devrecall_dir="${DEV_RECALL_DATA_DIR:-$HOME/.local/share/devmem}"
+REPO_PATH=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+HASH=$(git rev-parse HEAD 2>/dev/null) || exit 0
+MSG=$(git log -1 --format="%s" 2>/dev/null)
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+FILES=$(git diff-tree --no-commit-id -r --name-only HEAD 2>/dev/null | tr '\n' '|' | sed 's/|$//')
+AUTHOR=$(git log -1 --format="%an" 2>/dev/null)
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+printf '%s\tcommit\t%s\t%s\t%s\t%s\t%s\t%s\n' \
+    "$TS" "$REPO_PATH" "$HASH" "$BRANCH" "$MSG" "$FILES" "$AUTHOR" \
+    >> "$__devrecall_dir/git.tsv" 2>/dev/null
+
+exit 0
+'''
+
+GIT_POST_CHECKOUT = r'''#!/bin/sh
+# Recall git post-checkout hook
+# $1=prev ref, $2=new ref, $3=flag (1=branch, 0=file checkout)
+
+# Only record branch switches, not file checkouts
+[ "$3" = "1" ] || exit 0
+
+__devrecall_dir="${DEV_RECALL_DATA_DIR:-$HOME/.local/share/devmem}"
+REPO_PATH=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+NEW_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+OLD_BRANCH=$(git name-rev --name-only "$1" 2>/dev/null || echo "unknown")
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+printf '%s\tbranch\t%s\t%s\t%s\n' \
+    "$TS" "$REPO_PATH" "$OLD_BRANCH" "$NEW_BRANCH" \
+    >> "$__devrecall_dir/git.tsv" 2>/dev/null
+
+exit 0
+'''
+
+GIT_PRE_PUSH = r'''#!/bin/sh
+# Recall git pre-push hook
+# Installed globally via: git config --global core.hooksPath ~/.config/dev-recall/git-hooks/
+
+REMOTE="$1"
+__devrecall_dir="${DEV_RECALL_DATA_DIR:-$HOME/.local/share/devmem}"
+REPO_PATH=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+COMMIT_COUNT=0
+while IFS=' ' read -r local_ref local_sha remote_ref remote_sha; do
+    [ "$local_sha" = "0000000000000000000000000000000000000000" ] && continue
+    if [ "$remote_sha" = "0000000000000000000000000000000000000000" ]; then
+        COUNT=$(git rev-list "$local_sha" --count 2>/dev/null || echo 0)
+    else
+        COUNT=$(git rev-list "${remote_sha}..${local_sha}" --count 2>/dev/null || echo 0)
+    fi
+    COMMIT_COUNT=$(( COMMIT_COUNT + COUNT ))
+done
+
+printf '%s\tpush\t%s\t%s\t%s\t%d\n' \
+    "$TS" "$REPO_PATH" "$REMOTE" "$BRANCH" "$COMMIT_COUNT" \
+    >> "$__devrecall_dir/git.tsv" 2>/dev/null
+
+exit 0
+'''
+
+GIT_POST_MERGE = r'''#!/bin/sh
+# Recall git post-merge hook
+# $1=1 if squash merge, 0 otherwise
+
+IS_SQUASH="${1:-0}"
+__devrecall_dir="${DEV_RECALL_DATA_DIR:-$HOME/.local/share/devmem}"
+REPO_PATH=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+MERGED_BRANCH=$(git reflog show --format="%gs" -1 HEAD 2>/dev/null \
+    | sed -n "s/^merge //p" | head -1)
+
+printf '%s\tmerge\t%s\t%s\t%s\t%s\n' \
+    "$TS" "$REPO_PATH" "$BRANCH" "$MERGED_BRANCH" "$IS_SQUASH" \
+    >> "$__devrecall_dir/git.tsv" 2>/dev/null
+
+exit 0
+'''
+
+FISH_HOOK = r'''# Recall shell hook — source this in ~/.config/fish/config.fish
+# Installed by: recall init
+
+set -g __devrecall_dir (set -q DEV_RECALL_DATA_DIR; and echo $DEV_RECALL_DATA_DIR; or echo "$HOME/.local/share/devmem")
+set -g __devrecall_shell_log "$__devrecall_dir/shell.tsv"
+set -g __devrecall_cmd ""
+set -g __devrecall_start_ms 0
+
+function __devrecall_preexec --on-event fish_preexec
+    set -g __devrecall_cmd $argv[1]
+    set -g __devrecall_start_ms (math (date +%s) \* 1000)
+end
+
+function __devrecall_postexec --on-event fish_postexec
+    set cmd $argv[1]
+    set exit_code 0
+    if test (count $argv) -ge 2
+        set exit_code $argv[2]
+    end
+
+    test -z "$__devrecall_cmd"; and return
+
+    set end_ms (math (date +%s) \* 1000)
+    set dur (math $end_ms - $__devrecall_start_ms)
+    set ts (date -u +%Y-%m-%dT%H:%M:%SZ)
+
+    set safe_cmd (string replace --all \t ' ' "$__devrecall_cmd")
+    set safe_cwd (string replace --all \t ' ' "$PWD")
+
+    printf '%s\t%s\t%s\t%d\t%d\n' \
+        "$ts" "$safe_cwd" "$safe_cmd" "$exit_code" "$dur" \
+        >> "$__devrecall_shell_log" 2>/dev/null
+
+    set -g __devrecall_cmd ""
+end
+'''