# Memory (PowerMem) Plugin

Moltbot long-term memory plugin backed by [PowerMem](https://github.com/oceanbase/powermem) via its HTTP API. Provides intelligent memory extraction, Ebbinghaus forgetting curve, and multi-agent isolation without running Python inside Moltbot.

## Requirements

- A running **PowerMem HTTP API server**. Start it separately, for example:

  ```bash
  pip install powermem
  powermem-server --host 0.0.0.0 --port 8000
  ```

  Or with Docker:

  ```bash
  docker run -d -p 8000:8000 --env-file .env oceanbase/powermem-server:latest
  ```

- Configure PowerMem itself (embeddings, storage, etc.) via its `.env`; see [PowerMem configuration](https://github.com/oceanbase/powermem#quick-start).

## Moltbot configuration

1. Set the memory slot to this plugin:

   ```yaml
   plugins:
     slots:
       memory: memory-powermem
     config:
       memory-powermem:
         baseUrl: "http://localhost:8000"
         # apiKey: "optional-if-auth-enabled"
         autoCapture: true
         autoRecall: true
         inferOnAdd: true
         # userId: "optional-override"
         # agentId: "optional-override"
   ```

2. Ensure PowerMem server is running before starting the gateway.

## Options

| Option        | Required | Description                                                                 |
|---------------|----------|-----------------------------------------------------------------------------|
| `baseUrl`     | Yes      | PowerMem API base URL (e.g. `http://localhost:8000`), no `/api/v1` suffix. |
| `apiKey`      | No       | Set if PowerMem server has API key authentication enabled.                 |
| `userId`      | No       | PowerMem `user_id` for isolation; default `moltbot-user`.                 |
| `agentId`     | No       | PowerMem `agent_id` for isolation; default `moltbot-agent`.                |
| `autoCapture` | No       | Auto-store from conversations after agent ends; default `true`.            |
| `autoRecall`  | No       | Auto-inject relevant memories before agent starts; default `true`.        |
| `inferOnAdd`  | No       | Use PowerMem intelligent extraction when adding; default `true`.           |

## Tools

- **memory_recall** — Search long-term memories by query.
- **memory_store** — Save information (with optional infer).
- **memory_forget** — Delete by memory ID or by search query.

## CLI

- `moltbot ltm search <query> [--limit n]` — Search memories.
- `moltbot ltm health` — Check PowerMem server health.

## Running tests

From the repo root:

```bash
# Run all tests (includes extensions)
pnpm test

# Run only this plugin's tests
pnpm exec vitest run --config vitest.extensions.config.ts extensions/memory-powermem
```

## Docs

- [PowerMem](https://github.com/oceanbase/powermem)
- [PowerMem HTTP API](https://github.com/oceanbase/powermem/blob/master/docs/api/0005-api_server.md)
- [Moltbot long-term memory design](/docs/design/memory-powermem-integration.md)