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

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	CuratorFindings; 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, 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

# Validate the entire project immediately

ai-memory-cli lint --project .

This invokes lint.rs, which walks every page, executes registered rules, and surfaces any LintError to the user or calling hook.

Example Lint Rule Implementation

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.

---

What Curator Does: Semantic Quality Improvement

In crates/ai-memory-consolidate/src/curator.rs, the curator engine analyzes recall‑evaluation metrics from 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 CuratorFindings. These findings drive the auto‑improve scheduler or provide actionable lists for manual review.

Running Curator via CLI

# Generate a curator report for manual review

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

This triggers curator.rs, consuming recall‑evaluation data and emitting improvement opportunities.

Programmatic Curator Usage

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	Core lint engine: LintError, rule registration, page validation
crates/ai-memory-consolidate/src/curator.rs	Curation pipeline: CuratorReport, CuratorFinding, auto‑improve actions
crates/ai-memory-consolidate/src/recall_eval.rs	Recall‑evaluation metrics consumed by curator
crates/ai-memory-cli/src/commands/lint.rs	CLI wrapper for lint operations
crates/ai-memory-cli/src/commands/curator.rs	CLI wrapper for curator operations
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 CuratorFindings 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 CuratorFindings 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.

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