Workspaces and Data

Workspaces and Data

This page explains where UACRAgent stores its files and how workspace behavior differs by interface.

Storage Model

UACRAgent keeps its generated data in app-managed locations and per-workspace bundles.

There are two levels:

• a shared app data directory
• per-workspace .uacragent bundles

Bootstrap Config

The fixed bootstrap location is:

• ~/.uacragent/config.json

This file stores the currently selected app data directory.

App Data Directory

By default, the app data directory is:

• ~/.uacragent/

The user can change it from the desktop app settings.

Important:

• changing the app data folder does not migrate old sessions automatically
• the new location takes effect after relaunch

Main App Data Contents

The app data directory contains shared files such as:

• index.json
• logs/
• models/
• sessions/
• cli_run/
• api_run/

Workspace Types

Desktop Auto-Created Sessions

Desktop sessions without a user-chosen workspace live under:

• <app_data_dir>/sessions/<workspace_id>/

CLI Runs

CLI workspaces live under:

• <app_data_dir>/cli_run/<workspace_id>/

API Runs

API workspaces live under:

• <app_data_dir>/api_run/<workspace_id>/

User-Chosen Desktop Workspace

If the desktop user chooses a custom workspace folder before the first Apply, that chosen folder becomes the session workspace.

Once committed, it is treated as fixed for the life of that session.

Per-Workspace Agent Bundle

Inside each workspace, UACRAgent stores its own files under:

• <workspace>/.uacragent/

This keeps app-generated files separate from user-owned files.

Typical Bundle Contents

Inside <workspace>/.uacragent/, you will typically see:

• session.json
• uploads/
• outputs/
• chroma_db/

What Goes Into uploads/

The app may copy source files into:

• <workspace>/.uacragent/uploads/<doc_type>/

This happens in flows where the system is configured to keep the workspace self-contained.

Examples:

• desktop Apply flow
• API with copy_to_workspace=true

The exam-info sheet is also copied into the workspace when used in the desktop app.

If that exam-info file is changed or cleared later, old copied exam-info files are cleaned up automatically.

What Goes Into outputs/

Generated files are stored under:

• <workspace>/.uacragent/outputs/

Examples:

• Markdown
• optional DOCX
• optional PDF

What Goes Into chroma_db/

The local retrieval index is stored under:

• <workspace>/.uacragent/chroma_db/

This is how the app reuses retrieval state between runs and session reopenings.

Model Cache

Shared local embedding models are stored under:

• <app_data_dir>/models/

For frozen standalone builds, the ONNX local embedding model is stored under:

• <app_data_dir>/models/chroma/onnx_models/

Current standalone-build note:

• only all-MiniLM-L6-v2 is supported for free local embeddings in the frozen build

Logs

Logs are written under:

• <app_data_dir>/logs/uacragent.log

Default behavior:

• log level is WARNING
• warnings, errors, and security events are captured
• routine operations are mostly silent
• API keys and message content are not written to the log

Deletion Behavior

When a desktop session is deleted:

• the app deletes the <workspace>/.uacragent/ bundle
• original source files outside that bundle are not touched

For auto-created desktop workspaces under sessions/:

• the parent workspace folder may also be removed if nothing else remains in it

Shared model caches under <app_data_dir>/models/ are not per-session and are not removed when a single session is deleted.

App Data Folder Changes

Changing the app data folder is best understood as:

• pointing the app at a new app home for future launches

It does not automatically migrate:

• old sessions
• old indexes
• old model caches
• old .env placement

Recommended practice:

• use a dedicated folder as the app data directory
• manually copy the old app data folder if you truly want to relocate everything

Related Pages

• Desktop Guide
• CLI Guide
• API Guide
• Privacy and Disclaimer
• Troubleshooting