# AI Context Cache

> **PREREQUISITE: Requires civyk-repoix (REPOIX_MODE != "none").**
> **IF REPOIX_MODE == "none": SKIP this entire section.** Cache tools (`understand(action="recall")`, `understand(action="store")`, `understand(action="stats")`, `understand(action="invalidate")`) are unavailable without repoix. Proceed without caching -- read files directly with Read, Grep, Glob.

File-level cache operations (recall before read, store after analysis) are automated. Use `understand(action="store")` manually only for **synthesis** across multiple files.

## Stage Start: Check Cache Coverage

For multi-stage workflows, check what previous stages cached:

```text
# [!] PREREQUISITE: Requires repoix (skip when REPOIX_MODE == "none")
IF REPOIX_MODE == "none":
    OUTPUT: "[INFO] AI cache unavailable - no repoix. Skipping cache operations."
    SKIP to next section

understand(action="stats", limit=50)

# Recall project/module-level understanding from earlier stages
understand(action="recall", target="project")
# IF found AND fresh: Use cached architecture context to guide this stage
```

## Intentional Cache Stores

Use `understand(action="store")` for **synthesis** that goes beyond single-file analysis. **Skip when REPOIX_MODE == "none".**

```text
# [!] PREREQUISITE: Requires repoix (skip when REPOIX_MODE == "none")
# Module-level synthesis (after analyzing all files in a module)
understand(
  action="store",
  scope="module",
  target="src/auth",
  purpose="Authentication module with OAuth2 and session management",
  importance="critical",
  key_points=["OAuth2 flow", "Session Redis storage", "Token refresh"],
  gotchas=["Race condition on concurrent refresh"],
  analysis="<cross-file patterns and relationships>"
)

# Project-level synthesis (after understanding architecture)
understand(
  action="store",
  scope="project",
  target="project",
  purpose="<what this codebase does>",
  importance="critical",
  key_points=["<architecture>", "<key patterns>", "<main components>"],
  gotchas=["<architectural concerns>"],
  analysis="<high-level architecture summary>"
)
```

## Stage-Specific Guidance

| Stage Type | Examples | Cache Behavior |
|------------|----------|----------------|
| **Priming** | deepwiki 02-04, analyze 02a-02d | Building cache - many stores expected |
| **Analysis** | deepwiki 05-14, analyze 03a-03b | Using cache - high hit rate expected |
| **Generation** | deepwiki 15-16, analyze 04a-06 | Consuming cache - minimal file reads |
