Mnemo

🚀 Mnemo

Mnemo extends the memory of AI assistants through Gemini context caching. It (Greek: memory) enables AI assistants like Claude to access large codebases, documentation sites, PDFs, and more by leveraging Gemini's 1M token context window and context caching features.

🚀 Quick Start

Mnemo gives AI assistants access to various resources. You can start using it by choosing one of the deployment options below.

✨ Features

• Perfect recall: No chunking or retrieval means no lost context.
• Lower latency: Cached context is served quickly.
• Cost savings: Cached tokens cost 75 - 90% less than regular input tokens.
• Simplicity: No vector databases, embeddings, or complex retrieval logic.

📦 Installation

Mnemo can be deployed in three ways depending on your needs.

Option 1: Local Server (Development & Full Features)

Best for development and when you need to load local files.

# Clone and install
git clone https://github.com/logos-flux/mnemo
cd mnemo
bun install

# Set your Gemini API key
export GEMINI_API_KEY=your_key_here

# Start the server
bun run dev

Claude Code MCP config:

{
  "mcpServers": {
    "mnemo": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Option 2: Self-Hosted Cloudflare Worker (Recommended for Claude.ai)

Deploy to your own Cloudflare account. You control your data and costs. Prerequisites:

• Cloudflare account (free tier works)
• Gemini API key

# Clone and install
git clone https://github.com/logos-flux/mnemo
cd mnemo/packages/cf-worker

# Configure secrets
bunx wrangler secret put GEMINI_API_KEY
bunx wrangler secret put MNEMO_AUTH_TOKEN  # Optional but recommended

# Create D1 database
bunx wrangler d1 create mnemo-cache

# Deploy
bunx wrangler deploy

Claude.ai MCP config:

{
  "mcpServers": {
    "mnemo": {
      "type": "http",
      "url": "https://mnemo.<your-subdomain>.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AUTH_TOKEN"
      }
    }
  }
}

Why use this? Claude.ai can't connect to localhost. The Worker gives you an external endpoint that Claude.ai can reach.

Option 3: Managed Hosting (VIP)

Don't want to manage infrastructure? We offer fully managed Mnemo hosting for select clients. Includes:

• Dedicated Worker deployment
• Priority support
• Custom domain
• Usage monitoring Contact: lf@logosflux.io for pricing and availability.

💻 Usage Examples

Basic Usage

# Load a GitHub repo
curl -X POST http://localhost:8080/tools/context_load \
  -H "Content-Type: application/json" \
  -d '{"source": "https://github.com/honojs/hono", "alias": "hono"}'

# Load a documentation site (crawls up to token target)
curl -X POST http://localhost:8080/tools/context_load \
  -H "Content-Type: application/json" \
  -d '{"source": "https://hono.dev/docs", "alias": "hono-docs"}'

# Load a PDF
curl -X POST http://localhost:8080/tools/context_load \
  -H "Content-Type: application/json" \
  -d '{"source": "https://arxiv.org/pdf/2303.08774.pdf", "alias": "gpt4-paper"}'

# Load a private repo (with GitHub token)
curl -X POST http://localhost:8080/tools/context_load \
  -H "Content-Type: application/json" \
  -d '{"source": "https://github.com/owner/private-repo", "alias": "private", "githubToken": "ghp_xxx"}'

# Load multiple sources into one cache
curl -X POST http://localhost:8080/tools/context_load \
  -H "Content-Type: application/json" \
  -d '{"sources": ["https://github.com/owner/repo", "https://docs.example.com"], "alias": "combined"}'

# Query the cache
curl -X POST http://localhost:8080/tools/context_query \
  -H "Content-Type: application/json" \
  -d '{"alias": "hono", "query": "How do I add middleware?"}'

# List active caches
curl -X POST http://localhost:8080/tools/context_list \
  -H "Content-Type: application/json" -d '{}'

# Get usage stats with cost tracking
curl -X POST http://localhost:8080/tools/context_stats \
  -H "Content-Type: application/json" -d '{}'

# Evict when done
curl -X POST http://localhost:8080/tools/context_evict \
  -H "Content-Type: application/json" \
  -d '{"alias": "hono"}'

CLI

# Start server
mnemo serve

# Start MCP stdio transport (for Claude Desktop)
mnemo stdio

# Load a project
mnemo load ./my-project my-proj

# Query
mnemo query my-proj "What's the main entry point?"

# List caches
mnemo list

# Remove cache
mnemo evict my-proj

📚 Documentation

MCP Tools

context_load Parameters

Configuration

Authentication

When MNEMO_AUTH_TOKEN is configured, the /mcp and /tools/* endpoints require authentication:

# Set auth token (Workers)
bunx wrangler secret put MNEMO_AUTH_TOKEN

# Requests must include header:
Authorization: Bearer your-token-here

Public endpoints (no auth required):

• GET /health - Health check
• GET / - Service info
• GET /tools - List available tools

What Can Mnemo Load?

Costs

You always pay for Gemini API usage regardless of deployment option. Mnemo uses Gemini's context caching which is significantly cheaper than standard input:

• Workers: Free tier includes 100K requests/day
• D1: Free tier includes 5M reads/day
• Likely $0 for moderate usage

Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Mnemo                                │
├─────────────────────────────────────────────────────────────┤
│  MCP Tools                                                   │
│  • context_load    - Load into Gemini cache                 │
│  • context_query   - Query cached context                   │
│  • context_list    - Show active caches                     │
│  • context_evict   - Remove cache                           │
│  • context_stats   - Token usage, costs                     │
│  • context_refresh - Reload cache                           │
├─────────────────────────────────────────────────────────────┤
│  Adapters (v0.2)                                             │
│  • GitHub repos (via API)                                   │
│  • URL loading (HTML, PDF, JSON, text)                      │
│  • Token-targeted crawling                                  │
│  • robots.txt compliance                                    │
├─────────────────────────────────────────────────────────────┤
│  Packages                                                    │
│  • @mnemo/core      - Gemini client, loaders, adapters      │
│  • @mnemo/mcp-server - MCP protocol handling                │
│  • @mnemo/cf-worker - Cloudflare Workers deployment         │
│  • @mnemo/local     - Bun-based local server                │
└─────────────────────────────────────────────────────────────┘

📄 License

MIT

👏 Credits

Built by Logos Flux | Voltage Labs