# Understanding the Tiered Test Loop for ai-memory Development

> Discover the tiered test loop in ai-memory development for fast feedback and production-grade reliability. Learn how cargo t and cargo tf ensure code quality.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: deep-dive
- Published: 2026-09-11

---

**The ai-memory project employs a two-tiered test loop that separates rapid everyday validation (`cargo t`) from exhaustive pre-merge checks (`cargo tf`), enabling fast feedback while ensuring production-grade reliability.**

The `akitaonrails/ai-memory` repository is a Rust-based memory management system for AI applications that optimizes developer velocity through a sophisticated **tiered test loop** strategy. This approach categorizes tests by execution characteristics, allowing developers to iterate quickly during local development while enforcing comprehensive validation through automated gates before any code reaches the main branch.

## The Two-Tier Architecture

The testing strategy divides the suite into distinct tiers based on execution speed and resource requirements. This separation is enforced through module naming conventions and nextest profile configurations documented in the repository's build instructions.

### Everyday Fast Loop

The **everyday loop** targets sub-20-second feedback cycles for active development. This tier executes only unit tests that lack `slow` or `stress` path prefixes, using the nextest runner for parallel execution and fast compilation.

```bash

# Run the everyday fast loop (default nextest profile)

cargo t

# Equivalent explicit command

cargo nextest run

```

According to the repository documentation in [`README.md`](https://github.com/akitaonrails/ai-memory/blob/main/README.md) (lines 93-123), this loop represents the standard development workflow, providing immediate feedback on logic correctness without the overhead of integration or performance tests.

### Full Tier (Slow and Stress Tests)

The **full tier** encompasses the entire test suite, including integration tests, end-to-end workflows, and stress benchmarks. Tests belong to this tier when their module path contains a segment beginning with `slow` or `stress`, such as `tests::slow_integration` or `stress::concurrent_memory_pressure`.

```bash

# Execute the full tier including all slow/stress tests

cargo tf

# Run only slow-tier tests explicitly

cargo nextest run -E 'test(slow)'

```

This tier serves as the quality gate enforced by CI pipelines before merging pull requests.

## Test Classification Rules

The tier assignment relies on strict naming conventions within the source tree. Any test residing in a module whose path starts with `slow` or `stress` is automatically excluded from the everyday loop.

Key implementation details include:

- **Module Path Matching**: Tests in `crate::slow_database::connection_pool` or `crate::stress::memory_leak_detection` run exclusively under `cargo tf`
- **File System Patterns**: Physical test files named `slow_*.rs` or located in `tests/slow/` directories map to the slow tier
- **Example Location**: [`crates/ai-memory-store/tests/slow_integration.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/tests/slow_integration.rs) contains database integration tests that require external services

## Running the Test Loops Locally

Developers interact with the system through Cargo aliases defined in the workspace configuration. The following examples demonstrate the standard workflow:

```bash

# 1. Local development - fast feedback loop

cargo t

# 2. Pre-commit validation - includes slow tests

cargo tf

# 3. Continuous integration simulation

cargo nextest run --profile ci

# 4. Debugging a specific slow test

cargo nextest run --test-threads 1 slow_persistence_recovery

```

The `cargo tf` command expands to a nextest invocation using the full profile, which overrides the default test exclusions and executes every discovered test in the workspace.

## CI/CD Integration and Quality Gates

The repository enforces the full tier through GitHub Actions workflows defined in [`.github/workflows/ci.yml`](https://github.com/akitaonrails/ai-memory/blob/main/.github/workflows/ci.yml). These pipelines execute `cargo tf` on every pull request, ensuring that slow and stress tests pass before code merges.

The workflow typically follows this pattern:

1. **Fast check**: Run `cargo check` and `cargo clippy` for immediate linting
2. **Everyday tier**: Execute `cargo t` to catch logic errors quickly
3. **Full tier gate**: Run `cargo tf` to validate integration and performance
4. **Binary release**: Only proceed if the full tier succeeds

## Key Files and Configuration

| File | Purpose | Relevant Content |
|------|---------|------------------|
| [`README.md`](https://github.com/akitaonrails/ai-memory/blob/main/README.md) | Documents the tiered test strategy | Lines 93-123 describe the everyday loop and full tier commands |
| [`Cargo.toml`](https://github.com/akitaonrails/ai-memory/blob/main/Cargo.toml) | Workspace configuration | Defines `cargo t` and `cargo tf` aliases via `[alias]` sections |
| [`.github/workflows/ci.yml`](https://github.com/akitaonrails/ai-memory/blob/main/.github/workflows/ci.yml) | CI enforcement | Executes full tier on pull requests and pushes to main |
| `crates/*/tests/slow_*.rs` | Slow tier test modules | Integration and stress tests excluded from fast loop |

## Summary

- **Two-tier system**: The everyday loop (`cargo t`) provides rapid feedback during development, while the full tier (`cargo tf`) guarantees comprehensive coverage before merging.
- **Naming convention**: Tests in modules prefixed with `slow` or `stress` automatically belong to the full tier only.
- **Local efficiency**: Developers can iterate in ~20 seconds using the fast loop without waiting for resource-intensive tests.
- **CI enforcement**: GitHub Actions runs the full tier on every pull request, preventing regressions in integration or performance boundaries.

## Frequently Asked Questions

### What is the difference between `cargo t` and `cargo tf` in ai-memory?

`cargo t` runs the **everyday fast loop**, executing only quick unit tests that complete in seconds and have no `slow` or `stress` prefix in their module path. `cargo tf` runs the **full tier**, which includes all tests regardless of naming conventions, specifically targeting integration tests and stress benchmarks that may take minutes to complete.

### How do I mark a test as belonging to the slow or stress tier?

Place the test inside a module whose path contains a segment starting with `slow` or `stress`. For example, organize the test under `mod slow_integration` or place the file in a `tests/slow/` directory. The nextest configuration automatically detects these path patterns and excludes them from the default everyday profile while including them in the full tier profile.

### Why does the everyday loop exclude slow tests excluding external dependencies?

The everyday loop prioritizes **developer velocity** by eliminating tests that require database connections, network I/O, or long-running computations. This ensures feedback within ~20 seconds, maintaining flow state during iterative coding sessions while reserving expensive validation for pre-merge checks.

### Which CI checks run the full tier before merging?

The [`.github/workflows/ci.yml`](https://github.com/akitaonrails/ai-memory/blob/main/.github/workflows/ci.yml) workflow executes `cargo tf` (the full tier) on every pull request and push to protected branches. This gate prevents code that passes fast unit tests but fails integration or stress scenarios from entering the main branch, ensuring binary releases only ship after exhaustive validation.