Help us shape the future of Go! Take the 2026 Go Developer Survey

client

package
v0.8.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 24, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package client is ladyM's Go SDK for the HTTP data-plane (`ladym serve --http`): one method per /api/* endpoint — the nine MCP-tool endpoints (remember/recall/record_event/search via recall code_only/consolidate/ stats/link/forget, plus login) and the management-console CRUD for memories and users — with database-level Basic auth (users table).

It is the first language client; other languages live alongside it under client/<lang>/ (e.g. client/python/); the wire contract is api/api.go and api/crud.go.

Usage: 

c := client.New("http://127.0.0.1:8080", client.WithAuth("alice", "s3cret"))
res, err := c.Remember(ctx, "the sky is blue", []string{"fact"}, "")

The client sets no default timeout — callers bound each call with their own context (the CLI wraps 30s/120s; see cli/remote.go). Non-2xx responses surface as *Error{StatusCode, Message} with Message taken from the server's {"error": ...} body; network failures are single-line actionable errors ("cannot reach ladym server at ...").

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

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

Client talks to one `ladym serve --http` data-plane.

func New 

func New(baseURL string, opts ...Option) *Client

New returns a Client for baseURL (e.g. "http://127.0.0.1:8080"; a trailing slash is stripped). No default timeout: callers bound calls via ctx.

func (*Client) Consolidate 

func (c *Client) Consolidate(ctx context.Context, workspace string, since float64) (*ConsolidateResult, error)

Consolidate runs one System2 consolidation cycle. since (unix seconds) bounds the pass to episodes created at or after that time; 0 processes the whole pending backlog. It can take far longer than a plain read — callers should use a generous context deadline.

func (*Client) CreateUser 

func (c *Client) CreateUser(ctx context.Context, username, password, workspace string, admin bool) (*schema.User, error)

CreateUser creates one account (admin only). An empty password creates a passwordless user.

func (*Client) DeleteMemory 

func (c *Client) DeleteMemory(ctx context.Context, id string) error

DeleteMemory deletes one memory by id; a missing id is a 404 *Error.

func (*Client) DeleteUser 

func (c *Client) DeleteUser(ctx context.Context, username string) error

DeleteUser deletes one account (admin only; the server rejects deleting the calling account itself). A missing username is a 404 *Error.

func (*Client) Forget 

func (c *Client) Forget(ctx context.Context, id string) error

Forget deletes a memory by id (no-op when missing, MCP semantics; for 404-on-missing semantics use DeleteMemory). 

func (c *Client) Link(ctx context.Context, src, dst, relation string) (string, error)

Link creates an associative edge src -[relation]-> dst and returns the edge id. An empty relation defaults to "related_to" server-side.

func (*Client) ListMemories 

func (c *Client) ListMemories(ctx context.Context, f MemoryFilter) (*MemoryList, error)

ListMemories lists memories with workspace/layer/type filters.

func (*Client) ListUsers 

func (c *Client) ListUsers(ctx context.Context) ([]*schema.User, error)

ListUsers lists all accounts (admin only). The returned Users never carry a password hash.

func (*Client) Login 

func (c *Client) Login(ctx context.Context) (*schema.User, error)

Login verifies the client's own credentials against the users table and returns the account (username/workspace/admin; the password hash never leaves the server). No session is created — the data-plane is stateless.

func (*Client) Ping 

func (c *Client) Ping(ctx context.Context) error

Ping probes /healthz (exempt from auth); nil means the server and its store are reachable.

func (*Client) Recall 

func (c *Client) Recall(ctx context.Context, query string, opts RecallOptions) (*schema.RecallResponse, error)

Recall queries memories. The response decodes straight into schema.RecallResponse — the api package already mirrors its JSON shape.

func (*Client) RecallOperations added in v0.8.4 

func (c *Client) RecallOperations(ctx context.Context, q OperationsQuery) (*OperationsResult, error)

RecallOperations asks "how did I operate on this resource?" — the operation-history pivot (resource × action filter, operates_on graph join, ACT-R ranking). An unknown resource degrades to plain recall with Fallback=true and an empty Resource.

func (*Client) RecordEvent 

func (c *Client) RecordEvent(ctx context.Context, agent, action, observation, outcome string, tags []string, workspace string) (*RecordEventResult, error)

RecordEvent writes an L1 episodic event.

func (*Client) RecordOperation added in v0.8.4 

func (c *Client) RecordOperation(ctx context.Context, ws string, ev RecordOperationInput) (*RecordOperationResult, error)

RecordOperation writes one structured L1 operation: each resource is resolved (or created) as a workspace entity and linked to the episode with operates_on.

func (*Client) Remember 

func (c *Client) Remember(ctx context.Context, content string, tags []string, workspace string) (*RememberResult, error)

Remember writes a semantic fact (server labels the source "http").

func (*Client) RememberWithSource 

func (c *Client) RememberWithSource(ctx context.Context, content, source string, tags []string, workspace string) (*RememberResult, error)

RememberWithSource is Remember with an explicit source label (the CLI passes "cli"; an empty source lets the server default to "http").

func (*Client) Stats 

func (c *Client) Stats(ctx context.Context, workspace string) (*schema.Stats, error)

Stats returns aggregate statistics (workspace-scoped when the server forces one on the authenticated user).

func (*Client) UpdateMemory 

func (c *Client) UpdateMemory(ctx context.Context, id string, patch MemoryPatch) error

UpdateMemory patches content/summary/tags of one memory. A content change re-embeds server-side.

func (*Client) UpdateUser 

func (c *Client) UpdateUser(ctx context.Context, username string, patch UserPatch) (*schema.User, error)

UpdateUser patches one account's password/workspace/admin (admin only).

type ConsolidateResult 

type ConsolidateResult struct {
	KeptEpisodes        int            `json:"kept_episodes"`
	PromotedToSemantic  int            `json:"promoted_to_semantic"`
	SkippedConsolidated int            `json:"skipped_consolidated"`
	Actions             map[string]int `json:"actions"`
}

ConsolidateResult is the /api/consolidate report.

type Error 

type Error struct {
	StatusCode int
	Message    string
}

Error is a non-2xx response from the server. Message is the server's {"error": ...} field, falling back to the trimmed body for non-JSON error pages (proxies etc.), always single-line.

func (*Error) Error 

func (e *Error) Error() string

type MemoryFilter 

type MemoryFilter struct {
	Workspace string
	Layer     string
	Type      string
	Limit     int
	Offset    int
}

MemoryFilter filters/paginates ListMemories. Zero Limit/Offset are omitted so the server defaults apply (limit 50, offset 0).

type MemoryList 

type MemoryList struct {
	Memories []*schema.Memory `json:"memories"`
	Total    int              `json:"total"`
}

MemoryList is one page of GET /api/memories. Total is the filtered count before pagination.

type MemoryPatch 

type MemoryPatch struct {
	Content *string  `json:"content,omitempty"`
	Summary *string  `json:"summary,omitempty"`
	Tags    []string `json:"tags,omitempty"`
}

MemoryPatch is a partial memory update; nil fields are left unchanged.

type OperationsQuery added in v0.8.4 

type OperationsQuery struct {
	Workspace string
	Resource  string
	Action    string
	Since     float64
	Until     float64
	Outcome   string
	Limit     int
}

OperationsQuery mirrors the POST /api/recall_ops body. Resource is required; Limit 0 lets the server default (10, capped at 100); Since and Until are unix seconds (0 = unbounded).

type OperationsResult added in v0.8.4 

type OperationsResult struct {
	Resource string                 `json:"resource"`
	Items    []*schema.RecallResult `json:"items"`
	Fallback bool                   `json:"fallback"`
}

OperationsResult is the /api/recall_ops response. Resource is the resolved entity id ("" on a fallback pivot); Items decode straight into schema.RecallResult — the server mirrors the MCP recall_ops item shape.

type Option 

type Option func(*Client)

Option customizes a Client.

func WithAuth 

func WithAuth(username, password string) Option

WithAuth sets the Basic-auth credentials. A username with an empty password is valid — it matches a passwordless server account. With no WithAuth at all, no Authorization header is sent (no-auth deployments).

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient swaps the underlying http.Client (proxies, TLS, tracing).

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout sets http.Client.Timeout. Prefer a per-call context deadline; this is a blunt instrument for simple callers.

type RecallOptions 

type RecallOptions struct {
	Workspace string
	TopK      int
	CodeOnly  bool
}

RecallOptions tunes Recall. TopK 0 lets the server default (8); CodeOnly restricts to code items (the server maps it to SearchCode, so there is no separate SearchCode client method).

type RecordEventResult 

type RecordEventResult struct {
	ID    string `json:"id"`
	Layer string `json:"layer"`
	Type  string `json:"type"`
}

RecordEventResult is the /api/record_event response.

type RecordOperationInput added in v0.8.4 

type RecordOperationInput struct {
	Action      string
	Resources   []string
	Observation string
	Outcome     string
	Agent       string
	Tags        []string
}

RecordOperationInput mirrors the POST /api/record_operation body. Agent "" lets the server default to "api"; the action is normalized server-side onto the controlled vocabulary (Resources must be non-empty).

type RecordOperationResult added in v0.8.4 

type RecordOperationResult struct {
	ID      string `json:"id"`
	Dropped bool   `json:"dropped"`
	Reason  string `json:"reason"`
}

RecordOperationResult is the /api/record_operation response. Dropped is always false today (the attention gate covers the Remember path only); the field keeps the wire shape forward-compatible, with Reason explaining a drop if one ever applies.

type RememberResult 

type RememberResult struct {
	ID     string `json:"id"`
	Hash   string `json:"hash"`
	Gated  string `json:"gated"`
	Reason string `json:"reason"`
}

RememberResult is the /api/remember response. On an attention-gate drop nothing is persisted: ID/Hash are empty, Gated is "dropped" and Reason explains why (see Dropped).

func (*RememberResult) Dropped 

func (r *RememberResult) Dropped() bool

Dropped reports whether the server's attention gate dropped the write.

type UserPatch 

type UserPatch struct {
	Password  *string `json:"password,omitempty"`
	Workspace *string `json:"workspace,omitempty"`
	Admin     *bool   `json:"admin,omitempty"`
}

UserPatch is a partial account update; nil fields are left unchanged. An explicitly empty Password makes the account passwordless.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.