Centralize Snapshots: Storage Fix & Query API Guide

Aug 8, 2025 by Rajiv Sharma 52 views

Fix Snapshot Storage & Add Query API for Better Trace Viewing

Hey guys! Today, we're diving into some improvements for snapshot storage and adding a nifty query API to make trace viewing a whole lot easier. Let's get started!

The Problem: Scattered Snapshots and Missing Queries

Currently, the snapshot.storageDirectory defaults to the current working directory (server.getCurrentWorkspace()) if you don't explicitly configure it. This leads to a few headaches:

Redundant files in project directories: Imagine snapshots popping up all over your project folders – not the cleanest setup, right?
Poor organization: Snapshots scattered across different projects make it tough to find what you need.
Missing query capability: The frontend can't query snapshots by sessionId for trace viewing, which is a bummer when you're trying to debug.

Diving into the Current Implementation

In multimodal/tarko/agent-server/src/core/AgentSession.ts, lines 78-79 show the current setup:

const snapshotStoragesDirectory =
  agentOptions.snapshot.storageDirectory ?? server.getCurrentWorkspace();

This means if you don't specify a storage directory, it defaults to where you're currently working. Let's fix that!

The Proposed Solution: Centralized Storage and a Query API

So, what's the plan? We're going to centralize snapshot storage and add an API to make querying snapshots a breeze. Here’s the breakdown:

1. Fix Default Storage Directory

Instead of dumping snapshots in the current working directory, we'll use ~/.tarko/snapshots as the default. This keeps things tidy and in one place.

const snapshotStoragesDirectory =
  agentOptions.snapshot.storageDirectory ?? path.join(os.homedir(), '.tarko', 'snapshots');

By fixing the default storage directory, we ensure that all snapshots are stored in a centralized location, ~/.tarko/snapshots, rather than being scattered across various project directories. This centralized approach significantly improves organization and makes it easier to manage and locate snapshot files. The current implementation, which defaults to the current working directory, can lead to redundant files and clutter, making it challenging to maintain a clean project structure. Centralizing the storage directory not only simplifies file management but also enhances the overall development workflow by reducing the time spent searching for specific snapshot files. Moreover, a consistent storage location is crucial for automation and scripting tasks that rely on predictable file paths. This enhancement is a key step in improving the usability and maintainability of the snapshot feature. The implementation ensures that users who do not explicitly configure a storage directory still benefit from a well-organized snapshot system. This change is particularly beneficial for developers working on multiple projects simultaneously, as it prevents snapshot files from mixing and causing confusion. By providing a default storage directory, we streamline the snapshot process and make it more intuitive for all users.

2. Add Snapshot Query API

Next up, we're adding some API endpoints to support frontend snapshot queries. This means you can easily fetch snapshots by sessionId and trace data.

GET /api/snapshots - List all available snapshots
GET /api/snapshots/:sessionId - Get a specific snapshot by sessionId
GET /api/snapshots/:sessionId/trace - Get trace data for a specific session

Implementing a robust Snapshot Query API is essential for providing developers with the tools they need to effectively manage and analyze snapshots. The API endpoints, such as GET /api/snapshots, GET /api/snapshots/:sessionId, and GET /api/snapshots/:sessionId/trace, allow for flexible querying and retrieval of snapshot data. This functionality is particularly crucial for debugging and performance analysis, as it enables users to quickly access and examine the state of their application at specific points in time. The GET /api/snapshots endpoint offers a comprehensive list of all available snapshots, making it easy to browse and identify relevant data. The GET /api/snapshots/:sessionId endpoint allows users to retrieve specific snapshots based on their session ID, facilitating targeted investigations. Most importantly, the GET /api/snapshots/:sessionId/trace endpoint provides access to trace data for a given session, which is invaluable for understanding the execution flow and identifying potential bottlenecks. By adding these API endpoints, we significantly enhance the usability of the snapshot feature, making it easier for developers to integrate snapshots into their workflows. The Snapshot Query API also supports the development of more sophisticated tooling and dashboards for monitoring and managing application behavior. This level of detail is critical for maintaining high-quality software and ensuring optimal performance. The API's flexibility allows for a wide range of use cases, from simple debugging tasks to complex performance tuning scenarios. By providing a clear and accessible interface for querying snapshots, we empower developers to take full advantage of this powerful feature.

3. Update Configuration Interface

We need to make sure the AgentServerSnapshotOptions interface is up-to-date with the new default. This means documenting that ~/.tarko/snapshots is the default storage directory if nothing else is specified.

export interface AgentServerSnapshotOptions {
  /**
   * Whether to enable snapshots for agent sessions
   * @default false
   */
  enable: boolean;

  /**
   * Directory to store agent snapshots
   * @default "~/.tarko/snapshots"
   * If not specified, snapshots will be stored in ~/.tarko/snapshots
   */
  storageDirectory?: string;
}

Updating the Configuration Interface is vital for ensuring that developers have clear and accurate information about how to configure snapshot storage. The AgentServerSnapshotOptions interface should explicitly document the new default storage directory as ~/.tarko/snapshots. This clarity helps developers understand the system's behavior and configure it according to their needs. The interface should also include detailed descriptions of all available options, such as the enable flag and the storageDirectory property. Accurate documentation prevents confusion and reduces the likelihood of misconfiguration, which can lead to unexpected behavior or data loss. By providing a well-documented Configuration Interface, we empower developers to make informed decisions about how they use snapshots in their projects. The interface should also highlight the benefits of using the default storage directory, such as improved organization and easier access to snapshot files. Clear and concise documentation is a key component of a user-friendly system, and it plays a crucial role in the adoption and effective use of the snapshot feature. The updated Configuration Interface will also include examples and best practices for configuring snapshots in different environments, further enhancing its value to developers. By focusing on usability and clarity, we ensure that the configuration process is as smooth and straightforward as possible.

The Benefits: Cleaner, Organized, and Queryable Snapshots

So, what do we gain from all this? Let's break it down:

Centralized snapshot storage in ~/.tarko/snapshots – Say goodbye to scattered files!
Cleaner project directories without snapshot files – Keep your projects tidy.
Frontend can query and display traces by sessionId – Easier debugging and trace viewing.
Better organization and management of agent execution history – Know exactly where to find your snapshots.

By centralizing snapshot storage in ~/.tarko/snapshots, we eliminate the clutter of snapshot files in project directories, resulting in a cleaner and more organized development environment. This improved organization makes it easier for developers to locate and manage snapshot files, saving time and reducing frustration. Cleaner project directories also enhance collaboration, as team members can easily understand the project structure without being distracted by extraneous files. The centralized storage approach also simplifies backup and recovery processes, as all snapshot data is located in a single, predictable location. This is particularly important in production environments, where data integrity is paramount. Moreover, a centralized storage system enables the implementation of automated snapshot management tools and scripts, further streamlining the development workflow. By reducing the cognitive load associated with managing snapshot files, developers can focus on writing code and solving problems. The benefits of centralized storage extend beyond individual developers to the entire organization, fostering a more efficient and productive development culture. This enhancement is a critical step towards making snapshots a more valuable and user-friendly feature.

With the frontend now able to query and display traces by sessionId, debugging and trace viewing become significantly easier and more efficient. This enhanced query capability allows developers to quickly retrieve snapshots associated with specific sessions, providing a targeted view of application behavior. The ability to view traces by sessionId is invaluable for identifying the root causes of issues and understanding complex interactions within the system. The improved query functionality also supports the development of more sophisticated debugging tools and dashboards, enabling developers to visualize and analyze trace data in new ways. This level of insight is essential for optimizing application performance and ensuring high-quality user experiences. By making trace data more accessible and manageable, we empower developers to resolve issues faster and more effectively. The query API also opens up new possibilities for monitoring and auditing application behavior, providing a comprehensive view of system activity. This is particularly important in regulated industries, where compliance requirements demand detailed audit trails. The improved trace viewing capabilities contribute to a more robust and reliable software development process, ultimately benefiting both developers and end-users.

Overall, these changes lead to better organization and management of agent execution history, providing a more streamlined and efficient development workflow. The combination of centralized snapshot storage and enhanced query capabilities transforms snapshots from a potentially messy byproduct into a valuable tool for debugging, performance analysis, and auditing. By making it easier to store, locate, and analyze snapshots, we empower developers to take full advantage of this powerful feature. The improved organization reduces the risk of accidentally deleting or overwriting important snapshot data, ensuring that critical information is always available when needed. The ability to quickly access and analyze agent execution history provides valuable insights into application behavior, enabling developers to make informed decisions about optimization and refactoring. This holistic approach to snapshot management contributes to a more productive and satisfying development experience. By focusing on both storage and query aspects, we create a comprehensive solution that addresses the needs of developers at all stages of the software development lifecycle. The result is a more robust, reliable, and user-friendly snapshot system that enhances the overall quality of the software development process.

Conclusion

And that's the scoop! By fixing the default storage directory, adding a query API, and updating the configuration interface, we're making snapshots way more useful and user-friendly. Happy coding, guys!