JDSS/mem0
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: align agent plugin guides with shared runtime behavior (#7269)

Browse Source
This commit is contained in:
Kartik
2026-09-09 01:03:26 +05:30
committed by GitHub
parent 73e7b8763a
commit 02f7a9b2c4
17 changed files with 146 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/changelog/sdk.mdx
+4 -3
View File
@@ -2066,7 +2066,7 @@ A full-featured command-line interface for Mem0, available in both Python and No
- Consolidated the coding-agent integrations into `integrations/agent-plugin-core/`: one Python runtime, one TypeScript utility library, and six canonical Python-plugin skill templates. Native adapters retain each host's event contracts and capabilities.
- Python plugins ship generated, self-contained `core/` and `skills/` directories. Builds validate portable schemas and skills, parse native JSON, and reject generated-file drift, missing files, stale generated files, and symlinks. TypeScript packages bundle the shared source into their distributable JavaScript and verify their entry points.
- Replaced the old `integrations/mem0-plugin/` layout with native host directories and one portable `integrations/mem0-agent-plugin/` package. Updated marketplace paths, installation guides, and integration-skill links. OpenCode now lives in `integrations/opencode-plugin/`.
- Native Python plugins expose one local, read-only `search_memories` MCP tool and six skills: search, remember, forget, status, pause, and resume. The shared search tool no longer accepts `run_id`; session IDs remain internal metadata. This local tool is separate from the hosted Mem0 MCP server's tool set.
- Native Python plugins expose one local, read-only `search_memories` MCP tool and six skills: search, remember, forget, status, pause, and resume. The shared search tool accepts optional `run_id` with every scope (`repo`, `dir`, and `mine`) to recall memories from a specific coding-agent session. Omitting it searches across sessions. This local tool is separate from the hosted Mem0 MCP server's tool set.
**Fixes:**
- Hooks, controls, MCP servers, and detached workers use the same host-specific data directory. Detached workers retain the host identity and telemetry source; `--plugin-data-dir` reaches the shared resolver.
@@ -2380,7 +2380,7 @@ Initial release of the Mem0 plugin for Claude Code and Cursor, followed by Codex
**Fixes:**
- Session-end extraction no longer appends a final answer already captured from the transcript while an earlier extraction was running.
- Existing repository memories remain searchable after the shared-ID change; explicit shared-memory deletion also covers the legacy ID. Background workers and control skills consistently use Claude's data directory.
- Receives the shared JSON-secret redaction and nested telemetry filtering fixes. The local search tool exposes query, result count, category, and scope without asking the agent for a session ID.
- Receives the shared JSON-secret redaction and nested telemetry filtering fixes. The local search tool exposes query, result count, category, scope, and optional `run_id` for session-specific recall across all scopes.
[#7203](https://github.com/mem0ai/mem0/pull/7203)
@@ -2435,7 +2435,7 @@ Initial release of the Mem0 plugin for Claude Code and Cursor, followed by Codex
**Packaging:**
- Generated from the shared Python runtime and skill templates. Builds validate the manifest, MCP configuration, skills, and generated-file consistency.
- Host lifecycle hooks and native Sidekick declarations remain in the native plugin packages; the portable package does not claim automatic lifecycle capture or host-specific subagent isolation.
- Host lifecycle hooks and native Sidekick declarations remain in the native plugin packages; the portable package does not provide automatic lifecycle capture or host-specific subagent isolation. Its bundled remember skill cannot persist a new memory on its own because the portable package has no capture hooks or write tool.
[#7203](https://github.com/mem0ai/mem0/pull/7203)
@@ -2680,6 +2680,7 @@ Existing memories written by the previous versions are not rewritten. If your me
**Fixes:**
- `openclaw mem0 status` handles an unconfigured installation without crashing and directs users to setup.
- Removed OpenClaw's separate 2,000-character extraction cutoff. Selected user and assistant messages retain their full redacted text; recent-message selection, earlier summary selection, and noise filtering still apply.
- Telemetry removes sensitive properties recursively and uses the shared failure-safe delivery implementation.
[#7203](https://github.com/mem0ai/mem0/pull/7203)
docs/integrations/antigravity.mdx
+7 -1
View File
@@ -78,7 +78,7 @@ The plugin translates Antigravity events into the shared Mem0 capture lifecycle.
|------|-------|-------------|
| **Invocation** | `PreInvocation` | Initializes the first invocation and recovers pending capture |
| **Post-tool** | `PostToolUse` | Records useful tool results and failures |
| **Stop** | `Stop` | Captures the completed exchange for a later session |
| **Stop** | `Stop` | Reads completed transcript messages and starts a background flush |
Recall is explicit through `search_memories` and the search skill. The current Antigravity adapter does not inject query-specific memory during `PreInvocation` because that event does not include the user's prompt.
@@ -106,6 +106,12 @@ MEM0_CWD="$PWD" agy
The adapter uses `MEM0_CWD` only when Antigravity omits the workspace. If neither value is available, it skips recall and capture instead of writing memories under an incorrect repository scope.
## Search and capture
The local `search_memories` tool accepts `query`, `top_k`, `category`, `scope` (`repo`, `dir`, or `mine`), and optional `run_id` with every scope. Use a known session ID to recall memories saved in that session; omit it to search across sessions. See [search scopes](/integrations/claude-code#search-scope) for the shared Python search contract, including legacy repository memory compatibility.
Captured prompts and responses retain their full redacted text without a per-message character cutoff. Large extraction inputs are split across requests without dropping message text; recall output and tool-result previews have separate limits.
## Troubleshooting
- **No tools appearing**: Restart your Antigravity session after installation
docs/integrations/claude-code.mdx
+6 -6
View File
@@ -42,14 +42,14 @@ claude plugin uninstall mem0@mem0-plugins # uninstall the plugin (keeps the
Once installed, memory works without any action from you:
- **Capture** happens in the background as you work. Hooks save user messages, Claude's answers, changed files, and test/build results locally. Nothing calls a model or slows your session.
- **Recall** happens automatically before Claude's first response in a new session. The plugin searches your memories with your prompt and injects up to five relevant ones.
- **Capture** happens in the background as you work. Hooks save user messages, Claude's answers, changed files, and test/build results locally. Capture records evidence locally; memory extraction runs through Mem0 in a background worker.
- **Recall** happens automatically before Claude's first response in a new session. If the first prompt has at least 20 characters, the plugin searches with that prompt and injects up to five relevant memories. For shorter prompts or later questions, use explicit search.
### Commands
| Command | What it does |
| --- | --- |
| `/mem0:search` | Search memories from earlier sessions. Supports `--top-k <n>`, `--category <name>`, and `--scope <repo\|dir\|mine>`. |
| `/mem0:search` | Search memories from earlier sessions. Supports `--top-k <n>`, `--category <name>`, `--scope <repo\|dir\|mine>`, and `--run-id <session-id>`. |
| `/mem0:status` | Check if memory is working: config, capture state, pending flushes, API key validity. |
| `/mem0:forget` | Delete your memories for this repo (shared project memory stays unless you pass `--include-project-memory`). |
| `/mem0:pause` | Pause memory capture. |
@@ -60,7 +60,7 @@ Categories for `--category`: `project_knowledge`, `decisions_and_constraints`, `
### Search tool
After the automatic first-prompt search, Claude can also call `search_memories` with a specific question, and you can run `/mem0:search` yourself. Explicit searches return up to 3 results by default (configurable to 20). All results are capped at 4,000 characters.
After the automatic first-prompt search, Claude can also call `search_memories` with a specific question, and you can run `/mem0:search` yourself. Explicit searches return up to 3 results by default (configurable to 20). The combined search output is capped at 4,000 characters by default, configurable with `max_context_chars`. This recall limit does not truncate captured messages sent for extraction.
### Sidekick agent
@@ -80,7 +80,7 @@ At startup, Sidekick receives the memories already recalled for its parent sessi
The plugin follows a simple cycle: capture during a session, extract memories in the background, recall in the next session.
<Frame>
<img src="/images/plugin-sequence.svg" alt="Sequence diagram: session start triggers first-prompt search, hooks capture activity during the session, a background worker extracts memories after every five exchanges or on idle/exit, and the next session recalls them." />
<img src="/images/plugin-sequence.svg" alt="Sequence diagram: the first user prompt triggers search, hooks capture activity during the session, a background worker extracts memories after every five exchanges or on idle/exit, and the next session recalls them." />
</Frame>
**Step by step:**
@@ -153,7 +153,7 @@ Breaking update. Your memories carry over, most local config does not.
- **Commands replaced.** Old commands replaced by `/mem0:search`, `/mem0:status`, `/mem0:forget`, `/mem0:pause`, `/mem0:resume`, `/mem0:remember`.
- **MCP server replaced.** Nine read/write tools replaced by the single read-only `search_memories` tool.
- **Local config ignored.** `~/.mem0/settings.json` and per-project `mem0.md` files are no longer read.
- **Old memories searchable, not by category.** Normal search finds pre-upgrade memories, but category filters do not.
- **Old memories remain searchable.** Pre-upgrade memories may use different categories. Omit category filters if an older memory is missing from the results.
```bash
claude plugin marketplace update mem0-plugins
docs/integrations/codex.mdx
+14 -8
View File
@@ -3,7 +3,7 @@ title: Codex
description: "Add persistent memory to OpenAI Codex with automatic capture, automatic recall, a search tool, and six memory skills."
---
Add persistent memory to [**OpenAI Codex**](https://openai.com/index/codex/) with the Mem0 plugin. Codex forgets everything between tasks. This plugin fixes that by connecting to Mem0's cloud memory layer via MCP, automatically capturing learnings at key lifecycle points, and retrieving relevant context before every response.
Add persistent memory to [**OpenAI Codex**](https://openai.com/index/codex/) with the Mem0 plugin. Codex forgets everything between tasks. This plugin fixes that by connecting to Mem0's cloud memory layer via MCP, automatically capturing learnings at key lifecycle points, and retrieving relevant context on the first prompt of a session. Codex can use the search tool for recall later in the session.
<Info>Current plugin version: `0.3.1`.</Info>
@@ -79,7 +79,7 @@ bearer_token_env_var = "MEM0_API_KEY"
Make sure `MEM0_API_KEY` is exported in the shell you launch Codex from, then restart Codex.
This gives you the MCP tools but not the lifecycle hooks or SDK skill.
This gives you the hosted MCP tools but not the plugin's lifecycle hooks or six memory skills.
### Managing the Plugin
@@ -115,7 +115,7 @@ Lifecycle hooks that shell out to local scripts (Option A) are not applicable in
| Native subagent memory lifecycle | Yes | No |
| Memory skills | 6 | No |
Codex plugins cannot currently bundle a named custom agent. If you define project or user agents under `.codex/agents/` or `~/.codex/agents/`, the full Mem0 plugin gives every native subagent the parent turn's retrieved memory context and records its completed result.
Mem0's Codex package does not bundle a named custom agent. If you define project or user agents under `.codex/agents/` or `~/.codex/agents/`, the full Mem0 plugin gives every native subagent the parent turn's retrieved memory context and records its completed result.
## Direct MCP tools
@@ -139,8 +139,8 @@ Option A registers the hooks with the plugin. No separate hook installer or glob
| Hook | Event | What it does |
|------|-------|-------------|
| **Session start** | `SessionStart` | Loads prior memories and displays status banner |
| **User prompt** | `UserPromptSubmit` | Searches relevant memories before each message |
| **Session start** | `SessionStart` | Initializes the project session and recovers pending capture |
| **User prompt** | `UserPromptSubmit` | Records each prompt; searches on the first prompt when it has at least 20 characters |
| **Post-tool** | `PostToolUse` | Records useful tool outcomes for the completed exchange |
| **Subagent start** | `SubagentStart` | Reuses the parent turn's retrieved memory context in the child |
| **Subagent stop** | `SubagentStop` | Records the child transcript path and completed result |
@@ -148,18 +148,18 @@ Option A registers the hooks with the plugin. No separate hook installer or glob
| **Pre-compact** | `PreCompact` | Flushes pending capture before context compaction |
| **Session end** | `SessionEnd` | Flushes any remaining capture in the background |
What you type is stored as yours. What Codex produces (session summaries and compaction summaries) is stored as the assistant's, so its suggestions never become your stated preferences.
What you type is stored as yours. Codex's captured responses are stored as the assistant's, so its suggestions never become your stated preferences.
## Example Workflow
```text
# Task 1: Setting up a new service
You: Create a REST API for the notifications service using Express and TypeScript.
You: Create a REST API for the notifications service using Express and TypeScript. Prefer explicit error types over generic catch-all handlers.
# Codex searches memories, finds your preferences from prior tasks.
# Mem0 stores what you said as yours:
# - Your preference: "Prefers explicit error types over generic catch-all"
# ...and what Codex did as the assistant's, in the session summary:
# ...and completed work reported by Codex as the assistant's:
# - Decision: "Notifications service uses Express + TypeScript + Zod validation"
# - Convention: "All API routes follow /api/v1/{resource} pattern"
@@ -170,6 +170,12 @@ You: Add WebSocket support for real-time notification delivery.
# Follows the same patterns established in the first task.
```
## Search and capture
The local `search_memories` tool accepts `query`, `top_k`, `category`, `scope` (`repo`, `dir`, or `mine`), and optional `run_id` with every scope. Use a known session ID to recall memories saved in that session; omit it to search across sessions. See [search scopes](/integrations/claude-code#search-scope) for the shared Python search contract, including legacy repository memory compatibility.
Captured prompts and responses retain their full redacted text without a per-message character cutoff. Large extraction inputs are split across requests without dropping message text; recall output and tool-result previews have separate limits.
## Troubleshooting
- **"Connection failed"**: Verify `MEM0_API_KEY` is set: `echo $MEM0_API_KEY`
docs/integrations/cursor.mdx
+7 -1
View File
@@ -139,7 +139,7 @@ Cursor's `subagentStart` hook also cannot inject parent context. The bundled Sid
```text
# Session 1: Debugging a performance issue
You: The API endpoint /users is taking 3 seconds. Help me optimize it.
You: The API endpoint /users is taking 3 seconds. Help me optimize it. Prefer query-level fixes over caching.
# Cursor agent searches memories, proceeds with investigation.
# Mem0 stores what you said as yours:
@@ -155,6 +155,12 @@ You: The /orders endpoint is also slow, same pattern as before.
# Immediately checks for N+1 queries and missing indexes.
```
## Search and capture
The local `search_memories` tool accepts `query`, `top_k`, `category`, `scope` (`repo`, `dir`, or `mine`), and optional `run_id` with every scope. Use a known session ID to recall memories saved in that session; omit it to search across sessions. See [search scopes](/integrations/claude-code#search-scope) for the shared Python search contract, including legacy repository memory compatibility.
Captured prompts and responses retain their full redacted text without a per-message character cutoff. Large extraction inputs are split across requests without dropping message text; recall output and tool-result previews have separate limits.
## Troubleshooting
- **"Connection failed"**: Verify `MEM0_API_KEY` is set: `echo $MEM0_API_KEY`
docs/integrations/deepseek-plugin.mdx
+2 -2
View File
@@ -18,7 +18,7 @@ The plugin provides automatic memory plus two agent-callable tools:
| `search_memory` | Recall facts from Mem0 relevant to a query |
| `add_memory` | Store a fact in Mem0 for future sessions |
Unlike file-based memory plugins, Mem0 is a managed backend: server-side extraction, semantic dedup, and conflict resolution, with the same memory reusable across every agent you connect.
Unlike file-based memory plugins, Mem0 is a managed backend: server-side extraction, semantic dedup, and conflict resolution, with memories reusable by integrations that use compatible user identities and search filters.
## How it works
@@ -108,7 +108,7 @@ For a Mem0 Platform on-prem or dedicated deployment, point `config.host` at that
| `autoRecall` | no | `true` | Recall relevant memory before model requests |
| `autoCapture` | no | `true` | Store completed human and assistant turns |
Both tools also accept optional per-call `userId`, `agentId`, and `runId` params so a single install can partition memory by entity, agent, or session; when omitted they fall back to the configured `userId`.
Both tools also accept optional per-call `userId`, `agentId`, and `runId` params so a single install can partition memory by entity, agent, or session; `userId` defaults to the configured user, while `agentId` and `runId` are omitted unless supplied. Automatic recall and capture use the configured user without an agent, repository, or session filter. Automatic capture preserves full redacted user and assistant message text without a per-message character cutoff.
## Telemetry
docs/integrations/kimi.mdx
+9 -3
View File
@@ -38,7 +38,7 @@ Run `/plugins info mem0` to confirm that the plugin, MCP server, skills, hooks,
## What you get
- **Automatic capture:** Kimi records completed exchanges locally and flushes durable project knowledge to Mem0 in the background.
- **Automatic recall:** Relevant memories are added before Kimi answers the first prompt in a session.
- **Automatic recall:** Relevant memories are added before Kimi answers the first prompt in a session, if that prompt has at least 20 characters.
- **Explicit search:** Kimi can call `search_memories` when it needs a more specific answer.
- **Six memory skills:** Search, status, remember, forget, pause, and resume use the same memory behavior as the other Mem0 coding-agent plugins.
- **Project scoping:** Memories stay attached to the repository, with separate personal and shared project lanes.
@@ -52,8 +52,8 @@ Kimi's native lifecycle events are translated into the shared Mem0 memory lifecy
| Kimi event | What Mem0 does |
| --- | --- |
| `SessionStart` | Loads recent project context |
| `UserPromptSubmit` | Searches for relevant memories before the response |
| `SessionStart` | Initializes the project session and recovers pending capture |
| `UserPromptSubmit` | Records each prompt; searches on the first prompt when it has at least 20 characters |
| `PostToolUse` / `PostToolUseFailure` | Records useful tool results and failures |
| `Stop` | Captures the completed exchange |
| `PreCompact` / `SessionEnd` | Flushes pending capture in the background |
@@ -87,6 +87,12 @@ Kimi should return `ORCHID-9274` from memory.
Run `/reload` or start a new session after enabling, disabling, or reinstalling the plugin.
## Search and capture
The local `search_memories` tool accepts `query`, `top_k`, `category`, `scope` (`repo`, `dir`, or `mine`), and optional `run_id` with every scope. Use a known session ID to recall memories saved in that session; omit it to search across sessions. See [search scopes](/integrations/claude-code#search-scope) for the shared Python search contract, including legacy repository memory compatibility.
Captured prompts and responses retain their full redacted text without a per-message character cutoff. Large extraction inputs are split across requests without dropping message text; recall output and tool-result previews have separate limits.
## Troubleshooting
| Problem | Fix |
docs/integrations/openclaw.mdx
+3 -3
View File
@@ -343,8 +343,8 @@ openclaw mem0 status --json
|-----|------|---------|-------------|
| `mode` | `"platform"` \| `"open-source"` | `"platform"` | Which backend to use |
| `userId` | `string` | OS username | Scope memories per user |
| `autoRecall` | `boolean` | `true` | Inject memories before each turn. Ignored when `skills` is configured. |
| `autoCapture` | `boolean` | `true` | Store facts after each turn. Ignored when `skills` is configured. |
| `autoRecall` | `boolean` | `true` | Inject memories before each turn, including when skills mode is configured. |
| `autoCapture` | `boolean` | `true` | Store facts after each turn, including when skills mode is configured. |
| `topK` | `number` | `5` | Max memories per recall |
| `searchThreshold` | `number` | `0.3` | Min similarity (0–1) |
@@ -443,7 +443,7 @@ If `openclaw plugins update` fails:
### Auto-Capture and Auto-Recall
Auto-capture and auto-recall are **enabled by default**. When skills mode is configured (the default after `openclaw mem0 init`), these are ignored in favor of the skills-based triage and recall protocol.
Auto-capture and auto-recall are **enabled by default**. They also run when skills mode is configured (the default after `openclaw mem0 init`). Set `autoRecall` or `autoCapture` to `false` to disable the corresponding automatic hook while using skills.
To disable either:
docs/integrations/opencode.mdx
+4 -2
View File
@@ -113,13 +113,15 @@ The plugin uses the [mem0ai](https://www.npmjs.com/package/mem0ai) TypeScript SD
| OpenCode Event | Hook | What happens |
|----------------|------|-------------|
| `config` | **Config** | Registers the `/mem0-*` slash commands (`config.command`) and adds the plugin's own `opencode-skills/` dir to OpenCode's `skills.paths` for in-place skill discovery (no copying) |
| `chat.message` | **Chat message** | Searches prior memories on session start, searches relevant memories before each prompt, auto-captures learnings periodically |
| `chat.message` | **Chat message** | Searches prior memories on session start, searches relevant memories before each prompt, sends every third qualifying user prompt for extraction |
| `tool.execute.before` | **Pre-tool** | Blocks MEMORY.md writes, steering them to the `add_memory` tool |
| `tool.execute.after` | **Post-tool** | Scans Bash errors and pre-fetches related error memories |
| `experimental.chat.messages.transform` | **Messages transform** | Injects memory context (session memories, search results, error lookups) into the prompt |
| `experimental.session.compacting` | **Compaction** | Stores session state memory, then injects prior memories into compaction context so nothing is lost |
| `experimental.session.compacting` | **Compaction** | Stores session state memory, then injects prior memories into compaction context |
| `shell.env` | **Shell env** | Exports `MEM0_USER_ID`, `MEM0_APP_ID`, `MEM0_SESSION_ID`, and `MEM0_BRANCH` to all shell executions |
Automatic capture sends the selected user prompt with its full redacted text, without a per-message character cutoff. It does not capture every prompt or the full assistant transcript. These automatic writes use user and project scope, with the session ID in `metadata.session_id`; session-scoped tools use top-level `run_id`. A session-scoped search therefore does not include automatic writes that lack `run_id`.
## Troubleshooting
- **No tools appearing**: Restart OpenCode after installing
docs/integrations/pi-agent.mdx
+6 -6
View File
@@ -11,7 +11,7 @@ Add persistent memory to [**Pi Agent**](https://pi.dev) with `@mem0/pi-agent-plu
The plugin provides:
1. **Auto-capture**: Extracts durable facts from both user and assistant messages automatically
2. **Semantic recall**: Retrieves relevant memories via the `mem0_memory` tool before each response
2. **Semantic recall**: Automatically searches project memories before each agent turn; `mem0_memory` supports additional explicit searches
3. **Monorepo-aware scoping**: Uses git root for project detection, consistent across subdirectories
4. **Confirmation dialogs**: Destructive commands ask before acting via Pi's built-in UI
5. **6 skills + 6 commands**: Essential memory management from slash commands and agent-guided workflows
@@ -117,10 +117,12 @@ Memories are scoped using Mem0's `user_id`, `app_id`, and `run_id` parameters:
| Scope | Filters | Use Case |
|-------|---------|----------|
| `project` | user_id + app_id (git root) | **Default.** Project-specific knowledge: decisions, architecture, config |
| `session` | user_id + app_id + run_id | Ephemeral context for the current session only |
| `session` | user_id + app_id + run_id | Memories saved with the current session ID (no automatic expiration) |
| `global` | user_id only | All memories across all your projects |
The `app_id` is auto-detected from the git repository root (`git rev-parse --show-toplevel`), so all subdirectories within a monorepo share the same memory pool. Falls back to the working directory name for non-git directories. The `run_id` is derived from Pi's session file path.
The `app_id` is auto-detected from the git repository root (`git rev-parse --show-toplevel`), so all subdirectories within a monorepo share the same memory pool. Falls back to the working directory name for non-git directories. The `run_id` is derived from Pi's session file path. Automatic recall and capture use project scope, regardless of `defaultScope`; automatic writes do not include `run_id`. Use session-scoped tools or commands to save and recall session-specific memories. Captured user and assistant message text is redacted without a per-message character cutoff.
Global tool operations require `/mem0-scope global` or `defaultScope: "global"` in plugin configuration. A model-supplied `scope` argument cannot enable cross-project access on its own. Empty or wildcard user, project, and session identities are rejected.
## Confirmation Dialogs
@@ -144,7 +146,7 @@ You: What do you know about my preferences?
## Troubleshooting
- **"No API key found"**: Verify `MEM0_API_KEY` is set: `echo $MEM0_API_KEY`. If empty, add it to your shell profile (see Prerequisites)
- **Extension not loading**: Check Pi startup output for errors. Run `pi -e ./src/entry.ts` from the plugin directory for verbose output
- **Extension not loading**: Check Pi startup output for errors. For a source checkout, run `pnpm build`, then `pi -e ./dist/entry.js` from the plugin directory
- **Memories not capturing**: Verify `autoCapture` is `true` (default). Check `/mem0-status` for connection health
- **Wrong project detected**: The plugin uses the git repository root as `app_id`. If not in a git repo, it falls back to the working directory name. Run `/mem0-status` to see the detected project
@@ -158,5 +160,3 @@ You: What do you know about my preferences?
</CardGroup>
<Snippet file="star-on-github.mdx" />
Global tool operations require `/mem0-scope global` or `defaultScope: "global"` in plugin configuration. A model-supplied `scope` argument cannot enable cross-project access on its own. Empty or wildcard user, project, and session identities are rejected.
docs/llms.txt
+4 -4
View File
@@ -267,7 +267,7 @@ If the user is on a pre-current major (Python < 2, TS < 3, or a Platform call st
- [Strands Agents](https://docs.mem0.ai/integrations/strands) [Both]: Use when the user is on AWS Strands and wants a native MemoryStore.
### AI Coding Tools
- [Claude Code](https://docs.mem0.ai/integrations/claude-code) [Both]: Use when wiring memory into Claude Code.
- [Claude Code](https://docs.mem0.ai/integrations/claude-code) [Platform]: Use when wiring memory into Claude Code.
- [Claude.ai](https://docs.mem0.ai/integrations/claude-ai) [Platform]: Use when connecting Mem0 to Claude.ai (the hosted web app) via a custom remote MCP connector, or when Claude's native memory seems to be crowding out mem0 tool calls.
- [Cursor](https://docs.mem0.ai/integrations/cursor) [Platform]: Use when adding lifecycle capture, explicit memory recall, six skills, and a sidekick to Cursor.
- [Codex](https://docs.mem0.ai/integrations/codex) [Platform]: Use when adding automatic capture and recall, six memory skills, and a search tool to OpenAI Codex.
@@ -418,17 +418,17 @@ Each subdirectory is a Claude Code Skill (`SKILL.md` + supporting assets). Load
Source: https://github.com/mem0ai/mem0/tree/main/integrations/claude-code-plugin
The self-contained Claude Code plugin lives in `integrations/claude-code-plugin/` (v0.3.0, installs as `mem0@mem0-plugins`). It captures evidence locally through lifecycle hooks, extracts memories in a detached background worker, and exposes a single local MCP tool, `search_memories`, plus six `/mem0:*` skills and the unchanged `mem0:sidekick` agent. Pure-stdlib Python, nothing to install.
The self-contained Claude Code plugin lives in `integrations/claude-code-plugin/` (v0.3.1, installs as `mem0@mem0-plugins`). It captures evidence locally through lifecycle hooks, extracts memories in a detached background worker, and exposes a single local MCP tool, `search_memories`, plus six `/mem0:*` skills and the unchanged `mem0:sidekick` agent. Pure-stdlib Python, nothing to install.
### Coding-Agent Plugin Sources
Source: https://github.com/mem0ai/mem0/tree/main/integrations/agent-plugin-core
The `integrations/agent-plugin-core/` directory is the single source for shared Python and TypeScript memory behavior. Native plugins live in their own sibling directories, while `integrations/mem0-agent-plugin/` is the single portable Agent Plugins v1 package. TypeScript integrations reuse the core's lifecycle, formatting, identity, scoping, and telemetry utilities while keeping their public packages and native host APIs unchanged.
The `integrations/agent-plugin-core/` directory is the single source for shared Python and TypeScript memory behavior. Native plugins live in their own sibling directories, while `integrations/mem0-agent-plugin/` is the single portable Agent Plugins v1 package. The portable package provides search and skills but no automatic capture; its remember skill cannot save a new memory on its own. Shared Python search accepts optional `run_id` for session-specific recall in every scope. TypeScript integrations reuse the core's lifecycle, formatting, identity, scoping, and telemetry utilities while keeping their public packages and native host APIs unchanged.
Editor-specific setup docs (already listed above under `## Integrations > AI Coding Tools`):
- `integrations/claude-code` [Both]
- `integrations/claude-code` [Platform]
- `integrations/cursor` [Platform]
- `integrations/codex` [Platform]
- `integrations/kimi` [Platform]
integrations/agent-plugin-core/README.md
+22
View File
@@ -27,6 +27,28 @@ Claude Code remains the behavioral source of truth. Its sidekick stays at `claud
TypeScript integrations (`openclaw`, `opencode-plugin`, `pi-agent-plugin`, and `deepseek-plugin`) import `typescript/src/` at build time. Their package builders include the shared implementation in their normal output; they do not carry checked-in copies.
## Shared memory behavior
The six Python packages use the same `search_memories` MCP tool and six skill templates. Native hooks collect conversations and flush them to Mem0 in the background. The portable package uses the Agent Plugins v1 layout so compatible hosts can load its MCP server and skills. It has no lifecycle hooks or flush worker; its bundled `remember` skill assumes automatic capture and cannot save a memory on its own.
Python search accepts `query`, `top_k`, `category`, `scope`, and optional `run_id`:
| Scope | Memories searched |
| --- | --- |
| `repo` (default) | Shared repository memories and your personal memories in that repository |
| `dir` | Shared memories from the current directory and its children, plus your personal repository memories |
| `mine` | Your personal memories in that repository |
`run_id` filters any scope to memories saved in a known coding-agent session. Omit it for recall across sessions; it does not attribute the search request to the current session. Native Python extraction writes include the session's `run_id`.
New Git repository writes use a hashed remote identity for shared `agent_id`. Search and explicit shared-memory deletion include both that ID and the legacy unhashed ID under the same `app_id`. Legacy memories remain accessible, but their original ambiguity between matching owner/repository names on different Git hosts remains.
Captured prompts and responses preserve their full text after secret redaction. Python extraction splits oversized input across requests without dropping message text. The session-end worker flushes the conversation already collected by hooks without adding the final answer again. Search queries, retrieved context, and tool evidence have separate limits.
TypeScript hosts reuse redaction and lifecycle utilities but retain their own tools, scopes, and capture events. They do not inherit the Python `repo`/`dir`/`mine` contract or its background batching. OpenCode captures selected user prompts; Pi and DeepSeek capture completed conversation turns; OpenClaw selects recent messages and earlier summaries, then filters noise. Removing message-length truncation does not turn these integrations into complete transcript archives.
For installation, follow the host guides: [Claude Code](../../docs/integrations/claude-code.mdx), [Cursor](../../docs/integrations/cursor.mdx), [Codex](../../docs/integrations/codex.mdx), [Kimi](../../docs/integrations/kimi.mdx), and [Antigravity](../../docs/integrations/antigravity.mdx).
## Build and verify
From the repository root:
integrations/claude-code-plugin/README.md
+11 -7
View File
@@ -4,6 +4,8 @@ Persistent cross-session memory for Claude Code, plus a Sonnet sidekick agent fo
Claude Code forgets everything between sessions. This plugin fixes that: hooks capture session details locally, a background worker turns them into Mem0 memories, and Claude automatically gets the relevant ones back at the start of later sessions.
Current bundle version: `0.3.1`.
## Prerequisites
- Python 3.10+ and Git.
@@ -45,15 +47,17 @@ claude --plugin-dir integrations/claude-code-plugin
### Memory
1. **Capture.** Hooks save the main agent's activity locally: user messages, Claude's answers, changed file paths, and short test/build results. No model calls, no blocking. Sidekick output is excluded.
1. **Capture.** Hooks save the main agent's activity locally: user messages, Claude's answers, changed file paths, and short test/build results. Capture does not call a model. Sidekick assignments and completed responses are recorded separately as supporting evidence.
2. **Flush.** After every five completed exchanges, a detached background worker sends that batch to Mem0. Large exchanges flush sooner. Ending or compacting the session flushes anything remaining. If idle, an auto-flush runs after five minutes (configurable with `MEM0_CODE_IDLE_FLUSH_SECONDS`). The worker survives Claude Code exiting.
2. **Flush.** After every five completed exchanges, a detached background worker sends that batch to Mem0. Large exchanges flush sooner. Ending or compacting the session flushes anything remaining. The session-end worker sends the conversation already collected by hooks without recording the final answer again. If idle, an auto-flush runs after five minutes (configurable with `MEM0_CODE_IDLE_FLUSH_SECONDS`). The worker survives Claude Code exiting.
3. **Extract.** Each flush sends a single `add` call with `agent_id` (the project identity), `user_id` (you), `app_id` (the repository), and `run_id` (the session). Mem0 classifies each extracted memory as either:
3. **Extract.** Each flush sends one or more `add` calls with `agent_id` (the project identity), `user_id` (you), `app_id` (the repository), and `run_id` (the session). Mem0 classifies each extracted memory as either:
- **Shared project memory** (`agent_id`): one namespace per repo, scoped by `app_id`. Stores conventions, decisions, constraints, working commands, and failed commands with their fixes. Everyone on the repo reads and writes the same pool. Never carries a `user_id`. Directory information is stored in metadata for directory-scoped searches.
- **Personal memory** (`user_id`): your preferred tools, style, habits, and anything you asked to be remembered. Scoped to the repo by `app_id`. Private to you.
4. **Recall.** On the next session's first prompt, the plugin searches automatically and supplies up to five relevant memories. No model is called to write the query.
4. **Recall.** On the next session's first prompt, if it has at least 20 characters, the plugin searches automatically and supplies up to five relevant memories. No model is called to write the query.
Captured prompts and responses retain their full text after secret redaction. Oversized extraction input is split across requests without discarding message text. Search results and tool evidence still have separate size limits.
After that first search, Claude can call `search_memories` with a specific question, and you can run `/mem0:search` yourself. Explicit searches return up to 3 results by default (configurable to 20), capped at 4,000 characters.
@@ -88,7 +92,7 @@ By default the worktree branches from the repo's default branch. Set `worktree.b
| Command | What it does |
| --- | --- |
| `/mem0:search` | Search memories from earlier sessions. Accepts `--top-k <n>`, `--category <name>`, and `--scope <repo\|dir\|mine>`. |
| `/mem0:search` | Search memories from earlier sessions. Accepts `--top-k <n>`, `--category <name>`, `--scope <repo\|dir\|mine>`, and `--run-id <session-id>`. |
| `/mem0:status` | Check config, capture state, pending flushes, and API key validity. |
| `/mem0:forget` | Delete your memories for this repo (shared project memory stays unless you pass `--include-project-memory`). |
| `/mem0:pause` | Pause memory capture. |
@@ -105,7 +109,7 @@ Categories for `--category`: `project_knowledge`, `decisions_and_constraints`, `
| `dir` | Project memory from the current directory (and children), plus your preferences |
| `mine` | Your personal preferences only |
Set the default with the `search_scope` setting or `MEM0_CODE_SEARCH_SCOPE`. Search spans earlier sessions without a session ID; `run_id` remains internal metadata.
Set the default with the `search_scope` setting or `MEM0_CODE_SEARCH_SCOPE`. Pass optional `run_id` to `search_memories` (or `--run-id` to `/mem0:search`) with any scope to search memories saved in that session. Omit it to search across sessions. This filters the returned memories; it does not identify the session making the request. Use a known session ID.
New Git repository memories use a hash of the remote identity in `agent_id`. Searches also include the previous unhashed ID under the same repository `app_id`, so shared memories remain available after upgrading. Older IDs retain their original limitation: matching owner/repository names on different Git hosts share that legacy namespace. Local folders keep their path-based namespaces.
@@ -132,7 +136,7 @@ Local data lives in `${CLAUDE_PLUGIN_DATA}`:
- `plugin-errors.log`: hook errors (no credentials)
- `telemetry.jsonl` / `telemetry-identity.json`: anonymous usage events
Mem0 receives each block of user messages, Claude's answers, the sidekick's answer, and changed file paths. Complete files and general tool output stay on your machine. Values that look like credentials are redacted before anything is sent.
Mem0 receives captured user messages, Claude's answers, sidekick assignments and completed responses, and changed file paths. When a failed command is recorded, extraction can also include bounded command details and results. Complete files and general tool output stay on your machine. Values that look like credentials are redacted before anything is sent.
## Telemetry
integrations/deepseek-plugin/README.md
+13 -3
View File
@@ -11,7 +11,9 @@ It gives a Harness agent automatic long-term memory plus two explicit memory too
| `search_memory` | Recall facts from Mem0 relevant to a query |
| `add_memory` | Store a fact in Mem0 for future sessions |
Unlike the local/file-based memory plugins in the ecosystem, Mem0 is a managed backend: server-side extraction, semantic dedup and conflict resolution, and the same memory bank reusable across Harness, Claude Code, Codex, and other agents.
Unlike the local/file-based memory plugins in the ecosystem, Mem0 is a managed backend: server-side extraction, semantic dedup and conflict resolution, and memories that other agents can retrieve when their user and entity filters match.
Current package version: `0.3.0`.
## How it works
@@ -21,6 +23,8 @@ A Cordis plugin is a module exporting `apply(ctx, config)`. This one waits for t
- `session/event` captures only completed turns from the durable event stream.
- `ctx.tools.register(...)` exposes explicit search and add tools.
Completed human and assistant text is preserved after secret redaction, without the former 6,000-character per-message cutoff. Recall queries and displayed tool results retain separate size limits. These behaviors use [agent-plugin-core](../agent-plugin-core/README.md); this integration keeps its native tools and user-based scoping.
Cordis owns listener and tool cleanup when the plugin unmounts. Every automatic path is fail-open: a memory API failure does not block the agent.
```
@@ -70,6 +74,14 @@ For a Mem0 Platform on-prem or dedicated deployment, point `config.host` at that
| `autoRecall` | no | `true` | Recall relevant memory before model requests |
| `autoCapture` | no | `true` | Store completed human/assistant turns |
## Memory scope
Automatic capture and recall use the configured `userId` across sessions. Automatic writes do not attach a repository ID or `runId`.
Both `search_memory` and `add_memory` accept optional `agentId` and `runId`. On search, these narrow the returned memories; on add, they attach those identities to the stored memory. Pass a known `runId` to search memories explicitly saved with that session ID. This does not include automatically captured user-only memories or identify the session making the request.
Per-call `userId` overrides are rejected unless the operator enables `allowUserOverride: true`. Automatic recall and capture always use the configured user.
## Telemetry
Writes are tagged `source="DEEPSEEK_HARNESS"` so Mem0's backend can attribute usage to this integration. For it to surface by name (rather than bucketing into `OTHERS`), `DEEPSEEK_HARNESS` must be present in the backend's `KNOWN_EVENT_SOURCES` allowlist, a one-line platform change matching the existing `ZAPIER` / `STRANDS` sources.
@@ -79,5 +91,3 @@ The plugin also sends anonymous usage events (which tool ran, duration, result c
## Status
Developer preview. Tracks the DeepSeek Harness v0.1 plugin API, which is young and moving. Harness capability packages are peer dependencies supplied by the host; this package pins matching release-candidate versions for local typechecking and tests.
Per-call `userId` overrides are rejected unless the operator enables `allowUserOverride: true`. Automatic recall and capture always use the configured user.
integrations/openclaw/README.md
+9 -5
View File
@@ -6,6 +6,8 @@ Your agent forgets everything between sessions. This plugin fixes that — it st
By default, the plugin runs in **skills mode**: the agent controls what to remember (triage) and how to recall (recall). Skills mode, `autoRecall`, and `autoCapture` are all enabled by default during `openclaw mem0 init`.
Current package version: `1.1.0`. Shared redaction and lifecycle utilities come from [agent-plugin-core](../agent-plugin-core/README.md); OpenClaw keeps its own tools, skills, and memory scopes.
## Requirements
Check your OpenClaw version:
@@ -218,12 +220,14 @@ When skills mode is active, the skills handle memory operations. `autoRecall` an
### Auto-Recall & Auto-Capture
When skills mode is not configured, the plugin uses `autoRecall` and `autoCapture` (both enabled by default):
The plugin also registers `autoRecall` and `autoCapture` when their flags are enabled (both default to `true`), including alongside skills mode:
- **Auto-Recall** — Before the agent responds, the plugin searches Mem0 for relevant memories and injects them into context.
- **Auto-Capture** — After the agent responds, the conversation is filtered through a noise-removal pipeline and sent to Mem0. New facts get stored, stale ones updated, duplicates merged.
Set `autoRecall: false` or `autoCapture: false` to disable individually. The agent can also use memory tools (`memory_add`, `memory_search`, etc.) explicitly regardless of these settings.
Automatic capture selects a recent-message window and earlier assistant summaries, removes injected context and noise, and redacts secrets. Selected message text is no longer cut off at 2,000 characters. This preserves full redacted text for selected messages, not every message in the session. Capture skips non-interactive triggers, subagent sessions, and turns that already used memory mutation tools.
Set `autoRecall: false` or `autoCapture: false` to disable these automatic hooks individually. The agent can also use memory tools (`memory_add`, `memory_search`, etc.) explicitly regardless of these settings.
### Memory Scopes
@@ -293,8 +297,8 @@ openclaw mem0 help --json # discover all comma
| --- | ---- | ------- | ----------- |
| `mode` | `"platform"` \| `"open-source"` | `"platform"` | Backend mode |
| `userId` | `string` | OS username | User identifier. All memories scoped to this value. |
| `autoRecall` | `boolean` | `true` | Inject relevant memories before each turn. Ignored when `skills` is set. |
| `autoCapture` | `boolean` | `true` | Extract and store facts after each turn. Ignored when `skills` is set. |
| `autoRecall` | `boolean` | `true` | Inject relevant memories before each turn. Also runs when skills mode is enabled. |
| `autoCapture` | `boolean` | `true` | Extract and store facts after each turn. Also runs when skills mode is enabled. |
| `topK` | `number` | `5` | Max memories returned per recall |
| `searchThreshold` | `number` | `0.1` | Minimum similarity score (0-1) |
@@ -357,7 +361,7 @@ To avoid plaintext credentials:
In **skills mode** (default after `openclaw mem0 init`), the agent uses structured triage and recall protocols to decide what to store and recall. The built-in `session-memory` hook is disabled to avoid conflicts.
Without skills, `autoCapture` and `autoRecall` are both enabled by default:
`autoCapture` and `autoRecall` are both enabled by default, including alongside skills:
- `autoCapture`: sends conversation content to your configured backend after each agent turn
- `autoRecall`: queries your memory store before each agent turn and injects results into context
integrations/opencode-plugin/README.md
+14 -6
View File
@@ -2,6 +2,8 @@
Persistent memory for [OpenCode](https://opencode.ai). Your agent remembers decisions, preferences, and learnings across sessions automatically.
Current package version: `0.3.0`. This native TypeScript integration keeps its own tools and scopes while sharing redaction and lifecycle utilities with [agent-plugin-core](../agent-plugin-core/README.md).
## Install
```bash
@@ -28,7 +30,7 @@ Restart OpenCode.
| Component | Description |
|-----------|-------------|
| **9 Native Memory Tools** | `add_memory`, `search_memories`, `get_memories`, `update_memory`, `delete_memory`, and more — registered as OpenCode tools, backed by the `mem0ai` SDK (no MCP server required) |
| **10 Native Memory Tools** | `add_memory`, `search_memories`, `get_memories`, `update_memory`, `delete_memory`, and more — registered as OpenCode tools, backed by the `mem0ai` SDK (no MCP server required) |
| **Lifecycle Hooks** | Auto-search on session start and every prompt, error memory lookup, compaction context, secret redaction |
| **7 Skills** | `/mem0-remember`, `/mem0-tour`, `/mem0-search`, `/mem0-status`, `/mem0-scope`, `/mem0-forget`, `/mem0-context-loader` — discovered in place from the plugin via OpenCode's `skills.paths` |
@@ -43,7 +45,7 @@ Pure TypeScript — no Python, no shell scripts. Memory operations are native Op
| **Pre-tool** | `tool.execute.before` | Blocks MEMORY.md writes, steering them to the `add_memory` tool |
| **Post-tool** | `tool.execute.after` | Scans bash errors and pre-fetches related memories |
| **Messages transform** | `experimental.chat.messages.transform` | Injects memory context (session memories, search results, error lookups) into the prompt |
| **Compaction** | `experimental.session.compacting` | Stores session state memory, then injects prior memories into compaction context so nothing is lost |
| **Compaction** | `experimental.session.compacting` | Stores session state memory, then injects prior memories into compaction context |
| **Shell env** | `shell.env` | Exports `MEM0_USER_ID`, `MEM0_APP_ID`, `MEM0_SESSION_ID`, and `MEM0_BRANCH` to shell |
## Memory Tools
@@ -63,7 +65,7 @@ Pure TypeScript — no Python, no shell scripts. Memory operations are native Op
## Memory scope
Every memory tool accepts an optional `scope`, and you can set the **default**
`add_memory`, `search_memories`, `get_memories`, and `delete_all_memories` accept an optional `scope`. You can set the **default**
scope (used when none is passed) with the `/mem0-scope` skill:
| Scope | Reads | Writes |
@@ -83,6 +85,14 @@ fresh on each memory operation, so a change applies immediately — no restart.
`delete_all_memories` always requires an explicit `scope="global"` to delete
user-wide, so changing the default can't trigger a cross-project wipe.
## Capture and session context
Automatic capture saves every third qualifying user prompt. Other exchanges and assistant conclusions can be saved through `add_memory` or the remember skill; this is not a complete transcript recorder. Captured and explicitly saved text is redacted without the former 6,000-character cutoff.
Automatic capture uses the user and repository IDs, with the session ID in metadata. Explicit `session`-scope writes and searches use the top-level `run_id` filter. A session-scoped search therefore does not automatically include project memories that only carry `metadata.session_id`.
These `project`/`session`/`global` scopes are specific to this integration, not the Python plugins' `repo`/`dir`/`mine` scopes. Global tool access requires the user to enable it through `/mem0-scope global` or plugin settings first.
## Verify
Start OpenCode and ask: *"Search my memories for recent decisions"*
@@ -94,11 +104,9 @@ If the `mem0` tools respond, you're all set.
| Problem | Fix |
|---------|-----|
| No tools appearing | Restart OpenCode after installing |
| 401 Unauthorized | `echo $MEM0_API_KEY` must print your `m0-` key |
| 401 Unauthorized | Check that `MEM0_API_KEY` is set to a valid key without printing it |
| Plugin not loading | Run `opencode plugin @mem0/opencode-plugin` again |
## License
Apache-2.0
A memory tool cannot select global scope unless `/mem0-scope global` or the plugin settings already enable it.
integrations/pi-agent-plugin/README.md
+11 -3
View File
@@ -4,6 +4,8 @@ Persistent semantic memory for [Pi Agent](https://pi.dev), powered by [Mem0](htt
This extension gives Pi Agent long-term memory that persists across sessions, projects, and devices. Memories are automatically captured from conversations and can be searched and managed through slash commands and an agent-accessible tool.
Current package version: `0.3.0`. Shared redaction and lifecycle utilities come from [agent-plugin-core](../agent-plugin-core/README.md); Pi keeps its own tools and scopes.
## Features
- **Automatic memory capture** — learns from every conversation (both user and assistant messages)
@@ -79,11 +81,19 @@ The plugin includes 6 skills that guide the agent on how to use each capability:
| Scope | Filters | Use case |
|-------|---------|----------|
| `project` | user + app_id (git root) | Default. Project-specific knowledge |
| `session` | user + app_id + run_id | Ephemeral, session-only context |
| `session` | user + app_id + run_id | Recall restricted to memories saved with the current session ID |
| `global` | user only | All memories across all your projects |
Project scoping uses `git rev-parse --show-toplevel` to detect the repository root, so all subdirectories within a monorepo share the same memory pool.
Global tool operations require `/mem0-scope global` or `defaultScope: "global"` in plugin configuration. A model-supplied `scope` argument cannot enable cross-project access on its own. Empty or wildcard user, project, and session identities are rejected.
## Automatic recall and capture
Before an agent response, the extension searches project memories and injects relevant results. After `agent_end`, automatic capture sends the user and assistant text supplied by Pi to Mem0 in **project** scope, regardless of the default scope selected for explicit commands. Captured text is redacted without the former 6,000-character per-message cutoff.
Automatic project writes do not attach `run_id`. Session-scoped recall applies to memories explicitly saved in session scope; it does not make project memories session-specific or automatically expire them. Recall queries and displayed tool results keep separate size limits.
## Memory Categories
Memories are automatically classified into 10 general-purpose categories:
@@ -132,5 +142,3 @@ pnpm run build # Build (ESM + declarations)
## License
[Apache-2.0](LICENSE)
Global tool operations require `/mem0-scope global` or `defaultScope: "global"` in plugin configuration. A model-supplied `scope` argument cannot enable cross-project access on its own. Empty or wildcard user, project, and session identities are rejected.