In-Memory Artifact Service

Purpose

The In-Memory Artifact Service provides an ephemeral, memory-resident implementation of the artifact storage interface defined in the parent topic Artifact Management. This subtopic addresses the need for a lightweight, fast, and transient artifact store primarily used for testing, local development, and scenarios where persistence is unnecessary or undesirable.

Unlike persistent backends such as the Google Cloud Storage Service, the in-memory service facilitates rapid iteration and unit testing by avoiding external dependencies and disk I/O. It enables developers to validate artifact-related workflows within agents and tools without relying on a full cloud storage setup.

Functionality

The core functionality of the in-memory service revolves around storing, retrieving, listing, versioning, and deleting artifacts scoped by application, user, session, and filename. Artifacts are represented as genai.Part objects, which can encapsulate blobs or files.

Key Workflows and Methods

• Save: Stores an artifact with automatic version incrementing. If the artifact filename indicates a user-scoped namespace (prefix user:), it is stored under a shared user scope accessible across sessions.

• Load: Retrieves an artifact by app, user, session, filename, and optional version. If no version is specified, the latest version is returned.

• List: Enumerates artifact filenames available within a session and merges user-scoped artifacts, providing a unified view of accessible artifacts.

• Delete: Removes a specific artifact version or all versions if none specified. User-scoped artifacts are handled by adjusting the session identifier accordingly.

• Versions: Lists all version numbers available for a given artifact.

Internal Data Structures

Artifacts are keyed by a composite artifactKey consisting of:

• AppName

• UserID

• SessionID (or the special user-scoped key "user")

• FileName

• Version (stored in reverse order for scan efficiency)

The service uses an ordered map (omap.Map) to maintain sorted keys, enabling efficient range scans for listing and version retrieval.

Concurrency is managed by a read-write mutex (sync.RWMutex), ensuring thread-safe access for concurrent test scenarios.

Versioning and Namespace Handling

The service automatically manages artifact versioning by scanning for the latest existing version and incrementing it on each save operation. It also supports a user namespace for files prefixed with user:, allowing artifacts to be shared across sessions for the same user. This design supports scenarios where some artifacts are session-specific while others are user-global.

Example Method Snippet: Save Operation

func (s *inMemoryService) Save(ctx context.Context, req *SaveRequest) (*SaveResponse, error) {
    // Validate request
    // Adjust sessionID if user-scoped filename
    // Lock mutex for write
    // Determine next version by scanning existing artifacts
    // Store artifact in map with composite key
    // Return new version number
}

Integration

The in-memory service implements the artifact.Service interface used throughout the broader Artifact Management topic. It complements other implementations like the Google Cloud Storage Service by providing a no-dependency backend ideal for:

• Unit and integration testing pipelines (see artifact/inmemory_test.go).

• Local agent development and debugging.

• Transient workflows where artifacts do not require durable storage.

Agents and tools interacting with artifacts can remain agnostic to the underlying storage backend, enabling seamless switching between in-memory and cloud-based services during development and deployment.

This service is also leveraged indirectly by higher-level components such as session management (Session Management) and agent tooling (Tooling System) when configured to use in-memory artifact storage.

Diagram

classDiagram
class InMemoryService {
+Save(ctx, req) SaveResponse
+Load(ctx, req) LoadResponse
+Delete(ctx, req) error
+List(ctx, req) ListResponse
+Versions(ctx, req) VersionsResponse
}
class artifactKey {
-AppName: string
-UserID: string
-SessionID: string
-FileName: string
-Version: int64
+Encode() string
+Decode(key string) error
}
InMemoryService "1" --> "many" artifactKey : stores by
InMemoryService ..> omap.Map : uses internally
InMemoryService ..> sync.RWMutex : concurrency control

This class diagram illustrates the structure of the in-memory artifact service, highlighting its main methods and the composite key structure that uniquely identifies artifacts within the service. The concurrency control and ordered map usage facilitate efficient and safe artifact operations.