memory-feedback

Agent memory and learning system. Logs actions/failures, detects patterns, proposes skill improvements via GitHub PRs. Human approval required.

# Memory and Feedback

This skill gives the OpenClaw system a learning loop. All 18 skills log their episodes and failures. This skill reads those logs, detects patterns, and proposes improvements — as GitHub pull requests against the SKILL.md files that govern behaviour. Humans review and merge. The system learns.

This is Phase 4 infrastructure, designed to be activated once Phase 3B has been running long enough to generate meaningful data — typically 2-3 months of real operation. The episode and failure hooks in Skills 14-18 write to `/data/memory/` from day one. When this skill is activated, months of learning data are already waiting.


## Setup

```bash
export OPENCLAW_DATA_DIR="/data"
which jq || sudo apt install jq

# Optional: for GitHub PR workflow
export GITHUB_TOKEN="ghp_your_token"
which gh || echo "gh CLI optional — only needed for PR-based improvement proposals"
```

GITHUB_TOKEN is optional — required only for the PR workflow that proposes skill improvements. Core memory logging and failure tracking works without it using local files only.


## Core Philosophy

- **Semi-Automatic by Design**: The agent owns its memory files — episodes and failures are written without approval. Skill files govern behaviour and require human review before any change takes effect. This boundary is non-negotiable
- **Pattern Detection, Not Gut Feel**: Improvements are proposed only when a pattern appears with sufficient frequency and confidence. A single failure is a data point. Three failures of the same type with the same trigger is a pattern
- **Human in the Loop for Skill Changes**: Every proposed skill improvement becomes a GitHub pull request. The accountant or developer sees exactly what changed, why, and what evidence led to the proposal. Merge = accepted. Close = rejected and never re-proposed
- **Rate Limited to Protect the Machine**: Memory operations are token-budgeted. Pattern scans run overnight. Storage limits are enforced. The system cannot consume itself
- **Honest About What It Does Not Know**: Patterns below the confidence threshold are stored but not proposed. The system does not act on weak evidence

---

## OpenClaw Commands

### Episode and Failure Logging (called by other skills)
```bash
# Log a successful episode (called internally by all skills)
openclaw memory log-episode --skill greek-financial-statements --type statement_generated --afm EL123456789 --period 2026-01 --session S20260218-001 --tokens 1240 --duration-seconds 31

# Log a failure (called internally by all skills)
openclaw memory log-failure --skill conversational-ai-assistant --type intent_misread --session S20260218-003 --query "send the summary to Alpha" --action-taken "attempted openclaw comms send" --what-went-wrong "Skill 16 not available" --what-should-have-happened "draft text and state manual sending required"

# Log a human correction (called when accountant provides explicit feedback)
openclaw memory log-correction --session S20260218-005 --failure-id FAIL-20260218-003 --correction "Draft the text and tell me to send it manually"
```

### Pattern Scanning and Analysis
```bash
# Run pattern scan manually (normally runs nightly)
openclaw memory scan-patterns --since 30-days
openclaw memory scan-patterns --since 30-days --skill conversational-ai-assistant
openclaw memory scan-patterns --failures-only --min-occurrences 3

# View detected patterns
openclaw memory patterns-list --all
openclaw memory patterns-list --above-threshold   # Confidence >= 0.85
openclaw memory patterns-list --below-threshold   # Promising but not yet proposable
openclaw memory pattern-detail --id PAT-20260218-007

# View recent episodes and failures
openclaw memory episodes --last 7-days
openclaw memory episodes --skill greek-financial-statements --last 30-days
openclaw memory failures --last 7-days
openclaw memory failures --type completeness_gate_failed --last 30-days
openclaw memory corrections --last 30-days
```

### Proposal Generation and GitHub Integration
```bash
# Generate a proposal from a detected pattern
openclaw memory propose --pattern-id PAT-20260218-007
openclaw memory propose --pattern-id PAT-20260218-007 --dry-run   # Show proposed change without creating PR

# List proposals
openclaw memory proposals-list --all
openclaw memory proposals-list --status pending-pr
openclaw memory proposals-list --status pr-open
openclaw memory proposals-list --status rejected

# Create GitHub PR from a proposal
openclaw memory create-pr --proposal-id PROP-20260218-001
openclaw memory create-pr --proposal-id PROP-20260218-001 --branch-name "memory/skill-improvement/PROP-001"

# Sync PR status (check if merged or closed)
openclaw memory sync-prs
openclaw memory pr-status --proposal-id PROP-20260218-001
```

### Rate Limit Management
```bash
# View current consumption
openclaw memory rate-limit-status
openclaw memory rate-limit-status --verbose   # Show all counters and limits

# View config
openclaw memory rate-limit-config

# Reset daily counter (use only if counter stuck after verified issue)
openclaw memory rate-limit-reset --counter daily-tokens --confirm

# View storage usage
openclaw memory storage-usage
openclaw memory storage-usage --by-directory
```

### Memory Maintenance
```bash
# Archive old episodes (auto-runs, but can be triggered manually)
openclaw memory archive --episodes --older-than 90-days
openclaw memory archive --failures --older-than 90-days

# View memory health
openclaw memory health
openclaw memory health --verbose

# Generate memory report (monthly summary of learning activity)
openclaw memory report --period 2026-01
openclaw memory report --period 2026-01 --format pdf --output /data/reports/system/
```

---

## Episode Log Structure

```json
{
  "episode_id": "EP-20260218-001",
  "session_id": "S20260218-001",
  "user": "maria.g",
  "timestamp_utc": "2026-02-18T09:14:32Z",
  "skill": "greek-financial-statements",
  "action_type": "statement_generated",
  "client_afm": "EL123456789",
  "period": "2026-01",
  "commands_called": [
    "openclaw statements check-ready --afm EL123456789 --period 2026-01",
    "openclaw statements generate --afm EL123456789 --period 2026-01 --type all"
  ],
  "human_confirmation_required": false,
  "outcome": "success",
  "result_summary": "Full statement pack generated. P&L, balance sheet, cash flow, VAT summary. v1 issued.",
  "tokens_used": 1240,
  "duration_seconds": 31
}
```

---

## Failure Log Structure

```json
{
  "failure_id": "FAIL-20260218-003",
  "episode_id": "EP-20260218-003",
  "session_id": "S20260218-001",
  "user": "maria.g",
  "timestamp_utc": "2026-02-18T11:22:14Z",
  "skill": "conversational-ai-assistant",
  "failure_type": "intent_misread",
  "user_query": "Send the January summary to Alpha Trading",
  "agent_action_taken": "Attempted openclaw comms send — skill not yet available",
  "what_went_wrong": "Agent tried to send client communication directly. Skill 16 not deployed at time of query.",
  "what_should_have_happened": "Recognise outgoing communication unavailable. Draft the summary text. Inform user it needs manual sending.",
  "human_correction_provided": true,
  "human_correction_text": "Just write the summary text and tell me to send it manually",
  "pattern_candidate": true,
  "skill_improvement_candidate": "14-conversational-ai-assistant",
  "proposed_change_summary": "Add scope boundary: if comms send requested and Skill 16 unavailable, draft content and state manual sending required"
}
```

---

## Pattern Detection

### Detection Algorithm

```yaml
Pattern_Detection:
  runs: "Nightly at 02:00 Athens time"
  lookback_window: "30 days rolling"
  minimum_occurrences: 3
  confidence_threshold_for_proposal: 0.85

  grouping_keys:
    - skill + failure_type                     # Same skill, same failure type
    - user_query_intent + agent_action_taken   # Same intent, same wrong action
    - skill + missing_data_source              # Same skill, same upstream data missing

  confidence_calculation: