eidetic

package
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Mar 31, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package eidetic implements a thin HTTP client for the Eidetic memory service. The Eidetic server exposes a JSON-RPC 2.0 endpoint at /mcp and a health check at /health. All exported types used across packages are defined in types.go; this file contains only the client and its request/response shapes.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AppendRequest

type AppendRequest struct {
	Content string
	AgentID string
	Tags    []string
	Vector  []float32 // optional embedding vector for hybrid search
}

AppendRequest is the payload for AppendMemory.

type Client

type Client interface {
	AppendMemory(ctx context.Context, req AppendRequest) error
	SearchMemory(ctx context.Context, req SearchRequest) ([]MemoryEntry, error)
	GetRecent(ctx context.Context, agentID string, limit int) ([]MemoryEntry, error)
	Health(ctx context.Context) error
}

Client is the interface for interacting with the Eidetic memory service. The nil value is not valid; use a nil *Client variable tested against the interface to represent "disabled" — or keep a separate bool flag. All methods must be safe for concurrent use.

type Config

type Config struct {
	BaseURL         string // e.g. "http://localhost:7700"
	APIKey          string
	AgentID         string  // default agent_id for writes; falls back to agent def ID
	RecentLimit     int     // number of recent entries to inject (default 20)
	SearchLimit     int     // max results for search (default 10)
	SearchThreshold float64 // cosine similarity threshold (default 0.5)
	TimeoutSeconds  int     // per-request timeout (default 5)
}

Config holds connection settings for the Eidetic memory service.

type HTTPClient

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

HTTPClient implements Client over the Eidetic HTTP MCP API.

func New

func New(cfg Config) *HTTPClient

New creates a new HTTPClient from cfg. It does not perform a health check; call Health() if you want to verify connectivity at startup.

func (*HTTPClient) AppendMemory

func (c *HTTPClient) AppendMemory(ctx context.Context, req AppendRequest) error

AppendMemory writes a memory entry to Eidetic.

func (*HTTPClient) GetRecent

func (c *HTTPClient) GetRecent(ctx context.Context, agentID string, limit int) ([]MemoryEntry, error)

GetRecent retrieves the N most recent memory entries, optionally filtered by agentID (empty = all agents).

func (*HTTPClient) Health

func (c *HTTPClient) Health(ctx context.Context) error

Health calls GET /health to verify the service is reachable.

func (*HTTPClient) SearchMemory

func (c *HTTPClient) SearchMemory(ctx context.Context, req SearchRequest) ([]MemoryEntry, error)

SearchMemory performs a semantic search over stored memories.

type MemoryEntry

type MemoryEntry struct {
	ID         string
	Content    string
	AgentID    string
	Timestamp  time.Time
	SourceFile string
	Tags       []string
	WordCount  int
	Relevance  float64 // only populated by SearchMemory
}

MemoryEntry is a unified memory entry returned by GetRecent and SearchMemory.

func MMR

func MMR(results []MemoryEntry, lambda float64, maxResults int) []MemoryEntry

MMR re-ranks search results using Maximal Marginal Relevance to balance relevance against diversity. lambda controls the trade-off:

  • lambda=1.0 → pure relevance (no diversity penalty)
  • lambda=0.0 → pure diversity
  • lambda=0.5 → balanced (recommended default)

Results must already be sorted by Relevance descending. The function returns a new slice (up to maxResults) with diverse, relevant entries. If results have no embeddings or len ≤ 1, the original order is preserved.

type RetryClient

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

RetryClient wraps a Client and queues failed AppendMemory calls for background retry. The queue is persisted to disk so entries survive restarts. Search and health calls are proxied through unchanged.

func NewRetryClient

func NewRetryClient(inner Client, logger *zap.SugaredLogger, filePath string) *RetryClient

NewRetryClient wraps inner with a failure queue persisted at filePath. Call StartRetryLoop in a goroutine to process the queue.

func (*RetryClient) AppendMemory

func (rc *RetryClient) AppendMemory(ctx context.Context, req AppendRequest) error

AppendMemory tries the inner client first; on failure, queues the request.

func (*RetryClient) DrainQueue added in v1.2.0

func (rc *RetryClient) DrainQueue(ctx context.Context)

DrainQueue attempts to flush all queued items to the inner client. This is the same logic as the internal loop iteration; it is exported so integration tests and manual recovery tools can trigger a drain without waiting for the next ticker interval.

func (*RetryClient) GetRecent

func (rc *RetryClient) GetRecent(ctx context.Context, agentID string, limit int) ([]MemoryEntry, error)

GetRecent proxies through to the inner client.

func (*RetryClient) Health

func (rc *RetryClient) Health(ctx context.Context) error

Health proxies through to the inner client.

func (*RetryClient) QueueLen

func (rc *RetryClient) QueueLen() int

QueueLen returns the number of pending retry items.

func (*RetryClient) SearchMemory

func (rc *RetryClient) SearchMemory(ctx context.Context, req SearchRequest) ([]MemoryEntry, error)

SearchMemory proxies through to the inner client.

func (*RetryClient) StartRetryLoop

func (rc *RetryClient) StartRetryLoop(ctx context.Context)

StartRetryLoop drains the queue periodically until ctx is cancelled.

type SearchRequest

type SearchRequest struct {
	Query     string
	Limit     int
	Threshold float64
	Vector    []float32 // optional query embedding for hybrid search
	Hybrid    bool      // if true, request hybrid (keyword + vector) ranking
}

SearchRequest is the payload for SearchMemory.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL