Go Quick Start — Pensyve Docs

The Go SDK is a thin HTTP client. Standard library only — no external dependencies.

Install

go get github.com/major7apps/pensyve-go

Requires a running Pensyve REST API server. See the REST API Quick Start to set one up.

Initialize

package main

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

    pensyve "github.com/major7apps/pensyve-go"
)

func main() {
    client := pensyve.NewClient(pensyve.Config{
        BaseURL: "http://localhost:8000",
        Timeout: 10 * time.Second,
    })

    ctx := context.Background()

    // check the server is up
    health, err := client.Health(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(health.Status) // "ok"
}

Timeout defaults to 30 seconds if zero.

Remember

mem, err := client.Remember(ctx, "alice", "Prefers Go over Python", 0.9)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s: %s (confidence=%.1f)\n", mem.MemoryType, mem.Content, mem.Confidence)
// semantic: Prefers Go over Python (confidence=0.9)

Recall

memories, err := client.Recall(ctx, "language preferences", &pensyve.RecallOptions{
    Entity: "alice",
    Limit:  5,
    Types:  []string{"semantic"},
})
if err != nil {
    log.Fatal(err)
}

for _, m := range memories {
    fmt.Printf("[%s] %s (score=%.2f)\n", m.MemoryType, m.Content, m.Score)
}

Pass nil for default options (limit 5, no filters).

Episodes

Track multi-turn interactions with StartEpisode:

ep, err := client.StartEpisode(ctx, []string{"alice", "assistant"})
if err != nil {
    log.Fatal(err)
}

ep.AddMessage(ctx, "user", "I always use dark mode")
ep.AddMessage(ctx, "assistant", "Noted for future sessions")

ep.SetOutcome("success")

memoriesCreated, err := ep.End(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Memories created: %d\n", memoriesCreated)

SetOutcome is optional. Valid values: "success", "failure", "partial".

Entities

Create or retrieve entities explicitly:

entity, err := client.Entity(ctx, "alice", "user")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Entity %s (id=%s, kind=%s)\n", entity.Name, entity.ID, entity.Kind)

Forget

// Soft delete
count, err := client.Forget(ctx, "alice", false)

// Hard delete
count, err := client.Forget(ctx, "alice", true)

fmt.Printf("Forgotten: %d\n", count)

Consolidation

result, err := client.Consolidate(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("promoted=%d decayed=%d archived=%d\n",
    result.Promoted, result.Decayed, result.Archived)

Types

type Entity struct {
    ID   string `json:"id"`
    Name string `json:"name"`
    Kind string `json:"kind"`   // "agent", "user", "team", "tool"
}

type Memory struct {
    ID         string  `json:"id"`
    Content    string  `json:"content"`
    MemoryType string  `json:"memory_type"` // "episodic", "semantic", "procedural"
    Confidence float64 `json:"confidence"`
    Stability  float64 `json:"stability"`
    Score      float64 `json:"score,omitempty"`
}

type RecallOptions struct {
    Entity string
    Limit  int
    Types  []string
}

type ConsolidateResult struct {
    Promoted int `json:"promoted"`
    Decayed  int `json:"decayed"`
    Archived int `json:"archived"`
}

Error Handling

API errors return *pensyve.PensyveError with the HTTP status code and detail message:

_, err := client.Entity(ctx, "nobody", "user")
if err != nil {
    var pe *pensyve.PensyveError
    if errors.As(err, &pe) {
        fmt.Printf("API error: HTTP %d — %s\n", pe.Status, pe.Detail)
    } else {
        fmt.Printf("Network error: %v\n", err)
    }
}

Authentication

If the server has PENSYVE_API_KEYS set, pass your key in the config:

client := pensyve.NewClient(pensyve.Config{
    BaseURL: "http://localhost:8000",
    APIKey:  "your-api-key",
})

The SDK sends it as the X-Pensyve-Key header on every request. When no key is set, the header is omitted.

On this page