Go SDK

dakera-go is the Go client for the Dakera REST API. This page covers installation, client setup and the main calls (memories, sessions, search, knowledge graph, administration) for Go developers integrating Dakera into services and agents.

pkg.go.dev · GitHub

go get github.com/dakera-ai/dakera-go@v0.12.3

The current release is v0.12.3. It uses only the Go standard library at runtime. Every method takes a context.Context first; the snippets below assume ctx := context.Background().

Client setup

import (
    "os"
    "time"

    dakera "github.com/dakera-ai/dakera-go"
)

// Keep the URL and key out of source code:
// DAKERA_API_URL=http://<YOUR_SERVER_IP>:3000
// DAKERA_API_KEY=your-api-key

serverURL := os.Getenv("DAKERA_API_URL")
if serverURL == "" {
    serverURL = "http://localhost:3000"
}

client := dakera.NewClientWithOptions(dakera.ClientOptions{
    BaseURL: serverURL,
    APIKey:  os.Getenv("DAKERA_API_KEY"),
    Timeout: 30 * time.Second, // the default
})

dakera.NewClient(baseURL) creates a client without a key. ClientOptions also accepts ConnectTimeout, MaxRetries, RetryBackoff (*dakera.RetryConfig) and extra Headers.

Memory operations

importance := float32(0.8)
stored, err := client.StoreMemory(ctx, "my-agent", dakera.StoreMemoryRequest{
    Content:    "User is learning Rust",
    Importance: &importance,
    Tags:       []string{"learning"},
})
memID := stored.Memory.ID

recalled, err := client.Recall(ctx, "my-agent", dakera.RecallRequest{
    Query: "which programming language is the user learning?",
    TopK:  10,
})
for _, m := range recalled.Memories {
    fmt.Printf("%s (score: %.2f)\n", m.Content, m.Score)
}

memory, err := client.GetMemory(ctx, "my-agent", memID)
err = client.Forget(ctx, "my-agent", memID)

Sessions

session, err := client.StartSession(ctx, dakera.StartSessionRequest{
    AgentID:  "my-agent",
    Metadata: map[string]interface{}{"task": "review"},
})

_, err = client.StoreMemory(ctx, "my-agent", dakera.StoreMemoryRequest{
    Content:   "Found 2 issues",
    SessionID: session.ID,
})

ended, err := client.EndSession(ctx, session.ID)
fmt.Println(ended.MemoryCount)

sessions, err := client.ListSessions(ctx, nil)

EndSession takes only the session ID; v0.12.3 does not send a summary.

ChatMemorySession — LLM chat helper

ChatMemorySession wraps the session and memory calls for LLM chat loops. Create it with NewChatMemorySession, store turns with Store, recall context with Recall, and end the session with Close.

session, err := dakera.NewChatMemorySession(ctx, client, "chat-agent", nil)
if err != nil {
    return err
}
defer session.Close(ctx) // ends the session

session.Store(ctx, "user", "What is the capital of France?")
session.Store(ctx, "assistant", "The capital of France is Paris.")
memories, err := session.Recall(ctx, "capital cities", 5)

Text vectors

// Upsert documents; the server embeds the text
_, err := client.UpsertText(ctx, "docs", []dakera.TextDocument{
    {ID: "doc-001", Text: "Quarterly revenue report", Metadata: map[string]interface{}{"source": "finance"}},
}, nil)

// Query by natural language
res, err := client.QueryText(ctx, "docs", "revenue trends", &dakera.TextQueryOptions{TopK: 5})
for _, r := range res.Results {
    fmt.Println(r.ID, r.Score)
}

// Several text queries in one request
batch, err := client.BatchQueryText(ctx, "docs", []string{"revenue report", "product roadmap"},
    &dakera.BatchTextQueryOptions{TopK: 5})

For raw vectors use Upsert, Query, Fetch and Delete.

Namespace management

_, err := client.CreateNamespace(ctx, "production", &dakera.CreateNamespaceOptions{
    Dimensions: 1024,
    IndexType:  "hnsw",
})

names, err := client.ListNamespaces(ctx) // []string

err = client.DeleteNamespace(ctx, "old-namespace")

Knowledge graph

depth := 2
graph, err := client.KnowledgeGraph(ctx, dakera.KnowledgeGraphRequest{
    AgentID:  "my-agent",
    MemoryID: memID,
    Depth:    &depth,
})

network, err := client.CrossAgentNetwork(ctx, dakera.CrossAgentNetworkRequest{
    AgentIDs: []string{"agent-a", "agent-b"},
})

// Preview duplicates without merging
dupes, err := client.Deduplicate(ctx, dakera.DeduplicateRequest{
    AgentID: "my-agent",
    DryRun:  true,
})

Full-text and hybrid search

// Index documents for BM25
_, err := client.IndexDocuments(ctx, "docs", []dakera.DocumentInput{
    {ID: "doc-1", Text: "Quarterly revenue report"},
})

// BM25 search
hits, err := client.FulltextSearch(ctx, "docs", "revenue", &dakera.FullTextSearchOptions{TopK: 5})

// Hybrid: pass a query vector to blend vector and BM25 scores;
// with a nil vector the server answers with BM25 only
results, err := client.HybridSearch(ctx, "docs", queryVector /* []float32 */, "revenue trends",
    &dakera.HybridSearchOptions{TopK: 10, VectorWeight: 0.7})

Entity extraction and feedback

// Extract entities (nil = the server's default entity types)
entities, err := client.ExtractEntities(ctx, "Alice met Bob at Google HQ", nil)

// Feedback on a recalled memory
_, err = client.FeedbackMemory(ctx, memID, "my-agent", dakera.FeedbackSignalUpvote)
summary, err := client.GetAgentFeedbackSummary(ctx, "my-agent")

Import, export and API keys

// Export: format "mem0", "zep", "jsonl" or "csv"; agent, namespace and limit are optional
export, err := client.ExportMemories(ctx, "jsonl", "my-agent", "", 0)

// Import from Mem0 format
_, err = client.ImportMemories(ctx, mem0Data, "mem0", "my-agent", "")

// Namespace-scoped API key
days := 90
key, err := client.CreateNamespaceKey(ctx, "production", dakera.CreateNamespaceKeyRequest{
    Name:          "reader",
    ExpiresInDays: &days,
})

Global keys with a scope (read, write, admin, super_admin) are created with CreateKey and need a super_admin key.

Batch operations

maxImp := float32(0.3)
resp, err := client.BatchForget(ctx, dakera.BatchForgetRequest{
    AgentID: "my-agent",
    Filter: dakera.BatchMemoryFilter{
        Tags:          []string{"obsolete"},
        MaxImportance: &maxImp,
    },
})
fmt.Printf("Deleted %d memories\n", resp.DeletedCount)

Health probes

ready, err := client.HealthReady(ctx) // GET /health/ready: storage and models loaded
live, err := client.HealthLive(ctx)   // GET /health/live: process alive

Gate traffic on HealthReady: while a v0.12.0 server loads its models, /health and /health/ready answer 503.

Vector bulk operations

filter := map[string]interface{}{"source": "finance"}

// Update metadata of every vector matching a filter
_, err := client.BulkUpdateVectors(ctx, "docs", filter, map[string]interface{}{"reviewed": true})

// Delete every vector matching a filter
_, err = client.BulkDeleteVectors(ctx, "docs", filter)

// Count vectors (nil filter = all)
count, err := client.CountVectors(ctx, "docs", nil)

Full-text index management

stats, err := client.FulltextStats(ctx, "docs")
fmt.Printf("Documents: %d, unique terms: %d\n", stats.DocumentCount, stats.UniqueTerms)

_, err = client.FulltextDelete(ctx, "docs", []string{"doc-001"})

TTL and storage

ttl, err := client.AdminTtlStats(ctx)
tiers, err := client.AdminStorageTierOverview(ctx)
typeStats, err := client.AdminMemoryTypeStats(ctx) // episodic, semantic, procedural, working

Agent consolidation

_, err := client.ConsolidateAgent(ctx, "my-agent")

log, err := client.GetConsolidationLog(ctx, "my-agent")

enabled := true
_, err = client.PatchConsolidationConfig(ctx, "my-agent", dakera.ConsolidationConfigPatch{
    Enabled: &enabled,
})

Namespace config

config, err := client.GetNamespaceEntityConfig(ctx, "production")
extractor, err := client.GetNamespaceExtractor(ctx, "production")

// Turn entity extraction on (PATCH /v1/namespaces/{ns}/config)
_, err = client.ConfigureNamespaceNer(ctx, "production", dakera.NamespaceNerConfig{
    ExtractEntities: true,
    EntityTypes:     []string{"person", "organization", "location"},
})

// Migrate namespaces to a new embedding dimension
_, err = client.AdminMigrateNamespaceDimensions(ctx, dakera.MigrateNamespaceDimensionsRequest{
    Namespaces:      []string{"production"},
    TargetDimension: 1024,
})

Admin and ops

cluster, err := client.ClusterStatus(ctx)

// Maintenance mode
_, err = client.AdminEnableMaintenance(ctx, dakera.EnableMaintenanceRequest{Reason: "scheduled upgrade"})
_, err = client.AdminDisableMaintenance(ctx, dakera.DisableMaintenanceRequest{})

// Quotas
quotas, err := client.AdminListQuotas(ctx)
maxVectors := uint64(100000)
_, err = client.AdminSetQuota(ctx, "production", dakera.SetQuotaRequest{
    Config: dakera.QuotaConfig{MaxVectors: &maxVectors},
})

// Slow query log
slow, err := client.SlowQueries(ctx, &dakera.SlowQueryOptions{Limit: 20})

// Backups
backup, err := client.CreateBackup(ctx, true) // include data
backups, err := client.ListBackups(ctx)

// Diagnostics, jobs, compaction, shutdown
diag, err := client.OpsDiagnostics(ctx)
jobs, err := client.OpsListJobs(ctx)
_, err = client.OpsCompact(ctx, dakera.CompactionRequest{Namespace: "production"})
_, err = client.OpsShutdown(ctx)

On a v0.12.0 server these routes need an admin key with no namespace restriction; restoring, uploading or downloading a backup needs super_admin. See Upgrading to v0.12.

AutoPilot and decay (admin)

status, err := client.AutopilotStatus(ctx)

on, threshold := true, float32(0.93)
_, err = client.AutopilotUpdateConfig(ctx, dakera.AutoPilotConfigRequest{
    Enabled:        &on,
    DedupThreshold: &threshold,
})

// Trigger a cycle: "dedup", "consolidate" or "all"
_, err = client.AutopilotTrigger(ctx, "dedup")

decay, err := client.DecayConfig(ctx)
halfLife := 720.0 // hours
_, err = client.DecayUpdateConfig(ctx, dakera.DecayConfigUpdateRequest{
    HalfLifeHours: &halfLife,
})

Memory policy

episodic, working := int64(604800), int64(3600)
_, err := client.SetMemoryPolicy(ctx, "production", dakera.MemoryPolicy{
    EpisodicTTLSeconds: &episodic,
    WorkingTTLSeconds:  &working,
})

policy, err := client.GetMemoryPolicy(ctx, "production")

SSE streaming

events, err := client.StreamMemoryEvents(ctx)
if err != nil {
    return err
}
for ev := range events {
    if ev.Err != nil {
        log.Println(ev.Err)
        continue
    }
    fmt.Printf("%s: %s\n", ev.Event.EventType, ev.Event.AgentID)
}

SubscribeAgentMemories(ctx, agentID, tags) filters the same stream to one agent. On a v0.12.0 server /v1/events/stream needs an admin key with no namespace restriction.

Error handling

import "errors"

_, err := client.GetMemory(ctx, "my-agent", "mem-abc")
if err != nil {
    var notFound *dakera.NotFoundError
    var rateLimit *dakera.RateLimitError
    switch {
    case errors.As(err, &notFound):
        fmt.Println("Not found")
    case errors.As(err, &rateLimit):
        fmt.Printf("Rate limited — retry after %d s\n", rateLimit.RetryAfter)
    default:
        fmt.Printf("Error: %v\n", err)
    }
}

Error types: *DakeraError, *ConnectionError, *NotFoundError, *ValidationError, *RateLimitError, *ServerError, *AuthenticationError, *AuthorizationError, *TimeoutError. Calls return (result, error); deletes such as Forget and DeleteNamespace return only error.

Compatibility with v0.12.0

dakera-go v0.12.1 is the release aligned with Dakera v0.12.0 (it also works against v0.11.108 servers). Against a v0.12.0 server, note:

• Clearing entity types. ConfigureNamespaceNer sends an empty EntityTypes with PUT /v1/namespaces/{ns}/config (a full replacement), because a v0.12.0 PATCH merges and keeps the configured types; it falls back to PATCH with an explicit empty list on a v0.11 server.
• Startup window. While the server loads its models, /health and /health/ready answer 503 and other routes answer 503 with Retry-After: 5. HealthReady reports that 503 as an error, never as healthy; IsReady and WaitUntilReady wait for the server, and the SDK honours Retry-After on 429 and 503.
• Timeouts. The SDK times requests out at 30 s by default; a v0.12.0 server answers a queued recall with 503 + Retry-After within 20 s, before that timeout.
• Scores. Each recalled memory's Score is the server's smart_score when present. v0.12.0 computes it differently from v0.11, so re-check any absolute score cut-off you calibrated on v0.11.

See Upgrading to v0.12 for the full list of behavior changes.

See also: REST API reference · Quickstart · Python SDK · TypeScript SDK · Rust SDK