feat(integrations): add Hermes provider with shared memory utilities

Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>

.agents/plugins/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"
+    }
+  ]
+}

.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "mem0-plugins",
+  "owner": {
+    "name": "Mem0",
+    "email": "support@mem0.ai"
+  },
+  "metadata": {
+    "description": "Official Mem0 plugins for Claude"
+  },
+  "plugins": [
+    {
+      "name": "mem0",
+      "source": "./integrations/claude-code-plugin",
+      "description": "Cross-session memory and token savings for coding agents.",
+      "version": "0.3.1"
+    }
+  ]
+}

.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

@@ -0,0 +1,18 @@
+{
+  "name": "mem0-plugins",
+  "owner": {
+    "name": "Mem0",
+    "email": "support@mem0.ai"
+  },
+  "metadata": {
+    "description": "Official Mem0 plugins for Cursor"
+  },
+  "plugins": [
+    {
+      "name": "mem0",
+      "source": "./integrations/cursor-plugin",
+      "description": "Cross-session memory and token savings for coding agents.",
+      "version": "0.3.1"
+    }
+  ]
+}

.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

@@ -1,41 +1,93 @@
-name: 🐛 Bug Report
-description: Create a report to help us reproduce and fix the bug
+name: Bug Report
+description: Report a bug in mem0
+labels: ["bug"]
 
 body:
-- type: markdown
-  attributes:
-    value: >
-      #### Before submitting a bug, please make sure the issue hasn't been already addressed by searching through [the existing and past issues](https://github.com/embedchain/embedchain/issues?q=is%3Aissue+sort%3Acreated-desc+).
-- type: textarea
-  attributes:
-    label: 🐛 Describe the bug
-    description: |
-      Please provide a clear and concise description of what the bug is.
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which part of mem0 is affected?
+      options:
+        - Python SDK
+        - TypeScript SDK
+        - Vector Store
+        - Plugin
+        - REST API
+        - Other
+    validations:
+      required: true
 
-      If relevant, add a minimal example so that we can reproduce the error by running the code. It is very important for the snippet to be as succinct (minimal) as possible, so please take time to trim down any irrelevant code to help us debug efficiently. We are going to copy-paste your code and we expect to get the same result as you did: avoid any external data, and include the relevant imports, etc. For example:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      value: |
+        ### Summary
 
-      ```python
-      # All necessary imports at the beginning
-      import embedchain as ec
-      # Your code goes here
+        A clear summary of the bug.
 
+        ### Steps to Reproduce
 
-      ```
+        ```python
+        from mem0 import Memory
 
-      Please also paste or describe the results you observe instead of the expected results. If you observe an error, please paste the error message including the **full** traceback of the exception. It may be relevant to wrap error messages in ```` ```triple quotes blocks``` ````.
-    placeholder: |
-      A clear and concise description of what the bug is.
+        m = Memory()
+        # Your code here...
+        ```
 
-      ```python
-      Sample code to reproduce the problem
-      ```
+        ### Expected Behavior
 
-      ```
-      The error message you got, with the full traceback.
-      ````
-  validations:
-    required: true
-- type: markdown
-  attributes:
-    value: >
-      Thanks for contributing 🎉!
+        What you expected to happen.
+
+        ### Actual Behavior
+
+        What actually happened. Paste the full error traceback if applicable.
+
+        ### Environment
+
+        - mem0 version:
+        - Python/Node version:
+        - 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: 1-on-1 Session
-    url: https://cal.com/taranjeetio/ec
-    about: Speak directly with Taranjeet, the founder, to discuss issues, share feedback, or explore improvements for Embedchain
-  - name: Discord
+  - name: Question or general help
     url: https://discord.gg/6PzXDgEjG5
-    about: General community discussions
+    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

@@ -1,11 +1,37 @@
-name: Documentation
-description: Report an issue related to the Embedchain docs.
-title: "DOC: <Please write a comprehensive title after the 'DOC: ' prefix>"
+name: Documentation Issue
+description: Report an issue or suggest an improvement to the mem0 docs
+labels: ["documentation"]
 
 body:
-- type: textarea
-  attributes:
-    label: "Issue with current documentation:"
-    description: >
-      Please make sure to leave a reference to the document/code you're
-      referring to.
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      value: |
+        ### Page
+
+        Link to the docs page: https://docs.mem0.ai/...
+
+        ### What's Wrong or Missing
+
+        Describe what's incorrect, unclear, or missing.
+
+        ### Suggested Fix
+
+        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

@@ -1,23 +1,53 @@
-name: 🚀 Feature request
-description: Submit a proposal/request for a new Embedchain feature
+name: Feature Request
+description: Suggest a new feature or improvement for mem0
+labels: ["enhancement"]
 
 body:
-- type: textarea
-  id: feature-request
-  attributes:
-    label: 🚀 The feature
-    description: >
-      A clear and concise description of the feature proposal
-  validations:
-    required: true
-- type: textarea
-  attributes:
-    label: Motivation, pitch
-    description: >
-      Please outline the motivation for the proposal. Is your feature request related to a specific problem? e.g., *"I'm working on X and would like Y to be possible"*. If this is related to another GitHub issue, please link here too.
-  validations:
-    required: true
-- type: markdown
-  attributes:
-    value: >
-      Thanks for contributing 🎉!
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which part of mem0 does this relate to?
+      options:
+        - Python SDK
+        - TypeScript SDK
+        - Vector Store
+        - Plugin
+        - REST API
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      value: |
+        ### Use Case
+
+        What problem are you trying to solve?
+
+        ### Proposed Solution
+
+        How should this work? Include API examples or pseudocode if helpful.
+
+        ### Alternatives Considered
+
+        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

@@ -1,41 +1,50 @@
+## Linked Issue
+
+Closes #<!-- issue number -->
+
 ## Description
 
-Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.
+<!-- What does this PR do? Why is it needed? -->
 
-Fixes # (issue)
+## Type of Change
 
-## Type of change
-
-Please delete options that are not relevant.
-
-- [ ] Bug fix (non-breaking change which fixes an issue)
-- [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
-- [ ] Refactor (does not change functionality, e.g. code style improvements, linting)
+- [ ] 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
 
-## How Has This Been Tested?
+## AI Assistance
 
-Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration
+<!-- This is about the code, not this description. Writing the description with AI is fine. -->
 
-Please delete options that are not relevant.
+- [ ] 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)
 
-- [ ] Unit Test
-- [ ] Test Script (please provide)
+<!-- If you ticked either AI box, name the tool and what you checked yourself. -->
 
-## Checklist:
+- [ ] **I can explain every line of this diff and how it interacts with the rest of the codebase, without asking an AI tool.**
 
-- [ ] My code follows the style guidelines of this project
-- [ ] I have performed a self-review of my own code
-- [ ] I have commented my code, particularly in hard-to-understand areas
-- [ ] I have made corresponding changes to the documentation
-- [ ] My changes generate no new warnings
-- [ ] I have added tests that prove my fix is effective or that my feature works
-- [ ] New and existing unit tests pass locally with my changes
-- [ ] Any dependent changes have been merged and published in downstream modules
-- [ ] I have checked my code and corrected any misspellings
+## Breaking Changes
 
-## Maintainer Checklist
+<!-- If this is a breaking change, describe what breaks and the migration path. Delete this section if not applicable. -->
 
-- [ ] closes #xxxx (Replace xxxx with the GitHub issue number)
-- [ ] Made sure Checks passed
+N/A
+
+## Test Coverage
+
+- [ ] I added/updated unit tests
+- [ ] I added/updated integration tests
+- [ ] I tested manually (describe below)
+- [ ] No tests needed (explain why)
+
+<!-- Describe how you tested this, or link to CI results. -->
+
+## 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

.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

@@ -0,0 +1,15 @@
+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,17 +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
+    # 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
@@ -38,7 +54,6 @@ jobs:
       #     packages_dir: dist/
 
       - name: Publish distribution 📦 to PyPI
-        if: startsWith(github.ref, 'refs/tags')
         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

@@ -0,0 +1,60 @@
+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:
+  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(inputs.tag, 'cli-node-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: cli/node
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
+
+      - 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'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+          cache-dependency-path: cli/node/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - 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/cli-node-ci.yml

@@ -0,0 +1,99 @@
+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:
+    branches: [main]
+    paths:
+      - 'cli/node/**'
+      - '.github/workflows/cli-node-ci.yml'
+  workflow_call:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          cache-dependency-path: cli/node/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: cli/node
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        working-directory: cli/node
+        run: pnpm run lint
+
+      - name: Type check
+        working-directory: cli/node
+        run: pnpm run typecheck
+
+  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: 10
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'pnpm'
+          cache-dependency-path: cli/node/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: cli/node
+        run: pnpm install --frozen-lockfile
+
+      - name: Run tests
+        working-directory: cli/node
+        run: pnpm run test
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+          cache-dependency-path: cli/node/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: cli/node
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        working-directory: cli/node
+        run: pnpm run build
+
+      - name: Verify dist output
+        run: |
+          test -f cli/node/dist/index.js || (echo "Build output missing: dist/index.js" && exit 1)

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

@@ -0,0 +1,47 @@
+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:
+  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(inputs.tag, 'cli-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: cli/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: cli/python/dist/

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

@@ -0,0 +1,78 @@
+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:
+    branches: [main]
+    paths:
+      - 'cli/python/**'
+      - '.github/workflows/cli-python-ci.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: cli/python
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        working-directory: cli/python
+        run: ruff check .
+
+      - name: Check formatting
+        working-directory: cli/python
+        run: ruff format --check .
+
+  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: cli/python
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        working-directory: cli/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: cli/python
+        run: hatch build --clean
+
+      - name: Verify dist output
+        run: |
+          ls cli/python/dist/*.whl || (echo "Wheel file missing" && exit 1)
+          ls cli/python/dist/*.tar.gz || (echo "Source dist missing" && exit 1)

.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

@@ -0,0 +1,67 @@
+name: Auto-label issues
+
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  contents: read
+  issues: write
+
+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 }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          config-path: .github/advanced-issue-labeler.yml
+
+      - name: Infer component from text when the form was not used
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const {
+              componentLabels,
+              inferComponentLabels,
+              loadKeywords,
+            } = require(`${process.env.GITHUB_WORKSPACE}/.github/scripts/infer-component-labels.js`);
+
+            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

@@ -0,0 +1,60 @@
+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:
+  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(inputs.tag, 'openclaw-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: integrations/openclaw
+    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/openclaw/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/openclaw-checks.yml

@@ -0,0 +1,98 @@
+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:
+      - 'integrations/openclaw/**'
+      - 'integrations/agent-plugin-core/typescript/**'
+      - '.github/workflows/openclaw-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/openclaw/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd integrations/openclaw && pnpm install --frozen-lockfile
+
+      - name: Type check
+        run: cd integrations/openclaw && 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/openclaw/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd integrations/openclaw && pnpm install --frozen-lockfile
+
+      - name: Run tests with 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: integrations/openclaw/coverage
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  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/openclaw/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: cd integrations/openclaw && pnpm install --frozen-lockfile
+
+      - name: Build
+        run: cd integrations/openclaw && pnpm build
+
+      - 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,40 @@
+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: 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/stale.yml

@@ -0,0 +1,48 @@
+name: Close stale issues
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v9
+        with:
+          # Issue settings
+          days-before-issue-stale: 90
+          days-before-issue-close: 14
+          stale-issue-label: 'stale'
+          stale-issue-message: >
+            This issue has been automatically marked as stale because it has not
+            had any activity in 90 days. It will be closed in 14 days if no
+            further activity occurs. If this is still relevant, please leave a
+            comment or remove the `stale` label.
+          close-issue-message: >
+            This issue has been closed due to inactivity. If this is still
+            relevant, feel free to reopen it or create a new issue.
+
+          # PR settings — mark stale but never auto-close
+          days-before-pr-stale: 90
+          days-before-pr-close: -1
+          stale-pr-label: 'stale'
+          stale-pr-message: >
+            This pull request has been automatically marked as stale because it
+            has not had any activity in 90 days. Please update your branch and
+            address any review comments, or it may be closed in the future.
+
+          # Exempt these labels from stale processing
+          exempt-issue-labels: 'P0-critical,P1-high,good first issue,security'
+          exempt-pr-labels: 'P0-critical,P1-high'
+
+          # Remove stale label when there is new activity
+          remove-stale-when-updated: true
+
+          # Process up to 100 issues per run to stay within API limits
+          operations-per-run: 100

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

@@ -0,0 +1,59 @@
+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:
+  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(inputs.tag, 'ts-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: mem0-ts
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
+
+      - 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'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+          cache-dependency-path: mem0-ts/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - 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/ts-sdk-ci.yml

@@ -0,0 +1,146 @@
+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'
+  workflow_call:
+
+jobs:
+  check_changes:
+    runs-on: ubuntu-latest
+    outputs:
+      ts_sdk_changed: ${{ steps.filter.outputs.ts_sdk }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dorny/paths-filter@v2
+        id: filter
+        with:
+          filters: |
+            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'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'pnpm'
+          cache-dependency-path: mem0-ts/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: mem0-ts
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        working-directory: mem0-ts
+        run: npx prettier --check .
+
+      - name: Build
+        working-directory: mem0-ts
+        run: pnpm run build
+
+      - name: Run unit tests
+        working-directory: mem0-ts
+        run: pnpm run test:unit
+
+      - name: Verify package exports
+        working-directory: mem0-ts
+        run: |
+          node -e "const m = require('./dist/index.js'); console.log('Client exports:', Object.keys(m).length)"
+          node -e "const m = require('./dist/oss/index.js'); console.log('OSS exports:', Object.keys(m).length)"
+
+      - name: Upload coverage
+        if: matrix.node-version == 20
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: mem0-ts/coverage/
+
+  integration_ts_sdk:
+    needs: build_ts_sdk
+    runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 1
+      matrix:
+        node-version: [20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'pnpm'
+          cache-dependency-path: mem0-ts/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: mem0-ts
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        working-directory: mem0-ts
+        run: pnpm run build
+
+      - name: Run integration tests (with cleanup)
+        working-directory: mem0-ts
+        env:
+          MEM0_API_KEY: ${{ secrets.MEM0_API_KEY }}
+        run: pnpm run test:integration

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

@@ -0,0 +1,60 @@
+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:
+  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(inputs.tag, 'vercel-ai-v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    defaults:
+      run:
+        working-directory: integrations/vercel-ai-sdk
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
+
+      - 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'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+          cache-dependency-path: integrations/vercel-ai-sdk/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - 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/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.1",
+      "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

@@ -0,0 +1,175 @@
+# AGENTS.md
+
+Context for AI coding assistants (Claude Code, Cursor, Copilot, Codex) working in the Mem0 repository.
+
+**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)
+
+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.
+
+## Do NOT
+
+- 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.
+
+## Where to look
+
+| 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 |
+
+## 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) |
+| `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 |
+
+```
+mem0 (Python SDK)          mem0-ts (TypeScript SDK)
+├── 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, OSS mode)
+cli/node/                   ──▶ mem0ai (npm)
+integrations/vercel-ai-sdk/ ──▶ ai, @ai-sdk/*
+integrations/openclaw/      ──▶ mem0ai (npm)
+```
+
+## Setup
+
+```bash
+hatch shell dev_py_3_11   # Python: creates the env with all deps
+pre-commit install        # ruff + isort on commit
+
+cd <ts-package> && pnpm install
+```
+
+Requirements: Python 3.9+ (3.10+ for the CLI), Node 18+ (20 or 22 preferred), pnpm 10+, hatch, Docker for `server/`.
+
+## 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
+git submodule update --init evaluation
+```
+
+## What to ship with a change
+
+Guidelines, not rules. Trivial fixes need less; anything user-facing needs more.
+
+| 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. |
+
+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.
+
+## Contributing
+
+Full guide: [`CONTRIBUTING.md`](CONTRIBUTING.md). Conduct: [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).
+
+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.**
+
+### Two gates decide whether your pull request stays open
+
+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.
+
+**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.
+
+**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:
+
+| 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 |
+
+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.
+
+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.
+
+### The CLA is not optional
+
+**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.
+
+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.
+
+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.
+
+### What gets a pull request closed
+
+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:
+
+- **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.
+
+### Reference
+
+| 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` |
+| 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) |

CLAUDE.md

@@ -0,0 +1 @@
+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,63 +1,256 @@
-# 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()`.
+
+## Good Contribution Practices
+
+- **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`.
+
+## Pull Request Checklist
+
+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 |
+|---------|----------|------------|---------|
+| `mem0ai` (Python SDK) | PyPI | `v*` | `v0.1.31` |
+| `mem0-cli` (Python CLI) | PyPI | `cli-v*` | `cli-v0.2.1` |
+| `mem0ai` (TypeScript SDK) | npm | `ts-v*` | `ts-v2.4.6` |
+| `@mem0/cli` (Node CLI) | npm | `cli-node-v*` | `cli-node-v0.1.2` |
+| `@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
+
+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
+
+- **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

@@ -266,14 +266,14 @@ config = MemoryConfig(
     graph_store=GraphStoreConfig(provider="neo4j", config={...}),  # optional
     history_db_path="~/.mem0/history.db",
     version="v1.1",
-    custom_fact_extraction_prompt="Custom prompt...",
+    custom_instructions="Custom prompt...",
     custom_update_memory_prompt="Custom prompt..."
 )
 ```
 
 ### Supported Providers
 
-#### LLM Providers (19 supported)
+#### LLM Providers (20 supported)
 - **openai** - OpenAI GPT models (default)
 - **anthropic** - Claude models
 - **gemini** - Google Gemini
@@ -284,6 +284,7 @@ config = MemoryConfig(
 - **azure_openai** - Azure OpenAI
 - **litellm** - LiteLLM proxy
 - **deepseek** - DeepSeek models
+- **minimax** - MiniMax models
 - **xai** - xAI models
 - **sarvam** - Sarvam AI
 - **lmstudio** - LM Studio local server
@@ -683,7 +684,7 @@ Conversation: {messages}
 """
 
 config = MemoryConfig(
-    custom_fact_extraction_prompt=custom_extraction_prompt
+    custom_instructions=custom_extraction_prompt
 )
 memory = Memory(config)
 ```
@@ -1025,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
@@ -1312,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

@@ -15,8 +15,6 @@
   <a href="https://mem0.dev/DiG">Join Discord</a>
   ·
   <a href="https://mem0.dev/demo">Demo</a>
-  ·
-  <a href="https://mem0.dev/openmemory">OpenMemory</a>
 </p>
 
 <p align="center">
@@ -41,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
@@ -73,31 +86,116 @@
 
 ## 🚀 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
 ```
 
+For enhanced hybrid search with BM25 keyword matching and entity extraction, install with NLP support:
+
+```bash
+pip install mem0ai[nlp]
+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:
+
+```bash
+npm install -g @mem0/cli   # or: pip install mem0-cli
+
+mem0 init
+mem0 add "Prefers dark mode and vim keybindings" --user-id alice
+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.
 
 First step is to instantiate the memory:
 
@@ -110,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
@@ -150,7 +248,7 @@ For detailed integration steps, see the [Quickstart](https://docs.mem0.ai/quicks
 ## 📚 Documentation & Support
 
 - Full docs: https://docs.mem0.ai
-- Community: [Discord](https://mem0.dev/DiG) · [Twitter](https://x.com/mem0ai)
+- Community: [Discord](https://mem0.dev/DiG) · [X (formerly Twitter)](https://x.com/mem0ai)
 - Contact: founders@mem0.ai
 
 ## Citation
@@ -168,4 +266,4 @@ We now have a paper you can cite:
 
 ## ⚖️ License
 
-Apache 2.0 — see the [LICENSE](https://github.com/mem0ai/mem0/blob/main/LICENSE) file for details.
+Apache 2.0 — see the [LICENSE](https://github.com/mem0ai/mem0/blob/main/LICENSE) file for details.

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

@@ -0,0 +1,135 @@
+# mem0 CLI
+
+The official command-line interface for [mem0](https://mem0.ai) — the memory layer for AI agents. Works with the Mem0 Platform API. Available in Python and Node.js.
+
+> **For AI agents:** pass `--agent` (or `--json`) on any command for structured JSON output purpose-built for tool loops — sanitized fields, no colors or spinners, errors as JSON. See [Agent mode](#agent-mode) below.
+
+## Installation
+
+```bash
+npm install -g @mem0/cli
+```
+
+```bash
+pip install mem0-cli
+```
+
+Both packages install a `mem0` binary with identical behavior.
+
+## Quick start
+
+```bash
+# Interactive setup wizard
+mem0 init
+
+# Or login via email (get a new API key)
+mem0 init --email alice@company.com
+
+# Or authenticate with an existing API key
+mem0 init --api-key m0-xxx
+
+# Add a memory
+mem0 add "I prefer dark mode and use vim keybindings" --user-id alice
+
+# Search memories
+mem0 search "What are Alice's preferences?" --user-id alice
+
+# List all memories for a user
+mem0 list --user-id alice
+
+# Update a memory
+mem0 update <memory-id> "I switched to light mode"
+
+# Delete a memory
+mem0 delete <memory-id>
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `mem0 init` | Setup wizard — login via email or configure API key manually |
+| `mem0 add` | Add a memory from text, JSON messages, a file, or stdin |
+| `mem0 search` | Search memories using natural language |
+| `mem0 list` | List memories with optional filters and pagination |
+| `mem0 get` | Retrieve a specific memory by ID |
+| `mem0 update` | Update the text or metadata of a memory |
+| `mem0 delete` | Delete a memory, all memories for a scope, or an entity |
+| `mem0 import` | Bulk import memories from a JSON file |
+| `mem0 config` | View or modify CLI configuration |
+| `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 |
+
+Run `mem0 <command> --help` for detailed usage on any command, or `mem0 --version` to print the CLI 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:
+
+```bash
+mem0 --agent search "user preferences" --user-id alice
+mem0 --agent add "User prefers dark mode" --user-id alice
+mem0 --agent list --user-id alice
+```
+
+Every command returns the same envelope shape:
+
+```json
+{
+  "status": "success",
+  "command": "search",
+  "duration_ms": 134,
+  "scope": { "user_id": "alice" },
+  "count": 2,
+  "data": [
+    { "id": "abc-123", "memory": "User prefers dark mode", "score": 0.97, "created_at": "2026-01-15", "categories": ["preferences"] }
+  ]
+}
+```
+
+What agent mode does differently from `--output json`:
+- **Sanitized `data`**: only the fields an agent needs (id, memory, score, etc.) — no internal API noise
+- **No human output**: spinners, colors, and banners are suppressed entirely
+- **Errors as JSON**: errors go to stdout as `{"status": "error", "command": "...", "error": "..."}` with a non-zero exit code
+
+Use `mem0 help --json` to get the full command tree as JSON — useful for agents that need to self-discover available commands.
+
+## Output formats
+
+Control how results are displayed with `--output`:
+
+| Format | Description |
+|--------|-------------|
+| `text` | Human-readable with colors and formatting (default) |
+| `json` | Structured JSON for piping to `jq` (raw API response) |
+| `table` | Tabular format (default for `list`) |
+| `quiet` | Minimal — just IDs or status codes |
+| `agent` | Structured JSON envelope with sanitized fields (set by `--agent`/`--json`) |
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `MEM0_API_KEY` | API key (overrides config file) |
+| `MEM0_BASE_URL` | API base URL |
+| `MEM0_USER_ID` | Default user ID |
+| `MEM0_AGENT_ID` | Default agent ID |
+| `MEM0_APP_ID` | Default app ID |
+| `MEM0_RUN_ID` | Default run ID |
+| `MEM0_ENABLE_GRAPH` | Enable graph memory (`true` / `false`) |
+
+## Implementations
+
+| Language | Directory | Package | Docs |
+|----------|-----------|---------|------|
+| TypeScript | [`node/`](./node/) | `@mem0/cli` | [README](./node/README.md) |
+| Python | [`python/`](./python/) | `mem0-cli` | [README](./python/README.md) |
+
+## Documentation
+
+Full documentation is available at [docs.mem0.ai/platform/cli](https://docs.mem0.ai/platform/cli).
+
+## License
+
+Apache-2.0

cli/cli-spec.json

@@ -0,0 +1,563 @@
+{
+  "specVersion": 1,
+  "cli": {
+    "name": "mem0",
+    "version": "0.1.0",
+    "description": "The Memory Layer for AI Agents",
+    "helpText": "\u25c6 mem0 CLI \u2014 The Memory Layer for AI Agents"
+  },
+  "branding": {
+    "logoMini": "\u25c6 mem0",
+    "tagline": "The Memory Layer for AI Agents",
+    "colors": {
+      "brand": "#8b5cf6",
+      "accent": "#a78bfa",
+      "success": "#22c55e",
+      "error": "#ef4444",
+      "warning": "#f59e0b",
+      "dim": "#6b7280"
+    },
+    "icons": {
+      "success": "\u2713",
+      "error": "\u2717",
+      "warning": "\u26a0",
+      "info": "\u25c6",
+      "pending": "\u29d7",
+      "add": "+",
+      "update": "~",
+      "delete": "-",
+      "noop": "\u00b7",
+      "connected": "\u25cf",
+      "disconnected": "\u25cf"
+    },
+    "logo": "███\u2557   ███\u2557███████\u2557███\u2557   ███\u2557 ██████\u2557      ██████\u2557██\u2557     ██\u2557\n████\u2557 ████\u2551██\u2554\u2550\u2550\u2550\u2550\u255d████\u2557 ████\u2551██\u2554\u2550████\u2557    ██\u2554\u2550\u2550\u2550\u2550\u255d██\u2551     ██\u2551\n██\u2554████\u2554██\u2551█████\u2557  ██\u2554████\u2554██\u2551██\u2551██\u2554██\u2551    ██\u2551     ██\u2551     ██\u2551\n██\u2551\u255a██\u2554\u255d██\u2551██\u2554\u2550\u2550\u255d  ██\u2551\u255a██\u2554\u255d██\u2551████\u2554\u255d██\u2551    ██\u2551     ██\u2551     ██\u2551\n██\u2551 \u255a\u2550\u255d ██\u2551███████\u2557██\u2551 \u255a\u2550\u255d ██\u2551\u255a██████\u2554\u255d    \u255a██████\u2557███████\u2557██\u2551\n\u255a\u2550\u255d     \u255a\u2550\u255d\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u255d     \u255a\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u255d      \u255a\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u255d"
+  },
+  "config": {
+    "configDir": "~/.mem0",
+    "configFile": "config.json",
+    "version": 1,
+    "defaultBaseUrl": "https://api.mem0.ai",
+    "sections": {
+      "platform": {
+        "fields": {
+          "api_key": {
+            "type": "string",
+            "default": "",
+            "envVar": "MEM0_API_KEY",
+            "redact": true
+          },
+          "base_url": {
+            "type": "string",
+            "default": "https://api.mem0.ai",
+            "envVar": "MEM0_BASE_URL"
+          }
+        }
+      },
+      "defaults": {
+        "fields": {
+          "user_id": {
+            "type": "string",
+            "default": "",
+            "envVar": "MEM0_USER_ID"
+          },
+          "agent_id": {
+            "type": "string",
+            "default": "",
+            "envVar": "MEM0_AGENT_ID"
+          },
+          "app_id": {
+            "type": "string",
+            "default": "",
+            "envVar": "MEM0_APP_ID"
+          },
+          "run_id": {
+            "type": "string",
+            "default": "",
+            "envVar": "MEM0_RUN_ID"
+          },
+          "enable_graph": {
+            "type": "boolean",
+            "default": false,
+            "envVar": "MEM0_ENABLE_GRAPH"
+          }
+        }
+      }
+    }
+  },
+  "api": {
+    "endpoints": {
+      "add": { "method": "POST", "path": "/v1/memories/" },
+      "search": { "method": "POST", "path": "/v2/memories/search/" },
+      "get": { "method": "GET", "path": "/v1/memories/{memory_id}/" },
+      "list": { "method": "POST", "path": "/v2/memories/" },
+      "update": { "method": "PUT", "path": "/v1/memories/{memory_id}/" },
+      "delete": { "method": "DELETE", "path": "/v1/memories/{memory_id}/" },
+      "deleteAll": { "method": "DELETE", "path": "/v1/memories/" },
+      "entities": { "method": "GET", "path": "/v1/entities/" },
+      "deleteEntities": { "method": "DELETE", "path": "/v1/entities/" }
+    },
+    "authHeader": "Authorization",
+    "authScheme": "Token",
+    "timeout": 30,
+    "entityTypeMap": {
+      "users": "user",
+      "agents": "agent",
+      "apps": "app",
+      "runs": "run"
+    }
+  },
+  "errors": {
+    "AuthError": {
+      "httpStatus": 401,
+      "message": "Authentication failed. Your API key may be invalid or expired."
+    },
+    "NotFoundError": {
+      "httpStatus": 404,
+      "messageTemplate": "Resource not found: {path}"
+    },
+    "APIError": {
+      "httpStatus": 400,
+      "messageTemplate": "Bad request to {path}: {detail}"
+    },
+    "noApiKey": {
+      "message": "No API key configured.",
+      "hint": "Run 'mem0 init' or set MEM0_API_KEY environment variable."
+    }
+  },
+  "optionGroups": {
+    "scope": {
+      "label": "Scope",
+      "options": ["user_id", "agent_id", "app_id", "run_id"]
+    },
+    "search": {
+      "label": "Search",
+      "options": ["top_k", "threshold", "rerank", "keyword", "filter_json", "fields", "graph", "no_graph"]
+    },
+    "pagination": {
+      "label": "Pagination",
+      "options": ["page", "page_size"]
+    },
+    "filters": {
+      "label": "Filters",
+      "options": ["category", "after", "before", "graph", "no_graph"]
+    },
+    "output": {
+      "label": "Output",
+      "options": ["output"]
+    },
+    "connection": {
+      "label": "Connection",
+      "options": ["api_key", "base_url"]
+    }
+  },
+  "globalOptions": [
+    {
+      "name": "api_key",
+      "flags": ["--api-key"],
+      "type": "string",
+      "required": false,
+      "envVar": "MEM0_API_KEY",
+      "help": "Override API key.",
+      "panel": "Connection"
+    },
+    {
+      "name": "base_url",
+      "flags": ["--base-url"],
+      "type": "string",
+      "required": false,
+      "help": "Override API base URL.",
+      "panel": "Connection"
+    },
+    {
+      "name": "version",
+      "flags": ["--version"],
+      "type": "boolean",
+      "required": false,
+      "help": "Show version and exit."
+    }
+  ],
+  "commands": [
+    {
+      "name": "add",
+      "description": "Add a memory from text, messages, file, or stdin.",
+      "usage": "mem0 add <text> [OPTIONS]",
+      "needsBackend": true,
+      "needsConfig": true,
+      "resolveIds": true,
+      "resolveGraph": true,
+      "confirmDangerous": false,
+      "outputFormats": ["text", "json", "quiet"],
+      "defaultOutput": "text",
+      "arguments": [
+        {
+          "name": "text",
+          "type": "string",
+          "required": false,
+          "help": "Text content to add as a memory."
+        }
+      ],
+      "options": [
+        { "name": "user_id", "flags": ["--user-id", "-u"], "type": "string", "help": "Scope to user.", "panel": "Scope" },
+        { "name": "agent_id", "flags": ["--agent-id"], "type": "string", "help": "Scope to agent.", "panel": "Scope" },
+        { "name": "app_id", "flags": ["--app-id"], "type": "string", "help": "Scope to app.", "panel": "Scope" },
+        { "name": "run_id", "flags": ["--run-id"], "type": "string", "help": "Scope to run.", "panel": "Scope" },
+        { "name": "messages", "flags": ["--messages"], "type": "string", "help": "Conversation messages as JSON." },
+        { "name": "file", "flags": ["--file", "-f"], "type": "path", "help": "Read messages from JSON file." },
+        { "name": "metadata", "flags": ["--metadata", "-m"], "type": "string", "help": "Custom metadata as JSON." },
+        { "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": "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" }
+      ],
+      "apiEndpoint": "add"
+    },
+    {
+      "name": "search",
+      "description": "Search memories by semantic query.",
+      "usage": "mem0 search <query> [OPTIONS]",
+      "needsBackend": true,
+      "needsConfig": true,
+      "resolveIds": true,
+      "resolveGraph": true,
+      "confirmDangerous": false,
+      "outputFormats": ["text", "json", "table"],
+      "defaultOutput": "text",
+      "arguments": [
+        {
+          "name": "query",
+          "type": "string",
+          "required": true,
+          "help": "Search query."
+        }
+      ],
+      "options": [
+        { "name": "user_id", "flags": ["--user-id", "-u"], "type": "string", "help": "Filter by user.", "panel": "Scope" },
+        { "name": "agent_id", "flags": ["--agent-id"], "type": "string", "help": "Filter by agent.", "panel": "Scope" },
+        { "name": "app_id", "flags": ["--app-id"], "type": "string", "help": "Filter by app.", "panel": "Scope" },
+        { "name": "run_id", "flags": ["--run-id"], "type": "string", "help": "Filter by run.", "panel": "Scope" },
+        { "name": "top_k", "flags": ["--top-k", "-k", "--limit"], "type": "integer", "default": 10, "help": "Number of results.", "panel": "Search" },
+        { "name": "threshold", "flags": ["--threshold"], "type": "float", "default": 0.3, "help": "Minimum similarity score.", "panel": "Search" },
+        { "name": "rerank", "flags": ["--rerank"], "type": "boolean", "default": false, "help": "Enable reranking (Platform only).", "panel": "Search" },
+        { "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" }
+      ],
+      "apiEndpoint": "search"
+    },
+    {
+      "name": "get",
+      "description": "Get a specific memory by ID.",
+      "usage": "mem0 get <memory_id> [OPTIONS]",
+      "needsBackend": true,
+      "needsConfig": false,
+      "resolveIds": false,
+      "resolveGraph": false,
+      "confirmDangerous": false,
+      "outputFormats": ["text", "json"],
+      "defaultOutput": "text",
+      "arguments": [
+        {
+          "name": "memory_id",
+          "type": "string",
+          "required": true,
+          "help": "Memory ID to retrieve."
+        }
+      ],
+      "options": [
+        { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "text", "help": "Output: text, json.", "panel": "Output" }
+      ],
+      "apiEndpoint": "get"
+    },
+    {
+      "name": "list",
+      "description": "List memories with optional filters.",
+      "usage": "mem0 list [OPTIONS]",
+      "needsBackend": true,
+      "needsConfig": true,
+      "resolveIds": true,
+      "resolveGraph": true,
+      "confirmDangerous": false,
+      "outputFormats": ["text", "json", "table"],
+      "defaultOutput": "table",
+      "arguments": [],
+      "options": [
+        { "name": "user_id", "flags": ["--user-id", "-u"], "type": "string", "help": "Filter by user.", "panel": "Scope" },
+        { "name": "agent_id", "flags": ["--agent-id"], "type": "string", "help": "Filter by agent.", "panel": "Scope" },
+        { "name": "app_id", "flags": ["--app-id"], "type": "string", "help": "Filter by app.", "panel": "Scope" },
+        { "name": "run_id", "flags": ["--run-id"], "type": "string", "help": "Filter by run.", "panel": "Scope" },
+        { "name": "page", "flags": ["--page"], "type": "integer", "default": 1, "help": "Page number.", "panel": "Pagination" },
+        { "name": "page_size", "flags": ["--page-size"], "type": "integer", "default": 100, "help": "Results per page.", "panel": "Pagination" },
+        { "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" }
+      ],
+      "apiEndpoint": "list"
+    },
+    {
+      "name": "update",
+      "description": "Update a memory's text or metadata.",
+      "usage": "mem0 update <memory_id> [text] [OPTIONS]",
+      "needsBackend": true,
+      "needsConfig": false,
+      "resolveIds": false,
+      "resolveGraph": false,
+      "confirmDangerous": false,
+      "outputFormats": ["text", "json", "quiet"],
+      "defaultOutput": "text",
+      "arguments": [
+        {
+          "name": "memory_id",
+          "type": "string",
+          "required": true,
+          "help": "Memory ID to update."
+        },
+        {
+          "name": "text",
+          "type": "string",
+          "required": false,
+          "help": "New memory text."
+        }
+      ],
+      "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"
+    },
+    {
+      "name": "delete",
+      "description": "Delete a memory, all memories matching a scope, or an entity.",
+      "usage": "mem0 delete [memory_id] [OPTIONS]",
+      "needsBackend": true,
+      "needsConfig": true,
+      "resolveIds": true,
+      "resolveGraph": false,
+      "confirmDangerous": true,
+      "outputFormats": ["text", "json", "quiet"],
+      "defaultOutput": "text",
+      "arguments": [
+        {
+          "name": "memory_id",
+          "type": "string",
+          "required": false,
+          "help": "Memory ID to delete (omit when using --all or --entity)."
+        }
+      ],
+      "options": [
+        { "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" },
+        { "name": "agent_id", "flags": ["--agent-id"], "type": "string", "help": "Scope to agent.", "panel": "Scope" },
+        { "name": "app_id", "flags": ["--app-id"], "type": "string", "help": "Scope to app.", "panel": "Scope" },
+        { "name": "run_id", "flags": ["--run-id"], "type": "string", "help": "Scope to run.", "panel": "Scope" },
+        { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "text", "help": "Output: text, json, quiet.", "panel": "Output" }
+      ],
+      "apiEndpoint": "delete",
+      "notes": "Mutually exclusive modes: (1) mem0 delete <id> -- single memory, (2) mem0 delete --all [scope] -- bulk delete, (3) mem0 delete --entity [scope] -- entity cascade delete. Cannot combine <memoryId> with --all or --entity, and cannot combine --all with --entity."
+    },
+    {
+      "name": "import",
+      "description": "Import memories from a JSON file.",
+      "usage": "mem0 import <file_path> [OPTIONS]",
+      "needsBackend": true,
+      "needsConfig": true,
+      "resolveIds": true,
+      "resolveGraph": false,
+      "confirmDangerous": false,
+      "outputFormats": ["text"],
+      "defaultOutput": "text",
+      "arguments": [
+        {
+          "name": "file_path",
+          "type": "string",
+          "required": true,
+          "help": "JSON file to import."
+        }
+      ],
+      "options": [
+        { "name": "user_id", "flags": ["--user-id", "-u"], "type": "string", "help": "Override user ID.", "panel": "Scope" },
+        { "name": "agent_id", "flags": ["--agent-id"], "type": "string", "help": "Override agent ID.", "panel": "Scope" }
+      ],
+      "apiEndpoint": "add"
+    },
+    {
+      "name": "config",
+      "description": "Manage mem0 configuration.",
+      "isGroup": true,
+      "subcommands": [
+        {
+          "name": "show",
+          "description": "Display current configuration (secrets redacted).",
+          "usage": "mem0 config show",
+          "needsBackend": false,
+          "needsConfig": false,
+          "arguments": [],
+          "options": []
+        },
+        {
+          "name": "get",
+          "description": "Get a configuration value.",
+          "usage": "mem0 config get <key>",
+          "needsBackend": false,
+          "needsConfig": false,
+          "arguments": [
+            {
+              "name": "key",
+              "type": "string",
+              "required": true,
+              "help": "Config key (e.g. platform.api_key)."
+            }
+          ],
+          "options": []
+        },
+        {
+          "name": "set",
+          "description": "Set a configuration value.",
+          "usage": "mem0 config set <key> <value>",
+          "needsBackend": false,
+          "needsConfig": false,
+          "arguments": [
+            {
+              "name": "key",
+              "type": "string",
+              "required": true,
+              "help": "Config key (e.g. platform.api_key)."
+            },
+            {
+              "name": "value",
+              "type": "string",
+              "required": true,
+              "help": "Value to set."
+            }
+          ],
+          "options": []
+        }
+      ]
+    },
+    {
+      "name": "entity",
+      "description": "Manage entities.",
+      "isGroup": true,
+      "subcommands": [
+        {
+          "name": "list",
+          "description": "List all entities of a given type.",
+          "usage": "mem0 entity list <entity_type>",
+          "needsBackend": true,
+          "needsConfig": false,
+          "resolveIds": false,
+          "resolveGraph": false,
+          "confirmDangerous": false,
+          "outputFormats": ["table", "json"],
+          "defaultOutput": "table",
+          "arguments": [
+            {
+              "name": "entity_type",
+              "type": "string",
+              "required": true,
+              "help": "Entity type: users, agents, apps, runs.",
+              "choices": ["users", "agents", "apps", "runs"]
+            }
+          ],
+          "options": [
+            { "name": "output", "flags": ["--output", "-o"], "type": "string", "default": "table", "help": "Output: table, json.", "panel": "Output" }
+          ],
+          "apiEndpoint": "entities"
+        },
+        {
+          "name": "delete",
+          "description": "Delete an entity and ALL its memories (cascade).",
+          "usage": "mem0 entity delete [OPTIONS]",
+          "needsBackend": true,
+          "needsConfig": false,
+          "resolveIds": false,
+          "resolveGraph": false,
+          "confirmDangerous": true,
+          "outputFormats": ["text", "json", "quiet"],
+          "defaultOutput": "text",
+          "arguments": [],
+          "options": [
+            { "name": "user_id", "flags": ["--user-id", "-u"], "type": "string", "help": "User ID.", "panel": "Scope" },
+            { "name": "agent_id", "flags": ["--agent-id"], "type": "string", "help": "Agent ID.", "panel": "Scope" },
+            { "name": "app_id", "flags": ["--app-id"], "type": "string", "help": "App ID.", "panel": "Scope" },
+            { "name": "run_id", "flags": ["--run-id"], "type": "string", "help": "Run ID.", "panel": "Scope" },
+            { "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": "output", "flags": ["--output", "-o"], "type": "string", "default": "text", "help": "Output: text, json, quiet.", "panel": "Output" }
+          ],
+          "apiEndpoint": "deleteEntities"
+        }
+      ]
+    },
+    {
+      "name": "init",
+      "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,
+      "resolveIds": false,
+      "resolveGraph": false,
+      "confirmDangerous": false,
+      "arguments": [],
+      "options": [
+        { "name": "api-key", "flags": ["--api-key"], "type": "string", "default": null, "help": "API key (skip prompt)." },
+        { "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": "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)." }
+      ]
+    },
+    {
+      "name": "status",
+      "description": "Check connectivity and authentication.",
+      "usage": "mem0 status [OPTIONS]",
+      "needsBackend": true,
+      "needsConfig": true,
+      "resolveIds": false,
+      "resolveGraph": false,
+      "confirmDangerous": false,
+      "arguments": [],
+      "options": []
+    },
+    {
+      "name": "help",
+      "description": "Show help. Use --json for machine-readable output (for LLM agents).",
+      "usage": "mem0 help [OPTIONS]",
+      "needsBackend": false,
+      "needsConfig": false,
+      "resolveIds": false,
+      "resolveGraph": false,
+      "confirmDangerous": false,
+      "arguments": [],
+      "options": [
+        { "name": "json", "flags": ["--json"], "type": "boolean", "default": false, "help": "Output machine-readable JSON for LLM agents." }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,331 @@
+# mem0 CLI (Node.js)
+
+The official command-line interface for [mem0](https://mem0.ai) — the memory layer for AI agents. TypeScript implementation.
+
+> **Built for AI agents.** Pass `--agent` (or `--json`) as a global flag on any command to get structured JSON output optimized for programmatic consumption — sanitized fields, no colors or spinners, and errors as JSON too.
+
+## Prerequisites
+
+- Node.js **18+**
+- pnpm (`npm install -g pnpm`) — for development only
+
+## Installation
+
+```bash
+npm install -g @mem0/cli
+```
+
+## Quick start
+
+```bash
+# Interactive setup wizard
+mem0 init
+
+# Or login via email
+mem0 init --email alice@company.com
+
+# Or authenticate with an existing API key
+mem0 init --api-key m0-xxx
+
+# Add a memory
+mem0 add "I prefer dark mode and use vim keybindings" --user-id alice
+
+# Search memories
+mem0 search "What are Alice's preferences?" --user-id alice
+
+# List all memories for a user
+mem0 list --user-id alice
+
+# Get a specific memory
+mem0 get <memory-id>
+
+# Update a memory
+mem0 update <memory-id> "I switched to light mode"
+
+# Delete a memory
+mem0 delete <memory-id>
+```
+
+## Commands
+
+### `mem0 init`
+
+Interactive setup wizard. Prompts for your API key and default user ID.
+
+```bash
+mem0 init
+mem0 init --api-key m0-xxx --user-id alice
+mem0 init --email alice@company.com
+```
+
+If an existing configuration is detected, the CLI asks for confirmation before overwriting. Use `--force` to skip the prompt (useful in CI/CD).
+
+```bash
+mem0 init --api-key m0-xxx --user-id alice --force
+```
+
+| Flag | Description |
+|------|-------------|
+| `--api-key` | API key (skip prompt) |
+| `-u, --user-id` | Default user ID (skip prompt) |
+| `--email` | Login via email verification code |
+| `--code` | Verification code (use with `--email` for non-interactive login) |
+| `--force` | Overwrite existing config without confirmation |
+
+### `mem0 add`
+
+Add a memory from text, a JSON messages array, a file, or stdin.
+
+```bash
+mem0 add "I prefer dark mode" --user-id alice
+mem0 add --file conversation.json --user-id alice
+echo "Loves hiking on weekends" | mem0 add --user-id alice
+```
+
+| Flag | Description |
+|------|-------------|
+| `-u, --user-id` | Scope to a user |
+| `--agent-id` | Scope to an agent |
+| `--messages` | Conversation messages as JSON |
+| `-f, --file` | Read messages from a JSON file |
+| `-m, --metadata` | Custom metadata as JSON |
+| `--categories` | Categories (JSON array or comma-separated) |
+| `--graph / --no-graph` | Enable or disable graph memory extraction |
+| `-o, --output` | Output format: `text`, `json`, `quiet` |
+
+### `mem0 search`
+
+Search memories using natural language.
+
+```bash
+mem0 search "dietary restrictions" --user-id alice
+mem0 search "preferred tools" --user-id alice --output json --top-k 5
+```
+
+| Flag | Description |
+|------|-------------|
+| `-u, --user-id` | Filter by user |
+| `-k, --top-k` | Number of results (default: 10) |
+| `--threshold` | Minimum similarity score (default: 0.3) |
+| `--rerank` | Enable reranking |
+| `--keyword` | Use keyword search instead of semantic |
+| `--filter` | Advanced filter expression (JSON) |
+| `--graph / --no-graph` | Enable or disable graph in search |
+| `-o, --output` | Output format: `text`, `json`, `table` |
+
+### `mem0 list`
+
+List memories with optional filters and pagination.
+
+```bash
+mem0 list --user-id alice
+mem0 list --user-id alice --category preferences --output json
+mem0 list --user-id alice --after 2024-01-01 --page-size 50
+```
+
+| Flag | Description |
+|------|-------------|
+| `-u, --user-id` | Filter by user |
+| `--page` | Page number (default: 1) |
+| `--page-size` | Results per page (default: 100) |
+| `--category` | Filter by category |
+| `--after` | Created after date (YYYY-MM-DD) |
+| `--before` | Created before date (YYYY-MM-DD) |
+| `-o, --output` | Output format: `text`, `json`, `table` |
+
+### `mem0 get`
+
+Retrieve a specific memory by ID.
+
+```bash
+mem0 get 7b3c1a2e-4d5f-6789-abcd-ef0123456789
+mem0 get 7b3c1a2e-4d5f-6789-abcd-ef0123456789 --output json
+```
+
+### `mem0 update`
+
+Update the text or metadata of an existing memory.
+
+```bash
+mem0 update <memory-id> "Updated preference text"
+mem0 update <memory-id> --metadata '{"priority": "high"}'
+echo "new text" | mem0 update <memory-id>
+```
+
+### `mem0 delete`
+
+Delete a single memory, all memories for a scope, or an entire entity.
+
+```bash
+# Delete a single memory
+mem0 delete <memory-id>
+
+# Delete all memories for a user
+mem0 delete --all --user-id alice --force
+
+# Delete all memories project-wide
+mem0 delete --all --project --force
+
+# Preview what would be deleted
+mem0 delete --all --user-id alice --dry-run
+```
+
+| Flag | Description |
+|------|-------------|
+| `--all` | Delete all memories matching scope filters |
+| `--entity` | Delete the entity and all its memories |
+| `--project` | With `--all`: delete all memories project-wide |
+| `--dry-run` | Preview without deleting |
+| `--force` | Skip confirmation prompt |
+
+### `mem0 import`
+
+Bulk import memories from a JSON file.
+
+```bash
+mem0 import data.json --user-id alice
+```
+
+The file should be a JSON array where each item has a `memory` (or `text` or `content`) field and optional `user_id`, `agent_id`, and `metadata` fields.
+
+### `mem0 config`
+
+View or modify the local CLI configuration.
+
+```bash
+mem0 config show              # Display current config (secrets redacted)
+mem0 config get api_key       # Get a specific value
+mem0 config set user_id bob   # Set a value
+```
+
+### `mem0 entity`
+
+List or delete entities (users, agents, apps, runs).
+
+```bash
+mem0 entity list users
+mem0 entity list agents --output json
+mem0 entity delete --user-id alice --force
+```
+
+### `mem0 event`
+
+Inspect background processing events created by async operations (e.g. bulk deletes, large add jobs).
+
+```bash
+# List recent events
+mem0 event list
+
+# Check the status of a specific event
+mem0 event status <event-id>
+```
+
+| Flag | Description |
+|------|-------------|
+| `-o, --output` | Output format: `text`, `json` |
+
+### `mem0 status`
+
+Verify your API connection and display the current project.
+
+```bash
+mem0 status
+```
+
+## Agent mode
+
+Pass `--agent` (or its alias `--json`) as a **global flag** on any command to get output designed for AI agent tool loops:
+
+```bash
+mem0 --agent search "user preferences" --user-id alice
+mem0 --agent add "User prefers dark mode" --user-id alice
+mem0 --agent list --user-id alice
+mem0 --agent delete --all --user-id alice --force
+```
+
+Every command returns the same envelope shape:
+
+```json
+{
+  "status": "success",
+  "command": "search",
+  "duration_ms": 134,
+  "scope": { "user_id": "alice" },
+  "count": 2,
+  "data": [
+    { "id": "abc-123", "memory": "User prefers dark mode", "score": 0.97, "created_at": "2026-01-15", "categories": ["preferences"] }
+  ]
+}
+```
+
+What agent mode does differently from `--output json`:
+
+- **Sanitized `data`**: only the fields an agent needs (id, memory, score, etc.) — no internal API noise
+- **No human output**: spinners, colors, and banners are suppressed entirely
+- **Errors as JSON**: errors go to stdout as `{"status": "error", "command": "...", "error": "..."}` with a non-zero exit code
+
+Use `mem0 help --json` to get the full command tree as JSON — useful for agents that need to self-discover available commands.
+
+## Output formats
+
+Control how results are displayed with `--output`:
+
+| Format | Description |
+|--------|-------------|
+| `text` | Human-readable with colors and formatting (default) |
+| `json` | Structured JSON for piping to `jq` (raw API response) |
+| `table` | Tabular format (default for `list`) |
+| `quiet` | Minimal — just IDs or status codes |
+| `agent` | Structured JSON envelope with sanitized fields (set by `--agent`/`--json`) |
+
+## Global flags
+
+These flags are available on all commands:
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Enable agent mode: structured JSON envelope output, no colors or spinners |
+| `--agent` | Alias for `--json` |
+| `--api-key` | Override the configured API key for this request |
+| `--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 |
+|----------|-------------|
+| `MEM0_API_KEY` | API key (overrides config file) |
+| `MEM0_BASE_URL` | API base URL |
+| `MEM0_USER_ID` | Default user ID |
+| `MEM0_AGENT_ID` | Default agent ID |
+| `MEM0_APP_ID` | Default app ID |
+| `MEM0_RUN_ID` | Default run ID |
+| `MEM0_ENABLE_GRAPH` | Enable graph memory (`true` / `false`) |
+
+Environment variables take precedence over values in the config file, which take precedence over defaults.
+
+## Development
+
+```bash
+cd cli/node
+pnpm install
+
+# Development mode (runs TypeScript directly, no build needed)
+pnpm dev --help
+pnpm dev add "test memory" --user-id alice
+pnpm dev search "test" --user-id alice
+
+# Or build first, then run the compiled JS
+pnpm build
+node dist/index.js --help
+```
+
+## Documentation
+
+Full documentation is available at [docs.mem0.ai/platform/cli](https://docs.mem0.ai/platform/cli).
+
+## License
+
+Apache-2.0

cli/node/development.md

@@ -0,0 +1,91 @@
+# Development
+
+## Prerequisites
+
+- Node.js **18+**
+- pnpm (`npm install -g pnpm`)
+
+## Setup
+
+From the `node/` directory:
+
+```bash
+pnpm install
+```
+
+## Running the CLI
+
+There are two ways to run the CLI during development:
+
+### Option 1: Development mode (no build needed)
+
+Uses `tsx` to run TypeScript directly. Pass CLI arguments after `pnpm dev`:
+
+```bash
+pnpm dev --help
+pnpm dev version
+pnpm dev add "test memory" --user-id alice
+pnpm dev search "test" --user-id alice
+pnpm dev config show
+```
+
+> **Note:** Do NOT use `pnpm dev -- --help`. With pnpm, arguments pass through directly — adding `--` inserts a literal `--` that breaks the CLI parser.
+
+### Option 2: Build and run compiled JS
+
+```bash
+# Build first
+pnpm build
+
+# Run the compiled CLI
+node dist/index.js --help
+node dist/index.js version
+node dist/index.js add "test memory" --user-id alice
+```
+
+### Option 3: Link globally (makes `mem0` available system-wide)
+
+```bash
+pnpm build
+pnpm link --global
+
+# Now use it like a normal CLI
+mem0 --help
+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`.
+
+## Build
+
+```bash
+pnpm build
+```
+
+The compiled output is in `dist/`.
+
+## Run tests
+
+```bash
+# Run all tests
+pnpm test
+
+# Watch mode
+pnpm test:watch
+```
+
+## Lint
+
+```bash
+# Check
+pnpm lint
+
+# Auto-fix
+pnpm lint:fix
+```
+
+## Type checking
+
+```bash
+pnpm typecheck
+```

cli/node/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@mem0/cli",
+  "version": "0.2.13",
+  "description": "The official CLI for mem0 — the memory layer for AI agents",
+  "type": "module",
+  "bin": {
+    "mem0": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": "mem0.ai <founders@mem0.ai>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mem0ai/mem0",
+    "directory": "cli/node"
+  },
+  "keywords": ["mem0", "memory", "ai", "agents", "cli"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.4",
+    "ora": "^8.0.0",
+    "boxen": "^7.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.7.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

@@ -0,0 +1,143 @@
+/**
+ * Abstract backend interface and factory.
+ */
+
+import type { Mem0Config } from "../config.js";
+import { PlatformBackend } from "./platform.js";
+
+export interface AddOptions {
+	userId?: string;
+	agentId?: string;
+	appId?: string;
+	runId?: string;
+	metadata?: Record<string, unknown>;
+	immutable?: boolean;
+	infer?: boolean;
+	expires?: string;
+	customInstructions?: string;
+	agentCustomInstructions?: string;
+	customCategories?: Record<string, string>[];
+	structuredDataSchema?: Record<string, unknown>;
+	timestamp?: number;
+}
+
+export interface SearchOptions {
+	userId?: string;
+	agentId?: string;
+	appId?: string;
+	runId?: string;
+	topK?: number;
+	threshold?: number;
+	rerank?: boolean;
+	keyword?: boolean;
+	filters?: Record<string, unknown>;
+	fields?: string[];
+	showExpired?: boolean;
+	referenceDate?: string | number;
+	latestOnly?: boolean;
+}
+
+export interface ListOptions {
+	userId?: string;
+	agentId?: string;
+	appId?: string;
+	runId?: string;
+	page?: number;
+	pageSize?: number;
+	category?: string;
+	after?: string;
+	before?: string;
+	showExpired?: boolean;
+	latestOnly?: boolean;
+}
+
+export interface DeleteOptions {
+	all?: boolean;
+	userId?: string;
+	agentId?: string;
+	appId?: string;
+	runId?: string;
+	deleteLinked?: boolean;
+}
+
+export interface UpdateOptions {
+	expirationDate?: string;
+	timestamp?: number;
+}
+
+export interface EntityIds {
+	userId?: string;
+	agentId?: string;
+	appId?: string;
+	runId?: string;
+}
+
+export interface Backend {
+	add(
+		content?: string,
+		messages?: Record<string, unknown>[],
+		opts?: AddOptions,
+	): Promise<Record<string, unknown>>;
+
+	search(
+		query: string,
+		opts?: SearchOptions,
+	): Promise<Record<string, unknown>[]>;
+
+	get(memoryId: string): Promise<Record<string, unknown>>;
+
+	listMemories(opts?: ListOptions): Promise<Record<string, unknown>[]>;
+
+	update(
+		memoryId: string,
+		content?: string,
+		metadata?: Record<string, unknown>,
+		opts?: UpdateOptions,
+	): Promise<Record<string, unknown>>;
+
+	delete(
+		memoryId?: string,
+		opts?: DeleteOptions,
+	): Promise<Record<string, unknown>>;
+
+	deleteEntities(opts: EntityIds): Promise<Record<string, unknown>>;
+
+	ping(): Promise<Record<string, unknown>>;
+
+	status(opts?: { userId?: string; agentId?: string }): Promise<
+		Record<string, unknown>
+	>;
+
+	entities(entityType: string): Promise<Record<string, unknown>[]>;
+
+	listEvents(): Promise<Record<string, unknown>[]>;
+
+	getEvent(eventId: string): Promise<Record<string, unknown>>;
+}
+
+export class AuthError extends Error {
+	constructor(
+		message = "Authentication failed. Your API key may be invalid or expired.",
+	) {
+		super(message);
+		this.name = "AuthError";
+	}
+}
+
+export class NotFoundError extends Error {
+	constructor(path: string) {
+		super(`Resource not found: ${path}`);
+		this.name = "NotFoundError";
+	}
+}
+
+export class APIError extends Error {
+	constructor(path: string, detail: string) {
+		super(`Bad request to ${path}: ${detail}`);
+		this.name = "APIError";
+	}
+}
+
+export function getBackend(config: Mem0Config): Backend {
+	return new PlatformBackend(config.platform);
+}

cli/node/src/backend/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Backend factory re-export.
+ */
+
+export { getBackend } from "./base.js";
+export type {
+	Backend,
+	AddOptions,
+	SearchOptions,
+	ListOptions,
+	DeleteOptions,
+	EntityIds,
+} from "./base.js";
+export { AuthError, NotFoundError, APIError } from "./base.js";

cli/node/src/backend/platform.ts

@@ -0,0 +1,428 @@
+/**
+ * Platform (SaaS) backend — communicates with api.mem0.ai.
+ */
+
+import type { PlatformConfig } from "../config.js";
+import { captureNotice, isAgentMode } from "../state.js";
+import { CLI_VERSION } from "../version.js";
+import {
+	APIError,
+	type AddOptions,
+	AuthError,
+	type Backend,
+	type DeleteOptions,
+	type EntityIds,
+	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>;
+
+	constructor(config: PlatformConfig) {
+		this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+		this.headers = {
+			Authorization: `Token ${config.apiKey}`,
+			"Content-Type": "application/json",
+			"X-Mem0-Source": "cli",
+			"X-Mem0-Client-Language": "node",
+			"X-Mem0-Client-Version": CLI_VERSION,
+		};
+	}
+
+	private async _request(
+		method: string,
+		path: string,
+		opts?: { json?: unknown; params?: Record<string, string> },
+	): Promise<unknown> {
+		let url = `${this.baseUrl}${path}`;
+		if (opts?.params) {
+			const qs = new URLSearchParams(opts.params).toString();
+			url += `?${qs}`;
+		}
+
+		const headers = {
+			...this.headers,
+			"X-Mem0-Caller-Type": isAgentMode() ? "agent" : "user",
+		};
+
+		const fetchOpts: RequestInit = {
+			method,
+			headers,
+			signal: AbortSignal.timeout(30_000),
+		};
+		if (opts?.json) {
+			fetchOpts.body = JSON.stringify(opts.json);
+		}
+
+		const resp = await fetch(url, fetchOpts);
+
+		if (resp.status === 401) {
+			throw new AuthError();
+		}
+		if (resp.status === 404) {
+			throw new NotFoundError(path);
+		}
+		if (resp.status === 400) {
+			let detail: string;
+			try {
+				const body = (await resp.json()) as Record<string, unknown>;
+				detail =
+					((body.detail ?? body.message ?? JSON.stringify(body)) as string) ??
+					resp.statusText;
+			} catch {
+				detail = resp.statusText;
+			}
+			throw new APIError(path, detail);
+		}
+		if (!resp.ok) {
+			let detail: string = resp.statusText;
+			try {
+				const body = (await resp.json()) as Record<string, unknown>;
+				detail = (body.detail ?? body.message ?? resp.statusText) as string;
+			} catch {
+				/* ignore */
+			}
+			throw new Error(`HTTP ${resp.status}: ${detail}`);
+		}
+		if (resp.status === 204) {
+			return {};
+		}
+
+		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(
+		content?: string,
+		messages?: Record<string, unknown>[],
+		opts: AddOptions = {},
+	): Promise<Record<string, unknown>> {
+		const payload: Record<string, unknown> = {};
+
+		if (messages) {
+			payload.messages = messages;
+		} else if (content) {
+			payload.messages = [{ role: "user", content }];
+		}
+
+		if (opts.userId) payload.user_id = opts.userId;
+		if (opts.agentId) payload.agent_id = opts.agentId;
+		if (opts.appId) payload.app_id = opts.appId;
+		if (opts.runId) payload.run_id = opts.runId;
+		if (opts.metadata) payload.metadata = opts.metadata;
+		if (opts.immutable) payload.immutable = true;
+		if (opts.infer === false) payload.infer = false;
+		if (opts.expires) payload.expiration_date = opts.expires;
+		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", "/v3/memories/add/", {
+			json: payload,
+		})) as Record<string, unknown>;
+	}
+
+	private _buildFilters(opts: {
+		userId?: string;
+		agentId?: string;
+		appId?: string;
+		runId?: string;
+		extraFilters?: Record<string, unknown>;
+	}): Record<string, unknown> | undefined {
+		// If caller passed a pre-built filter structure, use it directly
+		if (
+			opts.extraFilters &&
+			("AND" in opts.extraFilters || "OR" in opts.extraFilters)
+		) {
+			return opts.extraFilters;
+		}
+
+		const andConditions: Record<string, unknown>[] = [];
+		if (opts.userId) andConditions.push({ user_id: opts.userId });
+		if (opts.agentId) andConditions.push({ agent_id: opts.agentId });
+		if (opts.appId) andConditions.push({ app_id: opts.appId });
+		if (opts.runId) andConditions.push({ run_id: opts.runId });
+
+		if (opts.extraFilters) {
+			for (const [k, v] of Object.entries(opts.extraFilters)) {
+				andConditions.push({ [k]: v });
+			}
+		}
+
+		if (andConditions.length === 1) return andConditions[0];
+		if (andConditions.length > 1) return { AND: andConditions };
+		return undefined;
+	}
+
+	async search(
+		query: string,
+		opts: SearchOptions = {},
+	): Promise<Record<string, unknown>[]> {
+		const payload: Record<string, unknown> = {
+			query,
+			top_k: opts.topK ?? 10,
+			threshold: opts.threshold ?? 0.3,
+		};
+
+		const apiFilters = this._buildFilters({
+			userId: opts.userId,
+			agentId: opts.agentId,
+			appId: opts.appId,
+			runId: opts.runId,
+			extraFilters: opts.filters,
+		});
+		if (apiFilters) payload.filters = apiFilters;
+		if (opts.rerank) payload.rerank = true;
+		if (opts.keyword) payload.keyword_search = true;
+		if (opts.fields) payload.fields = opts.fields;
+		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", "/v3/memories/search/", {
+			json: payload,
+		})) as unknown;
+		if (Array.isArray(result)) return result;
+		const obj = result as Record<string, unknown>;
+		return (obj.results ?? obj.memories ?? []) as Record<string, unknown>[];
+	}
+
+	async get(memoryId: string): Promise<Record<string, unknown>> {
+		return (await this._request(
+			"GET",
+			`/v1/memories/${encodePathSegment(memoryId)}/`,
+			{
+				params: { source: "CLI" },
+			},
+		)) as Record<string, unknown>;
+	}
+
+	async listMemories(
+		opts: ListOptions = {},
+	): Promise<Record<string, unknown>[]> {
+		const payload: Record<string, unknown> = {};
+		const params: Record<string, string> = {
+			page: String(opts.page ?? 1),
+			page_size: String(opts.pageSize ?? 100),
+		};
+
+		const extra: Record<string, unknown> = {};
+		if (opts.category) {
+			extra.categories = { contains: opts.category };
+		}
+		if (opts.after) {
+			extra.created_at = {
+				...(extra.created_at as Record<string, unknown> | undefined),
+				gte: opts.after,
+			};
+		}
+		if (opts.before) {
+			extra.created_at = {
+				...(extra.created_at as Record<string, unknown> | undefined),
+				lte: opts.before,
+			};
+		}
+
+		const apiFilters = this._buildFilters({
+			userId: opts.userId,
+			agentId: opts.agentId,
+			appId: opts.appId,
+			runId: opts.runId,
+			extraFilters: Object.keys(extra).length > 0 ? extra : undefined,
+		});
+		if (apiFilters) payload.filters = apiFilters;
+		if (opts.showExpired) payload.show_expired = true;
+		if (opts.latestOnly) payload.latest_only = true;
+		payload.source = "CLI";
+
+		const result = (await this._request("POST", "/v3/memories/", {
+			json: payload,
+			params,
+		})) as unknown;
+		if (Array.isArray(result)) return result;
+		const obj = result as Record<string, unknown>;
+		return (obj.results ?? obj.memories ?? []) as Record<string, unknown>[];
+	}
+
+	async update(
+		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/${encodePathSegment(memoryId)}/`,
+			{
+				json: payload,
+			},
+		)) as Record<string, unknown>;
+	}
+
+	async delete(
+		memoryId?: string,
+		opts: DeleteOptions = {},
+	): Promise<Record<string, unknown>> {
+		if (opts.all) {
+			const params: Record<string, string> = { source: "CLI" };
+			if (opts.userId) params.user_id = opts.userId;
+			if (opts.agentId) params.agent_id = opts.agentId;
+			if (opts.appId) params.app_id = opts.appId;
+			if (opts.runId) params.run_id = opts.runId;
+			return (await this._request("DELETE", "/v1/memories/", {
+				params,
+			})) as Record<string, unknown>;
+		}
+		if (memoryId) {
+			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");
+	}
+
+	async deleteEntities(opts: EntityIds): Promise<Record<string, unknown>> {
+		// v2 endpoint: DELETE /v2/entities/{entity_type}/{entity_id}/
+		const typeMap: [string, string | undefined][] = [
+			["user", opts.userId],
+			["agent", opts.agentId],
+			["app", opts.appId],
+			["run", opts.runId],
+		];
+		const entities = typeMap.filter(([, v]) => v) as [string, string][];
+		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. 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) {
+			results[entityType] = (await this._request(
+				"DELETE",
+				`/v2/entities/${encodePathSegment(entityType)}/${encodePathSegment(entityId)}/`,
+				{ params: { source: "CLI" } },
+			)) as Record<string, unknown>;
+		}
+		return results;
+	}
+
+	async ping(): Promise<Record<string, unknown>> {
+		return (await this._request("GET", "/v1/ping/")) as Record<string, unknown>;
+	}
+
+	async status(
+		opts: { userId?: string; agentId?: string } = {},
+	): Promise<Record<string, unknown>> {
+		try {
+			await this.ping();
+			return { connected: true, backend: "platform", base_url: this.baseUrl };
+		} catch (e) {
+			return {
+				connected: false,
+				backend: "platform",
+				error: e instanceof Error ? e.message : String(e),
+			};
+		}
+	}
+
+	async entities(entityType: string): Promise<Record<string, unknown>[]> {
+		const result = (await this._request("GET", "/v1/entities/")) as unknown;
+		let items: Record<string, unknown>[];
+		if (Array.isArray(result)) {
+			items = result;
+		} else {
+			items = ((result as Record<string, unknown>).results ?? []) as Record<
+				string,
+				unknown
+			>[];
+		}
+
+		const typeMap: Record<string, string> = {
+			users: "user",
+			agents: "agent",
+			apps: "app",
+			runs: "run",
+		};
+		const targetType = typeMap[entityType];
+		if (targetType) {
+			items = items.filter(
+				(e) => (e.type as string | undefined)?.toLowerCase() === targetType,
+			);
+		}
+		return items;
+	}
+
+	async listEvents(): Promise<Record<string, unknown>[]> {
+		const result = (await this._request("GET", "/v1/events/")) as unknown;
+		if (Array.isArray(result)) return result;
+		return ((result as Record<string, unknown>).results ?? []) as Record<
+			string,
+			unknown
+		>[];
+	}
+
+	async getEvent(eventId: string): Promise<Record<string, unknown>> {
+		return (await this._request(
+			"GET",
+			`/v1/event/${encodePathSegment(eventId)}/`,
+		)) as Record<string, unknown>;
+	}
+}

cli/node/src/branding.ts

@@ -0,0 +1,172 @@
+/**
+ * Branding and ASCII art for mem0 CLI.
+ */
+
+import chalk from "chalk";
+import ora, { type Ora } from "ora";
+import { getCurrentCommand, isAgentMode } from "./state.js";
+import { CLI_VERSION } from "./version.js";
+
+export const LOGO = `
+███╗   ███╗███████╗███╗   ███╗ ██████╗      ██████╗██╗     ██╗
+████╗ ████║██╔════╝████╗ ████║██╔═████╗    ██╔════╝██║     ██║
+██╔████╔██║█████╗  ██╔████╔██║██║██╔██║    ██║     ██║     ██║
+██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║████╔╝██║    ██║     ██║     ██║
+██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║╚██████╔╝    ╚██████╗███████╗██║
+╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝ ╚═════╝      ╚═════╝╚══════╝╚═╝
+`;
+
+export const LOGO_MINI = "◆ mem0";
+export const TAGLINE = "The Memory Layer for AI Agents";
+
+export const BRAND_COLOR = "#8b5cf6";
+export const ACCENT_COLOR = "#a78bfa";
+export const SUCCESS_COLOR = "#22c55e";
+export const ERROR_COLOR = "#ef4444";
+export const WARNING_COLOR = "#f59e0b";
+export const DIM_COLOR = "#6b7280";
+
+const brand = chalk.hex(BRAND_COLOR);
+const accent = chalk.hex(ACCENT_COLOR);
+const success = chalk.hex(SUCCESS_COLOR);
+const error = chalk.hex(ERROR_COLOR);
+const warning = chalk.hex(WARNING_COLOR);
+const dim = chalk.hex(DIM_COLOR);
+
+/**
+ * Choose a symbol based on TTY/NO_COLOR. Fancy for interactive terminals,
+ * plain-text for piped/non-TTY or NO_COLOR environments.
+ */
+export function sym(fancy: string, plain: string): string {
+	if (!process.stdout.isTTY || process.env.NO_COLOR) return plain;
+	return fancy;
+}
+
+export function printBanner(): void {
+	if (isAgentMode()) return;
+	const pad = 3; // horizontal padding each side (matches Rich's padding=(0, 2))
+	const logoLines = LOGO.trimEnd().split("\n");
+	const tagline = `  ${TAGLINE}`;
+	const subtitle = `Node.js SDK · v${CLI_VERSION}`;
+	const contentLines = ["", ...logoLines, "", tagline, ""];
+
+	// Compute inner width from longest content line + padding both sides
+	const maxContent = Math.max(...contentLines.map((l) => l.length));
+	const innerWidth = maxContent + pad * 2;
+	const totalWidth = innerWidth + 2; // + 2 for │ borders
+
+	const topBorder = brand(`╭${"─".repeat(totalWidth - 2)}╮`);
+	const subtitleFill = totalWidth - 2 - subtitle.length - 3; // 3 = "─ " before subtitle + "─" after
+	const bottomBorder = brand(
+		`╰${"─".repeat(subtitleFill)} ${dim(subtitle)} ${"─"}╯`,
+	);
+
+	const body = contentLines.map((line) => {
+		const rightPad = innerWidth - pad - line.length;
+		return `${brand("│")}${" ".repeat(pad)}${brand.bold(line)}${" ".repeat(Math.max(rightPad, 0))}${brand("│")}`;
+	});
+	// Re-color tagline line with accent instead of brand.bold
+	const taglineIdx = body.length - 2; // second-to-last (before trailing empty line)
+	const taglineRightPad = innerWidth - pad - tagline.length;
+	body[taglineIdx] =
+		`${brand("│")}${" ".repeat(pad)}${accent(tagline)}${" ".repeat(Math.max(taglineRightPad, 0))}${brand("│")}`;
+
+	console.log(topBorder);
+	for (const line of body) console.log(line);
+	console.log(bottomBorder);
+}
+
+export function printSuccess(message: string): void {
+	if (isAgentMode()) return;
+	console.log(`${success(sym("✓", "[ok]"))} ${message}`);
+}
+
+export function printError(message: string, hint?: string): void {
+	if (isAgentMode()) {
+		const envelope = {
+			status: "error",
+			command: getCurrentCommand(),
+			error: message,
+			data: null,
+		};
+		console.log(JSON.stringify(envelope));
+		return;
+	}
+	console.error(`${error(`${sym("✗", "[error]")} Error:`)} ${message}`);
+	const resolvedHint =
+		hint ??
+		(message.includes("Authentication failed")
+			? `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)}`);
+	}
+}
+
+export function printWarning(message: string): void {
+	console.error(`${warning(sym("⚠", "[warn]"))} ${message}`);
+}
+
+export function printInfo(message: string): void {
+	if (isAgentMode()) return;
+	console.error(`${brand(sym("◆", "*"))} ${message}`);
+}
+
+export function printScope(ids: Record<string, string | undefined>): void {
+	if (isAgentMode()) return;
+	const parts: string[] = [];
+	for (const [key, val] of Object.entries(ids)) {
+		if (val) {
+			parts.push(`${key}=${val}`);
+		}
+	}
+	if (parts.length > 0) {
+		console.error(`  ${dim(`Scope: ${parts.join(", ")}`)}`);
+	}
+}
+
+export interface TimedStatusContext {
+	successMsg: string;
+	errorMsg: string;
+}
+
+/**
+ * Run an async function with a spinner, timing the operation.
+ * Equivalent to Python's timed_status context manager.
+ */
+export async function timedStatus<T>(
+	message: string,
+	fn: (ctx: TimedStatusContext) => Promise<T>,
+): Promise<T> {
+	if (isAgentMode()) {
+		const ctx: TimedStatusContext = { successMsg: "", errorMsg: "" };
+		return fn(ctx);
+	}
+	const ctx: TimedStatusContext = { successMsg: "", errorMsg: "" };
+	const spinner = ora({
+		text: dim(message),
+		color: "yellow",
+		stream: process.stderr,
+	}).start();
+	const start = performance.now();
+
+	try {
+		const result = await fn(ctx);
+		const elapsed = ((performance.now() - start) / 1000).toFixed(2);
+		spinner.stop();
+		if (ctx.successMsg) {
+			console.error(`${success("✓")} ${ctx.successMsg} (${elapsed}s)`);
+		}
+		return result;
+	} catch (err) {
+		const elapsed = ((performance.now() - start) / 1000).toFixed(2);
+		spinner.stop();
+		if (ctx.errorMsg) {
+			printError(`${ctx.errorMsg} (${elapsed}s)`);
+		}
+		throw err;
+	}
+}
+
+/** Format helpers using brand colors for external use. */
+export const colors = { brand, accent, success, error, warning, dim };

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

@@ -0,0 +1,109 @@
+/**
+ * Config management commands: show, set, get.
+ */
+
+import Table from "cli-table3";
+import { colors, printError, printSuccess } from "../branding.js";
+import {
+	getNestedValue,
+	loadConfig,
+	redactKey,
+	saveConfig,
+	setNestedValue,
+} from "../config.js";
+import { formatAgentEnvelope, formatJsonEnvelope } from "../output.js";
+import { isAgentMode, setCurrentCommand } from "../state.js";
+
+const { brand, accent, dim } = colors;
+
+export function cmdConfigShow(opts: { output?: string } = {}): void {
+	setCurrentCommand("config show");
+	const config = loadConfig();
+
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "config show",
+			data: {
+				defaults: {
+					user_id: config.defaults.userId || null,
+					agent_id: config.defaults.agentId || null,
+					app_id: config.defaults.appId || null,
+					run_id: config.defaults.runId || null,
+				},
+				platform: {
+					api_key: redactKey(config.platform.apiKey),
+					base_url: config.platform.baseUrl,
+				},
+			},
+		});
+		return;
+	}
+
+	console.log();
+	console.log(`  ${brand("◆ mem0 Configuration")}\n`);
+
+	const table = new Table({
+		head: [accent("Key"), accent("Value")],
+		style: { head: [], border: [] },
+	});
+
+	// Defaults
+	table.push(["defaults.user_id", config.defaults.userId || dim("(not set)")]);
+	table.push([
+		"defaults.agent_id",
+		config.defaults.agentId || dim("(not set)"),
+	]);
+	table.push(["defaults.app_id", config.defaults.appId || dim("(not set)")]);
+	table.push(["defaults.run_id", config.defaults.runId || dim("(not set)")]);
+	table.push(["", ""]);
+
+	// Platform
+	table.push(["platform.api_key", redactKey(config.platform.apiKey)]);
+	table.push(["platform.base_url", config.platform.baseUrl]);
+
+	console.log(table.toString());
+	console.log();
+}
+
+export function cmdConfigGet(key: string): void {
+	setCurrentCommand("config get");
+	const config = loadConfig();
+	const value = getNestedValue(config, key);
+
+	if (value === undefined) {
+		printError(`Unknown config key: ${key}`);
+	} else {
+		// Redact secrets
+		const displayValue =
+			key.includes("api_key") || key.split(".").pop() === "key"
+				? redactKey(String(value))
+				: String(value);
+		if (isAgentMode()) {
+			formatAgentEnvelope({
+				command: "config get",
+				data: { key, value: displayValue },
+			});
+		} else {
+			console.log(displayValue);
+		}
+	}
+}
+
+export function cmdConfigSet(key: string, value: string): void {
+	setCurrentCommand("config set");
+	const config = loadConfig();
+	if (setNestedValue(config, key, value)) {
+		saveConfig(config);
+		const display = key.includes("key") ? redactKey(value) : value;
+		if (isAgentMode()) {
+			formatAgentEnvelope({
+				command: "config set",
+				data: { key, value: display },
+			});
+		} else {
+			printSuccess(`${key} = ${display}`);
+		}
+	} else {
+		printError(`Unknown config key: ${key}`);
+	}
+}

cli/node/src/commands/entities.ts

@@ -0,0 +1,168 @@
+/**
+ * Entity management commands.
+ */
+
+import readline from "node:readline";
+import Table from "cli-table3";
+import type { Backend } from "../backend/base.js";
+import {
+	colors,
+	printError,
+	printInfo,
+	printSuccess,
+	timedStatus,
+} from "../branding.js";
+import { formatAgentEnvelope, formatJson } from "../output.js";
+import { setCurrentCommand } from "../state.js";
+
+const { brand, accent, dim } = colors;
+
+const VALID_TYPES = new Set(["users", "agents", "apps", "runs"]);
+
+export async function cmdEntitiesList(
+	backend: Backend,
+	entityType: string,
+	opts: { output: string },
+): Promise<void> {
+	setCurrentCommand("entity list");
+	if (!VALID_TYPES.has(entityType)) {
+		printError(
+			`Invalid entity type: ${entityType}. Use: ${[...VALID_TYPES].join(", ")}`,
+		);
+		process.exit(1);
+	}
+
+	const start = performance.now();
+	let results: Record<string, unknown>[];
+	try {
+		results = await timedStatus(`Fetching ${entityType}...`, async () => {
+			return backend.entities(entityType);
+		});
+	} catch (e) {
+		printError(
+			e instanceof Error ? e.message : String(e),
+			"This feature may require the mem0 Platform.",
+		);
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "entity list",
+			data: results,
+			count: results.length,
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
+
+	if (!results.length) {
+		printInfo(`No ${entityType} found.`);
+		return;
+	}
+
+	const table = new Table({
+		head: [accent("Name / ID"), accent("Created")],
+		style: { head: [], border: [] },
+	});
+
+	for (const entity of results) {
+		const name = String(entity.name ?? entity.id ?? "—");
+		const created = String(entity.created_at ?? "—").slice(0, 10);
+		table.push([name, created]);
+	}
+
+	console.log();
+	console.log(table.toString());
+	console.log(
+		`  ${dim(`${results.length} ${entityType} (${elapsed.toFixed(2)}s)`)}`,
+	);
+	console.log();
+}
+
+export async function cmdEntitiesDelete(
+	backend: Backend,
+	opts: {
+		userId?: string;
+		agentId?: string;
+		appId?: string;
+		runId?: string;
+		dryRun?: boolean;
+		force: boolean;
+		output: string;
+	},
+): Promise<void> {
+	setCurrentCommand("entity delete");
+	const { isAgentMode } = await import("../state.js");
+	if (isAgentMode() && !opts.force) {
+		printError("Destructive operation requires --force in agent mode.");
+		process.exit(1);
+	}
+	if (!opts.userId && !opts.agentId && !opts.appId && !opts.runId) {
+		printError(
+			"Provide at least one of --user-id, --agent-id, --app-id, --run-id.",
+		);
+		process.exit(1);
+	}
+
+	const scopeParts: string[] = [];
+	if (opts.userId) scopeParts.push(`user=${opts.userId}`);
+	if (opts.agentId) scopeParts.push(`agent=${opts.agentId}`);
+	if (opts.appId) scopeParts.push(`app=${opts.appId}`);
+	if (opts.runId) scopeParts.push(`run=${opts.runId}`);
+	const scope = scopeParts.join(", ");
+
+	if (opts.dryRun) {
+		printInfo(`Would delete entity ${scope} and all its memories.`);
+		printInfo("No changes made.");
+		return;
+	}
+
+	if (!opts.force) {
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout,
+		});
+		const answer = await new Promise<string>((resolve) => {
+			rl.question(
+				`\n  \u26a0  Delete entity ${scope} AND all its memories? This cannot be undone. [y/N] `,
+				resolve,
+			);
+		});
+		rl.close();
+		if (answer.toLowerCase() !== "y") {
+			printInfo("Cancelled.");
+			process.exit(0);
+		}
+	}
+
+	const start = performance.now();
+	let result: Record<string, unknown>;
+	try {
+		result = await timedStatus("Deleting entity...", async () => {
+			return backend.deleteEntities({
+				userId: opts.userId,
+				agentId: opts.agentId,
+				appId: opts.appId,
+				runId: opts.runId,
+			});
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent") {
+		formatAgentEnvelope({
+			command: "entity delete",
+			data: { deleted: true },
+			durationMs: Math.round(elapsed * 1000),
+		});
+	} else if (opts.output === "json") {
+		formatJson(result);
+	} else if (opts.output !== "quiet") {
+		printSuccess(`Entity deleted with all memories (${elapsed.toFixed(2)}s)`);
+	}
+}

cli/node/src/commands/events.ts

@@ -0,0 +1,169 @@
+/**
+ * Event commands: list and status.
+ */
+
+import boxen from "boxen";
+import Table from "cli-table3";
+import type { Backend } from "../backend/base.js";
+import { colors, printError, printInfo, timedStatus } from "../branding.js";
+import { formatAgentEnvelope, formatJson } from "../output.js";
+import { setCurrentCommand } from "../state.js";
+
+const { brand, accent, success, error: errorColor, warning, dim } = colors;
+
+function statusStyled(status: string): string {
+	switch (status.toUpperCase()) {
+		case "SUCCEEDED":
+			return success("SUCCEEDED");
+		case "PENDING":
+			return accent("PENDING");
+		case "FAILED":
+			return errorColor("FAILED");
+		case "PROCESSING":
+			return warning("PROCESSING");
+		default:
+			return status;
+	}
+}
+
+export async function cmdEventList(
+	backend: Backend,
+	opts: { output: string },
+): Promise<void> {
+	setCurrentCommand("event list");
+	const start = performance.now();
+	let results: Record<string, unknown>[];
+	try {
+		results = await timedStatus("Fetching events...", async () => {
+			return backend.listEvents();
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "event list",
+			data: results,
+			count: results.length,
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
+
+	if (results.length === 0) {
+		console.log();
+		printInfo("No events found.");
+		console.log();
+		return;
+	}
+
+	const table = new Table({
+		head: [
+			accent("Event ID"),
+			accent("Type"),
+			accent("Status"),
+			accent("Latency"),
+			accent("Created"),
+		],
+		colWidths: [12, 14, 14, 10, 22],
+		wordWrap: true,
+		style: { head: [], border: [] },
+	});
+
+	for (const ev of results) {
+		const evId = String(ev.id ?? "").slice(0, 8);
+		const evType = String(ev.event_type ?? "—");
+		const status = String(ev.status ?? "—");
+		const latency = ev.latency as number | undefined;
+		const latencyStr = latency !== undefined ? `${Math.round(latency)}ms` : "—";
+		const created = String(ev.created_at ?? "—")
+			.slice(0, 19)
+			.replace("T", " ");
+		table.push([dim(evId), evType, statusStyled(status), latencyStr, created]);
+	}
+
+	console.log();
+	console.log(table.toString());
+	console.log(
+		`  ${dim(`${results.length} event${results.length !== 1 ? "s" : ""}`)}`,
+	);
+	console.log();
+}
+
+export async function cmdEventStatus(
+	backend: Backend,
+	eventId: string,
+	opts: { output: string },
+): Promise<void> {
+	setCurrentCommand("event status");
+	const start = performance.now();
+	let ev: Record<string, unknown>;
+	try {
+		ev = await timedStatus("Fetching event...", async () => {
+			return backend.getEvent(eventId);
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "event status",
+			data: ev,
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
+
+	const status = String(ev.status ?? "—");
+	const evType = String(ev.event_type ?? "—");
+	const latency = ev.latency as number | undefined;
+	const latencyStr = latency !== undefined ? `${Math.round(latency)}ms` : "—";
+	const created = String(ev.created_at ?? "—")
+		.slice(0, 19)
+		.replace("T", " ");
+	const updated = String(ev.updated_at ?? "—")
+		.slice(0, 19)
+		.replace("T", " ");
+	const results = ev.results as Record<string, unknown>[] | undefined;
+
+	const lines: string[] = [];
+	lines.push(`  ${dim("Event ID:")}     ${eventId}`);
+	lines.push(`  ${dim("Type:")}         ${evType}`);
+	lines.push(`  ${dim("Status:")}       ${statusStyled(status)}`);
+	lines.push(`  ${dim("Latency:")}      ${latencyStr}`);
+	lines.push(`  ${dim("Created:")}      ${created}`);
+	lines.push(`  ${dim("Updated:")}      ${updated}`);
+
+	if (results && results.length > 0) {
+		lines.push("");
+		lines.push(`  ${dim(`Results (${results.length}):`)}`);
+		for (const r of results) {
+			const memId = String(r.id ?? "").slice(0, 8);
+			const data = r.data as Record<string, unknown> | undefined;
+			const memory = data?.memory ? String(data.memory) : "";
+			const evName = String(r.event ?? "");
+			const user = String(r.user_id ?? "");
+			let detail = `${evName}  ${memory}`;
+			if (user) detail += `  ${dim(`(user_id=${user})`)}`;
+			lines.push(`    ${success("·")} ${detail}  ${dim(`(${memId})`)}`);
+		}
+	}
+
+	const content = lines.join("\n");
+	console.log();
+	console.log(
+		boxen(content, {
+			title: brand("Event Status"),
+			titleAlignment: "left",
+			borderColor: "magenta",
+			padding: 1,
+		}),
+	);
+	console.log();
+}

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

@@ -0,0 +1,612 @@
+/**
+ * mem0 init — interactive setup wizard.
+ */
+
+import fs from "node:fs";
+import readline from "node:readline";
+import { PlatformBackend } from "../backend/platform.js";
+import {
+	colors,
+	printBanner,
+	printError,
+	printInfo,
+	printSuccess,
+} from "../branding.js";
+import {
+	CONFIG_FILE,
+	DEFAULT_BASE_URL,
+	type Mem0Config,
+	createDefaultConfig,
+	loadConfig,
+	redactKey,
+	saveConfig,
+} from "../config.js";
+import { formatJsonEnvelope } from "../output.js";
+import { isAgentMode } from "../state.js";
+
+const { brand, dim } = colors;
+
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+
+function validateEmail(email: string): void {
+	if (!EMAIL_RE.test(email)) {
+		printError(`Invalid email address: ${JSON.stringify(email)}`);
+		process.exit(1);
+	}
+}
+
+/** @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,
+	baseUrl: string,
+): Promise<Record<string, unknown>> {
+	const url = baseUrl.replace(/\/+$/, "");
+	let codeValue = code;
+
+	const sourceHeaders = {
+		"Content-Type": "application/json",
+		"X-Mem0-Source": "cli",
+		"X-Mem0-Client-Language": "node",
+	};
+
+	if (!codeValue) {
+		const resp = await fetch(`${url}/api/v1/auth/email_code/`, {
+			method: "POST",
+			headers: sourceHeaders,
+			body: JSON.stringify({ email }),
+			signal: AbortSignal.timeout(30_000),
+		});
+		if (resp.status === 429) {
+			printError("Too many attempts. Try again in a few minutes.");
+			process.exit(1);
+		}
+		if (!resp.ok) {
+			let detail: string;
+			try {
+				const body = (await resp.json()) as Record<string, unknown>;
+				detail = (body.error ?? body.detail ?? resp.statusText) as string;
+			} catch {
+				detail = resp.statusText;
+			}
+			printError(`Failed to send code: ${detail}`);
+			process.exit(1);
+		}
+
+		printSuccess("Verification code sent! Check your email.");
+
+		if (!process.stdin.isTTY) {
+			printError(
+				"No --code provided and terminal is non-interactive.",
+				"Run: mem0 init --email <email> --code <code>",
+			);
+			process.exit(1);
+		}
+
+		console.log();
+		const entered = await promptLine(`  ${brand("Verification Code")}`);
+		if (!entered) {
+			printError("Code is required.");
+			process.exit(1);
+		}
+		codeValue = entered;
+	}
+
+	const verifyResp = await fetch(`${url}/api/v1/auth/email_code/verify/`, {
+		method: "POST",
+		headers: sourceHeaders,
+		body: JSON.stringify({ email, code: codeValue.trim() }),
+		signal: AbortSignal.timeout(30_000),
+	});
+	if (verifyResp.status === 429) {
+		printError("Too many attempts. Try again in a few minutes.");
+		process.exit(1);
+	}
+	if (!verifyResp.ok) {
+		let detail: string;
+		try {
+			const body = (await verifyResp.json()) as Record<string, unknown>;
+			detail = (body.error ?? body.detail ?? verifyResp.statusText) as string;
+		} catch {
+			detail = verifyResp.statusText;
+		}
+		printError(`Verification failed: ${detail}`);
+		process.exit(1);
+	}
+
+	return verifyResp.json() as Promise<Record<string, unknown>>;
+}
+
+function promptSecret(label: string): Promise<string> {
+	return new Promise((resolve, reject) => {
+		process.stdout.write(label);
+
+		if (process.stdin.isTTY) {
+			process.stdin.setRawMode(true);
+		}
+		process.stdin.resume();
+		process.stdin.setEncoding("utf-8");
+
+		const chars: string[] = [];
+
+		const onData = (key: string) => {
+			for (const ch of key) {
+				if (ch === "\r" || ch === "\n") {
+					cleanup();
+					process.stdout.write("\n");
+					resolve(chars.join(""));
+					return;
+				}
+				if (ch === "\x03") {
+					cleanup();
+					reject(new Error("Interrupted"));
+					return;
+				}
+				if (ch === "\x7f" || ch === "\x08") {
+					// backspace
+					if (chars.length > 0) {
+						chars.pop();
+						process.stdout.write("\b \b");
+					}
+				} else if (ch === "\x15") {
+					// Ctrl+U — clear line
+					process.stdout.write("\b \b".repeat(chars.length));
+					chars.length = 0;
+				} else if (ch >= " ") {
+					chars.push(ch);
+					process.stdout.write("*");
+				}
+			}
+		};
+
+		const cleanup = () => {
+			process.stdin.removeListener("data", onData);
+			if (process.stdin.isTTY) {
+				process.stdin.setRawMode(false);
+			}
+			process.stdin.pause();
+		};
+
+		process.stdin.on("data", onData);
+	});
+}
+
+function promptLine(label: string, defaultValue?: string): Promise<string> {
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+	const prompt = defaultValue ? `${label} [${defaultValue}]: ` : `${label}: `;
+	return new Promise((resolve) => {
+		rl.question(prompt, (answer) => {
+			rl.close();
+			resolve(answer.trim() || defaultValue || "");
+		});
+	});
+}
+
+async function setupPlatform(config: Mem0Config): Promise<void> {
+	console.log();
+	console.log(
+		`  ${dim("Get your API key at https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-node")}`,
+	);
+	console.log();
+
+	process.stdout.write(`  ${brand("API Key")}: `);
+	const apiKey = await promptSecret("");
+	if (!apiKey) {
+		printError("API key is required.");
+		process.exit(1);
+	}
+	config.platform.apiKey = apiKey;
+	config.platform.createdVia = "api_key";
+}
+
+async function setupDefaults(config: Mem0Config): Promise<void> {
+	console.log();
+	printInfo("Set default entity IDs (press Enter to skip).\n");
+
+	const _systemUser = process.env.USER || process.env.USERNAME || "mem0-cli";
+	const userId = await promptLine(
+		`  ${brand("Default User ID")} ${dim("(recommended)")}`,
+		_systemUser,
+	);
+	if (userId) config.defaults.userId = userId;
+}
+
+async function validatePlatform(config: Mem0Config): Promise<void> {
+	console.log();
+	printInfo("Validating connection...");
+	try {
+		const backend = new PlatformBackend(config.platform);
+		const status = await backend.status({
+			userId: config.defaults.userId || undefined,
+			agentId: config.defaults.agentId || undefined,
+		});
+		if (status.connected) {
+			printSuccess("Connected to mem0 Platform!");
+			// Cache user_email from ping response for telemetry distinct_id
+			try {
+				const pingData = (await backend.ping()) as Record<string, unknown>;
+				const userEmail = pingData?.user_email as string | undefined;
+				if (userEmail) {
+					config.platform.userEmail = userEmail;
+				}
+			} catch {
+				/* ignore — telemetry ID will fall back to API key hash */
+			}
+		} else {
+			printError(
+				`Could not connect: ${status.error ?? "Unknown error"}`,
+				"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) {
+		printError(`Connection test failed: ${e instanceof Error ? e.message : e}`);
+	}
+}
+
+export async function runInit(
+	opts: {
+		apiKey?: string;
+		userId?: string;
+		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) {
+		printError("--code requires --email.");
+		process.exit(1);
+	}
+	if (opts.email && opts.apiKey) {
+		printError("Cannot use both --api-key and --email.");
+		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 &&
+		fs.existsSync(CONFIG_FILE) &&
+		savedConfig.platform.apiKey
+	) {
+		console.log(
+			`\n  ${brand("Existing configuration found")} ${dim(`(API key: ${redactKey(savedConfig.platform.apiKey)})`)}`,
+		);
+		if (process.stdin.isTTY) {
+			const rl = readline.createInterface({
+				input: process.stdin,
+				output: process.stdout,
+			});
+			const answer = await new Promise<string>((resolve) => {
+				rl.question(
+					"  Overwrite existing config? This cannot be undone. [y/N] ",
+					resolve,
+				);
+			});
+			rl.close();
+			if (answer.toLowerCase() !== "y") {
+				printInfo("Cancelled. Use --force to skip this check.");
+				process.exit(0);
+			}
+		} else {
+			printError(
+				"Existing config would be overwritten.",
+				"Use --force to overwrite.",
+			);
+			process.exit(1);
+		}
+	}
+
+	// ── Email login flow ──────────────────────────────────────────────────────
+	if (opts.email) {
+		const email = opts.email.trim().toLowerCase();
+		validateEmail(email);
+
+		printBanner();
+		console.log();
+		printInfo(`Logging in as ${email}...\n`);
+
+		const result = await emailLogin(email, opts.code, baseUrl);
+
+		const apiKeyVal = result.api_key as string | undefined;
+		if (!apiKeyVal) {
+			printError(
+				"Auth succeeded but no API key was returned. Contact support.",
+			);
+			process.exit(1);
+		}
+
+		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";
+
+		saveConfig(config);
+		console.log();
+		printSuccess("Authenticated! Configuration saved to ~/.mem0/config.json");
+		console.log();
+		console.log(`  ${dim("Get started:")}`);
+		console.log(`  ${dim('  mem0 add "I prefer dark mode"')}`);
+		console.log(`  ${dim('  mem0 search "preferences"')}`);
+		console.log();
+		return;
+	}
+
+	// ── 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>, --email <addr>, or --agent for unattended Agent Mode bootstrap.",
+			);
+			process.exit(1);
+		}
+		opts.userId =
+			opts.userId || process.env.USER || process.env.USERNAME || "mem0-cli";
+	}
+
+	// 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);
+		printSuccess("Configuration saved to ~/.mem0/config.json");
+		return;
+	}
+
+	printBanner();
+	console.log();
+	printInfo("Welcome! Let's set up your mem0 CLI.\n");
+
+	// Use provided API key or prompt
+	if (opts.apiKey) {
+		config.platform.apiKey = opts.apiKey;
+	} else {
+		console.log(`  ${brand("How would you like to authenticate?")}`);
+		console.log(`  ${dim("1.")} Login with email ${dim("(recommended)")}`);
+		console.log(`  ${dim("2.")} Enter API key manually`);
+		console.log();
+
+		const choice = await promptLine(`  ${brand("Choose")} [1/2]`, "1");
+
+		if (choice === "1") {
+			console.log();
+			const emailAddr = await promptLine(`  ${brand("Email")}`);
+			if (!emailAddr) {
+				printError("Email is required.");
+				process.exit(1);
+			}
+
+			const email = emailAddr.trim().toLowerCase();
+			validateEmail(email);
+			printInfo(`Logging in as ${email}...\n`);
+
+			const result = await emailLogin(email, undefined, baseUrl);
+
+			const apiKeyVal = result.api_key as string | undefined;
+			if (!apiKeyVal) {
+				printError(
+					"Auth succeeded but no API key was returned. Contact support.",
+				);
+				process.exit(1);
+			}
+
+			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";
+
+			saveConfig(config);
+			console.log();
+			printSuccess("Authenticated! Configuration saved to ~/.mem0/config.json");
+			console.log();
+			console.log(`  ${dim("Get started:")}`);
+			console.log(`  ${dim('  mem0 add "I prefer dark mode"')}`);
+			console.log(`  ${dim('  mem0 search "preferences"')}`);
+			console.log();
+			return;
+		}
+
+		// choice === "2": fall through to API key prompt
+		await setupPlatform(config);
+	}
+
+	// Use provided user ID or prompt
+	if (opts.userId) {
+		config.defaults.userId = opts.userId;
+	} else {
+		await setupDefaults(config);
+	}
+
+	await validatePlatform(config);
+
+	saveConfig(config);
+	console.log();
+	printSuccess("Configuration saved to ~/.mem0/config.json");
+	console.log();
+	console.log(`  ${dim("Get started:")}`);
+	if (config.defaults.userId) {
+		console.log(`  ${dim('  mem0 add "I prefer dark mode"')}`);
+		console.log(`  ${dim('  mem0 search "preferences"')}`);
+	} else {
+		console.log(`  ${dim('  mem0 add "I prefer dark mode" --user-id alice')}`);
+		console.log(`  ${dim('  mem0 search "preferences" --user-id alice')}`);
+	}
+	console.log();
+}

cli/node/src/commands/memory.ts

@@ -0,0 +1,747 @@
+/**
+ * Memory CRUD commands: add, search, get, list, update, delete.
+ */
+
+import fs from "node:fs";
+import type { Backend } from "../backend/base.js";
+import {
+	printError,
+	printInfo,
+	printScope,
+	printSuccess,
+	timedStatus,
+} from "../branding.js";
+import {
+	formatAddResult,
+	formatAgentEnvelope,
+	formatJson,
+	formatJsonEnvelope,
+	formatMemoriesTable,
+	formatMemoriesText,
+	formatSingleMemory,
+	printResultSummary,
+} from "../output.js";
+import { isAgentMode, setCurrentCommand, stdinIsPiped } from "../state.js";
+
+/** 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);
+	}
+}
+
+export async function cmdAdd(
+	backend: Backend,
+	text: string | undefined,
+	opts: {
+		userId?: string;
+		agentId?: string;
+		appId?: string;
+		runId?: string;
+		messages?: string;
+		file?: string;
+		metadata?: string;
+		immutable: boolean;
+		infer?: boolean;
+		expires?: string;
+		categories?: string;
+		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;
+
+	// Read from file
+	if (opts.file) {
+		try {
+			const raw = fs.readFileSync(opts.file, "utf-8");
+			msgs = JSON.parse(raw);
+		} catch (e) {
+			printError(`Failed to read file: ${e instanceof Error ? e.message : e}`);
+			process.exit(1);
+		}
+	}
+	// Parse messages JSON
+	else if (opts.messages) {
+		try {
+			msgs = JSON.parse(opts.messages);
+		} catch (e) {
+			printError(
+				`Invalid JSON in --messages: ${e instanceof Error ? e.message : e}`,
+			);
+			process.exit(1);
+		}
+	}
+	// Read from stdin only if stdin is an actual pipe or file redirect
+	else if (!content && stdinIsPiped()) {
+		content = fs.readFileSync(0, "utf-8").trim();
+	}
+
+	if (content !== undefined && content.trim() === "") {
+		printError("Content cannot be empty.");
+		process.exit(1);
+	}
+	if (!content && !msgs) {
+		printError(
+			"No content provided. Pass text, --messages, --file, or pipe via stdin.",
+		);
+		process.exit(1);
+	}
+
+	let meta: Record<string, unknown> | undefined;
+	if (opts.metadata) {
+		try {
+			meta = JSON.parse(opts.metadata);
+		} catch {
+			printError("Invalid JSON in --metadata.");
+			process.exit(1);
+		}
+	}
+
+	let customCats: Record<string, string>[] | undefined;
+	if (opts.customCategories) {
+		try {
+			customCats = JSON.parse(opts.customCategories);
+		} catch {
+			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 () => {
+			return backend.add(content ?? undefined, msgs, {
+				userId: opts.userId,
+				agentId: opts.agentId,
+				appId: opts.appId,
+				runId: opts.runId,
+				metadata: meta,
+				immutable: opts.immutable,
+				infer: opts.infer !== false,
+				expires: opts.expires,
+				customInstructions: opts.customInstructions,
+				agentCustomInstructions: opts.agentCustomInstructions,
+				customCategories: customCats,
+				structuredDataSchema: schema,
+				timestamp: opts.timestamp,
+			});
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+
+	if (opts.output === "quiet") return;
+
+	// Deduplicate PENDING entries sharing the same event_id across all output modes
+	const rawResults: Record<string, unknown>[] = Array.isArray(result)
+		? result
+		: ((result.results as Record<string, unknown>[]) ?? [result]);
+	const seenEvents = new Set<string>();
+	const deduped: Record<string, unknown>[] = [];
+	for (const r of rawResults) {
+		if (r.status === "PENDING") {
+			const eid = (r.event_id as string) ?? "";
+			if (eid && seenEvents.has(eid)) continue;
+			if (eid) seenEvents.add(eid);
+		}
+		deduped.push(r);
+	}
+	// Write back so downstream formatters see deduplicated data
+	const dedupedResult: Record<string, unknown> = Array.isArray(result)
+		? (deduped as unknown as Record<string, unknown>)
+		: { ...result, results: deduped };
+
+	if (opts.output === "agent") {
+		const scope: Record<string, string | undefined> = {
+			user_id: opts.userId,
+			agent_id: opts.agentId,
+			app_id: opts.appId,
+			run_id: opts.runId,
+		};
+		formatAgentEnvelope({
+			command: "add",
+			data: deduped,
+			scope,
+			count: deduped.length,
+		});
+		return;
+	}
+
+	if (opts.output === "json") {
+		formatAddResult(dedupedResult, opts.output);
+		return;
+	}
+
+	console.log();
+	printScope({
+		user_id: opts.userId,
+		agent_id: opts.agentId,
+		app_id: opts.appId,
+		run_id: opts.runId,
+	});
+	const count = deduped.length;
+	const allPending = count > 0 && deduped.every((r) => r.status === "PENDING");
+	if (allPending) {
+		printSuccess(
+			`Memory queued — ${count} event${count !== 1 ? "s" : ""} pending`,
+		);
+	} else {
+		printSuccess(
+			`Memory processed — ${count} memor${count === 1 ? "y" : "ies"} extracted`,
+		);
+	}
+	formatAddResult(dedupedResult, opts.output);
+}
+
+export async function cmdSearch(
+	backend: Backend,
+	query: string | undefined,
+	opts: {
+		userId?: string;
+		agentId?: string;
+		appId?: string;
+		runId?: string;
+		topK: number;
+		threshold: number;
+		rerank: boolean;
+		keyword: boolean;
+		filterJson?: string;
+		fields?: string;
+		showExpired?: boolean;
+		referenceDate?: string;
+		latestOnly?: boolean;
+		output: string;
+	},
+): Promise<void> {
+	setCurrentCommand("search");
+	if (!query) {
+		printError("No query provided. Pass a query argument or pipe via stdin.");
+		process.exit(1);
+	}
+
+	let filters: Record<string, unknown> | undefined;
+	if (opts.filterJson) {
+		try {
+			filters = JSON.parse(opts.filterJson);
+		} catch {
+			printError("Invalid JSON in --filter.");
+			process.exit(1);
+		}
+	}
+
+	const fieldList = opts.fields
+		? opts.fields.split(",").map((f) => f.trim())
+		: undefined;
+
+	if (opts.topK < 1) {
+		printError("--top-k must be >= 1.");
+		process.exit(1);
+	}
+	if (opts.threshold < 0 || opts.threshold > 1) {
+		printError("--threshold must be between 0.0 and 1.0.");
+		process.exit(1);
+	}
+
+	const start = performance.now();
+	let results: Record<string, unknown>[];
+	try {
+		results = await timedStatus("Searching memories...", async () => {
+			// biome-ignore lint/style/noNonNullAssertion: guarded by process.exit above
+			return backend.search(query!, {
+				userId: opts.userId,
+				agentId: opts.agentId,
+				appId: opts.appId,
+				runId: opts.runId,
+				topK: opts.topK,
+				threshold: opts.threshold,
+				rerank: opts.rerank,
+				keyword: opts.keyword,
+				filters,
+				fields: fieldList,
+				showExpired: opts.showExpired,
+				referenceDate: opts.referenceDate,
+				latestOnly: opts.latestOnly,
+			});
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "quiet") return;
+
+	if (opts.output === "agent") {
+		const scope: Record<string, string | undefined> = {
+			user_id: opts.userId,
+			agent_id: opts.agentId,
+			app_id: opts.appId,
+			run_id: opts.runId,
+		};
+		formatAgentEnvelope({
+			command: "search",
+			data: results,
+			scope,
+			count: results.length,
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
+
+	if (opts.output === "json") {
+		formatJson(results);
+	} else if (opts.output === "table") {
+		if (results.length > 0) {
+			formatMemoriesTable(results, { showScore: true });
+			printResultSummary({
+				count: results.length,
+				durationSecs: elapsed,
+				scopeIds: { user_id: opts.userId, agent_id: opts.agentId },
+			});
+		} else {
+			console.log();
+			printInfo("No memories found matching your query.");
+			console.log();
+		}
+	} else {
+		if (results.length > 0) {
+			formatMemoriesText(results);
+			printResultSummary({
+				count: results.length,
+				durationSecs: elapsed,
+				scopeIds: { user_id: opts.userId, agent_id: opts.agentId },
+			});
+		} else {
+			console.log();
+			printInfo("No memories found matching your query.");
+			console.log();
+		}
+	}
+}
+
+export async function cmdGet(
+	backend: Backend,
+	memoryId: string,
+	opts: { output: string },
+): Promise<void> {
+	setCurrentCommand("get");
+	let result: Record<string, unknown>;
+	try {
+		result = await timedStatus("Fetching memory...", async () => {
+			return backend.get(memoryId);
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+
+	if (opts.output === "agent") {
+		formatAgentEnvelope({ command: "get", data: result });
+	} else {
+		formatSingleMemory(result, opts.output);
+	}
+}
+
+export async function cmdList(
+	backend: Backend,
+	opts: {
+		userId?: string;
+		agentId?: string;
+		appId?: string;
+		runId?: string;
+		page: number;
+		pageSize: number;
+		category?: string;
+		after?: string;
+		before?: string;
+		showExpired?: boolean;
+		latestOnly?: boolean;
+		output: string;
+	},
+): Promise<void> {
+	setCurrentCommand("list");
+	if (opts.pageSize < 1) {
+		printError("--page-size must be >= 1.");
+		process.exit(1);
+	}
+	if (opts.page < 1) {
+		printError("--page must be >= 1.");
+		process.exit(1);
+	}
+
+	const start = performance.now();
+	let results: Record<string, unknown>[];
+	try {
+		results = await timedStatus("Listing memories...", async () => {
+			return backend.listMemories({
+				userId: opts.userId,
+				agentId: opts.agentId,
+				appId: opts.appId,
+				runId: opts.runId,
+				page: opts.page,
+				pageSize: opts.pageSize,
+				category: opts.category,
+				after: opts.after,
+				before: opts.before,
+				showExpired: opts.showExpired,
+				latestOnly: opts.latestOnly,
+			});
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "quiet") return;
+
+	if (opts.output === "agent" || opts.output === "json") {
+		const scope: Record<string, string | undefined> = {
+			user_id: opts.userId,
+			agent_id: opts.agentId,
+			app_id: opts.appId,
+			run_id: opts.runId,
+		};
+		formatAgentEnvelope({
+			command: "list",
+			data: results,
+			scope,
+			count: results.length,
+			durationMs: Math.round(elapsed * 1000),
+		});
+	} else if (opts.output === "table") {
+		if (results.length > 0) {
+			formatMemoriesTable(results);
+			printResultSummary({
+				count: results.length,
+				durationSecs: elapsed,
+				page: opts.page,
+				scopeIds: { user_id: opts.userId, agent_id: opts.agentId },
+			});
+		} else {
+			console.log();
+			printInfo("No memories found.");
+			console.log();
+		}
+	} else {
+		if (results.length > 0) {
+			formatMemoriesText(results, "memories");
+			printResultSummary({
+				count: results.length,
+				durationSecs: elapsed,
+				page: opts.page,
+				scopeIds: { user_id: opts.userId, agent_id: opts.agentId },
+			});
+		} else {
+			console.log();
+			printInfo("No memories found.");
+			console.log();
+		}
+	}
+}
+
+export async function cmdUpdate(
+	backend: Backend,
+	memoryId: string,
+	text: string | undefined,
+	opts: {
+		metadata?: string;
+		expires?: string;
+		timestamp?: number;
+		output: string;
+	},
+): Promise<void> {
+	setCurrentCommand("update");
+	let meta: Record<string, unknown> | undefined;
+	if (opts.metadata) {
+		try {
+			meta = JSON.parse(opts.metadata);
+		} catch {
+			printError("Invalid JSON in --metadata.");
+			process.exit(1);
+		}
+	}
+
+	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, {
+				expirationDate: opts.expires,
+				timestamp: opts.timestamp,
+			});
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent") {
+		formatAgentEnvelope({
+			command: "update",
+			data: result,
+			durationMs: Math.round(elapsed * 1000),
+		});
+	} else if (opts.output === "json") {
+		formatJson(result);
+	} else if (opts.output !== "quiet") {
+		printSuccess(
+			`Memory ${memoryId.slice(0, 8)} updated (${elapsed.toFixed(2)}s)`,
+		);
+	}
+}
+
+export async function cmdDelete(
+	backend: Backend,
+	memoryId: string,
+	opts: {
+		output: string;
+		dryRun?: boolean;
+		force?: boolean;
+		deleteLinked?: boolean;
+	},
+): Promise<void> {
+	setCurrentCommand("delete");
+	if (opts.dryRun) {
+		let mem: Record<string, unknown>;
+		try {
+			mem = await backend.get(memoryId);
+		} catch (e) {
+			printError(e instanceof Error ? e.message : String(e));
+			process.exit(1);
+		}
+		const text = (mem.memory ?? mem.text ?? "") as string;
+		printInfo(`Would delete memory ${memoryId.slice(0, 8)}: ${text}`);
+		printInfo("No changes made.");
+		return;
+	}
+
+	const start = performance.now();
+	let result: Record<string, unknown>;
+	try {
+		result = await timedStatus("Deleting...", async () => {
+			return backend.delete(memoryId, { deleteLinked: opts.deleteLinked });
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent") {
+		formatAgentEnvelope({
+			command: "delete",
+			data: { id: memoryId, deleted: true },
+			durationMs: Math.round(elapsed * 1000),
+		});
+	} else if (opts.output === "json") {
+		formatJson(result);
+	} else if (opts.output !== "quiet") {
+		printSuccess(
+			`Memory ${memoryId.slice(0, 8)} deleted (${elapsed.toFixed(2)}s)`,
+		);
+	}
+}
+
+export async function cmdDeleteAll(
+	backend: Backend,
+	opts: {
+		force: boolean;
+		dryRun?: boolean;
+		all?: boolean;
+		userId?: string;
+		agentId?: string;
+		appId?: string;
+		runId?: string;
+		output: string;
+	},
+): Promise<void> {
+	setCurrentCommand("delete-all");
+	const { isAgentMode } = await import("../state.js");
+	if (isAgentMode() && !opts.force) {
+		printError("Destructive operation requires --force in agent mode.");
+		process.exit(1);
+	}
+	if (opts.all) {
+		// Project-wide wipe using wildcard entity IDs
+		// Note: --dry-run is ignored here because the API has no count-before-delete endpoint.
+
+		if (!opts.force) {
+			const readline = await import("node:readline");
+			const rl = readline.createInterface({
+				input: process.stdin,
+				output: process.stdout,
+			});
+			const answer = await new Promise<string>((resolve) => {
+				rl.question(
+					"\n  \u26a0  Delete ALL memories across the ENTIRE project? This cannot be undone. [y/N] ",
+					resolve,
+				);
+			});
+			rl.close();
+			if (answer.toLowerCase() !== "y") {
+				printInfo("Cancelled.");
+				process.exit(0);
+			}
+		}
+
+		const start = performance.now();
+		let result: Record<string, unknown>;
+		try {
+			result = await timedStatus(
+				"Deleting all memories project-wide...",
+				async () => {
+					return backend.delete(undefined, {
+						all: true,
+						userId: "*",
+						agentId: "*",
+						appId: "*",
+						runId: "*",
+					});
+				},
+			);
+		} catch (e) {
+			printError(e instanceof Error ? e.message : String(e));
+			process.exit(1);
+		}
+		const elapsed = (performance.now() - start) / 1000;
+
+		if (opts.output === "agent") {
+			formatAgentEnvelope({
+				command: "delete-all",
+				data: result,
+				durationMs: Math.round(elapsed * 1000),
+			});
+		} else if (opts.output === "json") {
+			formatJson(result);
+		} else if (opts.output !== "quiet") {
+			if (result.message) {
+				printInfo(
+					"Deletion started. Memories will be removed in the background.",
+				);
+			} else {
+				printSuccess(`All project memories deleted (${elapsed.toFixed(2)}s)`);
+			}
+		}
+		return;
+	}
+
+	if (opts.dryRun) {
+		let memories: Record<string, unknown>[];
+		try {
+			memories = await backend.listMemories({
+				userId: opts.userId,
+				agentId: opts.agentId,
+				appId: opts.appId,
+				runId: opts.runId,
+			});
+		} catch (e) {
+			printError(e instanceof Error ? e.message : String(e));
+			process.exit(1);
+		}
+		printInfo(`Would delete ${memories.length} memories.`);
+		printInfo("No changes made.");
+		return;
+	}
+
+	if (!opts.force) {
+		const scopeParts: string[] = [];
+		if (opts.userId) scopeParts.push(`user=${opts.userId}`);
+		if (opts.agentId) scopeParts.push(`agent=${opts.agentId}`);
+		if (opts.appId) scopeParts.push(`app=${opts.appId}`);
+		if (opts.runId) scopeParts.push(`run=${opts.runId}`);
+		const scope =
+			scopeParts.length > 0 ? scopeParts.join(", ") : "ALL entities";
+
+		const readline = await import("node:readline");
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout,
+		});
+		const answer = await new Promise<string>((resolve) => {
+			rl.question(
+				`\n  \u26a0  Delete ALL memories for ${scope}? This cannot be undone. [y/N] `,
+				resolve,
+			);
+		});
+		rl.close();
+		if (answer.toLowerCase() !== "y") {
+			printInfo("Cancelled.");
+			process.exit(0);
+		}
+	}
+
+	const start = performance.now();
+	let result: Record<string, unknown>;
+	try {
+		result = await timedStatus("Deleting all memories...", async () => {
+			return backend.delete(undefined, {
+				all: true,
+				userId: opts.userId,
+				agentId: opts.agentId,
+				appId: opts.appId,
+				runId: opts.runId,
+			});
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent") {
+		formatAgentEnvelope({
+			command: "delete-all",
+			data: result,
+			durationMs: Math.round(elapsed * 1000),
+		});
+	} else if (opts.output === "json") {
+		formatJson(result);
+	} else if (opts.output !== "quiet") {
+		if (result.message) {
+			printInfo(
+				"Deletion started. Memories will be removed in the background.",
+			);
+		} else {
+			printSuccess(`All matching memories deleted (${elapsed.toFixed(2)}s)`);
+		}
+	}
+}

cli/node/src/commands/utils.ts

@@ -0,0 +1,150 @@
+/**
+ * Utility commands: status, import.
+ */
+
+import fs from "node:fs";
+import boxen from "boxen";
+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";
+
+const { brand, dim, success, error: errorColor } = colors;
+
+export async function cmdStatus(
+	backend: Backend,
+	opts: { userId?: string; agentId?: string; output?: string } = {},
+): Promise<void> {
+	setCurrentCommand("status");
+	const start = performance.now();
+	let result: Record<string, unknown>;
+	try {
+		result = await timedStatus("Checking connection...", async () => {
+			return backend.status({ userId: opts.userId, agentId: opts.agentId });
+		});
+	} catch (e) {
+		result = {
+			connected: false,
+			error: e instanceof Error ? e.message : String(e),
+		};
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "status",
+			data: {
+				connected: result.connected,
+				backend: result.backend ?? null,
+				base_url: result.base_url ?? null,
+			},
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
+
+	const lines: string[] = [];
+	if (result.connected) {
+		lines.push(`  ${success("\u25cf")} Connected`);
+	} else {
+		lines.push(`  ${errorColor("\u25cf")} Disconnected`);
+	}
+
+	lines.push(`  ${dim("Backend:")}  ${result.backend ?? "?"}`);
+	if (result.base_url) {
+		lines.push(`  ${dim("API URL:")}  ${result.base_url}`);
+	}
+	if (result.error) {
+		lines.push(`  ${errorColor("Error:")}    ${result.error}`);
+		if (String(result.error).includes("Authentication failed")) {
+			lines.push("");
+			lines.push(
+				`  ${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?utm_source=oss&utm_medium=cli-node")}`,
+			);
+		}
+	}
+	lines.push(`  ${dim("Latency:")}  ${elapsed.toFixed(2)}s`);
+
+	const content = lines.join("\n");
+	console.log();
+	console.log(
+		boxen(content, {
+			title: brand("Connection Status"),
+			titleAlignment: "left",
+			borderColor: "magenta",
+			padding: 1,
+		}),
+	);
+	console.log();
+}
+
+export async function cmdImport(
+	backend: Backend,
+	filePath: string,
+	opts: { userId?: string; agentId?: string; output?: string },
+): Promise<void> {
+	setCurrentCommand("import");
+	let data: Record<string, unknown>[];
+	try {
+		const raw = fs.readFileSync(filePath, "utf-8");
+		const parsed = JSON.parse(raw);
+		data = Array.isArray(parsed) ? parsed : [parsed];
+	} catch (e) {
+		printError(`Failed to read file: ${e instanceof Error ? e.message : e}`);
+		process.exit(1);
+	}
+
+	let added = 0;
+	let failed = 0;
+	const start = performance.now();
+
+	for (let i = 0; i < data.length; i++) {
+		const item = data[i];
+		const content = (item.memory ?? item.text ?? item.content ?? "") as string;
+		if (!content) {
+			failed++;
+			continue;
+		}
+
+		try {
+			await backend.add(content, undefined, {
+				userId: opts.userId ?? (item.user_id as string | undefined),
+				agentId: opts.agentId ?? (item.agent_id as string | undefined),
+				metadata: item.metadata as Record<string, unknown> | undefined,
+			});
+			added++;
+		} catch {
+			failed++;
+		}
+
+		// Simple progress indicator
+		if ((i + 1) % 10 === 0 || i === data.length - 1) {
+			process.stdout.write(
+				`\r  ${dim(`Importing memories... ${i + 1}/${data.length}`)}`,
+			);
+		}
+	}
+
+	const elapsed = (performance.now() - start) / 1000;
+	console.log(); // Clear progress line
+
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "import",
+			data: {
+				added,
+				failed,
+			},
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
+
+	printSuccess(`Imported ${added} memories (${elapsed.toFixed(2)}s)`);
+	if (failed > 0) {
+		printError(`${failed} memories failed to import.`);
+	}
+}

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

@@ -0,0 +1,232 @@
+/**
+ * Configuration management for mem0 CLI.
+ *
+ * Config precedence (highest to lowest):
+ * 1. CLI flags (--api-key, --base-url, etc.)
+ * 2. Environment variables (MEM0_API_KEY, etc.)
+ * 3. Config file (~/.mem0/config.json)
+ * 4. Defaults
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const CONFIG_DIR = path.join(os.homedir(), ".mem0");
+export const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+export const DEFAULT_BASE_URL = "https://api.mem0.ai";
+export const CONFIG_VERSION = 1;
+
+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 {
+	userId: string;
+	agentId: string;
+	appId: string;
+	runId: string;
+}
+
+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 {
+	return {
+		version: CONFIG_VERSION,
+		defaults: {
+			userId: "",
+			agentId: "",
+			appId: "",
+			runId: "",
+		},
+		platform: {
+			apiKey: "",
+			baseUrl: DEFAULT_BASE_URL,
+			userEmail: "",
+			agentMode: false,
+			createdVia: "",
+			agentCaller: "",
+			claimedAt: "",
+			defaultUserId: "",
+		},
+		telemetry: {
+			anonymousId: "",
+		},
+		agentRush: {
+			acknowledgedAt: "",
+		},
+	};
+}
+
+export function ensureConfigDir(): string {
+	fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+	return CONFIG_DIR;
+}
+
+export function loadConfig(): Mem0Config {
+	const config = createDefaultConfig();
+
+	if (fs.existsSync(CONFIG_FILE)) {
+		const raw = fs.readFileSync(CONFIG_FILE, "utf-8");
+		const data = JSON.parse(raw);
+
+		config.version = data.version ?? CONFIG_VERSION;
+
+		const plat = data.platform ?? {};
+		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 ?? "";
+		const telemetry = data.telemetry ?? {};
+		config.telemetry.anonymousId = telemetry.anonymous_id ?? "";
+		const agentRush = data.agent_rush ?? {};
+		config.agentRush.acknowledgedAt = agentRush.acknowledged_at ?? "";
+	}
+
+	// Environment variable overrides
+	if (process.env.MEM0_API_KEY)
+		config.platform.apiKey = process.env.MEM0_API_KEY;
+	if (process.env.MEM0_BASE_URL)
+		config.platform.baseUrl = process.env.MEM0_BASE_URL;
+	if (process.env.MEM0_USER_ID)
+		config.defaults.userId = process.env.MEM0_USER_ID;
+	if (process.env.MEM0_AGENT_ID)
+		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;
+	return config;
+}
+
+export function saveConfig(config: Mem0Config): void {
+	ensureConfigDir();
+
+	const data = {
+		version: config.version,
+		defaults: {
+			user_id: config.defaults.userId,
+			agent_id: config.defaults.agentId,
+			app_id: config.defaults.appId,
+			run_id: config.defaults.runId,
+		},
+		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 {
+	if (!key) return "(not set)";
+	if (key.length <= 8) return `${key.slice(0, 2)}***`;
+	return `${key.slice(0, 4)}...${key.slice(-4)}`;
+}
+
+/** Key map from dotted config path to the config object fields. */
+const KEY_MAP: Record<string, [keyof Mem0Config, string]> = {
+	"platform.api_key": ["platform", "apiKey"],
+	"platform.base_url": ["platform", "baseUrl"],
+	"platform.user_email": ["platform", "userEmail"],
+	"defaults.user_id": ["defaults", "userId"],
+	"defaults.agent_id": ["defaults", "agentId"],
+	"defaults.app_id": ["defaults", "appId"],
+	"defaults.run_id": ["defaults", "runId"],
+	// Short-form aliases
+	api_key: ["platform", "apiKey"],
+	base_url: ["platform", "baseUrl"],
+	user_email: ["platform", "userEmail"],
+	user_id: ["defaults", "userId"],
+	agent_id: ["defaults", "agentId"],
+	app_id: ["defaults", "appId"],
+	run_id: ["defaults", "runId"],
+};
+
+export function getNestedValue(config: Mem0Config, dottedKey: string): unknown {
+	const mapping = KEY_MAP[dottedKey];
+	if (!mapping) return undefined;
+	const [section, field] = mapping;
+	return (config[section] as unknown as Record<string, unknown>)[field];
+}
+
+export function setNestedValue(
+	config: Mem0Config,
+	dottedKey: string,
+	value: string,
+): boolean {
+	const mapping = KEY_MAP[dottedKey];
+	if (!mapping) return false;
+	const [section, field] = mapping;
+	const obj = config[section] as unknown as Record<string, unknown>;
+
+	const current = obj[field];
+	if (typeof current === "boolean") {
+		obj[field] = ["true", "1", "yes"].includes(value.toLowerCase());
+	} else if (typeof current === "number") {
+		obj[field] = Number.parseInt(value, 10);
+	} else {
+		obj[field] = value;
+	}
+	return true;
+}

cli/node/src/globals.d.ts

@@ -0,0 +1,2 @@
+/** Injected by tsup at build time from package.json version field. Undefined in dev/test. */
+declare const __CLI_VERSION__: string | undefined;

cli/node/src/help.ts

@@ -0,0 +1,387 @@
+/**
+ * Rich-style help formatter for Commander.js that matches the Python CLI's
+ * Typer + Rich output (rounded box panels, brand purple, grouped options).
+ */
+
+import chalk from "chalk";
+import type { Argument, Command, Help, Option } from "commander";
+// Colors imported from chalk directly to match Typer/Rich defaults
+
+// ── Colors (matching Typer/Rich defaults) ────────────────────────────────
+
+const cyanBold = chalk.cyan.bold; // option flags, command names
+const greenBold = chalk.green.bold; // switch flags (boolean --force etc)
+const yellowBold = chalk.yellow.bold; // metavar <value>
+const yellow = chalk.yellow; // "Usage:" label
+const bold = chalk.bold; // command name in usage
+const dim = chalk.dim; // defaults, descriptions
+const dimBorder = chalk.dim; // panel borders
+
+// ── Strip ANSI ───────────────────────────────────────────────────────────
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequence is intentional
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+function stripAnsi(str: string): number {
+	return str.replace(ANSI_RE, "").length;
+}
+
+// ── Command display order (matches Python CLI) ──────────────────────────
+
+/** Commands grouped into panels, matching Python CLI's rich_help_panel. */
+const COMMAND_GROUPS: { panel: string; commands: string[] }[] = [
+	{
+		panel: "Memory",
+		commands: ["add", "search", "get", "list", "update", "delete"],
+	},
+	{
+		panel: "Management",
+		commands: [
+			"init",
+			"status",
+			"version",
+			"import",
+			"help",
+			"entity",
+			"event",
+			"config",
+		],
+	},
+];
+
+/** Flat order derived from COMMAND_GROUPS. */
+const COMMAND_ORDER: string[] = COMMAND_GROUPS.flatMap((g) => g.commands);
+
+// ── Option-to-panel mapping (derived from Python's rich_help_panel) ─────
+
+const OPTION_PANELS: Record<string, Record<string, string>> = {
+	add: {
+		"--user-id": "Scope",
+		"--agent-id": "Scope",
+		"--app-id": "Scope",
+		"--run-id": "Scope",
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	search: {
+		"--user-id": "Scope",
+		"--agent-id": "Scope",
+		"--app-id": "Scope",
+		"--run-id": "Scope",
+		"--top-k": "Search",
+		"--threshold": "Search",
+		"--rerank": "Search",
+		"--keyword": "Search",
+		"--filter": "Search",
+		"--fields": "Search",
+		"--graph": "Search",
+		"--no-graph": "Search",
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	get: {
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	list: {
+		"--user-id": "Scope",
+		"--agent-id": "Scope",
+		"--app-id": "Scope",
+		"--run-id": "Scope",
+		"--page": "Pagination",
+		"--page-size": "Pagination",
+		"--category": "Filters",
+		"--after": "Filters",
+		"--before": "Filters",
+		"--graph": "Filters",
+		"--no-graph": "Filters",
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	update: {
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	delete: {
+		"--user-id": "Scope",
+		"--agent-id": "Scope",
+		"--app-id": "Scope",
+		"--run-id": "Scope",
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	status: {
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	import: {
+		"--user-id": "Scope",
+		"--agent-id": "Scope",
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+};
+
+const PANEL_ORDER: string[] = [
+	"Scope",
+	"Search",
+	"Pagination",
+	"Filters",
+	"Output",
+	"Connection",
+];
+
+// ── Panel rendering ─────────────────────────────────────────────────────
+
+/**
+ * Render a Rich-style ROUNDED box panel.
+ *
+ * ```
+ * ╭─ Title ────────────────────────╮
+ * │ row content padded             │
+ * ╰────────────────────────────────╯
+ * ```
+ */
+function renderPanel(title: string, rows: string[], width: number): string {
+	if (rows.length === 0) return "";
+
+	// Inner width is total width minus the two border chars
+	const inner = width - 2;
+
+	// Top border: ╭─ Title ─...─╮
+	const titleStr = ` ${title} `;
+	const fillLen = Math.max(0, inner - 1 - titleStr.length);
+	const topLine =
+		dimBorder("╭─") +
+		dimBorder(titleStr) +
+		dimBorder("─".repeat(fillLen)) +
+		dimBorder("╮");
+
+	// Bottom border: ╰─...─╯
+	const bottomLine =
+		dimBorder("╰") + dimBorder("─".repeat(inner)) + dimBorder("╯");
+
+	// Content rows
+	const contentLines = rows.map((row) => {
+		const visLen = stripAnsi(row);
+		const pad = Math.max(0, inner - 1 - visLen);
+		return `${dimBorder("│")} ${row}${" ".repeat(pad)}${dimBorder("│")}`;
+	});
+
+	return [topLine, ...contentLines, bottomLine].join("\n");
+}
+
+// ── Format an option term (short + long) ────────────────────────────────
+
+function formatOptionTerm(opt: Option): string {
+	const parts: string[] = [];
+	if (opt.short) parts.push(opt.short);
+	if (opt.long) parts.push(opt.long);
+	let term = parts.join(", ");
+
+	// Append value placeholder for non-boolean options
+	if (opt.flags) {
+		const match = opt.flags.match(/<[^>]+>|\[[^\]]+\]/);
+		if (match) {
+			term += ` ${match[0]}`;
+		}
+	}
+	return term;
+}
+
+// ── Get the long flag name for panel lookup ─────────────────────────────
+
+function getLongFlag(opt: Option): string {
+	if (opt.long) return opt.long;
+	return opt.short || "";
+}
+
+// ── Format a default value ──────────────────────────────────────────────
+
+function formatDefault(opt: Option): string {
+	if (opt.defaultValue !== undefined && opt.defaultValue !== false) {
+		return dim(` [default: ${opt.defaultValue}]`);
+	}
+	return "";
+}
+
+// ── The main help formatter ─────────────────────────────────────────────
+
+export function richFormatHelp(cmd: Command, helper: Help): string {
+	const width = process.stdout.columns || 80;
+	const lines: string[] = [];
+
+	const isRoot = !cmd.parent;
+
+	// ── Usage line ──
+	const usage = helper.commandUsage(cmd);
+	lines.push("");
+	if (isRoot) {
+		// Root: "Usage: mem0 <command> [options]" — <command> yellow, [options] bold
+		lines.push(
+			` ${yellow("Usage:")} ${bold(cmd.name())} ${yellow("<command>")} ${bold("[options]")}`,
+		);
+	} else {
+		// Subcommands: split into command path (bold) and args (yellow)
+		const usageParts = usage.split(" ");
+		const cmdPath: string[] = [];
+		const argParts: string[] = [];
+		let pastCmd = false;
+		for (const part of usageParts) {
+			if (!pastCmd && !part.startsWith("[") && !part.startsWith("<")) {
+				cmdPath.push(part);
+			} else {
+				pastCmd = true;
+				argParts.push(part);
+			}
+		}
+		lines.push(
+			` ${yellow("Usage:")} ${bold(cmdPath.join(" "))} ${yellow(argParts.join(" "))}`,
+		);
+	}
+	lines.push("");
+
+	// ── Description ──
+	const desc = helper.commandDescription(cmd);
+	if (desc) {
+		// Split multi-line descriptions (e.g., title + tagline)
+		const descLines = desc.split("\n");
+		for (let i = 0; i < descLines.length; i++) {
+			const dLine = descLines[i];
+			// First line is the title, subsequent non-empty lines are tagline (dimmed)
+			if (i === 0 || dLine.trim() === "") {
+				lines.push(` ${dLine}`);
+			} else {
+				lines.push(` ${dim(dLine)}`);
+			}
+		}
+		lines.push("");
+	}
+
+	// ── Arguments panel (subcommands only) ──
+	if (!isRoot) {
+		const visibleArgs = helper.visibleArguments(cmd);
+		if (visibleArgs.length > 0) {
+			const maxLen = Math.max(
+				...visibleArgs.map((a: Argument) => a.name().length),
+			);
+			const argRows = visibleArgs.map((a: Argument) => {
+				const name = cyanBold(a.name().padEnd(maxLen));
+				const description = helper.argumentDescription(a);
+				return ` ${name}  ${description}`;
+			});
+			const panel = renderPanel("Arguments", argRows, width);
+			if (panel) lines.push(panel);
+		}
+	}
+
+	// ── Collect options (grouped into panels for subcommands) ──
+	const visibleOpts = helper.visibleOptions(cmd);
+	const cmdName = cmd.name();
+	const panelMap =
+		!isRoot && OPTION_PANELS[cmdName] ? OPTION_PANELS[cmdName] : {};
+
+	const grouped: Record<string, Option[]> = { Options: [] };
+	for (const panelName of PANEL_ORDER) {
+		grouped[panelName] = [];
+	}
+
+	for (const opt of visibleOpts) {
+		const flag = getLongFlag(opt);
+		const panel = panelMap[flag];
+		if (panel && PANEL_ORDER.includes(panel)) {
+			grouped[panel].push(opt);
+		} else {
+			grouped.Options.push(opt);
+		}
+	}
+
+	// ── Collect commands ──
+	const visibleCmds = helper.visibleCommands(cmd);
+
+	if (isRoot) {
+		// ROOT: Options first, then command groups (matches Python/Typer ordering)
+		if (grouped.Options.length > 0) {
+			const optRows = formatOptionRows(grouped.Options);
+			const panel = renderPanel("Options", optRows, width);
+			if (panel) lines.push(panel);
+		}
+		if (visibleCmds.length > 0) {
+			const cmdMap = new Map(visibleCmds.map((c) => [c.name(), c]));
+			for (const group of COMMAND_GROUPS) {
+				const groupCmds = group.commands
+					.map((name) => cmdMap.get(name))
+					.filter((c): c is Command => c !== undefined);
+				if (groupCmds.length === 0) continue;
+				const maxLen = Math.max(...groupCmds.map((c) => c.name().length));
+				const cmdRows = groupCmds.map((c) => {
+					const name = cyanBold(c.name().padEnd(maxLen));
+					const description = helper.subcommandDescription(c);
+					return ` ${name}  ${description}`;
+				});
+				const panel = renderPanel(group.panel, cmdRows, width);
+				if (panel) lines.push(panel);
+			}
+		}
+	} else {
+		// SUBCOMMANDS: Options/panels first, then sub-subcommands
+		const panelSequence = ["Options", ...PANEL_ORDER];
+		for (const panelName of panelSequence) {
+			const opts = grouped[panelName];
+			if (opts && opts.length > 0) {
+				const optRows = formatOptionRows(opts);
+				const panel = renderPanel(panelName, optRows, width);
+				if (panel) lines.push(panel);
+			}
+		}
+		// Sub-subcommands (e.g., config show/get/set, entity list/delete)
+		if (visibleCmds.length > 0) {
+			const maxLen = Math.max(...visibleCmds.map((c) => c.name().length));
+			const cmdRows = visibleCmds.map((c) => {
+				const name = cyanBold(c.name().padEnd(maxLen));
+				const description = helper.subcommandDescription(c);
+				return ` ${name}  ${description}`;
+			});
+			const panel = renderPanel("Commands", cmdRows, width);
+			if (panel) lines.push(panel);
+		}
+	}
+
+	lines.push("");
+	return lines.join("\n");
+}
+
+// ── Format option rows with aligned columns ─────────────────────────────
+
+function formatOptionRows(opts: Option[]): string[] {
+	const terms = opts.map((o) => formatOptionTerm(o));
+	const maxTermLen = Math.max(...terms.map((t) => t.length));
+
+	return opts.map((opt, i) => {
+		const term = cyanBold(terms[i].padEnd(maxTermLen));
+		const desc = opt.description || "";
+		const def = formatDefault(opt);
+		return ` ${term}  ${desc}${def}`;
+	});
+}
+
+// ── Sort commands by COMMAND_ORDER ──────────────────────────────────────
+
+function sortCommands(cmds: Command[]): Command[] {
+	return [...cmds].sort((a, b) => {
+		const ai = COMMAND_ORDER.indexOf(a.name());
+		const bi = COMMAND_ORDER.indexOf(b.name());
+		// Unknown commands go to end, preserving original order
+		const aIdx = ai === -1 ? COMMAND_ORDER.length : ai;
+		const bIdx = bi === -1 ? COMMAND_ORDER.length : bi;
+		return aIdx - bIdx;
+	});
+}

cli/node/src/index.ts

@@ -0,0 +1,950 @@
+#!/usr/bin/env node
+
+/**
+ * Main CLI application — the entrypoint for `mem0`.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { AuthError, type Backend, getBackend } from "./backend/index.js";
+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 {
+	isAgentMode,
+	setAgentMode,
+	setCurrentCommand,
+	stdinIsPiped,
+	takeNotice,
+} from "./state.js";
+import { captureEvent } from "./telemetry.js";
+import { CLI_VERSION } from "./version.js";
+
+const program = new Command();
+
+// ── Validated user identity (set by getBackendAndConfig) ─────────────────
+
+let _validatedUserEmail: string | undefined;
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+async function getBackendAndConfig(
+	apiKey?: string,
+	baseUrl?: string,
+): Promise<{ backend: Backend; config: Mem0Config }> {
+	const config = loadConfig();
+
+	if (apiKey) config.platform.apiKey = apiKey;
+	if (baseUrl) config.platform.baseUrl = baseUrl;
+
+	if (!config.platform.apiKey) {
+		printError(
+			"No API key configured.",
+			"Run 'mem0 init' or set MEM0_API_KEY environment variable.",
+		);
+		process.exit(1);
+	}
+
+	const backend = getBackend(config);
+
+	// Validate the API key upfront with a fast timeout
+	try {
+		const pingData = (await Promise.race([
+			backend.ping(),
+			new Promise<never>((_, reject) =>
+				setTimeout(() => reject(new Error("timeout")), 5000),
+			),
+		])) as Record<string, unknown>;
+
+		const email = pingData?.user_email as string | undefined;
+		if (email) {
+			_validatedUserEmail = email;
+			if (config.platform.userEmail !== email) {
+				config.platform.userEmail = email;
+				try {
+					saveConfig(config);
+				} catch {
+					/* ignore */
+				}
+			}
+		}
+	} catch (e) {
+		if (e instanceof AuthError) {
+			printError(
+				"Invalid or expired API key.",
+				"Run 'mem0 init' or set MEM0_API_KEY environment variable.",
+			);
+			process.exit(1);
+		}
+		// Network error / timeout — warn but proceed
+		printWarning(
+			"Could not validate API key (network issue). Proceeding anyway.",
+		);
+	}
+
+	return { backend, config };
+}
+
+async function getBackendOnly(
+	apiKey?: string,
+	baseUrl?: string,
+): Promise<Backend> {
+	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);
+	if (isAgent) setAgentMode(true);
+	return isAgent;
+}
+
+/**
+ * Resolve entity IDs: CLI flag > config default > undefined.
+ *
+ * If any explicit ID is provided, only use explicit IDs (don't mix
+ * in defaults for other entity types which would over-filter).
+ * If no explicit IDs, fall back to all configured defaults.
+ */
+function resolveIds(
+	config: Mem0Config,
+	opts: {
+		userId?: string;
+		agentId?: string;
+		appId?: string;
+		runId?: string;
+	},
+): { userId?: string; agentId?: string; appId?: string; runId?: string } {
+	const hasExplicit = !!(
+		opts.userId ||
+		opts.agentId ||
+		opts.appId ||
+		opts.runId
+	);
+	if (hasExplicit) {
+		return {
+			userId: opts.userId || undefined,
+			agentId: opts.agentId || undefined,
+			appId: opts.appId || undefined,
+			runId: opts.runId || undefined,
+		};
+	}
+	return {
+		userId: config.defaults.userId || undefined,
+		agentId: config.defaults.agentId || undefined,
+		appId: config.defaults.appId || undefined,
+		runId: config.defaults.runId || undefined,
+	};
+}
+
+// ── Main program ──────────────────────────────────────────────────────────
+
+program
+	.name("mem0")
+	.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", () => {
+		printVersion();
+		process.exit(0);
+	})
+	.option("--json", "Output as JSON for agent/programmatic use.")
+	.option(
+		"--agent",
+		"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.")
+	.addHelpCommand(false)
+	.configureHelp({ formatHelp: richFormatHelp });
+
+// ── Telemetry hook ───────────────────────────────────────────────────────
+
+program.hook("preAction", (_thisCommand, actionCommand) => {
+	try {
+		const commandName = actionCommand.name();
+		const parentName = actionCommand.parent?.name();
+		const fullCommand =
+			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}`,
+			{
+				command: fullCommand,
+				is_agent: isAgent,
+			},
+			_validatedUserEmail,
+		);
+	} catch {
+		/* silently swallow */
+	}
+});
+
+// ── Init ──────────────────────────────────────────────────────────────────
+
+program
+	.command("init")
+	.description("Interactive setup wizard for mem0 CLI.")
+	.option("--api-key <key>", "API key (skip prompt).")
+	.option("-u, --user-id <id>", "Default user ID (skip prompt).")
+	.option("--email <email>", "Login via email verification code.")
+	.option(
+		"--code <code>",
+		"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\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,
+			userId: opts.userId,
+			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
+	.command("add [text]")
+	.description("Add a memory from text, messages, file, or stdin.")
+	.option("-u, --user-id <id>", "Scope to user.")
+	.option("--agent-id <id>", "Scope to agent.")
+	.option("--app-id <id>", "Scope to app.")
+	.option("--run-id <id>", "Scope to run.")
+	.option("--messages <json>", "Conversation messages as JSON.")
+	.option("-f, --file <path>", "Read messages from JSON file.")
+	.option("-m, --metadata <json>", "Custom metadata as JSON.")
+	.option("--immutable", "Prevent future updates.", false)
+	.option("--no-infer", "Skip inference, store raw.")
+	.option("--expires <date>", "Expiration date (YYYY-MM-DD).")
+	.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.")
+	.addHelpText(
+		"after",
+		'\nExamples:\n  $ mem0 add "I prefer dark mode" --user-id alice\n  $ echo "text" | mem0 add -u alice\n  $ mem0 add --file msgs.json -u alice -o json',
+	)
+	.action(async (text, opts) => {
+		const { cmdAdd } = await import("./commands/memory.js");
+		const isAgent = checkAgentMode();
+		const { backend, config } = await getBackendAndConfig(
+			opts.apiKey,
+			opts.baseUrl,
+		);
+		const ids = resolveIds(config, opts);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdAdd(backend, text, { ...ids, ...opts, output });
+	});
+
+// ── Memory: search ────────────────────────────────────────────────────────
+
+program
+	.command("search [query]")
+	.description(
+		"Query your memory store — semantic, keyword, or hybrid retrieval.",
+	)
+	.option("-u, --user-id <id>", "Filter by user.")
+	.option("--agent-id <id>", "Filter by agent.")
+	.option("--app-id <id>", "Filter by app.")
+	.option("--run-id <id>", "Filter by run.")
+	.option(
+		"-k, --top-k <n>",
+		"Number of results.",
+		(v) => Number.parseInt(v),
+		10,
+	)
+	.option(
+		"--threshold <n>",
+		"Minimum similarity score.",
+		(v) => Number.parseFloat(v),
+		0.3,
+	)
+	.option("--rerank", "Enable reranking (Platform only).", false)
+	.option("--keyword", "Use keyword search.", false)
+	.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("--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\n  $ mem0 search "invoices" -u alice --filter \'{"AND": [{"categories": {"in": ["work"]}}]}\'',
+	)
+	.action(async (query, opts) => {
+		let resolvedQuery = query;
+		if (!resolvedQuery && stdinIsPiped()) {
+			resolvedQuery = fs.readFileSync(0, "utf-8").trim();
+		}
+		if (!resolvedQuery) {
+			printError("No query provided. Pass a query argument or pipe via stdin.");
+			process.exit(1);
+		}
+		const { cmdSearch } = await import("./commands/memory.js");
+		const isAgent = checkAgentMode();
+		const { backend, config } = await getBackendAndConfig(
+			opts.apiKey,
+			opts.baseUrl,
+		);
+		const ids = resolveIds(config, opts);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdSearch(backend, resolvedQuery, {
+			...ids,
+			topK: opts.topK,
+			threshold: opts.threshold,
+			rerank: opts.rerank,
+			keyword: opts.keyword,
+			filterJson: opts.filter,
+			fields: opts.fields,
+			showExpired: opts.showExpired,
+			referenceDate: opts.referenceDate,
+			latestOnly: opts.latestOnly,
+			output,
+		});
+	});
+
+// ── Memory: get ───────────────────────────────────────────────────────────
+
+program
+	.command("get <memoryId>")
+	.description("Get a specific memory by ID.")
+	.option("-o, --output <format>", "Output: text, json.", "text")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 get abc-123-def-456\n  $ mem0 get abc-123-def-456 -o json",
+	)
+	.action(async (memoryId, opts) => {
+		const { cmdGet } = await import("./commands/memory.js");
+		const isAgent = checkAgentMode();
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdGet(backend, memoryId, { output });
+	});
+
+// ── Memory: list ──────────────────────────────────────────────────────────
+
+program
+	.command("list")
+	.description("List memories with optional filters.")
+	.option("-u, --user-id <id>", "Filter by user.")
+	.option("--agent-id <id>", "Filter by agent.")
+	.option("--app-id <id>", "Filter by app.")
+	.option("--run-id <id>", "Filter by run.")
+	.option("--page <n>", "Page number.", (v) => Number.parseInt(v), 1)
+	.option(
+		"--page-size <n>",
+		"Results per page.",
+		(v) => Number.parseInt(v),
+		100,
+	)
+	.option("--category <name>", "Filter by category.")
+	.option("--after <date>", "Created after (YYYY-MM-DD).")
+	.option("--before <date>", "Created before (YYYY-MM-DD).")
+	.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.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 list -u alice\n  $ mem0 list --category prefs --after 2024-01-01 -o json",
+	)
+	.action(async (opts) => {
+		const { cmdList } = await import("./commands/memory.js");
+		const isAgent = checkAgentMode();
+		const { backend, config } = await getBackendAndConfig(
+			opts.apiKey,
+			opts.baseUrl,
+		);
+		const ids = resolveIds(config, opts);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdList(backend, {
+			...ids,
+			page: opts.page,
+			pageSize: opts.pageSize,
+			category: opts.category,
+			after: opts.after,
+			before: opts.before,
+			showExpired: opts.showExpired,
+			latestOnly: opts.latestOnly,
+			output,
+		});
+	});
+
+// ── Memory: update ────────────────────────────────────────────────────────
+
+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.")
+	.addHelpText(
+		"after",
+		`\nExamples:\n  $ mem0 update abc-123 "new text"\n  $ mem0 update abc-123 --metadata '{"key":"val"}'\n  $ echo "new text" | mem0 update abc-123`,
+	)
+	.action(async (memoryId, text, opts) => {
+		let resolvedText = text;
+		if (!resolvedText && stdinIsPiped()) {
+			resolvedText = fs.readFileSync(0, "utf-8").trim();
+		}
+		const { cmdUpdate } = await import("./commands/memory.js");
+		const isAgent = checkAgentMode();
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdUpdate(backend, memoryId, resolvedText, {
+			metadata: opts.metadata,
+			expires: opts.expires,
+			timestamp: opts.timestamp,
+			output,
+		});
+	});
+
+// ── Memory: delete (consolidated) ─────────────────────────────────────────
+
+program
+	.command("delete [memoryId]")
+	.description("Delete a memory, all memories matching a scope, or an entity.")
+	.option("--all", "Delete all memories matching scope filters.", false)
+	.option(
+		"--entity",
+		"Delete the entity itself and all its memories (cascade).",
+		false,
+	)
+	.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.")
+	.option("--run-id <id>", "Scope to run.")
+	.option("-o, --output <format>", "Output: text, json, quiet.", "text")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		[
+			"\nExamples:",
+			"  $ mem0 delete abc-123-def-456              # single memory",
+			"  $ mem0 delete --all -u alice --force        # all memories for user",
+			"  $ mem0 delete --all --project --force       # project-wide wipe",
+			"  $ mem0 delete --entity -u alice --force     # entity + all its memories",
+		].join("\n"),
+	)
+	.action(async (memoryId, opts) => {
+		const isAgent = checkAgentMode();
+		const output = isAgent ? "agent" : opts.output;
+		// ── Mutual-exclusion checks ──
+		if (memoryId && opts.all) {
+			printError("Cannot combine <memoryId> with --all. Use one or the other.");
+			process.exit(1);
+		}
+		if (memoryId && opts.entity) {
+			printError(
+				"Cannot combine <memoryId> with --entity. Use one or the other.",
+			);
+			process.exit(1);
+		}
+		if (opts.all && opts.entity) {
+			printError("Cannot combine --all with --entity. Use one or the other.");
+			process.exit(1);
+		}
+		if (!memoryId && !opts.all && !opts.entity) {
+			printError(
+				"Specify a memory ID, --all, or --entity.\n" +
+					"  mem0 delete <id>              Delete a single memory\n" +
+					"  mem0 delete --all [scope]     Delete all memories matching scope\n" +
+					"  mem0 delete --entity [scope]  Delete an entity and all its memories",
+			);
+			process.exit(1);
+		}
+
+		// ── Dispatch: single memory ──
+		if (memoryId) {
+			const { cmdDelete } = await import("./commands/memory.js");
+			const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
+			await cmdDelete(backend, memoryId, {
+				output,
+				dryRun: opts.dryRun,
+				force: opts.force,
+				deleteLinked: opts.deleteLinked,
+			});
+			return;
+		}
+
+		// ── Dispatch: --all ──
+		if (opts.all) {
+			const { cmdDeleteAll } = await import("./commands/memory.js");
+			const { backend, config } = await getBackendAndConfig(
+				opts.apiKey,
+				opts.baseUrl,
+			);
+			const ids = opts.project
+				? {
+						userId: undefined,
+						agentId: undefined,
+						appId: undefined,
+						runId: undefined,
+					}
+				: resolveIds(config, opts);
+			await cmdDeleteAll(backend, {
+				force: opts.force,
+				dryRun: opts.dryRun,
+				all: opts.project,
+				...ids,
+				output,
+			});
+			return;
+		}
+
+		// ── Dispatch: --entity ──
+		if (opts.entity) {
+			const { cmdEntitiesDelete } = await import("./commands/entities.js");
+			const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
+			await cmdEntitiesDelete(backend, { ...opts, output });
+			return;
+		}
+	});
+
+// ── Config subcommands ────────────────────────────────────────────────────
+
+const configCmd = program
+	.command("config")
+	.description("Manage mem0 configuration.")
+	.addHelpCommand(false);
+
+configCmd
+	.command("show")
+	.description("Display current configuration (secrets redacted).")
+	.option("-o, --output <format>", "Output: text, json.", "text")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 config show\n  $ mem0 config show -o json",
+	)
+	.action(async (opts) => {
+		const { cmdConfigShow } = await import("./commands/config.js");
+		const isAgent = checkAgentMode();
+		const output = isAgent ? "agent" : opts.output;
+		cmdConfigShow({ output });
+	});
+
+configCmd
+	.command("get <key>")
+	.description("Get a configuration value.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 config get platform.api_key\n  $ mem0 config get defaults.user_id",
+	)
+	.action(async (key) => {
+		const { cmdConfigGet } = await import("./commands/config.js");
+		checkAgentMode();
+		cmdConfigGet(key);
+	});
+
+configCmd
+	.command("set <key> <value>")
+	.description("Set a configuration value.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 config set defaults.user_id alice\n  $ mem0 config set platform.base_url https://api.mem0.ai",
+	)
+	.action(async (key, value) => {
+		const { cmdConfigSet } = await import("./commands/config.js");
+		checkAgentMode();
+		cmdConfigSet(key, value);
+	});
+
+// ── Entity subcommand group ───────────────────────────────────────────────
+
+const entityCmd = program
+	.command("entity")
+	.description("Manage entities.")
+	.addHelpCommand(false)
+	.configureHelp({ formatHelp: richFormatHelp });
+
+entityCmd
+	.command("list <entityType>")
+	.description("List all entities of a given type.")
+	.option("-o, --output <format>", "Output: table, json.", "table")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 entity list users\n  $ mem0 entity list agents -o json",
+	)
+	.action(async (entityType, opts) => {
+		const { cmdEntitiesList } = await import("./commands/entities.js");
+		const isAgent = checkAgentMode();
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdEntitiesList(backend, entityType, { output });
+	});
+
+entityCmd
+	.command("delete")
+	.description("Delete an entity and ALL its memories (cascade).")
+	.option("--dry-run", "Show what would be deleted without deleting.", false)
+	.option("-u, --user-id <id>", "Scope to user.")
+	.option("--agent-id <id>", "Scope to agent.")
+	.option("--app-id <id>", "Scope to app.")
+	.option("--run-id <id>", "Scope to run.")
+	.option("--force", "Skip confirmation.", false)
+	.option("-o, --output <format>", "Output: text, json, quiet.", "text")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 entity delete --user-id alice --force\n  $ mem0 entity delete --user-id alice --dry-run",
+	)
+	.action(async (opts) => {
+		const { cmdEntitiesDelete } = await import("./commands/entities.js");
+		const isAgent = checkAgentMode();
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdEntitiesDelete(backend, { ...opts, output });
+	});
+
+// ── Event subcommands ─────────────────────────────────────────────────────
+
+const eventCmd = program
+	.command("event")
+	.description("Inspect background processing events.")
+	.addHelpCommand(false)
+	.configureHelp({ formatHelp: richFormatHelp });
+
+eventCmd
+	.command("list")
+	.description("List recent background processing events.")
+	.option("-o, --output <format>", "Output: table, json.", "table")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 event list\n  $ mem0 event list -o json",
+	)
+	.action(async (opts) => {
+		const { cmdEventList } = await import("./commands/events.js");
+		const isAgent = checkAgentMode();
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdEventList(backend, { output });
+	});
+
+eventCmd
+	.command("status <eventId>")
+	.description("Check the status of a specific background event.")
+	.option("-o, --output <format>", "Output: text, json.", "text")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 event status <event-id>\n  $ mem0 event status <event-id> -o json",
+	)
+	.action(async (eventId, opts) => {
+		const { cmdEventStatus } = await import("./commands/events.js");
+		const isAgent = checkAgentMode();
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdEventStatus(backend, eventId, { output });
+	});
+
+// ── Utility commands ──────────────────────────────────────────────────────
+
+program
+	.command("status")
+	.description("Check connectivity and authentication.")
+	.option("-o, --output <format>", "Output: text, json.", "text")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText("after", "\nExamples:\n  $ mem0 status\n  $ mem0 status -o json")
+	.action(async (opts) => {
+		const { cmdStatus } = await import("./commands/utils.js");
+		const isAgent = checkAgentMode();
+		const { backend, config } = await getBackendAndConfig(
+			opts.apiKey,
+			opts.baseUrl,
+		);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdStatus(backend, {
+			userId: config.defaults.userId || undefined,
+			agentId: config.defaults.agentId || undefined,
+			output,
+		});
+	});
+
+program
+	.command("version")
+	.description("Show version and exit.")
+	.action(() => {
+		printVersion();
+	});
+
+program
+	.command("import <filePath>")
+	.description("Import memories from a JSON file.")
+	.option("-u, --user-id <id>", "Override user ID.")
+	.option("--agent-id <id>", "Override agent ID.")
+	.option("-o, --output <format>", "Output: text, json.", "text")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 import data.json --user-id alice\n  $ mem0 import data.json -u alice -o json",
+	)
+	.action(async (filePath, opts) => {
+		const { cmdImport } = await import("./commands/utils.js");
+		const isAgent = checkAgentMode();
+		const { backend, config } = await getBackendAndConfig(
+			opts.apiKey,
+			opts.baseUrl,
+		);
+		const ids = resolveIds(config, opts);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdImport(backend, filePath, {
+			userId: ids.userId,
+			agentId: ids.agentId,
+			output,
+		});
+	});
+
+// ── Help (machine-readable) ──────────────────────────────────────────────
+
+program
+	.command("help")
+	.description(
+		"Show help. Use --json for machine-readable output (for LLM agents).",
+	)
+	.option("--json", "Output machine-readable JSON for LLM agents.", false)
+	.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/.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");
+			if (fs.existsSync(specPath)) {
+				const spec = JSON.parse(fs.readFileSync(specPath, "utf-8"));
+				console.log(JSON.stringify(spec, null, 2));
+			} else {
+				console.log(
+					JSON.stringify(
+						{
+							name: "mem0",
+							version: CLI_VERSION,
+							description: "The Memory Layer for AI Agents",
+						},
+						null,
+						2,
+					),
+				);
+			}
+		} else {
+			const { brand: b } = colors;
+			console.log(
+				`${b("◆ Mem0 CLI")} v${CLI_VERSION} · Node.js SDK\n  The Memory Layer for AI Agents\n`,
+			);
+			console.log("Usage: mem0 <command> [OPTIONS]\n");
+			console.log("Commands:");
+			console.log(
+				"  add              Add a memory from text, messages, file, or stdin",
+			);
+			console.log(
+				"  search           Query your memory store (semantic, keyword, hybrid)",
+			);
+			console.log("  get              Get a specific memory by ID");
+			console.log("  list             List memories with optional filters");
+			console.log("  update           Update a memory's text or metadata");
+			console.log(
+				"  delete           Delete a memory, all memories, or an entity",
+			);
+			console.log("  import           Import memories from a JSON file");
+			console.log("  config           Manage configuration (show, get, set)");
+			console.log("  entity           Manage entities (list, delete)");
+			console.log(
+				"  event            Inspect background events (list, status)",
+			);
+			console.log("  init             Interactive setup wizard");
+			console.log("  status           Check connectivity and authentication");
+			console.log();
+			console.log("  mem0 <command> --help    Get help for a command");
+			console.log(
+				"  mem0 help --json         Machine-readable help (for LLM agents)",
+			);
+			console.log();
+		}
+	});
+
+// ── Entrypoint ────────────────────────────────────────────────────────────
+
+// 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

@@ -0,0 +1,411 @@
+/**
+ * Output formatting for mem0 CLI — text, JSON, table, quiet modes.
+ */
+
+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;
+
+function formatDate(dtStr?: string): string | undefined {
+	if (!dtStr) return undefined;
+	try {
+		const dt = new Date(dtStr.replace("Z", "+00:00"));
+		return dt.toISOString().slice(0, 10);
+	} catch {
+		return dtStr?.slice(0, 10);
+	}
+}
+
+export function formatMemoriesText(
+	memories: Record<string, unknown>[],
+	title = "memories",
+): void {
+	const count = memories.length;
+	console.log(`\n${brand(`Found ${count} ${title}:`)}\n`);
+
+	for (let i = 0; i < memories.length; i++) {
+		const mem = memories[i];
+		const memoryText = (mem.memory ?? mem.text ?? "") as string;
+		const memId = ((mem.id as string) ?? "").slice(0, 8);
+		const score = mem.score as number | undefined;
+		const created = formatDate(mem.created_at as string | undefined);
+		let category: string | undefined;
+		const cats = mem.categories;
+		if (Array.isArray(cats)) {
+			category = cats[0] as string | undefined;
+		}
+
+		console.log(`  ${i + 1}. ${memoryText}`);
+
+		const details: string[] = [];
+		if (score !== undefined) details.push(`Score: ${score.toFixed(2)}`);
+		if (memId) details.push(`ID: ${memId}`);
+		if (created) details.push(`Created: ${created}`);
+		if (category) details.push(`Category: ${category}`);
+
+		if (details.length > 0) {
+			console.log(`     ${dim(details.join(" · "))}`);
+		}
+		console.log();
+	}
+}
+
+export function formatMemoriesTable(
+	memories: Record<string, unknown>[],
+	opts: { showScore?: boolean } = {},
+): void {
+	const head = opts.showScore
+		? [
+				accent("ID"),
+				accent("Score"),
+				accent("Memory"),
+				accent("Category"),
+				accent("Created"),
+			]
+		: [accent("ID"), accent("Memory"), accent("Category"), accent("Created")];
+	const colWidths = opts.showScore ? [38, 8, 40, 16, 14] : [38, 40, 16, 14];
+	const table = new Table({
+		head,
+		colWidths,
+		wordWrap: true,
+		style: { head: [], border: [] },
+	});
+
+	for (const mem of memories) {
+		const memId = (mem.id as string) ?? "";
+		let memoryText = (mem.memory ?? mem.text ?? "") as string;
+		if (memoryText.length > 60) {
+			memoryText = `${memoryText.slice(0, 57)}...`;
+		}
+		const categories = mem.categories;
+		const cat =
+			Array.isArray(categories) && categories.length > 0
+				? categories.length > 1
+					? `${categories[0]} (+${categories.length - 1})`
+					: (categories[0] as string)
+				: "—";
+		const created = formatDate(mem.created_at as string | undefined) ?? "—";
+		if (opts.showScore) {
+			const score = mem.score as number | undefined;
+			const scoreStr = score !== undefined ? score.toFixed(2) : "—";
+			table.push([dim(memId), scoreStr, memoryText, cat, created]);
+		} else {
+			table.push([dim(memId), memoryText, cat, created]);
+		}
+	}
+
+	console.log();
+	console.log(table.toString());
+	console.log();
+}
+
+export function formatJson(data: unknown): void {
+	console.log(JSON.stringify(data, null, 2));
+}
+
+export function formatSingleMemory(
+	mem: Record<string, unknown>,
+	output = "text",
+): void {
+	if (output === "json") {
+		formatJson(mem);
+		return;
+	}
+
+	const memoryText = (mem.memory ?? mem.text ?? "") as string;
+	const memId = (mem.id ?? "") as string;
+
+	const lines: string[] = [];
+	lines.push(`  ${memoryText}`);
+	lines.push("");
+
+	if (memId) lines.push(`  ${dim("ID:")}         ${memId}`);
+	const created = formatDate(mem.created_at as string | undefined);
+	if (created) lines.push(`  ${dim("Created:")}    ${created}`);
+	const updated = formatDate(mem.updated_at as string | undefined);
+	if (updated) lines.push(`  ${dim("Updated:")}    ${updated}`);
+	const meta = mem.metadata;
+	if (meta) lines.push(`  ${dim("Metadata:")}   ${JSON.stringify(meta)}`);
+	const categories = mem.categories;
+	if (categories) {
+		const catStr = Array.isArray(categories)
+			? categories.join(", ")
+			: String(categories);
+		lines.push(`  ${dim("Categories:")} ${catStr}`);
+	}
+
+	const content = lines.join("\n");
+	console.log();
+	console.log(
+		boxen(content, {
+			title: brand("Memory"),
+			titleAlignment: "left",
+			borderColor: "magenta",
+			padding: 1,
+		}),
+	);
+	console.log();
+}
+
+export function formatAddResult(
+	result: Record<string, unknown> | Record<string, unknown>[],
+	output = "text",
+): void {
+	if (output === "json") {
+		formatJson(result);
+		return;
+	}
+	if (output === "quiet") return;
+
+	const results: Record<string, unknown>[] = Array.isArray(result)
+		? result
+		: ((result.results as Record<string, unknown>[]) ?? [result]);
+
+	if (!results.length) {
+		console.log(`  ${dim("No memories extracted.")}`);
+		return;
+	}
+
+	console.log();
+	const seenPendingEvents = new Set<string>();
+	for (const r of results) {
+		// Detect async PENDING response
+		if (r.status === "PENDING") {
+			const eventId = (r.event_id as string) ?? "";
+			// Deduplicate PENDING entries with the same event_id
+			if (eventId && seenPendingEvents.has(eventId)) continue;
+			if (eventId) seenPendingEvents.add(eventId);
+			const icon = accent(sym("⧗", "..."));
+			const parts = [
+				`  ${icon} ${dim("Queued".padEnd(10))}`,
+				"Processing in background",
+			];
+			console.log(parts.join("  "));
+			if (eventId) {
+				console.log(`  ${dim(`  event_id: ${eventId}`)}`);
+				console.log(
+					`  ${dim(`  → Check status: mem0 event status ${eventId}`)}`,
+				);
+			}
+			continue;
+		}
+
+		const event = (r.event ?? "ADD") as string;
+		const memory = (r.memory ?? r.text ?? r.content ?? r.data ?? "") as string;
+		const memId = ((r.id as string) ?? (r.memory_id as string) ?? "").slice(
+			0,
+			8,
+		);
+
+		let icon: string;
+		let label: string;
+		if (event === "ADD") {
+			icon = success("+");
+			label = "Added";
+		} else if (event === "UPDATE") {
+			icon = accent("~");
+			label = "Updated";
+		} else if (event === "DELETE") {
+			icon = errorColor("-");
+			label = "Deleted";
+		} else if (event === "NOOP") {
+			icon = dim("·");
+			label = "No change";
+		} else {
+			icon = dim("?");
+			label = event;
+		}
+
+		const parts = [`  ${icon} ${dim(label.padEnd(10))}`];
+		if (memory) parts.push(memory);
+		if (memId) parts.push(dim(`(${memId})`));
+		console.log(parts.join("  "));
+	}
+	console.log();
+}
+
+export function formatJsonEnvelope(opts: {
+	command: string;
+	data: unknown;
+	durationMs?: number;
+	scope?: Record<string, string | undefined>;
+	count?: number;
+	status?: string;
+	error?: string;
+}): void {
+	const envelope: Record<string, unknown> = {
+		status: opts.status ?? "success",
+		command: opts.command,
+	};
+	if (opts.durationMs !== undefined) envelope.duration_ms = opts.durationMs;
+	if (opts.scope !== undefined) envelope.scope = opts.scope;
+	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));
+}
+
+function pick(
+	obj: Record<string, unknown>,
+	keys: string[],
+): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+	for (const key of keys) {
+		if (key in obj) result[key] = obj[key];
+	}
+	return result;
+}
+
+export function sanitizeAgentData(command: string, data: unknown): unknown {
+	if (data === null || data === undefined) return data;
+
+	switch (command) {
+		case "add": {
+			const items = Array.isArray(data) ? data : [data];
+			return items.map((item) => {
+				const r = item as Record<string, unknown>;
+				if (r.status === "PENDING") return pick(r, ["status", "event_id"]);
+				return pick(r, ["id", "memory", "event"]);
+			});
+		}
+		case "search":
+			return (data as Record<string, unknown>[]).map((r) =>
+				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",
+					"expiration_date",
+				]),
+			);
+		case "get": {
+			const r = data as Record<string, unknown>;
+			return pick(r, [
+				"id",
+				"memory",
+				"created_at",
+				"updated_at",
+				"categories",
+				"metadata",
+				"expiration_date",
+			]);
+		}
+		case "update": {
+			const r = data as Record<string, unknown>;
+			return pick(r, ["id", "memory", "expiration_date"]);
+		}
+		case "delete":
+		case "delete-all":
+		case "entity delete":
+			return data;
+		case "entity list":
+			return (data as Record<string, unknown>[]).map((r) => ({
+				name: (r.name ?? r.id) as string,
+				...pick(r, ["type", "count"]),
+			}));
+		case "event list":
+			return (data as Record<string, unknown>[]).map((r) =>
+				pick(r, ["id", "event_type", "status", "latency", "created_at"]),
+			);
+		case "event status": {
+			const ev = data as Record<string, unknown>;
+			const rawResults =
+				(ev.results as Record<string, unknown>[] | undefined) ?? [];
+			const sanitizedResults = rawResults.map((r) => {
+				const nested = r.data as Record<string, unknown> | undefined;
+				return {
+					id: r.id,
+					event: r.event,
+					user_id: r.user_id,
+					memory: nested?.memory ?? null,
+				};
+			});
+			return {
+				...pick(ev, [
+					"id",
+					"event_type",
+					"status",
+					"latency",
+					"created_at",
+					"updated_at",
+				]),
+				results: sanitizedResults,
+			};
+		}
+		default:
+			return data;
+	}
+}
+
+export function formatAgentEnvelope(opts: {
+	command: string;
+	data: unknown;
+	durationMs?: number;
+	scope?: Record<string, string | undefined>;
+	count?: number;
+}): void {
+	const envelope: Record<string, unknown> = {
+		status: "success",
+		command: opts.command,
+	};
+	if (opts.durationMs !== undefined) envelope.duration_ms = opts.durationMs;
+	if (opts.scope) {
+		const filtered = Object.fromEntries(
+			Object.entries(opts.scope).filter(([, v]) => v),
+		);
+		if (Object.keys(filtered).length > 0) envelope.scope = filtered;
+	}
+	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));
+}
+
+export function printResultSummary(opts: {
+	count: number;
+	durationSecs?: number;
+	page?: number;
+	scopeIds?: Record<string, string | undefined>;
+}): void {
+	const parts = [`${opts.count} result${opts.count !== 1 ? "s" : ""}`];
+	if (opts.page !== undefined) parts.push(`page ${opts.page}`);
+	if (opts.scopeIds) {
+		const scopeParts = Object.entries(opts.scopeIds)
+			.filter(([, v]) => v)
+			.map(([k, v]) => `${k}=${v}`);
+		if (scopeParts.length > 0) parts.push(scopeParts.join(", "));
+	}
+	if (opts.durationSecs !== undefined)
+		parts.push(`${opts.durationSecs.toFixed(2)}s`);
+
+	console.log(`  ${dim(parts.join(" · "))}`);
+	console.log();
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Agent mode state — set by the root program option handler,
+ * read by commands and branding functions.
+ */
+
+import fs from "node:fs";
+
+let _agentMode = false;
+let _currentCommand = "";
+let _pendingNotice = "";
+
+export function isAgentMode(): boolean {
+	return _agentMode;
+}
+
+export function setAgentMode(val: boolean): void {
+	_agentMode = val;
+}
+
+export function getCurrentCommand(): string {
+	return _currentCommand;
+}
+
+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

@@ -0,0 +1,157 @@
+/**
+ * CLI telemetry — anonymous usage tracking via PostHog.
+ *
+ * Sends fire-and-forget events by spawning a detached child process
+ * (telemetry-sender.cjs). The parent CLI process exits immediately;
+ * the child handles email resolution, caching, and the HTTP POST.
+ *
+ * Disable with: MEM0_TELEMETRY=false
+ */
+
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_FILE, loadConfig, saveConfig } from "./config.js";
+import { CLI_VERSION } from "./version.js";
+
+const POSTHOG_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX";
+const POSTHOG_HOST = "https://us.i.posthog.com/i/v0/e/";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SENDER_SCRIPT = path.join(__dirname, "..", "telemetry-sender.cjs");
+
+function isTelemetryEnabled(): boolean {
+	try {
+		return process.env.MEM0_TELEMETRY !== "false";
+	} catch {
+		return true;
+	}
+}
+
+/**
+ * Return a persistent per-machine anonymous ID, generating one if needed.
+ *
+ * Stored in ~/.mem0/config.json under `telemetry.anonymous_id` so that
+ * repeat runs on the same machine share one PostHog identity instead of
+ * collapsing into a single shared fallback string.
+ */
+function getOrCreateAnonymousId(): string {
+	const config = loadConfig();
+	if (config.telemetry.anonymousId) {
+		return config.telemetry.anonymousId;
+	}
+
+	const newId = `cli-anon-${randomUUID().replace(/-/g, "")}`;
+	config.telemetry.anonymousId = newId;
+	try {
+		saveConfig(config);
+	} catch {
+		/* ignore persistence failure — still return the generated ID */
+	}
+	return newId;
+}
+
+/**
+ * Return a stable anonymous identifier for the current user.
+ *
+ * Priority: cached user_email (from /v1/ping/) > MD5(api_key) >
+ * persistent per-machine anonymous ID.
+ */
+function getDistinctId(): string {
+	try {
+		const config = loadConfig();
+		if (config.platform.userEmail) {
+			return config.platform.userEmail;
+		}
+		if (config.platform.apiKey) {
+			return createHash("md5").update(config.platform.apiKey).digest("hex");
+		}
+	} catch {
+		/* ignore */
+	}
+	try {
+		return getOrCreateAnonymousId();
+	} catch {
+		return `cli-anon-${randomUUID().replace(/-/g, "")}`;
+	}
+}
+
+/**
+ * Fire a PostHog event (non-blocking, returns void, never throws).
+ * Spawns telemetry-sender.cjs as a detached subprocess.
+ *
+ * When `preResolvedEmail` is provided (e.g. from an upfront ping
+ * validation), it is used directly as the PostHog distinct ID and the
+ * subprocess skips its own `/v1/ping/` call.
+ */
+export function captureEvent(
+	eventName: string,
+	properties: Record<string, unknown> = {},
+	preResolvedEmail?: string,
+): void {
+	if (!isTelemetryEnabled()) return;
+
+	try {
+		const config = loadConfig();
+		const distinctId = preResolvedEmail || getDistinctId();
+
+		// Detect anonymous → identified transition. If a stored anonymous_id
+		// exists and we just resolved to a real identity, fire a one-shot
+		// $identify event so PostHog stitches the pre-signup history onto
+		// the authenticated profile. Clear the stored id so we don't re-alias.
+		let anonIdToAlias: string | null = null;
+		if (
+			distinctId &&
+			!distinctId.startsWith("cli-anon-") &&
+			config.telemetry.anonymousId
+		) {
+			anonIdToAlias = config.telemetry.anonymousId;
+			config.telemetry.anonymousId = "";
+			try {
+				saveConfig(config);
+			} catch {
+				/* ignore — alias may double-fire next run, harmless */
+			}
+		}
+
+		// 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,
+			event: eventName,
+			properties: {
+				source: "CLI",
+				language: "node",
+				cli_version: CLI_VERSION,
+				agent_mode: Boolean(config.platform.agentMode),
+				node_version: process.version,
+				os: process.platform,
+				...properties,
+				$process_person_profile: false,
+				$lib: "posthog-node",
+			},
+		};
+
+		const context = {
+			payload,
+			posthogHost: POSTHOG_HOST,
+			needsEmail: !distinctId || !distinctId.includes("@"),
+			mem0ApiKey: config.platform.apiKey || "",
+			mem0BaseUrl: config.platform.baseUrl || "https://api.mem0.ai",
+			configPath: CONFIG_FILE,
+			anonDistinctIdToAlias: anonIdToAlias,
+		};
+
+		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/src/version.ts

@@ -0,0 +1,10 @@
+import { createRequire } from "node:module";
+
+// __CLI_VERSION__ is replaced at build time by tsup (see tsup.config.ts).
+// When running via tsx in dev/test mode, fall back to reading package.json.
+// typeof is safe to use on undeclared identifiers — it returns 'undefined' without throwing.
+export const CLI_VERSION: string =
+	typeof __CLI_VERSION__ !== "undefined"
+		? (__CLI_VERSION__ as string)
+		: (createRequire(import.meta.url)("../package.json") as { version: string })
+				.version;

cli/node/telemetry-sender.cjs

@@ -0,0 +1,155 @@
+/**
+ * Standalone telemetry sender — runs as a detached child process.
+ *
+ * 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:
+ *
+ * 1. Resolves the user's email via /v1/ping/ if not already cached
+ * 2. Caches the email in ~/.mem0/config.json for future runs
+ * 3. Sends the PostHog event
+ *
+ * All errors are silently swallowed — this process must never produce output
+ * or affect the user experience.
+ */
+
+"use strict";
+
+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);
+		const opts = {
+			hostname: u.hostname,
+			path: u.pathname + u.search,
+			method,
+			headers,
+			timeout: 10000,
+		};
+		const req = https.request(opts, (res) => {
+			let data = "";
+			res.on("data", (chunk) => (data += chunk));
+			res.on("end", () => {
+				try {
+					resolve(JSON.parse(data));
+				} catch {
+					resolve({});
+				}
+			});
+		});
+		req.on("error", reject);
+		req.on("timeout", () => {
+			req.destroy();
+			reject(new Error("timeout"));
+		});
+		if (body) {
+			req.end(body);
+		} else {
+			req.end();
+		}
+	});
+}
+
+async function resolveAndCacheEmail(ctx, payload) {
+	try {
+		const pingUrl = ctx.mem0BaseUrl.replace(/\/+$/, "") + "/v1/ping/";
+		const data = await httpsRequest(pingUrl, "GET", {
+			Authorization: "Token " + ctx.mem0ApiKey,
+			"Content-Type": "application/json",
+		});
+		if (data.user_email) {
+			payload.distinct_id = data.user_email;
+			cacheEmail(ctx.configPath, data.user_email);
+		}
+	} catch {
+		// silently swallow
+	}
+}
+
+function cacheEmail(configPath, email) {
+	if (!configPath) return;
+	try {
+		const raw = fs.readFileSync(configPath, "utf-8");
+		const cfg = JSON.parse(raw);
+		if (!cfg.platform) cfg.platform = {};
+		cfg.platform.user_email = email;
+		fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2));
+	} catch {
+		// silently swallow
+	}
+}
+
+async function sendPosthogEvent(posthogHost, payload) {
+	try {
+		const body = JSON.stringify(payload);
+		await httpsRequest(posthogHost, "POST", {
+			"Content-Type": "application/json",
+			"Content-Length": Buffer.byteLength(body),
+		}, body);
+	} catch {
+		// silently swallow
+	}
+}
+
+async function sendIdentifyEvent(ctx, payload, anonId) {
+	const identifyPayload = {
+		api_key: payload.api_key,
+		event: "$identify",
+		distinct_id: payload.distinct_id,
+		properties: {
+			$anon_distinct_id: anonId,
+			$lib: (payload.properties && payload.properties.$lib) || "posthog-node",
+		},
+	};
+	await sendPosthogEvent(ctx.posthogHost, identifyPayload);
+}
+
+async function main() {
+	const ctx = await loadContext();
+	const payload = ctx.payload;
+
+	if (ctx.needsEmail && ctx.mem0ApiKey) {
+		await resolveAndCacheEmail(ctx, payload);
+	}
+
+	// Fire $identify *after* email resolution so PostHog links the stored
+	// anonymous id directly to the final identity (email, not the api-key
+	// hash). The regular event is sent next so it lands under the merged
+	// profile.
+	if (ctx.anonDistinctIdToAlias) {
+		await sendIdentifyEvent(ctx, payload, ctx.anonDistinctIdToAlias);
+	}
+
+	await sendPosthogEvent(ctx.posthogHost, payload);
+}
+
+main().catch(() => {});