graphiti-go-client/README.md

Graphiti Go Client

A Go client library for the Graphiti HTTP API.

Installation

go get github.com/pentagi/graphiti-go-client

Usage

Creating a Client

import (
    "time"
    graphiti "github.com/pentagi/graphiti-go-client"
)

// Create a client with default settings
client := graphiti.NewClient("http://localhost:8000")

// Create a client with custom timeout
client := graphiti.NewClient("http://localhost:8000",
    graphiti.WithTimeout(60 * time.Second))

// Create a client with a custom HTTP client
httpClient := &http.Client{
    Timeout: 30 * time.Second,
}
client := graphiti.NewClient("http://localhost:8000",
    graphiti.WithHTTPClient(httpClient))

Health Check

health, err := client.HealthCheck()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Status: %s\n", health.Status)

Search for Facts

result, err := client.Search(graphiti.SearchQuery{
    Query:    "Tell me about user preferences",
    MaxFacts: 10,
})
if err != nil {
    log.Fatal(err)
}

for _, fact := range result.Facts {
    fmt.Printf("Fact: %s\n", fact.Fact)
}

Search with Group Filtering

groupIDs := []string{"group-123", "group-456"}
result, err := client.Search(graphiti.SearchQuery{
    GroupIDs: &groupIDs,
    Query:    "user settings",
    MaxFacts: 5,
})

Add Messages

⚠️ Important: The /messages endpoint is asynchronous. Messages are queued and processed by a background worker. Data may not be immediately available after this call returns.

messages := []graphiti.Message{
    {
        Content:   "Hello, how are you?",
        Author:    "User",
        Timestamp: time.Now(),
    },
    {
        Content:   "I'm doing great, thank you!",
        Author:    "Assistant",
        Timestamp: time.Now(),
    },
}

result, err := client.AddMessages(graphiti.AddMessagesRequest{
    GroupID:  "my-group-id",
    Messages: messages,
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s: %v\n", result.Message, result.Success)

// Wait for processing by polling for episodes
maxAttempts := 10
for attempt := 1; attempt <= maxAttempts; attempt++ {
    episodes, err := client.GetEpisodes("my-group-id", 10)
    if err == nil && len(episodes) > 0 {
        fmt.Println("Messages processed successfully!")
        break
    }
    time.Sleep(5 * time.Second)
}

Add an Entity Node

uuid := "entity-uuid-123"
node, err := client.AddEntityNode(graphiti.AddEntityNodeRequest{
    UUID:    uuid,
    GroupID: "my-group-id",
    Name:    "User Preferences",
    Summary: "Contains user's preferred settings",
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Created node: %s\n", node.UUID)

Get Memory from Messages

messages := []graphiti.Message{
    {
        Content:   "What were my settings?",
        Author:    "User",
        Timestamp: time.Now(),
    },
}

response, err := client.GetMemory(graphiti.GetMemoryRequest{
    GroupID:  "my-group-id",
    MaxFacts: 10,
    Messages: messages,
})
if err != nil {
    log.Fatal(err)
}

for _, fact := range response.Facts {
    fmt.Printf("Fact: %s (from %s)\n", fact.Fact, fact.Name)
}

Get Episodes

episodes, err := client.GetEpisodes("my-group-id", 5)
if err != nil {
    log.Fatal(err)
}

for _, episode := range episodes {
    fmt.Printf("Episode: %s - %s\n", episode.Name, episode.Content)
}

Get a Specific Entity Edge

fact, err := client.GetEntityEdge("edge-uuid-123")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Fact: %s\n", fact.Fact)

Delete Operations

// Delete an entity edge
result, err := client.DeleteEntityEdge("edge-uuid-123")

// Delete an episode
result, err := client.DeleteEpisode("episode-uuid-123")

// Delete a group
result, err := client.DeleteGroup("group-id-123")

// Clear all data (use with caution!)
result, err := client.Clear()

Types

Message

type Message struct {
    Content           string    // The message content
    UUID              *string   // Optional UUID
    Name              string    // Optional name for episodic node
    Author            string    // The author/entity that created this message
    Timestamp         time.Time // Message timestamp
    SourceDescription string    // Optional source description
}

SearchQuery

type SearchQuery struct {
    GroupIDs *[]string // Optional group IDs to filter
    Query    string    // Search query text
    MaxFacts int       // Maximum number of facts to return (default: 10)
}

FactResult

type FactResult struct {
    UUID      string     // Unique identifier
    Name      string     // Fact name
    Fact      string     // The actual fact text
    ValidAt   *time.Time // When fact became valid
    InvalidAt *time.Time // When fact became invalid
    CreatedAt time.Time  // Creation timestamp
    ExpiredAt *time.Time // Expiration timestamp
}

Error Handling

All client methods return an error as the last return value. Always check for errors:

result, err := client.Search(query)
if err != nil {
    // Handle error
    log.Printf("Search failed: %v", err)
    return
}
// Use result

Example

See the example for a complete working demonstration of the client, including proper handling of asynchronous operations and data verification.