GitHub - aexy-io/graphzep: GraphZep: A temporal knowledge graph memory system for AI agents in Typescript based on the Zep paper

import { 
  ZepMemoryManager,
  ZepSessionManager, 
  ZepRetrievalSystem,
  Neo4jDriver,
  OpenAIClient,
  OpenAIEmbedderClient,
  MemoryType
} from 'graphzep';

// Initialize core components
const driver = new Neo4jDriver({
  uri: 'bolt://localhost:7687',
  user: 'neo4j',
  password: 'password'
});

const llmClient = new OpenAIClient({
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o-mini',
});

const embedder = new OpenAIEmbedderClient({
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'text-embedding-3-small',
});

// Create Graphzep instance for underlying graph operations
const graphzep = new Graphzep({
  driver,
  llmClient,  
  embedder,
  groupId: 'my-project',
});

// Initialize Zep memory system
const memoryManager = new ZepMemoryManager(graphzep, llmClient, embedder, driver);
const sessionManager = new ZepSessionManager(memoryManager, driver);
const retrieval = new ZepRetrievalSystem(driver, embedder);

// Create a user session
const session = await sessionManager.createSession({
  userId: 'user-123',
  metadata: { source: 'chat-app' }
});

// Add episodic memory
const memory = await memoryManager.addMemory({
  content: 'Alice met Bob at the AI conference and discussed neural networks.',
  sessionId: session.sessionId,
  userId: 'user-123',
  memoryType: MemoryType.EPISODIC,
});

// Search memories using semantic search
const results = await retrieval.semanticSearch({
  query: 'Who did Alice meet?',
  sessionId: session.sessionId,
  limit: 5
});

console.log('Found memories:', results);

// Add memory to session
await sessionManager.addMemory(session.sessionId, memory.uuid);

// Get all session memories
const sessionMemories = await memoryManager.getSessionMemories(session.sessionId);
console.log('Session memories:', sessionMemories.length);

import { 
  Graphzep,
  OptimizedRDFDriver, 
  OpenAIClient, 
  OpenAIEmbedder,
  MemoryType 
} from 'graphzep';

// Initialize RDF driver with in-memory triple store
const rdfDriver = new OptimizedRDFDriver({
  inMemory: true,
  cacheSize: 10000,
  batchSize: 1000,
  customOntologyPath: './my-ontology.rdf' // optional
});

await rdfDriver.connect();

const llmClient = new OpenAIClient({
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o-mini',
});

const embedder = new OpenAIEmbedder({
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'text-embedding-3-small',
});

// Create GraphZep with RDF support
const graphzep = new Graphzep({
  driver: rdfDriver,
  llmClient,
  embedder,
});

// Add episodes that get converted to RDF triples
await graphzep.addEpisode({
  content: 'Alice works at ACME Corp and specializes in machine learning.',
});

// Execute SPARQL queries directly
const sparqlResults = await graphzep.sparqlQuery(`
  PREFIX zep: <http://graphzep.ai/ontology#>
  PREFIX zepent: <http://graphzep.ai/entity#>
  
  SELECT ?person ?organization ?expertise
  WHERE {
    ?person a zep:Person ;
            zep:worksAt ?organization ;
            zep:hasExpertise ?expertise .
  }
`);

console.log('SPARQL Results:', sparqlResults);

// Add semantic facts with confidence scores
await graphzep.addFact({
  subject: 'zepent:alice',
  predicate: 'zep:hasSkill',
  object: 'zepent:deep-learning',
  confidence: 0.95,
  sourceMemoryIds: [],
  validFrom: new Date()
});

// Search memories using Zep parameters
const memories = await graphzep.searchMemories({
  query: 'machine learning experts',
  limit: 10,
  searchType: 'semantic'
});

// Export knowledge graph to RDF formats
const turtle = await graphzep.exportToRDF('turtle');
const jsonLd = await graphzep.exportToRDF('json-ld');
const rdfXml = await graphzep.exportToRDF('rdf-xml');

console.log('Knowledge Graph in Turtle format:', turtle);

// Get temporal memories
const currentMemories = await graphzep.getMemoriesAtTime(
  new Date(), 
  [MemoryType.EPISODIC, MemoryType.SEMANTIC]
);

// Clean up
await graphzep.close();

import { 
  Graphzep, 
  Neo4jDriver, 
  OpenAIClient, 
  OpenAIEmbedderClient, 
  EpisodeType 
} from 'graphzep';

// Initialize components
const driver = new Neo4jDriver({
  uri: 'bolt://localhost:7687',
  user: 'neo4j',
  password: 'password'
});

const llmClient = new OpenAIClient({
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o-mini',
});

const embedder = new OpenAIEmbedderClient({
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'text-embedding-3-small',
});

// Create Graphzep instance
const graphzep = new Graphzep({
  driver,
  llmClient,
  embedder,
  groupId: 'my-project',
});

// Add an episode and extract knowledge
await graphzep.addEpisode({
  content: 'Alice met Bob at the conference and discussed their AI research.',
  episodeType: EpisodeType.TEXT,
  groupId: 'research-team'
});

// Search for information
const results = await graphzep.search({
  query: 'Who did Alice meet?',
  limit: 5,
});

console.log('Found relationships:', results);

// Clean up
await graphzep.close();

graphzep/
├── src/                          # Core TypeScript library
│   ├── zep/                      # Zep memory system implementation
│   │   ├── memory.ts             # Memory management
│   │   ├── session.ts            # Session management
│   │   ├── retrieval.ts          # Search and retrieval
│   │   └── types.ts              # Zep type definitions
│   ├── rdf/                      # RDF support implementation
│   │   ├── memory-mapper.ts      # Zep to RDF triple conversion
│   │   ├── sparql-interface.ts   # SPARQL query execution
│   │   ├── ontology-manager.ts   # Ontology loading and validation
│   │   ├── namespaces.ts         # RDF namespace management
│   │   └── ontologies/           # Default RDF ontologies
│   ├── core/                     # Graph nodes and edges
│   ├── drivers/                  # Database drivers (Neo4j, FalkorDB, RDF)
│   ├── llm/                      # LLM clients (OpenAI, Anthropic)
│   ├── embedders/                # Embedding clients
│   ├── types/                    # TypeScript type definitions
│   └── utils/                    # Utility functions
├── server/                       # HTTP server (Hono)
│   └── src/
│       ├── config/              # Server configuration
│       ├── dto/                 # Data transfer objects
│       └── standalone-main.ts   # Main server entry point
├── mcp_server/                  # MCP server for AI assistants
│   └── src/
│       └── graphzep-mcp-server.ts
├── examples/                 # TypeScript examples
│   ├── quickstart/              # Basic usage examples
│   ├── ecommerce/               # Product search demo
│   ├── podcast/                 # Conversation analysis
│   ├── langgraph-agent/         # AI agent with memory
│   └── zep-poc/                 # Zep memory system demo
├── Dockerfile                # Production Docker image
├── docker-compose.yml        # Full stack deployment
└── docker-compose.test.yml   # Testing environment

# Install dependencies
npm install

# Build the project
npm run build

# Core Library
npm run dev           # Development mode with watch
npm test             # Run all tests (91 tests)
npm run test:coverage # Test coverage report
npm run lint         # ESLint + TypeScript checking
npm run format       # Prettier code formatting
npm run check        # Run all checks (format, lint, test)

# HTTP Server
cd server
npm run dev          # Start server in development mode
npm run build        # Build production server
npm start           # Start production server

# MCP Server
cd mcp_server
npm run dev          # Start MCP server in development mode
npm run build        # Build MCP server
npm start           # Start MCP server

# Examples
cd examples
npm run quickstart:neo4j    # Basic Neo4j example
npm run ecommerce          # Product search demo
npm run podcast           # Conversation analysis
npm run langgraph-agent   # AI sales agent

# Required for LLM inference and embeddings
OPENAI_API_KEY=your-openai-key

# Optional LLM provider keys
ANTHROPIC_API_KEY=your-anthropic-key
GOOGLE_API_KEY=your-google-key
GROQ_API_KEY=your-groq-key

# Database connection
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password

# Or FalkorDB
FALKORDB_URI=falkor://localhost:6379

# Server configuration
PORT=3000

# Copy environment template
cp .env.docker.example .env
# Edit .env with your configuration

# Start full stack (server + MCP + database)
docker-compose -f docker-compose.yml up --build

// Neo4j
const driver = new Neo4jDriver({
  uri: 'bolt://localhost:7687',
  user: 'neo4j',
  password: 'password',
  database: 'my-database' // optional
});

// FalkorDB  
const driver = new FalkorDriver({
  uri: 'redis://localhost:6379',
  database: 'my-graph' // optional
});

// RDF Triple Store
const driver = new OptimizedRDFDriver({
  inMemory: true,                           // In-memory or external SPARQL endpoint
  sparqlEndpoint: 'http://localhost:3030', // Optional external endpoint
  cacheSize: 10000,                        // LRU cache size
  batchSize: 1000,                         // Batch processing size
  customOntologyPath: './ontology.rdf'     // Custom ontology file
});

// SPARQL queries with Zep extensions
const results = await graphzep.sparqlQuery(`
  PREFIX zep: <http://graphzep.ai/ontology#>
  PREFIX zeptime: <http://graphzep.ai/temporal#>
  
  SELECT ?memory ?content ?confidence
  WHERE {
    ?memory a zep:EpisodicMemory ;
            zep:content ?content ;
            zeptime:validFrom ?validFrom ;
            zep:confidence ?confidence .
    FILTER (?validFrom > "${yesterday.toISOString()}"^^xsd:dateTime)
    FILTER (?confidence > 0.8)
  }
  ORDER BY DESC(?confidence)
`);

// Add semantic facts with temporal validity
await graphzep.addFact({
  subject: 'zepent:alice',
  predicate: 'zep:worksAt', 
  object: 'zepent:acme-corp',
  confidence: 0.95,
  validFrom: new Date(),
  validUntil: new Date('2025-12-31')
});

// Export to different RDF formats
const turtle = await graphzep.exportToRDF('turtle');
const jsonLd = await graphzep.exportToRDF('json-ld'); 
const rdfXml = await graphzep.exportToRDF('rdf-xml');

// Namespace management
const nsManager = new NamespaceManager();
nsManager.addNamespace('myorg', 'https://mycompany.com/ontology#');
const expanded = nsManager.expand('myorg:Employee'); // -> https://mycompany.com/ontology#Employee

// OpenAI
const llm = new OpenAIClient({
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o-mini',
  temperature: 0.7,
});

// Anthropic
const llm = new AnthropicClient({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: 'claude-3-opus-20240229',
  temperature: 0.7,
});

# Add messages
curl -X POST http://localhost:3000/messages \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "demo",
    "messages": [{
      "content": "Hello world",
      "role_type": "user"
    }]
  }'

# Search
curl -X POST http://localhost:3000/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Hello",
    "max_facts": 10
  }'

cd examples

# Install dependencies
npm install

# Run examples  
npm run zep-poc              # Zep memory system demo
npm run quickstart:neo4j     # Basic Neo4j operations (2-5 minutes)
npm run quickstart:rdf       # RDF triple store demo (2-5 minutes)
npm run ecommerce           # E-commerce search (5-10 minutes)
npm run podcast            # Conversation analysis (10-15 minutes)  
npm run langgraph-agent    # AI agent with memory (15-20 minutes)

# Core library tests (all 130+ tests)
npm test

# Run specific test suites
npm test -- --grep="RDF"          # RDF and SPARQL tests
npm test -- --grep="Zep"          # Zep memory system tests
npm test -- --grep="Neo4j"        # Neo4j integration tests

# Integration tests (requires database)
npm run test:integration

# Test with coverage
npm run test:coverage

# Docker-based testing
docker-compose -f docker-compose.test.yml up --build

export enum EpisodeType {
  MESSAGE = 'message',
  JSON = 'json', 
  TEXT = 'text',
}

export interface GraphzepConfig {
  driver: GraphDriver;
  llmClient: BaseLLMClient;
  embedder: BaseEmbedderClient;
  groupId?: string;
  ensureAscii?: boolean;
}

export interface AddEpisodeParams {
  content: string;
  episodeType?: EpisodeType;
  referenceId?: string;
  groupId?: string;
  metadata?: Record<string, any>;
}

export interface SearchParams {
  query: string;
  groupId?: string;
  limit?: number;
  searchType?: 'semantic' | 'keyword' | 'hybrid';
  nodeTypes?: ('entity' | 'episodic' | 'community')[];
}

class Graphzep {
  // Add episode and extract entities/relations
  addEpisode(params: AddEpisodeParams): Promise<EpisodicNode>

  // Search knowledge graph  
  search(params: SearchParams): Promise<Node[]>

  // Node operations
  getNode(uuid: string): Promise<Node | null>
  deleteNode(uuid: string): Promise<void>

  // Edge operations
  getEdge(uuid: string): Promise<Edge | null>
  deleteEdge(uuid: string): Promise<void>

  // RDF and SPARQL operations (when using RDF driver)
  sparqlQuery(query: string, options?: any): Promise<SPARQLResult>
  addFact(fact: Omit<ZepFact, 'uuid'>): Promise<string>
  searchMemories(params: ZepSearchParams): Promise<ZepSearchResult[]>
  getMemoriesAtTime(timestamp: Date, types?: MemoryType[]): Promise<ZepMemory[]>
  getFactsAboutEntity(entityName: string, validAt?: Date): Promise<ZepFact[]>
  findRelatedEntities(entityName: string, maxHops?: number): Promise<any[]>
  exportToRDF(format?: 'turtle' | 'rdf-xml' | 'json-ld'): Promise<string>
  getSPARQLTemplates(): Record<string, string>
  isRDFSupported(): boolean

  // Cleanup
  close(): Promise<void>
}

# Clone and configure
git clone https://github.com/aexy-io/graphzep.git
cd graphzep
cp .env.docker.example .env
# Edit .env with your settings

# Deploy with Docker
docker-compose -f docker-compose.yml up -d

# Verify deployment
curl http://localhost:3000/healthcheck