service.go

Overview

The service.go file defines the memory package, which provides key abstractions and data structures for interacting with agent memory—specifically long-term knowledge storage scoped to users. This package enables ingestion of user sessions and retrieval of relevant memory entries for subsequent user queries, supporting continuity and contextual awareness across user interactions.

The central component is the Service interface, which outlines methods for adding sessions into memory and searching memory entries based on query parameters. The file also defines data types representing search requests, search responses, and individual memory entries.

This package plays a foundational role in the system's memory management functionality, enabling agents to persist and recall user-specific information beyond a single session. It interfaces with session management (session.Session) and integrates with content representations from the genai package, facilitating large language model (LLM) interactions and context augmentation.

Package: memory

Service Interface

The Service interface encapsulates the memory service capabilities focused on storing and searching long-term memory entries.

type Service interface {
    AddSession(ctx context.Context, s session.Session) error
    Search(ctx context.Context, req *SearchRequest) (*SearchResponse, error)
}

Methods

• AddSession

  • Purpose: Adds a user session into the memory service to be stored for later retrieval.

  • Signature: AddSession(ctx context.Context, s session.Session) error

  • Parameters:

    • ctx context.Context: Context for cancellation, deadlines, and request-scoped values.

    • s session.Session: The session to add to the memory store. Sessions can be added multiple times during their lifetime.

  • Returns: An error if the addition fails; otherwise, nil.

  • Usage: Typically called when a new user session or update to an existing session occurs and should be persisted in memory.

• Search

  • Purpose: Searches the stored memory for entries relevant to the specified query.

  • Signature: Search(ctx context.Context, req *SearchRequest) (*SearchResponse, error)

  • Parameters:

    • ctx context.Context: Context for cancellation and timeout control.

    • req *SearchRequest: The search request containing query parameters.

  • Returns: A pointer to SearchResponse containing matched memory entries, or an error if the search fails. Returns an empty slice of entries if no matches are found.

  • Usage: Invoked when agents or users query the system for recalling past interactions or knowledge relevant to the current context.

Data Structures

SearchRequest

Represents the input parameters for a memory search operation.

type SearchRequest struct {
    Query   string
    UserID  string
    AppName string
}

• Fields:

  • Query (string): The textual query string to search for in memory.

  • UserID (string): Identifier to scope the search to a particular user.

  • AppName (string): Optional application name to further filter or contextualize the search.

• Usage: Used as input to the Search method of the Service interface to find relevant memory entries.

SearchResponse

Encapsulates the results returned from a memory search.

type SearchResponse struct {
    Memories []Entry
}

• Fields:

  • Memories ([]Entry): A slice of matching memory entries.

• Usage: Returned by the Search method to provide relevant memory entries matching the query.

Entry

Defines a single memory record stored in the system.

type Entry struct {
    Content   *genai.Content
    Author    string
    Timestamp time.Time
}

• Fields:

  • Content (*genai.Content): Main content of the memory, typically structured data compatible with the LLM integration.

  • Author (string): Identifier or name of the author who created the memory entry.

  • Timestamp (time.Time): The time when the original content occurred. This timestamp is forwarded to the LLM and should preferably be in ISO 8601 format.

• Usage: Each Entry represents a discrete piece of knowledge or interaction stored in memory and can be returned in search results.

Implementation Details and Algorithms

• The Service interface abstracts storage and retrieval without imposing a concrete implementation, allowing for different backends (e.g., in-memory, database, or cloud storage).

• Sessions are ingested into memory via AddSession. This likely involves extracting relevant events or state from the session.Session and converting them into storable Entry instances.

• The Search method accepts a SearchRequest that filters memories by user and app context, then performs a relevance-based retrieval of memory entries. While the file does not define the search algorithm, it is expected to involve text similarity or semantic search techniques, possibly leveraging LLM embeddings given the integration with genai.Content.

• The timestamp in Entry supports temporal reasoning in search queries or LLM prompts, allowing for time-aware memory retrieval.

Interaction with Other System Components

• Session Management (session.Session): Sessions are the primary input to the memory service. The Service ingests sessions to form long-term memory entries.

• LLM Integration (genai.Content): Memory entries store content in a format compatible with LLMs, facilitating seamless integration with language model-driven agents. This allows memory data to be embedded into prompts or instructions.

• This package supports user-scoped memory persistence, enabling agents to maintain continuity across multiple sessions, an essential aspect of agent lifecycle and invocation context management as outlined in related topics like Agent Invocation Context.

• The memory service is a key component underlying advanced agent workflows that require persistent knowledge, referenced in LLM Integration and Agents and potentially utilized by Agent Workflow Management for contextual decision-making.

Usage Examples

// Create a memory service instance (concrete implementation not defined here)
var memService memory.Service

// Add a session to memory
err := memService.AddSession(ctx, userSession)
if err != nil {
    // handle error
}

// Search memory for relevant entries
searchReq := &memory.SearchRequest{
    Query:   "What did I discuss yesterday?",
    UserID:  "user123",
    AppName: "chatbot",
}
resp, err := memService.Search(ctx, searchReq)
if err != nil {
    // handle error
}
// Process resp.Memories as needed

Diagram: Memory Service Structure

classDiagram
class Service {
+AddSession()
+Search()
}
class SearchRequest {
+Query
+UserID
+AppName
}
class SearchResponse {
+Memories
}
class Entry {
+Content
+Author
+Timestamp
}
Service ..> SearchRequest : uses
Service ..> SearchResponse : returns
SearchResponse "1" o-- "*" Entry : contains
Entry ..> genai.Content : contains
Service ..> session.Session : interacts with

This documentation references relevant system concepts such as session management (Session Management) and LLM content integration (LLM Integration and Agents) for deeper understanding of how memory service fits into the overall agent architecture.