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
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.