Edgemaker

A TypeScript knowledge graph library inspired by Graphiti, designed for building temporally-aware AI memory systems.

🚀 Quick Start

Prerequisites

• Node.js 18+
• Supabase project with pgvector enabled
• OpenAI API key

Installation

npm install

Environment Setup

Create a .env.development file with your credentials:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
OPENAI_API_KEY=sk-your-openai-key
NODE_ENV=development

Database Setup

The database schema migration is located at:

supabase/migrations/20250101000001_edgemaker_initial_schema.sql

To apply the schema to your Supabase project, run this SQL in the Supabase Dashboard SQL Editor.

Basic Usage

import { Edgemaker, createEdgemakerConfig } from '@edgemaker/core';

// Create configuration
const config = createEdgemakerConfig({
  supabase: {
    url: process.env.SUPABASE_URL!,
    serviceKey: process.env.SUPABASE_SERVICE_ROLE_KEY!,
    anonKey: process.env.SUPABASE_ANON_KEY!,
  },
  llm: {
    openai: {
      apiKey: process.env.OPENAI_API_KEY!,
    },
  },
});

// Initialize Edgemaker
const edgemaker = new Edgemaker(config);

// Add an episode
const result = await edgemaker.addEpisode({
  content: "John bought coffee at Starbucks this morning",
  group_id: "project-1",
});

// Search the knowledge graph with different strategies
const searchResults = await edgemaker.search("coffee shops", {
  groupIds: ["project-1"],
  searchType: "story", // 'quick', 'story', 'character', 'factual', 'exploratory'
  limit: 10
});

// Advanced search with custom configuration
const advancedResults = await edgemaker.advancedSearch("character relationships", {
  searchConfig: {
    node_config: { method: 'cosine_similarity', limit: 15 },
    edge_config: { method: 'bm25', limit: 10 },
    reranking_strategy: 'node_distance'
  },
  filters: { groupIds: ["project-1"] }
});

🧪 Testing

# Run all tests
npm test

# Run only unit tests (fast, no external APIs)
npm run test:unit

# Run only integration tests (requires API keys)
npm run test:integration


# Run tests in watch mode
npm run test:watch
npm run test:watch:unit
npm run test:watch:integration

# Quick test (unit tests only)
npm run test:quick

# Build the project
npm run build

📁 Project Structure

src/
├── core/                 # Core Edgemaker class
├── infrastructure/       # External integrations
│   ├── supabase/        # Database client
│   └── llm/             # LLM clients
├── processors/          # Episode processing pipeline
├── search/              # Search and retrieval
├── prompts/             # LLM prompt templates
├── types/               # TypeScript definitions
└── utils/               # Utility functions

supabase/
├── migrations/          # Database schema
└── functions/           # Edge functions (optional)

🗃️ Database Schema

The system uses PostgreSQL with pgvector for:

• Episodes: Raw input episodes
• Entities: Extracted entities with embeddings
• Entity Edges: Relationships between entities
• Communities: Clustered entity groups

Key features:

• Temporal relationship tracking
• Vector similarity search
• Current/historical edge management
• Row-level security for multi-tenancy

🧠 Core Concepts

Episodes

Raw input data that gets processed into the knowledge graph.

Entities

Extracted people, places, objects, and concepts with:

• Name embeddings for semantic search
• Summaries and attributes
• Temporal context

Edges

Relationships between entities with:

• Fact embeddings
• Temporal validity periods
• Episode provenance

Search

Hybrid retrieval combining:

• Vector similarity (embeddings)
• Full-text search (PostgreSQL)
• Graph traversal

🚧 Current Status

Implemented:

• ✅ Project structure and TypeScript setup
• ✅ Database schema with pgvector support
• ✅ Supabase client configuration
• ✅ OpenAI LLM client integration
• ✅ Entity and edge extraction using LLM prompts
• ✅ Deduplication and conflict resolution
• ✅ Hybrid search implementation (vector + full-text + reranking)
• ✅ Core Edgemaker class with full pipeline
• ✅ Comprehensive test suite (unit + integration)
• ✅ Health checks and monitoring

TODO:

• Graph traversal search (BFS)
• Community detection algorithms
• Advanced documentation and examples
• Performance optimization

📚 Documentation

See the docs/ directory for detailed architecture and implementation guides:

• Project Setup Guide
• Graphiti Overview
• Database Layer
• LLM Integration
• Whetstone Integration
• Development Workflow - Complete guide for local development, testing changes in whetstone, and publishing new versions

🤝 Contributing

This is a work-in-progress project. Feel free to contribute by:

1. Implementing missing features
2. Adding tests
3. Improving documentation
4. Optimizing performance

📄 License

MIT