GraphMind

Voice-first personal knowledge assistant with GraphRAG on Cloudflare's edge network.

What is GraphMind?

GraphMind is an intelligent "second brain" that captures, organizes, and retrieves your personal knowledge through natural voice conversations. It combines real-time voice AI with graph-based retrieval-augmented generation (GraphRAG) to provide 90%+ accuracy in knowledge retrieval.

Key Features

• Voice-First Design - Natural conversation interface for capturing and querying knowledge
• GraphRAG Technology - 90%+ accuracy vs 56% with traditional RAG
• Edge-Native - Runs on Cloudflare's global network for low latency
• Privacy-First - Isolated user data with FalkorDB namespaces
• 100% Open Source - Built on open standards and technologies

Completed Features

✅ Feature 006: Knowledge Graph Building (Production Ready)

Automatic knowledge graph construction from voice notes with intelligent entity management:

• Automatic Graph Population - Voice notes automatically create graph nodes within 51ms (p95)
• Entity Deduplication - 100% accuracy in merging entity variants (e.g., "Sarah" + "Sarah Johnson")
• High-Performance Queries - Sub-10ms query latency, 84% cache hit rate
• User Isolation - Complete namespace separation with zero data leakage
• 7 Entity Types - Person, Project, Meeting, Topic, Technology, Location, Organization
• 8 Relationship Types - WORKED_WITH, WORKS_ON, ATTENDED, DISCUSSED, and more
• REST API - 12 endpoints for graph retrieval, search, CRUD operations
• Production Hardening - Error handling, retry logic, observability, structured logging

Performance Achievements:

• 🚀 Uncached queries: 9ms p95 (98% better than target)
• 🚀 Cached queries: ~8ms p95 (92% better than target)
• 🚀 Multi-hop queries: 3ms p95 (99.7% better than target)
• 🚀 Entity deduplication: 100% accuracy

See Feature 006 Docs for API documentation.

---

Technology Stack

• Runtime: Cloudflare Workers (serverless edge compute)
• Voice AI: Pipecat + Deepgram (STT/TTS) + Llama 3.1-8b (entity extraction)
• Knowledge Graph: FalkorDB + GraphRAG SDK
  • Development: Self-hosted Docker (localhost, sub-millisecond performance)
  • Production: Flexible deployment (VPS or FalkorDB Cloud, TBD)
• Storage: D1 (SQLite), KV (cache), R2 (audio)
• Frontend: Cloudflare Pages + WebRTC

Project Status

Current Phase: Phase 1 - Foundation (In Progress)

• ✅ Planning Complete
• ✅ Wrangler Configuration & Project Setup (Feature 001) - Complete
• 🚧 Phase 1 (Foundation): In Progress
• Target MVP: 12 weeks from start

See Implementation Phases for details.

Setup

Prerequisites

Before starting, ensure you have:

• Node.js 18+ (verify with node --version)
• npm or pnpm package manager
• Cloudflare account with API token (Get token here)

Installation

1. Clone the repository

   git clone <repo-url>
   cd graphmind

2. Configure environment variables

   cp .env.example .env
   # Edit .env and fill in:
   # - CLOUDFLARE_API_TOKEN (from Cloudflare dashboard)
   # - CLOUDFLARE_ACCOUNT_ID (from Cloudflare dashboard)
   # - FalkorDB will be configured in next step

2a. FalkorDB Setup (required for Feature 003+)

**Development (Recommended):**
```bash
# Run FalkorDB Docker container locally
docker run -d \
  --name falkordb-local \
  -p 6383:6379 \
  -v $(pwd)/falkordb-data:/data \
  falkordb/falkordb:latest

# Add to .env (already configured by default):
FALKORDB_HOST=localhost
FALKORDB_PORT=6383
FALKORDB_USER=default
FALKORDB_PASSWORD=
```

**Performance:** Sub-millisecond query times (<1ms connections, 0.32ms node creation)

See [docs/PRD/technical/falkordb-deployment.md](docs/PRD/technical/falkordb-deployment.md) for production options.

3. Install dependencies

   npm install

4. Create D1 database

   npm run db:create

   Copy the database_id from the output and paste it into wrangler.toml under [[d1_databases]]

5. Create KV namespace

   npm run kv:create

   Copy the id from the output and paste it into wrangler.toml under [[kv_namespaces]]

6. Run database migrations

   npm run db:migrate:local

7. Start development server

   npm run dev

8. Verify setup Visit http://localhost:8787/ - you should see a JSON health check response with all bindings showing as available.

See docs/SETUP.md for complete setup instructions.

For Claude Code Users

If you're using Claude Code to work on this project:

1. Setup Wrangler: Follow docs/SETUP.md for Cloudflare authentication
2. Setup MCP Servers: Follow docs/MCP_SETUP.md for Cloudflare MCP integration
3. Read CLAUDE.md: Project context for Claude Code

Documentation

Getting Started

• docs/SETUP.md - Complete development environment setup
• docs/MCP_SETUP.md - Cloudflare MCP servers for Claude Code
• CLAUDE.md - Project context for AI assistants

Product & Requirements

• PRD Overview - Product requirements documentation map
• Product Requirements - Complete PRD (comprehensive)
• Changelog - Documentation version history

Implementation Phases

• Phase 1: Foundation (Weeks 1-3) - Auth, voice capture, transcription
• Phase 2: Knowledge Graph (Weeks 4-6) - Entity extraction, graph building
• Phase 3: Voice Query (Weeks 7-9) - GraphRAG retrieval, Q&A
• Phase 4: Polish (Weeks 10-12) - Multi-source ingestion, search, UX
• Phase 5: Advanced (Future) - Collaboration, integrations, analytics

Technical Specifications

• Database Schemas - D1, FalkorDB, KV, R2
• FalkorDB Deployment Options - Development & production configurations
• API Specifications - REST + WebSocket endpoints
• Non-Functional Requirements - Performance, security, costs

Project Management

• Success Metrics - KPIs and targets
• Risks & Mitigations - Risk register

Architecture Overview

Data Flow: Voice Note Capture

User speaks → WebRTC → Deepgram STT → Transcript
     ↓
Llama 3.1 entity extraction → Entities/Relationships
     ↓
FalkorDB GraphRAG → Knowledge Graph update
     ↓
Store in D1 → Return success

Data Flow: Voice Query

User asks question → WebRTC → Deepgram STT → Question
     ↓
FalkorDB GraphRAG → Cypher query generation
     ↓
Execute query → Results → Llama 3.1 answer generation
     ↓
Deepgram TTS → Audio response → Stream to user

Development Commands

Local Development

# Start local dev server (with hot reload)
npm run dev

# Generate TypeScript types for Cloudflare bindings
npm run cf-typegen

Database Management

# Create D1 database
npm run db:create

# Apply migrations locally
npm run db:migrate:local

# Apply migrations to remote database
npm run db:migrate

# Execute SQL against local database
npm run db:shell "SELECT * FROM users;"

Key-Value Store

# Create KV namespace
npm run kv:create

Deployment

# Deploy to production (requires configured wrangler.toml)
npm run deploy

Testing

# Run tests (when implemented)
npm test

Type Checking

This project uses JSDoc + TypeScript for type checking without a build step. This provides ~80% of TypeScript benefits with minimal disruption.

# One-time type check
npm run typecheck

# Watch mode (continuous checking)
npm run typecheck:watch

Adding Types to New Files:

Add // @ts-check at the top of any JavaScript file to enable type checking:

// @ts-check
/// <reference path="../types/cloudflare.d.ts" />

/**
 * @param {string} name - User name
 * @param {number} age - User age
 * @returns {string} Greeting message
 */
function greet(name, age) {
  return `Hello ${name}, you are ${age} years old`;
}

Type Definition Files:

• types/cloudflare.d.ts - Cloudflare Workers bindings (Env, ExecutionContext)
• types/common.d.ts - Shared project types (ErrorWithCode, Logger)
• src/lib/falkordb/types.js - FalkorDB type definitions
• src/durable-objects/types.js - Durable Object types

IDE Support:

• VSCode: Automatic (uses .vscode/settings.json)
• WebStorm: Enable TypeScript service for JavaScript
• Vim/Neovim: Use coc-tsserver or nvim-lspconfig

Pre-commit Hook: Type checking runs automatically on commit via Husky. Commits will fail if type errors are present.

Troubleshooting

Port Conflicts

Problem: "Address already in use" error when starting dev server

Solution:

# Find and kill process using port 8787
lsof -ti:8787 | xargs kill -9

# Or specify a different port
npx wrangler dev --port 8788

Missing Credentials

Problem: "Authentication error" or "API token invalid"

Solution:

1. Verify your .env file exists and has correct values
2. Get a new API token from https://dash.cloudflare.com/profile/api-tokens
3. Ensure the token has proper permissions (Edit Cloudflare Workers)
4. Check that CLOUDFLARE_ACCOUNT_ID matches your account

Database Not Found

Problem: "Database not found" when running migrations

Solution:

1. Ensure you've created the database: npm run db:create
2. Copy the database_id from output into wrangler.toml
3. Try again: npm run db:migrate:local

Wrangler Configuration Invalid

Problem: "Invalid configuration" error

Solution:

# Verify wrangler.toml syntax
npx wrangler whoami

# Check for empty binding IDs - they should be filled in after service creation

Cost Structure

• Local Development: $0/month (Self-hosted Docker + Cloudflare free tiers)
• Production (VPS Self-Hosted): ~$15-30/month (VPS $10-25 + Cloudflare $5)
• Production (FalkorDB Cloud): ~$20-55/month (Starter $15 or Pro $50 + Cloudflare $5)

Workers AI is currently free during beta. Production deployment option TBD.

See FalkorDB Deployment Options for detailed comparisons.

Contributing

This project is in early development. Contribution guidelines will be added once Phase 1 is complete.

Key Technologies

• Cloudflare Workers - Edge compute platform
• FalkorDB - Knowledge graph database
• GraphRAG SDK - Graph-based RAG
• Pipecat - Voice AI framework
• Deepgram - STT/TTS models
• Llama 3.1-8b - Entity extraction & Q&A

License

MIT License (TBD - to be formalized)

Support

• Issues: GitHub Issues (link TBD)
• Documentation: See docs/PRD/README_PRD.md
• Discussions: GitHub Discussions (link TBD)

---

Status: Phase 2 In Progress | Version: 0.2.0 | Last Updated: 2025-11-12