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

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 (lines ~1650-1700) handles the database insertion:

/// 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

The salience_after_feedback helper in crates/ai-memory-store/src/decay.rs (lines ~130-150) computes the new weight:

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:

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

When you discover outdated information:

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	Creates the page_feedback table and indexes
crates/ai-memory-store/src/ops.rs (~l.1650-1700)	Core record_page_feedback implementation
crates/ai-memory-store/src/decay.rs (~l.130-150)	Salience computation logic
crates/ai-memory-mcp/src/server.rs (~l.2150)	MCP endpoint that validates and forwards requests
docs/ARCHITECTURE.md	Design rationale for append-only feedback
docs/usage.md	User-facing documentation of accepted values

The page_feedback table schema in 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, and optionally triggers lint
• All data lives in the page_feedback table introduced by migration 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 around line 2150. It validates incoming requests, sanitizes the optional reason field, and delegates to record_page_feedback in the store layer.

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