gh-arittr-tabula-scripta/commands/recall.md

Recall - Search Existing Memories

Search for existing memory notes in the Obsidian vault and present the top results.

Usage

/recall [query]

Arguments:

• query - Search terms to find relevant memories (required)

Examples:

/recall git worktrees
/recall debugging race condition
/recall react hooks patterns
/recall authentication flow

Implementation

When this command is invoked:

1. Parse and Validate Query

1. Parse the query by trimming whitespace from the command input
2. Validate that the query is not empty
   • If query is empty, return error message: "Query is required. Usage: /recall [query]"

2. Detect Project Context

1. Attempt to detect the current project from the git repository:
   • Run git rev-parse --show-toplevel to find the git repository root
   • Extract the project name from the repository directory name
2. If not in a git repository:
   • Fall back to using the current working directory name
   • If that fails, use 'default' as the project name
3. Store the detected project name for scoped search

3. Attempt Semantic Search (Smart Connections)

Note: Semantic search via Smart Connections plugin is an optional enhancement. If available, it provides better relevance ranking and conceptual matching.

1. Set initial search method to 'semantic' and initialize empty results array
2. Attempt to use semantic search (if Smart Connections plugin is installed):
   • Try to perform semantic search across both project notes and global entities
   • Search path: claude/projects/{currentProject}/** and claude/global/**
   • Retrieve top 10 results for ranking
3. If Smart Connections is not available or fails:
   • Set search method to 'text' for fallback
   • Continue to text search in next step

Implementation Note: Since obsidian-mcp-plugin does not provide native Smart Connections integration, this step may require custom MCP extensions or can be skipped in favor of text search only.

4. Perform Text Search

If semantic search was unavailable or returned no results, use text search:

1. Invoke MCP search_notes operation for project notes:

   • vault: ~/.claude-memory
   • query: The user's search query
   • path_filter: claude/projects/{currentProject}/**

2. Invoke MCP search_notes operation for global entities:

   • vault: ~/.claude-memory
   • query: The user's search query
   • path_filter: claude/global/entities/**

3. Combine the project results and global results, removing any duplicates

4. Set search method to 'text'

5. Handle errors:

   If MCPUnavailableError:

   • Return graceful degradation message explaining:
     • MCP server is unavailable
     • Steps to restore: ensure Obsidian is running, check plugin installation, verify config
     • Reference to docs/setup-guide.md

   If other error:

   • Return error message with details

5. Rank and Filter Results

1. Rank results by relevance:

   • If semantic search was used: Results are already ranked by vector similarity
   • If text search was used: Rank by match frequency and recency
     • Calculate match count: How many times the query appears in the result
     • Calculate recency boost: More recent notes ranked higher
     • Combine into relevance score: match count + (recency boost × 10)
     • Sort results by score in descending order

2. Limit to top 5 results for presentation

3. Check if no results were found:

   • If results are empty, return info message with:
     • "No memories found for query: '{query}'"
     • Suggestions: Try different terms, use /remember to create memories, search more broadly
     • Current project and search scope information

6. Track Cross-Project Recalls

Use the cross-project tracking patterns defined in the managing-working-memory skill:

1. Identify cross-project recalls by filtering results:

   • A recall is cross-project if the note's project differs from the current project
   • Exclude global entities (project = 'global') as they're expected to be cross-project

2. For each cross-project entity recall:

   • Load the current note using MCP read_note
   • Append a new entry to the cross_project_recalls frontmatter array:
     • project: Current project name
     • date: Current date (YYYY-MM-DD)
     • context: "Recalled via search: '{query}'"
   • Update the note using MCP update_note with:
     • Updated cross_project_recalls array
     • Updated claude_last_accessed timestamp

3. Check if promotion threshold is met:

   • If cross_project_recalls length >= 3, trigger promotion prompt (see below)
   • Promotion prompt is handled by the managing-working-memory skill

Promotion Prompt Format (I4):

When an entity reaches 3 cross-project recalls, display:

I've referenced [[{Entity Name}]] from {source-project} while working on other projects 3 times now:

1. {project-name} ({date}): {context}
2. {project-name} ({date}): {context}
3. {project-name} ({date}): {context}

This pattern seems reusable across projects. Should I promote it to global knowledge?

Options:
1. Yes, promote to global (move to ~/.claude-memory/claude/global/entities/)
2. Remind me later (ask again after 5 cross-project recalls)
3. No, it's project-specific (stop tracking)

What should I do?

User responses:

• If option 1: Execute promotion process (move entity, update frontmatter, create redirect)
• If option 2: Continue tracking, increase threshold to 5
• If option 3: Clear cross_project_recalls array and stop tracking

4. Handle errors silently:
   • Cross-project tracking is best-effort
   • Log warnings for failed tracking but don't interrupt the search flow

7. Present Results

1. Format the output message with:

   • Header: "Found {count} {memory/memories} for: '{query}'"
   • Search method used: Semantic or Text search
   • Current project name
   • Blank line

2. For each result (numbered 1-5):

   • Extract title from path (filename without extension)
   • Get type, project, and updated date from frontmatter
   • Get snippet preview from search result
   • Format as:

     {number}. [[{title}]] ({type})
        Project: {project}
        Updated: {updated}
        Preview: {first 150 chars of snippet}...
     

3. Add footer with options:

   • "Type a number (1-{count}) to load full note content"
   • "Continue conversation to work with these memories"
   • "Use /remember to create a new memory if nothing matches"

4. Return the formatted output as a success message

Error Handling

Missing Query

Input: /recall

Output:

Error: Query is required.

Usage: /recall [query]

Examples:
  /recall git worktrees
  /recall debugging race condition
  /recall react hooks patterns

No Results Found

Input: /recall nonexistent topic

Output:

No memories found for query: "nonexistent topic"

Suggestions:
- Try different search terms
- Check if you've created memories for this topic (use /remember)
- Search more broadly (fewer specific terms)

Current project: tabula-scripta
Searched: Project notes + global entities

MCP Unavailable

Input: /recall authentication (when MCP server is down)

Output:

Obsidian MCP server is unavailable. Cannot search memories.

To restore memory features:
1. Ensure Obsidian is running
2. Check obsidian-mcp-plugin is installed in ~/.claude-memory/
3. Verify Claude Code config includes MCP server

See docs/setup-guide.md for troubleshooting.

Success Output

Input: /recall git worktrees

Output:

Found 3 memories for: "git worktrees"
Search method: Semantic (Smart Connections)
Project: tabula-scripta

1. [[Git Worktrees]] (entity)
   Project: tabula-scripta
   Updated: 2025-11-18
   Preview: Git worktrees enable isolated directory trees for parallel development. Each worktree has its own working directory but shares the .git repository...

2. [[Parallel Execution Patterns]] (topic)
   Project: global
   Updated: 2025-11-17
   Preview: Techniques for concurrent task execution including git worktrees, background processes, and isolation strategies...

3. [[2025-11-18 - Spectacular Implementation]] (session)
   Project: tabula-scripta
   Updated: 2025-11-18
   Preview: Implementing parallel phase execution using git worktrees for task isolation. Decision: Use trap handlers for cleanup...


Options:
- Type a number (1-3) to load full note content
- Continue conversation to work with these memories
- Use /remember to create a new memory if nothing matches

Search Scope

The /recall command searches:

1. Current project notes:

   • claude/projects/{current-project}/sessions/**
   • claude/projects/{current-project}/entities/**

2. Global entities:

   • claude/global/entities/**
   • claude/global/topics/**

3. Excludes:

   • Archived sessions (claude/projects/{project}/archive/**)
   • Other project's sessions (unless global)

Semantic Search vs Text Search

Semantic Search (Preferred)

Requirements:

• Smart Connections plugin installed in Obsidian
• Plugin configured for ~/.claude-memory/ vault

Advantages:

• Better relevance ranking
• Finds conceptually similar notes
• Handles synonyms and related concepts

Example:

• Query: "concurrency issues"
• Finds: "Race Condition Debugging", "Parallel Execution Gotchas"

Text Search (Fallback)

When used:

• Smart Connections not installed
• Smart Connections unavailable
• Semantic search fails

Behavior:

• Exact/fuzzy text matching
• Ranked by match frequency and recency
• Still effective for keyword search

Example:

• Query: "race condition"
• Finds: Notes containing exact phrase "race condition"

Cross-Project Recall Tracking

When a memory from Project A is recalled while working in Project B:

1. Silent logging:

   • Update cross_project_recalls frontmatter array
   • No user-visible output (non-intrusive)

2. Threshold detection:

   • After 3 cross-project recalls
   • Trigger promotion prompt (via managing-working-memory skill)

3. Context capture:

   cross_project_recalls:
     - project: tabula-scripta
       date: 2025-11-18
       context: "Recalled via search: \"git worktrees\""
     - project: another-project
       date: 2025-11-19
       context: "Recalled via search: \"isolation patterns\""
   

Interactive Follow-Up

After presenting results, user can:

1. Load full note content:

   • User types: 1
   • Claude loads: Full content of result #1

2. Continue conversation:

   • User asks: "What did we decide about worktree cleanup?"
   • Claude references loaded memories in response

3. Create new memory:

   • User types: /remember entity Worktree Cleanup
   • New entity created based on discussion

Relevance Filtering

Results are filtered for relevance:

• Minimum score threshold: Only include results with score > 0.3
• Recency boost: Recently updated notes ranked higher
• Type priority: Entities ranked above sessions (more persistent knowledge)
• Project scoping: Current project results ranked above cross-project results

Acceptance Criteria

• Finds notes via semantic search (Smart Connections) when available
• Falls back to text search when semantic search unavailable
• Presents top 5 results with relevance ranking
• Handles MCP unavailable gracefully
• Detects project context correctly from git repo
• Tracks cross-project recalls silently
• Searches both project notes and global entities
• Shows clear message when no results found
• Includes note type, project, updated date, and preview in results
• Offers interactive follow-up options

Integration with managing-working-memory Skill

This command provides the manual interface for memory search. The managing-working-memory skill uses the same search logic for:

• Proactive recall at session start
• Finding related entities during updates
• Cross-project pattern detection

Relationship:

• /recall - Manual, user-initiated search
• managing-working-memory - Automatic, skill-driven search
• Both use same search methods (semantic → text fallback)
• Both track cross-project recalls