Recall

# Implementation Plan: Documentation Update **Created**: 2026-01-19 **Target**: Update outdated documentation files (hooks-setup.md, USAGE.md→recall.md), remove obsolete docs **Estimated Tasks**: 6 **Worktree Groups**: 1 (all sequential - documentation changes) ## Context for the Engineer You are updating documentation for the Recall memory system: - **Project**: Python MCP server with Claude Code hooks integration - **Architecture**: Daemon-based fast path with 15 hooks (docs show only 6) - **Key change**: Daemon integration, MLX embeddings, more hooks **You are expected to**: - Keep documentation concise and accurate - Match the existing README.md style - Remove obsolete content rather than maintaining it - Add files to .gitignore instead of deleting locally ## Prerequisites Checklist - [x] Recall repo cloned and accessible - [x] 15 hooks identified in hooks/ directory - [x] Current documentation reviewed --- ## Task 1: Update hooks-setup.md with Current Hooks **Agent**: `technical-documentation-specialist` **File(s)**: `docs/hooks-setup.md` **Estimated time**: 30m ### What you're building Update hooks-setup.md to accurately reflect the current 15 hooks instead of the outdated 6. The daemon architecture should be prominently featured since it's the key performance optimization. ### Implementation **Current hooks (15 total):** | Hook | File | Purpose | Hook Type | |------|------|---------|-----------| | SessionStart | `recall-session-start.py` | Record session initiation | SessionStart | | Context Loader | `recall-context.py` | Load relevant memories at session start | SessionStart | | User Prompt | `recall-prompt.py` | Inject context based on prompt content | UserPromptSubmit | | Pre-Tool Context | `recall-precontext.py` | Inject memories before tool calls | PreToolUse | | Security Validator | `recall-security.py` | Block dangerous bash patterns | PreToolUse | | Permissions | `recall-permissions.py` | Automate learned permission decisions | PermissionRequest | | File Tracker | `recall-track.py` | Track file Read/Write/Edit operations | PostToolUse | | Session Capture | `recall-capture.py` | Summarize session, store memories | SessionEnd | | Compaction Guard | `recall-compact.py` | Preserve context before compaction | PreCompact | | Monitor | `recall-monitor.py` | Health check and deep analysis | PostSessionEnd | | Notification | `recall-notify.py` | Handle notification events | Notification | | Stop Hook | `recall-stop.py` | Capture learnings when agent stops | Stop | | Subagent Tracker | `recall-subagent.py` | Track Task/subagent results | SubagentStop | | **Daemon** | `recall-daemon.py` | Fast IPC server (<10ms operations) | Background Service | | Daemon Control | `recall-daemon-ctl.py` | CLI for daemon lifecycle | Utility | **Key sections to update**: 1. **Overview table**: Replace 6 hooks with 15 2. **Daemon section**: Add prominent section explaining fast path 3. **Hook details**: Update each hook's description 4. **Configuration**: Update example `settings.json` with all hooks 5. **Remove**: References to non-existent `recall-errors.py` ### Verification ```bash # Check for references to non-existent files grep -n "recall-errors" docs/hooks-setup.md # Should return nothing # Verify hook count in overview grep -c "recall-" docs/hooks-setup.md # Should be > 15 ``` ### Commit ``` docs: update hooks-setup.md for 15 hooks and daemon architecture - Updated hook overview table (6 → 15 hooks) - Added daemon architecture section with fast path explanation - Updated all hook descriptions with current functionality - Updated example settings.json configuration - Removed references to non-existent recall-errors.py ``` --- ## Task 2: Rename USAGE.md to recall.md and Update **Agent**: `technical-documentation-specialist` **File(s)**: `docs/USAGE.md` → `docs/recall.md` **Depends on**: Task 1 **Estimated time**: 20m ### What you're building Rename USAGE.md to recall.md and update content to reflect: - Current slash commands - Daemon status checking - TRY-LEARN validation cycle - Golden rules concept ### Implementation **Key sections to add/update**: 1. **Daemon status**: Add daemon_status_tool usage 2. **Validation cycle**: Document memory_apply_tool and memory_outcome_tool 3. **Golden rules**: Explain confidence >= 0.9 promotion 4. **Memory types**: Add `golden_rule` and `file_context` types **New content structure**: ```markdown # Recall Usage Guide ## Three Ways to Use Recall [Keep existing table, update with daemon info] ## Slash Commands (Explicit Control) [Keep existing, add /validate if applicable] ## Hooks (Automatic) [Update with 15 hooks summary] ## MCP Tools (Claude's Choice) [Update with all current tools including daemon_status_tool] ## Validation Loop (TRY-LEARN) [NEW: Explain the validation cycle] ## Golden Rules [NEW: Explain high-confidence memory promotion] ## Memory Types [Update with all 6 types] ## Namespaces [Keep existing] ``` ### Verification ```bash # Verify file renamed ls docs/recall.md # Should exist ls docs/USAGE.md # Should not exist ``` ### Commit ``` docs: rename USAGE.md to recall.md with updated content - Renamed USAGE.md to recall.md - Added daemon status tool documentation - Added validation loop (TRY-LEARN) section - Added golden rules explanation - Updated memory types to include all 6 types - Updated hooks section to reference 15 hooks ``` --- ## Task 3: Remove Obsolete Documentation Files **Agent**: `technical-documentation-specialist` **File(s)**: - `docs/GRAPH_EXPANSION.md` (remove from git, keep locally) - `docs/VALIDATION_LOOP.md` (remove from git, keep locally) - `docs/LONG_TERM_MEMORY_RESEARCH.md` (remove from git, keep locally) - `docs/research_reports/` (remove from git, keep locally) - `.gitignore` (update) **Depends on**: Task 2 **Estimated time**: 15m ### What you're building Remove obsolete documentation from git tracking but keep locally. Add entries to .gitignore to prevent re-adding. ### Implementation **Commands to execute**: ```bash # Remove from git tracking (keeps local files) git rm --cached docs/GRAPH_EXPANSION.md git rm --cached docs/VALIDATION_LOOP.md git rm --cached docs/LONG_TERM_MEMORY_RESEARCH.md git rm -r --cached docs/research_reports/ # Update .gitignore cat >> .gitignore << 'EOF' # Obsolete documentation (kept locally for reference) docs/GRAPH_EXPANSION.md docs/VALIDATION_LOOP.md docs/LONG_TERM_MEMORY_RESEARCH.md docs/research_reports/ EOF ``` ### Verification ```bash # Verify files removed from git but exist locally git status | grep -E "GRAPH_EXPANSION|VALIDATION_LOOP|LONG_TERM|research_reports" # Should show deleted ls docs/GRAPH_EXPANSION.md # Should still exist locally ``` ### Commit ``` docs: remove obsolete documentation from git tracking Removed from tracking (kept locally): - GRAPH_EXPANSION.md - VALIDATION_LOOP.md - LONG_TERM_MEMORY_RESEARCH.md - research_reports/ Added to .gitignore to prevent re-adding. ``` --- ## Task 4: Remove poc/ Folder from Git **Agent**: `technical-documentation-specialist` **File(s)**: `poc/`, `.gitignore` **Depends on**: Task 3 **Estimated time**: 5m ### What you're building Remove poc/ folder from git tracking and add to .gitignore. ### Implementation ```bash # Check if poc/ is already removed (git status shows D) git status --short | grep poc # If not already staged for deletion: git rm -r --cached poc/ 2>/dev/null || echo "Already removed or not tracked" # Add to .gitignore if not present grep -q "^poc/" .gitignore || echo "poc/" >> .gitignore ``` ### Verification ```bash # Verify in gitignore grep "poc/" .gitignore # Should return "poc/" ``` ### Commit ``` chore: remove poc/ folder from git tracking - Added poc/ to .gitignore - Removed from git tracking (keeping local copy) ``` --- ## Task 5: Update README.md **Agent**: `technical-documentation-specialist` **File(s)**: `README.md` **Depends on**: Task 4 **Estimated time**: 15m ### What you're building Review and update README.md to ensure consistency with new documentation: - Verify daemon section is accurate - Update any broken links to removed docs - Add link to new recall.md usage guide ### Implementation **Sections to verify/update**: 1. **Links section** (if any): Update references to USAGE.md → recall.md 2. **See Also section** (if any): Remove links to GRAPH_EXPANSION.md, VALIDATION_LOOP.md 3. **Hooks section**: Verify it mentions 15 hooks, not 6 4. **Add link**: Point to docs/recall.md for usage guide ### Verification ```bash # Check for broken links grep -n "USAGE.md" README.md # Should return nothing grep -n "GRAPH_EXPANSION" README.md # Should return nothing grep -n "VALIDATION_LOOP" README.md # Should return nothing ``` ### Commit ``` docs: update README.md links and references - Updated reference to USAGE.md → recall.md - Removed broken links to obsolete docs - Verified hooks count and daemon documentation ``` --- ## Task 6: Update CLAUDE.md **Agent**: `technical-documentation-specialist` **File(s)**: `CLAUDE.md` **Depends on**: Task 5 **Estimated time**: 15m ### What you're building Review CLAUDE.md (project instructions for Claude Code) and update: - Remove references to obsolete docs - Ensure hooks list is accurate - Update any See Also links ### Implementation **Sections to check**: 1. **See Also section**: Remove links to GRAPH_EXPANSION.md, VALIDATION_LOOP.md 2. **Hooks section**: Verify accurate hook count 3. **Core Components**: Verify architecture description matches current state ### Verification ```bash # Check for broken links grep -n "GRAPH_EXPANSION" CLAUDE.md grep -n "VALIDATION_LOOP" CLAUDE.md ``` ### Commit ``` docs: update CLAUDE.md references - Removed links to obsolete documentation - Verified architecture and hook descriptions ``` --- ## Testing Strategy ### Manual Verification - Read through updated docs for coherence - Verify all file paths mentioned exist - Click-test any internal links ### Automated Checks ```bash # Find broken internal links grep -rE '\]\([^)]+\.md\)' docs/ | while read line; do file=$(echo "$line" | sed 's/.*](\([^)]*\)).*/\1/') if [[ ! -f "docs/$file" && ! -f "$file" ]]; then echo "Broken link: $line -> $file" fi done ``` --- ## Commit Strategy 6 commits in sequence: 1. **docs**: Update hooks-setup.md for 15 hooks 2. **docs**: Rename USAGE.md to recall.md 3. **docs**: Remove obsolete docs from git 4. **chore**: Remove poc/ from git 5. **docs**: Update README.md links 6. **docs**: Update CLAUDE.md references --- ## Common Pitfalls 1. **Deleting files locally instead of git rm --cached** - Why it happens: Confusion between removing from git vs filesystem - How to avoid: Always use `git rm --cached` for "remove from git but keep local" 2. **Forgetting to update .gitignore** - Why it happens: Files will get re-added on next `git add .` - How to avoid: Always add removed files to .gitignore 3. **Breaking internal links** - Why it happens: Renaming/removing files that are referenced elsewhere - How to avoid: Search for references before removing --- ## Resources ### Files to Reference - Current hooks: `hooks/recall-*.py` - README style: `README.md` - Claude instructions: `CLAUDE.md` ### Validation Checklist - [ ] hooks-setup.md lists 15 hooks - [ ] recall.md exists (USAGE.md renamed) - [ ] Obsolete docs removed from git but exist locally - [ ] .gitignore updated with removed files - [ ] No broken internal links - [ ] README.md and CLAUDE.md have no broken references