r3 Troubleshooting Guide

Common issues and solutions when working with r3, the open-source local Redis memory MCP server (npx @n3wth/r3).

Connection Issues

Redis Connection Failed

Error:

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

Solutions:

• Verify Redis is running:

bash
1
2
redis-cli ping
# Should return: PONG

• Start Redis if needed:

bash
1
2
3
4
5
6
7
8
# macOS
brew services start redis
​
# Linux
sudo systemctl start redis
​
# Docker
docker run -d -p 6379:6379 redis:alpine

• Check Redis URL format:

typescript
1
2
3
4
// Correct formats
redis://localhost:6379
redis://username:password@host:6379
redis://host:6379/0  // With database number

Mem0 API Connection Failed

Error:

text
1
Error: Mem0 API error: 401 Unauthorized

Solutions:

• Verify API key:

bash
1
2
curl -H "Authorization: Bearer $MEM0_API_KEY" \
  https://api.mem0.ai/v1/memories

• Check environment variables:

typescript
1
2
console.log(process.env.MEM0_API_KEY);
// Should not be undefined

• Regenerate API key at mem0.ai/dashboard

Performance Issues

Slow Response Times

Symptoms:

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

Solutions:

• Check cache hit rate:

typescript
1
2
3
const stats = await recall.cache.stats();
console.log("Hit rate:", stats.hit_rate);
// Should be >90% for warm cache

• Optimize cache strategy:

typescript
1
2
3
4
5
6
7
8
9
const recall = new Recall({
  cacheStrategy: "aggressive", // For read-heavy
  cache: {
    ttl: {
      l1: 86400, // Increase L1 TTL
      l2: 604800, // Increase L2 TTL
    },
  },
});

• Warm cache for active users:

typescript
1
2
3
4
await recall.cache.optimize({
  force_refresh: true,
  max_memories: 1000,
});

High Memory Usage

Symptoms:

• Redis memory usage growing unbounded
• OOM errors

Solutions:

• Set max memory policy:

bash
1
2
3
# In redis.conf
maxmemory 2gb
maxmemory-policy allkeys-lru

• Reduce cache size:

typescript
1
2
3
4
5
const recall = new Recall({
  cache: {
    maxSize: 5000, // Reduce from default 10000
  },
});

• Clear old data:

typescript
1
await 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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
async function addUnique(content: string, userId: string) {
  // Check for existing
  const existing = await recall.search({
    query: content,
    userId,
    limit: 1,
  });
​
  if (existing.length === 0 || existing[0].score < 0.95) {
    return await recall.add({ content, userId });
  }
​
  return existing[0];
}

Missing Search Results

Symptoms:

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

Solutions:

• Force cloud search:

typescript
1
2
3
4
const results = await recall.search({
  query: "your query",
  prefer_cache: false, // Bypass cache
});

• Check user ID:

typescript
1
2
3
4
5
// Ensure consistent user IDs
const results = await recall.search({
  query: "test",
  userId: "user_123", // Must match exactly
});

• Refresh cache:

typescript
1
2
3
await recall.cache.optimize({
  force_refresh: true,
});

Async Processing Issues

Jobs Not Processing

Symptoms:

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

Solutions:

• Check job queue:

typescript
1
2
const status = await recall.sync.status();
console.log("Pending jobs:", status.pending);

• Force synchronous mode:

typescript
1
2
3
4
await recall.add({
  content: "Important data",
  async: false, // Process immediately
});

• Restart background worker:

bash
1
2
3
# Restart the MCP server
pkill -f recall
npx @n3wth/recall

Integration Issues

Antigravity CLI Not Connecting

Error:

text
1
MCP server connection failed

Solutions:

• Verify configuration path:

bash
1
2
3
4
5
# macOS/Linux
cat ~/.gemini/settings.json
​
# Windows
type %USERPROFILE%\.gemini\settings.json

• Check JSON syntax:

json
1
2
3
4
5
6
7
8
9
10
11
12
{
  "mcpServers": {
    "recall": {
      "command": "npx",
      "args": ["@n3wth/recall"],
      "env": {
        "MEM0_API_KEY": "mem0_...",
        "REDIS_URL": "redis://localhost:6379"
      }
    }
  }
}

• Test manually:

bash
1
2
MEM0_API_KEY=your_key REDIS_URL=redis://localhost:6379 \
  npx @n3wth/recall

TypeScript Type Errors

Error:

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

Solution:

typescript
1
2
3
4
5
6
7
8
9
10
import { Recall, Memory, SearchResult } from "@n3wth/recall";
​
// Type your responses
const results: SearchResult = await recall.search({
  query: "test",
});
​
results.memories.forEach((memory: Memory) => {
  console.log(memory.content);
});

Debugging Tips

Enable Debug Logging

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

Monitor Network Traffic

bash
1
2
3
4
5
6
# Watch Redis commands
redis-cli monitor
​
# Check API calls
export DEBUG=recall:*
npx @n3wth/recall

Health Checks

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

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