npm package: @jmz1/remembrall
Description: OpenClaw extension that glows when you forget to scribe. Detects 'I'll remember' patterns without file writes and nudges on the next turn. Supports i18n via configurable patterns.
Author: jmz
Latest version: 1.1.0

# 🔮 Remembrall

An OpenClaw extension that detects when the assistant says "I'll remember" or "noted" but forgets to actually write it to a file — then nudges on the next turn.

**Now with i18n support!** Patterns and messages are fully configurable for any language.

## Why?

AI assistants don't have persistent memory between sessions. When an assistant says "I'll remember that", it's lying (unless it writes to a file). This plugin catches that pattern and prompts the assistant to either:

1. Actually write the information to an appropriate file, or
2. Acknowledge it was just conversational filler

## How it works

1. **Pattern detection**: Monitors assistant responses for memory-intent phrases
2. **Write verification**: Checks if `Write` or `edit` tool was called in the current turn
3. **Nudge injection**: If pattern found but no write occurred, queues a system event for the next turn

The nudge appears as a system message, not a user message — so it doesn't pollute the conversation history.

## Installation

### From npm

```bash
npm install @jmz1/remembrall
```

### Manual installation

Copy to your workspace extensions directory:

```bash
git clone https://github.com/jmz1/remembrall.git ~/.openclaw/extensions/remembrall
cd ~/.openclaw/extensions/remembrall
npm install
```

Restart the gateway:

```bash
openclaw gateway restart
```

### Verify it's loaded

```bash
openclaw plugins list
```

You should see `remembrall` in the list.

## Configuration

The plugin works out of the box with English patterns and no configuration required.

### Basic configuration

In `openclaw.json`:

```json
{
  "plugins": {
    "configs": {
      "remembrall": {
        "enabled": true
      }
    }
  }
}
```

### Custom patterns (inline)

Override patterns directly in config:

```json
{
  "plugins": {
    "configs": {
      "remembrall": {
        "patterns": [
          "\\b(i'll remember|i will remember)\\b",
          "\\b(noted|mental note)\\b",
          "\\bcustom pattern here\\b"
        ],
        "nudgeMessage": "🔮 Custom nudge message here"
      }
    }
  }
}
```

### Using a language file (i18n)

Point to an external YAML or JSON file for full customisation:

```json
{
  "plugins": {
    "configs": {
      "remembrall": {
        "patternsFile": "./patterns/fr.yaml"
      }
    }
  }
}
```

Included language files:
- `patterns/en.yaml` — English (default)
- `patterns/fr.yaml` — French
- `patterns/de.yaml` — German  
- `patterns/es.yaml` — Spanish

### Configuration options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable/disable the extension |
| `patternsFile` | string | — | Path to external YAML/JSON config file |
| `patterns` | string[] | (built-in) | Regex patterns that trigger the nudge |
| `writeTools` | string[] | `["Write", "edit"]` | Tool names that count as "writing" |
| `nudgeMessage` | string | (built-in) | System event message when nudge triggers |

**Priority order**: inline config > external file > built-in defaults

## Creating custom language files

Create a YAML file with this structure:

```yaml
# remembrall-mylang.yaml
patterns:
  - "\\bpattern one\\b"
  - "\\bpattern two\\b"
  # Add more patterns...

writeTools:
  - Write
  - edit

nudgeMessage: >
  🔮 Remembrall: Your custom nudge message here.
  Can be multi-line.
```

Patterns are case-insensitive by default. For explicit flags, use regex notation:

```yaml
patterns:
  - "/Pattern With Flags/gi"
  - "simple pattern"  # becomes /simple pattern/i
```

### Contributing translations

PRs welcome! See **[patterns/TRANSLATING.md](patterns/TRANSLATING.md)** for the full guide, including:

- Translation principles (capture intent, not literal words)
- Language-specific considerations (word boundaries, formality)
- **Round-trip validation** — test your translation by having an LLM translate it back to English

Quick start:
1. Copy `patterns/en.yaml` to `patterns/<lang>.yaml`
2. Translate following the guide
3. Run round-trip validation
4. Submit a PR

## Debugging

Check the gateway logs for Remembrall messages:

```bash
openclaw logs | grep Remembrall
```

You'll see:
- `🔮 Remembrall loaded` — extension initialised
- `🔮 Remembrall: Using N patterns from ...` — config loaded
- `🔮 Remembrall glowing` — nudge triggered

## Technical details

- **Hook**: `agent_end` — fires after each agent turn completes
- **Nudge method**: `api.runtime.system.enqueueSystemEvent()` — queues for next turn
- **Scope**: Current turn only (doesn't check entire conversation history)
- **Dependencies**: `yaml` for parsing external config files

## Limitations & the case for a native feature

This extension is a workaround for a fundamental problem. Here's what a proper OpenClaw-native implementation could do better:

### Current limitations (extension approach)

| Limitation | Impact |
|------------|--------|
| **Post-hoc detection** | Nudge arrives on the *next* turn, after the user has already seen the false promise |
| **Regex pattern matching** | Can miss edge cases ("I've logged that") or false-positive on conversational phrases |
| **No intent awareness** | Can't distinguish "noted" (acknowledgment) from "noted in MEMORY.md" (claim of action) |
| **No response interception** | Can't warn before sending; damage already done |
| **Session-scoped only** | Can't track unfulfilled commitments across compaction boundaries |

### How a native feature could work better

**1. Pre-send validation hook**

A `response_validate` hook that fires *before* the response is sent to the user. Could:
- Detect memory-intent patterns
- Check if write tools were called
- Inject a warning into the response itself, or
- Force the agent to retry with an actual write

```typescript
// Hypothetical API
api.on("response_validate", (draft, ctx) => {
  if (hasMemoryIntent(draft.text) && !draft.toolCalls.some(isWriteTool)) {
    return { action: "retry", guidance: "You claimed to remember but didn't write. Fix it." };
  }
});
```

**2. Model-based intent classification**

Instead of regex, use a lightweight model call (or the same model with a structured output) to classify:
- Is this a memory commitment? (yes/no/ambiguous)
- What specific information was promised to be stored?
- Was a file write observed?

This would dramatically reduce false positives from conversational "noted" vs actual memory claims.

### Related issues

- [#5073](https://github.com/openclaw/openclaw/issues/5073) — Agent falsely claims to write to memory files

### Contributing

If you're interested in building any of the above as a core feature, consider:
1. Commenting on #5073 with your approach
2. Submitting a PR to `openclaw/openclaw`
3. Discussing in the [OpenClaw Discord](https://discord.com/invite/clawd)

This extension serves as a proof-of-concept that the problem is solvable. A native implementation could be more elegant.

## License

MIT

## Credits

Inspired by the need to actually practice what we preach about "text > brain" 📝