# mem0-auto-capture hook

A self-contained OpenClaw hook that wires incoming messages to your Mem0 instance for auto-capture and auto-recall. It runs as a message hook inside the OpenClaw gateway, transcribes audio, decides what to store, queries memories/knowledge before the agent responds, and injects the results back into the prompt.

## Key behaviors

1. **Auto-Capture** — whenever a received message matches the configured trigger (default: every message or the phrase “please remember”), the hook gathers the most recent lines from that session (controlled by `recentKeep`) and POSTs them to `<baseUrl>/memories` with the resolved user id. It deduplicates captures by hashing the text and short-circuiting identical payloads within one minute.

2. **Auto-Recall** — before the agent answers (on the `preprocessed` or `transcribed` event) it runs parallel searches against `<baseUrl>/memories/search` and `/knowledge/search`, filters them by rerank score, and appends the results as `[MEMORY - Personal]` and `[MEMORY - Knowledge Base]` sections inside `bodyForAgent` so the LLM has both long-term and knowledge-base context.

3. **Audio support** — if the event includes media, the hook posts the file to the local STT service at `http://192.168.0.200:5005/transcribe`, caches transcripts, and uses them for both capture and recall. It also rewrites `bodyForAgent` so that audio messages appear as text when the agent eats them.

## Configuration

All options are read from environment variables (prefixed `MEM0_`) or a JSON file at `~/.openclaw/mem0.json`. Missing values fall back to sensible defaults.

| Option | Source | Default | Notes |
|---|---|---|---|
| `baseUrl` | `MEM0_BASE_URL` or config file (`baseUrl`) | `http://192.168.0.200:8420` | The Mem0 server root. |
| `userId` | `MEM0_USER_ID` or config file | derived from `sessionKey` → agent ID, then fallback to `userId` or `default` | Used for personal memories. |
| `recallLimit` | `MEM0_RECALL_LIMIT` | `5` | How many personal memories to admit. |
| `knowledgeLimit` | `MEM0_KNOWLEDGE_LIMIT` | `5` | How many knowledge-base hits to inject. |
| `knowledgeUserId` | `MEM0_KNOWLEDGE_USER_ID` | `knowledge_base` | The user id that holds knowledge-base memories. |
| `rerankThreshold` | `MEM0_RERANK_THRESHOLD` | `0.002` | Filters injected memories with low rerank scores. |
| `captureTrigger` | `MEM0_CAPTURE_TRIGGER` | `always` | `always` / `phrase` / `explicit`. |
| `triggerPhrase` | `MEM0_TRIGGER_PHRASE` | `please remember` | Used when `captureTrigger` is `phrase`. |
| `autoCapture` | `MEM0_AUTO_CAPTURE` | `true` | Enable/disable captures. |
| `autoRecall` | `MEM0_AUTO_RECALL` | `true` | Enable/disable recalls. |
| `recentKeep` | `MEM0_RECENT_KEEP` | `5` | How many lines of recent context to bundle for a capture. |

> Example `~/.openclaw/mem0.json`:
>
> ```json
> {
>   "baseUrl": "http://192.168.0.200:8420",
>   "userId": "lukas",
>   "captureTrigger": "phrase",
>   "triggerPhrase": "please remember",
>   "autoCapture": true,
>   "autoRecall": true
> }
> ```

## Deployment

1. Build + install dependencies (TypeScript only needs dev-time tooling; the runtime runs the `.ts` file directly):

   ```bash
   cd mem0-auto-capture-hook
   npm install
   ```

2. Link the hook into OpenClaw (this installs the compiled `hook/handler.ts` directory):

   ```bash
   openclaw hooks install --link $(pwd)/hook
   ```

3. Restart the gateway so it reloads hooks:

   ```bash
   openclaw gateway restart
   ```

4. Confirm via `openclaw hooks list` that the `mem0-auto-capture` hook is ready.

## Testing & troubleshooting

- Logs are prefixed with `[mem0-...]` (e.g., `[mem0-auto-capture]`, `[mem0-auto-recall]`, `[mem0-stt]`). If something silently fails, check `/tmp/openclaw/...` logs for those tags.
- Use `openclaw hooks simulate message` (or your own integration tests) to feed the hook a fake event and watch the HTTP calls.
- If the hook can’t reach Mem0, the recall/capture branches simply log errors and continue; the agent still runs but without those enhancements.

## What’s in the repo

- `hook/handler.ts` — the TypeScript entry point that implements capture, recall, STT, and caching.
- `package.json` + `tsconfig.json` — minimal metadata so other developers can install dependencies and build if needed.
- `README.md` & `PROJECT.md` — explain intent, configuration, and deployment.

## Next steps
- Tag releases (e.g., `v1.0.0`) and push to Git so you can `openclaw hooks install` directly from the repo.
- Automate builds/tests if you plan to extend the hook (e.g., add unit tests around the Mem0 request helpers).
- If you want the hook to share code with other Mem0 extensions, consider turning it into a proper plugin that registers both the hook and helper tools.

Happy to help set up the Git repo or draft a release template—shall I do that next?