memory

type Episode struct {
	Goal       string        `json:"goal"`
	Trajectory string        `json:"trajectory"`
	Status     EpisodeStatus `json:"status"`

	// Reflection is a verbal summary of why the episode succeeded or failed.
	// For failures, this is generated by the FailureReflector. For successes,
	// this is typically empty (the trajectory serves as the reference).
	Reflection string `json:"reflection,omitempty"`

	// Importance is an LLM-assigned 1-10 score indicating how significant
	// this experience is. Higher scores indicate novel or critical lessons.
	// Zero means no importance was assigned (backward-compatible default).
	Importance int `json:"importance,omitempty"`

	// CreatedAt records when the episode was stored. Used for recency-weighted
	// retrieval: newer episodes receive higher scores via exponential decay.
	CreatedAt time.Time `json:"created_at"`

	// SenderID is the raw sender identity (e.g. Slack user ID) that generated
	// this episode. Stored as vector metadata so ForgetUser can find and delete
	// a user's episodes across all visibility scopes. Must be set per-Store call;
	// do not carry it from an instance field to avoid stale values in group channels
	// where one EpisodicMemory instance serves multiple senders.
	SenderID string `json:"sender_id,omitempty"`
}

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

type EpisodeConsolidatorConfig struct {
	// Episodic is the source of raw episodes to consolidate.
	Episodic EpisodicMemory

	// Wisdom is the destination for consolidated wisdom notes.
	Wisdom WisdomStore

	// Summarizer generates the consolidated summary text.
	Summarizer EpisodeSummarizer

	// LookbackHours is how far back to look for episodes (default: 24).
	LookbackHours int
}

type EpisodeStatus string

type EpisodeSummarizer interface {
	// Summarize takes a batch of episodes and produces a concise wisdom summary.
	// Returns the summary text, or empty string if summarization fails.
	Summarize(ctx context.Context, episodes []Episode) string
}

type Episodes []Episode

type EpisodicMemory interface {
	// Store saves a completed episode into the memory.
	Store(ctx context.Context, episode Episode)

	// Retrieve finds the top-k most similar episodes for the given goal.
	Retrieve(ctx context.Context, goal string, k int) []Episode

	// RetrieveWeighted finds episodes for the given goal and ranks them
	// using a weighted score combining recency (exponential decay) and
	// importance. Returns the top-k highest-scoring episodes.
	RetrieveWeighted(ctx context.Context, goal string, k int) []Episode
}

type EpisodicMemoryConfig struct {
	// Service is the trpc-agent-go memory.Service backend (keyword path).
	Service memory.Service

	// VectorStore is the vector store backend. When non-nil, episodic memory
	// is backed by vector search instead of the keyword-based Service.
	VectorStore vector.IStore

	// AppName identifies the application for memory scoping (keyword path).
	AppName string

	// UserID is the visibility-scoped identity used for retrieval isolation
	// (e.g. "private:alice" or "group:C123" from DeriveVisibility()).
	// It determines which episodes are visible in a given context.
	UserID string
}

type FailureReflectionRequest struct {
	// Goal is the task the agent was trying to accomplish.
	Goal string
	// ErrorOutput is the error text or failed output from the agent.
	ErrorOutput string
}

type FailureReflector interface {
	// Reflect generates a 2-3 sentence reflection on why a task failed
	// and what the agent should try differently. Returns the reflection
	// text, or empty string if reflection is unavailable.
	Reflect(ctx context.Context, req FailureReflectionRequest) string
}

type ImportanceScorer interface {
	// Score returns a 1-10 importance score for the given episode.
	// Returns 0 if scoring is unavailable (best-effort).
	Score(ctx context.Context, req ImportanceScoringRequest) int
}

type ImportanceScoringRequest struct {
	// Goal is the task the agent was attempting.
	Goal string
	// Output is the trajectory or reflection text.
	Output string
	// Status is the episode outcome (success, failure, etc.)
	Status EpisodeStatus
}

type PlanAdvisor interface {
	// Advise queries past experiences for each step goal and returns
	// advisory context to inject into each step.
	Advise(ctx context.Context, req PlanAdvisoryRequest) PlanAdvisoryResult
}

type PlanAdvisoryRequest struct {
	// OverallGoal is the parent task's goal — used to retrieve
	// high-level wisdom notes.
	OverallGoal string

	// StepGoals maps step name → step goal text. Each step goal
	// is used to query episodic memory for relevant past experiences.
	StepGoals map[string]string
}

type PlanAdvisoryResult struct {
	// Advisories maps step name → StepAdvisory.
	Advisories map[string]StepAdvisory
}

type ReactionContext struct {
	// Goal is the agent's goal when the message was sent.
	Goal string `json:"goal"`
	// Output is the agent's output text (truncated for storage).
	Output string `json:"output"`
	// SenderKey identifies the user/channel ("platform:senderID:channelID").
	SenderKey string `json:"sender_key"`
}

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

type ReactionHandlerConfig struct {
	Ledger   *ReactionLedger
	Episodic EpisodicMemory
}

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

type StepAdvisory struct {
	// StepName identifies which plan step this advisory is for.
	StepName string

	// Episodes are the relevant past experiences for this step.
	Episodes Episodes

	// WisdomSection is the formatted wisdom notes (shared across steps).
	WisdomSection string
}

type WisdomNote struct {
	// Summary is the consolidated text from multiple episodes.
	Summary string `json:"summary"`

	// Period is the time range this note covers (e.g., "2026-03-10").
	Period string `json:"period"`

	// EpisodeCount is how many raw episodes were distilled into this note.
	EpisodeCount int `json:"episode_count"`

	// CreatedAt is when this wisdom note was generated.
	CreatedAt time.Time `json:"created_at"`
}

type WisdomStore interface {
	// StoreWisdom saves a consolidated wisdom note.
	StoreWisdom(ctx context.Context, note WisdomNote)

	// RetrieveWisdom returns the most recent wisdom notes (up to limit).
	RetrieveWisdom(ctx context.Context, limit int) []WisdomNote
}

type WisdomStoreConfig struct {
	Service memoryService.Service
	AppName string
	UserID  string
}

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