RecCall: Universal Context Management System

Record and Call context shortcuts across AI IDEs and environments. Now featuring ML-powered context generation, semantic search, and unified context management.

🚀 New in v2.0: Universal Context Management System with ML intelligence, hybrid search, and dynamic context generation from conversations.

🏗️ Architecture

RecCall has been refactored into a modular plugin-based architecture:

• Core Engine: Business logic, storage, repository management, caching
• Platform Adapters: CLI, MCP, VSCode, Warp, Perplexity, Sora
• Dependency Injection: Enterprise-ready IoC container
• Telemetry: Structured logging and performance monitoring

🚀 Features

Universal Context System (v2.0)

Three Context Types:

• Static Contexts: Pre-defined templates and guidelines
• Dynamic Contexts: ML-generated from conversations (auto-summarization, topic extraction, code references)
• Hybrid Contexts: Static templates enhanced with ML insights

ML-Powered Intelligence:

• Conversation summarization
• Code reference extraction
• Semantic embeddings for search
• Topic/keyword extraction

Hybrid Search:

• Keyword search (fast, exact matches)
• Semantic search (meaning-based similarity)
• Combined results for comprehensive discovery

Universal Commands

• rec: Record a shortcut with context/instructions
• call: Call (retrieve) stored context by shortcut name
• list: List all stored shortcuts
• update: Update an existing shortcut
• delete: Delete a shortcut (idempotent operation)
• purge: Purge all shortcuts (with confirmation)
• search: Search shortcuts by content

Context Commands (v2.0)

• context create: Create static contexts
• context get: Retrieve contexts by name or ID
• context search: Hybrid search (keyword + semantic)
• context list: List all contexts with filters
• context delete: Remove contexts
• context stats: View usage analytics

Repository Commands

• install: Install a recipe from the repository
• list-repo: List available recipes from repository
• search-repo: Search recipes in repository
• reload-starter-pack: Reload starter pack recipes

Multi-Platform Support

• 🖥️ Cursor IDE: MCP server integration with core engine
• 💻 VSCode: Native extension with Command Palette, powered by VSCodeAdapter
• ⚡ Warp Terminal: Shell integration via CLI commands (uses core engine)
• 🔧 CLI: Command-line interface for any terminal
• 🌐 Perplexity: Browser extension for AI search
• 🎬 Sora: Browser extension for video generation

All platforms now use the unified core engine, ensuring consistent behavior, caching, validation, and telemetry across all integrations.

Enterprise Features

• Type Safety: Strict TypeScript with branded types
• Dependency Injection: IoC container with tsyringe
• Telemetry: Structured logging with pino + Prometheus metrics
• Performance: Multi-layer caching with TTL
• Validation: Recipe validation with security checks
• Error Handling: Comprehensive error classes
• Storage Backends: Redis and PostgreSQL support for scalable deployments
• API Servers: Express.js and Fastify middleware for team API servers
• Webhooks: Event-driven integrations for external monitoring systems

📦 Installation

Quick Setup

curl -sfL https://reccaller.ai/install.sh | sh -

Manual Installation

npm install -g reccall

🎯 Usage

CLI - Shortcuts (v1.0)

# Record a shortcut
reccall rec react-component "Create React components with TypeScript, proper props, and hooks"

# Call a shortcut
reccall call react-component

# List all shortcuts
reccall list

# Install from repository
reccall install sync-main

CLI - Universal Context System (v2.0)

# Create a static context
reccall context create my-template \
  --content "# My Template\n\nGuidelines..." \
  --source global \
  --tags development \
  --category guides

# List all contexts
reccall context list

# Search contexts (hybrid: keyword + semantic)
reccall context search "API testing"

# Get a context
reccall context get my-template

# View statistics
reccall context stats

# Create dynamic context from conversation (via API/MCP)
# Automatically generates summary, topics, and embeddings

MCP (Cursor IDE)

{
  "mcpServers": {
    "reccall": {
      "command": "reccall-mcp",
      "args": []
    }
  }
}

By default, RecCall MCP server runs both stdio (for Cursor) and HTTP (for browser extensions) transports.

HTTP MCP Server (for Browser Extensions)

The HTTP MCP server runs on http://localhost:3000/mcp by default, enabling browser extensions (Perplexity, Sora) to connect via HTTP.

CLI Options:

# Default: both stdio and HTTP enabled
reccall-mcp

# Custom HTTP port
reccall-mcp --http-port 8080

# Only HTTP (for testing browser clients)
reccall-mcp --http-only

# Only stdio (Cursor only)
reccall-mcp --stdio-only

# Disable HTTP
reccall-mcp --no-http

Testing HTTP endpoint:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Browser Extensions

• Perplexity: Inject context into AI search queries
• Sora: Use video generation prompts with context shortcuts

🔧 Core Engine API

import { createCoreEngine } from 'reccall/core';

const engine = await createCoreEngine();
await engine.initialize();

// Record a shortcut
await engine.record('my-shortcut' as ShortcutId, 'My context instructions');

// Call a shortcut
const context = await engine.call('my-shortcut' as ShortcutId);

// List shortcuts
const shortcuts = await engine.list();

// Install from repository
await engine.installRecipe('https://contexts.reccaller.ai/' as RepositoryUrl, 'sync-main' as ShortcutId);

🏢 Enterprise Features

Dependency Injection

import { diContainer, TOKENS } from 'reccall/core';

// Register custom storage backend
diContainer.register(TOKENS.CONTEXT_STORAGE, RedisStorage);

// Get service
const engine = diContainer.get<ICoreEngine>(TOKENS.CORE_ENGINE);

Telemetry

import { telemetryManager } from 'reccall/core';

// Log custom events
telemetryManager.logEvent({
  event: 'custom.operation',
  timestamp: Date.now(),
  properties: { userId: '123' }
});

// Performance monitoring
@Performance('my-operation')
async myOperation() {
  // Method automatically monitored
}

Storage Backends

Redis Storage

import { RedisStorage } from 'reccall/storage-backends/redis';

const storage = new RedisStorage({
  url: 'redis://localhost:6379',
  keyPrefix: 'reccall:shortcuts:',
  ttl: 3600 // Optional TTL in seconds
});

const engine = await createCoreEngine({ storage });
await engine.initialize();

PostgreSQL Storage

import { PostgresStorage } from 'reccall/storage-backends/postgres';

const storage = new PostgresStorage({
  connectionString: 'postgresql://user:pass@localhost/reccall'
});

await storage.initialize(); // Creates schema
const engine = await createCoreEngine({ storage });
await engine.initialize();

API Servers

Express.js Middleware

import express from 'express';
import { createReccallMiddleware } from 'reccall/adapters/api/express';

const app = express();
app.use(express.json());

const middleware = await createReccallMiddleware({
  engine,
  basePath: '/api/reccall',
  authenticate: async (req) => {
    // Your authentication logic
    return await validateToken(req.headers.authorization);
  }
});

app.use(middleware);
app.listen(3000);

Fastify Plugin

import Fastify from 'fastify';
import reccallFastifyPlugin from 'reccall/adapters/api/fastify';

const fastify = Fastify({ logger: true });

await fastify.register(reccallFastifyPlugin, {
  engine,
  basePath: '/api/reccall',
  authenticate: async (request) => {
    return await validateToken(request.headers.authorization);
  }
});

await fastify.listen({ port: 3000 });

Webhooks

import { WebhookManager } from 'reccall/core/webhooks';

const webhookManager = new WebhookManager(true);

// Register webhook
webhookManager.register('slack-notifications', {
  url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
  secret: process.env.WEBHOOK_SECRET,
  events: ['shortcut.recorded', 'shortcut.deleted'],
  retries: 3,
  timeout: 5000
});

// Trigger webhook (automatically called by engine)
await engine.record('my-shortcut' as ShortcutId, 'Context');
// Webhook fires automatically: shortcut.recorded event

Prometheus Metrics

import { telemetryManager } from 'reccall/core/telemetry';
import express from 'express';

const app = express();

// Export Prometheus metrics
app.get('/metrics', (req, res) => {
  res.set('Content-Type', 'text/plain');
  res.send(telemetryManager.exportPrometheusMetrics());
});

🔌 Plugin Development

Creating a Platform Adapter

export class MyPlatformAdapter implements IPlatformAdapter {
  readonly platform = 'my-platform';
  readonly capabilities = {
    canRecord: true,
    canCall: true,
    canList: true,
    canUpdate: true,
    canDelete: true,
    canPurge: true,
    supportsRepository: true
  };

  async initialize(context: PlatformContext): Promise<void> {
    // Platform-specific initialization
  }

  async recordShortcut(): Promise<{ shortcut: ShortcutId; context: string } | null> {
    // Platform-specific UI for recording
  }

  // ... other methods
}

📊 Performance

RecCall is optimized for exceptional performance with intelligent caching and batched I/O operations:

Performance Characteristics

• Sub-millisecond operations: <1ms for cached rec and call operations
• Fast cold starts: <50ms for first write, <30ms for first read
• Efficient list operations: <10ms with caching
• Low MCP overhead: <5ms for Cursor IDE integration
• Optimized I/O: 90% reduction in disk writes through batching

Verified Performance Metrics

Based on architecture analysis and optimizations:

Operation	Cold Start	Cached	Improvement
rec	50-100ms	<1ms	50-100x faster
call	30-80ms	<1ms	30-80x faster
list	80ms	<10ms	8x faster
MCP overhead	10-50ms	<5ms	2-10x faster

Performance depends on cache configuration and workload. See Performance Guide for details.

Performance Features

• LRU cache with automatic eviction (lru-cache library)
• Atomic file operations prevent corruption
• Multi-layer caching (memory + disk) with configurable TTL
• Batched writes reduce I/O overhead by 90%
• Performance monitoring with automatic instrumentation
• Comprehensive metrics (operation counts, response times, cache hit rates)
• Structured logging for debugging and analytics

🔒 Security

• Recipe validation with security checks for malicious content
• Branded types prevent type confusion
• Input sanitization for all user inputs
• Reserved keyword detection prevents conflicts

📈 Monitoring

Metrics

• Shortcuts count
• Cache hit rate
• Repository status
• Performance metrics

Logging

• Structured JSON logs
• Performance timing
• Error tracking
• Event auditing

🛠️ Development

Prerequisites

• Node.js 18+
• TypeScript 5.6+
• npm, yarn, or pnpm
• Make (optional, but recommended for convenient commands)

Setup

git clone https://github.com/reccaller-ai/reccall.git
cd reccall
make install    # or: npm install
make build      # or: npm run build

Quick Commands (Makefile)

make help       # Show all available commands
make test       # Run tests
make lint       # Check code style
make lint-fix   # Auto-fix linting
make format     # Format code
make validate   # Run all validation checks
make pre-commit # Run pre-commit checks
make ci-all     # Run full CI pipeline locally

Testing

make test              # Run all tests
make test-watch        # Run tests in watch mode
make test-coverage     # Generate coverage report
# Or use npm directly:
npm test
npm run test:watch

Linting and Formatting

make lint          # Check code style
make lint-fix       # Auto-fix linting issues
make format         # Format code
make format-check   # Check formatting
# Or use npm directly:
npm run lint
npm run lint:fix

CI/CD Commands

make ci-all         # Run complete CI pipeline (recommended)
make ci-deps        # Install dependencies
make ci-type-check  # Type checking
make ci-lint        # Linting
make ci-test        # Tests with coverage
make ci-security    # Security audit
make ci-build       # Build

See Makefile Documentation for complete usage guide.

📚 Documentation

• Universal Context System ⭐ NEW - Complete guide to the context management system
• Plugin Development Guide
• API Reference
• Enterprise Deployment
• Enterprise API Server Guide
• Security Best Practices
• Migration Guide

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE for details.

🔗 Links

• Main Site: https://reccaller.ai (website hosted at reccaller-ai/websites)
• Repository: https://github.com/reccaller-ai/reccall
• Contexts: https://contexts.reccaller.ai
• Issues: https://github.com/reccaller-ai/reccall/issues

---

RecCall - Universal AI Context Engine for the modern developer.