Use Riverbed Memory

Riverbed Memory stores past review decisions as structured records that subsequent review runs can reference.

Prerequisites

• Node.js 22+
• npm ci completed

End-to-End Usage

1. Save memory during eval runs

Add the --persist-memory flag to npm run eval:all to automatically save eval results to .river/memory/index.json.

npm run eval:all -- --persist-memory --append-ledger --description "baseline"

After execution, an entry is appended to .river/memory/index.json.

2. Add memory entries manually

Use the API from src/lib/riverbed-memory.mjs to add records directly.

import { appendEntry } from './src/lib/riverbed-memory.mjs';

appendEntry('.river/memory/index.json', {
  id: 'wontfix-silent-catch-utils',
  type: 'wontfix',
  title: 'Silent catch in utils.mjs is intentional',
  content: 'Error logging is handled upstream, so re-throwing in catch is unnecessary.',
  metadata: {
    createdAt: new Date().toISOString(),
    author: 'reviewer',
    phase: 'midstream',
    tags: ['observability', 'silent-catch'],
    confidence: 0.9,
  },
  context: {
    sourcePR: 'https://github.com/example/repo/pull/42',
  },
});

3. Query memory entries

import { loadMemory, queryMemory } from './src/lib/riverbed-memory.mjs';

const index = loadMemory('.river/memory/index.json');

// Filter by type
const wontfixEntries = queryMemory(index, { type: 'wontfix' });

// Filter by phase + tags
const midstreamSecurity = queryMemory(index, {
  phase: 'midstream',
  tags: ['security'],
});

4. Persist in CI via GitHub Artifacts

.github/workflows/riverbed-persist.yml handles persistence through GitHub Artifacts.

# Call from another workflow
jobs:
  persist:
    uses: ./.github/workflows/riverbed-persist.yml

It automatically downloads the previous artifact and uploads the updated version (90-day retention). If no memory is found, the system operates normally (stateless fallback).

Save and compare review runs (result store)

You can persist review runs and compare them against earlier runs for regression. The result store lives in .river/runs/, separate from memory (.river/memory/).

--save: persist a run

Add --save to river run to persist the run to the result store (.river/runs/).

river run . --reviewers auto --save

river runs: inspect stored runs

# List stored runs (runId / phase / findings count, etc.)
river runs list

# Diff two runs (new / fixed findings)
river runs diff <run-id-1> <run-id-2>

# Aggregate metrics (dashboard-equivalent)
river runs summary

--baseline: regression-compare against a previous review

Pass a previous review JSON to --baseline <path> to print a regression summary (new / fixed findings) before the normal output. The JSON may be a raw findings array, or an object with a findings (or issues) key — e.g. the output of river run . --output json.

# 1. Save a baseline review as JSON
river run . --output json > baseline.json

# 2. Compare the current diff against the baseline
river run . --baseline baseline.json

Record Types

type	Purpose
adr	Link to Architecture Decision Records
review	Record review outcomes
wontfix	Document intentional non-fixes
pattern	Track recurring patterns
decision	Capture design decisions
eval_result	Evaluation run results (auto-generated by --persist-memory)

Schema

Records conform to schemas/riverbed-entry.schema.json. Required fields:

• id — Unique identifier
• type — One of the record types above
• content — Body text
• metadata.createdAt — ISO timestamp
• metadata.author — Creator

References

• Schema definition: schemas/riverbed-entry.schema.json
• Index schema: schemas/riverbed-index.schema.json
• Persistence workflow: .github/workflows/riverbed-persist.yml
• Background and design: pages/explanation/riverbed-memory.md