What Is the Time-To-Live (TTL) for Company Research Cache Entries in AI-Job-Search?

The company research cache entries in the AI-Job-Search system have a Time-To-Live (TTL) of 30 days, after which cached JSON files are considered stale and refreshed on the next request.

The MadsLorentzen/ai-job-search repository implements a caching mechanism for company research data to balance data freshness with API efficiency. Understanding the TTL for these cache entries is critical for developers contributing to or debugging the system, as it determines how long research data remains valid before requiring regeneration.

Where the 30-Day TTL Is Defined

The 30-day TTL is explicitly validated in the project's test suite rather than being buried in configuration files. The test file tests/test_company_research_cache.py contains an assertion that verifies the cache description documentation includes this specific duration.

At line 68 of the test file, the code checks that the generated cache section contains the string "30", effectively enforcing the 30-day TTL as a contractual requirement:

# From tests/test_company_research_cache.py

# Validates that cache documentation states the 30-day retention policy

assert "30" in cache_description

This approach ensures that any changes to the TTL must be intentional and documented, as they would cause the test suite to fail.

Cache Storage Location

The cached company research data is stored as JSON files in the company_research/ directory. This location is explicitly guarded by the security configuration in tools/security_guards.py, which lists the cache directory pattern company_research/*.json as part of the system’s file access controls.

When the system generates or retrieves company research, it writes these .json files to the cache directory with timestamps that the TTL logic uses to determine validity.

Checking Cache Freshness Programmatically

You can implement cache freshness checking using the 30-day TTL constant. The following Python function determines whether a cached entry is still valid by comparing its modification time against the TTL threshold:

import json
import datetime
from pathlib import Path

CACHE_DIR = Path("company_research")
TTL_DAYS = 30

def is_fresh(cache_file: Path) -> bool:
    """Return True if the cache file is younger than the TTL."""
    if not cache_file.exists():
        return False
    mtime = datetime.datetime.fromtimestamp(cache_file.stat().st_mtime)
    age = datetime.datetime.now() - mtime
    return age < datetime.timedelta(days=TTL_DAYS)

# Usage example

for json_file in CACHE_DIR.glob("*.json"):
    status = 'fresh' if is_fresh(json_file) else 'stale'
    print(f"{json_file.name}: {status}")

This implementation compares the file’s st_mtime (modification timestamp) against the current time, returning False for any file older than 30 days.

Why 30 Days?

The 30-day TTL represents a design decision documented in the test suite that balances data accuracy with API rate limiting. Company research data—such as funding rounds, employee counts, and leadership changes—does not typically require real-time updates, making a monthly refresh cycle sufficient for most job-search automation use cases.

When generating cache documentation, the system produces markdown output similar to:

from some_module import generate_cache_section

cache_md = generate_cache_section()
print(cache_md)

# Output contains:

# **TTL:** 30 days

This self-documenting approach ensures that users and developers always have visibility into the cache retention policy.

Summary

• The TTL for company research cache entries is strictly 30 days as enforced by tests/test_company_research_cache.py.
• Cached data is stored as JSON files in the company_research/ directory, guarded by tools/security_guards.py.
• The 30-day threshold prevents excessive API calls while ensuring research data remains reasonably current.
• Cache freshness can be validated programmatically by comparing file modification times against the TTL_DAYS = 30 constant.

Frequently Asked Questions

How long does the AI-Job-Search system cache company research data?

The system caches company research data for 30 days. After this period, cached entries are considered stale and will be refreshed automatically on the next request that requires that specific company data.

Where is the cache TTL value enforced in the codebase?

The TTL value is enforced in tests/test_company_research_cache.py at line 68, where a test assertion verifies that the generated cache documentation contains the string "30". This ensures the 30-day policy cannot be changed accidentally without breaking the test suite.

What file format does the company research cache use?

The cache stores company research data as JSON files (*.json) in the company_research/ directory. These files contain structured research data and metadata, with filesystem timestamps used to calculate age against the 30-day TTL threshold.

Can I modify the TTL for my local installation?

While the source code likely defines TTL_DAYS = 30 as a constant that could be overridden, modifying this value would cause the test suite in tests/test_company_research_cache.py to fail. To implement a custom TTL sustainably, you would need to update both the implementation constant and the corresponding test assertion that validates the "30 days" documentation string.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}