memory

type AgentMemory struct {
	// ID is a unique identifier for this memory record
	ID types.AgentMemoryID

	// AgentID identifies which agent this memory belongs to (e.g., "bigquery")
	AgentID string

	// Query is the task query that led to this insight
	// Used for semantic search to find relevant memories
	Query string

	// QueryEmbedding is the vector embedding of Query for semantic search
	// Generated automatically by Memory Service when saving
	// Must use firestore.Vector32 type for Firestore vector search to work
	QueryEmbedding firestore.Vector32

	// Claim is a specific, self-contained insight learned from execution
	// MUST be understandable without knowing the original query or task context
	// Examples:
	// - "BigQuery table 'project.dataset.events' has field 'user_id' as INT64 type, not STRING - attempting to filter with email addresses like 'user@example.com' will cause type mismatch errors, use numeric IDs only"
	// - "Slack search requires both 'from:@username' AND 'in:#channel' syntax for filtering by user in specific channel - using only 'from:' searches all channels and may return irrelevant results"
	Claim string

	// Score represents the usefulness of this memory (-10.0 to +10.0)
	// - Positive: Helpful memory (higher is better)
	// - 0.0: Neutral or newly created (default)
	// - Negative: Harmful/misleading memory (lower is worse)
	// Updated using EMA (Exponential Moving Average) based on reflection feedback
	Score float64

	// CreatedAt records when this memory was first created
	CreatedAt time.Time

	// LastUsedAt records when this memory was last retrieved/used
	// Used for recency calculation and pruning decisions
	// Zero value indicates never used since creation
	LastUsedAt time.Time
}

type Reflection struct {
	// NewClaims contains newly discovered insights from the execution
	// Each claim MUST be self-contained and understandable without the original query context
	// Format: "[Specific context/entity] [What was discovered] - [Why it matters/What problem it solves]"
	// Examples:
	// - "BigQuery table 'project.dataset.events' has field 'user_id' as INT64 type, not STRING - attempting to filter with email addresses like 'user@example.com' will cause type mismatch errors, use numeric IDs only"
	// - "Slack search requires both 'from:@username' AND 'in:#channel' syntax for filtering by user in specific channel - using only 'from:' searches all channels and may return irrelevant results"
	NewClaims []string

	// HelpfulMemories lists memory IDs that were useful during execution
	// Memories listed here will receive positive score updates
	HelpfulMemories []types.AgentMemoryID

	// HarmfulMemories lists memory IDs that were misleading or incorrect
	// Memories listed here will receive negative score updates
	HarmfulMemories []types.AgentMemoryID
}