memaura

README

MemAura Go SDK

简体中文

The official Go SDK for the MemAura API-key memory data plane. It provides a stable Memory facade for asynchronous ingestion, regular retrieval, explicit hybrid retrieval, and ingestion-job tracking.

Requirements

• Go 1.25 or Go 1.26
• A MemAura API key (qbk_...)

Install

go get github.com/Omnimemory/go-sdk@latest

Quick Start

package main

import (
	"context"
	"os"

	memaura "github.com/Omnimemory/go-sdk"
)

func main() {
	ctx := context.Background()
	memory, err := memaura.NewMemory(memaura.Config{
		APIKey:   os.Getenv("MEMAURA_API_KEY"),
		DeviceNo: "backend-worker-1",
	})
	if err != nil {
		panic(err)
	}

	ack, err := memory.Add(ctx, memaura.AddInput{
		CommitID: "conversation-42:1",
		Turns: []memaura.Turn{{
			Content: "The product review is next Wednesday at 3 PM.",
			Role:    memaura.RoleUser,
		}},
	})
	if err != nil {
		panic(err)
	}

	if _, err := memory.Jobs().Wait(ctx, ack.JobID); err != nil {
		panic(err)
	}

	result, err := memory.SearchHybrid(ctx, memaura.SearchInput{
		Query: "When is the product review?",
		Limit: 3,
	})
	if err != nil {
		panic(err)
	}
	_ = result
}

API

memory, err := memaura.NewMemory(memaura.Config{
	APIKey:     "qbk_...", // required
	Endpoint:   "https://api.omnimemory.cn/api/v2", // optional
	DeviceNo:   "service-a", // optional default device namespace
	HTTPClient: nil, // optional custom *http.Client
})

ack, err := memory.Add(ctx, memaura.AddInput{...})
regular, err := memory.Search(ctx, memaura.SearchInput{Query: "..."})
hybrid, err := memory.SearchHybrid(ctx, memaura.SearchInput{Query: "..."})
status, err := memory.Jobs().Get(ctx, ack.JobID)
finished, err := memory.Jobs().Wait(ctx, ack.JobID)

• Add is asynchronous. Use CommitID for idempotent retry behavior.
• Search always uses /memory/retrieval; SearchHybrid always uses /memory/retrieval/hybrid.
• A configured DeviceNo, or an operation-level DeviceNo, is sent as X-Device-No for ingestion and retrieval.
• Jobs().Wait polls once per second by default and has a one-minute default timeout. Use WithPollInterval and WithWaitTimeout to change these values. accumulated is a successful terminal state.

See the full API reference and the basic example.

Error Handling

• *memaura.ValidationError: invalid local input; no request was sent.
• *memaura.APIError: a Router error envelope; inspect StatusCode, Code, ErrorCode, and Detail.
• *memaura.TimeoutError: job waiting reached its deadline. It unwraps to context.DeadlineExceeded and includes LastJob when available.
• Network, transport, and caller-context errors are returned with their original cause.

Security

This SDK is for trusted server-side Go applications. Do not ship a qbk_... API key in a browser, mobile application, desktop client, or other untrusted distribution.

Contract and Development

The checked-in OpenAPI snapshot is intentionally limited to four API-key data-plane operations. The internal client is generated with ogen v1.20.3; generated files are committed and must not be edited manually.

# Requires a local Go 1.25+ toolchain and jq.
make snapshot OPENAPI_SOURCE=/path/to/router/docs/openapi.v2.json
make generate
make check-generated
go test -race ./...

Git tags in the form vX.Y.Z are Go Module release versions. CI verifies both supported Go releases before a tag is created.

License

MIT

Documentation

Overview

Package memaura is the official Go SDK for the MemAura memory data plane.

Index

• type APIError
  • func (e *APIError) Error() string
• type AddInput
• type Config
• type EvidenceDetail
• type JobAck
• type JobOperations
  • func (jobs *JobOperations) Get(ctx context.Context, jobID string) (JobStatus, error)
  • func (jobs *JobOperations) Wait(ctx context.Context, jobID string, options ...WaitOption) (JobStatus, error)
• type JobStatus
• type Memory
  • func NewMemory(config Config) (*Memory, error)
  • func (m *Memory) Add(ctx context.Context, input AddInput) (JobAck, error)
  • func (m *Memory) Jobs() *JobOperations
  • func (m *Memory) Search(ctx context.Context, input SearchInput) (SearchResult, error)
  • func (m *Memory) SearchHybrid(ctx context.Context, input SearchInput) (SearchResult, error)
• type Role
• type SearchInput
• type SearchResult
• type TimeoutError
  • func (e *TimeoutError) Error() string
  • func (e *TimeoutError) Unwrap() error
• type Turn
• type ValidationError
  • func (e *ValidationError) Error() string
• type WaitOption
  • func WithPollInterval(interval time.Duration) WaitOption
  • func WithWaitTimeout(timeout time.Duration) WaitOption

Types

type APIError

type APIError struct {
	StatusCode int
	Code       int
	ErrorCode  string
	Message    string
	Detail     json.RawMessage
}

APIError reports a non-success MemAura API envelope.

func (*APIError) Error

func (e *APIError) Error() string

type AddInput

type AddInput struct {
	Turns     []Turn
	SessionID string
	GroupID   string
	GroupName string
	CommitID  string
	DeviceNo  string
}

AddInput describes a memory-ingestion request.

type Config

type Config struct {
	// APIKey authenticates data-plane requests. Keep it on trusted servers only.
	APIKey string
	// Endpoint overrides the MemAura API endpoint.
	Endpoint string
	// DeviceNo is sent as X-Device-No unless an operation overrides it.
	DeviceNo string
	// HTTPClient optionally replaces the default HTTP client.
	HTTPClient *http.Client
}

Config configures a Memory client.

type EvidenceDetail

type EvidenceDetail struct {
	EventID     string
	Text        string
	Source      string
	Role        *string
	SenderName  *string
	AtomicFacts []string
	GroupID     *string
	Timestamp   *string
}

EvidenceDetail is one ordered item of retrieval evidence.

type JobAck

type JobAck struct {
	JobID     string
	SessionID string
	Status    string
	StatusURL string
}

JobAck confirms that an ingestion request has been accepted.

type JobOperations

type JobOperations struct {
	// contains filtered or unexported fields
}

JobOperations provides status and waiting operations for asynchronous ingestion.

func (*JobOperations) Get

func (jobs *JobOperations) Get(ctx context.Context, jobID string) (JobStatus, error)

Get returns the current status of an ingest job.

func (*JobOperations) Wait

func (jobs *JobOperations) Wait(ctx context.Context, jobID string, options ...WaitOption) (JobStatus, error)

Wait polls until the job has a terminal status or the context/deadline ends.

type JobStatus

type JobStatus struct {
	JobID     string
	SessionID string
	Status    string
}

JobStatus is the current state of an asynchronous ingestion task.

type Memory

type Memory struct {
	// contains filtered or unexported fields
}

Memory is a configured API-key client for MemAura memory operations.

func NewMemory

func NewMemory(config Config) (*Memory, error)

NewMemory creates a Memory client.

func (*Memory) Add

func (m *Memory) Add(ctx context.Context, input AddInput) (JobAck, error)

Add queues a memory-ingestion request. CommitID makes caller-managed retries idempotent.

func (*Memory) Jobs

func (m *Memory) Jobs() *JobOperations

Jobs returns the job operations associated with this Memory client.

func (*Memory) Search

func (m *Memory) Search(ctx context.Context, input SearchInput) (SearchResult, error)

Search performs regular memory retrieval.

func (*Memory) SearchHybrid

func (m *Memory) SearchHybrid(ctx context.Context, input SearchInput) (SearchResult, error)

SearchHybrid performs explicit hybrid memory retrieval.

type Role

type Role string

Role identifies the author of a memory turn.

const (
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
	RoleSystem    Role = "system"
)

type SearchInput

type SearchInput struct {
	Query    string
	Limit    int
	GroupID  string
	DeviceNo string
}

SearchInput describes a regular or hybrid memory retrieval request.

type SearchResult

type SearchResult struct {
	Strategy         string
	Query            string
	Evidence         []string
	EvidenceDetails  []EvidenceDetail
	RequestedGroupID *string
}

SearchResult is the normalized result of a regular or hybrid retrieval.

type TimeoutError

type TimeoutError struct {
	JobID   string
	LastJob *JobStatus
}

TimeoutError reports that waiting for an ingest job reached its deadline.

func (*TimeoutError) Error

func (e *TimeoutError) Error() string

func (*TimeoutError) Unwrap

func (e *TimeoutError) Unwrap() error

Unwrap allows errors.Is(err, context.DeadlineExceeded).

type Turn

type Turn struct {
	Content    string
	Role       Role
	TurnID     string
	Timestamp  string
	SenderName string
	ReferList  []string
}

Turn is one message submitted for asynchronous memory ingestion.

type ValidationError

type ValidationError struct {
	Field   string
	Message string
}

ValidationError reports invalid client-side input before a request is sent.

func (*ValidationError) Error

func (e *ValidationError) Error() string

type WaitOption

type WaitOption interface {
	// contains filtered or unexported methods
}

WaitOption configures Jobs().Wait.

func WithPollInterval

func WithPollInterval(interval time.Duration) WaitOption

WithPollInterval sets the delay between job status requests.

func WithWaitTimeout

func WithWaitTimeout(timeout time.Duration) WaitOption

WithWaitTimeout bounds the total time spent waiting for a job.