Go SDK

HTTP client for the Pensyve REST API. Standard library only -- no external dependencies.

go get github.com/major7apps/pensyve-go

All methods accept context.Context as their first parameter for cancellation and timeouts.

`Client`

`NewClient(cfg)`

Create a new API client.

Parameter	Type	Default	Description
`cfg`	`Config`	required	Client configuration

Returns: *Client

client := pensyve.NewClient(pensyve.Config{
    BaseURL: "http://localhost:8000",
})

client := pensyve.NewClient(pensyve.Config{
    BaseURL: "https://api.pensyve.com",
    APIKey:  "sk-...",
    Timeout: 10 * time.Second,
})

`Entity(ctx, name, kind)`

Create or retrieve an entity.

Parameter	Type	Default	Description
`ctx`	`context.Context`	required	Request context
`name`	`string`	required	Entity name
`kind`	`string`	required	One of `"agent"`, `"user"`, `"team"`, `"tool"`

Returns: (*Entity, error)

user, err := client.Entity(ctx, "alice", "user")
agent, err := client.Entity(ctx, "my-agent", "agent")

`Recall(ctx, query, opts)`

Search memories matching a query.

Parameter	Type	Default	Description
`ctx`	`context.Context`	required	Request context
`query`	`string`	required	Search query
`opts`	`*RecallOptions`	`nil`	Optional filters (pass `nil` for defaults)

Returns: ([]Memory, error)

memories, err := client.Recall(ctx, "project X deadline", nil)

memories, err := client.Recall(ctx, "deployment steps", &pensyve.RecallOptions{
    Entity: "my-agent",
    Limit:  10,
    Types:  []string{"procedural"},
})

`Remember(ctx, entity, fact, confidence)`

Store a semantic memory.

Parameter	Type	Default	Description
`ctx`	`context.Context`	required	Request context
`entity`	`string`	required	Entity name
`fact`	`string`	required	The fact to store
`confidence`	`float64`	required	Confidence in `[0, 1]`

Returns: (*Memory, error)

m, err := client.Remember(ctx, "alice", "Alice prefers dark mode", 0.9)

`Forget(ctx, entityName, hardDelete)`

Archive or delete all memories for an entity.

Parameter	Type	Default	Description
`ctx`	`context.Context`	required	Request context
`entityName`	`string`	required	Entity name
`hardDelete`	`bool`	required	`true` to permanently delete

Returns: (int, error) -- count of forgotten memories

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

`Consolidate(ctx)`

Trigger memory consolidation (promotion, decay, archival).

Parameter	Type	Default	Description
`ctx`	`context.Context`	required	Request context

Returns: (*ConsolidateResult, error)

result, err := client.Consolidate(ctx)
// result.Promoted, result.Decayed, result.Archived

`Health(ctx)`

Check API server health.

Parameter	Type	Default	Description
`ctx`	`context.Context`	required	Request context

Returns: (*HealthResult, error)

h, err := client.Health(ctx)
// h.Status == "ok"

`StartEpisode(ctx, participants)`

Begin an episode for recording messages. Returns a handle for adding messages and ending the episode.

Parameter	Type	Default	Description
`ctx`	`context.Context`	required	Request context
`participants`	`[]string`	required	Entity names participating

Returns: (*EpisodeHandle, error)

ep, err := client.StartEpisode(ctx, []string{"alice", "my-agent"})
if err != nil {
    log.Fatal(err)
}
err = ep.AddMessage(ctx, "user", "What's the status?")
err = ep.AddMessage(ctx, "assistant", "On track for Q2.")
ep.SetOutcome("success")
count, err := ep.End(ctx)
// count == 2

Types

`Config`

type Config struct {
    BaseURL string        // Required. Base URL of the REST API.
    APIKey  string        // Optional. Sent as X-Pensyve-Key header.
    Timeout time.Duration // Default: 30s.
}

`Entity`

type Entity struct {
    ID   string `json:"id"`
    Name string `json:"name"`
    Kind string `json:"kind"`
}

`Memory`

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

`RecallOptions`

type RecallOptions struct {
    Entity string   // Filter by entity name.
    Limit  int      // Max results (default: 5).
    Types  []string // Filter by memory type.
}

`ConsolidateResult`

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

`HealthResult`

type HealthResult struct {
    Status  string `json:"status"`
    Version string `json:"version"`
}

`EpisodeHandle`

Handle for an active episode. Not safe for concurrent use.

Method	Signature	Description
`AddMessage`	`(ctx context.Context, role, content string) error`	Send a message to the episode
`SetOutcome`	`(outcome string)`	Set outcome: `"success"`, `"failure"`, `"partial"`
`End`	`(ctx context.Context) (int, error)`	Close the episode, returns memories created

`PensyveError`

Returned when the API responds with a non-2xx status code.

Field	Type	Description
`Status`	`int`	HTTP status code
`Detail`	`string`	Error detail from API response

var perr *pensyve.PensyveError
if errors.As(err, &perr) && perr.Status == 401 {
    log.Fatal("invalid API key")
}

On this page