Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vectorize-io/hindsight/llms.txt

Use this file to discover all available pages before exploring further.

The Hindsight Go client is generated from the OpenAPI 3.1 specification and provides typed access to all Hindsight API operations. It follows standard Go conventions — context-based cancellation, idiomatic error handling, and nullable wrapper types for optional fields.

​
Installation

go get github.com/vectorize-io/hindsight/hindsight-clients/go
Requires Go 1.23+.

​
Create the client

import hindsight "github.com/vectorize-io/hindsight/hindsight-clients/go"

// No timeout (uses http.DefaultClient)
client := hindsight.NewAPIClientWithToken("http://localhost:8888", "your-api-key")

​
API structure

The client organises operations into typed API sub-clients:
PropertyOperations
client.MemoryAPIRetain, recall, reflect
client.BanksAPIBank create, update, list, delete
client.MentalModelsAPIMental model management
client.DirectivesAPIDirective management
client.DocumentsAPIDocument CRUD
client.EntitiesAPIEntity browsing
client.OperationsAPIAsync operation monitoring

​
Retain memories

package main

import (
    "context"
    "fmt"
    "log"

    hindsight "github.com/vectorize-io/hindsight/hindsight-clients/go"
)

func main() {
    client := hindsight.NewAPIClientWithToken("http://localhost:8888", "your-api-key")
    ctx := context.Background()
    bankID := "my-bank"

    // Single memory
    req := hindsight.RetainRequest{
        Items: []hindsight.MemoryItem{
            {Content: "Alice works at Google as a software engineer"},
        },
    }

    resp, httpResp, err := client.MemoryAPI.RetainMemories(ctx, bankID).
        RetainRequest(req).
        Execute()
    if err != nil {
        log.Fatal(err)
    }
    defer httpResp.Body.Close()

    fmt.Println("success:", resp.GetSuccess())
}

​
Batch retain

req := hindsight.RetainRequest{
    Items: []hindsight.MemoryItem{
        {Content: "Paris is the capital of France"},
        {Content: "The Eiffel Tower is in Paris"},
    },
}

resp, httpResp, err := client.MemoryAPI.RetainMemories(ctx, bankID).
    RetainRequest(req).
    Execute()

​
Retain with context and timestamp

import "time"

timestamp := time.Date(2024, 6, 1, 10, 0, 0, 0, time.UTC)

req := hindsight.RetainRequest{
    Items: []hindsight.MemoryItem{
        {
            Content:   "Bob went hiking in the mountains",
            Timestamp: *hindsight.NewNullableTimestamp(
                &hindsight.Timestamp{TimeTime: &timestamp},
            ),
            Context: *hindsight.NewNullableString(
                hindsight.PtrString("outdoor activities"),
            ),
            Tags: []string{"bob", "hobbies"},
        },
    },
}

​
Retain with tags

req := hindsight.RetainRequest{
    Items: []hindsight.MemoryItem{
        {
            Content: "New feature shipped for project Z",
            Tags:    []string{"project_z", "features"},
        },
    },
    DocumentTags: []string{"sprint-42"},
}

​
Recall memories

req := hindsight.RecallRequest{
    Query: "What does Alice do?",
}

resp, httpResp, err := client.MemoryAPI.RecallMemories(ctx, bankID).
    RecallRequest(req).
    Execute()
if err != nil {
    log.Fatal(err)
}
defer httpResp.Body.Close()

for _, r := range resp.Results {
    fmt.Printf("- %s  (type: %s)\n", r.GetText(), r.GetType())
}

​
Recall with options

req := hindsight.RecallRequest{
    Query:     "What are people's hobbies?",
    Types:     []string{"world", "observation"},
    MaxTokens: hindsight.PtrInt32(2048),
    Trace:     hindsight.PtrBool(true),
}

​
Reflect

req := hindsight.ReflectRequest{
    Query: "Tell me about Alice",
}

resp, httpResp, err := client.MemoryAPI.Reflect(ctx, bankID).
    ReflectRequest(req).
    Execute()
if err != nil {
    log.Fatal(err)
}
defer httpResp.Body.Close()

fmt.Println(resp.GetText())

​
Reflect with max tokens

req := hindsight.ReflectRequest{
    Query:     "Summarise what I know about Paris",
    MaxTokens: hindsight.PtrInt32(500),
}

​
Bank management

// Create or update a bank
createReq := hindsight.CreateBankRequest{
    Mission: *hindsight.NewNullableString(
        hindsight.PtrString("I am a helpful AI assistant."),
    ),
}

resp, httpResp, err := client.BanksAPI.CreateOrUpdateBank(ctx, bankID).
    CreateBankRequest(createReq).
    Execute()
if err != nil {
    log.Fatal(err)
}
defer httpResp.Body.Close()

fmt.Println("bank_id:", resp.GetBankId())

// List banks
listResp, httpResp2, err := client.BanksAPI.ListBanks(ctx).Execute()
if err != nil {
    log.Fatal(err)
}
defer httpResp2.Body.Close()

for _, b := range listResp.Banks {
    fmt.Println(b.GetBankId())
}

// Delete a bank
delResp, httpResp3, err := client.BanksAPI.DeleteBank(ctx, bankID).Execute()
if err != nil {
    log.Fatal(err)
}
defer httpResp3.Body.Close()

fmt.Println("deleted:", delResp.GetSuccess())

​
Working with nullable fields

The Go client uses NullableString, NullableTime, and similar wrapper types for fields that are optional in the API. Helper functions like PtrString, PtrBool, and PtrInt32 convert literals to pointers. 
// Setting a nullable string
context := hindsight.NewNullableString(hindsight.PtrString("my context"))
item := hindsight.MemoryItem{
    Content: "Some memory",
    Context: *context,
}

// Setting a nullable timestamp
ts := time.Now()
timestamp := hindsight.NewNullableTimestamp(&hindsight.Timestamp{TimeTime: &ts})
item.Timestamp = *timestamp

// Boolean and int32 pointers
req := hindsight.RecallRequest{
    Query:     "query",
    Trace:     hindsight.PtrBool(true),
    MaxTokens: hindsight.PtrInt32(1024),
}

​
Error handling

resp, httpResp, err := client.MemoryAPI.RetainMemories(ctx, bankID).
    RetainRequest(req).
    Execute()
if err != nil {
    // err is *hindsight.GenericOpenAPIError for API errors
    if apiErr, ok := err.(*hindsight.GenericOpenAPIError); ok {
        fmt.Println("API error body:", string(apiErr.Body()))
    }
    log.Fatal(err)
}
defer httpResp.Body.Close()

​
Complete workflow example

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    hindsight "github.com/vectorize-io/hindsight/hindsight-clients/go"
)

func main() {
    client := hindsight.NewAPIClientWithTimeout(
        "http://localhost:8888",
        "your-api-key",
        30*time.Second,
    )
    ctx := context.Background()
    bankID := "workflow-demo"

    // 1. Create bank with a mission
    bankReq := hindsight.CreateBankRequest{
        Mission: *hindsight.NewNullableString(
            hindsight.PtrString("I am a helpful assistant."),
        ),
    }
    _, httpR, err := client.BanksAPI.CreateOrUpdateBank(ctx, bankID).
        CreateBankRequest(bankReq).Execute()
    if err != nil { log.Fatal(err) }
    defer httpR.Body.Close()

    // 2. Retain memories
    retainReq := hindsight.RetainRequest{
        Items: []hindsight.MemoryItem{
            {Content: "Paris is the capital of France"},
            {Content: "The Eiffel Tower is in Paris"},
        },
    }
    _, httpR2, err := client.MemoryAPI.RetainMemories(ctx, bankID).
        RetainRequest(retainReq).Execute()
    if err != nil { log.Fatal(err) }
    defer httpR2.Body.Close()

    time.Sleep(time.Second)

    // 3. Recall
    recallReq := hindsight.RecallRequest{Query: "What is in Paris?"}
    recallResp, httpR3, err := client.MemoryAPI.RecallMemories(ctx, bankID).
        RecallRequest(recallReq).Execute()
    if err != nil { log.Fatal(err) }
    defer httpR3.Body.Close()

    fmt.Printf("Recall: %d results\n", len(recallResp.Results))
    for _, r := range recallResp.Results {
        fmt.Println(" •", r.GetText())
    }

    // 4. Reflect
    reflectReq := hindsight.ReflectRequest{Query: "Tell me about Paris"}
    reflectResp, httpR4, err := client.MemoryAPI.Reflect(ctx, bankID).
        ReflectRequest(reflectReq).Execute()
    if err != nil { log.Fatal(err) }
    defer httpR4.Body.Close()

    fmt.Println("Reflect:", reflectResp.GetText())
}

Build docs developers (and LLMs) love

Get started for freeTalk to us