memory

type Client interface {
	// Retain hands one item to Hindsight for extraction. It returns once Hindsight has
	// accepted the work, not once the facts exist.
	Retain(ctx context.Context, item Item) error
	// Recall is the semantic search behind SearchMemories.
	Recall(ctx context.Context, query string, limit int) ([]Memory, error)
	// List is the newest-first page behind ListMemories. The cursor is opaque; an empty
	// one starts at the beginning and an empty return means there is no further page.
	List(ctx context.Context, cursor string, limit int) (items []Memory, next string, err error)
	// Forget excludes one memory from every future recall. Hindsight has no
	// single-memory delete: this is its curation tombstone, which keeps the row for audit
	// and is reversible from Hindsight's own API.
	Forget(ctx context.Context, id string) error
	// FailedOperations is the work Hindsight accepted and then could not finish. Retain
	// reports only that the work was taken, so without this a total extraction outage —
	// a rejected model key, a model that no longer exists — is invisible to Podium.
	FailedOperations(ctx context.Context, limit int) ([]Operation, error)
	// Ready reports whether Hindsight and its database are reachable.
	Ready(ctx context.Context) error
}

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

type Item struct {
	// Content is the text facts are extracted from. Required.
	Content string
	// Context is a sentence about where the content came from.
	Context string
	// Tags are recorded for a later scoping step and never filtered on here.
	Tags []string
	// Metadata is provenance. It survives verbatim onto every fact extracted from Content
	// and is what the UI's provenance chips read.
	Metadata map[string]string
	// DocumentID groups the facts and is the idempotency key: retaining the same
	// DocumentID again replaces what was there rather than adding a duplicate.
	DocumentID string
}

type Memory struct {
	ID   string
	Text string
	// FactType is world, experience or observation.
	FactType string
	Tags     []string
	Metadata map[string]string
	// Entities are the people, systems and concepts Hindsight linked the memory to.
	Entities []string
	// Context is the retaining caller's own note about where the memory came from.
	Context string
	// DocumentID is what the retainer grouped the memory under. The conductor sets it to
	// the turn id, so this is the provenance that cannot be edited away.
	DocumentID string
	// LearnedAt is Hindsight's mentioned_at: when the memory was learned. There is no
	// created_at on the wire; updated_at is the fallback.
	LearnedAt time.Time
}

type Operation struct {
	ID string
	// Type is Hindsight's task_type: retain, batch_retain, consolidation, and so on.
	Type string
	// Status is pending, processing, completed, failed or cancelled.
	Status string
	// DocumentID is what the retainer grouped the work under — the conductor's turn id, for
	// a retain it started. Empty on the maintenance tasks Hindsight schedules itself.
	DocumentID string
	// ErrorMessage is Hindsight's own words about why it gave up, after its retries.
	ErrorMessage string
	RetryCount   int
	UpdatedAt    time.Time
}

type Options struct {
	// BaseURL is Hindsight's base URL as this process reaches it. Required.
	BaseURL string
	// Bank is the memory bank. Required.
	Bank string
	// APIKey is the bearer. Required: Hindsight ships with no authentication, so a client
	// with no key is a client talking to something that should not exist.
	APIKey string
	// HTTPClient lets a test point at an httptest server. Nil means one with DefaultTimeout.
	HTTPClient *http.Client
}