npm package: @smyslenny/agent-memory-openclaw
Description: AgentMemory native adapter plugin for OpenClaw
Author: smysle
Latest version: 0.2.3

# @smyslenny/agent-memory-openclaw

AgentMemory native adapter plugin for [OpenClaw](https://github.com/openclaw/openclaw).

Automatically boots memories on session start and surfaces relevant memories into agent prompts — no manual MCP/cron orchestration needed.

## Install

```bash
npm install @smyslenny/agent-memory-openclaw
# peer dependency
npm install @smyslenny/agent-memory
```

## Configure

Add to your `openclaw.json`:

```json
{
  "plugins": {
    "entries": {
      "@smyslenny/agent-memory-openclaw": {
        "enabled": true,
        "config": {
          "autoBoot": true,
          "autoSurface": true,
          "surfaceLimit": 5,
          "surfaceMaxChars": 2000
        }
      }
    }
  }
}
```

## What It Does

### Phase 1 (Current): Read Path

- **Boot** (`session_start`): Loads identity and pinned memories when a session starts. The narrative is cached and injected once via `appendSystemContext`.
- **Surface** (`before_prompt_build`): Retrieves relevant memories based on the user's message and recent conversation turns. Results are injected via `prependContext`.
- **Dedup**: Same memory is never injected twice within a session.
- **Cleanup** (`before_reset`): Clears session caches on `/new` or `/reset`.

### Phase 2 (Current): Write Path + Feedback

- **Remember** (`agent_end`): Automatically extracts conversation content from successful agent turns and writes to long-term memory via `rememberMemory()`.
  - Conservative thresholds: min 3 user turns, min 200 chars
  - 30-minute cooldown per session
  - Full provenance: `source_session`, `source_context`, `observed_at`
  - Write Guard handles dedup/merge/conflict
- **Passive Feedback** (`before_prompt_build`): Records `recordPassiveFeedback()` for surfaced memories, improving future retrieval ranking.

## Config Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | boolean | `true` | Enable/disable the adapter |
| `autoBoot` | boolean | `true` | Auto-boot on session start |
| `autoSurface` | boolean | `true` | Auto-surface before each reply |
| `autoRemember` | boolean | `false` | Auto-remember after turns |
| `autoFeedback` | boolean | `true` | Record passive feedback for surfaced memories |
| `surfaceLimit` | number | `5` | Max memories to surface |
| `surfaceMaxChars` | number | `2000` | Max chars in injected prompt block |
| `dbPath` | string | auto | Explicit path to AgentMemory SQLite DB |
| `rememberMinTurns` | number | `3` | Min user turns to trigger remember |
| `rememberMinChars` | number | `200` | Min user chars to trigger remember |
| `rememberCaptureRoles` | string | `"user-and-assistant"` | Capture user-only or both |
| `rememberCooldownMs` | number | `1800000` | Cooldown between writes (30min) |

## DB Path Resolution

1. `config.dbPath` (explicit)
2. `{workspaceDir}/agent-memory.db` (from OpenClaw hook context)
3. `AGENT_MEMORY_DB_PATH` environment variable
4. `~/.agent-memory/memory.db` (default)

## Architecture

```
OpenClaw Gateway
  │
  ├── session_start ──→ BootManager ──→ boot()
  │
  ├── before_prompt_build ──→ SurfaceManager
  │                           ├── boot narrative (appendSystemContext)
  │                           ├── relevant memories (prependContext)
  │                           └── recordPassiveFeedback()
  │
  ├── agent_end ──→ RememberManager ──→ rememberMemory()
  │                 ├── conversation normalization
  │                 ├── threshold checks (turns, chars, cooldown)
  │                 └── provenance (session, context, timestamp)
  │
  └── before_reset ──→ clear all session caches
                         │
                         ▼
                   AgentMemory Core (v5.1+)
```

## Requirements

- OpenClaw v2026.3.x+
- AgentMemory v5.1.0+
- Node.js 20+

## License

MIT