mem0-auto-capture-hook

mem0-auto-capture hook

Version: v1.0.1

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 POSTs the current user input plus the previous assistant reply to <baseUrl>/memories with the resolved user id. It deduplicates captures by hashing the payload and short-circuiting identical sends within one minute.

2. Auto-Recall — before the agent answers (on the preprocessed or transcribed event) it queries <baseUrl>/memories/search (conversational memory only), filters by rerank score, and injects [MEMORY - Personal] into bodyForAgent. Knowledge base retrieval is now tool-only.

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.

4. Cron sessions — the hook now detects session keys that begin with main:main:cron: and skips the auto-recall injection for those jobs so scheduled tasks stay free of [MEMORY – Personal] text. When that happens you’ll see [mem0] auto-recall-skip-cron {…} in the logs with a short snippet of the cron’s output.

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.
debugCapture	MEM0_DEBUG_CAPTURE	false	When true, logs full outgoing messages payload for capture; otherwise logs only summary counts.

Example ~/.openclaw/mem0.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 ```

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

Testing & troubleshooting

• Logs flow through a single helper and now print as [mem0] <tag> {...} (e.g., [mem0] auto-recall-query, [mem0] auto-capture, [mem0] auto-recall-injection). Filter on the tag to track capture/recall steps in /tmp/openclaw/... logs.
• 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.

Recent implementation notes

• Assistant lookup: auto-capture grabs the previous assistant reply by scanning the session JSONL (via sessions.json) for the last assistant message before the current user event. It falls back to /tmp/openclaw-chat.log only if the session file is unavailable.
• Capture payload shape: auto-capture sends messages: [...] to /memories in all cases. Minimum payload is one user item; assistant entry is appended when available.
• Personal memory age prefix: injected [MEMORY - Personal] lines prepend age from created_at when present (for example [25m ago] / [1d ago]).

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?