Let’s Talk
Help Desktop app Local Cache (MCP read tool cache)

Local Cache (MCP read tool cache)

Updated July 7, 2026

What Local Cache is, how the Overview metrics work, and when cached MCP read results refresh.

Local Cache is an in memory cache inside Singla AIOS Desktop. It stores recent MCP read tool responses so your AI client does not repeat the same expensive lookups: searching mail, listing calendar events, querying CRM records, and similar read operations.

This article explains what Local Cache is, what the Overview metrics mean, and how caching interacts with the integrations on your machine.

Local Cache is not a separate server

Local Cache lives entirely in the desktop app's memory on your computer. It is:

  • Not a cloud service
  • Not in a database you install separately
  • Not the same thing as Local Storage that holds synced mail, calendar events, contacts, and activity history

When you quit AIOS Desktop or restart your machine, the in memory cache is cleared. Local Storage persists across restarts.

Why it exists

MCP clients (Cursor, Claude Desktop, ChatGPT connectors, and others) often call the same read tools repeatedly during a session. For example mail_search, cal_search, or contact_search with identical arguments.

Without caching, every call:

  • Re-reads from local storage or external APIs
  • Returns a full JSON payload to the AI model
  • Consumes tokens in the model context window

Local Cache keeps a short lived copy of qualifying read responses so identical calls within the TTL window are answered faster with lower token cost.

Where to find it in the app

Location What you see
Overview The Local Cache KPI card: Memory, Entries, Hit Rate, Tokens Saved
Services Local Cache status plus the MCP Tool Cache toggle
Settings → Cache Enable or disable MCP Tool Cache

What the KPI metrics mean

The Overview card shows four numbers. A blank value usually means the cache is empty, disabled, or has not recorded activity yet.

Memory

Approximate RAM used by cached tool responses (serialized JSON in memory). This is typically small, from kilobytes to a few megabytes, and capped internally (about 512 tool result entries).

Entries

Number of cached items currently held. Each entry is one MCP read tool result keyed by integration + tool name + arguments (for example a calendar search with a specific query and date range).

Hit Rate

Percentage of cache lookups that found a match: hits / (hits + misses). A rising hit rate during a long AI session is normal. It means repeated reads are being served from cache instead of re-running the tool.

Tokens Saved

Estimated tokens not sent to the model because a cached response was reused. This is approximate (based on cached payload size). Use it to see whether caching is materially reducing context usage during a session.

How MCP Tool Cache works

  1. An MCP client calls a registered read tool (for example mail_read, cal_search, contact_search).
  2. AIOS checks whether MCP Tool Cache is enabled and whether this tool and arguments qualify.
  3. If a fresh cached entry exists, the desktop returns it immediately. The JSON includes cache_hit: true.
  4. Otherwise the tool runs normally, the result is stored with a TTL, and the response includes cache_hit: false.

What is cached

Only read tools registered for token efficient caching. Examples:

  • Mail: mail_search, mail_read, mail_folders
  • Calendar: cal_search, cal_today, cal_upcoming, cal_read
  • Contacts: contact_search, contact_read
  • CRM, DNS, Google Drive, and other configured read tools

Default TTL varies by integration (freshness vs token savings):

Integration Typical TTL
Calendar ~45 seconds
Mail ~2 minutes
Contacts ~10 minutes
Zoho CRM ~5 minutes
Some plugin read tools Not cached

Individual tools may override these defaults.

What is never cached

  • Write tools: create, update, delete, send, deploy, sync, and similar
  • Calls with force_refresh: true or dry_run: true
  • Unregistered tools
  • Failed responses

When entries are cleared

Entries expire when their TTL elapses. They are also removed when:

  • A write tool runs for the same integration (sending mail clears mail read cache)
  • Calendar create, update, or delete runs. Calendar MCP reads are suppressed for several minutes after a write.
  • You clear Local Cache in Services (or POST /ops/local-cache/clear)
  • You restart AIOS Desktop

Working with AI agents

If an agent shows data that looks slightly out of date after you changed mail, calendar, or CRM:

  1. Confirm the write tool succeeded.
  2. Repeat the read with force_refresh: true to bypass Local Cache for that call.
  3. For calendar, use force_sync: true on cal_create, cal_update, or cal_delete to run an immediate sync after the write.

Local Cache vs Local Storage

Local Cache Local Storage
Medium In memory on your PC File on disk
Survives restart No Yes
Purpose Faster repeated MCP reads; fewer tokens Synced mail/calendar/contacts; activity history
Overview KPIs Memory, Entries, Hit Rate, Tokens Saved Database size and table counts

Mail and calendar tools often read from Local Storage, not live servers on every call. There are two freshness layers: the synced local copy and the MCP read cache on top. Writes invalidate the MCP cache; background sync keeps Local Storage updated.

Enabling and disabling

MCP Tool Cache is on by default. To turn it off, open Settings → Cache and disable the toggle.

When disabled, every MCP read runs fresh. Token usage may increase; Overview metrics may show blank values until you re-enable caching.

Troubleshooting

Metrics stay blank. Cache may be idle, disabled, or entries expired. Run a few repeated read queries from your MCP client and refresh Overview.

Stale mail or calendar in an agent. Use force_refresh: true on the read tool. After calendar writes use force_sync: true or clear Local Cache from Services.

Everything reset after restart. Expected. In memory cache clears on quit; counters start over.

Related articles