139 lines
11 KiB
Markdown
139 lines
11 KiB
Markdown
# Mem0 agent plugin core
|
|
|
|
This directory is the single source of shared memory behavior for Mem0 coding-agent plugins. Installable plugins remain ordinary sibling directories under `integrations/`.
|
|
|
|
## Architecture
|
|
|
|
```text
|
|
integrations/
|
|
├── agent-plugin-core/ # Shared source; never installed as a plugin
|
|
│ ├── python/ # Claude-derived capture, recall, MCP, scoping, and telemetry
|
|
│ ├── typescript/ # Shared lifecycle, formatting, identity, scoping, and telemetry
|
|
│ ├── skills/ # The source for six memory skills and the handoff command
|
|
│ ├── build/ # Bundle builder, schemas, and validation
|
|
│ ├── conformance/ # One offline/live verification entry point
|
|
│ └── tests/
|
|
├── mem0-agent-plugin/ # One portable Agent Plugins v1 package
|
|
├── claude-code-plugin/ # Native Claude package and adapter
|
|
├── cursor-plugin/ # Native Cursor package and adapter
|
|
├── codex-plugin/ # Native Codex package and adapter
|
|
├── kimi-plugin/ # Native Kimi package and adapter
|
|
└── antigravity-plugin/ # Native Antigravity package and adapter
|
|
```
|
|
|
|
Each native directory owns only its manifest, native hooks or adapter, tests, and `plugin-build.json`. Its `core/` and `skills/` directories are generated from this module. They are committed because clients install a self-contained plugin directory and the Agent Plugins specification forbids package files from resolving outside the plugin root.
|
|
|
|
Claude Code remains the behavioral source of truth. Its sidekick stays at `claude-code-plugin/agents/sidekick.md` and is not generated or copied to hosts without a compatible native subagent interface.
|
|
|
|
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 memory skill templates plus the handoff command. 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.
|
|
|
|
Search guidance follows Memo: use a focused question when earlier work could help, reuse available context, and search again only for a specific remaining gap. The TypeScript hosts import one shared guidance constant; conformance checks keep it aligned with the generated Python MCP description and reject strict before-answer or repeated-search prompts. Automatic recall schedules and retrieval limits are independent of this wording.
|
|
|
|
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).
|
|
|
|
## Session handoff
|
|
|
|
`python/session_handoff.py` is the common entry point. `python/handoff_sources.py` reads native transcript formats; `python/claude_to_codex.py` retains the Claude parser and the single implementation of validation, private recovery, assets, context limits, and Codex import. It is adapted from [mem0ai/memo](https://github.com/mem0ai/memo/blob/aeeb1593284d1d2fca3b4bcf1e32ea10f71df549/docs/session-handoff.md).
|
|
|
|
The TypeScript hosts read their native active context and use `typescript/src/handoff.ts` to normalize messages and pass a `mem0.session-handoff.v1` bundle to the same Python engine over stdin. OpenClaw supplies its trusted native transcript path. Native Python and portable plugins generate the shared `handoff` skill, with source-specific instructions.
|
|
|
|
The common bundle contains `source` (`host`, `session_id`, `title`, `cwd`, optional `path`), `items` (user/assistant messages, paired function calls/results, and supported images), and optional `warnings`. The engine derives counts and validates the bundle. Unknown model-visible content, missing tool results, and opaque compaction state fail rather than disappearing from the imported task. Handoff runs only on explicit user request, independently of memory hooks and the Mem0 API. Creation requires Python 3.11+ and a local Codex CLI with native session import support.
|
|
|
|
`build/handoff-runtime.json` declares the runtime files once. Every TypeScript build uses `build/package_handoff.mjs` to package them. Conformance checks reject missing or stale copies, as well as generated Python bundle drift. When the importer changes, regenerate the Python bundles and rebuild the TypeScript packages; no per-plugin importer edits are needed. A new host needs only a native context reader or adapter producing the common bundle.
|
|
|
|
See the [handoff guide](../../docs/integrations/session-handoff.mdx) for host commands, verified formats, current-session limits, and recovery.
|
|
|
|
## Build and verify
|
|
|
|
From the repository root:
|
|
|
|
```bash
|
|
python3.11 -m venv /tmp/mem0-agent-plugins
|
|
/tmp/mem0-agent-plugins/bin/pip install \
|
|
-r integrations/agent-plugin-core/requirements-dev.txt
|
|
|
|
for host in claude-code cursor codex kimi antigravity; do
|
|
/tmp/mem0-agent-plugins/bin/python \
|
|
integrations/agent-plugin-core/build/build.py "$host" \
|
|
--kind native --check
|
|
done
|
|
|
|
/tmp/mem0-agent-plugins/bin/python \
|
|
integrations/agent-plugin-core/build/build.py mem0-agent-plugin \
|
|
--kind portable --check
|
|
```
|
|
|
|
Use `--sync` instead of `--check` after changing `python/` or `skills/`. This only replaces generated `core/` and `skills/` content; it does not change manifests, adapters, tests, or the Claude sidekick.
|
|
|
|
Run every offline Python and TypeScript check and write one machine-readable report:
|
|
|
|
```bash
|
|
/tmp/mem0-agent-plugins/bin/python \
|
|
integrations/agent-plugin-core/conformance/run.py \
|
|
--install \
|
|
--report /tmp/mem0-plugin-conformance.json
|
|
```
|
|
|
|
For every TypeScript integration, this also builds the publishable package, verifies its required entry files, and rejects compiled artifacts that still import monorepo source. This keeps published plugins self-contained without committing their `dist/` directories.
|
|
|
|
The offline suite does not contact Mem0 Platform. An explicit disposable key enables the inherited live scoping suite:
|
|
|
|
```bash
|
|
export MEM0_API_KEY="m0-disposable-test-key"
|
|
/tmp/mem0-agent-plugins/bin/python \
|
|
integrations/agent-plugin-core/conformance/run.py \
|
|
--group live-platform --live \
|
|
--report /tmp/mem0-plugin-live-conformance.json
|
|
```
|
|
|
|
Do not put a real key in source files, command history shared with others, or pull-request configuration.
|
|
|
|
## Add a plugin
|
|
|
|
For another native Python host:
|
|
|
|
1. Add `integrations/<host>-plugin/` with its native manifest and the smallest adapter that translates host events.
|
|
2. Add `plugin-build.json` declaring the plugin-root variable and runtime files.
|
|
3. Add one adapter contract test.
|
|
4. Register the host in `build/build.py` and `conformance/run.py`.
|
|
5. Run `--sync`, `--check`, and the conformance command above.
|
|
|
|
Keep capture, recall, memory scoping, redaction, skill text, and telemetry in this shared module. Host directories should contain only behavior required by their native SDK.
|
|
|
|
For a TypeScript host, import the shared lifecycle modules directly and keep only native SDK registration in the integration. Do not advertise capture, compaction, or sidekick behavior unless the host exposes the necessary lifecycle seam.
|
|
|
|
## Host capture capabilities
|
|
|
|
| Host | Conversation capture | Tool outcomes | Subagent context and correlation |
|
|
| --- | --- | --- | --- |
|
|
| Claude Code | Incremental active transcript branch | Native success/failure hooks | Parent context; native agent ID |
|
|
| Cursor | Prompt and response hooks; duplicate responses suppressed | Native success/failure hooks | Sidekick searches itself; no parent-injection claim |
|
|
| Codex | Native prompt and final-response fields | Structured failure indicators when present; otherwise unknown | Parent context; native agent ID |
|
|
| Kimi | Prompt hooks and completed v2 wire output | Native success/failure hooks | Parent context; without an ID, a stop matches only one unambiguous active run |
|
|
| Antigravity | Incremental completed transcript messages, including later prompts | Native tool errors | Sidekick searches itself; no worktree-isolation claim |
|
|
| Portable v1 | Explicit memory skills | No native lifecycle hooks | No native subagent declaration |
|
|
|
|
An uncorrelated subagent completion is kept as its own record; the plugin never guesses which overlapping run completed. Codex's documented hook fields already match the shared input contract, so no speculative field aliases or unsupported failure event are registered.
|
|
|
|
Offline conformance exercises the adapters and MCP servers with native-shaped payloads and builds each distributable package. It does not establish that every installed editor or Harness version loads the plugin correctly; those checks require smoke tests in the actual hosts.
|