Eve library

Graph Database Schema

Guide

Revision 1

On this page

This document describes the Neo4j knowledge graph schema for the Lilith platform.

Overview#

Lilith consumes Sophia's graph layer for representing knowledge relationships across spiritual traditions, texts, practices, figures, and concepts. The canonical implementation now lives under apps/sophia/knowledge-graph/.

Node Types#

The knowledge graph contains 9 node types:

Node Type Description Key Properties
Tradition Spiritual/philosophical traditions origin_region, time_period, key_principles
Text Sacred and philosophical texts title, author, language, year, genre
Concept Abstract ideas and teachings definition, category, complexity_level
Practice Spiritual exercises and rituals difficulty, prerequisites, duration
Figure Historical/religious figures birth_year, death_year, bio_summary
Place Sacred sites and locations country, region, coordinates, significance
School Philosophical/spiritual schools (extends BaseNodeProperties)
Doctrine Formal teachings and beliefs (extends BaseNodeProperties)
Event Historical events (extends BaseNodeProperties)

Base Node Properties#

All nodes share these properties:

typescript
interface BaseNodeProperties {
  id: string; // Unique identifier
  name: string; // Human-readable name
  description?: string; // Description or summary
  created_at?: number; // Creation timestamp
  updated_at?: number; // Last update timestamp
  created_by?: string; // User who created the node
}

Tradition Node#

typescript
interface TraditionProperties extends BaseNodeProperties {
  origin_region?: string; // Geographic origin
  time_period?: string; // Historical period
  key_principles?: string[]; // Core teachings
  founding_figures?: string[]; // Founders
  category?: string; // Classification
}

Text Node#

typescript
interface TextProperties extends BaseNodeProperties {
  title: string; // Title of the text
  author?: string; // Author name
  language?: string; // Original language
  tradition?: string; // Associated tradition
  year?: number; // Year written/compiled
  source_url?: string; // Digital source
  content_hash?: string; // Hash for deduplication
  genre?: string; // Literary genre
}

Concept Node#

typescript
interface ConceptProperties extends BaseNodeProperties {
  definition?: string; // Meaning/definition
  tradition?: string; // Primary tradition
  category?: string; // Concept category
  complexity_level?: 'basic' | 'intermediate' | 'advanced';
  related_terms?: string[]; // Alternative terms
}

Practice Node#

typescript
interface PracticeProperties extends BaseNodeProperties {
  tradition?: string; // Associated tradition
  difficulty?: 'beginner' | 'intermediate' | 'advanced' | 'master';
  prerequisites?: string[]; // Required prior practices
  duration?: string; // Typical session length
  frequency?: string; // Recommended frequency
}

Figure Node#

typescript
interface FigureProperties extends BaseNodeProperties {
  birth_year?: number; // Year of birth
  death_year?: number; // Year of death
  traditions?: string[]; // Associated traditions
  bio_summary?: string; // Biographical summary
  titles?: string[]; // Titles/honorifics
  location?: string; // Primary location
}

Place Node#

typescript
interface PlaceProperties extends BaseNodeProperties {
  country?: string; // Country
  region?: string; // Region/state
  coordinates?: {
    latitude: number;
    longitude: number;
  };
  significance?: string; // Why it's sacred/important
  traditions?: string[]; // Associated traditions
}

Relationship Types#

The schema defines 26 relationship types organized by domain:

Figure Relationships#

Relationship Description Example
TAUGHT Teacher-student relationship Buddha TAUGHT Ananda
WROTE Authorship Patanjali WROTE Yoga Sutras
LIVED_IN Residence Rumi LIVED_IN Konya
STUDIED_UNDER Apprenticeship Disciple STUDIED_UNDER Master
FOUNDED Establishment Bodhidharma FOUNDED Zen

Concept Relationships#

Relationship Description Example
ALIGNS_WITH Conceptual agreement Dharma ALIGNS_WITH Tao
CONTRADICTS Conceptual opposition Nihilism CONTRADICTS Meaning
DERIVES_FROM Origin/derivation Tantra DERIVES_FROM Vedas
REFINES Refinement/clarification Madhyamaka REFINES Emptiness
EXTENDS Extension/expansion Mahayana EXTENDS Buddhism

Practice Relationships#

Relationship Description Example
BELONGS_TO Tradition membership Zazen BELONGS_TO Zen
REQUIRES Prerequisites Advanced meditation REQUIRES Basic meditation
PRECEDES Ordering Concentration PRECEDES Insight
FOLLOWS Sequence Jhana FOLLOWS Samatha

Text Relationships#

Relationship Description Example
DISCUSSES Topic coverage Bhagavad Gita DISCUSSES Karma
REFERENCES Citation Commentary REFERENCES Sutra
CITES Direct citation Scholar CITES Text
ORIGINATES_FROM Source tradition Tao Te Ching ORIGINATES_FROM Taoism
TRANSLATED_FROM Translation source English version TRANSLATED_FROM Sanskrit

Place Relationships#

Relationship Description Example
ASSOCIATED_WITH General association Temple ASSOCIATED_WITH Figure
SACRED_TO Sacred significance Bodh Gaya SACRED_TO Buddhism
LOCATED_IN Geographic containment Monastery LOCATED_IN Mountain

Cross-Domain Relationships#

Relationship Description Example
EXEMPLIFIES Example of concept Story EXEMPLIFIES Wisdom
INFLUENCED_BY Influence Sufism INFLUENCED_BY Neoplatonism
RELATED_TO General relation Concept A RELATED_TO Concept B

Relationship Properties#

All relationships can have these properties:

typescript
interface BaseRelationshipProperties {
  created_at?: number; // Creation timestamp
  updated_at?: number; // Last update timestamp
  weight?: number; // Confidence/strength score (0-1)
  context?: string; // Additional context or notes
}

GraphStore Interface#

The GraphStore interface provides operations for:

Connection Management#

typescript
await graphStore.connect();
await graphStore.disconnect();
const connected = graphStore.isConnected();
const health = await graphStore.healthCheck();

Node Operations#

typescript
// Create
const node = await graphStore.createNode<TraditionProperties>('Tradition', {
  name: 'Buddhism',
  origin_region: 'India',
  time_period: '6th century BCE',
});

// Read
const node = await graphStore.getNode('node-id');
const nodes = await graphStore.getNodes(['id1', 'id2']);
const buddhism = await graphStore.queryNodes({
  type: 'Tradition',
  properties: { name: 'Buddhism' },
});

// Update
await graphStore.updateNode('node-id', { description: 'Updated' });

// Delete
await graphStore.deleteNode('node-id', { cascade: true });

Relationship Operations#

typescript
// Create relationship
const rel = await graphStore.createRelationship(
  'WROTE',
  'patanjali-id',
  'yoga-sutras-id',
  { weight: 1.0, context: 'Traditional attribution' }
);

// Query relationships
const relationships = await graphStore.getNodeRelationships('node-id', {
  direction: 'outgoing',
  types: ['TAUGHT', 'WROTE'],
});

// Check connection
const connected = await graphStore.areNodesConnected(
  'buddha-id',
  'ananda-id',
  'TAUGHT'
);

Graph Traversal#

typescript
// Get neighbors
const students = await graphStore.getNeighbors('teacher-id', {
  direction: 'outgoing',
  types: ['TAUGHT'],
  depth: 1,
});

// Find shortest path
const path = await graphStore.findShortestPath('concept-a-id', 'concept-b-id', {
  maxDepth: 5,
});

// Find all paths
const paths = await graphStore.findAllPaths(
  'tradition-a-id',
  'tradition-b-id',
  { maxPaths: 10 }
);

// General traversal
const subgraph = await graphStore.traverse({
  startNodeId: 'buddhism-id',
  direction: 'both',
  maxDepth: 3,
  nodeTypes: ['Concept', 'Practice', 'Figure'],
});

Cypher Queries#

typescript
// Execute raw Cypher
const result = await graphStore.executeCypher({
  query: `
    MATCH (t:Tradition)-[:FOUNDED]->(f:Figure)
    WHERE t.name = $tradition
    RETURN f.name as founder
  `,
  parameters: { tradition: 'Buddhism' },
});

// Pattern matching
const matches = await graphStore.match(
  '(c:Concept)-[:DERIVES_FROM]->(t:Tradition)',
  { limit: 100 }
);

Batch Operations#

typescript
// Batch create nodes
const nodes = await graphStore.batchCreateNodes([
  { type: 'Concept', properties: { name: 'Karma' } },
  { type: 'Concept', properties: { name: 'Dharma' } },
]);

// Batch create relationships
const rels = await graphStore.batchCreateRelationships([
  { type: 'ALIGNS_WITH', fromNodeId: 'karma-id', toNodeId: 'dharma-id' },
]);

Statistics#

typescript
const stats = await graphStore.getStatistics();
// {
//   totalNodes: 10000,
//   totalRelationships: 50000,
//   nodesByType: { Tradition: 50, Concept: 5000, ... },
//   relationshipsByType: { TAUGHT: 1000, WROTE: 500, ... }
// }

Configuration#

typescript
interface GraphStoreConfig {
  type: 'neo4j' | 'memory';
  uri?: string; // neo4j://localhost:7687
  username?: string; // neo4j
  password?: string; // password
  database?: string; // neo4j (default)
  poolSize?: number; // Connection pool size
  encrypted?: boolean; // Enable TLS
  queryTimeout?: number; // Query timeout in ms
}

Environment Variables#

bash
NEO4J_URI=neo4j://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password
NEO4J_DATABASE=lilith
NEO4J_POOL_SIZE=50
NEO4J_ENCRYPTED=false
NEO4J_QUERY_TIMEOUT=30000

Index Strategy#

Recommended indexes for optimal query performance:

cypher
// Node property indexes
CREATE INDEX tradition_name FOR (t:Tradition) ON (t.name);
CREATE INDEX text_title FOR (t:Text) ON (t.title);
CREATE INDEX concept_name FOR (c:Concept) ON (c.name);
CREATE INDEX practice_name FOR (p:Practice) ON (p.name);
CREATE INDEX figure_name FOR (f:Figure) ON (f.name);
CREATE INDEX place_name FOR (p:Place) ON (p.name);

// Full-text search indexes
CREATE FULLTEXT INDEX search_nodes FOR (n:Tradition|Text|Concept|Practice|Figure|Place)
ON EACH [n.name, n.description];

// Constraint for unique IDs
CREATE CONSTRAINT unique_node_id FOR (n:Tradition|Text|Concept|Practice|Figure|Place)
REQUIRE n.id IS UNIQUE;

Common Query Patterns#

Find All Concepts in a Tradition#

cypher
MATCH (t:Tradition {name: $tradition})<-[:BELONGS_TO|DERIVES_FROM]-(c:Concept)
RETURN c

Find Teaching Lineage#

cypher
MATCH path = (teacher:Figure)-[:TAUGHT*1..5]->(student:Figure)
WHERE teacher.name = $teacherName
RETURN path

Cross-Tradition Concept Alignment#

cypher
MATCH (c1:Concept)-[:ALIGNS_WITH]-(c2:Concept)
MATCH (c1)-[:BELONGS_TO]->(t1:Tradition)
MATCH (c2)-[:BELONGS_TO]->(t2:Tradition)
WHERE t1 <> t2
RETURN c1, c2, t1, t2

Texts Discussing a Concept#

cypher
MATCH (t:Text)-[:DISCUSSES]->(c:Concept {name: $conceptName})
RETURN t ORDER BY t.year