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 ¶
- type AppendRequest
- type Client
- type Config
- type HTTPClient
- func (c *HTTPClient) AppendMemory(ctx context.Context, req AppendRequest) error
- func (c *HTTPClient) GetRecent(ctx context.Context, agentID string, limit int) ([]MemoryEntry, error)
- func (c *HTTPClient) Health(ctx context.Context) error
- func (c *HTTPClient) SearchMemory(ctx context.Context, req SearchRequest) ([]MemoryEntry, error)
- type MemoryEntry
- type RetryClient
- func (rc *RetryClient) AppendMemory(ctx context.Context, req AppendRequest) error
- func (rc *RetryClient) DrainQueue(ctx context.Context)
- func (rc *RetryClient) GetRecent(ctx context.Context, agentID string, limit int) ([]MemoryEntry, error)
- func (rc *RetryClient) Health(ctx context.Context) error
- func (rc *RetryClient) QueueLen() int
- func (rc *RetryClient) SearchMemory(ctx context.Context, req SearchRequest) ([]MemoryEntry, error)
- func (rc *RetryClient) StartRetryLoop(ctx context.Context)
- type SearchRequest
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.