# What Is the `memory_feedback` Tool and How Does It Work?

> Discover the memory_feedback tool a write-only MCP tool used by AI agents to record quality judgments on wiki pages, adjust salience scores, and flag stale content.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-08-28

---

**`memory_feedback` is a write-only MCP tool that lets agents record quality judgments about wiki pages, adjusting their salience scores and flagging stale or incorrect content for human review.**

The `memory_feedback` tool sits at the heart of the `akitaonrails/ai-memory` project's learning mechanism. It enables agents to signal whether a retrieved page was helpful, outdated, or wrong—directly influencing how long that knowledge stays active and which pages get surfaced for cleanup. Unlike automated feedback loops that risk runaway deletions, this tool appends immutable records that humans ultimately review.

## How `memory_feedback` Records Agent Judgments

When an agent retrieves a page via `memory_query` or `memory_read_page`, it can later call `memory_feedback` to label that page with one of four feedback kinds. The tool writes a single row to the `page_feedback` table and never deletes existing data.

| Feedback kind | Effect on page |
|-------------|---------------|
| **helpful** | Increases salience, keeping the page in the active "sweep-eligible" pool longer |
| **not_helpful** | Decreases salience, making the page more likely to decay |
| **stale** | Decreases salience **and** creates a `feedback_flagged` lint finding |
| **wrong** | Decreases salience **and** creates a `feedback_flagged` lint finding |

The current page version is looked up inside the same transaction, so a later rewrite automatically clears any flag. This append-only design prevents feedback loops while still allowing the system to learn from experience.

## The Three-Stage Feedback Flow

### 1. Record Feedback in `page_feedback`

The `record_page_feedback` function in [`crates/ai-memory-store/src/ops.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/ops.rs) (lines ~1650-1700) handles the database insertion:

```rust
/// Record one explicit feedback signal against the latest version of a page.
pub fn record_page_feedback(
    conn: &Connection,
    params: &FeedbackParams,
) -> Result<Option<f64>> {
    // … compute `salience_after` …
    conn.execute(
        "INSERT INTO page_feedback (page_id, op, author_id, kind, reason, salience_after)
         VALUES (?1, 'page_feedback', ?2, ?3, ?4, ?5)",
        params,
    )?;
    // Return the new salience for the page.
}

```

### 2. Update Salience via [`decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/decay.rs)

The `salience_after_feedback` helper in [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs) (lines ~130-150) computes the new weight:

```rust
pub fn salience_after_feedback(
    cfg: &Config,
    current: Option<f64>,
    kind: FeedbackKind,
) -> f64 {
    // Apply the feedback step, then clamp between SALIENCE_MIN and SALIENCE_MAX.
}

```

This clamps results to safe bounds, ensuring no single feedback event can catastrophically alter a page's visibility.

### 3. Trigger Lint for Human Review

Pages marked **stale** or **wrong** appear as `feedback_flagged` findings when `memory_lint` runs. This surfaces problematic content for human rewrite or deletion without automating dangerous removals.

## Practical `memory_feedback` Examples

After successfully using a page to solve a problem:

```bash
memory_feedback \
  --path "projects/foo/pages/important-decision.md" \
  --kind helpful \
  --reason "The guidance prevented a costly regression."

```

When you discover outdated information:

```bash
memory_feedback \
  --path "projects/foo/pages/old-api.md" \
  --kind stale \
  --reason "API has been deprecated; page needs update."

```

## Where `memory_feedback` Fits in the Codebase

| File | Purpose |
|------|---------|
| [`crates/ai-memory-store/migrations/V37__page_feedback.sql`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/migrations/V37__page_feedback.sql) | Creates the `page_feedback` table and indexes |
| [`crates/ai-memory-store/src/ops.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/ops.rs) (~l.1650-1700) | Core `record_page_feedback` implementation |
| [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs) (~l.130-150) | Salience computation logic |
| [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs) (~l.2150) | MCP endpoint that validates and forwards requests |
| [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md) | Design rationale for append-only feedback |
| [`docs/usage.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/usage.md) | User-facing documentation of accepted values |

The `page_feedback` table schema in [`V37__page_feedback.sql`](https://github.com/akitaonrails/ai-memory/blob/main/V37__page_feedback.sql) enables the derived `pages.salience` column, which aggregators consult when deciding retention priorities.

## Summary

- **`memory_feedback`** is a write-only tool—no deletions, only appends
- Four feedback kinds (**helpful**, **not_helpful**, **stale**, **wrong**) adjust salience and trigger lint flags
- **Stale** and **wrong** feedback creates `feedback_flagged` findings for human review
- The three-stage flow records feedback, updates salience via [`decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/decay.rs), and optionally triggers lint
- All data lives in the `page_feedback` table introduced by migration [`V37__page_feedback.sql`](https://github.com/akitaonrails/ai-memory/blob/main/V37__page_feedback.sql)

## Frequently Asked Questions

### How does `memory_feedback` prevent automatic deletion of flagged pages?

The tool only appends rows to `page_feedback`. It never modifies or deletes page content directly. Flagged pages surface in `memory_lint` output for human review—actual rewrite or deletion requires explicit human action, preventing runaway automated removals.

### Can an agent provide multiple feedback entries for the same page?

Yes. Each call creates a distinct row with its own timestamp and computed `salience_after`. The accumulated history becomes the source of truth for the derived `pages.salience` value, weighted by recency through the decay mechanism.

### What happens to feedback when a page gets rewritten?

The `record_page_feedback` function looks up the current version inside the same transaction. Since feedback ties to a specific `page_id` and version, a rewrite (which creates a new version record) automatically clears active flags while preserving the feedback history for audit purposes.

### Where is the MCP endpoint defined?

The `memory_feedback` MCP tool endpoint lives in [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs) around line 2150. It validates incoming requests, sanitizes the optional `reason` field, and delegates to `record_page_feedback` in the store layer.