N3wth R3

r3 (by n3wth)

[](https://www.npmjs.com/package/@n3wth/r3) [](https://www.npmjs.com/package/@n3wth/r3) [](https://opensource.org/licenses/MIT) [](https://r3.newth.ai)

Intelligent memory MCP for AI apps

Features

• 🚀 Fast local caching - Redis L1 cache for low-latency responses
• 🛡️ Automatic failover - Falls back to cloud storage when Redis is unavailable
• 🧠 AI Intelligence (NEW) - Real vector embeddings, entity extraction, knowledge graphs
• 🔌 Easy integration - Works with Gemini, Claude, GPT, and any LLM
• 💻 100% TypeScript - Full type safety and IntelliSense support
• 🏠 Local-first - Works offline with embedded Redis server
• 📦 Zero configuration - Just run npx r3 to get started

New AI Intelligence Features (v1.3.0)

• Real Vector Embeddings - 384-dimensional embeddings using transformers.js
• Entity Extraction - Automatically extract people, organizations, technologies, projects
• Relationship Mapping - Discover connections between entities with confidence scores
• Knowledge Graph - Build and query your personal knowledge graph
• Semantic Search - Find memories by meaning, not just keywords
• Multi-factor Relevance - Combines semantic, keyword, entity, and recency scoring

Table of Contents

• [Quick Start](#quick-start)
• [Usage with Gemini CLI](#usage-with-gemini-cli)
• [Usage with Claude Code](#usage-with-claude-code)
• [Usage with Claude Desktop](#usage-with-claude-desktop)
• [Architecture](#architecture)
• [API Reference](#api-reference)
• [Examples](#real-world-examples)
• [Deployment](#deployment)
• [Contributing](#contributing)
• [License](#license)

Quick Start

# Just run it! Zero configuration needed
npx @n3wth/r3

That's it! r3 automatically starts with an embedded Redis server. No setup required.

Installation Options

# For frequent use, install globally:
npm install -g @n3wth/r3
r3

# Or add to your project:
npm install @n3wth/r3

Basic Usage

import { Recall } from "r3";

// Zero configuration - works immediately
const recall = new Recall();

// Store memory locally
await recall.add({
  content: "User prefers TypeScript and dark mode themes",
  userId: "user_123",
});

// Retrieve memories instantly
const memories = await recall.search({
  query: "What are the user preferences?",
  userId: "user_123",
});

Optional: Enable Cloud Sync

// Add Mem0 API key for cloud backup (get free at mem0.ai)
const recall = new Recall({
  apiKey: process.env.MEM0_API_KEY,
});

Usage with Gemini CLI

Integrate r3 with Google's Gemini CLI for powerful memory-enhanced AI workflows:

# Set environment variables
export MEM0_API_KEY="your_mem0_api_key"
export REDIS_URL="redis://localhost:6379"

# Use with Gemini for context-aware responses
gemini "Remember: User prefers Python over JavaScript" | npx r3 add
gemini "What are my coding preferences?" | npx r3 search

# Advanced integration with piping
echo "Project uses TypeScript and React" | npx r3 add --userId project-123
gemini "Generate component based on project stack" --context "$(npx r3 get --userId project-123)"

Usage with Claude Code

# Quick install via Claude Code CLI
claude mcp add @n3wth/r3 "npx @n3wth/r3"

# Claude Code will now remember context across sessions
# Available commands in Claude:
# - add_memory: Store information
# - search_memory: Query memories
# - get_all_memories: List all stored data

Usage with Claude Desktop

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "r3": {
      "command": "npx",
      "args": ["r3"],
      "env": {
        "MEM0_API_KEY": "your_mem0_api_key",
        "REDIS_URL": "redis://localhost:6379"
      }
    }
  }
}

Architecture

r3 implements a multi-tier caching strategy designed for AI workloads:

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│ Application │ ───► │   L1 Cache   │ ───► │  L2 Cache   │ ───► Cloud Storage
│             │      │   (Redis)    │      │  (Weekly)   │      (Permanent)
└─────────────┘      └──────────────┘      └─────────────┘
                          Fast                 Faster              Reliable

Core Features

Intelligent Caching

Automatically optimizes data placement across cache tiers based on access patterns:

const recall = new Recall({
  cacheStrategy: "aggressive", // 'balanced' | 'conservative'
  cache: {
    ttl: { l1: 86400, l2: 604800 },
    maxSize: 10000,
    compressionThreshold: 1024,
  },
});

Semantic Search

Find memories by meaning, not just keywords:

const results = await recall.search({
  query: "notification preferences",
  limit: 10,
  threshold: 0.8,
});

Monitoring Support

Includes basic monitoring capabilities:

// Monitor cache performance
const stats = await recall.cacheStats();
console.log(`Hit rate: ${stats.hitRate}%`);
console.log(`Avg latency: ${stats.avgLatency}ms`);

// Health checks
const health = await recall.health();
if (!health.redis.connected) {
  // Automatic failover to cloud storage
}

Real-World Examples

Next.js App Router

// app/api/memory/route.ts
import { Recall } from "r3";
import { NextResponse } from "next/server";

const recall = new Recall({
  apiKey: process.env.MEM0_API_KEY!,
  redis: process.env.REDIS_URL,
});

export async function POST(request: Request) {
  const { content, userId } = await request.json();

  const result = await recall.add({
    content,
    userId,
    metadata: {
      source: "web_app",
      timestamp: new Date().toISOString(),
    },
  });

  return NextResponse.json(result);
}

LangChain Integration

from langchain.memory import BaseChatMemory
from recall import RecallClient

class RecallMemory(BaseChatMemory):
    def __init__(self, user_id: str):
        self.recall = RecallClient(
            api_key=os.getenv("MEM0_API_KEY"),
            user_id=user_id
        )

    def save_context(self, inputs, outputs):
        self.recall.add(
            content=f"{inputs['input']} → {outputs['output']}",
            priority="high"
        )

Vercel AI SDK

import { createAI } from "ai";
import { Recall } from "r3";

const recall = new Recall({ apiKey: process.env.MEM0_API_KEY! });

export const ai = createAI({
  async before(messages) {
    const memories = await recall.search({
      query: messages[messages.length - 1].content,
      limit: 5,
    });

    return {
      ...messages,
      context: memories.map((m) => m.content).join("\n"),
    };
  },
});

Performance Characteristics

r3 is designed for speed with local Redis caching. In local development:

• Redis provides fast in-memory caching
• Automatic compression for larger entries
• Efficient connection pooling
• Falls back gracefully when Redis is unavailable

Note: Actual performance depends on your Redis setup and network conditions.

AI Intelligence Features

r3 now includes advanced AI capabilities that automatically enhance your memory storage:

Automatic Entity Extraction

Every memory is analyzed to extract:

• People - Names and references to individuals
• Organizations - Companies, teams, groups
• Technologies - Programming languages, frameworks, tools
• Projects - Project names and initiatives
• Dates - Temporal references

Knowledge Graph Construction

Build a connected knowledge graph from your memories:

# Extract entities from text
npx r3 extract-entities "Sarah from Marketing works on the Dashboard project with React"

# Query your knowledge graph
npx r3 get-knowledge-graph --entity-type "people"

# Find connections between entities
npx r3 find-connections --from "Sarah" --to "Dashboard"

Semantic Search with Relevance Scoring

Search uses multiple factors for intelligent ranking:

• Semantic similarity (50%) - Meaning-based matching
• Keyword overlap (20%) - Traditional text matching
• Entity matching (15%) - Shared people, orgs, tech
• Recency bonus (10%) - Prefer recent memories
• Access frequency (5%) - Popular memories rank higher

Performance

• **

Redis connection refused

Ensure Redis is running and accessible:

# Check Redis status
redis-cli ping

# Start Redis locally
redis-server

# Or use Docker
docker run -d -p 6379:6379 redis:alpine

High latency on first request

This is normal cold start behavior. r3 pre-warms connections:

// Pre-warm on startup
await recall.warmup();

Memory quota exceeded

Configure cache eviction policy:

const recall = new Recall({
  cache: {
    maxSize: 5000,
    evictionPolicy: "lru",
  },
});

Roadmap

• [ ] Edge deployment - Global distribution via Cloudflare Workers
• [ ] Encryption at rest - End-to-end encryption for sensitive data
• [ ] Real-time sync - WebSocket support for live updates
• [ ] GraphQL API - Alternative query interface
• [ ] Batch operations - Bulk import/export capabilities
• [ ] Analytics dashboard - Visual insights into memory patterns

Contributing

We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

# Development setup
git clone https://github.com/n3wth/r3.git
cd recall
npm install
npm run dev

# Run tests
npm test

# Submit PR
gh pr create

Support

• Documentation: r3.newth.ai
• Issue Tracker: GitHub Issues

License

MIT © 2025 r3 Contributors

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: n3wth
• Source: n3wth/r3
• License: MIT
• Homepage: https://r3.newth.ai

Install and usage instructions live in the source repository linked above.