[codex] add mem0 memory plugin

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Coming up]
 
+### Added
+
+- **Mem0 memory plugin**: Added a bundled `mem0-memory` plugin so local
+  HybridClaw installs can mirror turns into Mem0 cloud memory, inject
+  prompt-time Mem0 recall, expose `mem0_*` tools, and mirror explicit native
+  memory writes back into Mem0.
+
 ## [0.12.3](https://github.com/HybridAIOne/hybridclaw/tree/v0.12.3)
 
 ### Added

README.md

@@ -159,6 +159,7 @@ Browse the full manual at
   [Bundled Skills](https://www.hybridclaw.io/docs/guides/bundled-skills),
   [Plugin System](https://www.hybridclaw.io/docs/extensibility/plugins),
   [GBrain Plugin](https://www.hybridclaw.io/docs/extensibility/gbrain-plugin),
+  [Mem0 Memory Plugin](https://www.hybridclaw.io/docs/extensibility/mem0-memory-plugin),
   [Honcho Memory Plugin](https://www.hybridclaw.io/docs/extensibility/honcho-memory-plugin), and
   [MemPalace Memory Plugin](https://www.hybridclaw.io/docs/extensibility/mempalace-memory-plugin)
 - Configuration:

docs/development/agents.md

@@ -44,6 +44,7 @@ Main docs landing pages:
 - [Adaptive Skills](./extensibility/adaptive-skills.md)
 - [Agent Packages](./extensibility/agent-packages.md)
 - [Honcho Memory Plugin](./extensibility/honcho-memory-plugin.md)
+- [Mem0 Memory Plugin](./extensibility/mem0-memory-plugin.md)
 - [MemPalace Memory Plugin](./extensibility/mempalace-memory-plugin.md)
 - [OTEL Plugin](./extensibility/otel-plugin.md)
 - [Plugins](./extensibility/plugins.md)

docs/development/extensibility/README.md

@@ -20,7 +20,7 @@ operate at different layers, and are designed to complement each other.
 | **Install** | Ship with the codebase | Drop a `SKILL.md` file | `hybridclaw plugin install` or drop a directory |
 | **Hot reload** | Requires rebuild | Immediate (loaded per turn) | `/plugin reload` in session |
 | **Config needed** | Code change | None | `hybridclaw.plugin.yaml` manifest |
-| **Example** | `read`, `write`, `web_fetch`, `bash` | `pdf`, `github-pr-workflow`, `notion` | `gbrain`, `honcho-memory` |
+| **Example** | `read`, `write`, `web_fetch`, `bash` | `pdf`, `github-pr-workflow`, `notion` | `gbrain`, `honcho-memory`, `mem0-memory` |
 
 ## Tools (Container Runtime)
 
@@ -100,7 +100,7 @@ register runtime surfaces through the `HybridClawPluginApi`:
 **When to use:**
 - You need a tool that calls an external API (no sandbox restrictions needed)
 - You want to integrate an external memory or context system (e.g., Honcho,
-  LanceDB)
+  Mem0, LanceDB)
 - You need to react to lifecycle events (session start/end, tool calls,
   compaction)
 - You want to distribute an extension as a standalone package

docs/development/extensibility/honcho-memory-plugin.md

@@ -447,7 +447,7 @@ The usual first-run flow is:
 If you already have useful context in `SOUL.md`, `IDENTITY.md`, `USER.md`, or
 `MEMORY.md`, the setup step will seed that data into Honcho on demand.
 
-## Tips And Tricks
+## Tips & Tricks
 
 - Use the defaults first. In most cases, `/secret set HONCHO_API_KEY ...` plus
   `/honcho setup` is enough to get started.

docs/development/extensibility/mem0-memory-plugin.md

@@ -0,0 +1,160 @@
+---
+title: Mem0 Memory Plugin
+description: Setup and behavior for the bundled `mem0-memory` plugin.
+sidebar_position: 3
+---
+
+# Mem0 Memory Plugin
+
+HybridClaw ships a bundled Mem0 memory provider at
+[`plugins/mem0-memory`](https://github.com/HybridAIOne/hybridclaw/tree/main/plugins/mem0-memory).
+
+The plugin keeps HybridClaw's built-in memory active and layers Mem0 cloud
+recall on top. It can:
+
+- inject prompt-time Mem0 profile and semantic-search context
+- expose direct `mem0_profile`, `mem0_search`, and `mem0_conclude` tools
+- expose a `/mem0 ...` command surface in local sessions
+- mirror completed turns into Mem0 under the active HybridClaw user and agent
+- mirror explicit native memory writes back into Mem0 as durable conclusions
+
+## Requirements
+
+- a Mem0 API key from [app.mem0.ai](https://app.mem0.ai/dashboard/api-keys)
+- local plugin install so the plugin-local `mem0ai` dependency is available
+
+## Install
+
+```bash
+hybridclaw plugin install ./plugins/mem0-memory --yes
+hybridclaw plugin enable mem0-memory
+```
+
+Then configure the API key:
+
+```text
+/secret set MEM0_API_KEY your-mem0-key
+/plugin reload
+```
+
+## Minimal Config
+
+```json
+{
+  "plugins": {
+    "list": [
+      {
+        "id": "mem0-memory",
+        "enabled": true,
+        "config": {
+          "host": "https://api.mem0.ai",
+          "apiVersion": "v2",
+          "searchLimit": 5,
+          "profileLimit": 10
+        }
+      }
+    ]
+  }
+}
+```
+
+Useful optional keys:
+
+- `organizationId`: pin the plugin to a specific Mem0 organization
+- `projectId`: pin the plugin to a specific Mem0 project
+- `userId`: override HybridClaw's per-session user id
+- `agentId`: override HybridClaw's active agent id
+- `appId`: defaults to `hybridclaw`
+- `prefetchRerank`: rerank prompt-time Mem0 searches
+- `syncTurns`: disable automatic turn mirroring when set to `false`
+- `mirrorNativeMemoryWrites`: disable explicit native-memory mirroring when set
+  to `false`
+
+## Commands
+
+The plugin registers `/mem0` with these subcommands:
+
+- `/mem0 status`
+- `/mem0 profile`
+- `/mem0 search <query>`
+- `/mem0 conclude <fact>`
+
+Examples:
+
+```text
+/mem0 status
+/mem0 profile
+/mem0 search dark mode
+/mem0 conclude User prefers short status updates.
+```
+
+## Tools
+
+The plugin registers these tools:
+
+- `mem0_profile`
+- `mem0_search`
+- `mem0_conclude`
+
+Use `mem0_search` for targeted recall, `mem0_profile` for a broader snapshot,
+and `mem0_conclude` only for durable facts or corrections worth keeping across
+sessions.
+
+## Runtime Behavior
+
+When enabled with a configured `MEM0_API_KEY`:
+
+1. The plugin runs a Mem0 health check on startup.
+2. Before prompts, it fetches a profile snapshot and searches Mem0 using the
+   latest user message.
+3. After each completed turn, it mirrors user and assistant messages into Mem0.
+4. When HybridClaw writes native memory files such as `USER.md`, it mirrors the
+   explicit write into Mem0 as a durable conclusion.
+
+Read-side Mem0 recall is scoped to the current HybridClaw user id by default.
+Write-side sync uses the current HybridClaw user id plus the active agent id so
+Mem0 keeps attribution data.
+
+## Verification
+
+1. Install and enable the plugin.
+2. Set `MEM0_API_KEY`.
+3. Run `/mem0 status` and confirm `Connection: ok`.
+4. Chat for a turn, then run `/mem0 search <a fact from that turn>`.
+5. Save an explicit native memory fact, then run `/mem0 search <that fact>`.
+
+Expected result: prompt-time recall includes Mem0 context, `/mem0 search ...`
+returns stored memories, and explicit native memory writes appear in later Mem0
+search results.
+
+## Tips & Tricks
+
+- Leave `userId` and `agentId` unset unless you have a deliberate cross-session
+  routing plan. The defaults follow HybridClaw's active user and agent scope.
+- Keep `apiVersion: v2` unless you have a concrete compatibility reason to use
+  `v1`; the plugin is tuned around Mem0's newer filtered read path.
+- Use `mem0_profile` first when you want a broad snapshot, and `mem0_search`
+  for narrower questions. That keeps prompt and tool usage more predictable.
+- Keep `syncTurns` enabled for normal operation, but temporarily disable it if
+  you want read-only Mem0 recall during debugging or rollout.
+- Keep `mirrorNativeMemoryWrites` enabled when you want explicit `USER.md` or
+  `MEMORY.md` saves to become durable Mem0 facts without extra manual steps.
+
+## Troubleshooting
+
+- `/mem0 status` reports a missing API key:
+  set `MEM0_API_KEY` through `/secret`, then reload the plugin. The plugin does
+  not read plaintext API keys from plugin config.
+- The plugin loads but prompt recall is empty:
+  verify the scoped Mem0 user id, then run `/mem0 profile` and `/mem0 search`
+  manually to determine whether the issue is missing stored memories or prompt
+  injection.
+- Search results look too broad or unrelated:
+  confirm you are using the intended HybridClaw user scope, and override
+  `userId` only when you intentionally want shared memory across sessions.
+- New turns are not showing up in Mem0:
+  check that `syncTurns` is still enabled and that `/mem0 status` reports a
+  healthy connection before assuming retrieval is broken.
+- Repo edits do not affect the installed plugin:
+  run `/plugin reinstall ./plugins/mem0-memory` and then `/plugin reload`
+  because reload alone uses the installed copy under `~/.hybridclaw/plugins/`.

docs/development/extensibility/mempalace-memory-plugin.md

@@ -505,6 +505,40 @@ Supported config keys:
 - `timeoutMs`: timeout for `status`, `wake-up`, and automatic search calls. The
   plugin gives `mine` a longer minimum timeout automatically.
 
+## Tips & Tricks
+
+- Start with CLI recall first. Run `mempalace status`, `mempalace wake-up`, and
+  `mempalace search ...` outside HybridClaw before tuning plugin config.
+- Keep `palacePath`, the CLI you test manually, and any optional MemPalace MCP
+  server pointed at the same palace or results will look inconsistent.
+- Use a smaller `saveEveryMessages` while testing so new turns show up in
+  MemPalace faster, then raise it again for normal usage.
+- Use `wakeUpWing`, `searchWing`, and `updateWing` when one palace contains
+  multiple projects or domains and broad recall starts pulling the wrong facts.
+- Let HybridClaw built-in memory keep operational scratch state. Use MemPalace
+  for broader external recall rather than forcing every short-lived note into
+  the palace.
+
+## Troubleshooting
+
+- `/mempalace status` works in your shell but the plugin still reports it as
+  missing:
+  point `plugin config mempalace-memory command /absolute/path/to/mempalace`
+  at the exact executable you tested manually.
+- Prompt recall is empty:
+  verify whether the plugin is using CLI fallback or an enabled MemPalace MCP
+  server, then test the corresponding path directly with `/mempalace search ...`
+  or `/mcp list`.
+- New chat turns are not appearing in MemPalace:
+  lower `saveEveryMessages`, confirm `sessionExportDir` is writable, and check
+  whether `mempalace mine ... --mode convos` succeeds for exported transcripts.
+- Retrieval seems to come from the wrong project:
+  tighten `wakeUpWing`, `searchWing`, `searchRoom`, or `updateWing` so the
+  plugin stops recalling across unrelated palace areas.
+- Repo edits do not affect the active plugin:
+  reinstall the repo-shipped copy with `/plugin reinstall ./plugins/mempalace-memory`
+  and then reload the plugin.
+
 ## What This Plugin Does Not Do
 
 This plugin is intentionally narrow. It does not:

docs/development/extensibility/plugins.md

@@ -19,6 +19,7 @@ hybridclaw plugin config example-plugin workspaceId workspace-a
 hybridclaw plugin install ./plugins/example-plugin
 hybridclaw plugin install ./plugins/gbrain
 hybridclaw plugin install ./plugins/honcho-memory
+hybridclaw plugin install ./plugins/mem0-memory
 hybridclaw plugin install ./plugins/mempalace-memory
 hybridclaw plugin install ./plugins/qmd-memory
 hybridclaw plugin install ./plugins/brevo-email
@@ -73,6 +74,9 @@ or change one top-level `plugins.list[].config` key without editing
   tools
 - `honcho-memory` mirrors HybridClaw turns into Honcho, injects prompt-time
   recall, and exposes direct Honcho tools while keeping built-in memory active
+- `mem0-memory` mirrors HybridClaw turns into Mem0 cloud memory, injects
+  prompt-time recall, and exposes direct `mem0_*` tools while keeping
+  built-in memory active
 - `mempalace-memory` layers MemPalace recall on top of native memory, mirrors
   turns back into MemPalace, and can route prompt-time retrieval through CLI
   helpers or an active `mempalace` MCP server

docs/development/extensibility/qmd-memory-plugin.md

@@ -149,6 +149,25 @@ alone does not pick up repo edits.
 - `/qmd embed` is an explicit passthrough command and can run much longer than
   the short background-search timeout.
 
+## Troubleshooting
+
+- QMD loads but prompt recall stays empty:
+  confirm the target docs are actually indexed, then inspect
+  `~/.hybridclaw/data/last_prompt.jsonl` to distinguish "plugin loaded but no
+  hits" from "plugin never ran".
+- `/qmd status` works but retrieval quality is poor:
+  switch between `query`, `search`, and `vsearch` deliberately instead of
+  assuming the default mode fits the collection you built.
+- Background retrieval times out:
+  increase `timeoutMs`, reduce the size of the indexed corpus, or use explicit
+  `/qmd ...` commands for longer-running operations.
+- Repo edits do not affect the installed plugin:
+  run `/plugin reinstall ./plugins/qmd-memory` and then `/plugin reload`;
+  reload alone only reuses the installed copy under `~/.hybridclaw/plugins/`.
+- Searches miss exact terms you know exist:
+  try `/qmd search <term>` first. If lexical search fails too, the issue is
+  likely indexing rather than prompt wording.
+
 ## Verifying Retrieval
 
 To verify that the plugin is both loaded and actively contributing context:

docs/static/docs.js

@@ -43,6 +43,10 @@ export const DEVELOPMENT_DOCS_SECTIONS = [
         title: 'Honcho Memory Plugin',
         path: 'extensibility/honcho-memory-plugin.md',
       },
+      {
+        title: 'Mem0 Memory Plugin',
+        path: 'extensibility/mem0-memory-plugin.md',
+      },
       {
         title: 'MemPalace Memory Plugin',
         path: 'extensibility/mempalace-memory-plugin.md',

plugins/mem0-memory/hybridclaw.plugin.yaml

@@ -0,0 +1,71 @@
+id: mem0-memory
+name: Mem0 Memory
+version: 0.1.0
+kind: memory
+memoryProvider: true
+description: Mirror HybridClaw turns into Mem0 cloud memory, inject prompt-time recall, and expose direct Mem0 memory tools.
+entrypoint: src/index.js
+credentials:
+  - MEM0_API_KEY
+configSchema:
+  type: object
+  additionalProperties: false
+  properties:
+    host:
+      type: string
+      default: https://api.mem0.ai
+    organizationId:
+      type: string
+    projectId:
+      type: string
+    appId:
+      type: string
+      default: hybridclaw
+    userId:
+      type: string
+    agentId:
+      type: string
+    apiVersion:
+      type: string
+      enum: [v1, v2]
+      default: v2
+    searchLimit:
+      type: number
+      default: 5
+      minimum: 1
+      maximum: 20
+    profileLimit:
+      type: number
+      default: 10
+      minimum: 1
+      maximum: 50
+    maxInjectedChars:
+      type: number
+      default: 4000
+      minimum: 500
+      maximum: 20000
+    messageMaxChars:
+      type: number
+      default: 4000
+      minimum: 200
+      maximum: 20000
+    timeoutMs:
+      type: number
+      default: 15000
+      minimum: 1000
+      maximum: 60000
+    prefetchRerank:
+      type: boolean
+      default: true
+    includeProfile:
+      type: boolean
+      default: true
+    includeSearch:
+      type: boolean
+      default: true
+    syncTurns:
+      type: boolean
+      default: true
+    mirrorNativeMemoryWrites:
+      type: boolean
+      default: true

plugins/mem0-memory/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "hybridclaw-plugin-mem0-memory",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "description": "HybridClaw memory plugin for Mem0 cloud recall and sync",
+  "engines": {
+    "node": "22.x"
+  },
+  "dependencies": {
+    "mem0ai": "^2.4.6"
+  }
+}