docs(changelog): add v2.2.1 entry for Valkey None-timestamps fix (#7425)

Co-authored-by: Pratik <10096516+pratikgajjar@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.agents/plugins/marketplace.json

@@ -8,7 +8,7 @@
       "name": "mem0",
       "source": {
         "source": "local",
-        "path": "./mem0-plugin"
+        "path": "./integrations/codex-plugin"
       },
       "policy": {
         "installation": "AVAILABLE",

.claude-plugin/marketplace.json

@@ -10,9 +10,9 @@
   "plugins": [
     {
       "name": "mem0",
-      "source": "./mem0-plugin",
-      "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search to Claude workflows.",
-      "version": "0.1.0"
+      "source": "./integrations/claude-code-plugin",
+      "description": "Cross-session memory and token savings for coding agents.",
+      "version": "0.3.3"
     }
   ]
 }

.codex-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "mem0-plugins",
+  "interface": {
+    "displayName": "Mem0 Plugins"
+  },
+  "plugins": [
+    {
+      "name": "mem0",
+      "source": {
+        "source": "local",
+        "path": "./integrations/codex-plugin"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

.cursor-plugin/marketplace.json

@@ -10,9 +10,9 @@
   "plugins": [
     {
       "name": "mem0",
-      "source": "./mem0-plugin",
-      "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search.",
-      "version": "0.1.0"
+      "source": "./integrations/cursor-plugin",
+      "description": "Cross-session memory and token savings for coding agents.",
+      "version": "0.3.3"
     }
   ]
 }

.github/AGENTS.md

@@ -0,0 +1,156 @@
+# CI/CD and repository automation (`.github/`)
+
+> **Do not modify any workflow without explicit approval from a maintainer.** Publishing
+> credentials are bound to workflow filenames, and the gate workflows decide whether
+> contributions are accepted. Read this file before proposing any change here.
+
+## CI: one gate, many pipelines
+
+`ci-gate.yml` (**CI Gate**) is the single entry point. It runs on every PR, detects which packages changed, and calls only the relevant package workflows as reusable workflows (`workflow_call`). Its final `CI Gate` job aggregates the results: skipped pipelines pass, failed or cancelled ones fail. It is the **only CI status check that needs to be required** in branch protection.
+
+Package workflows keep their own push-to-main and manual triggers. Their `pull_request` triggers live in the gate's path filters instead.
+
+| Workflow | File | Standalone triggers | Runs |
+|----------|------|---------------------|------|
+| CI Gate | `ci-gate.yml` | All PRs | Routes to and aggregates everything below |
+| Python SDK | `ci.yml` | Push to main | Ruff + pytest on Python 3.10, 3.11, 3.12 |
+| TypeScript SDK | `ts-sdk-ci.yml` | Push to main (`mem0-ts/`) | Prettier + build + jest on Node 20, 22 |
+| Python CLI | `cli-python-ci.yml` | Push to main (`cli/python/`), manual | Ruff + pytest + hatch build on Python 3.10, 3.11, 3.12 |
+| Node CLI | `cli-node-ci.yml` | Push to main (`cli/node/`), manual | Biome + tsc + vitest + tsup on Node 20, 22 |
+| OpenClaw | `openclaw-checks.yml` | Push to main (`integrations/openclaw/`), manual | tsc + vitest (Codecov) + tsup on Node 20, 22 |
+| Agent Plugins Python | `agent-plugins-python-checks.yml` | Push to main (shared Python core and native/portable plugin directories), manual | Runtime tests on Python 3.10; full pytest on 3.11, 3.12; ruff + generated-package drift on 3.12 |
+| Agent Plugins TypeScript | `agent-plugins-typescript-checks.yml` | Push to main (`integrations/agent-plugin-core/typescript/`), manual | tsc + node:test on Node 22 |
+| OpenCode Plugin | `opencode-plugin-checks.yml` | Push to main (`integrations/opencode-plugin/`), manual | Bun: tsc + build + dist artifact check |
+| Pi Agent Plugin | `pi-agent-plugin-checks.yml` | Push to main (`integrations/pi-agent-plugin/`), manual | tsc + vitest + tsup on Node 20, 22 |
+| DeepSeek Harness Plugin | `deepseek-plugin-checks.yml` | Push to main (`integrations/deepseek-plugin/`), manual | tsc + vitest + tsup on Node 20, 22 |
+| n8n Node | `n8n-nodes-mem0-checks.yml` | Push to main (`integrations/n8n-nodes-mem0/`), manual | ESLint + tsc build on Node 20 |
+| Zapier App | `zapier-mem0-checks.yml` | Push to main (`integrations/zapier-mem0/`), manual | tsc + `zapier validate` + offline unit tests on Node 22 |
+| mem0-strands | `mem0-strands-checks.yml` | Push to main (`integrations/mem0-strands/`), manual | Ruff + mypy + pytest + hatch build on Python 3.10, 3.11, 3.12 |
+| docs llms.txt | `docs-llms-txt-check.yml` | Manual | `docs/llms.txt` coverage |
+| GitHub Scripts | inline in `ci-gate.yml` | none | `node` over every `.github/scripts/*.test.js` |
+
+Adding a package CI workflow: give it `workflow_call` plus `push` / `workflow_dispatch` as needed but **no `pull_request` trigger**, then register it in `ci-gate.yml` with a path filter under the `changes` job, a call job, and an entry in the gate job's `needs` list.
+
+`GitHub Scripts` is the one row that is a plain job inside `ci-gate.yml` rather than a called workflow, because a reusable workflow wrapping two `node` invocations would be more file than test. It runs on the `github_scripts` filter, which covers `.github/scripts/**` plus every file those tests read: `pr-gate.yml`, `vouch-check-pr.yml`, `issue-labeler.yml`, and `VOUCHED.td`. Add a new `.github/scripts/*.test.js` and it is picked up with no wiring; make a test read a new file and that file belongs in the filter.
+
+## Branch protection on `main`
+
+A repository ruleset named `Main Branch Rule`, id `11813754`. It enforces squash-only merges, linear history, no deletion, no force-push, and one approving review. Two status checks belong in its `required_status_checks` rule:
+
+| Context | Posted by | Why |
+|---------|-----------|-----|
+| `CI Gate` | `ci-gate.yml` | Aggregates every package pipeline |
+| `license/cla` | CLA Assistant | Proves the CLA is signed, not merely requested |
+
+Editing the ruleset requires repo **admin**. `maintain` is not enough, and the API returns 404 rather than 403 in that case. Until `license/cla` is required, the claim in `CONTRIBUTING.md` that unsigned PRs are blocked from merging holds by convention only.
+
+Requiring `CI Gate` also means fork PRs from first-time contributors cannot merge until a maintainer approves the workflow run. Those sit at `action_required`, which is intended behavior.
+
+## CD: one router, many publishers
+
+`release.yml` (**Release Router**) is the only workflow listening to `release: published`. It matches the tag prefix and dispatches the matching package workflow through `workflow_dispatch`, so one release produces exactly one routed run.
+
+| Workflow | File | Tag prefix | Target |
+|----------|------|------------|--------|
+| Release Router | `release.yml` | all releases | dispatches the rows below |
+| Python SDK | `cd.yml` | `v*` | PyPI (`mem0ai`) |
+| TypeScript SDK | `ts-sdk-cd.yml` | `ts-v*` | npm (`mem0ai`) |
+| Python CLI | `cli-python-cd.yml` | `cli-v*` | PyPI (`mem0-cli`) |
+| Node CLI | `cli-node-cd.yml` | `cli-node-v*` | npm (`@mem0/cli`) |
+| Vercel AI SDK | `vercel-ai-cd.yml` | `vercel-ai-v*` | npm (`@mem0/vercel-ai-provider`) |
+| OpenClaw | `openclaw-cd.yml` | `openclaw-v*` | npm (`@mem0/openclaw-mem0`) |
+| OpenCode Plugin | `opencode-plugin-cd.yml` | `opencode-v*` | npm (`@mem0/opencode-plugin`) |
+| Pi Agent Plugin | `pi-agent-plugin-cd.yml` | `pi-agent-v*` | npm (`@mem0/pi-agent-plugin`) |
+| DeepSeek Harness Plugin | `deepseek-plugin-cd.yml` | `deepseek-plugin-v*` | npm (`@mem0/deepseek-plugin`) |
+| n8n Node | `n8n-nodes-mem0-cd.yml` | `n8n-nodes-mem0-v*` | npm (`@mem0/n8n-nodes-mem0`) |
+| mem0-strands | `mem0-strands-cd.yml` | `mem0-strands-v*` | PyPI (`mem0-strands`) |
+
+- Package CD workflows are `workflow_dispatch`-only, with `tag` and `prerelease` inputs. They check out and build the given tag.
+- All publishing uses **OIDC trusted publishing**. No tokens, no secrets.
+- Registry trusted-publisher settings are pinned to each package's own workflow **filename**. Renaming a CD workflow breaks publishing for that package.
+- First publish of a new npm package must be done manually. OIDC works from the second version onward.
+- To re-publish a release, do **not** delete and recreate the GitHub release. Dispatch the workflow directly: `gh workflow run <package>-cd.yml --ref refs/tags/<tag> -f tag=<tag>`.
+- The Zapier app deploys to Zapier's platform, not npm, so it is not in the router. Deploy with `gh workflow run zapier-mem0-cd.yml --ref main`.
+- Adding a package: add its CD workflow, then register its tag prefix in the `case` block in `release.yml`, keeping the bare `v*` arm last.
+
+## Contribution gates
+
+| Workflow | File | Purpose |
+|----------|------|---------|
+| PR Gate | `pr-gate.yml` | Closes PRs that do not link an issue labeled `accepted`, and reopens them when that label arrives. Exempts members, bots, drafts, and docs-only changes. Never checks out PR code. |
+| Vouch (check PR) | `vouch-check-pr.yml` | Closes PRs from authors denounced in `VOUCHED.td`. Comments once on PRs from authors merely absent from it, and blocks nothing in that case. |
+| Vouch (manage list) | `vouch-manage-by-issue.yml` | Maintainers edit the trust list by commenting `!vouch @user`, `!denounce @user`, or `!unvouch @user` on any issue. Opens a PR against `VOUCHED.td` through a GitHub App token, for a maintainer to merge. |
+| Issue Labeler | `issue-labeler.yml` | Labels issues from the `component` field in the issue forms |
+| PR Labeler | `pr-labeler.yml` | Path-based labels, plus propagating labels from linked issues |
+| Stale Bot | `stale.yml` | Marks stale issues and PRs |
+| llms.txt Check | `docs-llms-txt-check.yml` | Blocks PRs touching `docs/**/*.mdx` when `docs/llms.txt` is out of sync |
+
+`pr-gate.yml` and `vouch-check-pr.yml` use `pull_request_target`, which is required to label and close fork PRs. Neither checks out PR code and neither has a `run:` step, so there is no pwn-request or script-injection surface. Keep it that way: any future `run:` step in these files must never interpolate `github.event.*` text.
+
+Both workflows exempt maintainers twice, and the second guard is the one that holds. `author_association` is rendered for the viewer, and a webhook payload has no privileged viewer: `MEMBER` needs the author's org membership to be **public**, `COLLABORATOR` needs a **direct** repository invite. An org member with private membership whose `maintain` comes through a team matches neither and arrives as `CONTRIBUTOR`, which is how PR #6948 was closed by its own author's gate. So the guard also skips any PR whose head branch lives in this repository (`head.repo.full_name == github.repository`). Pushing a branch here already requires write access and outside contributors always arrive from a fork, so that test means the same thing without depending on who is looking. Keep both: the `author_association` arm still covers members who work from their own fork.
+
+`pr-gate.yml` carries two jobs whose `if:` conditions are deliberately disjoint. `gate` closes, and only ever runs on `opened`, `reopened`, and `ready_for_review`. `reopen` reopens, and only ever runs on `edited` or on `issues: labeled` with the `accepted` label. Nothing can both close and reopen on the same event, which is the property to preserve when editing either guard.
+
+That split exists because the two halves of a gated PR's recovery arrive in either order. A maintainer usually labels the issue `accepted` at triage, before the author has linked it; sometimes the link lands first and the label follows. So `reopen` handles both directions. From `issues: labeled` it walks `closedByPullRequestsReferences` back to the pull requests that link the issue. From `edited` it takes the edited pull request directly. Both paths then apply the same four tests: the author is not denounced in `VOUCHED.td`, the PR is `CLOSED`, it links an issue labeled `accepted`, and it carries the `<!-- pr-gate -->` marker comment. Without the label path, a maintainer's label is inert. Without the `edited` path, an author who links the issue after it was labeled is stuck, since no other event fires.
+
+The denounce test is what keeps the two gates from cancelling each other out. A denounced author whose PR also lacked an accepted issue was closed by both workflows, so it carries the `<!-- pr-gate -->` marker, and labeling the linked issue would otherwise reopen it. Vouch cannot undo that: reopening runs through `GITHUB_TOKEN`, which raises no events, so `vouch-check-pr.yml` never fires a second time. Reading the list here is the only place the check can live. It fails open like vouch does, warning and treating nobody as denounced if the file cannot be read, and it is the one piece of vouch semantics duplicated outside `vouch-check-pr.yml`, because `pr-gate.yml` never checks out the repository and so cannot import a shared parser. `.github/scripts/vouch-decision.test.js` covers the parsing and asserts `pr-gate.yml` still filters the list the same way.
+
+`edited` must never reach the `gate` job. It fires on any title or description change, so when `gate` listened for it the gate re-judged pull requests that had been open for days and closed them the moment their author touched the description, which is what closed #6948. Rescuing on `edited` is safe for the same reason closing on it was not: the job can only move a PR from closed to open.
+
+Reopening runs through `GITHUB_TOKEN`, which by design raises no further workflow events, so `gate` cannot bounce a freshly reopened PR straight back out.
+
+The concurrency group is keyed on `github.event.action` as well as `github.event_name` and the number, and both keys carry weight. Without the event name, a maintainer applying `bug` right after `accepted` cancels the reopen mid-flight, since `cancel-in-progress` is on for `pull_request_target` and both label events would land in the same group. Without the action, `opened` and `edited` share a group on the same pull request, and an author who ticks a template checkbox in the seconds after opening cancels the run that was about to gate them: `gate` skips `edited` and `reopen` skips an open pull request, so the cancelled run is never replaced and the pull request stays ungated forever, since `opened` fires exactly once. Rapid successive edits still cancel each other, which is the dedup that was wanted.
+
+The `edited` arm of `reopen` requires `github.event.pull_request.state == 'closed'`, so ordinary description edits on open pull requests do not start a runner.
+
+Two known gaps, both mild. A PR that the gate closed, that someone reopened, and that a maintainer then closed deliberately still carries the marker, so labeling its issue reopens it again; a maintainer closes it once more. And an author who strips `Closes #<number>` out after passing keeps an open PR, which a reviewer sees anyway.
+
+`GATE_EFFECTIVE_FROM` in `pr-gate.yml` is a `created_at` cutoff. `reopened` and `ready_for_review` still fire on PRs opened long before the gate existed, so without the cutoff part of the open backlog would be closed by a rule that did not exist when those PRs were filed. Set it to the actual merge date in UTC.
+
+The gate's docs-only exemption covers `docs/` plus a named allowlist of four root files: `README.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md`. It is an allowlist rather than a rule about top-level markdown because the repository root also holds `AGENTS.md`, `CLAUDE.md`, and `LLM.md`, which are the instructions coding agents read before touching this codebase. Those are functional files that happen to be written in prose, and rewriting them is a change to behaviour, so they stay gated. Markdown nested anywhere else stays gated for the same reason: `skills/**/*.md` and everything under `.github/` are functional too. Adding a genuinely prose root file means adding it to `rootDocs` in `pr-gate.yml`.
+
+`.github/scripts/pr-gate-docs-exemption.test.js` covers that predicate. It pulls the `rootDocs` and `isDocs` lines out of `pr-gate.yml` and evaluates them, so it exercises the shipped rule rather than a copy that could drift from it, and it pins `AGENTS.md`, `CLAUDE.md`, and `LLM.md` on the gated side along with `skills/**/*.md`, nested `.github/` files, and the empty file list. It only accepts those two declarations in a literal one-line form, so keep `rootDocs` a `Set` of quoted names and `isDocs` a single arrow expression.
+
+The two contribution gates answer different questions and neither covers for the other. `pr-gate.yml` judges the change, and the `accepted` label is how a maintainer says yes to it. `vouch-check-pr.yml` judges the author, and `VOUCHED.td` is how a maintainer says no to one. A vouched author with no accepted issue is still closed by the gate; a denounced author with an accepted issue is still closed by vouch. Read either one as a backstop for the other and both get weakened.
+
+Vouch enforces on the denounce axis only, through `require-vouch: false` with `auto-close: true`. That pair is not the obvious reading of either input, so the decision table from v1.5.0 (`vouch/github.nu` at pinned SHA `d66fa29`) is worth stating outright:
+
+| Author | `status` | Effect |
+|---|---|---|
+| ends in `[bot]` | `skipped` | nothing |
+| collaborator with write or admin | `vouched` | nothing |
+| listed in `VOUCHED.td` | `vouched` | nothing |
+| listed as `-handle` | `closed` | action comments and closes |
+| absent from the file | `allowed` | workflow comments, nothing closed |
+
+`require-vouch: true` would close every first-time contributor, which is the opposite of what a trust list is for: the funnel has to stay open or nobody ever earns a vouch. `auto-close: false` is the setting that looked safe and did nothing at all, since in v1.5.0 both the unvouched and the denounced branch return before posting anything, leaving only a line in the run log. That is why `!denounce` was decorative until this pair landed.
+
+Only the `allowed` arm is ours: a `github-script` step posts the soft comment, keyed on a `<!-- vouch-check -->` marker so a reopen does not comment twice. The `closed` arm belongs to the action, message and all. Keeping the two arms disjoint is what stops a denounced author getting two comments, so if that step is ever re-keyed off `allowed`, check the overlap first.
+
+`.github/scripts/vouch-decision.test.js` holds that table as a `decide()` function and asserts the workflow's `require-vouch`, `auto-close`, and comment-step gating still produce it, comment counts included. Be clear about what that does and does not prove. `decide()` is a **hand transcription** of `gh-check-pr`, read from `vouch/github.nu` at the pinned SHA; the test cannot run the action, so it cannot notice the action changing underneath it. Left alone it would agree with itself forever, which makes bumping the pinned SHA the one edit it would otherwise sail through. So it also asserts `vouch-check-pr.yml` still pins `PINNED_VOUCH_SHA`, and a bump fails it on purpose: re-read `gh-check-pr` at the new revision, correct `decide()` and the table above, then move the constant. CI runs it through the `GitHub Scripts` job on any change to the scripts or the files they read.
+
+Failure is open by design. If the action cannot read `VOUCHED.td` it falls back to an empty list, every author reads as absent, and nobody is closed by an API hiccup.
+
+`vouch-manage-by-issue.yml` runs with `merge-immediately: "false"`. The `Main Branch Rule` ruleset requires one approving review and has no bypass actors, so the action's immediate `PUT /pulls/{n}/merge` would return 405 and leave `VOUCHED.td` unchanged on `main`. The bot opens the PR, a maintainer merges it. Setting `pull-request: "false"` is not an alternative: the same ruleset blocks direct pushes.
+
+That workflow also needs `VOUCH_APP_ID` and `VOUCH_APP_PRIVATE_KEY` repository secrets. Without them it fails at the token step before doing anything. `vouch-check-pr.yml` needs neither.
+
+## Issue forms and templates
+
+`ISSUE_TEMPLATE/*.yml` are GitHub issue **forms**, not markdown templates. Only forms support `required: true` and machine-parseable field ids. Blank issues are disabled in `config.yml`.
+
+`issue-labeler.yml` reads only the `component` field id through `stefanbuck/github-issue-parser` and `redhat-plumbers-in-action/advanced-issue-labeler`, so adding new field ids is safe. Renaming `component` is not.
+
+Current field ids:
+
+| Form | Ids |
+|------|-----|
+| `bug_report.yml` | `component`, `description`, `verification`, `ai_assistance` |
+| `feature_request.yml` | `component`, `description`, `ai_assistance` |
+| `documentation_issue.yml` | `description`, `ai_assistance` |
+
+## Trust list
+
+`VOUCHED.td` is one GitHub username per line, `#` for comments. Seeded from every author with at least one merged PR in this repository, then filtered: accounts at or below a 16% merge rate across five or more attempts were dropped, since landing one change out of many is the signature of automated submission rather than contribution.
+
+Vouch's only built-in exemptions are accounts ending in `[bot]` and repo collaborators with `write` or `admin`. **Organization membership alone is not one of them.** So `vouch-check-pr.yml` carries a job-level `if:` that skips the check for `OWNER`, `MEMBER`, and `COLLABORATOR` authors, the same exemption `pr-gate.yml` already applies. Org members are still listed in the file as a fallback, but the workflow guard is what actually holds.

.github/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -9,12 +9,10 @@ body:
       label: Component
       description: Which part of mem0 is affected?
       options:
-        - Core / Python SDK
+        - Python SDK
         - TypeScript SDK
-        - Vector Store (Qdrant, PGVector, Redis, Chroma, etc.)
-        - Graph Memory (Neo4j, Memgraph, etc.)
-        - Ollama / Local Models
-        - OpenClaw
+        - Vector Store
+        - Plugin
         - REST API
         - Other
     validations:
@@ -53,3 +51,43 @@ body:
         - OS:
     validations:
       required: true
+
+  - type: textarea
+    id: verification
+    attributes:
+      label: How You Verified This
+      description: We only take on bugs someone has actually reproduced. Show your work.
+      value: |
+        ### What I Ran
+
+        The exact command or script, and where it ran.
+
+        ### What I Saw
+
+        The real output, log line, or traceback. Paste it, do not describe it.
+
+        ### Why This Is a Bug
+
+        What should have happened instead, and what says so: a docs link, a
+        docstring, a test, or the code itself.
+
+        ### What I Ruled Out
+
+        Anything you checked that turned out not to be the cause.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: ai_assistance
+    attributes:
+      label: AI Assistance
+      description: >-
+        This asks how the bug was found and confirmed, not how the text was
+        written. Drafting the write-up with AI is fine. We ask because it tells
+        us how much to trust the reproduction, not because it counts against you.
+      options:
+        - No AI involved
+        - AI helped me find it, and I reproduced it myself afterwards
+        - AI found and wrote this, and I have not reproduced it myself
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +1,11 @@
-blank_issues_enabled: true
+blank_issues_enabled: false
 contact_links:
-  - name: Discord Community
+  - name: Question or general help
     url: https://discord.gg/6PzXDgEjG5
-    about: Ask questions and discuss with the community
+    about: Ask on Discord. The issue tracker is for bugs and accepted work only.
   - name: Documentation
     url: https://docs.mem0.ai
     about: Read the official mem0 documentation
+  - name: Report a security vulnerability
+    url: https://github.com/mem0ai/mem0/security/advisories/new
+    about: Report privately through a security advisory. Never open a public issue.

.github/ISSUE_TEMPLATE/documentation_issue.yml

@@ -21,3 +21,17 @@ body:
         How should the docs be improved?
     validations:
       required: true
+
+  - type: dropdown
+    id: ai_assistance
+    attributes:
+      label: AI Assistance
+      description: >-
+        This asks how the problem was found, not how the text was written.
+        Drafting the write-up with AI is fine.
+      options:
+        - No AI involved, I hit this reading the docs
+        - AI-assisted, but I checked the page myself
+        - AI found this, and I have not opened the page
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -9,14 +9,11 @@ body:
       label: Component
       description: Which part of mem0 does this relate to?
       options:
-        - Core / Python SDK
+        - Python SDK
         - TypeScript SDK
-        - Vector Store (Qdrant, PGVector, Redis, Chroma, etc.)
-        - Graph Memory (Neo4j, Memgraph, etc.)
-        - Ollama / Local Models
-        - OpenClaw
+        - Vector Store
+        - Plugin
         - REST API
-        - Benchmarks / Evals
         - Other
     validations:
       required: true
@@ -39,3 +36,18 @@ body:
         Any workarounds you've tried or other approaches considered.
     validations:
       required: true
+
+  - type: dropdown
+    id: ai_assistance
+    attributes:
+      label: AI Assistance
+      description: >-
+        This asks where the idea came from, not how the text was written.
+        Drafting the write-up with AI is fine. A request you hit yourself while
+        building something carries more weight than one a model suggested.
+      options:
+        - No AI involved, this is a need I hit myself
+        - AI-assisted, but the need is mine
+        - AI suggested this feature
+    validations:
+      required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -14,6 +14,18 @@ Closes #<!-- issue number -->
 - [ ] Refactor (no functional changes)
 - [ ] Documentation update
 
+## AI Assistance
+
+<!-- This is about the code, not this description. Writing the description with AI is fine. -->
+
+- [ ] No AI assistance
+- [ ] AI-assisted (autocomplete, or I asked a model questions while writing this)
+- [ ] AI-generated (an agent wrote most or all of this diff)
+
+<!-- If you ticked either AI box, name the tool and what you checked yourself. -->
+
+- [ ] **I can explain every line of this diff and how it interacts with the rest of the codebase, without asking an AI tool.**
+
 ## Breaking Changes
 
 <!-- If this is a breaking change, describe what breaks and the migration path. Delete this section if not applicable. -->

.github/VOUCHED.td

@@ -0,0 +1,427 @@
+# The list of vouched (or denounced) users for this repository.
+#
+# A denounced user (prefixed with a minus) is blocked outright: their pull
+# requests are closed on sight, whatever they link. Being absent from this file
+# blocks nothing. An unvouched author gets one comment saying so and their pull
+# request is reviewed like anyone else's, because a first contribution has to
+# start somewhere. Vouching is how that comment stops.
+#
+# This list is about who, and it is the only thing that judges who. Whether a
+# change is wanted is a separate question, answered by the accepted label and
+# enforced by pr-gate.yml. Neither gate substitutes for the other: a vouched
+# author still needs an accepted issue, and a denounced author is turned away
+# even holding one.
+#
+# Vouch automatically allows two kinds of account without consulting this file:
+# accounts ending in [bot], and repo collaborators with write or admin
+# permission. Org membership on its own is NOT one of them, so
+# vouch-check-pr.yml skips the check for OWNER, MEMBER, and COLLABORATOR
+# authors, and for any branch pushed to this repository.
+#
+# Keep every mem0ai member listed below anyway. The author_association arm of
+# that guard is weaker than it looks: MEMBER needs the member's org membership
+# to be public and COLLABORATOR needs a direct repo invite, so a member with
+# private membership and a team-derived role reads as CONTRIBUTOR. Working from
+# a branch here covers them, working from their own fork leaves this file as
+# the only thing that does. A missing or miscased entry is a real gap.
+#
+# Syntax:
+#  - One handle per line (without @), sorted alphabetically.
+#  - Optionally specify platform: `platform:username` (e.g. `github:mitchellh`).
+#  - To denounce a user, prefix with minus: `-username`.
+#  - Optionally add a note after a space following the handle.
+#
+# Maintainers vouch by commenting "!vouch @username" on any issue, and denounce
+# with "!denounce @username". The bot commits the change back to this file.
+#
+# Seeded on 2026-08-12 from every author with at least one merged pull request,
+# then filtered: accounts with a merge rate at or below 16% across six or more
+# attempts were dropped, since landing one change out of many is the signature
+# of automated submission rather than contribution. Removal is not a ban. Any
+# maintainer can !vouch these accounts back in.
+1MikeMakuch
+aaishikdutta
+Aarkin7
+abdullahirfann
+AbdurNawaz
+abhay-codes07
+Abhineshhh
+ac12644
+acarbonetto
+adh-wonolo
+Aditya-Tripuraneni
+aesher9o1
+agumpandey
+ahnedeee
+ajmalmohad
+AkisAya
+akshat1423
+akshseh
+alessandropanzieri
+alohays
+aloktripathi1
+amahuli03
+amanagarwal042
+Ameysr
+amjadraza
+anantoj
+anchit-nishant
+andrewghlee
+andy-k-improving
+anifort
+anishesg
+AnkushMalaker
+AnnaSuSu
+anujshandillya
+ArchishmanSengupta
+Arsh-mem0
+ArthurHoward1
+aryankhanna475
+Ashu463
+atahanyild
+AtharvaJaiswal005
+atkinsh
+avp1598
+axelray-dev
+ayaangazali
+aymenkrifa
+barry166
+being-abhi
+berwinjoule
+BillionClaw
+bioshazard
+bisla
+bkidd1
+blino
+bmsvinci1729
+boss-mao
+Br1an67
+brucewkz
+cachho
+caifeizhi
+candidosales
+cclauss
+chaithanyak42
+chinnuabey
+ChiragArora31
+ChrisFloofyKitsune
+chrisqu777
+clementantonyk
+codexvn
+Colsrch
+CrepuscularIRIS
+ctxlong
+danielsiwiec
+darkhaniop
+davidatorres
+deshraj
+Dev-Khant
+Devan019
+deven298
+devYRPauli
+DhanushNehru
+DhilipBinny
+Dhravya
+dimigerontaki
+Diveyam-Mishra
+divyansh-1009
+Divyanshu9822
+dog-last
+DrJsPBs
+dtee1
+DumoeDss
+e-biswas
+Echo3ToEcho7
+eldar702
+eltociear
+EnzoFanAccount
+Esparon1
+Fahmid-Arman
+Failfail2603
+FarukhS52
+farzad528
+felipeavilis
+femto
+fengjikui
+fenilfaldu
+fileames
+Flyfoxs
+fmercurio
+FoliageOwO
+fran3cc
+frank-zsy
+frederikb96
+Freshield
+freya0926
+G26karthik
+gabe-l-hart
+gabrielstein-mem0
+gajazlikovac
+gasolin
+gaurav0107
+gauravagerwala
+Genarojrsanchez
+ghdcksgml1
+GingerMoon
+gmdorf
+golemus
+GongRzhe
+GopalGB
+Gyubin
+haarishmk26
+hackice20
+halanm
+hardik1408
+Harin329
+harshgupta-mem0
+harshpandit007
+hayescode
+hcsum
+he-yufeng
+heng-ah
+Hexecu
+Himanshu-Sangshetti
+hjlarry
+HowieG
+HrushiYadav
+HScarb
+huveewomg
+Hybirdss
+ianupamsingh
+IgnazioDS
+immuhammadfurqan
+into-the-night
+invincible04
+Itz-Antaripa
+ixchio
+Jaco-Ren
+Jai0401
+JainamShah-22
+Jainish-S
+jarediaz
+jeanibarz
+Jerry-Terrasse
+jessai2026
+jesse-c
+jfeng18
+jferrettiboke
+jjjojoj
+joaomdmoura
+JoeSL
+johnwlockwood
+jonasiwnl
+josephchancey
+juananpe
+juaneloDev
+junmo1215
+Jupiter363
+KapilM26
+karthik-indla
+KarthikeyaKollu
+kartik-mem0
+katarinasupe
+ketangangal
+kimnamu
+kindertheo
+kirex0
+kirklin
+kk2211
+kmitul
+koi646
+kratos0718
+krescent
+Krishnachaitanyakc
+kriszlazar
+KushagraB424
+l1anch1
+lamost423
+lan17
+LeonieFreisinger
+lh0x00
+limboinf
+liviaellen
+longway-code
+lsvishaal
+LuciAkirami
+lucifertrj
+lvpx
+ly-wang19
+maamalama
+maccuryj
+mae5357
+mahone3297
+Malhis
+maljazaery
+manganeseheptoxide
+manthanguptaa
+mark-watson
+Mark-Zeng
+markmbain
+matanco1
+mauricioalarcon
+maxvonhippel
+me-tusharchandra
+mezotv
+MgeeeeK
+mggger
+mgoulart
+microbluey
+mikejgray
+Mingxiangyu
+Mini256
+misrasaurabh1
+mjzcng
+mogith-pn
+morgoth9808
+moyueheng
+mrbusche
+Mrinank-Bhowmick
+muhammed-mamun
+MUZAMMILPERVAIZ
+mvanhorn
+naman09
+NavyaAlapati13
+neilbhutada
+NightClover-code
+nikhilsharma26500
+NILAY1556
+niv-hertz
+NoahStapp
+norrishuang
+OfficialAbhinavSingh
+officialasishkumar
+OjusWiZard
+okaditya84
+omahs
+OsamaNabih
+oskarrough
+p-tirth
+Padarn
+paipeline
+ParseDark
+parshvadaftari
+Parteeksachdeva
+parthshr370
+parzival418
+Paulie-Aditya
+paurushmittal
+pc9
+Pecunia201
+peterj
+pragnyanramtha
+PranavPuranik
+PrashantDixit0
+prateekchhikara
+prathameshagrawal
+pratikgajjar
+PratikRai0101
+Prikshit7766
+Prithvi1994
+QunBB
+rafid001
+raghavtyagii
+rahulsharmavishwakarma
+rajib76
+rakheesingh
+ranjithkumar8352
+Rayhanpatel
+reachAnushaKondam
+Real5K
+Rhythm-08
+richawo
+Rishiraj2594
+RitwijParmar
+RobinALG87
+rocke2020
+rodboev
+rohitgr7
+ron-42
+roshan-shaik-ml
+rst0070
+rudra717
+rudrajmehta-mem0
+rupamoraczen
+rupeshbansal
+ryanrozich
+SaharshPatel24
+sahilyadav902
+sahithreddy05
+SakshiSrivastava2024
+SamuelDevdas
+sarkarsaurabh27
+sdht0
+seetharam-rajagopal
+sergio-toro
+SerSamgy
+shafdev
+shashank42
+ShauryaaSharma
+Sheharyar570
+shenxiangzhuang
+ShivamMenda
+shlokkhemani
+shraderdm
+shrivastavanolo
+shubhampal123
+shuoli84
+sidmohanty11
+siroa
+slobodaapl
+soapun
+soumil-rathi
+spike-spiegel-21
+srishti-git1110
+SSDWGG
+sssserrano
+subhadip001
+subhajit20
+SudoAnirudh
+sukkritsharmaofficial
+sw8fbar
+swarnaprakash
+sxu75374
+SZemse
+taranjeet
+techcontributor
+tgabi333
+theagenticguy
+thomasgtaylor
+tomasonjo
+TommyZihao
+TruptiAgrawal
+turtletongue
+Tushar-kalsi
+Ukong0324
+umran666
+utkarsh240799
+UzairNaeem3
+V-Silpin
+vatsalrathod16
+vedant381
+veeceey
+vgvoleg
+VictorECDSA
+VikramIyer125
+Vir-8
+vsatyamuralikrishna
+vuonghuuhung
+WayneCao
+whysosaket
+wobushixiaoj
+xiangpingjiang
+XiaojuCH
+xu-xiang
+xyb
+yashikabadaya
+yashs33244
+ygorth
+youneshima
+ytkimirti
+YuriyTW
+YusukeJustinNakajima
+zaiddkhan
+zegerhoogeboom
+zinyando
+Zlo7
+Zncl2222
+zzaym

.github/advanced-issue-labeler.yml

@@ -1,18 +1,15 @@
-# Maps dropdown selections to GitHub labels
-# Used by the advanced-issue-labeler GitHub Action
-
-component:
-  - label: "sdk-python"
-    matcher: "Core / Python SDK"
-  - label: "sdk-typescript"
-    matcher: "TypeScript SDK"
-  - label: "vector-store"
-    matcher: "Vector Store"
-  - label: "graph-memory"
-    matcher: "Graph Memory"
-  - label: "ollama"
-    matcher: "Ollama"
-  - label: "openclaw"
-    matcher: "OpenClaw"
-  - label: "rest-api"
-    matcher: "REST API"
+policy:
+  - section:
+      - id: ['component']
+        block-list: ['Other']
+        label:
+          - name: 'sdk-python'
+            keys: ['Python SDK']
+          - name: 'sdk-typescript'
+            keys: ['TypeScript SDK']
+          - name: 'vector-store'
+            keys: ['Vector Store']
+          - name: 'plugin'
+            keys: ['Plugin']
+          - name: 'rest-api'
+            keys: ['REST API']

.github/component-keywords.json

@@ -0,0 +1,40 @@
+{
+  "language": {
+    "sdk-python": [
+      "python", "pip install", "pypi", "pyproject", "requirements.txt",
+      "from mem0", "import mem0", "traceback", "pydantic", "asyncmemory",
+      "poetry", "virtualenv", "venv", "conda", "pytest", "async def"
+    ],
+    "sdk-typescript": [
+      "typescript", "javascript", "pnpm", "yarn", "node.js", "nodejs",
+      "mem0-ts", "mem0ai/oss", "tsconfig", "await import",
+      "=> {", "undefined is not"
+    ]
+  },
+  "area": {
+    "plugin": [
+      "openclaw", "openclaw-mem0", "openclaw.json", "openclaw plugin",
+      "claude code", "opencode", "pi agent", "mem0-plugin",
+      "cursor plugin", "codex plugin", "editor plugin"
+    ],
+    "cli": ["mem0-cli", "@mem0/cli", "npx mem0", "command line"],
+    "vector-store": [
+      "pgvector", "pinecone", "chroma", "chromadb", "weaviate",
+      "milvus", "faiss", "vector store", "vectorstore",
+      "elasticsearch", "supabase", "azure ai search",
+      "s3 vectors", "mongodb"
+    ],
+    "integrations": [
+      "vercel ai", "vercel-ai-sdk", "@mem0/vercel-ai-provider",
+      "llamaindex", "crewai", "autogen", "langgraph"
+    ],
+    "rest-api": [
+      "rest api", "fastapi", "docker-compose", "/v1/memories",
+      "localhost:8000", "localhost:8888", "curl -x", "http endpoint"
+    ],
+    "documentation": [
+      "docs.mem0.ai", "documentation", "typo", "readme", "docstring", "broken link",
+      "issue on docs", "docs:", "link to the docs page", "issue with current documentation"
+    ]
+  }
+}

.github/labeler.yml

@@ -0,0 +1,59 @@
+sdk-python:
+  - changed-files:
+      - any-glob-to-any-file:
+          - 'mem0/**'
+          - 'tests/**'
+          - 'cli/python/**'
+          - 'pyproject.toml'
+          - 'poetry.lock'
+
+sdk-typescript:
+  - changed-files:
+      - any-glob-to-any-file:
+          - 'mem0-ts/**'
+          - 'cli/node/**'
+
+vector-store:
+  - changed-files:
+      - any-glob-to-any-file:
+          - 'mem0/vector_stores/**'
+          - 'mem0-ts/src/oss/src/vector_stores/**'
+
+rest-api:
+  - changed-files:
+      - any-glob-to-any-file: 'server/**'
+
+integrations:
+  - changed-files:
+      - any-glob-to-any-file: 'integrations/**'
+
+plugin:
+  - changed-files:
+      - all-globs-to-any-file:
+          - 'integrations/**'
+          - '!integrations/vercel-ai-sdk/**'
+      - any-glob-to-any-file:
+          - 'skills/**'
+          - '.agents/**'
+          - '.claude-plugin/**'
+          - '.codex-plugin/**'
+          - '.cursor-plugin/**'
+          - 'marketplace.json'
+
+cli:
+  - changed-files:
+      - any-glob-to-any-file: 'cli/**'
+
+documentation:
+  - changed-files:
+      - any-glob-to-any-file:
+          - 'docs/**'
+          - 'examples/**'
+          - '*.md'
+
+ci:
+  - changed-files:
+      - any-glob-to-any-file:
+          - '.github/**'
+          - 'scripts/**'
+          - '.pre-commit-config.yaml'

.github/scripts/infer-component-labels.js

@@ -0,0 +1,44 @@
+const fs = require('fs');
+
+function componentLabels(keywords) {
+  return Object.values(keywords).flatMap(Object.keys);
+}
+
+function toMatcher(term) {
+  const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const prefix = /^[a-z0-9]/i.test(term) ? '\\b' : '';
+  return new RegExp(prefix + escaped, 'i');
+}
+
+function scoreGroup(text, group) {
+  let winner = null;
+  let best = 0;
+  for (const [label, terms] of Object.entries(group)) {
+    const score = terms.reduce((n, term) => n + (toMatcher(term).test(text) ? 1 : 0), 0);
+    if (score > best) {
+      winner = label;
+      best = score;
+    }
+  }
+  return winner;
+}
+
+const UMBRELLA = { plugin: 'integrations' };
+
+function inferComponentLabels(text, keywords) {
+  if (!text) return [];
+  const labels = [scoreGroup(text, keywords.language), scoreGroup(text, keywords.area)].filter(
+    Boolean,
+  );
+  for (const label of labels.slice()) {
+    const parent = UMBRELLA[label];
+    if (parent && !labels.includes(parent)) labels.push(parent);
+  }
+  return labels;
+}
+
+function loadKeywords(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+module.exports = { componentLabels, inferComponentLabels, loadKeywords };

.github/scripts/infer-component-labels.test.js

@@ -0,0 +1,102 @@
+const assert = require('assert');
+const path = require('path');
+const { inferComponentLabels, loadKeywords } = require('./infer-component-labels.js');
+
+const keywords = loadKeywords(path.join(__dirname, '..', 'component-keywords.json'));
+
+const cases = [
+  {
+    number: 6210,
+    title: "but(anthropic): sampling parameters returns 400 error for new model",
+    body: "### Component\n\nCore / Python SDK\n\n### Description\n\n### Summary\n\nWhen using Anthropic latest models such as `claude-opus-4-7`, `claude-opus-4-8`, or `claude-sonnet-5`, Mem0 still sends sampling parameters like `temperature` / `top_p`. These models do not support those parameters, causing Anthropic API requests to fail.\n\nSee https://platform.claude.com/docs/en/about-claude/models/migration-guide\n\n### Steps to Reproduce\n\n```python\n  from mem0 import Memory\n\n  m = Memory.from_config({\n      \"llm\": {\n          \"provider\": \"anthropic\",\n          \"config\": {\n              \"model\": \"claude-opus-4-8\",\n              \"api_key\": \"your-anthropic-api-key\"\n          },\n      },\n      ...\n  })\n```\n\n### Expected Behavior\n\nMem0 should detect Anthropic models that do not support sampling parameters and omit temperature and top_p from the request.\n\nFor models that still support sampling parameters, such as claude-opus-4-6, claude-sonnet-4-6, and claude-haiku-4-5, Mem0 should continue sending supported sampling parameters till they're deprecated.\n\n### Actual Behavior\n\nMem0 includes temperature by default for Anthropic requests. With newer Anthropic models that do not support sampling parameters, the API request fails because unsupported parameters are sent.\n\n### Environment\n\n  - mem0 version: 2.0.11\n  - Python/Node version: Python 3.11\n  - OS: macOS\n",
+    expected: ["sdk-python"],
+  },
+  {
+    number: 5770,
+    title: "feat(ts-sdk): add FastEmbed embedding provider",
+    body: "## Summary\n\nThe Python SDK supports **FastEmbed** as an embedding provider, but the TypeScript OSS SDK (`mem0ai/oss`) does not. Add it to bring the TS SDK to parity.\n\n| | |\n|---|---|\n| Python reference | `mem0/embeddings/fastembed.py` |\n| Registered in (Python) | `mem0/utils/factory.py` (EmbedderFactory) |\n| Target file (TypeScript) | `mem0-ts/src/oss/src/embeddings/fastembed.ts` |\n| Suggested implementation | Use the `fastembed` npm package (ONNX local embeddings). |\n\n## Requirements\n\n- [ ] Implement `FastEmbedEmbedder` in `mem0-ts/src/oss/src/embeddings/fastembed.ts`, extending `Embedder` (`mem0-ts/src/oss/src/embeddings/base.ts`) and mirroring the Python provider's behavior (embed / embedBatch).\n- [ ] Register the `\"fastembed\"` provider in `mem0-ts/src/oss/src/utils/factory.ts` (EmbedderFactory).\n- [ ] Add config typing in `mem0-ts/src/oss/src/types/`.\n- [ ] Add a unit test under `mem0-ts/src/oss/src/tests/`.\n- [ ] Add `fastembed` to `mem0-ts/package.json` (optional/peer dependency, lazy-imported like other providers).\n- [ ] Update docs under `docs/` if this provider is user-facing.\n\n## Reference pattern\n\nMirror an existing TS provider: `embeddings/openai.ts`.\n\n## Notes\n\n`fastembed` (v2.x) is the JS port of Qdrant's FastEmbed — local/offline embeddings. Mirror the default model in `mem0/embeddings/fastembed.py`.\n\n---\n_Part of the TypeScript ↔ Python SDK provider-parity effort. One provider per issue (atomic)._\n",
+    expected: ["sdk-typescript"],
+  },
+  {
+    number: 3940,
+    title: "Milvus database will return distance not similarity score",
+    body: "### 🐛 Describe the bug\n\nMilvus database will return distance not similarity score\n\n## in milvus.py\n\ndef _parse_output(self, data: list):\n        \"\"\"\n        Parse the output data.\n\n        Args:\n            data (Dict): Output data.\n\n        Returns:\n            List[OutputData]: Parsed output data.\n        \"\"\"\n        memory = []\n\n        for value in data:\n            uid, score, metadata = (\n                value.get(\"id\"),\n                value.get(\"distance\"),  # here\n                value.get(\"entity\", {}).get(\"metadata\"),\n            )\n\n            memory_obj = OutputData(id=uid, score=score, payload=metadata)\n            memory.append(memory_obj)\n\n        return memory\n",
+    expected: ["vector-store"],
+  },
+  {
+    number: 5290,
+    title: "Recall search failed: Bad Request Using OpenAI Embedding Model",
+    body: "### Component\n\nOpenClaw\n\n### Description\n\n### Summary\nuse openclaw.json config:\n\n```json\n...\n\"embedder\": {\n              \"provider\": \"openai\",\n              \"config\": {\n                \"model\": \"bge-base-zh-v1.5\",\n                \"embedding_dims\": 1024,\n                \"embeddingDims\": 1024,\n                \"url\": \"https://xxxxxxxxx/v1\",\n                \"apiKey\": \"xxxxxxxxxxxx\"\n              }\n            },\n\"vectorStore\": {\n              \"provider\": \"qdrant\",\n              \"config\": {\n                \"url\": \"http://qdrant:6333\",\n                \"apiKey\": \"${QDRANT_API_KEY}\",\n                \"collectionName\": \"mem0\",\n                \"embeddingModelDims\": 1024\n              }\n            }\n```\n```\n\nopenclaw log info is：\n\n```\n23:14:20 Api key is used with unsecure connection.\n23:14:21 [mem0] Recall search failed: Bad Request\n23:14:21 [plugins] openclaw-mem0: skills-mode recall (strategy=smart) injecting 0 memories (~20 tokens)\n23:14:22 [ws] ⇄ res ✓ sessions.list 256ms conn=d1eb9bc4…17da id=201b8113…c9dc\n23:14:22 [ws] ⇄ res ✓ sessions.list 264ms conn=d1eb9bc4…17da id=4939f962…2f16\n23:14:34 [ws] ⇄ res ✓ sessions.list 250ms conn=d1eb9bc4…17da id=f7ad503f…baa6\n23:15:12 [mem0] **Recall search failed: Bad Request**\n23:15:12 [plugins] openclaw-mem0: skills-mode recall (strategy=smart) injecting 0 memories (~20 tokens)\n23:15:12 [ws] ⇄ res ✓ sessions.list 288ms conn=d1eb9bc4…17da id=9e20bb86…371e\n23:15:13 [ws] ⇄ res ✓ sessions.list 268ms conn=d1eb9bc4…17da id=3b49a2ad…7ada\n23:15:20 [ws] ⇄ res ✓ sessions.list 235ms conn=d1eb9bc4…17da id=a192da30…069f\n```\n\n### Actual Behavior\n\nembedding model response ok,response message has 1024 vectors,but the vectors are submitted to vector-db:qdrant with all zero vectors,and vectors has only 256 size.\n\n```http\nPOST /collections/mem0/points/search HTTP/1.1\nhost: qdrant:6333\nconnection: keep-alive\nuser-agent: qdrant-js/1.13.0\napi-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxx\nContent-Type: application/json\nAccept: application/json\naccept-language: *\nsec-fetch-mode: cors\naccept-encoding: gzip, deflate\ncontent-length: 651\n\n{\"vector\":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],\"limit\":120,\"offset\":0,\"filter\":{\"must\":[{\"key\":\"user_id\",\"match\":{\"value\":\"agent\"}}]},\"with_payload\":true,\"with_vector\":false}\n\n**HTTP/1.1 400 Bad Request**\ntransfer-encoding: chunked\ncontent-type: application/json\nvary: accept-encoding, Origin, Access-Control-Request-Method, Access-Control-Request-Headers\ncontent-encoding: gzip\n\n```\n\n### Expected Behavior\n\nembedding model response ok by tcpdump, response message has 1024 vectors,and this vectors are submitted to vector-db:qdrant with the same vectors,and vectors has also 1024 size.\n\n\n### Environment\n\n- openclaw-mem0 version: 1.0.11\n- qdrant: 1.13.6\n",
+    expected: ["plugin", "integrations"],
+  },
+  {
+    number: 3696,
+    title: "Cannot set expiration_date for memory in REST API server (Docker Compose)",
+    body: "### 🐛 Describe the bug\n\nI'm using docker compose to deploy a REST API server. When adding memory, I'm unable to set the expiration_date. Is this feature not supported?",
+    expected: ["rest-api"],
+  },
+  {
+    number: 6252,
+    title: "cursor: on_file_read_cursor.sh ignores auto_search / MEM0_AUTO_SEARCH",
+    body: "### Component\n\nCursor / mem0-plugin\n\n### Description\n\n`on_file_read_cursor.sh` never checks `MEM0_AUTO_SEARCH`. In Claude Code, #6065/#6071 added a guard on `on_file_read.sh`, but the Cursor PreToolUse variant still always calls `file_context.py` (and thus Platform search) once `MEM0_API_KEY` is set.\n\n### Expected\n\nWhen `auto_search: false` / `MEM0_AUTO_SEARCH=false`, `on_file_read_cursor.sh` should exit 0 without searching.\n\n### Actual\n\nTimeline search still runs.\n\n### Related\n\n#6065, #6071, #6250\n",
+    expected: ["plugin", "integrations"],
+  },
+  {
+    number: 6032,
+    title: "docs: fix typos and punctuation errors across docs",
+    body: "### Description\n\n### Page\nMultiple pages — see list below.\n\n### What's Wrong or Missing\n1. https://docs.mem0.ai/components/llms/overview — \"a llm\" should be \"an LLM\"\n2. https://docs.mem0.ai/components/vectordbs/dbs/azure — 2 comma splices + \"setup\" used as a verb (should be \"set up\")\n3. https://docs.mem0.ai/components/embedders/models/azure_openai — \"from the Azure.\" is an incomplete sentence\n4. https://docs.mem0.ai/components/llms/models/azure_openai — same incomplete \"from the Azure\" phrasing\n5. https://docs.mem0.ai/cookbooks/companions/voice-companion-openai — \"an important information\" (uncountable noun)\n6. https://docs.mem0.ai/cookbooks/essentials/exporting-memories — comma splice\n7. https://docs.mem0.ai/cookbooks/integrations/tavily-search — \"usecase\" should be \"use case\"\n8. https://docs.mem0.ai/cookbooks/overview — broken parallelism in bullet list\n9. README.md — \"Github App\" should be \"GitHub App\"\n10. https://docs.mem0.ai/platform/overview — table cell not capitalized like other rows\n\n### Suggested Fix\nApply the corrections listed above for each page. I will submit a PR soon addressing all of the issues mentioned.",
+    expected: ["documentation"],
+  },
+];
+
+const cliRegressionCase = {
+  number: 3144,
+  title: "Bug Report: Memory Score Does Not Match Expected Relevance in Local Search",
+  body: "### 🐛 Describe the bug\n\n#### Description\n\nWhen using the locally deployed `mem0` server, the returned memory `score` from the `search` interface does not align with the expected semantic relevance. In particular, irrelevant or less relevant memories sometimes receive higher scores than directly related ones.\n\n#### Reproduction Steps\n\n```python\nmem0 = mem0_client(mode=\"local\")\nprint(\"Mem0 client initialized successfully.\")\n\nprint(\"Adding memories...\")\nresult = mem0.add(messages=[\n    {\"role\": \"user\", \"content\": \"I like drinking coffee in the morning\"},\n    {\"role\": \"user\", \"content\": \"I enjoy reading books at night\"}\n], user_id=\"alice\")\nprint(\"Memory added:\", result)\n\nprint(\"Searching memories...\")\nsearch_result = mem0.search(query=\"coffee\", user_id=\"alice\", top_k=2)\nprint(\"Search results:\", search_result)\n```\n\n#### Actual Output\n\n```json\n{\n  \"results\": [\n    {\n      \"id\": \"5099b5be-c673-4f09-99de-a196f43b6476\",\n      \"memory\": \"Likes drinking coffee in the morning\",\n      \"score\": 0.5115111920687857\n    },\n    {\n      \"id\": \"08df5c51-c52b-4c45-a5b6-b3f864ea149a\",\n      \"memory\": \"Enjoys reading books at night\",\n      \"score\": 0.7755568273863331\n    }\n  ],\n  \"relations\": [\n    {\"source\": \"coffee\", \"relationship\": \"consumed_in\", \"destination\": \"morning\"},\n    {\"source\": \"user_id:_alice\", \"relationship\": \"likes\", \"destination\": \"coffee\"},\n    {\"source\": \"user_id:_alice\", \"relationship\": \"likes_drinking\", \"destination\": \"coffee\"},\n    {\"source\": \"user_id:_alice\", \"relationship\": \"in_time\", \"destination\": \"morning\"},\n    {\"source\": \"user_id:_alice\", \"relationship\": \"drinks_in\", \"destination\": \"morning\"}\n  ]\n}\n```\n\n#### Expected Behavior\n\nThe memory `\"Likes drinking coffee in the morning\"` should have a **higher score** than `\"Enjoys reading books at night\"` when querying for `\"coffee\"`, since it is directly semantically related.",
+};
+
+let failures = 0;
+
+function run(name, fn) {
+  try {
+    fn();
+    console.log(`PASS ${name}`);
+  } catch (err) {
+    failures++;
+    console.error(`FAIL ${name}: ${err.message}`);
+  }
+}
+
+for (const { number, title, body, expected } of cases) {
+  const text = `${title}
+
+${body}`;
+  run(`#${number}`, () => {
+    assert.deepStrictEqual(inferComponentLabels(text, keywords), expected);
+  });
+}
+
+run('#3144 cliKeywordPrefixSubstringRegression', () => {
+  const text = `${cliRegressionCase.title}
+
+${cliRegressionCase.body}`;
+  const inferred = inferComponentLabels(text, keywords);
+  assert.ok(!inferred.includes('cli'), `expected 'cli' absent (body contains 'Mem0 client', a substring of the removed 'mem0 cli' term), got ${JSON.stringify(inferred)}`);
+});
+
+run('noKeywordMatchReturnsEmptyArray', () => {
+  const text = 'The weather today is sunny and I went for a walk in the park with my dog.';
+  assert.deepStrictEqual(inferComponentLabels(text, keywords), []);
+});
+
+run('emptyStringReturnsEmptyArray', () => {
+  assert.deepStrictEqual(inferComponentLabels('', keywords), []);
+});
+
+if (failures > 0) {
+  console.error(`
+${failures} test(s) failed.`);
+  process.exit(1);
+}
+console.log(`
+All ${cases.length + 3} tests passed.`);

.github/scripts/pr-gate-docs-exemption.test.js

@@ -0,0 +1,60 @@
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const gate = fs.readFileSync(path.join(__dirname, '..', 'workflows', 'pr-gate.yml'), 'utf8');
+
+const rootDocsLine = gate.match(/^\s*(const rootDocs = new Set\(\['[\w.-]+'(?:, '[\w.-]+')*\]\);)\s*$/m);
+const isDocsLine = gate.match(/^\s*(const isDocs = \(\w+\) => [\w.'"()[\]\/, |&!=><+-]+;)\s*$/m);
+
+assert.ok(
+  rootDocsLine,
+  'pr-gate.yml no longer declares rootDocs as a single-line Set of quoted filenames. ' +
+    'This test evaluates that line to exercise the shipped predicate rather than a copy of it, ' +
+    'and only accepts a literal shape, so widen the pattern deliberately or keep the declaration literal.',
+);
+assert.ok(
+  isDocsLine,
+  'pr-gate.yml no longer declares isDocs as a single-line arrow expression. ' +
+    'This test evaluates that line to exercise the shipped predicate rather than a copy of it, ' +
+    'and refuses anything with a statement body, so keep it an expression.',
+);
+
+const isDocs = new Function(`${rootDocsLine[1]}\n${isDocsLine[1]}\nreturn isDocs;`)();
+
+const exempt = (files) => files.length > 0 && files.every(isDocs);
+
+const cases = [
+  [['docs/a.mdx'], true],
+  [['docs/platform/quickstart.mdx'], true],
+  [['README.md'], true],
+  [['CONTRIBUTING.md'], true],
+  [['CODE_OF_CONDUCT.md'], true],
+  [['SECURITY.md'], true],
+  [['README.md', 'CONTRIBUTING.md', 'docs/x.mdx'], true],
+  [['AGENTS.md'], false],
+  [['CLAUDE.md'], false],
+  [['LLM.md'], false],
+  [['README.md', 'AGENTS.md'], false],
+  [['README.md', 'mem0/memory/main.py'], false],
+  [['skills/mem0/SKILL.md'], false],
+  [['.github/AGENTS.md'], false],
+  [['.github/workflows/ci.yml'], false],
+  [['docs-site/index.md'], false],
+  [[], false],
+];
+
+let failures = 0;
+for (const [files, expected] of cases) {
+  const actual = exempt(files);
+  const label = files.length ? files.join(', ') : '(no files)';
+  if (actual === expected) {
+    console.log(`ok   ${label} -> ${actual ? 'exempt' : 'gated'}`);
+  } else {
+    failures += 1;
+    console.log(`FAIL ${label} -> ${actual ? 'exempt' : 'gated'}, expected ${expected ? 'exempt' : 'gated'}`);
+  }
+}
+
+console.log(failures === 0 ? '\nPASS' : `\nFAIL (${failures} cases)`);
+process.exit(failures === 0 ? 0 : 1);

.github/scripts/vouch-decision.test.js

@@ -0,0 +1,122 @@
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const workflowPath = path.join(__dirname, '..', 'workflows', 'vouch-check-pr.yml');
+const workflow = fs.readFileSync(workflowPath, 'utf8');
+
+const PINNED_VOUCH_SHA = 'd66fa29a64600490892131ad87597c30c91fcac4';
+
+assert.ok(
+  workflow.includes(`mitchellh/vouch/action/check-pr@${PINNED_VOUCH_SHA}`),
+  `decide() below is a hand transcription of gh-check-pr from vouch/github.nu at ${PINNED_VOUCH_SHA} (v1.5.0). ` +
+    'It reads the action, it does not run it, so on its own it agrees with itself whatever the action does. ' +
+    'vouch-check-pr.yml now pins a different revision: re-read gh-check-pr there, update decide() and the ' +
+    'decision table in .github/AGENTS.md to match it, then set PINNED_VOUCH_SHA to the new SHA.',
+);
+
+const actionDefaults = { 'require-vouch': true, 'auto-close': false };
+
+const booleanInput = (name) => {
+  const match = workflow.match(new RegExp(`^\\s+${name}:\\s*"?(true|false)"?\\s*$`, 'm'));
+  return match ? match[1] === 'true' : actionDefaults[name];
+};
+
+const requireVouch = booleanInput('require-vouch');
+const autoClose = booleanInput('auto-close');
+
+const commentedStatus = (() => {
+  const match = workflow.match(/steps\.vouch\.outputs\.status == '(\w+)'/);
+  assert.ok(match, 'the follow-up comment step is not keyed on a vouch status');
+  return match[1];
+})();
+
+const decide = (author) => {
+  if (author === 'bot') return { status: 'skipped', closed: false, actionComments: false };
+  if (author === 'collaborator' || author === 'vouched') {
+    return { status: 'vouched', closed: false, actionComments: false };
+  }
+  if (author === 'denounced') {
+    if (!autoClose) return { status: 'closed', closed: false, actionComments: false };
+    return { status: 'closed', closed: true, actionComments: true };
+  }
+  if (!requireVouch) return { status: 'allowed', closed: false, actionComments: false };
+  if (!autoClose) return { status: 'closed', closed: false, actionComments: false };
+  return { status: 'closed', closed: true, actionComments: true };
+};
+
+const outcome = (author) => {
+  const result = decide(author);
+  return { ...result, workflowComments: result.status === commentedStatus };
+};
+
+const cases = [
+  { author: 'bot', closed: false, comments: 0 },
+  { author: 'collaborator', closed: false, comments: 0 },
+  { author: 'vouched', closed: false, comments: 0 },
+  { author: 'unvouched', closed: false, comments: 1 },
+  { author: 'denounced', closed: true, comments: 1 },
+];
+
+let failures = 0;
+for (const expected of cases) {
+  const actual = outcome(expected.author);
+  const comments = Number(actual.actionComments) + Number(actual.workflowComments);
+  try {
+    assert.strictEqual(actual.closed, expected.closed, `${expected.author}: closed`);
+    assert.strictEqual(comments, expected.comments, `${expected.author}: comment count`);
+    console.log(`ok   ${expected.author} -> ${actual.status}, closed=${actual.closed}, comments=${comments}`);
+  } catch (error) {
+    failures += 1;
+    console.log(`FAIL ${expected.author} -> ${actual.status}, closed=${actual.closed}, comments=${comments}`);
+    console.log(`     ${error.message}: expected ${JSON.stringify(expected)}`);
+  }
+}
+
+console.log(`\nvouch@${PINNED_VOUCH_SHA.slice(0, 7)} require-vouch=${requireVouch} auto-close=${autoClose} comment-on=${commentedStatus}`);
+
+const parseDenounced = (contents) => new Set(contents
+  .split('\n')
+  .map((line) => line.trim())
+  .filter((line) => line.startsWith('-'))
+  .map((line) => line.slice(1).split(/\s+/)[0].split(':').pop().toLowerCase())
+  .filter(Boolean));
+
+const gate = fs.readFileSync(path.join(__dirname, '..', 'workflows', 'pr-gate.yml'), 'utf8');
+assert.ok(
+  gate.includes(".filter((line) => line.startsWith('-'))"),
+  'pr-gate.yml no longer parses the denounce list the way this test does',
+);
+
+const vouched = fs.readFileSync(path.join(__dirname, '..', 'VOUCHED.td'), 'utf8');
+const denouncedNow = parseDenounced(vouched);
+const sample = parseDenounced([
+  '# -notacomment is a comment line',
+  '-SpamBot  seeded 2026-08-12',
+  '-github:OtherSpammer',
+  'realcontributor',
+  '',
+].join('\n'));
+
+let parseFailures = 0;
+for (const [label, actual, expected] of [
+  ['denounce entry, with note', sample.has('spambot'), true],
+  ['denounce entry, platform prefixed', sample.has('otherspammer'), true],
+  ['comment line is not an entry', sample.has('notacomment'), false],
+  ['vouched entry is not denounced', sample.has('realcontributor'), false],
+  ['live file parses without throwing', denouncedNow instanceof Set, true],
+]) {
+  try {
+    assert.strictEqual(actual, expected, label);
+    console.log(`ok   ${label}`);
+  } catch (error) {
+    parseFailures += 1;
+    console.log(`FAIL ${label}: ${error.message}`);
+  }
+}
+
+console.log(`denounced in VOUCHED.td: ${denouncedNow.size}`);
+
+const total = failures + parseFailures;
+console.log(total === 0 ? 'PASS' : `FAIL (${total} assertions)`);
+process.exit(total === 0 ? 0 : 1);

.github/workflows/agent-plugins-python-checks.yml

@@ -0,0 +1,97 @@
+name: Agent Plugins Python Checks
+
+# Python runtime, adapters, generated bundles, and portable plugin validation.
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'integrations/agent-plugin-core/**'
+      - '!integrations/agent-plugin-core/typescript/**'
+      - 'integrations/mem0-agent-plugin/**'
+      - 'integrations/claude-code-plugin/**'
+      - 'integrations/cursor-plugin/**'
+      - 'integrations/codex-plugin/**'
+      - 'integrations/kimi-plugin/**'
+      - 'integrations/antigravity-plugin/**'
+      - 'marketplace.json'
+      - '.agents/plugins/marketplace.json'
+      - '.claude-plugin/marketplace.json'
+      - '.codex-plugin/marketplace.json'
+      - '.cursor-plugin/marketplace.json'
+      - '.kimi-plugin/marketplace.json'
+      - '.github/workflows/agent-plugins-python-checks.yml'
+  workflow_call:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install runtime test tooling
+        if: matrix.python-version == '3.10'
+        run: pip install pytest
+
+      - name: Install build and test tooling
+        if: matrix.python-version != '3.10'
+        run: pip install pytest ruff -r integrations/agent-plugin-core/requirements-dev.txt
+
+      - name: Check Python runtime compatibility
+        run: >-
+          python3 -m compileall -q
+          integrations/agent-plugin-core/python
+          integrations/claude-code-plugin/adapters
+          integrations/cursor-plugin/hooks
+          integrations/codex-plugin/hooks
+          integrations/kimi-plugin/hooks
+          integrations/antigravity-plugin/hooks
+
+      - name: Lint
+        if: matrix.python-version == '3.12'
+        run: >-
+          python3 -m ruff check
+          integrations/agent-plugin-core
+          integrations/claude-code-plugin
+          integrations/cursor-plugin
+          integrations/codex-plugin
+          integrations/kimi-plugin
+          integrations/antigravity-plugin
+
+      - name: Verify installable plugins are current
+        if: matrix.python-version == '3.12'
+        run: |
+          for host in claude-code cursor codex kimi antigravity; do
+            python3 integrations/agent-plugin-core/build/build.py "$host" --kind native --check
+          done
+          python3 integrations/agent-plugin-core/build/build.py mem0-agent-plugin --kind portable --check
+
+      - name: Run Python 3.10 runtime tests
+        if: matrix.python-version == '3.10'
+        run: >-
+          python3 -m pytest -q
+          integrations/claude-code-plugin/tests/test_memory_core.py
+          integrations/claude-code-plugin/tests/test_telemetry.py
+
+      - name: Run full tests
+        if: matrix.python-version != '3.10'
+        run: >-
+          python3 -m pytest -q
+          integrations/agent-plugin-core/tests
+          integrations/claude-code-plugin/tests
+          integrations/cursor-plugin/tests
+          integrations/codex-plugin/tests
+          integrations/kimi-plugin/tests
+          integrations/antigravity-plugin/tests
+          --ignore=integrations/claude-code-plugin/tests/integration

.github/workflows/agent-plugins-typescript-checks.yml

@@ -0,0 +1,42 @@
+name: Agent Plugins TypeScript Checks
+
+# Shared TypeScript runtime checks. Each consuming integration keeps its own
+# build workflow, which is also triggered when this shared core changes.
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'integrations/agent-plugin-core/typescript/**'
+      - '.github/workflows/agent-plugins-typescript-checks.yml'
+  workflow_call:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'pnpm'
+          cache-dependency-path: integrations/agent-plugin-core/typescript/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: integrations/agent-plugin-core/typescript
+        run: pnpm install --frozen-lockfile
+
+      - name: Type check
+        working-directory: integrations/agent-plugin-core/typescript
+        run: pnpm typecheck
+
+      - name: Run tests
+        working-directory: integrations/agent-plugin-core/typescript
+        run: pnpm test

.github/workflows/cd.yml

@@ -1,18 +1,33 @@
 name: Publish Python 🐍 distributions 📦 to PyPI and TestPyPI
 
+# Dispatched by release.yml (Release Router) when a release tagged v* is
+# published. Can also be dispatched manually to re-publish a tag.
 on:
-  release:
-    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. v1.2.3)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Unused for PyPI (pre-releases are expressed in the version itself); accepted for router uniformity'
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build-n-publish:
     name: Build and publish Python 🐍 distributions 📦 to PyPI and TestPyPI
-    if: startsWith(github.event.release.tag_name, 'v')
+    # Pure SDK version tags only (v1.2.3) — excludes package-prefixed tags
+    # like vercel-ai-v* that also start with 'v'
+    if: startsWith(inputs.tag, 'v') && !contains(inputs.tag, '-v')
     runs-on: ubuntu-latest
     permissions:
       id-token: write
     steps:
       - uses: actions/checkout@v2
+        with:
+          ref: ${{ inputs.tag }}
 
       - name: Set up Python
         uses: actions/setup-python@v2
@@ -39,7 +54,6 @@ jobs:
       #     packages_dir: dist/
 
       - name: Publish distribution 📦 to PyPI
-        if: startsWith(github.ref, 'refs/tags/v')
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           packages_dir: dist/

.github/workflows/ci-gate.yml

@@ -0,0 +1,289 @@
+name: CI Gate
+
+# Single required status check for all PRs.
+#
+# Path-filtered CI workflows can't be marked as required in branch
+# protection: on a PR that doesn't touch their paths they never report, and
+# the required check hangs at "Expected" forever. This gate solves that. It
+# runs on every PR, detects which packages changed, calls only the relevant
+# package CI workflows (as reusable workflows), and the final "CI Gate" job
+# reports the aggregate result — success when every invoked pipeline passed
+# (skipped pipelines are fine), failure when any failed.
+#
+# Branch protection should require exactly one status check: "CI Gate".
+#
+# Package CI workflows keep their own push-to-main and workflow_dispatch
+# triggers; only their pull_request triggers moved here. To wire in a new
+# package: add a filter under the `changes` job, a call job that `uses:` the
+# package workflow, and list the call job in the gate's `needs`.
+
+on:
+  pull_request:
+
+concurrency:
+  group: ci-gate-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  changes:
+    name: Detect changed packages
+    runs-on: ubuntu-latest
+    outputs:
+      python_sdk: ${{ steps.filter.outputs.python_sdk }}
+      ts_sdk: ${{ steps.filter.outputs.ts_sdk }}
+      cli_python: ${{ steps.filter.outputs.cli_python }}
+      cli_node: ${{ steps.filter.outputs.cli_node }}
+      openclaw: ${{ steps.filter.outputs.openclaw }}
+      agent_plugins_python: ${{ steps.filter.outputs.agent_plugins_python }}
+      agent_plugins_typescript: ${{ steps.filter.outputs.agent_plugins_typescript }}
+      opencode_plugin: ${{ steps.filter.outputs.opencode_plugin }}
+      pi_agent_plugin: ${{ steps.filter.outputs.pi_agent_plugin }}
+      deepseek_plugin: ${{ steps.filter.outputs.deepseek_plugin }}
+      n8n_nodes_mem0: ${{ steps.filter.outputs.n8n_nodes_mem0 }}
+      zapier_mem0: ${{ steps.filter.outputs.zapier_mem0 }}
+      mem0_strands: ${{ steps.filter.outputs.mem0_strands }}
+      docs_llms_txt: ${{ steps.filter.outputs.docs_llms_txt }}
+      github_scripts: ${{ steps.filter.outputs.github_scripts }}
+    steps:
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          # Each filter mirrors the package workflow's old pull_request
+          # paths, plus the package workflow file itself and this gate file
+          # (changing either must re-exercise the pipeline).
+          filters: |
+            python_sdk:
+              - 'mem0/**'
+              - 'tests/**'
+              - 'pyproject.toml'
+              - '.github/workflows/ci.yml'
+              - '.github/workflows/ci-gate.yml'
+            ts_sdk:
+              - 'mem0-ts/**'
+              - '.github/workflows/ts-sdk-ci.yml'
+              - '.github/workflows/ci-gate.yml'
+            cli_python:
+              - 'cli/python/**'
+              - '.github/workflows/cli-python-ci.yml'
+              - '.github/workflows/ci-gate.yml'
+            cli_node:
+              - 'cli/node/**'
+              - '.github/workflows/cli-node-ci.yml'
+              - '.github/workflows/ci-gate.yml'
+            openclaw:
+              - 'integrations/openclaw/**'
+              - 'integrations/agent-plugin-core/typescript/**'
+              - '.github/workflows/openclaw-checks.yml'
+              - '.github/workflows/ci-gate.yml'
+            agent_plugins_python:
+              - 'integrations/agent-plugin-core/**'
+              - '!integrations/agent-plugin-core/typescript/**'
+              - 'integrations/mem0-agent-plugin/**'
+              - 'integrations/claude-code-plugin/**'
+              - 'integrations/cursor-plugin/**'
+              - 'integrations/codex-plugin/**'
+              - 'integrations/kimi-plugin/**'
+              - 'integrations/antigravity-plugin/**'
+              - 'marketplace.json'
+              - '.agents/plugins/marketplace.json'
+              - '.claude-plugin/marketplace.json'
+              - '.codex-plugin/marketplace.json'
+              - '.cursor-plugin/marketplace.json'
+              - '.kimi-plugin/marketplace.json'
+              - '.github/workflows/agent-plugins-python-checks.yml'
+              - '.github/workflows/ci-gate.yml'
+            agent_plugins_typescript:
+              - 'integrations/agent-plugin-core/typescript/**'
+              - '.github/workflows/agent-plugins-typescript-checks.yml'
+              - '.github/workflows/ci-gate.yml'
+            opencode_plugin:
+              - 'integrations/opencode-plugin/**'
+              - 'integrations/agent-plugin-core/typescript/**'
+              - '.github/workflows/opencode-plugin-checks.yml'
+              - '.github/workflows/ci-gate.yml'
+            pi_agent_plugin:
+              - 'integrations/pi-agent-plugin/**'
+              - 'integrations/agent-plugin-core/typescript/**'
+              - '.github/workflows/pi-agent-plugin-checks.yml'
+              - '.github/workflows/ci-gate.yml'
+            deepseek_plugin:
+              - 'integrations/deepseek-plugin/**'
+              - 'integrations/agent-plugin-core/typescript/**'
+              - '.github/workflows/deepseek-plugin-checks.yml'
+              - '.github/workflows/ci-gate.yml'
+            n8n_nodes_mem0:
+              - 'integrations/n8n-nodes-mem0/**'
+              - '.github/workflows/n8n-nodes-mem0-checks.yml'
+            zapier_mem0:
+              - 'integrations/zapier-mem0/**'
+              - '.github/workflows/zapier-mem0-checks.yml'
+              - '.github/workflows/ci-gate.yml'
+            mem0_strands:
+              - 'integrations/mem0-strands/**'
+              - '.github/workflows/mem0-strands-checks.yml'
+              - '.github/workflows/ci-gate.yml'
+            docs_llms_txt:
+              - 'docs/**/*.mdx'
+              - 'docs/llms.txt'
+              - 'scripts/check-llms-txt-coverage.py'
+              - 'scripts/llms-txt-ignore.txt'
+              - '.github/workflows/docs-llms-txt-check.yml'
+              - '.github/workflows/ci-gate.yml'
+            github_scripts:
+              - '.github/scripts/**'
+              - '.github/VOUCHED.td'
+              - '.github/workflows/pr-gate.yml'
+              - '.github/workflows/vouch-check-pr.yml'
+              - '.github/workflows/issue-labeler.yml'
+              - '.github/workflows/ci-gate.yml'
+
+  python-sdk:
+    name: Python SDK
+    needs: changes
+    if: needs.changes.outputs.python_sdk == 'true'
+    uses: ./.github/workflows/ci.yml
+    secrets: inherit
+
+  ts-sdk:
+    name: TypeScript SDK
+    needs: changes
+    if: needs.changes.outputs.ts_sdk == 'true'
+    uses: ./.github/workflows/ts-sdk-ci.yml
+    secrets: inherit
+
+  cli-python:
+    name: Python CLI
+    needs: changes
+    if: needs.changes.outputs.cli_python == 'true'
+    uses: ./.github/workflows/cli-python-ci.yml
+    secrets: inherit
+
+  cli-node:
+    name: Node CLI
+    needs: changes
+    if: needs.changes.outputs.cli_node == 'true'
+    uses: ./.github/workflows/cli-node-ci.yml
+    secrets: inherit
+
+  openclaw:
+    name: OpenClaw
+    needs: changes
+    if: needs.changes.outputs.openclaw == 'true'
+    uses: ./.github/workflows/openclaw-checks.yml
+    secrets: inherit
+
+  agent-plugins-python:
+    name: Agent Plugins Python
+    needs: changes
+    if: needs.changes.outputs.agent_plugins_python == 'true'
+    uses: ./.github/workflows/agent-plugins-python-checks.yml
+
+  agent-plugins-typescript:
+    name: Agent Plugins TypeScript
+    needs: changes
+    if: needs.changes.outputs.agent_plugins_typescript == 'true'
+    uses: ./.github/workflows/agent-plugins-typescript-checks.yml
+    secrets: inherit
+
+  opencode-plugin:
+    name: OpenCode Plugin
+    needs: changes
+    if: needs.changes.outputs.opencode_plugin == 'true'
+    uses: ./.github/workflows/opencode-plugin-checks.yml
+    secrets: inherit
+
+  pi-agent-plugin:
+    name: Pi Agent Plugin
+    needs: changes
+    if: needs.changes.outputs.pi_agent_plugin == 'true'
+    uses: ./.github/workflows/pi-agent-plugin-checks.yml
+    secrets: inherit
+
+  deepseek-plugin:
+    name: DeepSeek Harness Plugin
+    needs: changes
+    if: needs.changes.outputs.deepseek_plugin == 'true'
+    uses: ./.github/workflows/deepseek-plugin-checks.yml
+    secrets: inherit
+
+  n8n-nodes-mem0:
+    name: n8n Node
+    needs: changes
+    if: needs.changes.outputs.n8n_nodes_mem0 == 'true'
+    uses: ./.github/workflows/n8n-nodes-mem0-checks.yml
+  zapier-mem0:
+    name: Zapier App
+    needs: changes
+    if: needs.changes.outputs.zapier_mem0 == 'true'
+    uses: ./.github/workflows/zapier-mem0-checks.yml
+    secrets: inherit
+
+  mem0-strands:
+    name: mem0-strands
+    needs: changes
+    if: needs.changes.outputs.mem0_strands == 'true'
+    uses: ./.github/workflows/mem0-strands-checks.yml
+    secrets: inherit
+
+  docs-llms-txt:
+    name: docs llms.txt
+    needs: changes
+    if: needs.changes.outputs.docs_llms_txt == 'true'
+    uses: ./.github/workflows/docs-llms-txt-check.yml
+    secrets: inherit
+
+  github-scripts:
+    name: GitHub Scripts
+    needs: changes
+    if: needs.changes.outputs.github_scripts == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Run .github/scripts tests
+        run: |
+          for test in .github/scripts/*.test.js; do
+            echo "::group::$test"
+            node "$test"
+            echo "::endgroup::"
+          done
+
+  gate:
+    name: CI Gate
+    needs:
+      - changes
+      - python-sdk
+      - ts-sdk
+      - cli-python
+      - cli-node
+      - openclaw
+      - agent-plugins-python
+      - agent-plugins-typescript
+      - opencode-plugin
+      - pi-agent-plugin
+      - deepseek-plugin
+      - n8n-nodes-mem0
+      - zapier-mem0
+      - mem0-strands
+      - docs-llms-txt
+      - github-scripts
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Evaluate pipeline results
+        env:
+          NEEDS: ${{ toJSON(needs) }}
+        run: |
+          echo "$NEEDS" | jq -r 'to_entries[] | "\(.key): \(.value.result)"'
+          failed=$(echo "$NEEDS" | jq -r '[to_entries[] | select(.value.result == "failure" or .value.result == "cancelled") | .key] | join(", ")')
+          if [ -n "$failed" ]; then
+            echo "::error::Failing pipelines: $failed"
+            exit 1
+          fi
+          echo "All pipelines relevant to this change passed."

.github/workflows/ci.yml

@@ -1,28 +1,58 @@
 name: ci
 
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main runs remain standalone.
 on:
   push:
     branches: [main]
-    paths:
-      - 'mem0/**'
-      - 'tests/**'
-      - 'embedchain/**'
-      - '.github/workflows/**'
-      - 'pyproject.toml'
-  pull_request:
-    paths:
-      - 'mem0/**'
-      - 'tests/**'
-      - 'embedchain/**'
+  workflow_call:
 
 jobs:
+  changelog_check:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Require CHANGELOG entry when Python SDK version changes
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+
+          extract_version() {
+            python3 -c "import sys, re; m = re.search(r'^\s*version\s*=\s*\"([^\"]+)\"', sys.stdin.read(), re.M); print(m.group(1) if m else '')"
+          }
+
+          base_version=$(git show "$BASE_SHA:pyproject.toml" 2>/dev/null | extract_version || echo "")
+          head_version=$(git show "$HEAD_SHA:pyproject.toml" | extract_version)
+
+          echo "Base version: ${base_version:-<unknown>}"
+          echo "Head version: $head_version"
+
+          if [ -z "$base_version" ] || [ "$base_version" = "$head_version" ]; then
+            echo "pyproject.toml version unchanged — no CHANGELOG entry required."
+            exit 0
+          fi
+
+          echo "Detected version bump ${base_version} -> ${head_version}. Checking docs/changelog/sdk.mdx…"
+
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- docs/changelog/sdk.mdx | grep -q .; then
+            echo "Changelog update present in docs/changelog/sdk.mdx ✅"
+          else
+            echo "::error file=pyproject.toml::pyproject.toml version changed from ${base_version} to ${head_version} but docs/changelog/sdk.mdx was not updated in this PR. Add a new <Update> entry under the Python tab for v${head_version}."
+            exit 1
+          fi
+
   check_changes:
     runs-on: ubuntu-latest
     outputs:
       mem0_changed: ${{ steps.filter.outputs.mem0 }}
-      embedchain_changed: ${{ steps.filter.outputs.embedchain }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: dorny/paths-filter@v2
       id: filter
       with:
@@ -30,25 +60,28 @@ jobs:
           mem0:
             - 'mem0/**'
             - 'tests/**'
-            - '.github/workflows/**'
+            - '.github/workflows/ci.yml'
             - 'pyproject.toml'
-          embedchain:
-            - 'embedchain/**'
 
   build_mem0:
     needs: check_changes
-    if: needs.check_changes.outputs.mem0_changed == 'true'
     runs-on: ubuntu-latest
     strategy:
       matrix:
         python-version: ["3.10", "3.11", "3.12"]
     steps:
-      - uses: actions/checkout@v3
+      - name: Skip — no relevant changes
+        if: needs.check_changes.outputs.mem0_changed != 'true'
+        run: echo "No changes in mem0/, tests/, pyproject.toml, or ci.yml — skipping"
+      - uses: actions/checkout@v4
+        if: needs.check_changes.outputs.mem0_changed == 'true'
       - name: Set up Python ${{ matrix.python-version }}
+        if: needs.check_changes.outputs.mem0_changed == 'true'
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
       - name: Clean up disk space
+        if: needs.check_changes.outputs.mem0_changed == 'true'
         run: |
           df -h
           sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc /opt/hostedtoolcache/CodeQL
@@ -56,61 +89,27 @@ jobs:
           sudo docker builder prune -a
           df -h
       - name: Install Hatch
+        if: needs.check_changes.outputs.mem0_changed == 'true'
         run: pip install hatch
       - name: Load cached venv
+        if: needs.check_changes.outputs.mem0_changed == 'true'
         id: cached-hatch-dependencies
         uses: actions/cache@v3
         with:
           path: .venv
           key: venv-mem0-${{ runner.os }}-${{ hashFiles('**/pyproject.toml') }}
       - name: Install GEOS Libraries
+        if: needs.check_changes.outputs.mem0_changed == 'true'
         run: sudo apt-get update && sudo apt-get install -y libgeos-dev
       - name: Install dependencies
+        if: needs.check_changes.outputs.mem0_changed == 'true' && steps.cached-hatch-dependencies.outputs.cache-hit != 'true'
         run: |
           pip install --upgrade pip
           pip install -e ".[test,graph,vector_stores,llms,extras]"
-          pip install ruff
-        if: steps.cached-hatch-dependencies.outputs.cache-hit != 'true'
+          pip install ruff==0.16.0
       - name: Run Linting
+        if: needs.check_changes.outputs.mem0_changed == 'true'
         run: make lint
       - name: Run tests and generate coverage report
+        if: needs.check_changes.outputs.mem0_changed == 'true'
         run: make test
-
-  build_embedchain:
-    needs: check_changes
-    if: needs.check_changes.outputs.embedchain_changed == 'true'
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
-    steps:
-      - uses: actions/checkout@v3
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install Hatch
-        run: pip install hatch
-      - name: Load cached venv
-        id: cached-hatch-dependencies
-        uses: actions/cache@v3
-        with:
-          path: .venv
-          key: venv-embedchain-${{ runner.os }}-${{ hashFiles('**/pyproject.toml') }}
-      - name: Install dependencies
-        run: cd embedchain && make install_all
-        if: steps.cached-hatch-dependencies.outputs.cache-hit != 'true'
-      - name: Run Formatting
-        run: |
-          mkdir -p embedchain/.ruff_cache && chmod -R 777 embedchain/.ruff_cache
-          cd embedchain && hatch run format
-      - name: Lint with ruff
-        run: cd embedchain && make lint
-      - name: Run tests and generate coverage report
-        run: cd embedchain && make coverage
-      - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@v3
-        with:
-          file: coverage.xml
-        env:
-          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/cli-node-cd.yml

@@ -1,13 +1,25 @@
 name: Publish @mem0/cli 📦 to npm
 
+# Dispatched by release.yml (Release Router) when a release tagged
+# cli-node-v* is published. Can also be dispatched manually to re-publish
+# a tag.
 on:
-  release:
-    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. cli-node-v0.2.0)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Publish under the version preid dist-tag instead of latest'
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build-n-publish:
     name: Build and publish @mem0/cli 📦 to npm
-    if: startsWith(github.event.release.tag_name, 'cli-node-v')
+    if: startsWith(inputs.tag, 'cli-node-v')
     runs-on: ubuntu-latest
     permissions:
       id-token: write
@@ -16,6 +28,8 @@ jobs:
         working-directory: cli/node
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
@@ -38,7 +52,7 @@ jobs:
 
       - name: Publish to npm
         run: |
-          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+          if [ "${{ inputs.prerelease }}" = "true" ]; then
             PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
             npx npm@latest publish --provenance --access public --tag "$PREID"
           else

.github/workflows/cli-node-ci.yml

@@ -1,5 +1,7 @@
 name: CLI Node CI
 
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
 on:
   workflow_dispatch:
   push:
@@ -7,10 +9,7 @@ on:
     paths:
       - 'cli/node/**'
       - '.github/workflows/cli-node-ci.yml'
-  pull_request:
-    paths:
-      - 'cli/node/**'
-      - '.github/workflows/cli-node-ci.yml'
+  workflow_call:
 
 jobs:
   lint:

.github/workflows/cli-python-cd.yml

@@ -1,13 +1,24 @@
 name: Publish mem0-cli 🐍 distributions 📦 to PyPI
 
+# Dispatched by release.yml (Release Router) when a release tagged cli-v* is
+# published. Can also be dispatched manually to re-publish a tag.
 on:
-  release:
-    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. cli-v0.2.0)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Unused for PyPI (pre-releases are expressed in the version itself); accepted for router uniformity'
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build-n-publish:
     name: Build and publish mem0-cli 📦 to PyPI
-    if: startsWith(github.event.release.tag_name, 'cli-v')
+    if: startsWith(inputs.tag, 'cli-v')
     runs-on: ubuntu-latest
     permissions:
       id-token: write
@@ -16,6 +27,8 @@ jobs:
         working-directory: cli/python
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
 
       - name: Set up Python
         uses: actions/setup-python@v5

.github/workflows/cli-python-ci.yml

@@ -1,5 +1,7 @@
 name: CLI Python CI
 
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
 on:
   workflow_dispatch:
   push:
@@ -7,10 +9,7 @@ on:
     paths:
       - 'cli/python/**'
       - '.github/workflows/cli-python-ci.yml'
-  pull_request:
-    paths:
-      - 'cli/python/**'
-      - '.github/workflows/cli-python-ci.yml'
+  workflow_call:
 
 jobs:
   lint:

.github/workflows/deepseek-plugin-cd.yml

@@ -0,0 +1,60 @@
+name: Publish @mem0/deepseek-plugin 📦 to npm
+
+# Dispatched by release.yml (Release Router) when a release tagged
+# deepseek-plugin-v* is published. Can also be dispatched manually to re-publish
+# a tag.
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. deepseek-plugin-v0.1.1)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Publish under the version preid dist-tag instead of latest'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  build-n-publish:
+    name: Build and publish @mem0/deepseek-plugin 📦 to npm
+    if: startsWith(inputs.tag, 'deepseek-plugin-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: integrations/deepseek-plugin
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+          cache-dependency-path: integrations/deepseek-plugin/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Publish to npm
+        run: |
+          if [ "${{ inputs.prerelease }}" = "true" ]; then
+            PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
+            npx npm@latest publish --provenance --access public --tag "$PREID"
+          else
+            npx npm@latest publish --provenance --access public
+          fi

.github/workflows/deepseek-plugin-checks.yml

@@ -0,0 +1,89 @@
+name: deepseek-plugin checks
+
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'integrations/deepseek-plugin/**'
+      - 'integrations/agent-plugin-core/typescript/**'
+      - '.github/workflows/deepseek-plugin-checks.yml'
+  workflow_call:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          cache-dependency-path: integrations/deepseek-plugin/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd integrations/deepseek-plugin && pnpm install --frozen-lockfile
+
+      - name: Type check
+        run: cd integrations/deepseek-plugin && pnpm exec tsc --noEmit
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'pnpm'
+          cache-dependency-path: integrations/deepseek-plugin/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd integrations/deepseek-plugin && pnpm install --frozen-lockfile
+
+      - name: Run tests
+        run: cd integrations/deepseek-plugin && pnpm exec vitest run
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          cache-dependency-path: integrations/deepseek-plugin/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd integrations/deepseek-plugin && pnpm install --frozen-lockfile
+
+      - name: Build
+        run: cd integrations/deepseek-plugin && pnpm build
+
+      - name: Verify package artifact
+        run: python3 integrations/agent-plugin-core/conformance/artifacts.py deepseek

.github/workflows/docs-llms-txt-check.yml

@@ -0,0 +1,42 @@
+name: docs - llms.txt check
+
+# Blocks PRs that introduce new .mdx pages without a matching entry in
+# docs/llms.txt, or that link to pages that no longer exist. Contributors
+# must update docs/llms.txt in the same PR. Run locally with:
+#   python scripts/check-llms-txt-coverage.py           # read-only
+#   python scripts/check-llms-txt-coverage.py --write   # scaffold placeholders
+
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# manual runs remain standalone.
+on:
+  workflow_call:
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  check-llms-txt:
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 2
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify docs/llms.txt coverage
+        run: |
+          if ! python3 scripts/check-llms-txt-coverage.py; then
+            echo ""
+            echo "::error title=llms.txt out of sync::docs/llms.txt does not match docs/**/*.mdx."
+            echo ""
+            echo "To fix:"
+            echo "  1. Run locally:  python scripts/check-llms-txt-coverage.py --write"
+            echo "     This appends placeholder entries under '## Unclassified - needs triage'."
+            echo "  2. For each placeholder:"
+            echo "       - replace [TODO: Platform|OSS|Both] with the correct scope tag"
+            echo "       - rewrite the description as 'Use when ...'"
+            echo "       - move the entry into the appropriate section"
+            echo "       - delete the '## Unclassified - needs triage' heading once empty"
+            echo "  3. Resolve any stale URLs listed above by updating or removing the link."
+            echo "  4. Commit the updated docs/llms.txt to this PR."
+            exit 1
+          fi

.github/workflows/issue-labeler.yml

@@ -12,28 +12,56 @@ jobs:
   label:
     runs-on: ubuntu-latest
     steps:
+      - uses: actions/checkout@v4
+
       - uses: stefanbuck/github-issue-parser@v3
         id: issue-parser
+        continue-on-error: true
         with:
           template-path: .github/ISSUE_TEMPLATE/bug_report.yml
 
       - uses: redhat-plumbers-in-action/advanced-issue-labeler@v3
+        continue-on-error: true
         with:
           issue-form: ${{ steps.issue-parser.outputs.jsonString }}
-          section: component
           token: ${{ secrets.GITHUB_TOKEN }}
           config-path: .github/advanced-issue-labeler.yml
 
-      - uses: stefanbuck/github-issue-parser@v3
-        id: feature-parser
-        if: contains(github.event.issue.labels.*.name, 'enhancement')
+      - name: Infer component from text when the form was not used
+        uses: actions/github-script@v7
         with:
-          template-path: .github/ISSUE_TEMPLATE/feature_request.yml
+          script: |
+            const {
+              componentLabels,
+              inferComponentLabels,
+              loadKeywords,
+            } = require(`${process.env.GITHUB_WORKSPACE}/.github/scripts/infer-component-labels.js`);
 
-      - uses: redhat-plumbers-in-action/advanced-issue-labeler@v3
-        if: contains(github.event.issue.labels.*.name, 'enhancement')
-        with:
-          issue-form: ${{ steps.feature-parser.outputs.jsonString }}
-          section: component
-          token: ${{ secrets.GITHUB_TOKEN }}
-          config-path: .github/advanced-issue-labeler.yml
+            const { data: issue } = await github.rest.issues.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const keywords = loadKeywords(`${process.env.GITHUB_WORKSPACE}/.github/component-keywords.json`);
+            const known = componentLabels(keywords);
+            const existing = issue.labels.map((label) => label.name || label);
+            if (existing.some((name) => known.includes(name))) {
+              core.info(`Component label already present: ${existing.join(', ')}`);
+              return;
+            }
+
+            const labels = inferComponentLabels(`${issue.title}\n\n${issue.body || ''}`, keywords);
+
+            if (labels.length === 0) {
+              core.info('No component could be inferred from the issue text');
+              return;
+            }
+
+            core.info(`Inferred: ${labels.join(', ')}`);
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              labels,
+            });

.github/workflows/mem0-strands-cd.yml

@@ -0,0 +1,50 @@
+name: Publish mem0-strands 🐍 distribution 📦 to PyPI
+
+# Dispatched by release.yml (Release Router) when a release tagged
+# mem0-strands-v* is published. Can also be dispatched manually to re-publish
+# a tag. Publishing uses PyPI Trusted Publishing (OIDC), so no API token is
+# stored; the `mem0-strands` PyPI project must have a trusted publisher
+# configured for mem0ai/mem0 + this workflow.
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. mem0-strands-v0.1.0)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Unused for PyPI (pre-releases are expressed in the version itself); accepted for router uniformity'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  build-n-publish:
+    name: Build and publish mem0-strands 📦 to PyPI
+    if: startsWith(inputs.tag, 'mem0-strands-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: integrations/mem0-strands/python
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Hatch
+        run: pip install hatch
+
+      - name: Build a binary wheel and a source tarball
+        run: hatch build --clean
+
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: integrations/mem0-strands/python/dist/

.github/workflows/mem0-strands-checks.yml

@@ -0,0 +1,82 @@
+name: mem0-strands CI
+
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'integrations/mem0-strands/**'
+      - '.github/workflows/mem0-strands-checks.yml'
+  workflow_call:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dev dependencies
+        working-directory: integrations/mem0-strands/python
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        working-directory: integrations/mem0-strands/python
+        run: ruff check .
+
+      - name: Check formatting
+        working-directory: integrations/mem0-strands/python
+        run: ruff format --check .
+
+      - name: Type-check with mypy
+        working-directory: integrations/mem0-strands/python
+        run: mypy src
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dev dependencies
+        working-directory: integrations/mem0-strands/python
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        working-directory: integrations/mem0-strands/python
+        run: pytest
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install Hatch
+        run: pip install hatch
+
+      - name: Build
+        working-directory: integrations/mem0-strands/python
+        run: hatch build --clean
+
+      - name: Verify dist output
+        run: |
+          ls integrations/mem0-strands/python/dist/*.whl || (echo "Wheel file missing" && exit 1)
+          ls integrations/mem0-strands/python/dist/*.tar.gz || (echo "Source dist missing" && exit 1)

.github/workflows/n8n-nodes-mem0-cd.yml

@@ -0,0 +1,60 @@
+name: Publish n8n-nodes-mem0 📦 to npm
+
+# Dispatched by release.yml (Release Router) when a release tagged
+# n8n-nodes-mem0-v* is published. Can also be dispatched manually to
+# re-publish a tag.
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. n8n-nodes-mem0-v0.1.0)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Publish under the version preid dist-tag instead of latest'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  build-n-publish:
+    name: Build and publish n8n-nodes-mem0 📦 to npm
+    if: startsWith(inputs.tag, 'n8n-nodes-mem0-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: integrations/n8n-nodes-mem0
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+          cache-dependency-path: integrations/n8n-nodes-mem0/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Publish to npm
+        run: |
+          if [ "${{ inputs.prerelease }}" = "true" ]; then
+            PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
+            npx npm@latest publish --provenance --access public --tag "$PREID"
+          else
+            npx npm@latest publish --provenance --access public
+          fi

.github/workflows/n8n-nodes-mem0-checks.yml

@@ -0,0 +1,88 @@
+name: n8n-nodes-mem0 checks
+
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'integrations/n8n-nodes-mem0/**'
+      - '.github/workflows/n8n-nodes-mem0-checks.yml'
+  workflow_call:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          cache-dependency-path: integrations/n8n-nodes-mem0/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd integrations/n8n-nodes-mem0 && pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Lint
+        run: cd integrations/n8n-nodes-mem0 && pnpm run lint
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          cache-dependency-path: integrations/n8n-nodes-mem0/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd integrations/n8n-nodes-mem0 && pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Run tests
+        run: cd integrations/n8n-nodes-mem0 && pnpm test
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          cache-dependency-path: integrations/n8n-nodes-mem0/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd integrations/n8n-nodes-mem0 && pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Build
+        run: cd integrations/n8n-nodes-mem0 && pnpm run build
+
+      - name: Verify dist output exists
+        run: |
+          test -f integrations/n8n-nodes-mem0/dist/nodes/Mem0/Mem0.node.js || (echo "Build output missing: dist/nodes/Mem0/Mem0.node.js" && exit 1)
+          test -f integrations/n8n-nodes-mem0/dist/credentials/Mem0Api.credentials.js || (echo "Build output missing: dist/credentials/Mem0Api.credentials.js" && exit 1)
+          test -f integrations/n8n-nodes-mem0/dist/nodes/Mem0/mem0.svg || (echo "Build output missing: dist/nodes/Mem0/mem0.svg" && exit 1)

.github/workflows/openclaw-cd.yml

@@ -1,21 +1,35 @@
 name: Publish @mem0/openclaw-mem0 📦 to npm
 
+# Dispatched by release.yml (Release Router) when a release tagged
+# openclaw-v* is published. Can also be dispatched manually to re-publish
+# a tag.
 on:
-  release:
-    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. openclaw-v0.5.0)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Publish under the version preid dist-tag instead of latest'
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build-n-publish:
     name: Build and publish @mem0/openclaw-mem0 📦 to npm
-    if: startsWith(github.event.release.tag_name, 'openclaw-v')
+    if: startsWith(inputs.tag, 'openclaw-v')
     runs-on: ubuntu-latest
     permissions:
       id-token: write
     defaults:
       run:
-        working-directory: openclaw
+        working-directory: integrations/openclaw
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
@@ -28,7 +42,7 @@ jobs:
           node-version: '22'
           registry-url: 'https://registry.npmjs.org'
           cache: 'pnpm'
-          cache-dependency-path: openclaw/pnpm-lock.yaml
+          cache-dependency-path: integrations/openclaw/pnpm-lock.yaml
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -38,7 +52,7 @@ jobs:
 
       - name: Publish to npm
         run: |
-          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+          if [ "${{ inputs.prerelease }}" = "true" ]; then
             PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
             npx npm@latest publish --provenance --access public --tag "$PREID"
           else

.github/workflows/openclaw-checks.yml

@@ -1,16 +1,16 @@
 name: openclaw checks
 
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
 on:
   workflow_dispatch:
   push:
     branches: [main]
     paths:
-      - 'openclaw/**'
-      - '.github/workflows/openclaw-checks.yml'
-  pull_request:
-    paths:
-      - 'openclaw/**'
+      - 'integrations/openclaw/**'
+      - 'integrations/agent-plugin-core/typescript/**'
       - '.github/workflows/openclaw-checks.yml'
+  workflow_call:
 
 jobs:
   lint:
@@ -28,13 +28,13 @@ jobs:
         with:
           node-version: 20
           cache: 'pnpm'
-          cache-dependency-path: openclaw/pnpm-lock.yaml
+          cache-dependency-path: integrations/openclaw/pnpm-lock.yaml
 
       - name: Install dependencies
-        run: cd openclaw && pnpm install --frozen-lockfile
+        run: cd integrations/openclaw && pnpm install --frozen-lockfile
 
       - name: Type check
-        run: cd openclaw && pnpm exec tsc --noEmit
+        run: cd integrations/openclaw && pnpm exec tsc --noEmit
 
   test:
     runs-on: ubuntu-latest
@@ -54,20 +54,20 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
           cache: 'pnpm'
-          cache-dependency-path: openclaw/pnpm-lock.yaml
+          cache-dependency-path: integrations/openclaw/pnpm-lock.yaml
 
       - name: Install dependencies
-        run: cd openclaw && pnpm install --frozen-lockfile
+        run: cd integrations/openclaw && pnpm install --frozen-lockfile
 
       - name: Run tests with coverage
-        run: cd openclaw && pnpm exec vitest run --coverage
+        run: cd integrations/openclaw && pnpm exec vitest run --coverage
 
       - name: Upload coverage to Codecov
         if: matrix.node-version == 20
         uses: codecov/codecov-action@v4
         with:
           flags: openclaw
-          directory: openclaw/coverage
+          directory: integrations/openclaw/coverage
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
@@ -86,15 +86,13 @@ jobs:
         with:
           node-version: 20
           cache: 'pnpm'
-          cache-dependency-path: openclaw/pnpm-lock.yaml
+          cache-dependency-path: integrations/openclaw/pnpm-lock.yaml
 
       - name: Install dependencies
-        run: cd openclaw && pnpm install --frozen-lockfile
+        run: cd integrations/openclaw && pnpm install --frozen-lockfile
 
       - name: Build
-        run: cd openclaw && pnpm build
+        run: cd integrations/openclaw && pnpm build
 
-      - name: Verify dist output exists
-        run: |
-          test -f openclaw/dist/index.js || (echo "Build output missing: dist/index.js" && exit 1)
-          test -f openclaw/dist/index.d.ts || (echo "Build output missing: dist/index.d.ts" && exit 1)
+      - name: Verify package artifact
+        run: python3 integrations/agent-plugin-core/conformance/artifacts.py openclaw

.github/workflows/opencode-plugin-cd.yml

@@ -0,0 +1,58 @@
+name: Publish @mem0/opencode-plugin 📦 to npm
+
+# Dispatched by release.yml (Release Router) when a release tagged
+# opencode-v* is published. Can also be dispatched manually to re-publish
+# a tag.
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. opencode-v0.2.0)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Publish under the version preid dist-tag instead of latest'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  build-n-publish:
+    name: Build and publish @mem0/opencode-plugin 📦 to npm
+    if: startsWith(inputs.tag, 'opencode-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: integrations/opencode-plugin
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
+
+      - name: Install Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+      - name: Publish to npm
+        run: |
+          if [ "${{ inputs.prerelease }}" = "true" ]; then
+            PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
+            npx npm@latest publish --provenance --access public --tag "$PREID"
+          else
+            npx npm@latest publish --provenance --access public
+          fi

.github/workflows/opencode-plugin-checks.yml

@@ -0,0 +1,43 @@
+name: opencode-plugin checks
+
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'integrations/opencode-plugin/**'
+      - 'integrations/agent-plugin-core/typescript/**'
+      - '.github/workflows/opencode-plugin-checks.yml'
+  workflow_call:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: integrations/opencode-plugin
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Type check
+        run: bun run type-check
+
+      - name: Test
+        run: bun test
+
+      - name: Build
+        run: bun run build
+
+      - name: Verify package artifact
+        working-directory: .
+        run: python3 integrations/agent-plugin-core/conformance/artifacts.py opencode

.github/workflows/pi-agent-plugin-cd.yml

@@ -0,0 +1,60 @@
+name: Publish @mem0/pi-agent-plugin 📦 to npm
+
+# Dispatched by release.yml (Release Router) when a release tagged
+# pi-agent-v* is published. Can also be dispatched manually to re-publish
+# a tag.
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. pi-agent-v0.1.1)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Publish under the version preid dist-tag instead of latest'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  build-n-publish:
+    name: Build and publish @mem0/pi-agent-plugin 📦 to npm
+    if: startsWith(inputs.tag, 'pi-agent-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: integrations/pi-agent-plugin
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+          cache-dependency-path: integrations/pi-agent-plugin/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Publish to npm
+        run: |
+          if [ "${{ inputs.prerelease }}" = "true" ]; then
+            PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
+            npx npm@latest publish --provenance --access public --tag "$PREID"
+          else
+            npx npm@latest publish --provenance --access public
+          fi

.github/workflows/pi-agent-plugin-checks.yml

@@ -0,0 +1,89 @@
+name: pi-agent-plugin checks
+
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'integrations/pi-agent-plugin/**'
+      - 'integrations/agent-plugin-core/typescript/**'
+      - '.github/workflows/pi-agent-plugin-checks.yml'
+  workflow_call:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          cache-dependency-path: integrations/pi-agent-plugin/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd integrations/pi-agent-plugin && pnpm install --frozen-lockfile
+
+      - name: Type check
+        run: cd integrations/pi-agent-plugin && pnpm exec tsc --noEmit
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'pnpm'
+          cache-dependency-path: integrations/pi-agent-plugin/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd integrations/pi-agent-plugin && pnpm install --frozen-lockfile
+
+      - name: Run tests
+        run: cd integrations/pi-agent-plugin && pnpm exec vitest run
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          cache-dependency-path: integrations/pi-agent-plugin/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd integrations/pi-agent-plugin && pnpm install --frozen-lockfile
+
+      - name: Build
+        run: cd integrations/pi-agent-plugin && pnpm build
+
+      - name: Verify package artifact
+        run: python3 integrations/agent-plugin-core/conformance/artifacts.py pi-agent

.github/workflows/pr-gate.yml

@@ -0,0 +1,214 @@
+name: PR Gate
+
+on:
+  pull_request_target:
+    types: [opened, reopened, ready_for_review, edited]
+  issues:
+    types: [labeled]
+
+concurrency:
+  group: pr-gate-${{ github.event_name }}-${{ github.event.action }}-${{ github.event.pull_request.number || github.event.issue.number }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request_target' }}
+
+env:
+  GATE_EFFECTIVE_FROM: '2026-08-12T00:00:00Z'
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: read
+
+jobs:
+  gate:
+    if: >-
+      github.event_name == 'pull_request_target' &&
+      github.event.action != 'edited' &&
+      github.event.pull_request.draft == false &&
+      github.event.pull_request.user.type != 'Bot' &&
+      github.event.pull_request.head.repo.full_name != github.repository &&
+      !contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.pull_request.author_association)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const { owner, repo } = context.repo;
+
+            const effectiveFrom = process.env.GATE_EFFECTIVE_FROM;
+            if (effectiveFrom && Date.parse(pr.created_at) < Date.parse(effectiveFrom)) {
+              core.info(`Opened ${pr.created_at}, before the gate took effect ${effectiveFrom}. Skipped.`);
+              return;
+            }
+
+            const { data: current } = await github.rest.pulls.get({
+              owner, repo, pull_number: pr.number,
+            });
+            if (current.state !== 'open') {
+              core.info(`#${pr.number} is already ${current.state}. Skipped.`);
+              return;
+            }
+
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              owner, repo, pull_number: pr.number, per_page: 100,
+            });
+            const rootDocs = new Set(['README.md', 'CONTRIBUTING.md', 'CODE_OF_CONDUCT.md', 'SECURITY.md']);
+            const isDocs = (filename) => filename.startsWith('docs/') || rootDocs.has(filename);
+            if (files.length > 0 && files.every((file) => isDocs(file.filename))) {
+              core.info('Docs-only PR, gate skipped');
+              return;
+            }
+
+            const { repository } = await github.graphql(
+              `query ($owner: String!, $repo: String!, $number: Int!) {
+                repository(owner: $owner, name: $repo) {
+                  pullRequest(number: $number) {
+                    closingIssuesReferences(first: 20) {
+                      nodes { number labels(first: 50) { nodes { name } } }
+                    }
+                  }
+                }
+              }`,
+              { owner, repo, number: pr.number },
+            );
+
+            const accepted = repository.pullRequest.closingIssuesReferences.nodes
+              .filter((issue) => issue.labels.nodes.some((label) => label.name === 'accepted'))
+              .map((issue) => issue.number);
+
+            if (accepted.length > 0) {
+              core.info(`Accepted issue linked: #${accepted.join(', #')}`);
+              return;
+            }
+
+            const body = [
+              '<!-- pr-gate -->',
+              'Thanks for taking the time to open this.',
+              '',
+              'We only review pull requests that fix an issue we have already agreed to take on, so this one is closed for now.',
+              '**Closed does not mean rejected.** It means it is not in the queue yet, and reopening takes about a minute.',
+              '',
+              'To get it reviewed:',
+              '',
+              '1. Make sure an issue describes the problem, with the version you are on, a runnable reproduction, and the real output or traceback you saw.',
+              '2. Link it from this pull request description with `Closes #<number>`.',
+              '3. Ask a maintainer to label that issue `accepted`. This pull request reopens by itself when they do.',
+              '',
+              'Issue already labeled `accepted`? Just add `Closes #<number>` to the description. That reopens this too.',
+              '',
+              'Documentation-only changes skip this gate entirely.',
+              '',
+              'See [CONTRIBUTING.md](https://github.com/mem0ai/mem0/blob/main/CONTRIBUTING.md) for the full policy.',
+            ].join('\n');
+
+            await github.rest.issues.createComment({
+              owner, repo, issue_number: pr.number, body,
+            });
+            await github.rest.pulls.update({
+              owner, repo, pull_number: pr.number, state: 'closed',
+            });
+            core.info(`Closed #${pr.number}: no accepted issue linked`);
+
+  reopen:
+    if: >-
+      (github.event_name == 'issues' && github.event.label.name == 'accepted') ||
+      (github.event.action == 'edited' && github.event.pull_request.state == 'closed')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const marker = '<!-- pr-gate -->';
+
+            const denounced = await (async () => {
+              try {
+                const { data } = await github.rest.repos.getContent({
+                  owner, repo, path: '.github/VOUCHED.td',
+                  ref: context.payload.repository.default_branch,
+                });
+                return new Set(Buffer.from(data.content, 'base64').toString('utf8')
+                  .split('\n')
+                  .map((line) => line.trim())
+                  .filter((line) => line.startsWith('-'))
+                  .map((line) => line.slice(1).split(/\s+/)[0].split(':').pop().toLowerCase())
+                  .filter(Boolean));
+              } catch (error) {
+                core.warning(`Could not read VOUCHED.td, treating nobody as denounced: ${error.message}`);
+                return new Set();
+              }
+            })();
+
+            const isReopenable = async (number) => {
+              const { repository } = await github.graphql(
+                `query ($owner: String!, $repo: String!, $number: Int!) {
+                  repository(owner: $owner, name: $repo) {
+                    pullRequest(number: $number) {
+                      state
+                      author { login }
+                      closingIssuesReferences(first: 20) {
+                        nodes { labels(first: 50) { nodes { name } } }
+                      }
+                    }
+                  }
+                }`,
+                { owner, repo, number },
+              );
+              const pullRequest = repository.pullRequest;
+              if (denounced.has(pullRequest.author?.login?.toLowerCase())) {
+                core.info(`#${number} is from a denounced author. Vouch outranks this gate.`);
+                return false;
+              }
+              return pullRequest.state === 'CLOSED' &&
+                pullRequest.closingIssuesReferences.nodes.some((issue) =>
+                  issue.labels.nodes.some((label) => label.name === 'accepted'));
+            };
+
+            let candidates;
+            if (context.eventName === 'issues') {
+              const { repository } = await github.graphql(
+                `query ($owner: String!, $repo: String!, $number: Int!) {
+                  repository(owner: $owner, name: $repo) {
+                    issue(number: $number) {
+                      closedByPullRequestsReferences(first: 20, includeClosedPrs: true) {
+                        nodes { number }
+                      }
+                    }
+                  }
+                }`,
+                { owner, repo, number: context.payload.issue.number },
+              );
+              candidates = repository.issue.closedByPullRequestsReferences.nodes.map((pr) => pr.number);
+            } else {
+              candidates = [context.payload.pull_request.number];
+            }
+
+            for (const number of candidates) {
+              if (!(await isReopenable(number))) {
+                core.info(`#${number} is not a closed pull request linking an accepted issue. Skipped.`);
+                continue;
+              }
+
+              const comments = await github.paginate(github.rest.issues.listComments, {
+                owner, repo, issue_number: number, per_page: 100,
+              });
+              if (!comments.some((comment) => comment.body?.startsWith(marker))) {
+                core.info(`#${number} was not closed by this gate. Left alone.`);
+                continue;
+              }
+
+              try {
+                await github.rest.pulls.update({
+                  owner, repo, pull_number: number, state: 'open',
+                });
+              } catch (error) {
+                core.warning(`Could not reopen #${number}: ${error.message}`);
+                continue;
+              }
+
+              await github.rest.issues.createComment({
+                owner, repo, issue_number: number,
+                body: 'An `accepted` issue is linked now, so this is open again and ready for review.',
+              });
+              core.info(`Reopened #${number}`);
+            }

.github/workflows/pr-labeler.yml

@@ -0,0 +1,64 @@
+name: PR Labeler
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, edited]
+
+concurrency:
+  group: pr-labeler-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: read
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/labeler@v5
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Propagate labels from linked issues
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const allowed = new Set([
+              'sdk-python', 'sdk-typescript', 'vector-store', 'plugin',
+              'rest-api', 'documentation', 'ci', 'cli', 'integrations',
+            ]);
+            const umbrella = { plugin: 'integrations' };
+            const { repository } = await github.graphql(
+              `query ($owner: String!, $repo: String!, $number: Int!) {
+                repository(owner: $owner, name: $repo) {
+                  pullRequest(number: $number) {
+                    closingIssuesReferences(first: 20) {
+                      nodes { labels(first: 50) { nodes { name } } }
+                    }
+                  }
+                }
+              }`,
+              { owner: context.repo.owner, repo: context.repo.repo, number: context.issue.number },
+            );
+
+            const labels = new Set();
+            for (const issue of repository.pullRequest.closingIssuesReferences.nodes) {
+              for (const label of issue.labels.nodes) {
+                if (allowed.has(label.name)) labels.add(label.name);
+              }
+            }
+
+            for (const label of [...labels]) {
+              if (umbrella[label]) labels.add(umbrella[label]);
+            }
+
+            if (labels.size > 0) {
+              await github.rest.issues.addLabels({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                labels: [...labels],
+              });
+            }

.github/workflows/release.yml

@@ -0,0 +1,71 @@
+name: Release Router 🚦
+
+# Single entry point for all release publishing.
+#
+# Package CD workflows no longer listen to release events themselves — this
+# router inspects the release tag and dispatches only the matching pipeline,
+# so each release produces one routed run instead of one real run plus seven
+# skipped ones.
+#
+# Re-publishing a release (e.g. after fixing registry settings) does NOT
+# require deleting and recreating it anymore — manually dispatch the
+# package's CD workflow from the tag instead:
+#
+#   gh workflow run <package>-cd.yml --ref refs/tags/<tag> -f tag=<tag>
+#
+# Note: dispatching runs the workflow file as it exists at the given ref, so
+# this router can only dispatch tags created after the workflow_dispatch
+# conversion landed on main. For older tags, dispatch manually from main.
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  actions: write
+
+jobs:
+  route:
+    name: Route ${{ github.event.release.tag_name }} to its CD pipeline
+    runs-on: ubuntu-latest
+    steps:
+      - name: Match tag prefix to CD workflow
+        id: match
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          # Specific package prefixes first; the bare v* (Python SDK) arm
+          # must stay last so prefixed tags that also start with 'v'
+          # (vercel-ai-v*) can never be routed to the Python pipeline.
+          case "$TAG" in
+            ts-v*)        workflow="ts-sdk-cd.yml" ;;
+            cli-node-v*)  workflow="cli-node-cd.yml" ;;
+            cli-v*)       workflow="cli-python-cd.yml" ;;
+            vercel-ai-v*) workflow="vercel-ai-cd.yml" ;;
+            openclaw-v*)  workflow="openclaw-cd.yml" ;;
+            opencode-v*)  workflow="opencode-plugin-cd.yml" ;;
+            pi-agent-v*)  workflow="pi-agent-plugin-cd.yml" ;;
+            deepseek-plugin-v*)  workflow="deepseek-plugin-cd.yml" ;;
+            n8n-nodes-mem0-v*) workflow="n8n-nodes-mem0-cd.yml" ;;
+            mem0-strands-v*)   workflow="mem0-strands-cd.yml" ;;
+            v*)           workflow="cd.yml" ;;
+            *)
+              echo "::error::Release tag '$TAG' does not match any known package prefix — nothing will be published. See the tag prefix table in AGENTS.md."
+              exit 1
+              ;;
+          esac
+          echo "workflow=$workflow" >> "$GITHUB_OUTPUT"
+          echo ":outbox_tray: Routed \`$TAG\` → \`$workflow\`" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Dispatch ${{ steps.match.outputs.workflow }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          # --ref points at the tag so the dispatched run builds (and signs
+          # provenance for) the exact tagged commit.
+          gh workflow run "${{ steps.match.outputs.workflow }}" \
+            --repo "$GITHUB_REPOSITORY" \
+            --ref "refs/tags/$TAG" \
+            -f tag="$TAG" \
+            -f prerelease="${{ github.event.release.prerelease }}"

.github/workflows/ts-sdk-cd.yml

@@ -1,13 +1,24 @@
 name: Publish mem0ai 📦 to npm
 
+# Dispatched by release.yml (Release Router) when a release tagged ts-v* is
+# published. Can also be dispatched manually to re-publish a tag.
 on:
-  release:
-    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. ts-v2.1.0)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Publish under the version preid dist-tag instead of latest'
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build-n-publish:
     name: Build and publish mem0ai 📦 to npm
-    if: startsWith(github.event.release.tag_name, 'ts-v')
+    if: startsWith(inputs.tag, 'ts-v')
     runs-on: ubuntu-latest
     permissions:
       id-token: write
@@ -16,6 +27,8 @@ jobs:
         working-directory: mem0-ts
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
@@ -38,7 +51,7 @@ jobs:
 
       - name: Publish to npm
         run: |
-          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+          if [ "${{ inputs.prerelease }}" = "true" ]; then
             PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
             npx npm@latest publish --provenance --access public --tag "$PREID"
           else

.github/workflows/ts-sdk-ci.yml

@@ -1,14 +1,14 @@
 name: TypeScript SDK CI
 
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main runs remain standalone.
 on:
   push:
     branches: [main]
     paths:
       - 'mem0-ts/**'
       - '.github/workflows/ts-sdk-ci.yml'
-  pull_request:
-    paths:
-      - 'mem0-ts/**'
+  workflow_call:
 
 jobs:
   check_changes:
@@ -24,6 +24,42 @@ jobs:
             ts_sdk:
               - 'mem0-ts/**'
 
+  changelog_check:
+    needs: check_changes
+    if: github.event_name == 'pull_request' && needs.check_changes.outputs.ts_sdk_changed == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Require CHANGELOG entry when SDK version changes
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+
+          base_version=$(git show "$BASE_SHA:mem0-ts/package.json" 2>/dev/null | jq -r .version || echo "")
+          head_version=$(git show "$HEAD_SHA:mem0-ts/package.json" | jq -r .version)
+
+          echo "Base version: ${base_version:-<unknown>}"
+          echo "Head version: $head_version"
+
+          if [ -z "$base_version" ] || [ "$base_version" = "$head_version" ]; then
+            echo "mem0-ts/package.json version unchanged — no CHANGELOG entry required."
+            exit 0
+          fi
+
+          echo "Detected version bump ${base_version} -> ${head_version}. Checking docs/changelog/sdk.mdx…"
+
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- docs/changelog/sdk.mdx | grep -q .; then
+            echo "Changelog update present in docs/changelog/sdk.mdx ✅"
+          else
+            echo "::error file=mem0-ts/package.json::mem0-ts/package.json version changed from ${base_version} to ${head_version} but docs/changelog/sdk.mdx was not updated in this PR. Add a new <Update> entry under the TypeScript tab for v${head_version}."
+            exit 1
+          fi
+
   build_ts_sdk:
     needs: check_changes
     if: needs.check_changes.outputs.ts_sdk_changed == 'true'

.github/workflows/vercel-ai-cd.yml

@@ -1,21 +1,35 @@
 name: Publish @mem0/vercel-ai-provider 📦 to npm
 
+# Dispatched by release.yml (Release Router) when a release tagged
+# vercel-ai-v* is published. Can also be dispatched manually to re-publish
+# a tag.
 on:
-  release:
-    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to build and publish (e.g. vercel-ai-v2.0.7)'
+        required: true
+        type: string
+      prerelease:
+        description: 'Publish under the version preid dist-tag instead of latest'
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build-n-publish:
     name: Build and publish @mem0/vercel-ai-provider 📦 to npm
-    if: startsWith(github.event.release.tag_name, 'vercel-ai-v')
+    if: startsWith(inputs.tag, 'vercel-ai-v')
     runs-on: ubuntu-latest
     permissions:
       id-token: write
     defaults:
       run:
-        working-directory: vercel-ai-sdk
+        working-directory: integrations/vercel-ai-sdk
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
@@ -28,7 +42,7 @@ jobs:
           node-version: '22'
           registry-url: 'https://registry.npmjs.org'
           cache: 'pnpm'
-          cache-dependency-path: vercel-ai-sdk/pnpm-lock.yaml
+          cache-dependency-path: integrations/vercel-ai-sdk/pnpm-lock.yaml
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -38,7 +52,7 @@ jobs:
 
       - name: Publish to npm
         run: |
-          if [ "${{ github.event.release.prerelease }}" = "true" ]; then
+          if [ "${{ inputs.prerelease }}" = "true" ]; then
             PREID=$(node -p "require('./package.json').version.split('-')[1].split('.')[0]")
             npx npm@latest publish --provenance --access public --tag "$PREID"
           else

.github/workflows/vouch-check-pr.yml

@@ -0,0 +1,59 @@
+name: Vouch - Check PR
+
+on:
+  pull_request_target:
+    types: [opened, reopened]
+
+concurrency:
+  group: vouch-check-pr-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  check:
+    if: >-
+      github.event.pull_request.user.type != 'Bot' &&
+      github.event.pull_request.head.repo.full_name != github.repository &&
+      !contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.pull_request.author_association)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: mitchellh/vouch/action/check-pr@d66fa29a64600490892131ad87597c30c91fcac4 # v1.5.0
+        id: vouch
+        with:
+          pr-number: ${{ github.event.pull_request.number }}
+          require-vouch: false
+          auto-close: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - if: steps.vouch.outputs.status == 'allowed'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const pr = context.payload.pull_request;
+            const marker = '<!-- vouch-check -->';
+
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner, repo, issue_number: pr.number, per_page: 100,
+            });
+            if (comments.some((comment) => comment.body?.startsWith(marker))) {
+              core.info('Vouch comment already posted, skipped.');
+              return;
+            }
+
+            const body = [
+              marker,
+              `Hi @${context.payload.pull_request.user.login}, thanks for opening this pull request.`,
+              '',
+              "This is just a soft check: you are not yet in this repo's vouched contributor list (`.github/VOUCHED.td`). Nothing is blocked and there is nothing you need to do.",
+              '',
+              `A maintainer can vouch for you by commenting \`!vouch @${context.payload.pull_request.user.login}\` on any issue.`,
+            ].join('\n');
+
+            await github.rest.issues.createComment({
+              owner, repo, issue_number: pr.number, body,
+            });

.github/workflows/vouch-manage-by-issue.yml

@@ -0,0 +1,42 @@
+name: Vouch - Manage by Issue
+
+on:
+  issue_comment:
+    types: [created]
+
+concurrency:
+  group: vouch-manage
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  manage:
+    if: contains(github.event.comment.body, '!vouch') || contains(github.event.comment.body, '!denounce') || contains(github.event.comment.body, '!unvouch')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/create-github-app-token@v3
+        id: app-token
+        with:
+          app-id: ${{ secrets.VOUCH_APP_ID }}
+          private-key: ${{ secrets.VOUCH_APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+
+      - uses: mitchellh/vouch/action/manage-by-issue@d66fa29a64600490892131ad87597c30c91fcac4 # v1.5.0
+        with:
+          repo: ${{ github.repository }}
+          issue-id: ${{ github.event.issue.number }}
+          comment-id: ${{ github.event.comment.id }}
+          vouch-keyword: "!vouch"
+          denounce-keyword: "!denounce"
+          unvouch-keyword: "!unvouch"
+          pull-request: "true"
+          merge-immediately: "false"
+        env:
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}

.github/workflows/zapier-mem0-cd.yml

@@ -0,0 +1,42 @@
+name: Deploy zapier-mem0 to Zapier
+
+# Zapier apps deploy to Zapier's own platform (not npm), so this is NOT wired
+# into the npm release router (release.yml). It is manual workflow_dispatch
+# only and requires the ZAPIER_DEPLOY_KEY repo secret.
+#
+#   gh workflow run zapier-mem0-cd.yml --ref main
+on:
+  workflow_dispatch:
+
+jobs:
+  push:
+    name: Push zapier-mem0 to Zapier
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: integrations/zapier-mem0
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'pnpm'
+          cache-dependency-path: integrations/zapier-mem0/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build TypeScript
+        run: pnpm build
+
+      - name: Push to Zapier
+        env:
+          ZAPIER_DEPLOY_KEY: ${{ secrets.ZAPIER_DEPLOY_KEY }}
+        run: npx zapier-platform-cli@19 push

.github/workflows/zapier-mem0-checks.yml

@@ -0,0 +1,47 @@
+name: zapier-mem0 checks
+
+# On PRs this is invoked by ci-gate.yml (the single required check);
+# push-to-main and manual runs remain standalone.
+#
+# CI compiles the TypeScript app, runs `zapier validate` (offline schema + style
+# checks) against the build, plus the offline jest unit suite (test/unit.test.ts —
+# mocked z.request, no network). The end-to-end jest suite is skipped here because
+# it hits the live Mem0 API — it runs locally with MEM0_API_KEY set (see README).
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - 'integrations/zapier-mem0/**'
+      - '.github/workflows/zapier-mem0-checks.yml'
+  workflow_call:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'pnpm'
+          cache-dependency-path: integrations/zapier-mem0/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd integrations/zapier-mem0 && pnpm install --frozen-lockfile
+
+      - name: Build TypeScript
+        run: cd integrations/zapier-mem0 && pnpm build
+
+      - name: Validate Zapier app definition
+        run: cd integrations/zapier-mem0 && npx zapier-platform-cli@19 validate
+
+      - name: Run offline unit tests
+        run: cd integrations/zapier-mem0 && pnpm test:unit

.gitignore

@@ -4,19 +4,27 @@ __pycache__/
 *$py.class
 **/node_modules/
 
+# Self-hosted server local runtime state
+server/history/
+server/.env
+
 # C extensions
 *.so
 
 # Distribution / packaging
 .Python
 build/
+!integrations/agent-plugin-core/build/
+!integrations/agent-plugin-core/build/*.py
+!integrations/agent-plugin-core/build/schemas/
+!integrations/agent-plugin-core/build/schemas/*.json
 develop-eggs/
 dist/
 downloads/
 eggs/
 .eggs/
-lib/
-lib64/
+/lib/
+/lib64/
 parts/
 sdist/
 var/
@@ -166,7 +174,6 @@ cython_debug/
 # Database
 db
 test-db
-!embedchain/embedchain/core/db/
 
 .vscode
 .idea/
@@ -186,3 +193,9 @@ eval/
 qdrant_storage/
 .crossnote
 testing.ipynb
+.weave/
+
+
+# TypeScript incremental build info and local, uncommitted e2e scripts (used by the integrations, e.g. integrations/deepseek-plugin)
+*.tsbuildinfo
+*.local.mjs

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "evaluation"]
+	path = evaluation
+	url = https://github.com/mem0ai/memory-benchmarks
+	branch = main

.kimi-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "mem0-plugins",
+  "version": "1",
+  "plugins": [
+    {
+      "id": "mem0",
+      "displayName": "Mem0",
+      "version": "0.3.3",
+      "description": "Cross-session memory and token savings for coding agents.",
+      "homepage": "https://mem0.ai",
+      "keywords": ["memory", "personalization", "mcp", "semantic-search"],
+      "source": "https://github.com/mem0ai/mem0/tree/main/integrations/kimi-plugin"
+    }
+  ]
+}

AGENTS.md

@@ -1,580 +1,175 @@
 # AGENTS.md
 
-This file provides context for AI coding assistants (Claude Code, Cursor, GitHub Copilot, Codex, etc.) working with the Mem0 repository.
+Context for AI coding assistants (Claude Code, Cursor, Copilot, Codex) working in the Mem0 repository.
 
-## Project Overview
+**Mem0** ("mem-zero") is a memory layer for AI agents: persistent, personalized memory through a hosted platform API and self-hosted open-source SDKs. Apache-2.0.
+[Repository](https://github.com/mem0ai/mem0) · [Documentation](https://docs.mem0.ai)
 
-**Mem0** ("mem-zero") is an intelligent memory layer for AI agents and assistants. It provides persistent, personalized memory via both a hosted platform API and self-hosted open-source SDKs.
+This is a polyglot monorepo and **every package sets its own rules**. Read the `AGENTS.md` nearest the files you are editing before running any command. The linters, formatters, test runners, and line lengths genuinely differ per package, and using the wrong one fails CI or produces a diff full of noise.
 
-- **Repository**: https://github.com/mem0ai/mem0
-- **Documentation**: https://docs.mem0.ai
-- **License**: Apache-2.0
+## Do NOT
 
-## Repository Structure
+- Open a pull request without a signed CLA. It will not be reviewed. See [The CLA is not optional](#the-cla-is-not-optional).
+- Open a pull request that does not link an issue carrying the `accepted` label. A bot closes it within a minute. See [Two gates decide whether your pull request stays open](#two-gates-decide-whether-your-pull-request-stays-open).
+- Modify anything in `.github/workflows/` without explicit maintainer approval. Publishing credentials are pinned to workflow filenames.
+- Commit `.env` files, API keys, or credentials.
+- Skip pre-commit hooks.
+- Use npm or yarn in TypeScript packages. This repo is pnpm-only (Bun in `integrations/opencode-plugin/`).
+- Use `require()` in TypeScript. ES module `import` syntax only.
+- Mix up linter configs. Root Python is ruff at line length **120**, `cli/python/` is ruff at **100**, `cli/node/` is Biome, `mem0-ts/` is Prettier, `integrations/vercel-ai-sdk/` is ESLint.
+- Add Python dependencies to the core `dependencies` list in `pyproject.toml`. Use an optional group.
+- Change a public API without updating `docs/` in the same pull request.
+- Introduce a new framework or abstraction without discussion. Follow the patterns already in the file you are editing.
 
-This is a **polyglot monorepo** containing Python and TypeScript packages, CLIs, servers, plugins, documentation, and evaluation tooling.
+## Where to look
 
-### Key Directories
+| Editing | Read | Toolchain |
+|---------|------|-----------|
+| `mem0/` | [`mem0/AGENTS.md`](mem0/AGENTS.md) | hatch, ruff 120, pytest |
+| `tests/` | [`tests/AGENTS.md`](tests/AGENTS.md) | pytest |
+| `mem0-ts/` | [`mem0-ts/AGENTS.md`](mem0-ts/AGENTS.md) | pnpm, tsup, Prettier, jest |
+| `cli/python/` | [`cli/python/AGENTS.md`](cli/python/AGENTS.md) | ruff **100**, pytest |
+| `cli/node/` | [`cli/node/AGENTS.md`](cli/node/AGENTS.md) | pnpm, tsup, Biome, vitest |
+| `integrations/` | [`integrations/AGENTS.md`](integrations/AGENTS.md) | varies per integration |
+| `server/` | [`server/AGENTS.md`](server/AGENTS.md) | Docker Compose, FastAPI |
+| `docs/` | [`docs/AGENTS.md`](docs/AGENTS.md) | Mintlify |
+| `skills/` | [`skills/AGENTS.md`](skills/AGENTS.md) | markdown, size-budgeted |
+| `.github/` | [`.github/AGENTS.md`](.github/AGENTS.md) | GitHub Actions |
 
-| Directory | Description |
-|-----------|-------------|
-| `mem0/` | Core Python SDK (`mem0ai` on PyPI) — memory, LLMs, embeddings, vector stores, graphs, rerankers |
-| `mem0-ts/` | TypeScript SDK (`mem0ai` on npm) — client + OSS memory |
-| `cli/python/` | Python CLI (`mem0-cli` on PyPI) — Typer-based, entry point `mem0` |
-| `cli/node/` | Node CLI (`@mem0/cli` on npm) — Commander-based, entry point `mem0` |
-| `vercel-ai-sdk/` | `@mem0/vercel-ai-provider` — Vercel AI SDK memory provider |
-| `openclaw/` | `@mem0/openclaw-mem0` — OpenClaw plugin for Claude Code / AI editors |
-| `server/` | FastAPI REST server for self-hosted Mem0 (Docker: FastAPI + PostgreSQL/pgvector + Neo4j) |
-| `openmemory/` | Self-hosted memory platform — `api/` (FastAPI + Alembic + MCP server) and `ui/` (Next.js 15 + React 19) |
-| `mem0-plugin/` | AI editor plugins (Claude Code, Cursor, Codex) — MCP server connection, lifecycle hooks, skills |
-| `skills/` | Claude Code skill definitions — `mem0/`, `mem0-cli/`, `mem0-vercel-ai-sdk/` |
+## Repository map
+
+| Directory | What it is |
+|-----------|------------|
+| `mem0/` | Core Python SDK (`mem0ai` on PyPI): memory, LLMs, embeddings, vector stores, graphs, rerankers |
+| `mem0-ts/` | TypeScript SDK (`mem0ai` on npm): hosted client + OSS memory |
+| `cli/python/` | Python CLI (`mem0-cli` on PyPI), Typer-based, entry point `mem0` |
+| `cli/node/` | Node CLI (`@mem0/cli` on npm), Commander-based, entry point `mem0` |
+| `integrations/` | Agent and editor integrations, one self-contained directory each |
+| `server/` | FastAPI REST server for self-hosted Mem0 (Docker: FastAPI + pgvector + Neo4j) |
+| `skills/` | Claude Code skill definitions, published by raw URL |
 | `docs/` | Documentation site (Mintlify) |
 | `tests/` | Python SDK tests (pytest) |
-| `evaluation/` | Benchmarking framework — LOCOMO evals, experiment runner, score generation |
-| `examples/` | Sample projects — demo apps, Chrome extension, multi-agent patterns |
-| `cookbooks/` | Jupyter notebooks — customer support chatbot, AutoGen integration |
-| `embedchain/` | Legacy Embedchain RAG framework (maintained separately, Poetry-based) |
+| `examples/` | Sample apps, Chrome extension, multi-agent patterns, notebooks |
+| `scripts/` | Repo-wide utilities, e.g. `check-llms-txt-coverage.py` |
+| `evaluation/` | Submodule pinned to [`mem0ai/memory-benchmarks`](https://github.com/mem0ai/memory-benchmarks) |
 | `pr-reviews/` | Pull request review materials |
 
-### Core Package Dependencies
-
 ```
 mem0 (Python SDK)          mem0-ts (TypeScript SDK)
-├── mem0/memory/           ├── src/client/        (MemoryClient — hosted)
-├── mem0/llms/             └── src/oss/           (Memory — self-hosted)
+├── mem0/memory/           ├── src/client/    MemoryClient (hosted)
+├── mem0/llms/             └── src/oss/       Memory (self-hosted)
 ├── mem0/embeddings/           ├── src/llms/
 ├── mem0/vector_stores/        ├── src/embeddings/
 ├── mem0/graphs/               ├── src/vector_stores/
 └── mem0/reranker/             └── src/graphs/
 
-cli/python/ ──▶ mem0ai (optional, for OSS mode)
-cli/node/   ──▶ mem0ai (npm, for API calls)
-vercel-ai-sdk/ ──▶ ai, @ai-sdk/* providers
-openclaw/   ──▶ mem0ai (npm)
+cli/python/                 ──▶ mem0ai (optional, OSS mode)
+cli/node/                   ──▶ mem0ai (npm)
+integrations/vercel-ai-sdk/ ──▶ ai, @ai-sdk/*
+integrations/openclaw/      ──▶ mem0ai (npm)
 ```
 
-## Development Setup
-
-### Requirements
-
-- **Python**: 3.9+ (3.10+ for CLI)
-- **Node.js**: v18+ (v20 or v22 recommended)
-- **pnpm**: v10+ (`npm install -g pnpm@10`) — used for all TypeScript packages
-- **Hatch**: Python build/environment tool (`pip install hatch`)
-- **Docker**: Required for `server/` and `openmemory/` development
-
-### Initial Setup
+## Setup
 
 ```bash
-# Python SDK
-hatch shell dev_py_3_11           # creates environment with all deps
-pre-commit install                # install git hooks
+hatch shell dev_py_3_11   # Python: creates the env with all deps
+pre-commit install        # ruff + isort on commit
 
-# TypeScript packages
-cd mem0-ts && pnpm install        # TS SDK
-cd cli/node && pnpm install       # Node CLI
-cd vercel-ai-sdk && pnpm install  # Vercel AI provider
-cd openclaw && pnpm install       # OpenClaw plugin
+cd <ts-package> && pnpm install
 ```
 
-## Build, Lint, and Test Commands
+Requirements: Python 3.9+ (3.10+ for the CLI), Node 18+ (20 or 22 preferred), pnpm 10+, hatch, Docker for `server/`.
 
-### Python SDK (`mem0/`)
+## Conventions everywhere
+
+- **Naming:** `snake_case.py`, `test_<module>.py`, `snake_case.ts`, `<module>.test.ts`, `kebab-case` for config and manifest files.
+- **Python:** Pydantic v2 for models and config. Providers inherit a `base.py` abstract class; config lives in `configs.py`.
+- **TypeScript:** strict mode, tsup builds, ES module imports.
+- **Commits:** [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`).
+- **Versions:** bump in `pyproject.toml` or `package.json`. Releases are cut by tag prefix; see [`.github/AGENTS.md`](.github/AGENTS.md).
+
+## Benchmarking
+
+Benchmarks (LOCOMO, LongMemEval, BEAM) live in [`mem0ai/memory-benchmarks`](https://github.com/mem0ai/memory-benchmarks). The in-repo `evaluation/` path is a submodule pinned to that repo's `main`:
 
 ```bash
-# Environment setup (uses Hatch)
-hatch shell dev_py_3_11           # or dev_py_3_9, dev_py_3_10, dev_py_3_12
-
-# Linting and formatting
-make lint                          # ruff check
-make format                        # ruff format
-make sort                          # isort mem0/
-
-# Tests
-make test                          # pytest tests/
-make test-py-3.9                   # test specific Python version (3.9–3.12)
-
-# Build and publish
-make build                         # hatch build
-make publish                       # hatch publish
+git submodule update --init evaluation
 ```
 
-- **Python:** 3.9, 3.10, 3.11, 3.12
-- **Linter/formatter:** Ruff (line length **120**)
-- **Import sorting:** isort (`profile = "black"`)
-- **Test framework:** pytest (with pytest-mock, pytest-asyncio)
-- **Pre-commit hooks:** ruff + isort — run `pre-commit install` before committing
+## What to ship with a change
 
-### TypeScript SDK (`mem0-ts/`)
+Guidelines, not rules. Trivial fixes need less; anything user-facing needs more.
 
-```bash
-cd mem0-ts
-pnpm install
-pnpm run build                     # tsup
-pnpm run test                      # jest (all tests)
-pnpm run test:unit                 # jest --coverage (unit tests only)
-pnpm run test:integration          # jest (integration tests, needs MEM0_API_KEY)
-pnpm run test:ci                   # jest --coverage --ci (CI mode)
-pnpm run test:watch                # jest watch mode
-```
+| Change | Expect |
+|--------|--------|
+| **Bug fix** | A regression test that fails without the fix, written first. The fix. The relevant suite passing. The package's linter run. |
+| **New feature** | Implementation following existing patterns, test coverage, `docs/` updates for public APIs, an example if the behavior is user-facing, and an `llms.txt` entry for any new `.mdx` page. |
+| **New provider** | See [Adding a provider](mem0/AGENTS.md#adding-a-provider). |
+| **New integration** | See [Adding an integration](integrations/AGENTS.md#adding-an-integration). |
+| **Refactor** | Tests for changed behavior, existing tests still green. No docs needed for internal-only changes. |
 
-- **Node:** 20, 22 (CI-tested)
-- **Build:** tsup (CJS + ESM)
-- **Test:** jest
-- **Formatter:** prettier
+Fix bugs at the root, not at the symptom. If a guard belongs in a shared function, put it there rather than in each caller.
 
-### Python CLI (`cli/python/`)
+## Contributing
 
-```bash
-cd cli/python
-pip install -e ".[dev]"            # dev install with ruff + pytest
-ruff check .                       # lint
-ruff format .                      # format
-pytest                             # test
-hatch build                        # build
-```
+Full guide: [`CONTRIBUTING.md`](CONTRIBUTING.md). Conduct: [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).
 
-- **Python:** 3.10+ (not 3.9)
-- **Linter/formatter:** Ruff (line length **100** — different from root SDK)
-- **Ruff rules:** E, F, I, W, UP, B, SIM, RUF (ignores E501, B008 for Typer patterns, SIM108)
-- **Framework:** Typer + Rich + httpx
-- **Entry point:** `mem0 = "mem0_cli.app:main"`
-- **Source layout:** `src/mem0_cli/`
-- **Optional dependency:** `mem0ai` (for OSS mode, via `[oss]` extra)
+1. Open an issue **first** and wait for a maintainer to apply the `accepted` label. Every PR must link it with `Closes #<number>`. PRs without an accepted linked issue are closed automatically by the [PR Gate](.github/workflows/pr-gate.yml), with a reopen path. Documentation-only changes are exempt.
+2. Fork, then branch from `main` (`feature/...`, `fix/...`).
+3. Make the change: code, tests, docs, examples.
+4. Run lint and tests for **every** package you touched.
+5. Commit with Conventional Commits.
+6. Open the PR against `main` and fill in [the template](.github/PULL_REQUEST_TEMPLATE.md). Do not paraphrase it; GitHub prefills it.
+7. **Sign the CLA.**
 
-### Node CLI (`cli/node/`)
+### Two gates decide whether your pull request stays open
 
-```bash
-cd cli/node
-pnpm install
-pnpm run build                     # tsup
-pnpm run lint                      # biome check src/
-pnpm run lint:fix                  # biome check --write src/
-pnpm run typecheck                 # tsc --noEmit
-pnpm run test                      # vitest run
-pnpm run test:watch                # vitest (watch mode)
-pnpm run dev                       # tsx src/index.ts (development)
-```
+Two workflows run on every pull request from a fork. They judge different things and neither covers for the other, so a pull request has to get past both.
 
-- **Node:** 18+ required
-- **Build:** tsup (ESM)
-- **Linter:** Biome (not ESLint, not Ruff)
-- **Test:** vitest (not jest)
-- **Framework:** Commander + Chalk + ora + cli-table3
+**The [PR Gate](.github/workflows/pr-gate.yml) judges the change.** It closes any pull request that does not link an issue carrying the `accepted` label. Closed is a queue decision, not a verdict: when a maintainer applies the label the pull request reopens by itself. Drafts, documentation-only changes, and branches pushed to this repository rather than a fork are all exempt.
 
-### Vercel AI SDK Provider (`vercel-ai-sdk/`)
+**The [vouch check](.github/workflows/vouch-check-pr.yml) judges the account.** It reads [`.github/VOUCHED.td`](.github/VOUCHED.td), which has three possible answers about any given person:
 
-```bash
-cd vercel-ai-sdk
-pnpm install
-pnpm run build                     # tsup
-pnpm run lint                      # eslint
-pnpm run type-check                # tsc --noEmit
-pnpm run prettier-check            # prettier --check
-pnpm run test                      # jest
-pnpm run test:edge                 # vitest (edge runtime)
-pnpm run test:node                 # vitest (node runtime)
-```
+| The list says | Meaning | Effect on the pull request |
+|---|---|---|
+| `-handle` | a maintainer ran `!denounce` after the code of conduct process | closed, even with an accepted issue |
+| nothing at all | everybody who has not contributed here before | **none.** One comment saying nothing is blocked. |
+| `handle` | a maintainer ran `!vouch` | none, and the comment stops appearing |
 
-- **Build:** tsup (CJS + ESM)
-- **Lint:** ESLint + Prettier
-- **Test:** jest + vitest (edge/node configs)
+Being vouched grants nothing. It is a "we have seen this person before" flag that mutes the newcomer comment, not permission to skip the accepted-issue rule. Being absent from the list costs nothing.
 
-### OpenClaw Plugin (`openclaw/`)
+If you are an agent opening a pull request on someone's behalf, the practical consequence is one rule: **get the linked issue labelled `accepted` before you open the pull request, or expect the pull request to be closed and to reopen later.** Do not work around either gate, do not reopen a gated pull request by hand, and do not re-file the same change under a new pull request when one is closed.
 
-```bash
-cd openclaw
-pnpm install
-pnpm run build                     # tsup
-pnpm run test                      # vitest run
-```
+### The CLA is not optional
 
-- **Build:** tsup (ESM)
-- **Test:** vitest (with Codecov in CI)
-- **Plugin manifest:** `openclaw.plugin.json`
+**A pull request from a contributor who has not signed the Contributor License Agreement is not accepted, not reviewed, and not merged.** This is not a formality applied at merge time. An unsigned pull request does not enter the review queue at all: maintainers do not read the diff, do not leave feedback, and do not discuss the approach. It sits until the CLA is signed, and it is closed if it goes stale.
 
-### Server (`server/`)
+The `CLAassistant` bot comments on your first pull request with a link. Signing takes under a minute, is done once per GitHub account, and covers every contribution you make afterwards. Until it is signed the `license/cla` check stays red.
 
-```bash
-# Docker production build
-cd server
-make build                         # docker build -t mem0-api-server .
-make run_local                     # docker run -p 8000:8000 with .env
+If you are an agent opening a pull request on someone's behalf, tell them they must sign it themselves. Nobody else can sign for them, and the pull request goes nowhere until they do.
 
-# Docker Compose development (FastAPI + PostgreSQL/pgvector + Neo4j)
-cd server
-docker-compose up                  # starts all 3 services
-# mem0 API: localhost:8888
-# PostgreSQL: localhost:8432
-# Neo4j HTTP: localhost:8474, Bolt: localhost:8687
-```
+### What gets a pull request closed
 
-- **Framework:** FastAPI with uvicorn (auto-reload in dev)
-- **Services:** PostgreSQL with pgvector, Neo4j 5.x with APOC plugin
-- **Hot reload:** Dev Dockerfile mounts `server/` and `mem0/` for live changes
+Beyond the CLA and the accepted-issue gate, the [Contribution Conduct](CODE_OF_CONDUCT.md#contribution-conduct) section of the code of conduct is the enforceable form of this repo's anti-slop policy:
 
-### OpenMemory (`openmemory/`)
+- **Disclose AI use.** The PR template asks how the *code* was written; drafting the description with a model is fine. The disclosure is never held against you, it tells a reviewer where to look. Silence followed by a review comment you cannot answer is what costs everyone the afternoon.
+- **Do not submit work you have not run.** A bug report means you reproduced it. A PR means you ran the tests.
+- **Do not fabricate evidence.** Invented tracebacks, unmeasured benchmarks, tests that assert the implementation back at itself, descriptions that describe a different change than the diff makes.
+- **Match your volume to your engagement.** Open changes at the rate you can discuss them.
+- **Do not press for merges.** One polite follow-up after a reasonable wait is fine.
+- **You must be able to explain every line of your diff** and how it interacts with the rest of the codebase, without asking an AI tool. This is the one rule that does not bend.
 
-```bash
-# Full stack via Docker Compose
-cd openmemory
-docker-compose up
-# Qdrant: localhost:6333
-# API (MCP): localhost:8765
-# UI: localhost:3000
+### Reference
 
-# Individual development
-cd openmemory/api && uvicorn main:app --reload       # FastAPI backend
-cd openmemory/ui && npm run dev                       # Next.js frontend
-
-# Tests
-cd openmemory/api && pytest tests/                   # API tests (e.g., test_mcp_server.py)
-```
-
-- **API:** FastAPI + Alembic (DB migrations) + MCP server (Model Context Protocol)
-- **UI:** Next.js 15, React 19, Radix UI, Redux Toolkit, TailwindCSS, Recharts
-- **Vector store:** Qdrant
-
-### Documentation (`docs/`)
-
-```bash
-make docs                          # or: cd docs && mintlify dev
-```
-
-- **Framework:** Mintlify
-- **API spec:** `docs/openapi.json`
-- **Structure:** `api-reference/`, `open-source/`, `platform/`, `integrations/`, `cookbooks/`, `core-concepts/`
-
-### Evaluation (`evaluation/`)
-
-```bash
-cd evaluation
-make run-mem0-add                  # Run mem0 add experiments
-make run-mem0-search               # Run mem0 search experiments
-make run-mem0-plus-add             # With graph memory
-make run-mem0-plus-search          # With graph memory
-make run-rag                       # RAG baseline
-make run-full-context              # Full context baseline
-make run-langmem                   # LangMem comparison
-make run-openai                    # OpenAI comparison
-```
-
-## Core APIs
-
-### Python
-
-| Function / Class | Purpose | Import |
-|-----------------|---------|--------|
-| `Memory` | Self-hosted memory (sync) | `from mem0 import Memory` |
-| `AsyncMemory` | Self-hosted memory (async) | `from mem0 import AsyncMemory` |
-| `MemoryClient` | Hosted platform client (sync) | `from mem0 import MemoryClient` |
-| `AsyncMemoryClient` | Hosted platform client (async) | `from mem0 import AsyncMemoryClient` |
-
-**Key `Memory` / `MemoryClient` methods:**
-
-| Method | Purpose |
-|--------|---------|
-| `add(messages, *, user_id, agent_id, run_id, metadata)` | Store a new memory |
-| `search(query, *, user_id, agent_id, run_id, limit, filters)` | Search memories |
-| `get(memory_id)` | Retrieve a single memory by ID |
-| `get_all(*, user_id, agent_id, run_id, limit)` | List all memories |
-| `update(memory_id, data)` | Update a memory |
-| `delete(memory_id)` | Delete a memory |
-| `delete_all(*, user_id, agent_id, run_id)` | Delete all memories |
-| `history(memory_id)` | Get change history for a memory |
-
-### TypeScript
-
-| Export | Purpose | Import |
-|--------|---------|--------|
-| `MemoryClient` | Hosted platform client | `import { MemoryClient } from 'mem0ai'` |
-| `Memory` | Self-hosted OSS memory | `import { Memory } from 'mem0ai/oss'` |
-
-## Import Patterns
-
-### Python
-
-| What | Import |
-|------|--------|
-| Core memory classes | `from mem0 import Memory, AsyncMemory` |
-| Platform client | `from mem0 import MemoryClient, AsyncMemoryClient` |
-| Configuration | `from mem0.configs.base import MemoryConfig` |
-| LLM providers | `from mem0.llms.<provider> import <ProviderLLM>` |
-| Embedding providers | `from mem0.embeddings.<provider> import <ProviderEmbedding>` |
-| Vector store providers | `from mem0.vector_stores.<provider> import <ProviderVectorStore>` |
-
-### TypeScript
-
-| What | Import |
-|------|--------|
-| Hosted client | `import { MemoryClient } from 'mem0ai'` |
-| OSS memory | `import { Memory } from 'mem0ai/oss'` |
-| Specific providers (OSS) | `import { OpenAIEmbedding } from 'mem0ai/oss'` |
-
-## Coding Standards
-
-### File Naming Conventions
-
-- **Python source files:** `snake_case.py` (e.g., `azure_openai.py`, `cohere_reranker.py`)
-- **Python test files:** `test_<module>.py` (e.g., `test_memory.py`, `test_main.py`)
-- **TypeScript source files:** `snake_case.ts` (e.g., `azure_ai_search.ts`)
-- **TypeScript test files:** `<module>.test.ts` (e.g., `memory.test.ts`)
-- **Config/manifest files:** `kebab-case` (e.g., `openclaw.plugin.json`, `jest.config.js`)
-
-### Python Conventions
-
-- **Provider pattern:** All providers (LLMs, embeddings, vector stores, graphs, rerankers) inherit from a `base.py` abstract class in their directory. Config classes live in `configs.py`.
-- **Pydantic v2** for all data models and configuration.
-- **Ruff** is the single linting and formatting tool — no black, no flake8.
-  - Root SDK: line length **120**
-  - Python CLI: line length **100** with extended rule set (UP, B, SIM, RUF)
-- **isort** with `profile = "black"` for import sorting.
-- Ruff excludes `embedchain/` and `openmemory/` from root config.
-
-### TypeScript Conventions
-
-- **Build:** tsup across all packages.
-- **Package manager:** pnpm everywhere (no npm, no yarn).
-- **TypeScript strict mode** across all packages.
-- **Linting varies by package:**
-
-| Package | Linter | Formatter | Test Framework |
-|---------|--------|-----------|---------------|
-| `mem0-ts/` | — | Prettier | jest |
-| `cli/node/` | Biome | Biome | vitest |
-| `vercel-ai-sdk/` | ESLint | Prettier | jest + vitest |
-| `openclaw/` | — | — | vitest |
-
-### Type Checking
-
-Always run type checking after modifying TypeScript code:
-
-```bash
-cd <package> && pnpm run typecheck    # or: tsc --noEmit
-```
-
-## Architecture
-
-### Provider Pattern
-
-The SDK uses a consistent plugin architecture across 5 categories. Each category has a `base.py` abstract class and concrete provider implementations:
-
-| Category | Count | Examples |
-|----------|-------|---------|
-| **LLMs** | 24 | OpenAI, Anthropic, AWS Bedrock, Azure OpenAI, Gemini, Groq, Ollama, Together, DeepSeek, vLLM, LiteLLM, LM Studio, xAI |
-| **Vector Stores** | 30 | Qdrant, Pinecone, Chroma, Weaviate, Milvus, MongoDB, Redis, Elasticsearch, pgvector, Supabase, Faiss, S3 Vectors |
-| **Embeddings** | 15 | OpenAI, Azure OpenAI, Gemini, HuggingFace, FastEmbed, Together, AWS Bedrock, Ollama, Vertex AI |
-| **Graph Stores** | 4 | Neo4j, Memgraph, Kuzu, Apache AGE |
-| **Rerankers** | 5 | Cohere, HuggingFace, LLM-based, Sentence Transformer, Zero Entropy |
-
-### Two Usage Modes
-
-Self-hosted `Memory` / `AsyncMemory` classes and hosted-platform `MemoryClient` — both in Python and TypeScript.
-
-### Graph Memory
-
-Optional layer on top of vector memory for relationship-aware retrieval. Configured via the `graph` section of `MemoryConfig`.
-
-### MCP Integration
-
-Model Context Protocol support in multiple places:
-
-- **Remote:** MCP server at `mcp.mem0.ai`
-- **Local:** MCP server in `openmemory/api/` (FastAPI-based)
-- **Plugin:** MCP tools in `mem0-plugin/` — 9 tools: `add_memory`, `search_memories`, `get_memories`, `get_memory`, `update_memory`, `delete_memory`, `delete_all_memories`, `delete_entities`, `list_entities`
-
-### Plugin & Skills System
-
-- `mem0-plugin/` provides integrations for Claude Code, Cursor, and Codex via MCP server connections and lifecycle hooks for automatic memory capture.
-- `skills/` contains structured skill definitions for AI agents, covering SDK usage, CLI workflows, and Vercel AI SDK patterns.
-
-### Adding a New Provider
-
-To add a new LLM, embedding, vector store, or reranker provider:
-
-1. Create `mem0/<category>/<provider_name>.py`
-2. Inherit from the abstract base class in `mem0/<category>/base.py`
-3. Add configuration to `mem0/<category>/configs.py` (if the category uses one)
-4. Register the provider in `mem0/<category>/__init__.py`
-5. Add tests in `tests/<category>/<provider_name>/`
-6. Add any new dependencies to the appropriate optional group in `pyproject.toml` (never to core `dependencies`)
-7. Follow the exact pattern of existing providers in the same category — match method signatures, error handling, and config structure
-
-## CI/CD
-
-### CI Workflows (automated testing)
-
-| Workflow | File | Triggers | Tests |
-|----------|------|----------|-------|
-| Python SDK | `ci.yml` | Push to main, PRs on `mem0/`, `tests/`, `pyproject.toml` | Ruff lint + pytest on Python 3.10, 3.11, 3.12 |
-| TypeScript SDK | `ts-sdk-ci.yml` | Push to main, PRs on `mem0-ts/` | Prettier + build + jest on Node 20, 22 |
-| Python CLI | `cli-python-ci.yml` | Push to `cli/python/`, PRs, manual | Ruff lint + pytest + hatch build on Python 3.10, 3.11, 3.12 |
-| Node CLI | `cli-node-ci.yml` | Push to `cli/node/`, PRs, manual | Biome lint + tsc + vitest + tsup build on Node 20, 22 |
-| OpenClaw | `openclaw-checks.yml` | Push to `openclaw/`, PRs, manual | tsc + vitest (with Codecov) + tsup build on Node 20, 22 |
-| Embedchain | `ci.yml` (shared) | PRs on `embedchain/` | Ruff + pytest + coverage on Python 3.9–3.12 |
-
-### CD Workflows (automated publishing)
-
-| Workflow | File | Tag Prefix | Target |
-|----------|------|------------|--------|
-| Python SDK | `cd.yml` | `v*` | PyPI (`mem0ai`) |
-| TypeScript SDK | `ts-sdk-cd.yml` | `ts-v*` | npm (`mem0ai`) |
-| Python CLI | `cli-python-cd.yml` | `cli-v*` | PyPI (`mem0-cli`) |
-| Node CLI | `cli-node-cd.yml` | `cli-node-v*` | npm (`@mem0/cli`) |
-| Vercel AI SDK | `vercel-ai-cd.yml` | `vercel-ai-v*` | npm (`@mem0/vercel-ai-provider`) |
-| OpenClaw | `openclaw-cd.yml` | `openclaw-v*` | npm (`@mem0/openclaw-mem0`) |
-
-- All publishing uses **OIDC trusted publishing** — no tokens or secrets required.
-- First publish of a new npm package must be done manually; OIDC works for subsequent versions.
-
-### Utility Workflows
-
-| Workflow | File | Purpose |
-|----------|------|---------|
-| Issue Labeler | `issue-labeler.yml` | Automatic issue labeling |
-| Stale Bot | `stale.yml` | Marks stale issues and PRs |
-
-## Task Completion Guidelines
-
-These guidelines outline typical artifacts for different task types. Use judgment to adapt based on scope and context.
-
-### Bug Fixes
-
-1. **Unit tests**: Add tests that would fail without the fix (regression tests)
-2. **Implementation**: Fix the bug
-3. **Manual verification**: Run the relevant test suite to confirm the fix
-4. **Lint**: Run the appropriate linter for the package you modified
-
-### New Features
-
-1. **Implementation**: Build the feature following existing patterns
-2. **Unit tests**: Comprehensive test coverage for new functionality
-3. **Documentation**: Update relevant docs in `docs/` for public APIs
-4. **Examples**: Add usage examples if the feature introduces new user-facing behavior
-
-### New Provider (LLM / Embedding / Vector Store / Reranker)
-
-1. **Implementation**: Follow the "Adding a New Provider" steps above
-2. **Tests**: Add unit tests matching the pattern of existing providers
-3. **Configuration**: Add to the appropriate `configs.py` and `__init__.py`
-4. **Dependencies**: Add to the correct optional group in `pyproject.toml`
-5. **Documentation**: Add an integration guide in `docs/integrations/`
-
-### Refactoring / Internal Changes
-
-- Unit tests for any changed behavior
-- No documentation needed for internal-only changes
-- Ensure all existing tests still pass
-
-### When to Deviate
-
-These are guidelines, not rigid rules. Adjust based on:
-
-- **Scope**: Trivial fixes (typos, comments) may not need tests
-- **Visibility**: Internal changes may not need documentation
-- **Context**: Some changes span multiple categories — use judgment
-
-When uncertain about expected artifacts, ask for clarification.
-
-## Contributing Guidelines
-
-### Workflow
-
-1. Fork and clone the repository.
-2. Create a feature branch from `main` (e.g., `feature/my-new-feature`).
-3. Make your changes — add tests, docs, and examples as appropriate.
-4. Run linting and tests for every package you modified (see commands above).
-5. Run `pre-commit install` on first setup — hooks run ruff + isort automatically.
-6. Commit with a clear message following [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat:`, `fix:`, `docs:`, `refactor:`).
-7. Push and open a Pull Request against `main`.
-
-### Pull Request Requirements
-
-Every PR must follow the repo's PR template (`.github/PULL_REQUEST_TEMPLATE.md`):
-
-1. **Linked Issue** — Reference the issue with `Closes #<number>`. If no issue exists, create one first or explain why in the description.
-2. **Description** — Explain what the PR does and why it's needed.
-3. **Type of Change** — Check the appropriate box:
-   - Bug fix / New feature / Breaking change / Refactor / Documentation update
-4. **Breaking Changes** — If applicable, describe what breaks and the migration path.
-5. **Test Coverage** — Check what applies:
-   - Added/updated unit tests
-   - Added/updated integration tests
-   - Tested manually (describe how)
-   - No tests needed (explain why)
-6. **Checklist** — All must be checked before merge:
-   - [ ] Code follows the project's style guidelines
-   - [ ] Self-review performed
-   - [ ] Tests added that prove the fix/feature works
-   - [ ] New and existing tests pass locally
-   - [ ] Documentation updated if needed
-
-### PR Description Template
-
-```markdown
-## Linked Issue
-
-Closes #<!-- issue number -->
-
-## Description
-
-<!-- What does this PR do? Why is it needed? -->
-
-## Type of Change
-
-- [ ] Bug fix (non-breaking change that fixes an issue)
-- [ ] New feature (non-breaking change that adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to change)
-- [ ] Refactor (no functional changes)
-- [ ] Documentation update
-
-## Breaking Changes
-
-N/A
-
-## Test Coverage
-
-- [ ] I added/updated unit tests
-- [ ] I added/updated integration tests
-- [ ] I tested manually (describe below)
-- [ ] No tests needed (explain why)
-
-## Checklist
-
-- [ ] My code follows the project's style guidelines
-- [ ] I have performed a self-review of my code
-- [ ] I have added tests that prove my fix/feature works
-- [ ] New and existing tests pass locally
-- [ ] I have updated documentation if needed
-```
-
-### General Rules
-
-- Follow existing code patterns — don't introduce new frameworks or abstractions without discussion.
-- Version bumps go in `pyproject.toml` (Python) or `package.json` (TypeScript).
-- For `server/` and `openmemory/` work, use Docker Compose for local development.
-- Do NOT use `pip` or `conda` for dependency management — use `hatch` (see `docs/contributing/development.mdx`).
-
-### Contributing Guides
-
-| Task | Guide |
-|------|-------|
-| Code contributions | `docs/contributing/development.mdx` |
+| Topic | File |
+|-------|------|
+| Contributor guide | [`CONTRIBUTING.md`](CONTRIBUTING.md) |
+| Code of conduct | [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) |
+| Security reports | [`SECURITY.md`](SECURITY.md) |
+| Development setup | `docs/contributing/development.mdx` |
 | Documentation contributions | `docs/contributing/documentation.mdx` |
 | PR template | `.github/PULL_REQUEST_TEMPLATE.md` |
-| Bug reports | `.github/ISSUE_TEMPLATE/bug_report.yml` |
-| Feature requests | `.github/ISSUE_TEMPLATE/feature_request.yml` |
-| Documentation issues | `.github/ISSUE_TEMPLATE/documentation_issue.yml` |
-
-## Do NOT
-
-- Modify CI/CD workflows without explicit approval.
-- Add new Python dependencies to the core `dependencies` list in `pyproject.toml` without discussion — use optional dependency groups instead.
-- Commit `.env` files, API keys, or credentials.
-- Modify `embedchain/` unless specifically working on that package — it has its own build system (Poetry).
-- Skip pre-commit hooks.
-- Use npm or yarn in TypeScript packages — this repo uses pnpm exclusively.
-- Use `require()` for imports in TypeScript — use ES module `import` syntax.
-- Mix up linter configs: root Python SDK uses line-length 120, Python CLI uses 100, Node CLI uses Biome (not ESLint/Ruff).
-- Modify `openmemory/` database migrations without understanding the Alembic migration chain.
-- Change public APIs without updating documentation in `docs/`.
+| Issue forms | `.github/ISSUE_TEMPLATE/` |
+| Contribution gates | [Two gates decide whether your pull request stays open](#two-gates-decide-whether-your-pull-request-stays-open) |
+| Trust list (vouch) | [`.github/VOUCHED.td`](.github/VOUCHED.td) |
+| CI/CD, gates, rulesets | [`.github/AGENTS.md`](.github/AGENTS.md) |

CODE_OF_CONDUCT.md

@@ -0,0 +1,181 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Contribution Conduct
+
+Mem0 receives more contributions than any maintainer can read line by line. The
+rules below exist so that the time we do have goes to people who are actually
+trying to improve the project. They apply to issues, pull requests, discussions,
+and reviews.
+
+**Be honest about how the work was produced.** Using an AI tool to find a bug,
+write a patch, or draft a description is fine and welcome. Not saying so is not.
+Every issue form and the pull request template ask about AI, and the answer is
+never held against you. It tells a reviewer where to look. An unanswered review
+comment on code the author cannot explain is what costs us the afternoon.
+
+**Do not submit work you have not verified.** A reported bug means you ran it and
+saw it. A pull request means you ran the tests. Pasting a model's output, a
+scanner result, or a plausible-looking patch and letting maintainers find out
+whether it is real moves your work onto someone else's desk. Reports and patches
+that turn out to be unverified are closed without a detailed response.
+
+**Do not fabricate evidence.** Invented tracebacks, benchmark numbers you did not
+measure, reproductions that were never run, tests that assert the implementation
+back at itself, and descriptions that describe a different change than the diff
+makes are all treated the same way, regardless of whether a person or a tool
+produced them.
+
+**Match your volume to your engagement.** Open changes at the rate you can
+discuss them. A queue of open pull requests from one author, none of them
+answered when questioned, is treated as automated submission and handled under
+enforcement below, whatever the individual diffs look like.
+
+**Do not press for merges.** Bumping a thread, tagging maintainers repeatedly,
+asking in Discord or by direct message for a review, and reopening a closed pull
+request without addressing why it was closed all take attention away from the
+queue rather than moving your change through it. One polite follow-up after a
+reasonable wait is fine.
+
+**Do not contribute for a badge.** Changes made to raise a contribution count,
+qualify for an event, or pad a profile, whitespace edits, README churn, and
+mechanical reformatting bundled with nothing else, are closed on sight.
+
+**Disagreement is fine, and closing is not a verdict.** Our pull request gate
+closes changes that do not yet link an accepted issue. That is a queue decision,
+not a judgment of you or your code, and reopening takes about a minute. Argue for
+your change on its merits; that is a normal and welcome part of contributing.
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, including this
+repository, our Discord, and our documentation, and also applies when an
+individual is officially representing the community in public spaces. Examples of
+representing our community include using an official email address, posting via
+an official social media account, or acting as an appointed representative at an
+online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers at **support@mem0.ai**. All complaints will be
+reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community, or a first contribution that
+breaches the Contribution Conduct rules above.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions, including a repeated pattern of unverified or automated submissions
+after a first warning.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban. At this stage the account may be denounced in `.github/VOUCHED.td`, which
+means new pull requests are flagged automatically.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+The Contribution Conduct section is specific to this repository.
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][mozilla].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][faq]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[mozilla]: https://github.com/mozilla/inclusion
+[faq]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -1,72 +1,235 @@
-# Contributing to mem0
+# Contributing to Mem0
 
-Let us make contribution easy, collaborative and fun.
+First off, thank you for taking the time to contribute! 🎉 Mem0 is a
+community-driven project and we welcome contributions of all kinds — bug fixes,
+new features, documentation, examples, and integrations.
 
-## Submit your Contribution through PR
+Mem0 is a polyglot monorepo, and this guide covers contributing to both the
+**Python SDK** and the **TypeScript SDK** (and the rest of the repository).
 
-To make a contribution, follow these steps:
+By participating you agree to our [Code of Conduct](./CODE_OF_CONDUCT.md). Its
+**Contribution Conduct** section is the enforceable form of the rules on this
+page: disclose AI use, don't submit work you haven't run, don't fabricate
+reproductions or benchmarks, keep your volume matched to your engagement, and
+don't press for merges.
 
-1. Fork and clone this repository
-2. Do the changes on your fork with dedicated feature branch `feature/f1`
-3. If you modified the code (new feature or bug-fix), please add tests for it
-4. Include proper documentation / docstring and examples to run the feature
-5. Ensure that all tests pass
-6. Submit a pull request
+## Before You Start
 
-For more details about pull requests, please read [GitHub's guides](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
+### 1. Open an Issue First
 
+**Always open an issue before opening a pull request.** This lets us discuss the
+change, avoid duplicate effort, and agree on the approach before you invest time
+in code.
 
-### 📦 Development Environment
+- Search [existing issues](https://github.com/mem0ai/mem0/issues) first to see if
+  your bug or idea already exists.
+- If it doesn't, open a
+  [bug report](https://github.com/mem0ai/mem0/issues/new?template=bug_report.yml) or
+  [feature request](https://github.com/mem0ai/mem0/issues/new?template=feature_request.yml).
+- For anything beyond a trivial fix, wait for a maintainer to confirm the approach
+  before starting significant work.
 
-We use `hatch` for managing development environments. To set up:
+A bug report needs a reproduction we can run, the version you are on, and the
+real output or traceback you saw. Reports without those cannot be acted on and
+get closed. A feature request needs the problem you hit and the workaround you
+are living with, not just the API you would like.
+
+Every pull request must link to an issue using `Closes #<issue-number>`, and that
+issue must carry the `accepted` label. A maintainer applies `accepted` once we
+agree the change is one we want.
+
+Pull requests that don't link an accepted issue are closed automatically by the
+[PR Gate](./.github/workflows/pr-gate.yml). **Closed does not mean rejected.** It
+means the change isn't in the queue yet. Once a maintainer labels the issue the
+pull request reopens itself, and you don't have to do anything. Documentation-only
+changes skip the gate entirely.
+
+A second check looks at who opened the pull request rather than what it changes.
+If you are not yet in this repo's contributor list
+([`.github/VOUCHED.td`](./.github/VOUCHED.td)) you get one comment saying so.
+**Nothing is blocked and there is nothing you need to do.** A maintainer can add
+you by commenting `!vouch @you` on any issue, which only stops that comment from
+appearing again. Being on the list is not permission to skip the accepted-issue
+rule, and being absent from it costs you nothing.
+
+The list has a negative side too. A maintainer can `!denounce` an account that
+has been through the
+[code of conduct](./CODE_OF_CONDUCT.md#contribution-conduct) enforcement process,
+and pull requests from that account are closed whether or not they link an
+accepted issue. This is rare, it is never where anyone starts, and it is
+reversible.
+
+Security fixes are the one exception, and they don't go through public pull
+requests at all. Follow the [Security Policy](./SECURITY.md) instead, which uses
+a private advisory and a private fork so the vulnerability isn't disclosed before
+the fix ships.
+
+### 2. Understand Your Code
+
+**You must be able to explain what your changes do and how they interact with
+the rest of the codebase without the help of an AI tool.** This is the one rule
+we will not bend on.
+
+Using AI to write code is fine. Most of us do. You can build real understanding
+by interrogating an agent about this codebase until you grasp the edge cases and
+the blast radius of your change. What is not fine is opening a pull request for
+a diff you cannot defend in review.
+
+Disclose it in the pull request template and say what you checked yourself.
+We ask about the code, not the write-up: using AI to draft the pull request
+description is fine. We ask because it tells reviewers where to look, not
+because it counts against you. An honest "an agent wrote this, here is what I
+verified" is welcome. Silence, followed by a review comment you cannot answer,
+is what wastes everyone's time.
+
+Signs your pull request will be closed:
+
+- Invented APIs, config keys, or providers that don't exist in this repo.
+- Tests that assert the implementation back at itself rather than the behaviour.
+- A description that describes a different change than the diff makes.
+- Sweeping unrelated reformatting bundled with a small fix.
+- You cannot answer a direct question about your own diff.
+
+### 3. Sign the Contributor License Agreement (CLA)
+
+**We cannot accept or merge any pull request until you have signed our Contributor
+License Agreement (CLA).**
+
+When you open your first PR, the CLA bot will automatically comment with a link to
+sign. Signing takes less than a minute and only needs to be done once. Pull
+requests from contributors who have not signed the CLA will be blocked from
+merging.
+
+## First Contribution Fast Path
+
+Fixing a typo or a small docs issue? You don't need the full workflow below.
+
+1. **Pick something small.** Look for issues labeled `documentation` or `good first issue`, or a typo/broken link you noticed while reading the docs.
+2. **Branch from `main`** with a name that says what you're fixing, e.g. `docs/fix-quickstart-typo` or `fix/broken-crewai-link`.
+3. **Make the change, then run only what applies:**
+   - Docs-only change (`docs/**`): preview with `make docs`. If you added or removed an `.mdx` page, run `python scripts/check-llms-txt-coverage.py --write` so `docs/llms.txt` stays in sync.
+   - Code change: run the linter and tests for the package you touched, see [Development Workflow](#development-workflow) below.
+4. **Open a PR** against `main` with `Closes #<issue-number>` and a one-line description of what you fixed.
+
+For anything larger than a docs fix or a small bug, follow the full workflow below.
+
+## Repository Layout
+
+The two most common contribution targets are the SDKs:
+
+| Package               | Path       | Language     | Package manager |
+| --------------------- | ---------- | ------------ | --------------- |
+| Python SDK (`mem0ai`) | `mem0/`    | Python 3.9+  | `hatch`         |
+| TypeScript SDK (`mem0ai`) | `mem0-ts/` | TypeScript | `pnpm`        |
+
+Other packages include the CLIs (`cli/python/`, `cli/node/`), integrations
+(`integrations/`), the self-hosted `server/`, and the docs site
+(`docs/`). See [AGENTS.md](./AGENTS.md) for a full map of the repository.
+
+## Development Workflow
+
+1. **Fork** the repository and **clone** your fork.
+2. Create a **feature branch** from `main` (e.g. `feature/my-new-feature` or
+   `fix/issue-1234`).
+3. Make your changes — add **tests**, **documentation**, and **examples** as
+   appropriate.
+4. Run **linting and tests** for every package you touched (see below).
+5. Commit using [Conventional Commits](https://www.conventionalcommits.org/)
+   (e.g. `feat:`, `fix:`, `docs:`, `refactor:`, `test:`).
+6. Push and open a **pull request** against `main`, linking the issue with
+   `Closes #<number>` and filling out the
+   [PR template](./.github/PULL_REQUEST_TEMPLATE.md).
+
+### Contributing to the Python SDK (`mem0/`)
+
+We use [`hatch`](https://hatch.pypa.io/latest/install/) to manage environments.
+**Do not use `pip` or `conda` for dependency management.**
 
 ```bash
-# Activate environment for specific Python version:
-hatch shell dev_py_3_9   # Python 3.9
-hatch shell dev_py_3_10  # Python 3.10  
-hatch shell dev_py_3_11  # Python 3.11
-hatch shell dev_py_3_12  # Python 3.12
+# Activate a dev environment (3.9 / 3.10 / 3.11 / 3.12)
+hatch shell dev_py_3_11
 
-# The environment will automatically install all dev dependencies
-# Run tests within the activated shell:
-make test
-```
-
-### 📌 Pre-commit
-
-To ensure our standards, make sure to install pre-commit before starting to contribute.
-
-```bash
+# Install pre-commit hooks (runs ruff + isort on commit)
 pre-commit install
+
+# Lint, format, and sort imports
+make lint
+make format
+make sort
+
+# Run the test suite (run `make install_all` first if deps are missing)
+make test
 ```
 
-### 🧪 Testing
+- **Linter / formatter:** Ruff (line length **120**)
+- **Import sorting:** isort (`profile = "black"`)
+- **Tests:** pytest (in `tests/`)
 
-We use `pytest` to test our code across multiple Python versions. You can run tests using:
+See the full [Development guide](https://docs.mem0.ai/contributing/development) for
+environment details.
+
+### Contributing to the TypeScript SDK (`mem0-ts/`)
+
+We use [`pnpm`](https://pnpm.io/) (v10+) for all TypeScript packages. **Do not use
+`npm` or `yarn`.**
 
 ```bash
-# Run tests with default Python version
-make test
+cd mem0-ts
+pnpm install
 
-# Test specific Python versions:
-make test-py-3.9   # Python 3.9 environment
-make test-py-3.10  # Python 3.10 environment
-make test-py-3.11  # Python 3.11 environment
-make test-py-3.12  # Python 3.12 environment
-
-# When using hatch shells, run tests with:
-make test  # After activating a shell with hatch shell test_XX
+pnpm run build        # tsup (CJS + ESM)
+pnpm run test         # jest (all tests)
+pnpm run test:unit    # unit tests with coverage
 ```
 
-Make sure that all tests pass across all supported Python versions before submitting a pull request.
+- **Build:** tsup
+- **Formatter:** Prettier
+- **Tests:** jest
+- Always run type checking after changes: `pnpm run typecheck` (or `tsc --noEmit`).
+- Use ES module `import` syntax — never `require()`.
 
-We look forward to your pull requests and can't wait to see your contributions!
+## Good Contribution Practices
 
-### 🚀 Releasing
+- **Keep PRs small and focused.** One logical change per PR is easier to review and
+  merge.
+- **Follow existing patterns.** Match the style, structure, and conventions of the
+  code around you. Don't introduce new frameworks or abstractions without
+  discussion.
+- **Write tests** that would fail without your change — regression tests for bugs,
+  coverage for new features.
+- **Update documentation** in `docs/` for any user-facing change. New `.mdx` pages
+  must be added to `docs/llms.txt` (run
+  `python scripts/check-llms-txt-coverage.py --write` to scaffold entries).
+- **Add examples** when introducing new user-facing behavior.
+- **Run linters and tests locally** before pushing — CI re-runs them on every PR
+  via the CI Gate.
+- **Never commit secrets** — no `.env` files, API keys, or credentials.
+- **Don't add core dependencies lightly.** New Python dependencies belong in an
+  optional group in `pyproject.toml`, not the core `dependencies` list.
+- **Be responsive** to review feedback and keep your branch up to date with `main`.
 
-All packages are published automatically via GitHub Actions when a GitHub Release is created with the correct tag prefix.
+## Pull Request Checklist
 
-#### Tag Prefixes
+Before requesting review, make sure:
+
+- [ ] An issue exists and is linked with `Closes #<number>`
+- [ ] You have signed the CLA
+- [ ] Your code follows the project's style guidelines (lint passes)
+- [ ] You performed a self-review of your changes
+- [ ] Tests are added/updated and pass locally
+- [ ] Documentation is updated if needed
+
+## Reporting Security Issues
+
+**Do not report security vulnerabilities through public issues or pull requests.**
+Please follow our [Security Policy](./SECURITY.md) to report them privately.
+
+## Releasing
+
+All packages are published automatically via GitHub Actions when a GitHub Release
+is created with the correct tag prefix.
+
+### Tag Prefixes
 
 | Package | Registry | Tag Prefix | Example |
 |---------|----------|------------|---------|
@@ -77,15 +240,17 @@ All packages are published automatically via GitHub Actions when a GitHub Releas
 | `@mem0/vercel-ai-provider` | npm | `vercel-ai-v*` | `vercel-ai-v2.0.6` |
 | `@mem0/openclaw-mem0` | npm | `openclaw-v*` | `openclaw-v1.0.1` |
 
-#### How to Release
+### How to Release
 
 1. Bump the version in `pyproject.toml` (Python) or `package.json` (Node)
 2. Create a [GitHub Release](https://github.com/mem0ai/mem0/releases/new) with the matching tag prefix
 3. The correct workflow will trigger automatically — verify in the [Actions tab](https://github.com/mem0ai/mem0/actions)
 
-#### Publishing Details
+### Publishing Details
 
 - **PyPI packages** use OIDC trusted publishing via `pypa/gh-action-pypi-publish`
 - **npm packages** use OIDC trusted publishing via npm CLI (>= 11.5.1) — no tokens or secrets required
 - All workflows require `permissions: id-token: write` for OIDC authentication
 - First publish of a new npm package must be done manually; OIDC works for subsequent versions
+
+We look forward to your pull requests and can't wait to see your contributions!

LLM.md

@@ -1026,7 +1026,8 @@ def get_user_preferences(user_id: str):
 ### AutoGen Integration
 
 ```python
-from cookbooks.helper.mem0_teachability import Mem0Teachability
+# Mem0Teachability lives in examples/notebooks/helper/ — see examples/notebooks/mem0-autogen.ipynb
+from helper.mem0_teachability import Mem0Teachability
 from mem0 import Memory
 
 # Add memory capability to AutoGen agents
@@ -1313,7 +1314,7 @@ async def delete_memory(memory_id: str):
 - **Documentation**: https://docs.mem0.ai
 - **GitHub Repository**: https://github.com/mem0ai/mem0
 - **Discord Community**: https://mem0.dev/DiG
-- **Platform**: https://app.mem0.ai
+- **Platform**: https://app.mem0.ai?utm_source=oss&utm_medium=llm
 - **Research Paper**: https://mem0.ai/research
 - **Examples**: https://github.com/mem0ai/mem0/tree/main/examples
 

MIGRATION_GUIDE_v1.0.md

@@ -1,221 +0,0 @@
-# Migration Guide: Upgrading to mem0 1.0.0
-
-## TL;DR
-
-**What changed?** We simplified the API by removing confusing version parameters. Now everything returns a consistent format: `{"results": [...]}`.
-
-**What you need to do:**
-1. Upgrade: `pip install mem0ai==1.0.0`
-2. Remove `version` and `output_format` parameters from your code
-3. Update response handling to use `result["results"]` instead of treating responses as lists
-
-**Time needed:** ~5-10 minutes for most projects
-
----
-
-## Quick Migration Guide
-
-### 1. Install the Update
-
-```bash
-pip install mem0ai==1.0.0
-```
-
-### 2. Update Your Code
-
-**If you're using the Memory API:**
-
-```python
-# Before
-memory = Memory(config=MemoryConfig(version="v1.1"))
-result = memory.add("I like pizza")
-
-# After
-memory = Memory()  # That's it - version is automatic now
-result = memory.add("I like pizza")
-```
-
-**If you're using the Client API:**
-
-```python
-# Before
-client.add(messages, output_format="v1.1")
-client.search(query, version="v2", output_format="v1.1")
-
-# After
-client.add(messages)  # Just remove those extra parameters
-client.search(query)
-```
-
-### 3. Update How You Handle Responses
-
-All responses now use the same format: a dictionary with `"results"` key.
-
-```python
-# Before - you might have done this
-result = memory.add("I like pizza")
-for item in result:  # Treating it as a list
-    print(item)
-
-# After - do this instead
-result = memory.add("I like pizza")
-for item in result["results"]:  # Access the results key
-    print(item)
-
-# Graph relations (if you use them)
-if "relations" in result:
-    for relation in result["relations"]:
-        print(relation)
-```
-
----
-
-## Enhanced Message Handling
-
-The platform client (MemoryClient) now supports the same flexible message formats as the OSS version:
-
-```python
-from mem0 import MemoryClient
-
-client = MemoryClient(api_key="your-key")
-
-# All three formats now work:
-
-# 1. Single string (automatically converted to user message)
-client.add("I like pizza", user_id="alice")
-
-# 2. Single message dictionary
-client.add({"role": "user", "content": "I like pizza"}, user_id="alice")
-
-# 3. List of messages (conversation)
-client.add([
-    {"role": "user", "content": "I like pizza"},
-    {"role": "assistant", "content": "I'll remember that!"}
-], user_id="alice")
-```
-
-### Async Mode Configuration
-
-The `async_mode` parameter now defaults to `True` but can be configured:
-
-```python
-# Default behavior (async_mode=True)
-client.add(messages, user_id="alice")
-
-# Explicitly set async mode
-client.add(messages, user_id="alice", async_mode=True)
-
-# Disable async mode if needed
-client.add(messages, user_id="alice", async_mode=False)
-```
-
-**Note:** `async_mode=True` provides better performance for most use cases. Only set it to `False` if you have specific synchronous processing requirements.
-
----
-
-## That's It!
-
-For most users, that's all you need to know. The changes are:
-- ✅ No more `version` or `output_format` parameters
-- ✅ Consistent `{"results": [...]}` response format
-- ✅ Cleaner, simpler API
-
----
-
-## Common Issues
-
-**Getting `KeyError: 'results'`?**
-
-Your code is still treating the response as a list. Update it:
-```python
-# Change this:
-for memory in response:
-
-# To this:
-for memory in response["results"]:
-```
-
-**Getting `TypeError: unexpected keyword argument`?**
-
-You're still passing old parameters. Remove them:
-```python
-# Change this:
-client.add(messages, output_format="v1.1")
-
-# To this:
-client.add(messages)
-```
-
-**Seeing deprecation warnings?**
-
-Remove any explicit `version="v1.0"` from your config:
-```python
-# Change this:
-memory = Memory(config=MemoryConfig(version="v1.0"))
-
-# To this:
-memory = Memory()
-```
-
----
-
-## What's New in 1.0.0
-
-- **Better vector stores:** Fixed OpenSearch and improved reliability across all stores
-- **Cleaner API:** One way to do things, no more confusing options
-- **Enhanced GCP support:** Better Vertex AI configuration options
-- **Flexible message input:** Platform client now accepts strings, dicts, and lists (aligned with OSS)
-- **Configurable async_mode:** Now defaults to `True` but users can override if needed
-
----
-
-## Need Help?
-
-- Check [GitHub Issues](https://github.com/mem0ai/mem0/issues)
-- Read the [documentation](https://docs.mem0.ai/)
-- Open a new issue if you're stuck
-
----
-
-## Advanced: Configuration Changes
-
-**If you configured vector stores with version:**
-
-```python
-# Before
-config = MemoryConfig(
-    version="v1.1",
-    vector_store=VectorStoreConfig(...)
-)
-
-# After
-config = MemoryConfig(
-    vector_store=VectorStoreConfig(...)
-)
-```
-
----
-
-## Testing Your Migration
-
-Quick sanity check:
-
-```python
-from mem0 import Memory
-
-memory = Memory()
-
-# Add should return a dict with "results"
-result = memory.add("I like pizza", user_id="test")
-assert "results" in result
-
-# Search should return a dict with "results"
-search = memory.search("food", user_id="test")
-assert "results" in search
-
-# Get all should return a dict with "results"
-all_memories = memory.get_all(user_id="test")
-assert "results" in all_memories
-
-print("✅ Migration successful!")
-```

Makefile

@@ -11,7 +11,7 @@ install:
 	hatch env create
 
 install_all:
-	pip install ruff==0.6.9 groq together boto3 litellm ollama chromadb weaviate weaviate-client sentence_transformers vertexai \
+	pip install ruff==0.16.0 groq together boto3 'litellm>=1.83.7,<1.98.0' ollama chromadb weaviate weaviate-client sentence_transformers vertexai \
 	            google-generativeai elasticsearch opensearch-py vecs "pinecone<7.0.0" pinecone-text faiss-cpu langchain-community \
 							upstash-vector azure-search-documents langchain-memgraph langchain-neo4j langchain-aws rank-bm25 pymochow pymongo psycopg kuzu databricks-sdk valkey
 
@@ -42,9 +42,6 @@ clean:
 test:
 	hatch run test
 
-test-py-3.9:
-	hatch run dev_py_3_9:test
-
 test-py-3.10:
 	hatch run dev_py_3_10:test
 

README.md

@@ -39,18 +39,33 @@
 </p>
 
 <p align="center">
-  <a href="https://mem0.ai/research"><strong>📄 Building Production-Ready AI Agents with Scalable Long-Term Memory →</strong></a>
-</p>
-<p align="center">
-  <strong>⚡ +26% Accuracy vs. OpenAI Memory • 🚀 91% Faster • 💰 90% Fewer Tokens</strong>
+  <a href="https://mem0.ai/research"><strong>📄 Benchmarking Mem0's token-efficient memory algorithm →</strong></a>
 </p>
 
-> **🎉 mem0ai v1.0.0 is now available!** This major release includes API modernization, improved vector store support, and enhanced GCP integration. [See migration guide →](MIGRATION_GUIDE_v1.0.md)
+## New Memory Algorithm (April 2026)
 
-##  🔥 Research Highlights
-- **+26% Accuracy** over OpenAI Memory on the LOCOMO benchmark
-- **91% Faster Responses** than full-context, ensuring low-latency at scale
-- **90% Lower Token Usage** than full-context, cutting costs without compromise
+| Benchmark | Old | New  | Tokens  | Latency p50  |
+| --- | --- | --- | --- | --- |
+| **LoCoMo** | 71.4 | **92.5** | 7.0K  | 0.88s  |
+| **LongMemEval** | 67.8 | **94.4** | 6.8K  | 1.09s  |
+| **BEAM (1M)** | — | **64.1** | 6.7K  | 1.00s  |
+| **BEAM (10M)** | — | **48.6** | 6.9K  | 1.05s  |
+
+All benchmarks run on the same production-representative model stack. Single-pass retrieval (one call, no agentic loops) at a top_200 retrieval budget. Scores reflect Mem0's managed platform, which includes proprietary optimizations not available in the open-source SDK; open-source users should expect directionally similar gains but not identical numbers.
+
+**What changed:**
+- **Single-pass ADD-only extraction** -- one LLM call, no UPDATE/DELETE. Memories accumulate; nothing is overwritten.
+- **Agent-generated facts are first-class** -- when an agent confirms an action, that information is now stored with equal weight.
+- **Entity linking** -- entities are extracted, embedded, and linked across memories for retrieval boosting.
+- **Multi-signal retrieval** -- semantic, BM25 keyword, and entity matching scored in parallel and fused.
+- **Temporal Reasoning** -- time-aware retrieval that ranks the right dated instance for queries about current state, past events, and upcoming plans.
+
+See the [migration guide](https://docs.mem0.ai/migration/oss-v2-to-v3) for upgrade instructions. The [evaluation framework](https://github.com/mem0ai/memory-benchmarks) is open-sourced so anyone can reproduce the numbers.
+
+## Research Highlights
+- **92.5 on LoCoMo** -- +21 points over the previous algorithm
+- **94.4 on LongMemEval** -- +27 points, with 98.2 on assistant memory recall
+- **64.1 on BEAM (1M)** -- production-scale memory evaluation at 1M tokens
 - [Read the full paper](https://mem0.ai/research)
 
 # Introduction
@@ -71,18 +86,37 @@
 
 ## 🚀 Quickstart Guide <a name="quickstart"></a>
 
-Choose between our hosted platform or self-hosted package:
+### Sign up as an agent
 
-### Hosted Platform
+AI agents can mint a working Mem0 API key in under five seconds — no email, no dashboard, no OTP. Four commands end-to-end:
 
-Get up and running in minutes with automatic updates, analytics, and enterprise security.
+```bash
+# 1. Install
+npm install -g @mem0/cli      # or: pip install mem0-cli
 
-1. Sign up on [Mem0 Platform](https://app.mem0.ai)
-2. Embed the memory layer via SDK or API keys
+# 2. Sign up as an agent (replace `claude-code` with your name)
+mem0 init --agent --agent-caller claude-code
 
-### Self-Hosted (Open Source)
+# 3. Add a memory
+mem0 add "I am using mem0"
 
-Install the sdk via pip:
+# 4. Search
+mem0 search "am I using mem0"
+```
+
+The human owner can claim the account later with `mem0 init --email <their-email>` — same key, memories preserved. Full guide: [Sign up as an agent](https://docs.mem0.ai/platform/agent-signup).
+
+| | Library | Self-Hosted Server | Cloud Platform |
+|---|---------|-------------------|----------------|
+| **Best for** | Testing, prototyping | Teams running on their own infrastructure | Zero-ops production use |
+| **Setup** | `pip install mem0ai` | `docker compose up` | Sign up at [app.mem0.ai](https://app.mem0.ai?utm_source=oss&utm_medium=readme) |
+| **Dashboard** | -- | [Yes](https://docs.mem0.ai/open-source/setup) | Yes |
+| **Auth & API Keys** | -- | Yes | Yes |
+| **Advanced Features** | -- | Teasers | All included |
+
+Just testing? Use the library. Building for a team? Self-hosted. Want zero ops? Cloud.
+
+### Library (pip / npm)
 
 ```bash
 pip install mem0ai
@@ -96,10 +130,31 @@ python -m spacy download en_core_web_sm
 ```
 
 Install sdk via npm:
+
 ```bash
 npm install mem0ai
 ```
 
+### Self-Hosted Server
+
+> **Note:** Self-hosted auth is on by default. Upgrading from a pre-auth build? Set `ADMIN_API_KEY`, register an admin through the wizard, or `AUTH_DISABLED=true` for local dev only. See [upgrade notes](https://docs.mem0.ai/open-source/setup#upgrade-notes).
+
+```bash
+# Recommended: one command — start the stack, create an admin, issue the first API key.
+cd server && make bootstrap
+
+# Manual: start the stack and finish setup via the browser wizard.
+cd server && docker compose up -d    # http://localhost:3000
+```
+
+See the [self-hosted docs](https://docs.mem0.ai/open-source/overview) for configuration.
+
+### Cloud Platform
+
+1. Sign up on [Mem0 Platform](https://app.mem0.ai?utm_source=oss&utm_medium=readme)
+2. Embed the memory layer via SDK or API keys
+3. Using hosted Qdrant vectors? See the [Platform migration guide](https://docs.mem0.ai/migration/oss-to-platform) to import them into Mem0 Platform.
+
 ### CLI
 
 Manage memories from your terminal:
@@ -114,9 +169,31 @@ mem0 search "What does Alice prefer?" --user-id alice
 
 See the [CLI documentation](https://docs.mem0.ai/platform/cli) for the full command reference.
 
+### Agent Skills
+
+Teach your AI coding assistant (Claude Code, Codex, Cursor, Windsurf, OpenCode, OpenClaw, and any tool that supports the skills standard) how to build with Mem0. Two categories:
+
+**Reference skills — always on** (SDK knowledge loaded into the assistant's context):
+
+```bash
+npx skills add https://github.com/mem0ai/mem0 --skill mem0
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-cli
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-vercel-ai-sdk
+```
+
+**Pipeline skills — run on demand** (execute an end-to-end workflow in an existing repo):
+
+```bash
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-oss-to-platform
+```
+
+Use `/mem0-integrate` to wire Mem0 into an existing repo via a test-first pipeline, then `/mem0-test-integration` to verify. Use `/mem0-oss-to-platform` to migrate an existing project from Mem0 OSS to the hosted Platform SDK. See the [skills catalog](./skills/) or [Vibecoding with Mem0](https://docs.mem0.ai/vibecoding) for the full picture.
+
 ### Basic Usage
 
-Mem0 requires an LLM to function, with `gpt-4.1-nano-2025-04-14` from OpenAI as the default. However, it supports a variety of LLMs; for details, refer to our [Supported LLMs documentation](https://docs.mem0.ai/components/llms/overview).
+Mem0 requires an LLM to function, with `gpt-5-mini` from OpenAI as the default. However, it supports a variety of LLMs; for details, refer to our [Supported LLMs documentation](https://docs.mem0.ai/components/llms/overview).
 
 Mem0 uses `text-embedding-3-small` from OpenAI as the default embedding model. For best results with hybrid search (semantic + keyword + entity boosting), we recommend using at least [Qwen 600M](https://huggingface.co/Alibaba-NLP/gte-Qwen2-1.5B-instruct) or a comparable embedding model. See [Supported Embeddings](https://docs.mem0.ai/components/embedders/overview) for configuration details.
 
@@ -131,13 +208,13 @@ memory = Memory()
 
 def chat_with_memories(message: str, user_id: str = "default_user") -> str:
     # Retrieve relevant memories
-    relevant_memories = memory.search(query=message, user_id=user_id, limit=3)
+    relevant_memories = memory.search(query=message, filters={"user_id": user_id}, top_k=3)
     memories_str = "\n".join(f"- {entry['memory']}" for entry in relevant_memories["results"])
 
     # Generate Assistant response
     system_prompt = f"You are a helpful AI. Answer the question based on query and memories.\nUser Memories:\n{memories_str}"
     messages = [{"role": "system", "content": system_prompt}, {"role": "user", "content": message}]
-    response = openai_client.chat.completions.create(model="gpt-4.1-nano-2025-04-14", messages=messages)
+    response = openai_client.chat.completions.create(model="gpt-5-mini", messages=messages)
     assistant_response = response.choices[0].message.content
 
     # Create new memories from the conversation

SECURITY.md

@@ -0,0 +1,54 @@
+# Security Policy
+
+We take the security of Mem0 and our community seriously. Thank you for helping
+keep Mem0 and its users safe by disclosing vulnerabilities responsibly.
+
+## Reporting a Vulnerability
+
+Please **do not** report security vulnerabilities through public GitHub issues,
+pull requests, or discussions.
+
+If you believe you have found a security vulnerability in Mem0, please report it
+privately through one of the following channels:
+
+1. **GitHub Private Vulnerability Reporting** — open a
+   [private security advisory](https://github.com/mem0ai/mem0/security/advisories/new)
+   directly on this repository.
+2. **Email** the maintainers at **support@mem0.ai** with the subject line:
+
+   `SECURITY: Mem0 vulnerability report`
+
+To help us triage and resolve the issue quickly, please include as much of the
+following as you can:
+
+- Affected component or package (e.g. Python SDK, TypeScript SDK, server, CLI)
+- Affected version, tag, or commit
+- Clear, step-by-step reproduction instructions
+- The security impact and a proof of concept, if available
+- Any suggested fix or mitigation
+- Whether an AI tool was involved in finding or writing up the report
+
+Reports generated by an AI tool are welcome, but only once you have run the
+reproduction yourself and confirmed the impact is real. A scan result or model
+output pasted in without that step is not a vulnerability report, and we close
+those without a detailed response so we can spend the time on real ones.
+
+## Response Process
+
+- We will acknowledge receipt of your report within **72 hours**.
+- We will work with you privately to confirm the issue and assess its impact.
+- Once a fix or mitigation is ready, we will coordinate a disclosure timeline
+  with you and credit you for the discovery, unless you prefer to remain anonymous.
+
+## Public Disclosure
+
+Please avoid sharing technical details of the vulnerability publicly until the
+maintainers have reviewed the issue and a fix or mitigation has been released. We
+are committed to resolving valid reports promptly and keeping you informed
+throughout the process.
+
+## Supported Versions
+
+We release security fixes against the latest published version of each package.
+Whenever possible, please reproduce the issue on the most recent release before
+reporting.

cli/README.md

@@ -60,9 +60,8 @@ mem0 delete <memory-id>
 | `mem0 entity` | List or delete entities (users, agents, apps, runs) |
 | `mem0 event` | Inspect background processing events (bulk deletes, large add jobs) |
 | `mem0 status` | Verify API connection and display current project |
-| `mem0 version` | Print the CLI version |
 
-Run `mem0 <command> --help` for detailed usage on any command.
+Run `mem0 <command> --help` for detailed usage on any command, or `mem0 --version` to print the CLI version.
 
 ## Agent mode
 

cli/cli-spec.json

@@ -207,7 +207,11 @@
         { "name": "immutable", "flags": ["--immutable"], "type": "boolean", "default": false, "help": "Prevent future updates." },
         { "name": "no_infer", "flags": ["--no-infer"], "type": "boolean", "default": false, "help": "Skip inference, store raw." },
         { "name": "expires", "flags": ["--expires"], "type": "string", "help": "Expiration date (YYYY-MM-DD)." },
-        { "name": "categories", "flags": ["--categories"], "type": "string", "help": "Categories (JSON array or comma-separated)." },
+        { "name": "categories", "flags": ["--categories"], "type": "string", "help": "Not supported on add, use --custom-categories instead." },
+        { "name": "custom_instructions", "flags": ["--custom-instructions"], "type": "string", "help": "Custom instructions for fact extraction." },
+        { "name": "custom_categories", "flags": ["--custom-categories"], "type": "string", "help": "Custom categories as a JSON array of {name: description} objects." },
+        { "name": "structured_data_schema", "flags": ["--structured-data-schema"], "type": "string", "help": "Schema for structured data extraction, as JSON." },
+        { "name": "timestamp", "flags": ["--timestamp"], "type": "integer", "help": "Unix timestamp for the memory." },
         { "name": "graph", "flags": ["--graph"], "type": "boolean", "default": false, "help": "Enable graph memory extraction.", "panel": "Scope" },
         { "name": "no_graph", "flags": ["--no-graph"], "type": "boolean", "default": false, "help": "Disable graph memory extraction.", "panel": "Scope" },
         { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "text", "help": "Output format: text, json, quiet.", "panel": "Output" }
@@ -244,6 +248,9 @@
         { "name": "keyword", "flags": ["--keyword"], "type": "boolean", "default": false, "help": "Use keyword search.", "panel": "Search" },
         { "name": "filter_json", "flags": ["--filter"], "type": "string", "help": "Advanced filter expression (JSON).", "panel": "Search" },
         { "name": "fields", "flags": ["--fields"], "type": "string", "help": "Specific fields to return (comma-separated).", "panel": "Search" },
+        { "name": "show_expired", "flags": ["--show-expired"], "type": "boolean", "default": false, "help": "Include expired memories.", "panel": "Search" },
+        { "name": "reference_date", "flags": ["--reference-date"], "type": "string", "help": "Reference date for relative queries (YYYY-MM-DD or unix timestamp).", "panel": "Search" },
+        { "name": "latest_only", "flags": ["--latest-only"], "type": "boolean", "default": false, "help": "Only return the latest version of each memory.", "panel": "Search" },
         { "name": "graph", "flags": ["--graph"], "type": "boolean", "default": false, "help": "Enable graph in search.", "panel": "Search" },
         { "name": "no_graph", "flags": ["--no-graph"], "type": "boolean", "default": false, "help": "Disable graph in search.", "panel": "Search" },
         { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "text", "help": "Output: text, json, table.", "panel": "Output" }
@@ -296,6 +303,8 @@
         { "name": "category", "flags": ["--category"], "type": "string", "help": "Filter by category.", "panel": "Filters" },
         { "name": "after", "flags": ["--after"], "type": "string", "help": "Created after (YYYY-MM-DD).", "panel": "Filters" },
         { "name": "before", "flags": ["--before"], "type": "string", "help": "Created before (YYYY-MM-DD).", "panel": "Filters" },
+        { "name": "show_expired", "flags": ["--show-expired"], "type": "boolean", "default": false, "help": "Include expired memories.", "panel": "Filters" },
+        { "name": "latest_only", "flags": ["--latest-only"], "type": "boolean", "default": false, "help": "Only return the latest version of each memory.", "panel": "Filters" },
         { "name": "graph", "flags": ["--graph"], "type": "boolean", "default": false, "help": "Enable graph in listing.", "panel": "Filters" },
         { "name": "no_graph", "flags": ["--no-graph"], "type": "boolean", "default": false, "help": "Disable graph in listing.", "panel": "Filters" },
         { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "table", "help": "Output: text, json, table.", "panel": "Output" }
@@ -329,6 +338,8 @@
       ],
       "options": [
         { "name": "metadata", "flags": ["--metadata", "-m"], "type": "string", "help": "Update metadata (JSON)." },
+        { "name": "expires", "flags": ["--expires"], "type": "string", "help": "Expiration date (YYYY-MM-DD)." },
+        { "name": "timestamp", "flags": ["--timestamp"], "type": "integer", "help": "Unix timestamp for the memory." },
         { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "text", "help": "Output: text, json, quiet.", "panel": "Output" }
       ],
       "apiEndpoint": "update"
@@ -356,6 +367,7 @@
         { "name": "all", "flags": ["--all"], "type": "boolean", "default": false, "help": "Delete all memories matching scope filters." },
         { "name": "entity", "flags": ["--entity"], "type": "boolean", "default": false, "help": "Delete the entity itself and all its memories (cascade)." },
         { "name": "project", "flags": ["--project"], "type": "boolean", "default": false, "help": "With --all: delete ALL memories project-wide." },
+        { "name": "delete_linked", "flags": ["--delete-linked"], "type": "boolean", "default": false, "help": "Also delete memories linked to this memory." },
         { "name": "dry_run", "flags": ["--dry-run"], "type": "boolean", "default": false, "help": "Show what would be deleted without deleting." },
         { "name": "force", "flags": ["--force"], "type": "boolean", "default": false, "help": "Skip confirmation." },
         { "name": "user_id", "flags": ["--user-id", "-u"], "type": "string", "help": "Scope to user.", "panel": "Scope" },
@@ -503,7 +515,7 @@
     },
     {
       "name": "init",
-      "description": "Setup wizard for mem0 CLI. Supports email login (--email) or manual API key (--api-key).",
+      "description": "Setup wizard for mem0 CLI. Supports Agent Mode bootstrap (--agent), email login (--email), or manual API key (--api-key).",
       "usage": "mem0 init [OPTIONS]",
       "needsBackend": false,
       "needsConfig": false,
@@ -516,7 +528,9 @@
         { "name": "user-id", "flags": ["-u", "--user-id"], "type": "string", "default": null, "help": "Default user ID (skip prompt)." },
         { "name": "email", "flags": ["--email"], "type": "string", "default": null, "help": "Login via email verification code." },
         { "name": "code", "flags": ["--code"], "type": "string", "default": null, "help": "Verification code (use with --email for non-interactive login)." },
-        { "name": "force", "flags": ["--force"], "type": "boolean", "default": false, "help": "Overwrite existing config without confirmation." }
+        { "name": "force", "flags": ["--force"], "type": "boolean", "default": false, "help": "Overwrite existing config without confirmation." },
+        { "name": "agent", "flags": ["--agent"], "type": "boolean", "default": false, "help": "Bootstrap an unattended Agent Mode account (no email required)." },
+        { "name": "source", "flags": ["--source"], "type": "string", "default": null, "help": "Channel attribution for signup (e.g. github, hn, ph)." }
       ]
     },
     {

cli/node/AGENTS.md

@@ -0,0 +1,41 @@
+# Node CLI (`cli/node/`)
+
+The `@mem0/cli` package on npm. Commander-based, entry point `mem0`.
+
+## Commands
+
+```bash
+pnpm install
+pnpm run build        # tsup (ESM)
+pnpm run lint         # biome check src/
+pnpm run lint:fix     # biome check --write src/
+pnpm run typecheck    # tsc --noEmit
+pnpm run test         # vitest run
+pnpm run test:watch
+pnpm run dev          # tsx src/index.ts
+```
+
+pnpm only. Never npm, never yarn.
+
+## Conventions
+
+> **Biome, not ESLint. vitest, not jest.** `mem0-ts/` uses Prettier + jest and
+> `integrations/vercel-ai-sdk/` uses ESLint + jest. Running those tools here produces
+> spurious diffs. Every toolchain in this repo is per-package.
+
+- **Node 18+** required.
+- **Build:** tsup, ESM output only.
+- **Linter and formatter:** Biome, configured in `biome.json`.
+- **Tests:** vitest.
+- **TypeScript strict mode.** ES module `import` syntax only, never `require()`.
+
+Run `pnpm run typecheck` after every change.
+
+## Dependencies
+
+Commander + Chalk + ora + cli-table3, and `mem0ai` (npm) for API calls.
+
+## CI and release
+
+- CI: `cli-node-ci.yml`, Biome + tsc + vitest + tsup build on Node 20 and 22.
+- Release: tag prefix `cli-node-v*` dispatches `cli-node-cd.yml`, publishing to npm over OIDC.

cli/node/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

cli/node/README.md

@@ -232,14 +232,6 @@ Verify your API connection and display the current project.
 mem0 status
 ```
 
-### `mem0 version`
-
-Print the CLI version.
-
-```bash
-mem0 version
-```
-
 ## Agent mode
 
 Pass `--agent` (or its alias `--json`) as a **global flag** on any command to get output designed for AI agent tool loops:
@@ -298,6 +290,8 @@ These flags are available on all commands:
 | `--base-url` | Override the configured API base URL for this request |
 | `-o, --output` | Set the output format |
 
+`mem0 --version` prints the CLI version. It is only valid before a subcommand, not after one.
+
 ## Environment variables
 
 | Variable | Description |

cli/node/development.md

@@ -51,7 +51,7 @@ pnpm link --global
 
 # Now use it like a normal CLI
 mem0 --help
-mem0 version
+mem0 --version
 ```
 
 > **Warning:** If you also have the Python CLI installed, both register the `mem0` command. The last one linked/installed wins. Unlink with `pnpm unlink --global`.

cli/node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mem0/cli",
-  "version": "0.2.3",
+  "version": "0.2.14",
   "description": "The official CLI for mem0 — the memory layer for AI agents",
   "type": "module",
   "bin": {
@@ -40,8 +40,19 @@
     "typescript": "^5.4.0",
     "tsup": "^8.0.0",
     "tsx": "^4.7.0",
-    "vitest": "^1.5.0",
+    "vite": "^6.0.0",
+    "vitest": "^4.1.11",
     "@biomejs/biome": "^1.7.0",
     "@types/node": "^20.0.0"
+  },
+  "pnpm": {
+    "overrides": {
+      "jws@4.0.0": "4.0.1",
+      "langsmith@<0.6.0": "^0.6.0",
+      "tar-fs@>=2.0.0 <2.1.4": "^2.1.4",
+      "picomatch@<2.3.2": "^2.3.2",
+      "esbuild": ">=0.28.1",
+      "postcss@<8.5.18": ">=8.5.18 <9.0.0"
+    }
   }
 }

cli/node/pnpm-workspace.yaml

@@ -0,0 +1,14 @@
+packages:
+  - '.'
+
+onlyBuiltDependencies:
+  - "@biomejs/biome"
+  - esbuild
+
+overrides:
+  jws@4.0.0: 4.0.1
+  langsmith@<0.6.0: ^0.6.0
+  tar-fs@>=2.0.0 <2.1.4: ^2.1.4
+  picomatch@<2.3.2: ^2.3.2
+  "esbuild": ">=0.28.1"
+  "postcss@<8.5.18": ">=8.5.18 <9.0.0"

cli/node/src/agent-detect.ts

@@ -0,0 +1,32 @@
+/**
+ * Detect whether the CLI is being invoked from inside an AI-agent context.
+ *
+ * Used by `mem0 init` to auto-enter Agent Mode (Rule 3 bootstrap) when an
+ * agent runtime env var is present. The return value is a context **trigger
+ * only** — the canonical agent identity is self-declared by the agent via
+ * `--agent-caller <name>` (Proof Editor-style) and never sniffed from env
+ * vars to fill the `agent_caller` field on the APIKey row.
+ *
+ * Returns a short name or null. Honest reporting depends on `--agent-caller`;
+ * this list is just enough to enable the zero-friction auto-bootstrap UX.
+ */
+
+const AGENT_CALLER_ENV: ReadonlyArray<readonly [string, readonly string[]]> = [
+	["claude-code", ["CLAUDECODE", "CLAUDE_CODE"]],
+	["cursor", ["CURSOR_AGENT", "CURSOR_SESSION_ID"]],
+	["codex", ["CODEX_CLI", "OPENAI_CODEX"]],
+	["cline", ["CLINE_AGENT", "CLINE"]],
+	["continue", ["CONTINUE_AGENT", "CONTINUE_SESSION"]],
+	["aider", ["AIDER_SESSION"]],
+	["goose", ["GOOSE_AGENT"]],
+	["windsurf", ["WINDSURF_AGENT"]],
+] as const;
+
+export function detectAgentCaller(): string | null {
+	for (const [name, envVars] of AGENT_CALLER_ENV) {
+		if (envVars.some((v) => process.env[v])) {
+			return name;
+		}
+	}
+	return null;
+}

cli/node/src/backend/base.ts

@@ -14,8 +14,11 @@ export interface AddOptions {
 	immutable?: boolean;
 	infer?: boolean;
 	expires?: string;
-	categories?: string[];
-	enableGraph?: boolean;
+	customInstructions?: string;
+	agentCustomInstructions?: string;
+	customCategories?: Record<string, string>[];
+	structuredDataSchema?: Record<string, unknown>;
+	timestamp?: number;
 }
 
 export interface SearchOptions {
@@ -29,7 +32,9 @@ export interface SearchOptions {
 	keyword?: boolean;
 	filters?: Record<string, unknown>;
 	fields?: string[];
-	enableGraph?: boolean;
+	showExpired?: boolean;
+	referenceDate?: string | number;
+	latestOnly?: boolean;
 }
 
 export interface ListOptions {
@@ -42,7 +47,8 @@ export interface ListOptions {
 	category?: string;
 	after?: string;
 	before?: string;
-	enableGraph?: boolean;
+	showExpired?: boolean;
+	latestOnly?: boolean;
 }
 
 export interface DeleteOptions {
@@ -51,6 +57,12 @@ export interface DeleteOptions {
 	agentId?: string;
 	appId?: string;
 	runId?: string;
+	deleteLinked?: boolean;
+}
+
+export interface UpdateOptions {
+	expirationDate?: string;
+	timestamp?: number;
 }
 
 export interface EntityIds {
@@ -80,6 +92,7 @@ export interface Backend {
 		memoryId: string,
 		content?: string,
 		metadata?: Record<string, unknown>,
+		opts?: UpdateOptions,
 	): Promise<Record<string, unknown>>;
 
 	delete(

cli/node/src/backend/platform.ts

@@ -3,7 +3,7 @@
  */
 
 import type { PlatformConfig } from "../config.js";
-import { isAgentMode } from "../state.js";
+import { captureNotice, isAgentMode } from "../state.js";
 import { CLI_VERSION } from "../version.js";
 import {
 	APIError,
@@ -15,8 +15,13 @@ import {
 	type ListOptions,
 	NotFoundError,
 	type SearchOptions,
+	type UpdateOptions,
 } from "./base.js";
 
+function encodePathSegment(value: unknown): string {
+	return encodeURIComponent(String(value));
+}
+
 export class PlatformBackend implements Backend {
 	private baseUrl: string;
 	private headers: Record<string, string>;
@@ -26,7 +31,8 @@ export class PlatformBackend implements Backend {
 		this.headers = {
 			Authorization: `Token ${config.apiKey}`,
 			"Content-Type": "application/json",
-			"X-Mem0-Source": "cli",
+			"X-Mem0-Source": "CLI",
+			"X-Mem0-Client": `mem0-cli-node/${CLI_VERSION}`,
 			"X-Mem0-Client-Language": "node",
 			"X-Mem0-Client-Version": CLI_VERSION,
 		};
@@ -90,7 +96,39 @@ export class PlatformBackend implements Backend {
 		if (resp.status === 204) {
 			return {};
 		}
-		return resp.json();
+
+		const data = await resp.json();
+
+		// Pull the unclaimed-Agent-Mode notice out of the body (or the header
+		// fallback for endpoints returning non-dict / non-dict-leading payloads)
+		// and stash for end-of-command surfacing.
+		let notice: string | null = null;
+		if (
+			data &&
+			typeof data === "object" &&
+			!Array.isArray(data) &&
+			"mem0_notice" in data
+		) {
+			notice = (data as Record<string, unknown>).mem0_notice as string;
+			// biome-ignore lint/performance/noDelete: intentional strip so downstream consumers don't see duplicate notice
+			delete (data as Record<string, unknown>).mem0_notice;
+		} else if (
+			Array.isArray(data) &&
+			data.length > 0 &&
+			typeof data[0] === "object" &&
+			data[0] !== null &&
+			"mem0_notice" in data[0]
+		) {
+			notice = (data[0] as Record<string, unknown>).mem0_notice as string;
+			// biome-ignore lint/performance/noDelete: see above.
+			delete (data[0] as Record<string, unknown>).mem0_notice;
+		}
+		if (!notice) {
+			notice = resp.headers.get("X-Mem0-Notice-Message") ?? null;
+		}
+		captureNotice(notice);
+
+		return data;
 	}
 
 	async add(
@@ -114,11 +152,18 @@ export class PlatformBackend implements Backend {
 		if (opts.immutable) payload.immutable = true;
 		if (opts.infer === false) payload.infer = false;
 		if (opts.expires) payload.expiration_date = opts.expires;
-		if (opts.categories) payload.categories = opts.categories;
-		if (opts.enableGraph) payload.enable_graph = true;
+		if (opts.customInstructions)
+			payload.custom_instructions = opts.customInstructions;
+		if (opts.agentCustomInstructions)
+			payload.agent_custom_instructions = opts.agentCustomInstructions;
+		if (opts.customCategories)
+			payload.custom_categories = opts.customCategories;
+		if (opts.structuredDataSchema)
+			payload.structured_data_schema = opts.structuredDataSchema;
+		if (opts.timestamp !== undefined) payload.timestamp = opts.timestamp;
 		payload.source = "CLI";
 
-		return (await this._request("POST", "/v1/memories/", {
+		return (await this._request("POST", "/v3/memories/add/", {
 			json: payload,
 		})) as Record<string, unknown>;
 	}
@@ -176,10 +221,13 @@ export class PlatformBackend implements Backend {
 		if (opts.rerank) payload.rerank = true;
 		if (opts.keyword) payload.keyword_search = true;
 		if (opts.fields) payload.fields = opts.fields;
-		if (opts.enableGraph) payload.enable_graph = true;
+		if (opts.showExpired) payload.show_expired = true;
+		if (opts.referenceDate !== undefined)
+			payload.reference_date = opts.referenceDate;
+		if (opts.latestOnly) payload.latest_only = true;
 		payload.source = "CLI";
 
-		const result = (await this._request("POST", "/v2/memories/search/", {
+		const result = (await this._request("POST", "/v3/memories/search/", {
 			json: payload,
 		})) as unknown;
 		if (Array.isArray(result)) return result;
@@ -188,9 +236,13 @@ export class PlatformBackend implements Backend {
 	}
 
 	async get(memoryId: string): Promise<Record<string, unknown>> {
-		return (await this._request("GET", `/v1/memories/${memoryId}/`, {
-			params: { source: "CLI" },
-		})) as Record<string, unknown>;
+		return (await this._request(
+			"GET",
+			`/v1/memories/${encodePathSegment(memoryId)}/`,
+			{
+				params: { source: "CLI" },
+			},
+		)) as Record<string, unknown>;
 	}
 
 	async listMemories(
@@ -227,10 +279,11 @@ export class PlatformBackend implements Backend {
 			extraFilters: Object.keys(extra).length > 0 ? extra : undefined,
 		});
 		if (apiFilters) payload.filters = apiFilters;
-		if (opts.enableGraph) payload.enable_graph = true;
+		if (opts.showExpired) payload.show_expired = true;
+		if (opts.latestOnly) payload.latest_only = true;
 		payload.source = "CLI";
 
-		const result = (await this._request("POST", "/v2/memories/", {
+		const result = (await this._request("POST", "/v3/memories/", {
 			json: payload,
 			params,
 		})) as unknown;
@@ -243,14 +296,21 @@ export class PlatformBackend implements Backend {
 		memoryId: string,
 		content?: string,
 		metadata?: Record<string, unknown>,
+		opts: UpdateOptions = {},
 	): Promise<Record<string, unknown>> {
 		const payload: Record<string, unknown> = {};
 		if (content) payload.text = content;
 		if (metadata) payload.metadata = metadata;
+		if (opts.expirationDate) payload.expiration_date = opts.expirationDate;
+		if (opts.timestamp !== undefined) payload.timestamp = opts.timestamp;
 		payload.source = "CLI";
-		return (await this._request("PUT", `/v1/memories/${memoryId}/`, {
-			json: payload,
-		})) as Record<string, unknown>;
+		return (await this._request(
+			"PUT",
+			`/v1/memories/${encodePathSegment(memoryId)}/`,
+			{
+				json: payload,
+			},
+		)) as Record<string, unknown>;
 	}
 
 	async delete(
@@ -268,9 +328,13 @@ export class PlatformBackend implements Backend {
 			})) as Record<string, unknown>;
 		}
 		if (memoryId) {
-			return (await this._request("DELETE", `/v1/memories/${memoryId}/`, {
-				params: { source: "CLI" },
-			})) as Record<string, unknown>;
+			const params: Record<string, string> = { source: "CLI" };
+			if (opts.deleteLinked) params.delete_linked = "true";
+			return (await this._request(
+				"DELETE",
+				`/v1/memories/${encodePathSegment(memoryId)}/`,
+				{ params },
+			)) as Record<string, unknown>;
 		}
 		throw new Error("Either memoryId or --all is required");
 	}
@@ -287,16 +351,18 @@ export class PlatformBackend implements Backend {
 		if (entities.length === 0) {
 			throw new Error("At least one entity ID is required for deleteEntities.");
 		}
-		// Delete each provided entity via the v2 path-based endpoint
-		let result: Record<string, unknown> = {};
+		// Delete each provided entity via the v2 path-based endpoint. Key each
+		// response by entity type so a multi-entity delete (e.g. --user-id and
+		// --agent-id together) doesn't discard everything but the last result.
+		const results: Record<string, unknown> = {};
 		for (const [entityType, entityId] of entities) {
-			result = (await this._request(
+			results[entityType] = (await this._request(
 				"DELETE",
-				`/v2/entities/${entityType}/${entityId}/`,
+				`/v2/entities/${encodePathSegment(entityType)}/${encodePathSegment(entityId)}/`,
 				{ params: { source: "CLI" } },
 			)) as Record<string, unknown>;
 		}
-		return result;
+		return results;
 	}
 
 	async ping(): Promise<Record<string, unknown>> {
@@ -355,9 +421,9 @@ export class PlatformBackend implements Backend {
 	}
 
 	async getEvent(eventId: string): Promise<Record<string, unknown>> {
-		return (await this._request("GET", `/v1/event/${eventId}/`)) as Record<
-			string,
-			unknown
-		>;
+		return (await this._request(
+			"GET",
+			`/v1/event/${encodePathSegment(eventId)}/`,
+		)) as Record<string, unknown>;
 	}
 }

cli/node/src/branding.ts

@@ -96,7 +96,7 @@ export function printError(message: string, hint?: string): void {
 	const resolvedHint =
 		hint ??
 		(message.includes("Authentication failed")
-			? `Run ${brand("mem0 init")} to reconfigure your API key · https://app.mem0.ai/dashboard/api-keys`
+			? `Run ${brand("mem0 init")} to reconfigure your API key · https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-node`
 			: undefined);
 	if (resolvedHint) {
 		console.error(`  ${dim(resolvedHint)}`);

cli/node/src/commands/agent-mode.ts

@@ -0,0 +1,285 @@
+/**
+ * Agent Mode commands — bootstrap (unattended signup) and OTP-based claim.
+ */
+
+import readline from "node:readline";
+import { colors, printError, printInfo, printSuccess } from "../branding.js";
+import { type Mem0Config, saveConfig } from "../config.js";
+
+const { brand, dim } = colors;
+
+const SOURCE_HEADERS = {
+	"X-Mem0-Source": "cli",
+	"X-Mem0-Client-Language": "node",
+} as const;
+
+export interface BootstrapEnvelope {
+	api_key: string;
+	default_user_id: string;
+	org_id: string;
+	project_id: string;
+	mcp_url?: string;
+	smoke_test_url?: string;
+	claim_command?: string;
+	mem0_notice?: string;
+}
+
+function isValidEnvelope(v: unknown): v is BootstrapEnvelope {
+	return (
+		!!v &&
+		typeof v === "object" &&
+		typeof (v as BootstrapEnvelope).api_key === "string" &&
+		(v as BootstrapEnvelope).api_key.length > 0 &&
+		typeof (v as BootstrapEnvelope).default_user_id === "string" &&
+		(v as BootstrapEnvelope).default_user_id.length > 0
+	);
+}
+
+/**
+ * POST /api/v1/auth/agent_mode/ and mutate config in place.
+ *
+ * @param config - Mem0Config mutated in place with the new platform values.
+ * @param source - `--source` flag passthrough (analytics tag, free-form).
+ * @param agentCaller - Self-declared agent identity passed via `--agent-caller`
+ *   (e.g. `claude-code`, `cursor`). May be null when the caller omitted the
+ *   flag; the agent can backfill later via `mem0 identify <name>`. Sent to the
+ *   backend in the request body and saved into `platform.agentCaller` for
+ *   local introspection.
+ */
+export async function bootstrapViaBackend(
+	config: Mem0Config,
+	{
+		source,
+		agentCaller,
+	}: { source?: string | null; agentCaller?: string | null } = {},
+): Promise<void> {
+	const baseUrl = (config.platform.baseUrl || "https://api.mem0.ai").replace(
+		/\/+$/,
+		"",
+	);
+	const body: Record<string, unknown> = {};
+	if (source) body.source = source;
+	if (agentCaller) body.agent_caller = agentCaller;
+
+	let resp: Response;
+	try {
+		resp = await fetch(`${baseUrl}/api/v1/auth/agent_mode/`, {
+			method: "POST",
+			headers: {
+				...SOURCE_HEADERS,
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify(body),
+			signal: AbortSignal.timeout(30_000),
+		});
+	} catch (err) {
+		printError(
+			`Network error contacting Mem0: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		process.exit(1);
+	}
+
+	if (resp.status === 429) {
+		printError("Rate-limited. Try again in a few minutes.");
+		process.exit(1);
+	}
+	if (resp.status === 503) {
+		printError("Agent Mode is temporarily disabled. Try again later.");
+		process.exit(1);
+	}
+	if (!resp.ok) {
+		let detail: string = resp.statusText;
+		try {
+			const errBody = (await resp.json()) as {
+				error?: string;
+				detail?: string;
+			};
+			detail = errBody.error ?? errBody.detail ?? resp.statusText;
+		} catch {
+			/* leave detail as statusText */
+		}
+		// Backend's @ratelimit decorator raises PermissionDenied, which DRF
+		// translates to a generic 403 "You do not have permission to perform
+		// this action." That's opaque — surface it as the rate-limit message
+		// it actually is.
+		if (resp.status === 403 && /permission/i.test(detail)) {
+			printError(
+				"Daily Agent Mode signup limit reached for this network (5/day). Try again from a different IP or after midnight UTC.",
+			);
+			process.exit(1);
+		}
+		printError(`Bootstrap failed: ${detail}`);
+		process.exit(1);
+	}
+
+	const envelope = (await resp.json()) as BootstrapEnvelope;
+	if (!isValidEnvelope(envelope)) {
+		// Defend against partial/malformed backend responses (e.g. {api_key: null}).
+		// Without this guard, the typed `string` field is silently set to
+		// undefined/null and persisted, producing confusing downstream errors.
+		printError(
+			"Bootstrap response missing required fields — please update the CLI.",
+		);
+		process.exit(1);
+	}
+
+	config.platform.apiKey = envelope.api_key;
+	config.platform.baseUrl = baseUrl;
+	config.platform.agentMode = true;
+	config.platform.createdVia = "agent_mode";
+	config.platform.agentCaller = agentCaller ?? "";
+	config.platform.claimedAt = "";
+	config.platform.defaultUserId = envelope.default_user_id;
+	// Adopt the slug-derived user_id as the default scope for memory ops.
+	config.defaults.userId = envelope.default_user_id;
+	saveConfig(config);
+
+	printSuccess(
+		`Agent Mode active. Default user_id: ${envelope.default_user_id}`,
+	);
+	if (envelope.mem0_notice) {
+		console.log(`\n\x1b[33m🔔 ${envelope.mem0_notice}\x1b[0m\n`);
+	} else {
+		// Fallback for older backends without the unified notice field.
+		const claimCmd = envelope.claim_command ?? "mem0 init --email <your-email>";
+		console.log(`  ${dim(`To claim this account later: ${claimCmd}`)}`);
+	}
+
+	if (!agentCaller) {
+		console.log(
+			`  ${dim("If you are an AI agent, identify yourself: `mem0 identify <your-name>` (e.g. claude-code, cursor).")}`,
+		);
+	}
+}
+
+/**
+ * Claim an existing Agent Mode account via OTP — no browser, no polling.
+ *
+ * Hits /api/v1/auth/email_code/ to send a verification code, prompts for it
+ * interactively (or accepts via `code`), then sends it to /verify/ alongside
+ * `agent_mode_api_key`. Backend's verify_email_code runs upgrade-in-place
+ * inline and returns the claim result.
+ */
+export async function claimViaOtp(
+	config: Mem0Config,
+	{ email, code }: { email: string; code?: string },
+): Promise<void> {
+	const baseUrl = (config.platform.baseUrl || "https://api.mem0.ai").replace(
+		/\/+$/,
+		"",
+	);
+	if (!config.platform.apiKey || !config.platform.agentMode) {
+		printError(
+			"This command requires an active Agent Mode config. Run `mem0 init` first.",
+		);
+		process.exit(1);
+	}
+
+	const rawKey = config.platform.apiKey;
+
+	// Step 1: request OTP (unless --code was supplied)
+	if (!code) {
+		const sendResp = await fetch(`${baseUrl}/api/v1/auth/email_code/`, {
+			method: "POST",
+			headers: { ...SOURCE_HEADERS, "Content-Type": "application/json" },
+			body: JSON.stringify({ email }),
+			signal: AbortSignal.timeout(30_000),
+		});
+		if (sendResp.status === 429) {
+			printError("Too many attempts. Try again in a few minutes.");
+			process.exit(1);
+		}
+		if (!sendResp.ok) {
+			let detail: string = sendResp.statusText;
+			try {
+				const errBody = (await sendResp.json()) as { error?: string };
+				if (errBody.error) detail = errBody.error;
+			} catch {
+				/* leave as statusText */
+			}
+			printError(`Failed to send code: ${detail}`);
+			process.exit(1);
+		}
+
+		printSuccess(`Verification code sent to ${email}. Check your inbox.`);
+
+		if (!process.stdin.isTTY) {
+			printError(
+				"No --code provided and terminal is non-interactive.",
+				`Re-run: mem0 init --email ${email} --code <code>`,
+			);
+			process.exit(1);
+		}
+
+		console.log();
+		code = await promptLine(`  ${brand("Verification Code")}`);
+		if (!code) {
+			printError("Code is required.");
+			process.exit(1);
+		}
+	}
+
+	// Step 2: verify + claim atomically
+	const verifyResp = await fetch(`${baseUrl}/api/v1/auth/email_code/verify/`, {
+		method: "POST",
+		headers: { ...SOURCE_HEADERS, "Content-Type": "application/json" },
+		body: JSON.stringify({
+			email,
+			code: code.trim(),
+			agent_mode_api_key: rawKey,
+		}),
+		signal: AbortSignal.timeout(30_000),
+	});
+
+	if (!verifyResp.ok) {
+		let detail: string = verifyResp.statusText;
+		let errCode = "";
+		try {
+			const errBody = (await verifyResp.json()) as {
+				error?: string;
+				code?: string;
+			};
+			if (errBody.error) detail = errBody.error;
+			if (errBody.code) errCode = errBody.code;
+		} catch {
+			/* leave as statusText */
+		}
+		printError(`Claim failed: ${detail}`);
+		if (errCode === "email_already_claimed") {
+			console.log(
+				`  ${dim("Tip: this email already has a Mem0 account. Sign in at app.mem0.ai with your existing credentials.")}`,
+			);
+		}
+		process.exit(1);
+	}
+
+	const claimBody = (await verifyResp.json()) as {
+		claimed?: boolean;
+		claimed_at?: string;
+	};
+	if (!claimBody.claimed) {
+		printError(`Unexpected verify response: ${JSON.stringify(claimBody)}`);
+		process.exit(1);
+	}
+
+	config.platform.agentMode = false;
+	config.platform.claimedAt = claimBody.claimed_at ?? new Date().toISOString();
+	config.platform.userEmail = email;
+	config.platform.createdVia = "email";
+	saveConfig(config);
+
+	printSuccess(`Agent claimed to ${email}. Your API key is unchanged.`);
+}
+
+function promptLine(label: string): Promise<string> {
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+	return new Promise((resolve) => {
+		rl.question(`${label}: `, (answer) => {
+			rl.close();
+			resolve(answer.trim());
+		});
+	});
+}

cli/node/src/commands/agent-rush.ts

@@ -0,0 +1,147 @@
+/**
+ * `mem0 agent-rush <add|search> "..."` — wraps the AGENTRUSH platform endpoints.
+ * Project routing is implicit (server-side); zero flags needed.
+ */
+
+import readline from "node:readline";
+import { colors, printError, printSuccess } from "../branding.js";
+import { loadConfig, saveConfig } from "../config.js";
+import { CLI_VERSION } from "../version.js";
+
+const PII_WARNING = [
+	"",
+	"⚠️  AGENTRUSH memories are PUBLIC — visible to any other player.",
+	"   Do not include real names, emails, secrets, work content, or PII.",
+	"",
+].join("\n");
+
+const ERROR_HINTS: Record<string, string> = {
+	agentrush_search_first:
+		"Run 3 'mem0 agent-rush search' commands before adding.",
+	agentrush_search_quota: "You've used your 3 lifetime searches.",
+	agentrush_add_quota: "You've used your 3 lifetime adds.",
+	agentrush_not_agent_mode:
+		"Re-run 'mem0 init --agent' to bootstrap an agent-mode key.",
+	agentrush_length: "Memory text must be 50-1000 characters.",
+	agentrush_no_urls: "URLs are not allowed.",
+	agentrush_blocklist: "Content contains a blocked term.",
+	agentrush_global_quota: "Event-wide cap reached. Try again later.",
+	agentrush_not_provisioned:
+		"AGENTRUSH is not provisioned in this environment.",
+};
+
+async function callEndpoint(
+	path: string,
+	body: Record<string, unknown>,
+): Promise<unknown> {
+	const config = loadConfig();
+	const baseUrl = (config.platform?.baseUrl ?? "https://api.mem0.ai").replace(
+		/\/+$/,
+		"",
+	);
+
+	if (!config.platform?.apiKey) {
+		printError("Not initialized. Run `mem0 init --agent` first.");
+		process.exit(1);
+	}
+
+	const resp = await fetch(`${baseUrl}${path}`, {
+		method: "POST",
+		headers: {
+			Authorization: `Token ${config.platform.apiKey}`,
+			"Content-Type": "application/json",
+			"X-Mem0-Source": "cli",
+			"X-Mem0-Client-Language": "node",
+			"X-Mem0-Client-Version": CLI_VERSION,
+			"X-Mem0-Mode": "agent-rush",
+		},
+		body: JSON.stringify(body),
+		signal: AbortSignal.timeout(30_000),
+	});
+
+	const json = await resp.json().catch(() => ({}));
+
+	if (!resp.ok) {
+		const code =
+			(json as { error?: { code?: string } }).error?.code ?? "unknown";
+		printError(`AGENTRUSH error: ${code}`);
+		if (ERROR_HINTS[code]) {
+			console.log(`  ${colors.dim(ERROR_HINTS[code])}`);
+		}
+		process.exit(1);
+	}
+
+	return json;
+}
+
+function promptLine(question: string): Promise<string> {
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+	return new Promise((resolve) => {
+		rl.question(question, (answer) => {
+			rl.close();
+			resolve(answer.trim());
+		});
+	});
+}
+
+/**
+ * Ensure the human has acknowledged that AGENTRUSH memories are PUBLIC.
+ *
+ * Interactive (TTY): show the prompt; on "y" persist `agentRush.acknowledgedAt`
+ * so we never ask the same machine twice. On anything else, abort.
+ *
+ * Non-interactive (agent invocation, no TTY): print the warning to stderr
+ * for the human reading the agent's transcript and proceed — agents can't
+ * answer y/N prompts.
+ */
+async function ensureWarningAcknowledged(): Promise<void> {
+	const config = loadConfig();
+	if (config.agentRush?.acknowledgedAt) return;
+
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		// Agent context: surface the warning to stderr, don't block.
+		console.error(PII_WARNING);
+		return;
+	}
+
+	console.log(PII_WARNING);
+	const answer = (await promptLine("   Continue? [y/N]: ")).toLowerCase();
+	if (answer !== "y" && answer !== "yes") {
+		printError("Aborted.");
+		process.exit(1);
+	}
+
+	config.agentRush.acknowledgedAt = new Date().toISOString();
+	saveConfig(config);
+}
+
+export async function cmdAgentRushAdd(content: string): Promise<void> {
+	await ensureWarningAcknowledged();
+	const result = await callEndpoint("/v1/agent-rush/memories/", { content });
+	printSuccess(
+		`Memory submitted (event_id: ${(result as { event_id?: string }).event_id ?? "?"})`,
+	);
+}
+
+export async function cmdAgentRushSearch(query: string): Promise<void> {
+	const result = (await callEndpoint("/v1/agent-rush/memories/search/", {
+		query,
+	})) as {
+		results?: Array<{ memory?: string }>;
+		memories?: Array<{ memory?: string }>;
+	};
+
+	const memories = result.results ?? result.memories ?? [];
+
+	if (memories.length === 0) {
+		console.log(colors.dim("(no results)"));
+		return;
+	}
+
+	memories.slice(0, 5).forEach((m, i) => {
+		console.log(`  ${i + 1}. ${m.memory ?? JSON.stringify(m)}`);
+	});
+}

cli/node/src/commands/config.ts

@@ -29,7 +29,6 @@ export function cmdConfigShow(opts: { output?: string } = {}): void {
 					agent_id: config.defaults.agentId || null,
 					app_id: config.defaults.appId || null,
 					run_id: config.defaults.runId || null,
-					enable_graph: config.defaults.enableGraph,
 				},
 				platform: {
 					api_key: redactKey(config.platform.apiKey),
@@ -56,7 +55,6 @@ export function cmdConfigShow(opts: { output?: string } = {}): void {
 	]);
 	table.push(["defaults.app_id", config.defaults.appId || dim("(not set)")]);
 	table.push(["defaults.run_id", config.defaults.runId || dim("(not set)")]);
-	table.push(["defaults.enable_graph", String(config.defaults.enableGraph)]);
 	table.push(["", ""]);
 
 	// Platform

cli/node/src/commands/identify.ts

@@ -0,0 +1,75 @@
+/**
+ * mem0 identify — declare which agent owns the current agent-mode key.
+ *
+ * Used when `mem0 init --agent` ran without --agent-caller, so the backend
+ * saved agent_caller=NULL. The agent re-runs `mem0 identify <name>` to PATCH
+ * its own row with its real identity. Idempotent.
+ */
+
+import { printError, printSuccess } from "../branding.js";
+import { loadConfig, saveConfig } from "../config.js";
+
+const SOURCE_HEADERS = {
+	"X-Mem0-Source": "cli",
+	"X-Mem0-Client-Language": "node",
+} as const;
+
+export async function runIdentify(name: string): Promise<void> {
+	const config = loadConfig();
+	if (!config.platform.apiKey) {
+		printError("No API key configured. Run `mem0 init --agent` first.");
+		process.exit(1);
+	}
+	if (!config.platform.agentMode) {
+		printError("This command only works on unclaimed agent-mode keys.");
+		process.exit(1);
+	}
+
+	const clean = (name ?? "").trim();
+	if (!clean) {
+		printError("Agent name is required.");
+		process.exit(1);
+	}
+
+	const baseUrl = (config.platform.baseUrl || "https://api.mem0.ai").replace(
+		/\/+$/,
+		"",
+	);
+
+	let resp: Response;
+	try {
+		resp = await fetch(`${baseUrl}/api/v1/auth/agent_mode/caller/`, {
+			method: "PATCH",
+			headers: {
+				...SOURCE_HEADERS,
+				Authorization: `Token ${config.platform.apiKey}`,
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify({ agent_caller: clean }),
+			signal: AbortSignal.timeout(30_000),
+		});
+	} catch (err) {
+		printError(
+			`Network error: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		process.exit(1);
+	}
+
+	if (!resp.ok) {
+		let detail: string = resp.statusText;
+		try {
+			const body = (await resp.json()) as { error?: string };
+			if (body.error) detail = body.error;
+		} catch {
+			/* leave as statusText */
+		}
+		printError(`Identify failed: ${detail}`);
+		process.exit(1);
+	}
+
+	const body = (await resp.json()) as { agent_caller?: string };
+	const canonical = body.agent_caller ?? clean;
+	config.platform.agentCaller = canonical;
+	saveConfig(config);
+	printSuccess(`Identified as ${canonical}.`);
+}

cli/node/src/commands/init.ts

@@ -21,6 +21,8 @@ import {
 	redactKey,
 	saveConfig,
 } from "../config.js";
+import { formatJsonEnvelope } from "../output.js";
+import { isAgentMode } from "../state.js";
 
 const { brand, dim } = colors;
 
@@ -33,6 +35,65 @@ function validateEmail(email: string): void {
 	}
 }
 
+/** @internal — exported for unit tests. */
+export async function pingKey(
+	apiKey: string,
+	baseUrl: string,
+	timeoutMs = 5000,
+): Promise<boolean> {
+	// Returns false ONLY on a definitive "invalid key" signal (HTTP 401/403).
+	// Network errors, timeouts, and 5xx responses return true so we prefer
+	// reusing an existing key over silently minting a new shadow on a transient
+	// blip (which would also clobber config + plugin-sync targets).
+	try {
+		const resp = await fetch(`${baseUrl.replace(/\/+$/, "")}/v1/ping/`, {
+			headers: { Authorization: `Token ${apiKey}` },
+			signal: AbortSignal.timeout(timeoutMs),
+		});
+		return resp.status !== 401 && resp.status !== 403;
+	} catch {
+		return true; // unknown — prefer reuse
+	}
+}
+
+async function maybeIdentify(
+	key: string,
+	baseUrl: string,
+	agentCaller: string | undefined,
+): Promise<void> {
+	// Best-effort PATCH agent_caller when --agent-caller is supplied on a
+	// reused key. Silent no-op on any failure — reuse must not break.
+	if (!agentCaller) return;
+	try {
+		const resp = await fetch(
+			`${baseUrl.replace(/\/+$/, "")}/api/v1/auth/agent_mode/caller/`,
+			{
+				method: "PATCH",
+				headers: {
+					Authorization: `Token ${key}`,
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({ agent_caller: agentCaller }),
+				signal: AbortSignal.timeout(10_000),
+			},
+		);
+		if (resp.ok) {
+			try {
+				const body = (await resp.json()) as { agent_caller?: string };
+				if (fs.existsSync(CONFIG_FILE)) {
+					const cfg = loadConfig();
+					cfg.platform.agentCaller = body.agent_caller ?? agentCaller;
+					saveConfig(cfg);
+				}
+			} catch {
+				/* swallow — best effort */
+			}
+		}
+	} catch {
+		/* swallow — best effort */
+	}
+}
+
 async function emailLogin(
 	email: string,
 	code: string | undefined,
@@ -185,7 +246,7 @@ function promptLine(label: string, defaultValue?: string): Promise<string> {
 async function setupPlatform(config: Mem0Config): Promise<void> {
 	console.log();
 	console.log(
-		`  ${dim("Get your API key at https://app.mem0.ai/dashboard/api-keys")}`,
+		`  ${dim("Get your API key at https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-node")}`,
 	);
 	console.log();
 
@@ -196,6 +257,7 @@ async function setupPlatform(config: Mem0Config): Promise<void> {
 		process.exit(1);
 	}
 	config.platform.apiKey = apiKey;
+	config.platform.createdVia = "api_key";
 }
 
 async function setupDefaults(config: Mem0Config): Promise<void> {
@@ -234,7 +296,7 @@ async function validatePlatform(config: Mem0Config): Promise<void> {
 		} else {
 			printError(
 				`Could not connect: ${status.error ?? "Unknown error"}`,
-				"Visit https://app.mem0.ai/dashboard/api-keys to get a new key, or run mem0 init again.",
+				"Visit https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-node to get a new key, or run mem0 init again.",
 			);
 		}
 	} catch (e) {
@@ -249,14 +311,35 @@ export async function runInit(
 		email?: string;
 		code?: string;
 		force?: boolean;
+		agent?: boolean;
+		source?: string;
+		agentCaller?: string;
 	} = {},
 ): Promise<void> {
+	const { detectAgentCaller } = await import("../agent-detect.js");
+	const { bootstrapViaBackend, claimViaOtp } = await import("./agent-mode.js");
+	const { isAgentMode } = await import("../state.js");
+	const { captureEvent } = await import("../telemetry.js");
+
+	const fireInit = (
+		mode: "agent" | "email" | "api_key" | "existing_key",
+		claimed = false,
+	) => {
+		const props: Record<string, unknown> = { command: "init", mode };
+		// Self-declared via --agent-caller; not sniffed from env vars.
+		if (opts.agentCaller) props.agent_caller = opts.agentCaller;
+		if (opts.source) props.signup_source = opts.source;
+		if (claimed) props.claimed_agent_mode = true;
+		captureEvent("cli.init", props);
+	};
+
 	const config = createDefaultConfig();
 	const savedConfig = loadConfig();
 	const baseUrl =
 		process.env.MEM0_BASE_URL ||
 		savedConfig.platform.baseUrl ||
 		DEFAULT_BASE_URL;
+	config.platform.baseUrl = baseUrl;
 
 	// Guards
 	if (opts.code && !opts.email) {
@@ -268,6 +351,84 @@ export async function runInit(
 		process.exit(1);
 	}
 
+	// ── Claim flow: --email against an existing agent-mode config ───────────
+	if (
+		opts.email &&
+		fs.existsSync(CONFIG_FILE) &&
+		savedConfig.platform.agentMode &&
+		savedConfig.platform.apiKey
+	) {
+		const email = opts.email.trim().toLowerCase();
+		validateEmail(email);
+		printInfo(`Claiming Agent Mode account to ${email}...`);
+		await claimViaOtp(savedConfig, { email, code: opts.code });
+		fireInit("email", true);
+		return;
+	}
+
+	// ── Agent Mode path runs BEFORE the existing-config guard ──────────────
+	// Rule 1/2 will REUSE a valid existing key (not overwrite), so we must
+	// short-circuit before the guard prompts the user about overwriting.
+	// Rule 3 only mints when there's no valid key to reuse — in that case
+	// overwriting is what the user wants.
+	const agentCtx =
+		opts.agent === true || isAgentMode() || detectAgentCaller() !== null;
+	if (!opts.apiKey && !opts.email && agentCtx) {
+		const emitReuseEnvelope = (source: "env" | "config") => {
+			if (isAgentMode()) {
+				formatJsonEnvelope({
+					command: "init",
+					data: {
+						api_key_saved: false,
+						api_key_source: source,
+						agent_mode: false,
+						message:
+							"Existing Mem0 API key found and reused. No Agent Mode key was created.",
+					},
+				});
+			} else {
+				printSuccess(
+					source === "env"
+						? "Existing MEM0_API_KEY is valid; reusing it. No new Agent Mode key was minted."
+						: "Existing API key in config is valid; reusing it. No new Agent Mode key was minted.",
+				);
+			}
+		};
+		// Rule 1: env MEM0_API_KEY valid → reuse, no new key.
+		const envKey = (process.env.MEM0_API_KEY || "").trim();
+		if (envKey && (await pingKey(envKey, baseUrl))) {
+			await maybeIdentify(envKey, baseUrl, opts.agentCaller);
+			emitReuseEnvelope("env");
+			fireInit("existing_key");
+			return;
+		}
+		// Rule 2: existing config api_key valid → reuse.
+		if (
+			savedConfig.platform.apiKey &&
+			(await pingKey(savedConfig.platform.apiKey, baseUrl))
+		) {
+			await maybeIdentify(
+				savedConfig.platform.apiKey,
+				baseUrl,
+				opts.agentCaller,
+			);
+			emitReuseEnvelope("config");
+			fireInit("existing_key");
+			return;
+		}
+		// Rule 3: mint a fresh shadow (no valid key to reuse).
+		// agent_caller is self-declared via --agent-caller (Proof Editor-style),
+		// not derived from env-var sniffing. detectAgentCaller() above is still
+		// used as a context trigger (does this look like an agent?) but never
+		// to fill identity.
+		await bootstrapViaBackend(config, {
+			source: opts.source ?? null,
+			agentCaller: opts.agentCaller ?? null,
+		});
+		fireInit("agent");
+		return;
+	}
+
 	// Warn if an existing config with an API key would be overwritten
 	if (
 		!opts.force &&
@@ -324,6 +485,7 @@ export async function runInit(
 		config.platform.apiKey = apiKeyVal;
 		config.platform.baseUrl = baseUrl;
 		config.platform.userEmail = email;
+		config.platform.createdVia = "email";
 		config.defaults.userId =
 			opts.userId || process.env.USER || process.env.USERNAME || "mem0-cli";
 
@@ -339,13 +501,15 @@ export async function runInit(
 	}
 
 	// ── API key flow ──────────────────────────────────────────────────────────
+	// (Agent Mode branch runs earlier — see above, before the existing-config
+	// guard, so Rules 1/2 can REUSE a valid key without prompting overwrite.)
 
 	// Non-TTY: resolve defaults so partial flags work in pipelines / CI
 	if (!process.stdin.isTTY) {
 		if (!opts.apiKey) {
 			printError(
 				"Non-interactive terminal detected and --api-key is required.",
-				"Usage: mem0 init --api-key <key> [--user-id <id>]",
+				"Usage: mem0 init --api-key <key>, --email <addr>, or --agent for unattended Agent Mode bootstrap.",
 			);
 			process.exit(1);
 		}
@@ -356,6 +520,7 @@ export async function runInit(
 	// Non-interactive: both flags provided
 	if (opts.apiKey && opts.userId) {
 		config.platform.apiKey = opts.apiKey;
+		config.platform.createdVia = "api_key";
 		config.defaults.userId = opts.userId;
 		await validatePlatform(config);
 		saveConfig(config);
@@ -403,6 +568,7 @@ export async function runInit(
 			config.platform.apiKey = apiKeyVal;
 			config.platform.baseUrl = baseUrl;
 			config.platform.userEmail = email;
+			config.platform.createdVia = "email";
 			config.defaults.userId =
 				opts.userId || process.env.USER || process.env.USERNAME || "mem0-cli";
 

cli/node/src/commands/memory.ts

@@ -21,16 +21,19 @@ import {
 	formatSingleMemory,
 	printResultSummary,
 } from "../output.js";
-import { isAgentMode, setCurrentCommand } from "../state.js";
+import { isAgentMode, setCurrentCommand, stdinIsPiped } from "../state.js";
 
-/** True only when stdin is an actual pipe or file redirect — never in agent mode. */
-function _stdinIsPiped(): boolean {
-	if (isAgentMode()) return false;
-	try {
-		const stat = fs.fstatSync(0);
-		return stat.isFIFO() || stat.isFile();
-	} catch {
-		return false;
+/** Exit 1 if value is not a future YYYY-MM-DD date. */
+function _validateExpires(value: string): void {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+		printError(
+			"Invalid date format for --expires. Use YYYY-MM-DD (e.g. 2025-12-31).",
+		);
+		process.exit(1);
+	}
+	if (new Date(value) <= new Date()) {
+		printError("--expires date must be in the future.");
+		process.exit(1);
 	}
 }
 
@@ -46,14 +49,26 @@ export async function cmdAdd(
 		file?: string;
 		metadata?: string;
 		immutable: boolean;
-		noInfer: boolean;
+		infer?: boolean;
 		expires?: string;
 		categories?: string;
-		enableGraph: boolean;
+		customInstructions?: string;
+		agentCustomInstructions?: string;
+		customCategories?: string;
+		structuredDataSchema?: string;
+		timestamp?: number;
 		output: string;
 	},
 ): Promise<void> {
 	setCurrentCommand("add");
+
+	if (opts.categories) {
+		printError(
+			"--categories is not supported on add. Use --custom-categories instead.",
+		);
+		process.exit(1);
+	}
+
 	let msgs: Record<string, unknown>[] | undefined;
 	let content = text;
 
@@ -79,7 +94,7 @@ export async function cmdAdd(
 		}
 	}
 	// Read from stdin only if stdin is an actual pipe or file redirect
-	else if (!content && _stdinIsPiped()) {
+	else if (!content && stdinIsPiped()) {
 		content = fs.readFileSync(0, "utf-8").trim();
 	}
 
@@ -94,20 +109,6 @@ export async function cmdAdd(
 		process.exit(1);
 	}
 
-	// Validate --expires
-	if (opts.expires) {
-		if (!/^\d{4}-\d{2}-\d{2}$/.test(opts.expires)) {
-			printError(
-				"Invalid date format for --expires. Use YYYY-MM-DD (e.g. 2025-12-31).",
-			);
-			process.exit(1);
-		}
-		if (new Date(opts.expires) <= new Date()) {
-			printError("--expires date must be in the future.");
-			process.exit(1);
-		}
-	}
-
 	let meta: Record<string, unknown> | undefined;
 	if (opts.metadata) {
 		try {
@@ -118,15 +119,28 @@ export async function cmdAdd(
 		}
 	}
 
-	let cats: string[] | undefined;
-	if (opts.categories) {
+	let customCats: Record<string, string>[] | undefined;
+	if (opts.customCategories) {
 		try {
-			cats = JSON.parse(opts.categories);
+			customCats = JSON.parse(opts.customCategories);
 		} catch {
-			cats = opts.categories.split(",").map((c) => c.trim());
+			printError("Invalid JSON in --custom-categories.");
+			process.exit(1);
 		}
 	}
 
+	let schema: Record<string, unknown> | undefined;
+	if (opts.structuredDataSchema) {
+		try {
+			schema = JSON.parse(opts.structuredDataSchema);
+		} catch {
+			printError("Invalid JSON in --structured-data-schema.");
+			process.exit(1);
+		}
+	}
+
+	if (opts.expires) _validateExpires(opts.expires);
+
 	let result: Record<string, unknown>;
 	try {
 		result = await timedStatus("Adding memory...", async () => {
@@ -137,10 +151,13 @@ export async function cmdAdd(
 				runId: opts.runId,
 				metadata: meta,
 				immutable: opts.immutable,
-				infer: !opts.noInfer,
+				infer: opts.infer !== false,
 				expires: opts.expires,
-				categories: cats,
-				enableGraph: opts.enableGraph,
+				customInstructions: opts.customInstructions,
+				agentCustomInstructions: opts.agentCustomInstructions,
+				customCategories: customCats,
+				structuredDataSchema: schema,
+				timestamp: opts.timestamp,
 			});
 		});
 	} catch (e) {
@@ -225,7 +242,9 @@ export async function cmdSearch(
 		keyword: boolean;
 		filterJson?: string;
 		fields?: string;
-		enableGraph: boolean;
+		showExpired?: boolean;
+		referenceDate?: string;
+		latestOnly?: boolean;
 		output: string;
 	},
 ): Promise<void> {
@@ -274,7 +293,9 @@ export async function cmdSearch(
 				keyword: opts.keyword,
 				filters,
 				fields: fieldList,
-				enableGraph: opts.enableGraph,
+				showExpired: opts.showExpired,
+				referenceDate: opts.referenceDate,
+				latestOnly: opts.latestOnly,
 			});
 		});
 	} catch (e) {
@@ -368,7 +389,8 @@ export async function cmdList(
 		category?: string;
 		after?: string;
 		before?: string;
-		enableGraph: boolean;
+		showExpired?: boolean;
+		latestOnly?: boolean;
 		output: string;
 	},
 ): Promise<void> {
@@ -396,7 +418,8 @@ export async function cmdList(
 				category: opts.category,
 				after: opts.after,
 				before: opts.before,
-				enableGraph: opts.enableGraph,
+				showExpired: opts.showExpired,
+				latestOnly: opts.latestOnly,
 			});
 		});
 	} catch (e) {
@@ -456,7 +479,12 @@ export async function cmdUpdate(
 	backend: Backend,
 	memoryId: string,
 	text: string | undefined,
-	opts: { metadata?: string; output: string },
+	opts: {
+		metadata?: string;
+		expires?: string;
+		timestamp?: number;
+		output: string;
+	},
 ): Promise<void> {
 	setCurrentCommand("update");
 	let meta: Record<string, unknown> | undefined;
@@ -469,11 +497,16 @@ export async function cmdUpdate(
 		}
 	}
 
+	if (opts.expires) _validateExpires(opts.expires);
+
 	const start = performance.now();
 	let result: Record<string, unknown>;
 	try {
 		result = await timedStatus("Updating memory...", async () => {
-			return backend.update(memoryId, text, meta);
+			return backend.update(memoryId, text, meta, {
+				expirationDate: opts.expires,
+				timestamp: opts.timestamp,
+			});
 		});
 	} catch (e) {
 		printError(e instanceof Error ? e.message : String(e));
@@ -499,7 +532,12 @@ export async function cmdUpdate(
 export async function cmdDelete(
 	backend: Backend,
 	memoryId: string,
-	opts: { output: string; dryRun?: boolean; force?: boolean },
+	opts: {
+		output: string;
+		dryRun?: boolean;
+		force?: boolean;
+		deleteLinked?: boolean;
+	},
 ): Promise<void> {
 	setCurrentCommand("delete");
 	if (opts.dryRun) {
@@ -520,7 +558,7 @@ export async function cmdDelete(
 	let result: Record<string, unknown>;
 	try {
 		result = await timedStatus("Deleting...", async () => {
-			return backend.delete(memoryId);
+			return backend.delete(memoryId, { deleteLinked: opts.deleteLinked });
 		});
 	} catch (e) {
 		printError(e instanceof Error ? e.message : String(e));

cli/node/src/commands/utils.ts

@@ -1,5 +1,5 @@
 /**
- * Utility commands: status, version, import.
+ * Utility commands: status, import.
  */
 
 import fs from "node:fs";
@@ -8,7 +8,6 @@ import type { Backend } from "../backend/base.js";
 import { colors, printError, printSuccess, timedStatus } from "../branding.js";
 import { formatAgentEnvelope, formatJsonEnvelope } from "../output.js";
 import { setCurrentCommand } from "../state.js";
-import { CLI_VERSION } from "../version.js";
 
 const { brand, dim, success, error: errorColor } = colors;
 
@@ -63,7 +62,7 @@ export async function cmdStatus(
 				`  ${dim("Run")} ${brand("mem0 init")} ${dim("to reconfigure your API key")}`,
 			);
 			lines.push(
-				`  ${dim("Get a key at")} ${brand("https://app.mem0.ai/dashboard/api-keys")}`,
+				`  ${dim("Get a key at")} ${brand("https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-node")}`,
 			);
 		}
 	}
@@ -82,10 +81,6 @@ export async function cmdStatus(
 	console.log();
 }
 
-export function cmdVersion(): void {
-	console.log(`  ${brand("◆ Mem0")} CLI v${CLI_VERSION}`);
-}
-
 export async function cmdImport(
 	backend: Backend,
 	filePath: string,

cli/node/src/commands/whoami.ts

@@ -0,0 +1,18 @@
+/**
+ * `mem0 whoami` — print the active agent's default_user_id (AGENTRUSH identifier).
+ * Reads from local config; no network call.
+ */
+
+import { colors, printError, printInfo } from "../branding.js";
+import { loadConfig } from "../config.js";
+
+export async function cmdWhoami(): Promise<void> {
+	const config = loadConfig();
+	const sessionId = config.platform?.defaultUserId;
+	if (!sessionId) {
+		printError("No default_user_id found. Run `mem0 init --agent` first.");
+		process.exit(1);
+	}
+	console.log(`Your AGENTRUSH identifier:  ${colors.brand(sessionId)}`);
+	printInfo("Find your row at https://mem0.ai/agentrush");
+}

cli/node/src/config.ts

@@ -21,6 +21,12 @@ export interface PlatformConfig {
 	apiKey: string;
 	baseUrl: string;
 	userEmail: string;
+	// Agent Mode (unclaimed-shadow signup)
+	agentMode: boolean; // true while the key is an unclaimed agent-mode key
+	createdVia: string; // "agent_mode" | "email" | "api_key" | "existing_key"
+	agentCaller: string; // canonical agent name when createdVia === "agent_mode" (e.g. "claude-code")
+	claimedAt: string; // ISO timestamp once the agent has been claimed
+	defaultUserId: string; // `user_<slug>` returned by bootstrap; auto-default scope
 }
 
 export interface DefaultsConfig {
@@ -28,18 +34,24 @@ export interface DefaultsConfig {
 	agentId: string;
 	appId: string;
 	runId: string;
-	enableGraph: boolean;
 }
 
 export interface TelemetryConfig {
 	anonymousId: string;
 }
 
+export interface AgentRushConfig {
+	// ISO timestamp the human acknowledged the "memories are public" warning.
+	// Empty until first interactive `mem0 agent-rush add`.
+	acknowledgedAt: string;
+}
+
 export interface Mem0Config {
 	version: number;
 	defaults: DefaultsConfig;
 	platform: PlatformConfig;
 	telemetry: TelemetryConfig;
+	agentRush: AgentRushConfig;
 }
 
 export function createDefaultConfig(): Mem0Config {
@@ -50,16 +62,23 @@ export function createDefaultConfig(): Mem0Config {
 			agentId: "",
 			appId: "",
 			runId: "",
-			enableGraph: false,
 		},
 		platform: {
 			apiKey: "",
 			baseUrl: DEFAULT_BASE_URL,
 			userEmail: "",
+			agentMode: false,
+			createdVia: "",
+			agentCaller: "",
+			claimedAt: "",
+			defaultUserId: "",
 		},
 		telemetry: {
 			anonymousId: "",
 		},
+		agentRush: {
+			acknowledgedAt: "",
+		},
 	};
 }
 
@@ -81,16 +100,21 @@ export function loadConfig(): Mem0Config {
 		config.platform.apiKey = plat.api_key ?? "";
 		config.platform.baseUrl = plat.base_url ?? DEFAULT_BASE_URL;
 		config.platform.userEmail = plat.user_email ?? "";
+		config.platform.agentMode = Boolean(plat.agent_mode ?? false);
+		config.platform.createdVia = plat.created_via ?? "";
+		config.platform.agentCaller = plat.agent_caller ?? "";
+		config.platform.claimedAt = plat.claimed_at ?? "";
+		config.platform.defaultUserId = plat.default_user_id ?? "";
 
 		const defaults = data.defaults ?? {};
 		config.defaults.userId = defaults.user_id ?? "";
 		config.defaults.agentId = defaults.agent_id ?? "";
 		config.defaults.appId = defaults.app_id ?? "";
 		config.defaults.runId = defaults.run_id ?? "";
-		config.defaults.enableGraph = defaults.enable_graph ?? false;
-
 		const telemetry = data.telemetry ?? {};
 		config.telemetry.anonymousId = telemetry.anonymous_id ?? "";
+		const agentRush = data.agent_rush ?? {};
+		config.agentRush.acknowledgedAt = agentRush.acknowledged_at ?? "";
 	}
 
 	// Environment variable overrides
@@ -104,12 +128,6 @@ export function loadConfig(): Mem0Config {
 		config.defaults.agentId = process.env.MEM0_AGENT_ID;
 	if (process.env.MEM0_APP_ID) config.defaults.appId = process.env.MEM0_APP_ID;
 	if (process.env.MEM0_RUN_ID) config.defaults.runId = process.env.MEM0_RUN_ID;
-	if (process.env.MEM0_ENABLE_GRAPH) {
-		config.defaults.enableGraph = ["true", "1", "yes"].includes(
-			process.env.MEM0_ENABLE_GRAPH.toLowerCase(),
-		);
-	}
-
 	return config;
 }
 
@@ -123,20 +141,41 @@ export function saveConfig(config: Mem0Config): void {
 			agent_id: config.defaults.agentId,
 			app_id: config.defaults.appId,
 			run_id: config.defaults.runId,
-			enable_graph: config.defaults.enableGraph,
 		},
 		platform: {
 			api_key: config.platform.apiKey,
 			base_url: config.platform.baseUrl,
 			user_email: config.platform.userEmail,
+			agent_mode: config.platform.agentMode,
+			created_via: config.platform.createdVia,
+			agent_caller: config.platform.agentCaller,
+			claimed_at: config.platform.claimedAt,
+			default_user_id: config.platform.defaultUserId,
 		},
 		telemetry: {
 			anonymous_id: config.telemetry.anonymousId,
 		},
+		agent_rush: {
+			acknowledged_at: config.agentRush.acknowledgedAt,
+		},
 	};
 
 	fs.writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2));
 	fs.chmodSync(CONFIG_FILE, 0o600);
+
+	// Propagate api_key to ecosystem touchpoints (Claude plugin env injection,
+	// shell rc exports). Idempotent — updates only EXISTING entries; never
+	// creates new ones. Best-effort: errors swallowed so config.json is
+	// always authoritative, never blocked by plugin-state issues.
+	if (config.platform.apiKey) {
+		try {
+			// eslint-disable-next-line @typescript-eslint/no-require-imports
+			const { syncApiKey } = require("./plugin-sync.js");
+			syncApiKey(config.platform.apiKey);
+		} catch {
+			/* swallow */
+		}
+	}
 }
 
 export function redactKey(key: string): string {
@@ -154,7 +193,6 @@ const KEY_MAP: Record<string, [keyof Mem0Config, string]> = {
 	"defaults.agent_id": ["defaults", "agentId"],
 	"defaults.app_id": ["defaults", "appId"],
 	"defaults.run_id": ["defaults", "runId"],
-	"defaults.enable_graph": ["defaults", "enableGraph"],
 	// Short-form aliases
 	api_key: ["platform", "apiKey"],
 	base_url: ["platform", "baseUrl"],
@@ -163,7 +201,6 @@ const KEY_MAP: Record<string, [keyof Mem0Config, string]> = {
 	agent_id: ["defaults", "agentId"],
 	app_id: ["defaults", "appId"],
 	run_id: ["defaults", "runId"],
-	enable_graph: ["defaults", "enableGraph"],
 };
 
 export function getNestedValue(config: Mem0Config, dottedKey: string): unknown {

cli/node/src/help.ts

@@ -36,7 +36,16 @@ const COMMAND_GROUPS: { panel: string; commands: string[] }[] = [
 	},
 	{
 		panel: "Management",
-		commands: ["init", "status", "import", "help", "entity", "event", "config"],
+		commands: [
+			"init",
+			"status",
+			"version",
+			"import",
+			"help",
+			"entity",
+			"event",
+			"config",
+		],
 	},
 ];
 

cli/node/src/index.ts

@@ -13,7 +13,13 @@ import { colors, printError, printWarning } from "./branding.js";
 import type { Mem0Config } from "./config.js";
 import { loadConfig, saveConfig } from "./config.js";
 import { richFormatHelp } from "./help.js";
-import { setAgentMode } from "./state.js";
+import {
+	isAgentMode,
+	setAgentMode,
+	setCurrentCommand,
+	stdinIsPiped,
+	takeNotice,
+} from "./state.js";
 import { captureEvent } from "./telemetry.js";
 import { CLI_VERSION } from "./version.js";
 
@@ -89,6 +95,10 @@ async function getBackendOnly(
 	return (await getBackendAndConfig(apiKey, baseUrl)).backend;
 }
 
+function printVersion(): void {
+	console.log(`  ${colors.brand("◆ Mem0")} CLI v${CLI_VERSION}`);
+}
+
 function checkAgentMode(): boolean {
 	const rootOpts = program.opts();
 	const isAgent = !!(rootOpts.json || rootOpts.agent);
@@ -134,18 +144,6 @@ function resolveIds(
 	};
 }
 
-/**
- * Resolve graph tri-state: --no-graph > --graph > config default.
- */
-function resolveGraph(
-	config: Mem0Config,
-	opts: { graph?: boolean; noGraph?: boolean },
-): boolean {
-	if (opts.noGraph) return false;
-	if (opts.graph) return true;
-	return config.defaults.enableGraph;
-}
-
 // ── Main program ──────────────────────────────────────────────────────────
 
 program
@@ -153,15 +151,20 @@ program
 	.description(
 		`◆ Mem0 CLI v${CLI_VERSION} · Node.js SDK\n\nThe Memory Layer for AI Agents`,
 	)
+	// Positional options: flags AFTER a subcommand name belong to that
+	// subcommand, not the global program. Without this, `mem0 init --agent`
+	// routes `--agent` to the program-level alias (for --json) and init's own
+	// `--agent` (Agent Mode bootstrap) silently never fires.
+	.enablePositionalOptions()
 	.option("--version", "Show version and exit.")
 	.on("option:version", () => {
-		console.log(`  ${colors.brand("◆ Mem0")} CLI v${CLI_VERSION}`);
+		printVersion();
 		process.exit(0);
 	})
 	.option("--json", "Output as JSON for agent/programmatic use.")
 	.option(
 		"--agent",
-		"Output as JSON for agent/programmatic use. (alias: --json)",
+		"Output as JSON for agent/programmatic use. (alias: --json) Place BEFORE the subcommand: `mem0 --agent <cmd>`. On `init`, `mem0 init --agent` is the Agent Mode bootstrap flag instead.",
 	)
 	.usage("<command> [options]")
 	.helpOption("--help", "Show this message and exit.")
@@ -178,6 +181,14 @@ program.hook("preAction", (_thisCommand, actionCommand) => {
 			parentName && parentName !== "mem0"
 				? `${parentName}.${commandName}`
 				: commandName;
+		// Stash the active command name in shared state so the JSON
+		// error envelope (printError) can report which command failed
+		// instead of an empty `"command": ""` field.
+		setCurrentCommand(fullCommand);
+		// init fires its own telemetry from runInit with full M1-M6 props
+		// (mode/agent_caller/signup_source/claimed_agent_mode); skip the
+		// auto-fire here so we don't double-count.
+		if (fullCommand === "init") return;
 		const isAgent = !!(program.opts().json || program.opts().agent);
 		captureEvent(
 			`cli.${fullCommand}`,
@@ -205,11 +216,32 @@ program
 		"Verification code (use with --email for non-interactive login).",
 	)
 	.option("--force", "Overwrite existing config without confirmation.", false)
+	.option(
+		"--agent",
+		"Bootstrap an unattended Agent Mode account (no email required).",
+		false,
+	)
+	.option(
+		"--source <channel>",
+		"Channel attribution for signup (e.g. github, hn, ph).",
+	)
+	.option(
+		"--agent-caller <name>",
+		"Self-declared agent identity (e.g. claude-code, cursor). Used with --agent to attribute Agent Mode signups.",
+	)
+	// Accept `--json` at the init level too so the PRD-documented form
+	// `mem0 init --agent --json` works without requiring users to move it
+	// before the subcommand. Effect is identical to the global `--json`:
+	// flip agent-mode output state.
+	.option("--json", "Output as JSON (alias for global `--json`).", false)
 	.addHelpText(
 		"after",
-		"\nExamples:\n  $ mem0 init\n  $ mem0 init --api-key m0-xxx --user-id alice\n  $ mem0 init --email you@example.com\n  $ mem0 init --email you@example.com --code 123456",
+		"\nExamples:\n  $ mem0 init\n  $ mem0 init --api-key m0-xxx --user-id alice\n  $ mem0 init --email you@example.com\n  $ mem0 init --email you@example.com --code 123456\n  $ mem0 init --agent             # Bootstrap an Agent Mode account (unattended)\n  $ mem0 init --email you@example.com  # Claims an existing Agent Mode key when one is present",
 	)
 	.action(async (opts) => {
+		// `--json` at init level mirrors the global flag — flip agent_mode
+		// state so downstream formatters use JSON envelopes.
+		if (opts.json) setAgentMode(true);
 		const { runInit } = await import("./commands/init.js");
 		await runInit({
 			apiKey: opts.apiKey,
@@ -217,9 +249,66 @@ program
 			email: opts.email,
 			code: opts.code,
 			force: opts.force,
+			agent: opts.agent,
+			source: opts.source,
+			agentCaller: opts.agentCaller,
 		});
 	});
 
+// ── Setup: identify (post-bootstrap agent self-tag) ──────────────────────
+
+program
+	.command("identify <name>")
+	.description(
+		"Tag your active Agent Mode key with the AI agent that's using it (e.g. claude-code, cursor).",
+	)
+	.action(async (name: string) => {
+		const { runIdentify } = await import("./commands/identify.js");
+		await runIdentify(name);
+	});
+
+// ── Setup: whoami (print active agent identifier) ────────────────────────
+
+program
+	.command("whoami")
+	.description("Print the active agent's AGENTRUSH identifier.")
+	.action(async () => {
+		const { cmdWhoami } = await import("./commands/whoami.js");
+		await cmdWhoami();
+	});
+
+// ── AGENTRUSH subcommand group ────────────────────────────────────────────
+
+const agentRush = program
+	.command("agent-rush")
+	.description("AGENTRUSH game commands.")
+	.addHelpCommand(false)
+	.configureHelp({ formatHelp: richFormatHelp });
+
+agentRush
+	.command("add <content...>")
+	.description("Submit a memory to AGENTRUSH.")
+	.addHelpText(
+		"after",
+		'\nExamples:\n  $ mem0 agent-rush add "I used mem0 to build a coding agent"\n  $ mem0 agent-rush add "Agents that remember are better agents"',
+	)
+	.action(async (parts: string[]) => {
+		const { cmdAgentRushAdd } = await import("./commands/agent-rush.js");
+		await cmdAgentRushAdd(parts.join(" "));
+	});
+
+agentRush
+	.command("search <query...>")
+	.description("Search AGENTRUSH memories.")
+	.addHelpText(
+		"after",
+		'\nExamples:\n  $ mem0 agent-rush search "agents and memory and tools"\n  $ mem0 agent-rush search "coding assistant"',
+	)
+	.action(async (parts: string[]) => {
+		const { cmdAgentRushSearch } = await import("./commands/agent-rush.js");
+		await cmdAgentRushSearch(parts.join(" "));
+	});
+
 // ── Memory: add ───────────────────────────────────────────────────────────
 
 program
@@ -235,9 +324,29 @@ program
 	.option("--immutable", "Prevent future updates.", false)
 	.option("--no-infer", "Skip inference, store raw.")
 	.option("--expires <date>", "Expiration date (YYYY-MM-DD).")
-	.option("--categories <value>", "Categories (JSON array or comma-separated).")
-	.option("--graph", "Enable graph memory extraction.", false)
-	.option("--no-graph", "Disable graph memory extraction.")
+	.option(
+		"--categories <value>",
+		"Not supported on add, use --custom-categories instead.",
+	)
+	.option(
+		"--custom-instructions <text>",
+		"Custom instructions for fact extraction.",
+	)
+	.option(
+		"--agent-custom-instructions <text>",
+		"Extraction instructions for agent-scoped memories, overriding the project setting.",
+	)
+	.option(
+		"--custom-categories <json>",
+		"Custom categories as a JSON array of {name: description} objects.",
+	)
+	.option(
+		"--structured-data-schema <json>",
+		"Schema for structured data extraction, as JSON.",
+	)
+	.option("--timestamp <unix>", "Unix timestamp for the memory.", (v) =>
+		Number.parseInt(v),
+	)
 	.option("-o, --output <format>", "Output format: text, json, quiet.", "text")
 	.option("--api-key <key>", "Override API key.")
 	.option("--base-url <url>", "Override API base URL.")
@@ -253,9 +362,8 @@ program
 			opts.baseUrl,
 		);
 		const ids = resolveIds(config, opts);
-		const enableGraph = resolveGraph(config, opts);
 		const output = isAgent ? "agent" : opts.output;
-		await cmdAdd(backend, text, { ...ids, ...opts, enableGraph, output });
+		await cmdAdd(backend, text, { ...ids, ...opts, output });
 	});
 
 // ── Memory: search ────────────────────────────────────────────────────────
@@ -283,20 +391,31 @@ program
 	)
 	.option("--rerank", "Enable reranking (Platform only).", false)
 	.option("--keyword", "Use keyword search.", false)
-	.option("--filter <json>", "Advanced filter expression (JSON).")
+	.option(
+		"--filter <json>",
+		'Advanced filter as JSON: {"AND": [...]} or {"OR": [...]}, e.g. {"AND": [{"categories": {"in": ["work"]}}]}.',
+	)
 	.option("--fields <list>", "Specific fields to return (comma-separated).")
-	.option("--graph", "Enable graph in search.", false)
-	.option("--no-graph", "Disable graph in search.")
+	.option("--show-expired", "Include expired memories.", false)
+	.option(
+		"--reference-date <date>",
+		"Reference date for relative queries (YYYY-MM-DD or unix timestamp).",
+	)
+	.option(
+		"--latest-only",
+		"Only return the latest version of each memory.",
+		false,
+	)
 	.option("-o, --output <format>", "Output: text, json, table.", "text")
 	.option("--api-key <key>", "Override API key.")
 	.option("--base-url <url>", "Override API base URL.")
 	.addHelpText(
 		"after",
-		'\nExamples:\n  $ mem0 search "preferences" --user-id alice\n  $ mem0 search "tools" -u alice -o json -k 5\n  $ echo "preferences" | mem0 search -u alice',
+		'\nExamples:\n  $ mem0 search "preferences" --user-id alice\n  $ mem0 search "tools" -u alice -o json -k 5\n  $ echo "preferences" | mem0 search -u alice\n  $ mem0 search "invoices" -u alice --filter \'{"AND": [{"categories": {"in": ["work"]}}]}\'',
 	)
 	.action(async (query, opts) => {
 		let resolvedQuery = query;
-		if (!resolvedQuery && !process.stdin.isTTY) {
+		if (!resolvedQuery && stdinIsPiped()) {
 			resolvedQuery = fs.readFileSync(0, "utf-8").trim();
 		}
 		if (!resolvedQuery) {
@@ -310,7 +429,6 @@ program
 			opts.baseUrl,
 		);
 		const ids = resolveIds(config, opts);
-		const enableGraph = resolveGraph(config, opts);
 		const output = isAgent ? "agent" : opts.output;
 		await cmdSearch(backend, resolvedQuery, {
 			...ids,
@@ -320,7 +438,9 @@ program
 			keyword: opts.keyword,
 			filterJson: opts.filter,
 			fields: opts.fields,
-			enableGraph,
+			showExpired: opts.showExpired,
+			referenceDate: opts.referenceDate,
+			latestOnly: opts.latestOnly,
 			output,
 		});
 	});
@@ -364,8 +484,12 @@ program
 	.option("--category <name>", "Filter by category.")
 	.option("--after <date>", "Created after (YYYY-MM-DD).")
 	.option("--before <date>", "Created before (YYYY-MM-DD).")
-	.option("--graph", "Enable graph in listing.", false)
-	.option("--no-graph", "Disable graph in listing.")
+	.option("--show-expired", "Include expired memories.", false)
+	.option(
+		"--latest-only",
+		"Only return the latest version of each memory.",
+		false,
+	)
 	.option("-o, --output <format>", "Output: text, json, table.", "table")
 	.option("--api-key <key>", "Override API key.")
 	.option("--base-url <url>", "Override API base URL.")
@@ -381,7 +505,6 @@ program
 			opts.baseUrl,
 		);
 		const ids = resolveIds(config, opts);
-		const enableGraph = resolveGraph(config, opts);
 		const output = isAgent ? "agent" : opts.output;
 		await cmdList(backend, {
 			...ids,
@@ -390,7 +513,8 @@ program
 			category: opts.category,
 			after: opts.after,
 			before: opts.before,
-			enableGraph,
+			showExpired: opts.showExpired,
+			latestOnly: opts.latestOnly,
 			output,
 		});
 	});
@@ -401,6 +525,10 @@ program
 	.command("update <memoryId> [text]")
 	.description("Update a memory's text or metadata.")
 	.option("-m, --metadata <json>", "Update metadata (JSON).")
+	.option("--expires <date>", "Expiration date (YYYY-MM-DD).")
+	.option("--timestamp <unix>", "Unix timestamp for the memory.", (v) =>
+		Number.parseInt(v),
+	)
 	.option("-o, --output <format>", "Output: text, json, quiet.", "text")
 	.option("--api-key <key>", "Override API key.")
 	.option("--base-url <url>", "Override API base URL.")
@@ -410,7 +538,7 @@ program
 	)
 	.action(async (memoryId, text, opts) => {
 		let resolvedText = text;
-		if (!resolvedText && !opts.metadata && !process.stdin.isTTY) {
+		if (!resolvedText && stdinIsPiped()) {
 			resolvedText = fs.readFileSync(0, "utf-8").trim();
 		}
 		const { cmdUpdate } = await import("./commands/memory.js");
@@ -419,6 +547,8 @@ program
 		const output = isAgent ? "agent" : opts.output;
 		await cmdUpdate(backend, memoryId, resolvedText, {
 			metadata: opts.metadata,
+			expires: opts.expires,
+			timestamp: opts.timestamp,
 			output,
 		});
 	});
@@ -437,6 +567,11 @@ program
 	.option("--project", "With --all: delete ALL memories project-wide.", false)
 	.option("--dry-run", "Show what would be deleted without deleting.", false)
 	.option("--force", "Skip confirmation.", false)
+	.option(
+		"--delete-linked",
+		"Also delete memories linked to this memory.",
+		false,
+	)
 	.option("-u, --user-id <id>", "Scope to user.")
 	.option("--agent-id <id>", "Scope to agent.")
 	.option("--app-id <id>", "Scope to app.")
@@ -490,6 +625,7 @@ program
 				output,
 				dryRun: opts.dryRun,
 				force: opts.force,
+				deleteLinked: opts.deleteLinked,
 			});
 			return;
 		}
@@ -694,6 +830,13 @@ program
 		});
 	});
 
+program
+	.command("version")
+	.description("Show version and exit.")
+	.action(() => {
+		printVersion();
+	});
+
 program
 	.command("import <filePath>")
 	.description("Import memories from a JSON file.")
@@ -733,8 +876,8 @@ program
 	.addHelpText("after", "\nExamples:\n  $ mem0 help\n  $ mem0 help --json")
 	.action((opts) => {
 		// opts.json is set when `mem0 help --json` is used (subcommand flag).
-		// program.opts().json is set when the root --json global flag was used first.
-		if (opts.json || program.opts().json) {
+		// program.opts().json/.agent is set when a root global flag was used first.
+		if (opts.json || program.opts().json || program.opts().agent) {
 			// Load spec from parent directory
 			const __dirname = path.dirname(fileURLToPath(import.meta.url));
 			const specPath = path.join(__dirname, "..", "..", "cli-spec.json");
@@ -792,4 +935,16 @@ program
 
 // ── Entrypoint ────────────────────────────────────────────────────────────
 
-program.parse();
+// Surface any unclaimed Agent Mode notice once per command, after the primary
+// output. In JSON/agent mode the notice is folded into the envelope by
+// formatJsonEnvelope, so skip the stderr banner there to avoid duplication.
+function surfaceNotice(): void {
+	const notice = takeNotice();
+	if (notice && !isAgentMode()) {
+		process.stderr.write(`\n\x1b[33m🔔 ${notice}\x1b[0m\n\n`);
+	}
+}
+
+program.parseAsync().finally(() => {
+	surfaceNotice();
+});

cli/node/src/output.ts

@@ -5,6 +5,7 @@
 import boxen from "boxen";
 import Table from "cli-table3";
 import { colors, sym } from "./branding.js";
+import { takeNotice } from "./state.js";
 
 const { brand, accent, success, error: errorColor, dim } = colors;
 
@@ -244,6 +245,15 @@ export function formatJsonEnvelope(opts: {
 	if (opts.count !== undefined) envelope.count = opts.count;
 	if (opts.error) envelope.error = opts.error;
 	envelope.data = opts.data;
+
+	// If the platform flagged this as an unclaimed Agent Mode account, surface
+	// the notice inside the JSON envelope so an agent consuming the output
+	// sees it without needing to inspect HTTP headers.
+	// eslint-disable-next-line @typescript-eslint/no-require-imports
+	const { takeNotice } = require("./state.js");
+	const notice = takeNotice();
+	if (notice) envelope.mem0_notice = notice;
+
 	console.log(JSON.stringify(envelope, null, 2));
 }
 
@@ -272,11 +282,24 @@ export function sanitizeAgentData(command: string, data: unknown): unknown {
 		}
 		case "search":
 			return (data as Record<string, unknown>[]).map((r) =>
-				pick(r, ["id", "memory", "score", "created_at", "categories"]),
+				pick(r, [
+					"id",
+					"memory",
+					"score",
+					"created_at",
+					"categories",
+					"expiration_date",
+				]),
 			);
 		case "list":
 			return (data as Record<string, unknown>[]).map((r) =>
-				pick(r, ["id", "memory", "created_at", "categories"]),
+				pick(r, [
+					"id",
+					"memory",
+					"created_at",
+					"categories",
+					"expiration_date",
+				]),
 			);
 		case "get": {
 			const r = data as Record<string, unknown>;
@@ -287,11 +310,12 @@ export function sanitizeAgentData(command: string, data: unknown): unknown {
 				"updated_at",
 				"categories",
 				"metadata",
+				"expiration_date",
 			]);
 		}
 		case "update": {
 			const r = data as Record<string, unknown>;
-			return pick(r, ["id", "memory"]);
+			return pick(r, ["id", "memory", "expiration_date"]);
 		}
 		case "delete":
 		case "delete-all":
@@ -356,6 +380,12 @@ export function formatAgentEnvelope(opts: {
 	}
 	if (opts.count !== undefined) envelope.count = opts.count;
 	envelope.data = sanitizeAgentData(opts.command, opts.data);
+
+	// Surface the unclaimed-Agent-Mode notice (if any) in the envelope so an
+	// agent reading the JSON output sees it without inspecting HTTP headers.
+	const notice = takeNotice();
+	if (notice) envelope.mem0_notice = notice;
+
 	console.log(JSON.stringify(envelope, null, 2));
 }
 

cli/node/src/plugin-sync.ts

@@ -0,0 +1,120 @@
+/**
+ * Sync the active Mem0 API key into other ecosystem touchpoints.
+ *
+ * Why: the CLI canonical state is ~/.mem0/config.json. MCP servers
+ * (Claude Code plugin, Codex plugin) read MEM0_API_KEY from env or
+ * their own config files. Without a sync, agent-mode bootstrap mints a
+ * new key into config.json but the plugin's MCP keeps using the old
+ * key from env — silent surprise.
+ *
+ * Design:
+ *  - Update ONLY entries that already exist; never create new ones
+ *  - Preserve surrounding content, formatting, other keys
+ *  - Atomic writes (tmp + rename) so a crash mid-write doesn't corrupt
+ *  - Idempotent — re-running with the same key is a no-op
+ *
+ * Targets:
+ *  - ~/.claude/settings.json::env::MEM0_API_KEY (Claude Code env injection)
+ *  - ~/.zshrc / ~/.bashrc `export MEM0_API_KEY="..."` lines
+ *
+ * Out of scope: Codex / Cursor MCP configs and the plugin's own
+ * <plugin-dir>/.api_key file (plugin-managed, different schema).
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const CLAUDE_SETTINGS = path.join(os.homedir(), ".claude", "settings.json");
+const SHELL_RCS = [
+	path.join(os.homedir(), ".zshrc"),
+	path.join(os.homedir(), ".bashrc"),
+	path.join(os.homedir(), ".bash_profile"),
+];
+
+// Use [ \t]* (not \s*) so a trailing newline at end-of-file is preserved
+// when the MEM0_API_KEY export is the last line of the rc file.
+const RC_LINE_RE =
+	/^([ \t]*export[ \t]+MEM0_API_KEY[ \t]*=[ \t]*)(["']?)([^"'\n]*)(["']?)[ \t]*$/m;
+
+export function syncApiKey(apiKey: string): string[] {
+	if (!apiKey) return [];
+	const updated: string[] = [];
+	if (updateClaudeSettings(CLAUDE_SETTINGS, apiKey)) {
+		updated.push(CLAUDE_SETTINGS);
+	}
+	for (const rc of SHELL_RCS) {
+		if (updateShellRc(rc, apiKey)) updated.push(rc);
+	}
+	return updated;
+}
+
+/** @internal — exported for unit tests; consumers should use {@link syncApiKey}. */
+export function updateClaudeSettings(
+	filePath: string,
+	apiKey: string,
+): boolean {
+	if (!fs.existsSync(filePath)) return false;
+	let raw: string;
+	let data: Record<string, unknown>;
+	try {
+		raw = fs.readFileSync(filePath, "utf-8");
+		data = JSON.parse(raw);
+	} catch {
+		return false;
+	}
+	const env = data.env;
+	if (!env || typeof env !== "object" || !("MEM0_API_KEY" in env)) {
+		return false; // no existing entry — don't create one
+	}
+	const envObj = env as Record<string, string>;
+	if (envObj.MEM0_API_KEY === apiKey) return false; // already in sync
+	envObj.MEM0_API_KEY = apiKey;
+	atomicWriteText(filePath, `${JSON.stringify(data, null, 2)}\n`);
+	return true;
+}
+
+/** @internal — exported for unit tests; consumers should use {@link syncApiKey}. */
+export function updateShellRc(filePath: string, apiKey: string): boolean {
+	if (!fs.existsSync(filePath)) return false;
+	let text: string;
+	try {
+		text = fs.readFileSync(filePath, "utf-8");
+	} catch {
+		return false;
+	}
+	const match = text.match(RC_LINE_RE);
+	if (!match) return false; // no existing line
+	if (match[3] === apiKey) return false;
+	const newText = text.replace(
+		RC_LINE_RE,
+		(_full, prefix) => `${prefix}"${apiKey}"`,
+	);
+	atomicWriteText(filePath, newText);
+	return true;
+}
+
+function atomicWriteText(filePath: string, content: string): void {
+	const dir = path.dirname(filePath);
+	const tmp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.tmp`);
+	try {
+		fs.writeFileSync(tmp, content, "utf-8");
+		// Preserve permissions if original existed.
+		if (fs.existsSync(filePath)) {
+			try {
+				const mode = fs.statSync(filePath).mode & 0o777;
+				fs.chmodSync(tmp, mode);
+			} catch {
+				/* best-effort */
+			}
+		}
+		fs.renameSync(tmp, filePath);
+	} catch (err) {
+		try {
+			fs.unlinkSync(tmp);
+		} catch {
+			/* ignore */
+		}
+		throw err;
+	}
+}

cli/node/src/state.ts

@@ -3,8 +3,11 @@
  * read by commands and branding functions.
  */
 
+import fs from "node:fs";
+
 let _agentMode = false;
 let _currentCommand = "";
+let _pendingNotice = "";
 
 export function isAgentMode(): boolean {
 	return _agentMode;
@@ -21,3 +24,30 @@ export function getCurrentCommand(): string {
 export function setCurrentCommand(name: string): void {
 	_currentCommand = name;
 }
+
+/**
+ * Stash a Mem0 backend notice (Agent Mode unclaimed reminder) for end-of-
+ * command surfacing. Called from the platform backend after each response so
+ * the notice prints once per command regardless of how many sub-requests
+ * fired. Last-write-wins is fine — the message text is identical.
+ */
+export function captureNotice(notice: string | null | undefined): void {
+	if (notice) _pendingNotice = notice;
+}
+
+export function takeNotice(): string {
+	const msg = _pendingNotice;
+	_pendingNotice = "";
+	return msg;
+}
+
+/** True only when stdin is an actual pipe or file redirect (never in agent mode). */
+export function stdinIsPiped(): boolean {
+	if (isAgentMode()) return false;
+	try {
+		const stat = fs.fstatSync(0);
+		return stat.isFIFO() || stat.isFile();
+	} catch {
+		return false;
+	}
+}

cli/node/src/telemetry.ts

@@ -115,6 +115,9 @@ export function captureEvent(
 			}
 		}
 
+		// M4: every cli.* event carries agent_mode based on the config flag
+		// (unclaimed Agent Mode key). This is the growth-doc property used to
+		// join init → add → search funnels in PostHog.
 		const payload = {
 			api_key: POSTHOG_API_KEY,
 			distinct_id: distinctId,
@@ -123,6 +126,7 @@ export function captureEvent(
 				source: "CLI",
 				language: "node",
 				cli_version: CLI_VERSION,
+				agent_mode: Boolean(config.platform.agentMode),
 				node_version: process.version,
 				os: process.platform,
 				...properties,
@@ -141,11 +145,11 @@ export function captureEvent(
 			anonDistinctIdToAlias: anonIdToAlias,
 		};
 
-		const child = spawn(
-			process.execPath,
-			[SENDER_SCRIPT, JSON.stringify(context)],
-			{ detached: true, stdio: "ignore" },
-		);
+		const child = spawn(process.execPath, [SENDER_SCRIPT], {
+			detached: true,
+			stdio: ["pipe", "ignore", "ignore"],
+		});
+		child.stdin?.end(JSON.stringify(context));
 		child.unref();
 	} catch {
 		/* silently swallow */

cli/node/telemetry-sender.cjs

@@ -1,7 +1,8 @@
 /**
  * Standalone telemetry sender — runs as a detached child process.
  *
- * Usage: node telemetry-sender.cjs '<json context>'
+ * Usage: node telemetry-sender.cjs   (JSON context is read from stdin; a single
+ * argv argument is still accepted as a legacy fallback)
  *
  * This script is spawned by telemetry.captureEvent() and runs independently
  * of the parent CLI process. It:
@@ -19,6 +20,31 @@
 const https = require("https");
 const fs = require("fs");
 
+function loadContext() {
+	return new Promise((resolve, reject) => {
+		if (process.argv[2]) {
+			try {
+				resolve(JSON.parse(process.argv[2]));
+			} catch (err) {
+				reject(err);
+			}
+			return;
+		}
+
+		let data = "";
+		process.stdin.setEncoding("utf8");
+		process.stdin.on("data", (chunk) => (data += chunk));
+		process.stdin.on("end", () => {
+			try {
+				resolve(JSON.parse(data));
+			} catch (err) {
+				reject(err);
+			}
+		});
+		process.stdin.on("error", reject);
+	});
+}
+
 function httpsRequest(url, method, headers, body) {
 	return new Promise((resolve, reject) => {
 		const u = new URL(url);
@@ -108,7 +134,7 @@ async function sendIdentifyEvent(ctx, payload, anonId) {
 }
 
 async function main() {
-	const ctx = JSON.parse(process.argv[2]);
+	const ctx = await loadContext();
 	const payload = ctx.payload;
 
 	if (ctx.needsEmail && ctx.mem0ApiKey) {

cli/node/tests/agent-mode.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Parity tests for `mem0 init --agent` (Agent Mode bootstrap).
+ *
+ * Mirror of `cli/python/tests/test_agent_mode.py` — both files MUST stay
+ * in sync so that the Python and Node CLIs expose an identical surface
+ * for the Agent Mode entrypoint. If you add a flag here, add the same
+ * assertion on the Python side (and vice versa).
+ *
+ * Network-bound bootstrap is covered by the platform-side E2E suite
+ * (`backend/tests/e2e/test_05_agent_mode.py`); these tests only verify
+ * the CLI surface that ships in the binary.
+ */
+
+import { describe, it, expect } from "vitest";
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+function run(
+  args: string[],
+  opts: { home?: string; env?: Record<string, string> } = {},
+): { stdout: string; stderr: string; exitCode: number } {
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) {
+    if (key.startsWith("MEM0_")) delete env[key];
+  }
+  if (opts.home) env.HOME = opts.home;
+  if (opts.env) Object.assign(env, opts.env);
+
+  try {
+    const stdout = execSync(`npx tsx src/index.ts ${args.join(" ")}`, {
+      cwd: path.join(__dirname, ".."),
+      env,
+      encoding: "utf-8",
+      timeout: 15000,
+    });
+    return { stdout, stderr: "", exitCode: 0 };
+  } catch (e: any) {
+    return {
+      stdout: e.stdout ?? "",
+      stderr: e.stderr ?? "",
+      exitCode: e.status ?? 1,
+    };
+  }
+}
+
+function cleanHome(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "mem0-test-"));
+}
+
+describe("init flag surface", () => {
+  it("init --help lists --agent", () => {
+    const result = run(["init", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--agent");
+  });
+
+  it("init --help describes Agent Mode", () => {
+    const result = run(["init", "--help"]);
+    expect(result.exitCode).toBe(0);
+    // Description must mention what --agent actually does so an agent
+    // reading the help can self-discover the bootstrap entrypoint.
+    expect(
+      result.stdout.includes("Agent Mode") ||
+        result.stdout.toLowerCase().includes("unattended"),
+    ).toBe(true);
+  });
+
+  it("init --help lists --source", () => {
+    const result = run(["init", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--source");
+  });
+
+  it("init --help lists --email and --code", () => {
+    const result = run(["init", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("--email");
+    expect(result.stdout).toContain("--code");
+  });
+});
+
+describe("argv preprocessing — --agent reaches init subcommand", () => {
+  // Regression for the bug where the global --agent JSON-alias swallowed
+  // the init-level --agent flag, making `mem0 init --agent` behave like
+  // the plain interactive wizard.
+
+  it("init --agent triggers bootstrap branch (not the wizard)", () => {
+    const home = cleanHome();
+    const result = run(["init", "--agent"], {
+      home,
+      env: {
+        MEM0_BASE_URL: "http://127.0.0.1:1", // blackhole
+        FORCE_COLOR: "0",
+      },
+    });
+    const combined = (result.stdout + result.stderr).toLowerCase();
+    // Either bootstrap-attempt error, or a connection/network error —
+    // both prove the --agent path executed (the wizard would prompt for
+    // input and succeed/hang, not surface a network error).
+    expect(
+      combined.includes("agent") ||
+        combined.includes("connect") ||
+        combined.includes("network") ||
+        combined.includes("fetch") ||
+        combined.includes("bootstrap"),
+    ).toBe(true);
+    fs.rmSync(home, { recursive: true, force: true });
+  });
+});
+
+describe("JSON envelope on network failure", () => {
+  it("init --agent --json does not leak a stack trace when backend is unreachable", () => {
+    const home = cleanHome();
+    const result = run(["init", "--agent", "--json"], {
+      home,
+      env: {
+        MEM0_BASE_URL: "http://127.0.0.1:1",
+        FORCE_COLOR: "0",
+      },
+    });
+    const combined = result.stdout + result.stderr;
+    // No raw Node stack should escape the agent-mode handler.
+    expect(combined).not.toMatch(/at \w+\s*\(.+\.ts:\d+/);
+    expect(combined).not.toContain("UnhandledPromiseRejection");
+    expect(result.exitCode).not.toBe(0);
+    fs.rmSync(home, { recursive: true, force: true });
+  });
+});
+
+describe("top-level help lists init", () => {
+  // `mem0 --help` must list `init` so agents walking the top-level help
+  // can discover the Agent Mode entrypoint without prior knowledge.
+
+  it("--help lists init", () => {
+    const result = run(["--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("init");
+  });
+});

cli/node/tests/cli-integration.test.ts

@@ -44,15 +44,31 @@ describe("CLI Integration — help and version", () => {
     expect(result.stdout).toContain("search");
   });
 
-  it("help --json produces valid JSON", () => {
-    const result = run(["help", "--json"]);
-    expect(result.exitCode).toBe(0);
-    const parsed = JSON.parse(result.stdout);
-    // spec may have cli.name or top-level name
-    const name = parsed.name ?? parsed.cli?.name;
-    expect(name).toBe("mem0");
+  it("prints the version with --version", () => {
+    const flag = run(["--version"]);
+    expect(flag.exitCode).toBe(0);
+    expect(flag.stdout).toContain("Mem0");
   });
 
+  it("version subcommand output matches --version output byte-for-byte", () => {
+    const flag = run(["--version"]);
+    const cmd = run(["version"]);
+    expect(cmd.exitCode).toBe(0);
+    expect(cmd.stdout).toBe(flag.stdout);
+  });
+
+  it.each([["help", "--json"], ["--json", "help"], ["--agent", "help"]])(
+    "%s %s produces valid JSON",
+    (...args) => {
+      const result = run(args);
+      expect(result.exitCode).toBe(0);
+      const parsed = JSON.parse(result.stdout);
+      // spec may have cli.name or top-level name
+      const name = parsed.name ?? parsed.cli?.name;
+      expect(name).toBe("mem0");
+    },
+  );
+
   it("shows add help", () => {
     const result = run(["add", "--help"]);
     expect(result.exitCode).toBe(0);
@@ -107,22 +123,29 @@ describe("CLI Integration — help and version", () => {
     expect(result.exitCode).toBe(0);
   });
 
-  it("add help has --graph flag", () => {
+  it("add help has --output flag", () => {
     const result = run(["add", "--help"]);
     expect(result.exitCode).toBe(0);
-    expect(result.stdout).toContain("--graph");
+    expect(result.stdout).toContain("--output");
   });
 
-  it("search help has --graph flag", () => {
+  it("search help has --rerank flag", () => {
     const result = run(["search", "--help"]);
     expect(result.exitCode).toBe(0);
-    expect(result.stdout).toContain("--graph");
+    expect(result.stdout).toContain("--rerank");
   });
 
-  it("list help has --graph flag", () => {
+  it("search help documents the --filter JSON shape with an example", () => {
+    const result = run(["search", "--help"]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toContain("AND");
+    expect(result.stdout).toContain("categories");
+  });
+
+  it("list help has --category flag", () => {
     const result = run(["list", "--help"]);
     expect(result.exitCode).toBe(0);
-    expect(result.stdout).toContain("--graph");
+    expect(result.stdout).toContain("--category");
   });
 });
 

cli/node/tests/config.test.ts

@@ -64,7 +64,6 @@ describe("createDefaultConfig", () => {
     expect(config.platform.baseUrl).toBe("https://api.mem0.ai");
     expect(config.platform.apiKey).toBe("");
     expect(config.defaults.userId).toBe("");
-    expect(config.defaults.enableGraph).toBe(false);
   });
 });
 
@@ -105,9 +104,4 @@ describe("setNestedValue", () => {
     expect(config.defaults.userId).toBe("bob");
   });
 
-  it("coerces boolean for enable_graph", () => {
-    const config = createDefaultConfig();
-    expect(setNestedValue(config, "defaults.enable_graph", "true")).toBe(true);
-    expect(config.defaults.enableGraph).toBe(true);
-  });
 });

cli/node/tests/init-internals.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Unit tests for init internals — decision tree primitives + plugin sync.
+ *
+ * Mirror of `cli/python/tests/test_init_internals.py`. Both files MUST stay
+ * in sync — if you add a behavioral assertion here, mirror it on the Python
+ * side and vice versa.
+ *
+ *  - `pingKey` must NOT treat network errors as "invalid key" (else a VPN
+ *    flap silently mints a new shadow over a working key).
+ *  - `plugin_sync` must only update entries that already exist, preserve
+ *    trailing newlines, and never mangle other lines.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { pingKey } from "../src/commands/init.js";
+import { updateClaudeSettings, updateShellRc } from "../src/plugin-sync.js";
+
+// ── pingKey ──────────────────────────────────────────────────────────────
+
+describe("pingKey — network vs auth distinction", () => {
+	const origFetch = globalThis.fetch;
+	afterEach(() => {
+		globalThis.fetch = origFetch;
+		vi.restoreAllMocks();
+	});
+
+	it("returns true for 200", async () => {
+		globalThis.fetch = vi.fn().mockResolvedValue({ status: 200 } as Response);
+		await expect(pingKey("k", "http://x")).resolves.toBe(true);
+	});
+
+	it("returns false for 401 (definitively invalid)", async () => {
+		globalThis.fetch = vi.fn().mockResolvedValue({ status: 401 } as Response);
+		await expect(pingKey("k", "http://x")).resolves.toBe(false);
+	});
+
+	it("returns false for 403 (definitively invalid)", async () => {
+		globalThis.fetch = vi.fn().mockResolvedValue({ status: 403 } as Response);
+		await expect(pingKey("k", "http://x")).resolves.toBe(false);
+	});
+
+	it("returns true for 5xx (transient upstream — prefer reuse)", async () => {
+		globalThis.fetch = vi.fn().mockResolvedValue({ status: 503 } as Response);
+		await expect(pingKey("k", "http://x")).resolves.toBe(true);
+	});
+
+	it("returns true on network error (prefer reuse over re-mint)", async () => {
+		globalThis.fetch = vi.fn().mockRejectedValue(new Error("ECONNREFUSED"));
+		await expect(pingKey("k", "http://x")).resolves.toBe(true);
+	});
+
+	it("returns true on timeout (prefer reuse)", async () => {
+		globalThis.fetch = vi.fn().mockRejectedValue(new Error("aborted"));
+		await expect(pingKey("k", "http://x")).resolves.toBe(true);
+	});
+});
+
+// ── updateShellRc ────────────────────────────────────────────────────────
+
+describe("updateShellRc — exists-only contract", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "mem0-test-"));
+	});
+	afterEach(() => {
+		fs.rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	it("updates existing export and preserves trailing newline", () => {
+		const rc = path.join(tmpDir, ".zshrc");
+		fs.writeFileSync(rc, 'export MEM0_API_KEY="old"\n');
+		expect(updateShellRc(rc, "newkey")).toBe(true);
+		expect(fs.readFileSync(rc, "utf-8")).toBe('export MEM0_API_KEY="newkey"\n');
+	});
+
+	it("does NOT create a new export when none exists", () => {
+		const rc = path.join(tmpDir, ".zshrc");
+		fs.writeFileSync(rc, "alias ll='ls -la'\n");
+		expect(updateShellRc(rc, "newkey")).toBe(false);
+		expect(fs.readFileSync(rc, "utf-8")).toBe("alias ll='ls -la'\n");
+	});
+
+	it("preserves surrounding content", () => {
+		const rc = path.join(tmpDir, ".zshrc");
+		const original =
+			"# my zshrc\n" +
+			"alias ll='ls -la'\n" +
+			"export MEM0_API_KEY='old'\n" +
+			"export OTHER=keepme\n";
+		fs.writeFileSync(rc, original);
+		updateShellRc(rc, "newkey");
+		const after = fs.readFileSync(rc, "utf-8");
+		expect(after).toContain("alias ll='ls -la'\n");
+		expect(after).toContain("export OTHER=keepme\n");
+		expect(after).toContain("# my zshrc\n");
+		expect(after).toContain('export MEM0_API_KEY="newkey"\n');
+	});
+
+	it("is idempotent when value already matches", () => {
+		const rc = path.join(tmpDir, ".zshrc");
+		fs.writeFileSync(rc, 'export MEM0_API_KEY="same"\n');
+		expect(updateShellRc(rc, "same")).toBe(false);
+	});
+
+	it("is a no-op for missing files", () => {
+		const rc = path.join(tmpDir, ".zshrc"); // does not exist
+		expect(updateShellRc(rc, "x")).toBe(false);
+	});
+});
+
+// ── updateClaudeSettings ─────────────────────────────────────────────────
+
+describe("updateClaudeSettings — never creates entries", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "mem0-test-"));
+	});
+	afterEach(() => {
+		fs.rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	it("does not create env block when none exists", () => {
+		const settings = path.join(tmpDir, "settings.json");
+		fs.writeFileSync(settings, JSON.stringify({ otherKey: 1 }));
+		expect(updateClaudeSettings(settings, "newkey")).toBe(false);
+		expect(JSON.parse(fs.readFileSync(settings, "utf-8"))).toEqual({
+			otherKey: 1,
+		});
+	});
+
+	it("does not create MEM0_API_KEY entry in existing env block", () => {
+		const settings = path.join(tmpDir, "settings.json");
+		fs.writeFileSync(settings, JSON.stringify({ env: { OTHER_KEY: "x" } }));
+		expect(updateClaudeSettings(settings, "newkey")).toBe(false);
+	});
+
+	it("updates existing entry and preserves siblings", () => {
+		const settings = path.join(tmpDir, "settings.json");
+		fs.writeFileSync(
+			settings,
+			JSON.stringify({ env: { MEM0_API_KEY: "old", OTHER: "y" } }, null, 2),
+		);
+		expect(updateClaudeSettings(settings, "fresh")).toBe(true);
+		const data = JSON.parse(fs.readFileSync(settings, "utf-8"));
+		expect(data.env.MEM0_API_KEY).toBe("fresh");
+		expect(data.env.OTHER).toBe("y");
+	});
+
+	it("is idempotent when value already matches", () => {
+		const settings = path.join(tmpDir, "settings.json");
+		fs.writeFileSync(
+			settings,
+			JSON.stringify({ env: { MEM0_API_KEY: "same" } }),
+		);
+		expect(updateClaudeSettings(settings, "same")).toBe(false);
+	});
+
+	it("is a no-op for malformed JSON", () => {
+		const settings = path.join(tmpDir, "settings.json");
+		fs.writeFileSync(settings, "{ this is not json");
+		expect(updateClaudeSettings(settings, "x")).toBe(false);
+	});
+});

cli/node/tests/option-parity.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Drift test: every documented v3 add/search/list param must be reachable from the Node CLI.
+ */
+
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+const OPENAPI_PATH = path.join(
+	__dirname,
+	"..",
+	"..",
+	"..",
+	"docs",
+	"openapi.json",
+);
+
+const KNOWN_UNSURFACED: Record<string, Record<string, string>> = {
+	"/v3/memories/add/": {
+		includes: "extraction hint, no CLI flag yet",
+		excludes: "extraction hint, no CLI flag yet",
+		enable_graph: "graph memory toggle, no CLI flag yet",
+		output_format: "response envelope is pinned by the CLI",
+		prompt_profile_id: "no CLI flag yet",
+		temporal_reasoning: "no CLI flag yet",
+		timezone: "no CLI flag yet",
+		observation_datetime: "no CLI flag yet, --timestamp backdates instead",
+		observation_date: "no CLI flag yet, --timestamp backdates instead",
+	},
+	"/v3/memories/search/": {
+		categories: "expressible through --filter",
+		metadata: "expressible through --filter",
+	},
+	"/v3/memories/": {
+		start_date: "covered by --after via filters.created_at.gte",
+		end_date: "covered by --before via filters.created_at.lte",
+		categories: "covered by --category via filters.categories",
+		fields: "no CLI flag yet",
+		keywords: "no CLI flag yet",
+	},
+};
+
+const ADD_MAPPING: Record<string, string[]> = {
+	messages: ["--messages", "--file", "text"],
+	user_id: ["--user-id"],
+	agent_id: ["--agent-id"],
+	app_id: ["--app-id"],
+	run_id: ["--run-id"],
+	metadata: ["--metadata"],
+	expiration_date: ["--expires"],
+	custom_instructions: ["--custom-instructions"],
+	agent_custom_instructions: ["--agent-custom-instructions"],
+	custom_categories: ["--custom-categories"],
+	infer: ["--no-infer"],
+	immutable: ["--immutable"],
+	structured_data_schema: ["--structured-data-schema"],
+	timestamp: ["--timestamp"],
+};
+
+const SEARCH_MAPPING: Record<string, string[]> = {
+	query: ["query"],
+	filters: ["--filter", "--user-id", "--agent-id", "--run-id"],
+	show_expired: ["--show-expired"],
+	top_k: ["--top-k"],
+	threshold: ["--threshold"],
+	rerank: ["--rerank"],
+	reference_date: ["--reference-date"],
+	fields: ["--fields"],
+};
+
+const LIST_MAPPING: Record<string, string[]> = {
+	filters: [
+		"--user-id",
+		"--agent-id",
+		"--run-id",
+		"--category",
+		"--after",
+		"--before",
+	],
+	show_expired: ["--show-expired"],
+	page: ["--page"],
+	page_size: ["--page-size"],
+};
+
+function documentedFields(endpoint: string): string[] {
+	const spec = JSON.parse(fs.readFileSync(OPENAPI_PATH, "utf-8"));
+	const schema =
+		spec.paths[endpoint].post.requestBody.content["application/json"].schema;
+	return Object.keys(schema.properties);
+}
+
+function helpText(command: string): string {
+	return execSync(`npx tsx src/index.ts ${command} --help`, {
+		cwd: path.join(__dirname, ".."),
+		encoding: "utf-8",
+		timeout: 15000,
+	});
+}
+
+function assertAllReachable(
+	endpoint: string,
+	mapping: Record<string, string[]>,
+	command: string,
+) {
+	const documented = documentedFields(endpoint);
+	const help = helpText(command);
+	for (const field of documented) {
+		if (KNOWN_UNSURFACED[endpoint]?.[field]) continue;
+		const candidates = mapping[field];
+		expect(
+			candidates,
+			`${endpoint}: documented field "${field}" has no mapping entry for command "${command}"`,
+		).toBeDefined();
+		const reachable = candidates.some((flag) =>
+			flag.startsWith("--") ? help.includes(flag) : true,
+		);
+		expect(
+			reachable,
+			`${endpoint}: documented field "${field}" not reachable via any of ${JSON.stringify(candidates)} on command "${command}"`,
+		).toBe(true);
+	}
+}
+
+describe("Option parity: Node CLI reachability of documented v3 params", () => {
+	it("add covers documented fields", () => {
+		assertAllReachable("/v3/memories/add/", ADD_MAPPING, "add");
+	});
+
+	it("search covers documented fields", () => {
+		assertAllReachable("/v3/memories/search/", SEARCH_MAPPING, "search");
+	});
+
+	it("list covers documented fields", () => {
+		assertAllReachable("/v3/memories/", LIST_MAPPING, "list");
+	});
+});
+
+describe("stdin fallback uses the shared piped-stdin guard", () => {
+	const SOURCES = ["src/index.ts", "src/commands/memory.ts"];
+
+	for (const rel of SOURCES) {
+		it(`${rel} never checks process.stdin.isTTY directly`, () => {
+			const src = fs.readFileSync(path.join(__dirname, "..", rel), "utf-8");
+			expect(
+				src.includes("process.stdin.isTTY"),
+				`${rel}: use stdinIsPiped() from state.ts. A bare !isTTY check is also true for /dev/null and sockets, so readFileSync(0) crashes with EAGAIN in scripts, CI, and agent mode.`,
+			).toBe(false);
+		});
+
+		it(`${rel} guards every readFileSync(0) with stdinIsPiped()`, () => {
+			const src = fs.readFileSync(path.join(__dirname, "..", rel), "utf-8");
+			const lines = src.split("\n");
+			for (const [i, line] of lines.entries()) {
+				if (!line.includes("readFileSync(0")) continue;
+				const guard = lines.slice(Math.max(0, i - 3), i).join("\n");
+				expect(
+					guard.includes("stdinIsPiped()"),
+					`${rel}:${i + 1}: readFileSync(0) must be guarded by stdinIsPiped()`,
+				).toBe(true);
+			}
+		});
+	}
+});

cli/node/tests/platform-backend.test.ts

@@ -0,0 +1,242 @@
+/**
+ * Tests for the Platform backend (mem0 Platform API client).
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { PlatformBackend } from "../src/backend/platform.js";
+import { createDefaultConfig } from "../src/config.js";
+
+function makeBackend(): PlatformBackend {
+	return new PlatformBackend(createDefaultConfig().platform);
+}
+
+function mockFetch() {
+	const fetchMock = vi.fn().mockResolvedValue({
+		ok: true,
+		status: 200,
+		headers: { get: vi.fn().mockReturnValue(null) },
+		json: vi.fn().mockResolvedValue({ message: "ok" }),
+	});
+	vi.stubGlobal("fetch", fetchMock);
+	return fetchMock;
+}
+
+beforeEach(() => {
+	vi.restoreAllMocks();
+	vi.unstubAllGlobals();
+});
+
+describe("deleteEntities", () => {
+	it("returns all results keyed by entity type for a multi-entity delete", async () => {
+		const backend = makeBackend();
+		const responses: Record<string, unknown> = {
+			"/v2/entities/user/alice/": { message: "user deleted" },
+			"/v2/entities/agent/bob/": { message: "agent deleted" },
+		};
+		const spy = vi
+			// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+			.spyOn(backend as any, "_request")
+			.mockImplementation(
+				async (_method: string, path: string) => responses[path],
+			);
+
+		const result = await backend.deleteEntities({
+			userId: "alice",
+			agentId: "bob",
+		});
+
+		expect(result).toEqual({
+			user: { message: "user deleted" },
+			agent: { message: "agent deleted" },
+		});
+		expect(spy).toHaveBeenCalledTimes(2);
+	});
+
+	it("keys a single-entity delete by its type", async () => {
+		const backend = makeBackend();
+		// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+		vi.spyOn(backend as any, "_request").mockResolvedValue({
+			message: "user deleted",
+		});
+
+		const result = await backend.deleteEntities({ userId: "alice" });
+		expect(result).toEqual({ user: { message: "user deleted" } });
+	});
+
+	it("throws when no entity id is provided", async () => {
+		const backend = makeBackend();
+		await expect(backend.deleteEntities({})).rejects.toThrow(
+			"At least one entity ID is required",
+		);
+	});
+});
+
+describe("PlatformBackend option-parity payloads (MEM-5893)", () => {
+	it("add: custom_instructions, custom_categories, structured_data_schema, timestamp reach the payload alongside existing fields", async () => {
+		const backend = makeBackend();
+		const spy = vi
+			// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+			.spyOn(backend as any, "_request")
+			.mockResolvedValue({ results: [] });
+
+		await backend.add("hello", undefined, {
+			userId: "alice",
+			metadata: { source: "test" },
+			expires: "2099-01-01",
+			customInstructions: "Extract only preferences.",
+			agentCustomInstructions: "Extract only tool outcomes.",
+			customCategories: [{ prefs: "user preferences" }],
+			structuredDataSchema: { type: "object" },
+			timestamp: 1700000000,
+		});
+
+		const payload = spy.mock.calls[0][2].json;
+		expect(payload.custom_instructions).toBe("Extract only preferences.");
+		expect(payload.agent_custom_instructions).toBe(
+			"Extract only tool outcomes.",
+		);
+		expect(payload.custom_categories).toEqual([{ prefs: "user preferences" }]);
+		expect(payload.structured_data_schema).toEqual({ type: "object" });
+		expect(payload.timestamp).toBe(1700000000);
+		expect(payload.metadata).toEqual({ source: "test" });
+		expect(payload.expiration_date).toBe("2099-01-01");
+	});
+
+	it("add: omitted optional fields are absent from the payload", async () => {
+		const backend = makeBackend();
+		const spy = vi
+			// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+			.spyOn(backend as any, "_request")
+			.mockResolvedValue({ results: [] });
+
+		await backend.add("hello", undefined, { userId: "alice" });
+
+		const payload = spy.mock.calls[0][2].json;
+		expect(payload).not.toHaveProperty("custom_instructions");
+		expect(payload).not.toHaveProperty("agent_custom_instructions");
+		expect(payload).not.toHaveProperty("custom_categories");
+		expect(payload).not.toHaveProperty("structured_data_schema");
+		expect(payload).not.toHaveProperty("timestamp");
+	});
+
+	it("search: show_expired, reference_date, latest_only reach the payload", async () => {
+		const backend = makeBackend();
+		// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+		const spy = vi.spyOn(backend as any, "_request").mockResolvedValue([]);
+
+		await backend.search("query", {
+			showExpired: true,
+			referenceDate: "2024-01-01",
+			latestOnly: true,
+		});
+
+		const payload = spy.mock.calls[0][2].json;
+		expect(payload.show_expired).toBe(true);
+		expect(payload.reference_date).toBe("2024-01-01");
+		expect(payload.latest_only).toBe(true);
+	});
+
+	it("search: keyword_search and fields reach the payload", async () => {
+		const backend = makeBackend();
+		// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+		const spy = vi.spyOn(backend as any, "_request").mockResolvedValue([]);
+
+		await backend.search("query", {
+			keyword: true,
+			fields: ["memory", "score"],
+		});
+
+		const payload = spy.mock.calls[0][2].json;
+		expect(payload.keyword_search).toBe(true);
+		expect(payload.fields).toEqual(["memory", "score"]);
+	});
+
+	it("search: omitted keyword and fields are absent from the payload", async () => {
+		const backend = makeBackend();
+		// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+		const spy = vi.spyOn(backend as any, "_request").mockResolvedValue([]);
+
+		await backend.search("query", {});
+
+		const payload = spy.mock.calls[0][2].json;
+		expect(payload).not.toHaveProperty("keyword_search");
+		expect(payload).not.toHaveProperty("fields");
+	});
+
+	it("listMemories: show_expired and latest_only are top-level, not nested inside filters", async () => {
+		const backend = makeBackend();
+		// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+		const spy = vi.spyOn(backend as any, "_request").mockResolvedValue([]);
+
+		await backend.listMemories({
+			userId: "alice",
+			showExpired: true,
+			latestOnly: true,
+		});
+
+		const payload = spy.mock.calls[0][2].json;
+		expect(payload.show_expired).toBe(true);
+		expect(payload.latest_only).toBe(true);
+		expect(payload.filters ?? {}).not.toHaveProperty("show_expired");
+		expect(payload.filters ?? {}).not.toHaveProperty("latest_only");
+	});
+
+	it("update: expiration_date and timestamp reach the payload", async () => {
+		const backend = makeBackend();
+		// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+		const spy = vi.spyOn(backend as any, "_request").mockResolvedValue({});
+
+		await backend.update("mem-123", undefined, undefined, {
+			expirationDate: "2099-01-01",
+			timestamp: 1700000000,
+		});
+
+		const payload = spy.mock.calls[0][2].json;
+		expect(payload.expiration_date).toBe("2099-01-01");
+		expect(payload.timestamp).toBe(1700000000);
+	});
+
+	it("delete: delete_linked is a query param, not part of the JSON body", async () => {
+		const backend = makeBackend();
+		// biome-ignore lint/suspicious/noExplicitAny: spying on a private method
+		const spy = vi.spyOn(backend as any, "_request").mockResolvedValue({});
+
+		await backend.delete("mem-123", { deleteLinked: true });
+
+		const opts = spy.mock.calls[0][2];
+		expect(opts.params.delete_linked).toBe("true");
+		expect(opts.json).toBeUndefined();
+	});
+});
+
+describe("PlatformBackend path encoding", () => {
+	it("encodes memory IDs before interpolating them into paths", async () => {
+		const fetchMock = mockFetch();
+		const backend = makeBackend();
+
+		await backend.get("mem/a?b#c");
+		await backend.update("mem/a?b#c", "updated");
+		await backend.delete("mem/a?b#c");
+
+		const urls = fetchMock.mock.calls.map((call) => call[0]);
+		expect(urls).toEqual([
+			"https://api.mem0.ai/v1/memories/mem%2Fa%3Fb%23c/?source=CLI",
+			"https://api.mem0.ai/v1/memories/mem%2Fa%3Fb%23c/",
+			"https://api.mem0.ai/v1/memories/mem%2Fa%3Fb%23c/?source=CLI",
+		]);
+	});
+
+	it("encodes entity and event IDs before interpolating them into paths", async () => {
+		const fetchMock = mockFetch();
+		const backend = makeBackend();
+
+		await backend.deleteEntities({ userId: "org/team?active#frag" });
+		await backend.getEvent("evt/a?b#c");
+
+		const urls = fetchMock.mock.calls.map((call) => call[0]);
+		expect(urls).toEqual([
+			"https://api.mem0.ai/v2/entities/user/org%2Fteam%3Factive%23frag/?source=CLI",
+			"https://api.mem0.ai/v1/event/evt%2Fa%3Fb%23c/",
+		]);
+	});
+});