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

> Discover the Time-To-Live TTL for company research cache entries in AI-Job-Search. Learn how long data stays fresh and when it's refreshed.

- Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search)
- Tags: internals
- Published: 2026-08-31

---

**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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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:

```python

# 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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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:

```python
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:

```python
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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/tests/test_company_research_cache.py).
- Cached data is stored as JSON files in the `company_research/` directory, guarded by [`tools/security_guards.py`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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`](https://github.com/MadsLorentzen/ai-job-search/blob/main/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.