Go SDK Reference

The Go SDK is a client for the Memanto REST server. Point it at a server you run (BaseURL), or leave BaseURL empty and it starts uvx memanto serve on first use, like the TypeScript SDK.

Prerequisites

Go 1.24+
uvx on PATH, only if the client starts the server itself. Install uv, which ships uvx.

Installation

go get github.com/moorcheh-ai/memanto/sdks/go

Quick Start

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	memanto "github.com/moorcheh-ai/memanto/sdks/go"
)

func main() {
	ctx := context.Background()
	client, err := memanto.New(memanto.Options{
		AgentID: "my-agent",
		APIKey:  os.Getenv("MOORCHEH_API_KEY"),
	})
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close() // stops the server the client started

	if _, err := client.Remember(ctx, memanto.RememberInput{
		Content: "Alex prefers oat milk.",
		Type:    "preference",
	}); err != nil {
		log.Fatal(err)
	}

	recalled, err := client.Recall(ctx, memanto.RecallInput{Query: "what does Alex drink?"})
	if err != nil {
		log.Fatal(err)
	}
	for _, m := range recalled.Memories {
		if m.Content != nil { // optional fields in api types are pointers
			fmt.Println(*m.Content)
		}
	}

	answer, err := client.Answer(ctx, memanto.AnswerInput{Question: "Does Alex drink dairy?"})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(answer.Answer)
}

New memories take about a second to become searchable, so a Recall right after a Remember may not return them yet. On the first call, the client:

Starts the server, unless BaseURL is set: picks a free port, runs uvx memanto serve --host 127.0.0.1 --port <port>, and waits for /health.
Creates the agent if it does not exist (unless DisableAutoCreate is set).
Activates a session and sends its token with each memory call. If the server rejects the token, the client activates a new session and retries once.

A Client is safe for concurrent use from multiple goroutines.

Close stops a server the client started. Go has no exit hooks, so always call it (defer client.Close()); otherwise the server keeps running after your program exits.

Memanto allows one session per agent. Activating a session signs out every other client of that agent (the CLI, MCP, IDE hooks), and the other way round. Use a separate agent for your Go program if other tools use the same agent at the same time.

Connecting to a Running Server

To use a server you started with memanto serve (or Docker), set BaseURL. The client then never starts a server, and Close leaves yours running:

client, err := memanto.New(memanto.Options{
	AgentID: "my-agent",
	BaseURL: "http://127.0.0.1:8000",
	APIKey:  os.Getenv("MOORCHEH_API_KEY"),
})

APIKey is sent as X-Api-Key on every request. A server reachable beyond localhost requires it to create or activate agents.

On-Prem

No API key is needed on the on-prem backend. Run uvx memanto once and choose On-Prem; a server the client starts inherits that config from ~/.memanto/:

client, err := memanto.New(memanto.Options{AgentID: "my-agent"})

See the On-Prem Overview.

`Client`

Options

memanto.New(opts memanto.Options) (*memanto.Client, error)

New does not contact the server; that happens on the first call.

Field	Type	Default	Description
`AgentID`	`string`	—	Required. The agent this client works with.
`DisableAutoCreate`	`bool`	`false`	Do not create the agent when it is missing.
`BaseURL`	`string`	—	A running server. When empty, the client starts one with `uvx`.
`APIKey`	`string`	—	Moorcheh API key. Passed to a started server as `MOORCHEH_API_KEY` and sent as `X-Api-Key`.
`HTTPClient`	`*http.Client`	`http.DefaultClient`	HTTP client for all requests.
`Host`	`string`	`127.0.0.1`	Bind host of a started server.
`Port`	`int`	free port	Port of a started server.
`UvxPath`	`string`	`uvx`	Path to `uvx`.
`PackageSpec`	`string`	`memanto`	Package passed to `uvx`. Use `memanto==0.2.3` to pin.
`HealthTimeout`	`time.Duration`	`60s`	How long to wait for a started server to become healthy.
`Verbose`	`bool`	`false`	Stream a started server’s logs to stdout and stderr.

Every method takes a context.Context first. Responses are typed with the generated package github.com/moorcheh-ai/memanto/sdks/go/api; endpoints without a response schema return map[string]any.

Memory Write Methods

client.Remember(ctx, memanto.RememberInput{Content, Type, Title, Confidence, Tags, Source, Provenance}) // *api.RememberResponse
client.BatchRemember(ctx, []memanto.RememberInput{...})             // up to 100 items
client.ExtractMemories(ctx, memanto.ExtractMemoriesInput{Messages, DryRun, MaxMemories, AIModel})
client.UploadFile(ctx, memanto.UploadFileInput{Path, Filename})     // .pdf, .docx, .xlsx, .json, .txt, .csv, .md
client.DeleteMemory(ctx, memoryID)

In RememberInput, Confidence defaults to 0.8, Source to agent, and Provenance to explicit_statement.

Memory Read Methods

client.Recall(ctx, memanto.RecallInput{Query, Limit, MinSimilarity, Type, Tags}) // Tags: only memories carrying all of them
client.RecallAsOf(ctx, memanto.RecallAsOfInput{AsOf, Limit, Type})               // point-in-time
client.RecallChangedSince(ctx, memanto.RecallChangedSinceInput{Since, Limit, Type})
client.RecallRecent(ctx, memanto.RecallRecentInput{Limit, Type})                 // newest first
client.Answer(ctx, memanto.AnswerInput{Question, Limit, Threshold, Temperature, AIModel, KioskMode})

AsOf and Since take YYYY-MM-DD or an ISO 8601 datetime. Optional numbers where zero is a meaningful value (MinSimilarity, Threshold, Temperature) are pointers. Leave them nil for the server default, or set one with memanto.Ptr:

client.Answer(ctx, memanto.AnswerInput{Question: "...", Temperature: memanto.Ptr(0.0)})

Analysis Methods

client.DailySummary(ctx, memanto.DailySummaryInput{Date, OutputPath})
client.GenerateConflicts(ctx, memanto.ConflictDateInput{Date})
client.ListConflicts(ctx, memanto.ConflictDateInput{Date})
client.ResolveConflict(ctx, memanto.ResolveConflictInput{ConflictIndex, Action, Date, ManualContent, ManualType})

Action is one of keep_old, keep_new, keep_both, remove_both, manual.

Agent & Session Lifecycle

client.ListAgents(ctx)
client.GetAgent(ctx)
client.CreateAgent(ctx, memanto.CreateAgentInput{Pattern, Description}) // only needed with DisableAutoCreate
client.DeleteAgent(ctx, memanto.DeleteAgentInput{DeleteMemories})       // memories kept in Moorcheh unless DeleteMemories is true
client.Deactivate(ctx) // end the session; the next call activates a new one
client.Status(ctx)     // the server's active session
client.Close()         // stop the server the client started

Errors

A failed call returns a nil result and an error. When the server answers with a non-2xx status, the error is a *memanto.APIError carrying StatusCode and the server’s message in Detail:

_, err := client.GetAgent(ctx)
var apiErr *memanto.APIError
if errors.As(err, &apiErr) && apiErr.StatusCode == http.StatusNotFound {
	// the agent does not exist
}

If uvx is not installed, the first call returns an error telling you to install uv.

Versioning

Each Memanto release vX.Y.Z also tags the Go SDK as sdks/go/vX.Y.Z, so the SDK version matches the memanto release on PyPI:

go get github.com/moorcheh-ai/memanto/sdks/go@latest   # or @vX.Y.Z for a specific release

To pin the server a started client runs, set PackageSpec: "memanto==<version>".

License

MIT

Python

Node.js

Go

Go SDK Reference

Go SDK Reference

Prerequisites

Installation

Quick Start

Connecting to a Running Server

On-Prem

`Client`

Options

Memory Write Methods

Memory Read Methods

Analysis Methods

Agent & Session Lifecycle

Errors

Versioning

License

​Go SDK Reference

​Prerequisites

​Installation

​Quick Start

​Connecting to a Running Server

​On-Prem

​Client

​Options

​Memory Write Methods

​Memory Read Methods

​Analysis Methods

​Agent & Session Lifecycle

​Errors

​Versioning

​License

Go SDK Reference

Prerequisites

Installation

Quick Start

Connecting to a Running Server

On-Prem

`Client`

Options

Memory Write Methods

Memory Read Methods

Analysis Methods

Agent & Session Lifecycle

Errors

Versioning

License