feat: introduce /recall skill for reliable memory retrieval

[bigph00t]

Summary

• Adds /recall skill for token-efficient memory retrieval using 2-step workflow
• Step 1: Search returns index with IDs/titles (~100 tokens/result)
• Step 2: Fetch full observations by ID (~500 tokens/result)
• Adds /api/recall endpoint to worker service

Skill Invocation

• As plugin skill: /claude-mem:recall
• For shorter /recall: copy to ~/.claude/skills/recall/SKILL.md

Test plan

• Tested /recall skill discovery
• Tested search API endpoint
• Tested recall API endpoint

🤖 Generated with Claude Code

[bigph00t]

What the /recall skill does

The skill bundles the MCP 3-layer search workflow into a simpler prompted 2-step process:

1. Search → Returns compact index with IDs (~100 tokens/result)
2. Fetch → Claude decides which IDs are relevant, then retrieves full details (~500 tokens/result)

The key innovation is that it's prompted - the SKILL.md file teaches Claude:

• WHEN to use memory (questions about past work, missing context, repeated tasks)
• HOW to execute token-efficiently (filter before fetching)

So when a user asks "How did we fix the rate limiting issue?", Claude automatically:

1. Searches memory for "rate limiting"
2. Reviews the index results
3. Uses judgment to pick the 2-3 most relevant observations
4. Fetches only those, saving ~10x tokens vs loading everything

The skill is bundled with claude-mem as /claude-mem:recall, or users can copy it to ~/.claude/skills/recall/ to get the shorter /recall command.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR introduces the /recall skill for token-efficient memory retrieval using a 2-step workflow that significantly improves how Claude accesses past work.

Key Changes:

• New /recall Skill: Added skill documentation (plugin/skills/recall/SKILL.md) that teaches Claude when and how to retrieve memories efficiently through a prompted 2-step process
• New /api/recall Endpoint: Added SearchManager.recall() method and corresponding HTTP route to fetch full observations by IDs
• Chroma Architecture Migration: Migrated from MCP client to direct HTTP client using chromadb npm package and ChromaClient
• Local Server Management: New ChromaServerManager singleton manages Chroma HTTP server lifecycle via npx chroma run
• Multi-tenancy Support: Added configuration settings for tenant isolation to support future cloud/pro features
• Context Prompt Updates: Modified formatters to guide Claude to use /recall instead of MCP tools

2-Step Workflow:

1. Search returns index with IDs/titles (~100 tokens/result)
2. Claude judges relevance and fetches full details for selected IDs (~500 tokens/result)

This achieves ~10x token savings compared to bulk loading while maintaining full context retrieval capabilities.

Architecture Improvements:

• Removes Windows console popup issues from MCP subprocess spawning
• Enables future cloud vector search for pro users
• Maintains backward compatibility with existing search infrastructure

Confidence Score: 4/5

• This PR is safe to merge with good architectural improvements, though the large Chroma migration should be monitored in production
• Score reflects solid implementation of the /recall skill and API endpoint (5/5 quality), but the substantial Chroma migration from MCP to HTTP introduces architectural changes that warrant production monitoring. The code quality is excellent with proper error handling, cross-platform support, and graceful degradation. The 2-step workflow is well-designed and the skill documentation is clear. Minor concern is the large refactor of ChromaSync affecting vector search reliability.
• Monitor src/services/sync/ChromaSync.ts and src/services/sync/ChromaServerManager.ts in production to ensure the HTTP-based Chroma connection is stable across platforms. The rest of the changes are straightforward additions.

Important Files Changed

Filename	Overview
plugin/skills/recall/SKILL.md	Added /recall skill documentation with clear 2-step workflow instructions for token-efficient memory retrieval
src/services/worker/SearchManager.ts	Added recall() method to fetch observations by IDs with proper validation and formatted markdown output
src/services/worker/http/routes/SearchRoutes.ts	Added /api/recall endpoint handler that delegates to SearchManager.recall()
src/services/sync/ChromaServerManager.ts	New singleton manager for Chroma HTTP server lifecycle with cross-platform process management
src/services/sync/ChromaSync.ts	Migrated from MCP client to direct HTTP ChromaClient with tenant isolation support for future pro features
src/services/worker-service.ts	Integrated ChromaServerManager to start local Chroma server during worker initialization

Sequence Diagram

sequenceDiagram
    participant User
    participant Claude
    participant RecallSkill as /recall Skill
    participant SearchAPI as /api/search
    participant RecallAPI as /api/recall
    participant SearchMgr as SearchManager
    participant SessionStore as SessionStore
    participant ChromaDB as ChromaDB

    User->>Claude: "How did we fix the auth bug?"
    Claude->>RecallSkill: Invokes /recall skill
    
    Note over Claude,RecallAPI: Step 1: Search for relevant memories
    Claude->>SearchAPI: GET /api/search?query=auth+bug&limit=15
    SearchAPI->>SearchMgr: search(query, limit)
    SearchMgr->>ChromaDB: queryChroma(query, 100)
    ChromaDB-->>SearchMgr: vector search results (IDs only)
    SearchMgr->>SessionStore: Get metadata for IDs
    SessionStore-->>SearchMgr: titles, types, dates
    SearchMgr-->>SearchAPI: Index (~100 tokens/result)
    SearchAPI-->>Claude: [ID, Title, Type, Date] list
    
    Note over Claude: Claude reviews index and<br/>decides which memories<br/>are relevant
    
    Note over Claude,RecallAPI: Step 2: Fetch full details for selected IDs
    Claude->>RecallAPI: GET /api/recall?ids=234,567,891
    RecallAPI->>SearchMgr: recall([234,567,891])
    SearchMgr->>SessionStore: getObservationsByIds([234,567,891])
    SessionStore-->>SearchMgr: Full observation records
    SearchMgr-->>RecallAPI: Formatted markdown (~500 tokens/result)
    RecallAPI-->>Claude: Full memory narratives
    
    Claude->>User: Answers question using<br/>retrieved context

Loading