# 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:**

```
Error: Redis connection failed: ECONNREFUSED 127.0.0.1:6379
```

**Solutions:**

- **Verify Redis is running:**

```bash
redis-cli ping
# Should return: PONG
```

- **Start Redis if needed:**

```bash
# macOS
brew services start redis

# Linux
sudo systemctl start redis

# Docker
docker run -d -p 6379:6379 redis:alpine
```

- **Check Redis URL format:**

```typescript
// Correct formats
redis://localhost:6379
redis://username:password@host:6379
redis://host:6379/0  // With database number
```

### Mem0 API Connection Failed

**Error:**

```
Error: Mem0 API error: 401 Unauthorized
```

**Solutions:**

- **Verify API key:**

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

- **Check environment variables:**

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

- **Regenerate API key** at [mem0.ai/dashboard](https://mem0.ai)

## Performance Issues

### Slow Response Times

**Symptoms:**

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

**Solutions:**

- **Check cache hit rate:**

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

- **Optimize cache strategy:**

```typescript
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
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
# In redis.conf
maxmemory 2gb
maxmemory-policy allkeys-lru
```

- **Reduce cache size:**

```typescript
const recall = new Recall({
  cache: {
    maxSize: 5000, // Reduce from default 10000
  },
});
```

- **Clear old data:**

```typescript
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
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
const results = await recall.search({
  query: "your query",
  prefer_cache: false, // Bypass cache
});
```

- **Check user ID:**

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

- **Refresh cache:**

```typescript
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
const status = await recall.sync.status();
console.log("Pending jobs:", status.pending);
```

- **Force synchronous mode:**

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

- **Restart background worker:**

```bash
# Restart the MCP server
pkill -f recall
npx @n3wth/recall
```

## Integration Issues

### Antigravity CLI Not Connecting

**Error:**

```
MCP server connection failed
```

**Solutions:**

- **Verify configuration path:**

```bash
# macOS/Linux
cat ~/.gemini/settings.json

# Windows
type %USERPROFILE%\.gemini\settings.json
```

- **Check JSON syntax:**

```json
{
  "mcpServers": {
    "recall": {
      "command": "npx",
      "args": ["@n3wth/recall"],
      "env": {
        "MEM0_API_KEY": "mem0_...",
        "REDIS_URL": "redis://localhost:6379"
      }
    }
  }
}
```

- **Test manually:**

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

### TypeScript Type Errors

**Error:**

```
Type 'unknown' is not assignable to type 'Memory'
```

**Solution:**

```typescript
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
const recall = new Recall({
  apiKey: process.env.MEM0_API_KEY,
  debug: true, // Enable verbose logging
});
```

### Monitor Network Traffic

```bash
# Watch Redis commands
redis-cli monitor

# Check API calls
export DEBUG=recall:*
npx @n3wth/recall
```

### Health Checks

```typescript
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](https://github.com/n3wth/recall/issues)
- **Join our Discord** for community support
- **Open an issue** with:
  - Error message
  - Code snippet
  - Environment details
  - Steps to reproduce

Source: https://r3.n3wth.com/docs/troubleshooting