Summary

Add claude-code as an LLM provider option, allowing users with Claude Pro/Max subscriptions to use their subscription for LLM-assisted features (rerank, entity refinement) without requiring a separate API key.

Motivation

Currently, MemPalace supports three LLM providers (llm_client.py):

• ollama — local models (default)
• openai-compat — OpenAI-compatible endpoints
• anthropic — requires API key

Users who already pay for Claude Pro/Max subscriptions cannot leverage their existing authentication for MemPalace's LLM features. They must either:

1. Set up Ollama locally
2. Pay for a separate Anthropic API key
3. Use a third-party OpenAI-compatible service

Proposed Solution

Add a claude-code provider that uses the Claude Agent SDK (claude-agent-sdk) to make LLM calls through the user's existing Claude CLI authentication (claude auth login).

Reference Implementation

Hindsight has already implemented this pattern successfully:

• File: hindsight-api-slim/hindsight_api/engine/providers/claude_code_llm.py
• Approach: Uses claude_agent_sdk.query() for simple calls and ClaudeSDKClient for tool calling
• Auth: Leverages existing claude auth login credentials — no API key needed
• Fallback: Clear error messages guide users to authenticate if not logged in

Key implementation details from Hindsight:

from claude_agent_sdk import query, ClaudeAgentOptions

# Simple call
async for message in query(prompt=user_content, options=options):
    # process response

# With tools
async with ClaudeSDKClient(options=options) as client:
    await client.query(user_content)
    async for message in client.receive_response():
        # process response

Use Cases

1. Rerank (Hybrid + LLM): Users can get ≥99% R@5 using their Claude subscription instead of 98.4% with Hybrid v4 alone
2. Entity refinement (mempalace init --llm): Better entity classification without Ollama setup
3. Future LLM features: Any upcoming LLM-assisted functionality

Implementation Scope

1. Add ClaudeCodeProvider class to mempalace/llm_client.py
2. Add claude-code to provider selection logic
3. Add dependency: claude-agent-sdk (optional, only needed if using this provider)
4. Update CLI flags documentation

Additional Context

• Claude Agent SDK: pip install claude-agent-sdk
• Requires user to run claude auth login once
• No API key management needed
• Works with Claude Pro ($20/mo) and Max ($100/mo) subscriptions