# Curator vs Lint in ai‑memory: Two Stages of the Auto‑Improvement Loop Explained

> Understand Curator vs Lint in ai-memory. Lint checks structural correctness and Curator finds recall gaps to improve your AI knowledge base. Learn when to use each.

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

---

**Lint validates structural correctness at write time, while Curator performs semantic analysis on the whole knowledge base to surface recall gaps and drive improvements.**

Both `curator` and `lint` are quality‑control stages in the **ai‑memory** auto‑improvement loop, but they serve fundamentally different purposes. `lint` blocks malformed data from entering the store; `curator` identifies semantic weaknesses in stored knowledge and schedules fixes. Understanding when to use each—and how they interact—lets you maintain both immediate data integrity and long‑term retrieval quality.

---

## Core Differences: Lint vs Curator

| Aspect | Lint | Curator |
|--------|------|---------|
| **Purpose** | Deterministic, rule‑based validation of formatting, metadata, and schema compliance | Semantic gap analysis after consolidation; finds low‑recall pages and generates improvement suggestions |
| **Execution** | Synchronous on every write path | Asynchronous, project‑wide sweep triggered by timer or manual CLI |
| **Inputs** | Raw observations, page metadata, SQLite schema | `CuratorReport` from recall‑evaluation, embeddings, lint outcomes |
| **Outputs** | `LintError` / `LintWarning` objects; no automatic changes | `CuratorFinding`s; may trigger re‑embedding, regeneration, or review |
| **Blocks writes?** | Yes | No |

These differences reflect their distinct roles in the quality pipeline: **lint** is a gatekeeper, **curator** is an optimizer.

---

## What Lint Does: Structural Validation

In [`crates/ai-memory-consolidate/src/lint.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/lint.rs), the lint engine performs deterministic checks that guarantee every page conforms to required standards before it enters the store.

Lint rules validate:

- Front‑matter completeness (e.g., `applyTo: '**'`)
- Schema‑compliant IDs and timestamps
- Required markdown sections
- Syntax and formatting errors

Because lint runs **synchronously** during every write—hook payload storage, wiki page creation, or post‑sweep finalization—failures block the operation until resolved. This fail‑fast behavior ensures downstream processes never process corrupted data.

### Running Lint via CLI

```bash

# Validate the entire project immediately

ai-memory-cli lint --project .

```

This invokes [`lint.rs`](https://github.com/akitaonrails/ai-memory/blob/main/lint.rs), which walks every page, executes registered rules, and surfaces any `LintError` to the user or calling hook.

### Example Lint Rule Implementation

```rust
use ai_memory_consolidate::{LintError, Lint};

fn ensure_apply_to_frontmatter(page: &Page) -> Result<(), LintError> {
    if !page.front_matter.contains("applyTo: '**'") {
        Err(LintError::MissingApplyTo)
    } else {
        Ok(())
    }
}

```

Lint rules are pure functions returning `Result<(), LintError>`, assembled into a validation pipeline in [`lint.rs`](https://github.com/akitaonrails/ai-memory/blob/main/lint.rs).

---

## What Curator Does: Semantic Quality Improvement

In [`crates/ai-memory-consolidate/src/curator.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/curator.rs), the curator engine analyzes **recall‑evaluation metrics** from [`recall_eval.rs`](https://github.com/akitaonrails/ai-memory/blob/main/recall_eval.rs) to find knowledge that embeddings fail to retrieve effectively.

Curator detects:

- Pages with chronically low recall scores
- Stale embeddings that no longer represent current content
- Semantic drift between stored pages and their vector representations
- Candidates for auto‑improve actions (re‑embedding, rewriting, or human review)

Unlike lint, curator operates **asynchronously** on the entire project, producing a `CuratorReport` containing structured `CuratorFinding`s. These findings drive the auto‑improve scheduler or provide actionable lists for manual review.

### Running Curator via CLI

```bash

# Generate a curator report for manual review

ai-memory-cli curator --project . --output report.json

```

This triggers [`curator.rs`](https://github.com/akitaonrails/ai-memory/blob/main/curator.rs), consuming recall‑evaluation data and emitting improvement opportunities.

### Programmatic Curator Usage

```rust
use ai_memory_consolidate::{CuratorParams, Curator};

let params = CuratorParams {
    // Optional: limits, dry‑run flag, filtering
    ..Default::default()
};
let curator = Curator::new(&db, &params)?;
let report = curator.run()?; // Executes full curation pipeline

println!("Found {} improvement opportunities", report.findings.len());

```

The `Curator::run` method implements the complete pipeline: loading embeddings, aggregating recall metrics, identifying gaps, and scheduling corrective actions.

---

## When to Use Each Tool

### Use Lint When You Need Immediate Data Integrity

- **CI/CD pipelines**: Gate commits on `cargo test` and `cargo clippy` which depend on lint success
- **Hook integrations**: Reject malformed observations before they pollute the store
- **Manual edits**: Catch front‑matter errors before saving wiki pages

Lint is your **first line of defense**—inexpensive, deterministic, and blocking.

### Use Curator When You Need Long‑Term Quality Improvement

- **Periodic maintenance**: Run on schedule to catch degrading retrieval performance
- **Recall debugging**: Investigate why specific knowledge fails to surface in queries
- **Auto‑improve workflows**: Enable background re‑embedding and page regeneration

Curator is your **quality optimization engine**—analytical, project‑scoped, and improvement‑oriented.

---

## Typical Workflow Integration

The **ai‑memory** auto‑improvement loop orchestrates both tools:

```

1. Hook → Store → Lint          (Reject malformed data)
        ↓
2. Periodic Sweep → Embedding → Lint → Recall‑Eval → Curator
                                        (Surface gaps, schedule fixes)

```

This two‑stage approach separates concerns: lint guarantees structural correctness at entry, while curator ensures semantic relevance over time.

---

## Key Source Files

| File | Purpose |
|------|---------|
| [`crates/ai-memory-consolidate/src/lint.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/lint.rs) | Core lint engine: `LintError`, rule registration, page validation |
| [`crates/ai-memory-consolidate/src/curator.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/curator.rs) | Curation pipeline: `CuratorReport`, `CuratorFinding`, auto‑improve actions |
| [`crates/ai-memory-consolidate/src/recall_eval.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/recall_eval.rs) | Recall‑evaluation metrics consumed by curator |
| [`crates/ai-memory-cli/src/commands/lint.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/lint.rs) | CLI wrapper for lint operations |
| [`crates/ai-memory-cli/src/commands/curator.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/curator.rs) | CLI wrapper for curator operations |
| [`docs/auto-improvement-loop.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/auto-improvement-loop.md) | Architectural documentation for the full pipeline |

---

## Summary

- **Lint** performs synchronous, rule‑based validation on every write; use it to block malformed data immediately
- **Curator** performs asynchronous, semantic analysis across the project; use it to improve retrieval quality over time
- Lint outputs are `LintError`/`LintWarning`; curator outputs are `CuratorFinding`s that drive auto‑improve actions
- Both tools are essential: lint for data integrity at entry, curator for quality optimization at scale

---

## Frequently Asked Questions

### Does lint run automatically or do I need to invoke it manually?

Lint runs **automatically and synchronously** on every write path in ai‑memory—hook storage, wiki page creation, and post‑sweep finalization. You can also invoke it manually via `ai-memory-cli lint --project .` for ad‑hoc validation or CI integration.

### Can curator fix problems automatically or does it only report them?

Curator **both reports and acts**. The `CuratorReport` surfaces `CuratorFinding`s for human review, but when auto‑improve is enabled, curator also schedules and executes corrective actions including re‑embedding stale vectors and regenerating low‑recall pages.

### What happens if lint fails during a hook write?

The write **is blocked** until the lint error is resolved. This fail‑fast design ensures that malformed observations, missing metadata, or schema violations never enter the store and propagate to downstream consolidation processes.

### How often should I run curator on my ai‑memory project?

Run curator **on a schedule** (via the built‑in auto‑improve timer) for continuous quality maintenance, or **manually** when you notice retrieval degradation or after major content additions. The recall‑evaluation sweep that feeds curator is computationally heavier than lint, making periodic execution more appropriate than per‑write invocation.