Docs/Getting Started

Troubleshooting

Common issues and solutions when working with Recall.

Connection Issues

Redis Connection Failed

Error:

TEXT
1Error: Redis connection failed: ECONNREFUSED 127.0.0.1:6379

Solutions:

  • Verify Redis is running:
Bash
1redis-cli ping
2# Should return: PONG
  • Start Redis if needed:
Bash
1# macOS
2brew services start redis
3

4# Linux
5sudo systemctl start redis
6

7# Docker
8docker run -d -p 6379:6379 redis:alpine
  • Check Redis URL format:
TypeScript
1// Correct formats
2redis://localhost:6379
3redis://username:password@host:6379
4redis://host:6379/0  // With database number

Mem0 API Connection Failed

Error:

TEXT
1Error: Mem0 API error: 401 Unauthorized

Solutions:

  • Verify API key:
Bash
1curl -H "Authorization: Bearer $MEM0_API_KEY" \
2  https://api.mem0.ai/v1/memories
  • Check environment variables:
TypeScript
1console.log(process.env.MEM0_API_KEY);
2// Should not be undefined

Performance Issues

Slow Response Times

Symptoms:

  • Response times >100ms for cache hits
  • Degraded performance over time

Solutions:

  • Check cache hit rate:
TypeScript
1const stats = await recall.cache.stats();
2console.log("Hit rate:", stats.hit_rate);
3// Should be >90% for warm cache
  • Optimize cache strategy:
TypeScript
1const recall = new Recall({
2  cacheStrategy: "aggressive", // For read-heavy
3  cache: {
4    ttl: {
5      l1: 86400, // Increase L1 TTL
6      l2: 604800, // Increase L2 TTL
7    },
8  },
9});
  • Warm cache for active users:
TypeScript
1await recall.cache.optimize({
2  force_refresh: true,
3  max_memories: 1000,
4});

High Memory Usage

Symptoms:

  • Redis memory usage growing unbounded
  • OOM errors

Solutions:

  • Set max memory policy:
Bash
1# In redis.conf
2maxmemory 2gb
3maxmemory-policy allkeys-lru
  • Reduce cache size:
TypeScript
1const recall = new Recall({
2  cache: {
3    maxSize: 5000, // Reduce from default 10000
4  },
5});
  • Clear old data:
TypeScript
1await recall.cache.clear();

Data Issues

Duplicate Memories

Symptoms:

  • Same content appearing multiple times
  • Search returning duplicates

Solution: Mem0 handles deduplication automatically, but you can prevent client-side duplicates:

TypeScript
1async function addUnique(content: string, userId: string) {
2  // Check for existing
3  const existing = await recall.search({
4    query: content,
5    userId,
6    limit: 1,
7  });
8

9  if (existing.length === 0 || existing[0].score < 0.95) {
10    return await recall.add({ content, userId });
11  }
12

13  return existing[0];
14}

Missing Search Results

Symptoms:

  • Known memories not appearing in search
  • Empty results despite data existing

Solutions:

  • Force cloud search:
TypeScript
1const results = await recall.search({
2  query: "your query",
3  prefer_cache: false, // Bypass cache
4});
  • Check user ID:
TypeScript
1// Ensure consistent user IDs
2const results = await recall.search({
3  query: "test",
4  userId: "user_123", // Must match exactly
5});
  • Refresh cache:
TypeScript
1await recall.cache.optimize({
2  force_refresh: true,
3});

Async Processing Issues

Jobs Not Processing

Symptoms:

  • Memories stuck in 'queued' status
  • Background sync not working

Solutions:

  • Check job queue:
TypeScript
1const status = await recall.sync.status();
2console.log("Pending jobs:", status.pending);
  • Force synchronous mode:
TypeScript
1await recall.add({
2  content: "Important data",
3  async: false, // Process immediately
4});
  • Restart background worker:
Bash
1# Restart the MCP server
2pkill -f recall
3npx @n3wth/recall

Integration Issues

Claude Desktop Not Connecting

Error:

TEXT
1MCP server connection failed

Solutions:

  • Verify configuration path:
Bash
1# macOS/Linux
2cat ~/.claude/claude_desktop_config.json
3

4# Windows
5type %APPDATA%\Claude\claude_desktop_config.json
  • Check JSON syntax:
JSON
1{
2  "mcpServers": {
3    "recall": {
4      "command": "npx",
5      "args": ["@n3wth/recall"],
6      "env": {
7        "MEM0_API_KEY": "mem0_...",
8        "REDIS_URL": "redis://localhost:6379"
9      }
10    }
11  }
12}
  • Test manually:
Bash
1MEM0_API_KEY=your_key REDIS_URL=redis://localhost:6379 \
2  npx @n3wth/recall

TypeScript Type Errors

Error:

TEXT
1Type 'unknown' is not assignable to type 'Memory'

Solution:

TypeScript
1import { Recall, Memory, SearchResult } from "@n3wth/recall";
2

3// Type your responses
4const results: SearchResult = await recall.search({
5  query: "test",
6});
7

8results.memories.forEach((memory: Memory) => {
9  console.log(memory.content);
10});

Debugging Tips

Enable Debug Logging

TypeScript
1const recall = new Recall({
2  apiKey: process.env.MEM0_API_KEY,
3  debug: true, // Enable verbose logging
4});

Monitor Network Traffic

Bash
1# Watch Redis commands
2redis-cli monitor
3

4# Check API calls
5export DEBUG=recall:*
6npx @n3wth/recall

Health Checks

TypeScript
1async function checkHealth() {
2  try {
3    const health = await recall.health();
4    console.log("Redis:", health.redis);
5    console.log("Mem0:", health.mem0);
6    console.log("Cache:", health.cache);
7  } catch (error) {
8    console.error("Health check failed:", error);
9  }
10}

Getting Help

If you're still experiencing issues:

  • Check the examples in /docs/examples
  • Search existing issues on GitHub
  • Join our Discord for community support
  • Open an issue with:
    • Error message
    • Code snippet
    • Environment details
    • Steps to reproduce
ExamplesAI Intelligence Features