recall: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

---

Project Context

Recall is an MCP (Model Context Protocol) server providing long-term memory for Claude conversations. It stores context in Redis or Valkey with semantic search capabilities to survive context window limitations.

Key Principle: This server IS the solution to context loss - treat it with care and always maintain backward compatibility.

---

Build & Run Commands

npm run build      # Production build (tsup)
npm run dev        # Watch mode for development
npm run start      # Run MCP server (stdio transport)
npm run start:http # Run HTTP server (for SaaS deployment)

Testing

# Unit tests with vitest (primary test runner)
npm test                    # Run all tests once
npm run test:watch          # Watch mode
npm run test:coverage       # With coverage report

# Run specific test file
npx vitest run src/services/rlm.service.test.ts

# Static checks (fast, no dependencies)
./tests/test-v1.5.0-simple.sh

# Runtime tests (requires Redis)
ANTHROPIC_API_KEY="test-key" node tests/test-runtime.js

Manual Testing

# Start Redis
redis-server

# Run MCP server manually
REDIS_URL=redis://localhost:6379 ANTHROPIC_API_KEY=sk-... node dist/index.js

# Run HTTP server for SaaS testing
REDIS_URL=redis://localhost:6379 STRIPE_SECRET_KEY=sk_test_... node dist/server-http.js

# Test Redis connection
redis-cli ping  # Should return PONG
redis-cli KEYS memory:*

---

Architecture Overview

Entry Points

• index.ts - MCP server (stdio transport) - use for Claude Desktop/Claude Code
• server-http.ts - HTTP server for SaaS deployment (recallmcp.com)

Core Components

src/
├── index.ts                    # MCP server entry (stdio)
├── server-http.ts              # HTTP server entry (SaaS)
├── types.ts                    # Zod schemas, TypeScript types
├── persistence/                # Storage layer (abstracted)
│   ├── storage-client.interface.ts  # Interface for storage adapters
│   ├── storage-client.factory.ts    # Creates Redis or Valkey adapter
│   ├── storage-client.ts            # Storage client singleton
│   ├── memory-store.ts              # Core memory CRUD operations
│   ├── redis-client.ts / redis-adapter.ts
│   └── valkey-client.ts / valkey-adapter.ts
├── embeddings/                 # Multi-provider embedding system
│   ├── factory.ts              # Auto-detects provider from API keys
│   ├── generator.ts            # Embedding generation orchestration
│   ├── types.ts                # Provider interface
│   └── providers/              # Provider implementations
│       ├── voyage-provider.ts      # Voyage AI (best quality)
│       ├── cohere-provider.ts      # Cohere (multilingual)
│       ├── openai-compatible-provider.ts  # OpenAI/Deepseek/Grok
│       ├── anthropic-provider.ts   # Anthropic (keyword fallback)
│       └── ollama-provider.ts      # Local Ollama
├── services/                   # Business logic services
│   └── rlm.service.ts          # RLM (Recursive Language Model) for large context
├── tools/                      # MCP tool handlers
│   ├── index.ts                # Core tools (store, search, delete)
│   ├── context-tools.ts        # Smart context (recall, analyze, summarize)
│   ├── rlm-tools.ts            # RLM tools (create_execution_context, decompose, etc.)
│   ├── relationship-tools.ts   # Memory linking/graphs
│   ├── version-tools.ts        # Version history/rollback
│   ├── template-tools.ts       # Memory templates
│   ├── category-tools.ts       # Category management
│   └── export-import-tools.ts  # Backup/restore
├── resources/                  # MCP resource handlers
├── prompts/                    # MCP prompt handlers
├── analysis/                   # Claude-powered conversation analysis
└── http/                       # HTTP/SaaS infrastructure
    ├── server.ts               # Express server setup
    ├── mcp-handler.ts          # MCP-over-HTTP with session management
    ├── auth.middleware.ts      # API key authentication + tenant isolation
    ├── billing.service.ts      # Stripe subscription management
    ├── workspace.service.ts    # Workspace limit enforcement
    ├── team.service.ts         # Team/organization management
    ├── oauth.service.ts        # OAuth flow for Claude Desktop
    ├── audit.service.ts        # API usage auditing
    ├── firebase-admin.ts       # Firebase auth integration
    └── types.ts                # HTTP-specific types (TenantContext, etc.)