Mnemo

Extended memory for AI assistants via Gemini context caching.

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

Why Mnemo?

Instead of complex RAG pipelines with embeddings and retrieval, Mnemo takes a simpler approach:

Load your entire codebase into Gemini's context cache
Query it with natural language
Let Claude orchestrate while Gemini holds the context

This gives you:

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

What Can Mnemo Load?

Source	Local Server	Worker
GitHub repos (public)	✅	✅
GitHub repos (private)	✅	✅
Any URL (docs, articles)	✅	✅
PDF documents	✅	✅
JSON APIs	✅	✅
Local files/directories	✅	❌
Multi-page crawls	✅ unlimited	✅ 40 pages max

Deployment Options

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

# 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

MCP Tools

Tool	Description
`context_load`	Load GitHub repos, URLs, PDFs, or local dirs into Gemini cache
`context_query`	Query a cached context with natural language
`context_list`	List all active caches with token counts and expiry
`context_evict`	Remove a cache
`context_stats`	Get usage statistics with cost tracking
`context_refresh`	Reload a cache with fresh content

context_load Parameters

Parameter	Description
`source`	Single source: GitHub URL, any URL, or local path
`sources`	Multiple sources to combine into one cache
`alias`	Friendly name for this cache (1-64 chars)
`ttl`	Time to live in seconds (60-86400, default 3600)
`githubToken`	GitHub token for private repos
`systemInstruction`	Custom system prompt for queries

Configuration

Variable	Description	Default
`GEMINI_API_KEY`	Your Gemini API key	Required
`MNEMO_PORT`	Server port (local only)	8080
`MNEMO_DIR`	Data directory (local only)	~/.mnemo
`MNEMO_AUTH_TOKEN`	Auth token for protected endpoints	None

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

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:

Resource	Cost
Cache storage	~$4.50 per 1M tokens per hour
Cached input	75-90% discount vs regular input
Regular input	~$0.075 per 1M tokens (Flash)

Example: 100K token codebase cached for 1 hour with 10 queries ≈ $0.47

Cloudflare costs (self-hosted):

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