npm package: @maximem/moltbot-memory
Description: Maximem memory plugin for Moltbot — persistent cross-channel memory
Author: Maximem
Latest version: 0.1.0
Deprecated: Moved to @maximem/memory-plugin

# Maximem Memory Plugin for Moltbot

Persistent cross-channel memory for Moltbot via the Maximem backend API.

## Features

- **Auto-Recall**: Automatically injects relevant memories before each LLM turn
- **Auto-Capture**: Automatically stores conversation context after each turn
- **Slash Commands**: `/remember` and `/recall` for direct memory interaction
- **LLM Tools**: `maximem_store`, `maximem_search`, `maximem_forget` for agent-driven memory operations
- **CLI Commands**: Terminal-based memory management with `moltbot maximem`
- **Cross-Channel**: Memories persist across Telegram, Slack, WhatsApp, Discord, and all supported channels

## Installation

### From npm

```bash
moltbot plugins install @maximem/moltbot-memory
```

### From GitHub

```bash
moltbot plugins install github:maximem/moltbot-plugin
```

### Verify Installation

```bash
moltbot plugins list
```

## Configuration

### Option 1: Environment Variable (Recommended)

Add to your shell profile (`~/.zshrc` or `~/.bashrc`):

```bash
export MAXIMEM_API_KEY="maximem_live_abc123..."
source ~/.zshrc
```

### Option 2: Config File

```bash
moltbot config set plugins.config.maximem.apiKey "maximem_live_abc123..."
```

### Full Configuration Example

Edit `~/.clawdbot/clawdbot.json`:

```json
{
  "plugins": {
    "config": {
      "maximem": {
        "apiKey": "maximem_live_...",
        "endpoint": "https://agenticrouter.maximem.ai",
        "autoRecall": true,
        "autoCapture": true,
        "maxRecallTokens": 1000,
        "minPromptLength": 5,
        "captureDebounceMs": 2000
      }
    }
  },
  "agents": {
    "list": [{
      "id": "main",
      "tools": {
        "allow": ["maximem_store", "maximem_search", "maximem_forget"]
      }
    }]
  }
}
```

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | string | - | Maximem API key (or set `MAXIMEM_API_KEY` env var) |
| `endpoint` | string | `https://agenticrouter.maximem.ai` | Maximem API endpoint |
| `autoRecall` | boolean | `true` | Automatically inject memories before each turn |
| `autoCapture` | boolean | `true` | Automatically capture conversation after each turn |
| `maxRecallTokens` | number | `1000` | Maximum tokens for recalled memory context (100-10000) |
| `minPromptLength` | number | `5` | Minimum prompt length to trigger recall |
| `captureDebounceMs` | number | `2000` | Debounce window for batching captures (milliseconds) |

## Usage

### Slash Commands

Use these commands directly in any supported chat channel:

#### `/remember [text]`

Manually save information to long-term memory:

```
/remember My favorite programming language is TypeScript
/remember I prefer dark themes for all applications
/remember Project deadline is March 15, 2026
```

#### `/recall [query]`

Search your long-term memory:

```
/recall favorite programming language
/recall project deadline
/recall preferences
```

### CLI Commands

Manage memories from the terminal:

#### Search Memories

```bash
moltbot maximem search "favorite color"
moltbot maximem search "deadlines" --limit 20
moltbot maximem search "preferences" --category preference --json
```

Options:
- `-l, --limit <n>` - Maximum results (default: 10)
- `-c, --category <cat>` - Filter by category
- `--json` - Output as JSON

#### View Statistics

```bash
moltbot maximem stats
```

#### Wipe All Memories

```bash
# Dry run (preview only)
moltbot maximem wipe --dry-run

# With confirmation prompt
moltbot maximem wipe

# Skip confirmation
moltbot maximem wipe --yes
```

### LLM Tools

Enable tools in your agent configuration to let the AI use memory operations:

```json
{
  "agents": {
    "list": [{
      "id": "main",
      "tools": {
        "allow": ["maximem_store", "maximem_search", "maximem_forget"]
      }
    }]
  }
}
```

The AI can then autonomously:
- **Store** important facts when users share information
- **Search** memories when answering questions about past conversations
- **Forget** specific memories when requested

## How It Works

### Auto-Recall Flow

1. User sends a message
2. **Before** the LLM processes it, the plugin queries Maximem for relevant memories
3. Memories are injected into the context as XML-tagged content
4. LLM responds with awareness of past conversations

### Auto-Capture Flow

1. User and LLM have a conversation
2. **After** the LLM responds, the plugin sends the conversation to Maximem
3. Maximem extracts memory-worthy facts and stores them
4. Future conversations can recall this information

### Debouncing

The plugin uses configurable debouncing (default 2000ms) to batch rapid message sequences, reducing API calls and improving efficiency.

## API Key

Get your API key from [maximem.ai](https://maximem.ai). The key format is:

- Production: `maximem_live_<32_chars>`
- Test/Sandbox: `maximem_test_<32_chars>`

## Development

### Setup

```bash
npm install
```

### Type Check

```bash
npm run typecheck
```

### Run Tests

```bash
npm test
npm run test:watch
```

### Build

```bash
npm run typecheck
```

## Architecture

```
User Machine (Moltbot Gateway)
├── MaxiMem Plugin
│   ├── Lifecycle Hooks (auto-recall, auto-capture)
│   ├── LLM Tools (store, search, forget)
│   ├── Slash Commands (/remember, /recall)
│   └── CLI Commands (search, wipe, stats)
└── HTTP Client
    └── Maximem Backend (agenticrouter.maximem.ai)
```

## Support

- **Documentation**: [docs.maximem.ai](https://docs.maximem.ai)
- **Issues**: [GitHub Issues](https://github.com/maximem/moltbot-plugin/issues)
- **Email**: hello@maximem.dev

## License

MIT © Maximem