memory

type Episode ¶

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"`
}

Episode records a single subgoal-level experience for episodic memory. Each episode stores the goal, the full text trajectory, and the termination status. This granularity enables targeted in-context example retrieval per the paper.

func (ep Episode) String() string

type EpisodeConsolidator ¶

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

EpisodeConsolidator reads recent raw episodes, groups them, summarizes them into wisdom notes, and stores the results. It is designed to be called periodically (e.g., daily via cron or on startup).

func NewEpisodeConsolidator(cfg EpisodeConsolidatorConfig) *EpisodeConsolidator

func (c *EpisodeConsolidator) Consolidate(ctx context.Context) int

type EpisodeConsolidatorConfig ¶

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
}

EpisodeConsolidatorConfig holds dependencies for creating a consolidator.

type EpisodeStatus ¶

type EpisodeStatus string

EpisodeStatus records how an agent node terminated.

const (
	// EpisodeSuccess means the agent completed its subgoal.
	EpisodeSuccess EpisodeStatus = "success"
	// EpisodeFailure means the agent failed its subgoal.
	EpisodeFailure EpisodeStatus = "failure"
	// EpisodeExpand means the agent decomposed into sub-tasks.
	EpisodeExpand EpisodeStatus = "expand"
	// EpisodePending means the episode is awaiting human validation.
	// Episodes are initially stored as pending until a user reacts
	// (e.g. 👍 upgrades to success, 👎 downgrades to failure).
	EpisodePending EpisodeStatus = "pending"
)

type EpisodeSummarizer ¶

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
}

EpisodeSummarizer generates a consolidated summary from a batch of episodes. The interface is defined in the memory package to avoid import cycles; the LLM-backed implementation lives in the reactree package.

type Episodes ¶

type Episodes []Episode

Episodes is a domain type wrapping a slice of Episode. It provides behavior for summarizing, classifying, and formatting episodes for prompt injection — keeping that logic close to the data it operates on.

func (eps Episodes) HasFailures() bool

func (eps Episodes) HasSuccesses() bool

func (eps Episodes) Header() string

func (eps Episodes) Summarize() string

type EpisodicMemory ¶

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
}

EpisodicMemory stores and retrieves past subgoal-level experiences. Implementations can use embedding similarity (e.g., Sentence-BERT) to find the most relevant past experiences for a given goal.

func NewNoOpEpisodicMemory() EpisodicMemory

type EpisodicMemoryConfig ¶

type EpisodicMemoryConfig struct {
	// Service is the trpc-agent-go memory.Service backend.
	Service memory.Service

	// AppName identifies the application for memory scoping.
	AppName string

	// UserID identifies the user/session for memory scoping.
	UserID string
}

EpisodicMemoryConfig holds configuration for creating a memory.Service-backed EpisodicMemory implementation.

func DefaultEpisodicMemoryConfig() EpisodicMemoryConfig

func (cfg EpisodicMemoryConfig) NewEpisodicMemory() EpisodicMemory

func (cfg EpisodicMemoryConfig) WithUserID(userID string) EpisodicMemoryConfig

type FailureReflectionRequest ¶

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
}

FailureReflectionRequest holds the inputs for generating a failure reflection.

type FailureReflector ¶

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
}

FailureReflector generates verbal reflections on agent failures. Instead of storing raw error text (which is nearly useless for future context), it asks a cheap LLM to summarize what went wrong and what the agent should try differently next time.

This is inspired by the Reflexion paper (Shinn et al., 2023) which showed that verbal reinforcement — storing reflections rather than raw trajectories — significantly improves agent self-correction.

The interface is defined here (memory package) to avoid import cycles; the LLM-backed implementation lives in the reactree package.

func NewNoOpFailureReflector() FailureReflector

type ImportanceScorer ¶

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
}

ImportanceScorer assigns a 1-10 importance score to an episode. Higher scores indicate novel, critical, or reusable lessons. Lower scores indicate routine or trivial experiences.

The interface lives here (memory package) to avoid import cycles; the LLM-backed implementation lives in the reactree package.

func NewNoOpImportanceScorer() ImportanceScorer

type ImportanceScoringRequest ¶

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
}

ImportanceScoringRequest holds the inputs for scoring an episode's importance.

type PlanAdvisor ¶

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
}

PlanAdvisor consults past experiences (episodic memory and wisdom) to generate advisory context for plan steps BEFORE they execute. This closes the gap where plan decomposition was "blind" to past outcomes — the LLM now sees relevant successes, failures, and lessons when executing each step of a multi-step plan.

The interface is defined here (memory package) to avoid import cycles; the wiring happens in the reactree package.

func NewNoOpPlanAdvisor() PlanAdvisor

func NewPlanAdvisor(

	episodic EpisodicMemory,

	wisdom WisdomStore) PlanAdvisor

type PlanAdvisoryRequest ¶

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
}

PlanAdvisoryRequest holds the inputs for generating plan-level advisory.

type PlanAdvisoryResult ¶

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

PlanAdvisoryResult holds the advisory output for all plan steps.

func (r PlanAdvisoryResult) ForStep(stepName string) string

func (r PlanAdvisoryResult) StepsAdvised() int

type ReactionContext ¶

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"`
}

ReactionContext captures the agent's goal and output when a message was sent, so that a later emoji reaction can be correlated back to the episode. Without this correlation, reactions would be meaningless because we wouldn't know which goal/output the user is approving.

type ReactionHandler ¶

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

ReactionHandler processes incoming emoji reactions and converts them into episodic memory entries. This is the core of the "giving the LLM a cookie" mechanism: positive reactions store the episode as validated success, negative reactions store it as failure.

Without this handler, the system would rely solely on heuristic-based episode storage (looksLikeError), which is susceptible to memory poisoning from graceful LLM failures.

func NewReactionHandler(cfg ReactionHandlerConfig) *ReactionHandler

func (h *ReactionHandler) HandleReaction(ctx context.Context, msg messenger.IncomingMessage)

type ReactionHandlerConfig ¶

type ReactionHandlerConfig struct {
	Ledger   *ReactionLedger
	Episodic EpisodicMemory
}

ReactionHandlerConfig holds the dependencies needed to create a ReactionHandler.

type ReactionLedger ¶

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

ReactionLedger is a DB-backed ledger that maps sent message IDs to the agent context that produced them. The send_message tool records entries; the reaction handler looks them up.

Without this ledger, incoming reactions (which only carry the reacted message ID) cannot be correlated to the agent's goal and output.

Backed by the generic short_memories table (memory_type = "reaction_ledger").

func NewReactionLedger(store *db.ShortMemoryStore) *ReactionLedger

func (l *ReactionLedger) Lookup(ctx context.Context, messageID string) (ReactionContext, bool)

func (l *ReactionLedger) Record(ctx context.Context, messageID string, goal, output, senderKey string)

type StepAdvisory ¶

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
}

StepAdvisory holds the advisory context for a single plan step.

func (sa StepAdvisory) Format() string

type WisdomNote ¶

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"`
}

WisdomNote is a concise, distilled summary of raw episodes from a time period (e.g., one day). Instead of injecting 20 raw episodes into a prompt, the consolidator batches them into 1-2 wisdom notes that capture the essential lessons.

Format:

"On <date>, you learned:
 - <lesson 1>
 - <lesson 2>
 ..."

type WisdomStore ¶

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
}

WisdomStore stores and retrieves consolidated wisdom notes. It uses the same memory.Service backend as episodic memory.

func NewNoOpWisdomStore() WisdomStore

type WisdomStoreConfig ¶

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

WisdomStoreConfig holds configuration for creating a WisdomStore.

func (cfg WisdomStoreConfig) NewWisdomStore() WisdomStore

type WorkingMemory ¶

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

WorkingMemory is a thread-safe key-value store shared across all agent nodes in a single ReAcTree run. It enables agents to share environment-specific observations (e.g., discovered file content, resource locations) without re-exploring the environment. Without this, each agent node would operate in isolation, potentially duplicating costly exploration actions.

func NewWorkingMemory() *WorkingMemory

func (m *WorkingMemory) Clear()

func (m *WorkingMemory) Keys() []string

func (m *WorkingMemory) Recall(key string) (string, bool)

func (m *WorkingMemory) Snapshot() map[string]string

func (m *WorkingMemory) Store(key, value string)