JDSS/mem0

Files

T

Saket Aryan df70d7833f fix(plugins): stamp surface identity at record time, not send time

Six defects in 0.3.x plugin telemetry. Defects 1, 2 and 6 were not three bugs:
they were one spool protocol getting three properties wrong.

Identity was decided by the wrong process. `harness` was stamped in record(),
correctly, but `source` was read from a module global in flush() — so whichever
process drained the spool named every event in it. Two processes never call
init(): mcp_server.py, and the detached `python3 telemetry.py` sender that
spawn_flush() starts. record() now stamps source beside harness, and the build
generates core/_harness_id.py per host so identity resolves with no init() call
at all. That also unifies two defaults that disagreed (`<host>_plugin` vs
`MEM0_<HOST>_PLUGIN`), which could yield three source values for one plugin.

Ownership was inferred, not held. Path.replace is os.rename, which preserves
mtime, so a claim made after a quiet minute inherited the spool's age and was
stealable the instant it existed. Claims are touched on creation and the
per-batch rewrite doubles as a lease heartbeat.

Progress was not durable. flush() returned on the first failed batch without
truncating, so the retry re-posted from index 0 — 150 events delivered 250
times. It now rewrites the claim with the unsent remainder after every batch,
bounding a crash to one repeated batch, and each event carries a uuid.

Parked batches starved. They were only reachable when no spool existed, and
because sessions keep recording there usually was one, so a batch parked by a
failed send waited until the 7-day expiry deleted it unsent — despite its own
presence being what starts the sender. flush() drains them in the same run, and
expiry now applies only after a genuine retry has failed.

code.install counted upgrades and repeat sessions. is_first_run() read the
identity file, which only a successful flush writes, so an offline user recorded
an install every session forever. A dedicated install-state.json is claimed
atomically at record time; a non-empty data directory reads as an upgrade.

The docs called this anonymous. Every event carries the account email, and the
hashes were unsalted SHA-256 over a git remote URL or an absolute path
containing the username. READMEs, the module docstring and a new docs section
now say what the code does, and repo/session digests are salted per install.

A cached email outlived an API key change. It is now re-resolved when the key's
fingerprint differs, and $identify aliases anonymous->email only — aliasing one
account to another merges person profiles irreversibly.

All six shipped green because the shared core's only tests lived under one host,
behind a conftest that calls init() at import. Core behaviour was never
exercised uninitialised. Adds agent-plugin-core/tests with no init, including
subprocess tests and coverage for the portable plugin, which has no flush worker
and would pass a native-only test vacuously.

Also puts the three surface headers on the SDKs, CLIs and integrations, and
corrects a README claiming ZAPIER/STRANDS were already in the platform allowlist.

Verified: 59 core tests, 203 claude-code, 11 cursor, 5 codex, 2 kimi, 6
antigravity. ruff and compileall clean. --check clean for all six hosts.
TypeScript changes are not typechecked locally (deps not installed).

Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb

2026-09-15 00:14:11 +05:30

6.4 KiB

Raw Permalink Blame History

Integrations (`integrations/`)

Agent and editor integrations. Most packages are self-contained; coding-agent plugins share the code in agent-plugin-core/. Check the table before running anything.

Directory	Package	Build	Lint	Test
`vercel-ai-sdk/`	`@mem0/vercel-ai-provider`	tsup (CJS+ESM)	ESLint + Prettier	jest + vitest (edge/node)
`openclaw/`	`@mem0/openclaw-mem0`	tsup (ESM)	none	vitest
`agent-plugin-core/`	Shared Python/TypeScript behavior, skill templates, builds, and conformance	Python build script	ruff + tsc	pytest + node:test
`mem0-agent-plugin/`	One portable Agent Plugins v1 package	Python	ruff	shared conformance
`claude-code-plugin/`, `cursor-plugin/`, `codex-plugin/`, `kimi-plugin/`, `antigravity-plugin/`	Self-contained native plugins generated from the shared Python core	Python	ruff	pytest
`opencode-plugin/`	`@mem0/opencode-plugin` (Bun/TypeScript)	tsup (via Bun)	tsc	bun test
`pi-agent-plugin/`	`@mem0/pi-agent-plugin`	tsup	none	vitest
`deepseek-plugin/`	`@mem0/deepseek-plugin`	tsup (ESM)	none	vitest
`n8n-nodes-mem0/`	`@mem0/n8n-nodes-mem0`	tsc	ESLint (n8n-nodes-base)	none
`zapier-mem0/`	`@mem0/zapier`	tsc	none	offline unit tests + `zapier validate`
`mem0-strands/`	`mem0-strands` (PyPI)	hatch	Ruff + mypy	pytest

pnpm for TypeScript packages except opencode-plugin/ (Bun). mem0-strands/ uses Python/pip/hatch. Never npm or yarn.

Commands

cd integrations/vercel-ai-sdk
pnpm install
pnpm run build           # tsup
pnpm run lint            # eslint
pnpm run type-check      # tsc --noEmit
pnpm run prettier-check
pnpm run test            # jest
pnpm run test:edge       # vitest, edge runtime
pnpm run test:node       # vitest, node runtime

cd integrations/openclaw
pnpm install
pnpm run build           # tsup
pnpm run test            # vitest

Run the type check after every TypeScript change: pnpm run typecheck or tsc --noEmit, whichever the package defines.

What each one is

vercel-ai-sdk/ wraps the Vercel AI SDK through a createMem0 provider. Integrations for AI-SDK repos go through this wrapper, not raw MemoryClient.
agent-plugin-core/ owns the shared Python memory runtime, TypeScript lifecycle utilities, skill templates, builds, and conformance runner. Claude Code is the behavioral source of truth. Native manifests and adapters live in sibling plugin directories; do not hand-edit their generated core/ or skills/ trees. Build and validation details are in agent-plugin-core/README.md.
opencode-plugin/ is a Bun/TypeScript plugin for OpenCode (@mem0/opencode-plugin on npm). It registers Mem0 memory tools as an OpenCode plugin with its own skills and telemetry.
openclaw/, pi-agent-plugin/, deepseek-plugin/ are editor and agent plugins with the same shape. deepseek-plugin/ registers Mem0 search/add tools as a native DeepSeek Harness (Cordis) plugin.
n8n-nodes-mem0/ is an n8n community node: add, search, get, update, delete.
zapier-mem0/ is a Zapier Platform CLI app: add, search, get, delete. It deploys to Zapier, not npm, so it is not in the release router. Deploy it with gh workflow run zapier-mem0-cd.yml --ref main (needs the ZAPIER_DEPLOY_KEY secret).
mem0-strands/ is a native Strands MemoryStore (Python, published to PyPI as mem0-strands). It plugs into the Strands MemoryManager for automatic recall and server-side extraction, over the hosted Mem0 platform or self-hosted Mem0 OSS. The package lives under mem0-strands/python/.

Surface attribution

Every integration tells the Mem0 platform which surface it is. Three headers, and the rules on them are what keep one layer from erasing another:

Header	Carries	Rule
`X-Mem0-Source`	one canonical source value	set-once — write only if absent
`X-Application`	the host app it runs inside	set-once — write only if absent
`X-Mem0-Client`	`name/version`, outermost first	append-only — add yourself, never replace

Set-once means setdefault, never assignment. An integration that wraps the SDK is the outermost layer and sets the source; the SDK underneath must defer to it. Assignment is exactly how every agent plugin came to be indistinguishable from every other one at the platform.

Append-only means a plugin calling the Python SDK produces mem0-plugin/0.3.1, mem0-python/2.0.19, so neither layer can erase the other.

The backend recognizes a fixed list of source values and buckets everything else into OTHERS. A new value has to land in the platform's EventSource enum, so do not invent one without that change going in too.

Adding an integration

For a native coding-agent host, add integrations/<name>-plugin/ with plugin-build.json, its manifest, and a thin adapter, then generate its shared runtime. Portable clients use the single mem0-agent-plugin/ package. Independent TypeScript integrations stay self-contained and import shared lifecycle behavior from agent-plugin-core/typescript/.
If it publishes to a registry, set repository.directory: "integrations/<name>" in package.json so npm provenance links to the right subdirectory.
Add .github/workflows/<name>-checks.yml and <name>-cd.yml. Use integrations/<name> in the paths: trigger, working-directory, and cache-dependency-path. Register the release tag prefix in the case block in release.yml, keeping the bare v* arm last. Workflow filenames are load-bearing: npm OIDC trusted publishing is pinned to repository plus workflow filename. Renaming one breaks publishing.
Register the CI workflow in ci-gate.yml: a path filter under the changes job, a call job, and an entry in the gate job's needs list.
If it is a Claude Code or editor marketplace plugin, register the generated native bundle path in the applicable marketplace files. Preserve the existing public plugin name.
Document it under docs/integrations/ and add the page to docs/docs.json and docs/llms.txt.
Add rows to the table above and to the CI/CD tables in ../.github/AGENTS.md.
Send the three headers in Surface attribution, and land the matching EventSource value on the platform in the same week. Until it exists, your traffic reports as OTHERS.

6.4 KiB Raw Permalink Blame History

Integrations (integrations/)