GraphMemory-IDE

An AI-assisted, long-term memory system for IDEs, powered by Kuzu graph database. GraphMemory-IDE is an MCP (Model Context Protocol) server that provides semantic vector search, graph-based knowledge storage, and real-time analytics. It integrates with VSCode, Cursor, and Windsurf through dedicated IDE plugins.

Features

• Graph-based memory storage — Kuzu native graph database with semantic vector search (HNSW indexes, sentence-transformers embeddings)
• Codon-accelerated graph algorithms — Optional native compilation via Codon for 10-100x speedups on centrality, community detection, path analysis, and similarity computations, with automatic Python/NetworkX fallback
• FastAPI backend — Async API with JWT authentication (EdDSA/Ed25519), rate limiting, and security middleware
• Real-time analytics — WebSocket and SSE streaming for live telemetry dashboards
• Streamlit dashboard — Interactive visualization of graph metrics, user activity, and system health
• Multi-IDE plugin support — Extensions for VSCode, Cursor, and Windsurf
• Full observability — Prometheus metrics, Grafana dashboards, health checks, and alert correlation
• Production-ready Docker deployment — Multi-service Docker Compose with Nginx, PostgreSQL, Redis, and monitoring stack

Quick Start

Docker (recommended)

git clone https://github.com/elementalcollision/GraphMemory-IDE.git
cd GraphMemory-IDE/docker
docker compose up -d

Services will be available at:

• MCP Server: http://localhost:8080/docs
• Kestra (workflow orchestration): http://localhost:8081

Local Development

# Install dependencies
pip install -r requirements.txt

# Start the FastAPI server
uvicorn server.main:app --host 0.0.0.0 --port 8080 --reload

# Start the Streamlit dashboard (separate terminal)
cd dashboard
streamlit run streamlit_app.py

Environment Variables

Variable	Default	Description
JWT_SECRET_KEY	(required)	Secret key for JWT token signing
DATABASE_URL	sqlite:///./graphmemory.db	PostgreSQL connection string
REDIS_URL	redis://localhost:6379	Redis connection for caching
KUZU_DB_PATH	./data/kuzu	Path to Kuzu graph database
CODON_ENABLED	true	Enable Codon acceleration
CODON_LIB_PATH	./codon/lib/	Path to compiled Codon libraries
CODON_MIN_GRAPH_SIZE	100	Minimum graph size for Codon routing

Architecture

GraphMemory-IDE uses a hybrid architecture where I/O-bound code (FastAPI, database clients, WebSocket) runs in CPython, while compute-heavy graph algorithms can optionally run as native-compiled Codon modules.

IDE Plugins (VSCode/Cursor/Windsurf)
        |
        v
  FastAPI Server (CPython)
   ├── JWT Auth + Security Middleware
   ├── MCP Protocol Handler
   ├── Telemetry Ingestion
   └── Analytics Engine
        |
   ┌────┴────┐
   v         v
Kuzu DB   Redis Cache
(graphs)  (sessions)
   |
   v
Codon Bridge (optional)
 ├── Graph Kernels (.so/.dylib)
 └── Python/NetworkX fallback

See Architecture Overview for detailed system design.

Codon Acceleration

The codon/ directory contains graph algorithm implementations compiled to native machine code via Codon. The bridge layer (codon/bridge/) automatically routes computations based on graph size and library availability:

• Graph kernels: betweenness/closeness/degree centrality, PageRank, label propagation, Louvain community detection, BFS/Dijkstra shortest paths
• Data processing: cosine similarity, batch vector operations, consistent hashing
• Fallback: If Codon libraries aren't compiled, all operations fall back to NetworkX/numpy transparently

Compile Codon modules with:

./scripts/build_codon.sh

Project Structure

GraphMemory-IDE/
├── server/                # FastAPI backend
│   ├── main.py            # Application entry point
│   ├── core/              # Configuration and settings
│   ├── auth/              # SSO, MFA, onboarding
│   ├── auth_jwt.py        # JWT authentication
│   ├── analytics/         # Analytics engine
│   ├── collaboration/     # Real-time collaboration
│   ├── dashboard/         # Dashboard API routes
│   ├── monitoring/        # Health checks, metrics, alerting
│   ├── security/          # Security middleware
│   ├── streaming/         # WebSocket/SSE streaming
│   └── graph_database.py  # Kuzu DB integration
├── dashboard/             # Streamlit UI
├── frontend/              # TypeScript/React frontend
├── codon/                 # Codon acceleration layer
│   ├── bridge/            # Python-Codon interop with fallback
│   ├── graph_kernels/     # Native graph algorithms (.codon)
│   └── data_processing/   # Native data operations (.codon)
├── docker/                # Docker Compose configs
│   ├── docker-compose.yml # Development environment
│   └── production/        # Production multi-service setup
├── tests/                 # Test suites
│   ├── integration/       # Integration tests
│   ├── production/        # Production validation
│   ├── load_testing/      # Locust load tests
│   └── smoke/             # Smoke tests
├── docs/                  # Documentation
├── ide-plugins/           # VSCode, Cursor, Windsurf extensions
├── monitoring/            # Prometheus & Grafana configs
├── scripts/               # Build and deployment scripts
└── kubernetes/            # Kubernetes manifests

Testing

# Run all tests
PYTHONPATH=. pytest tests/ -v

# Run with coverage
PYTHONPATH=. pytest tests/ --cov=server --cov-report=html

# Run specific test categories
PYTHONPATH=. pytest tests/ -m unit
PYTHONPATH=. pytest tests/ -m integration
PYTHONPATH=. pytest tests/ -m "not slow"

Test markers: unit, integration, e2e, api, database, authentication, analytics, performance, slow

Coverage target: 85% minimum.

Production Deployment

For production, use the multi-service Docker Compose configuration:

cd docker/production
cp .env.example .env  # Configure environment variables
docker compose -f docker-compose.prod.yml up -d

This starts 7+ services: Nginx (reverse proxy), FastAPI, Streamlit, Analytics, PostgreSQL, Redis, Prometheus, and Grafana — with isolated network subnets and resource limits.

See the Docker Deployment Guide for complete production setup instructions.

Documentation

Directory	Description
docs/project/	Project overview, PRD, contributing guidelines, security policy
docs/architecture/	System architecture, code paths, network flows
docs/api/	API reference and client examples
docs/deployment/	Docker, Kubernetes, and production deployment guides
docs/development/	Developer setup, code quality, testing procedures
docs/operations/	System operations and performance tuning
docs/monitoring/	Prometheus, Grafana, and alerting configuration
docs/analytics/	Analytics system and ML components
docs/ide-plugins/	Plugin development for VSCode, Cursor, Windsurf
docs/user-guides/	Tutorials and end-user documentation

Contributing

See Contributing Guidelines for development workflow, commit conventions, and code review process.

License

This project is licensed under the MIT License. See LICENSE for details.