docs(readme): update benchmark numbers and add temporal reasoning

- LongMemEval: 93.4 → 94.8 (top_50 with temporal reasoning)
- Research Highlights: update LongMemEval from +26 to +27 pts
- Add Temporal Reasoning to "What Changed" feature list

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "mem0",
       "source": "./mem0-plugin",
       "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search to Claude workflows.",
-      "version": "0.1.0"
+      "version": "0.1.2"
     }
   ]
 }

.cursor-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "mem0",
       "source": "./mem0-plugin",
       "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search.",
-      "version": "0.1.0"
+      "version": "0.1.1"
     }
   ]
 }

AGENTS.md

@@ -27,7 +27,7 @@ This is a **polyglot monorepo** containing Python and TypeScript packages, CLIs,
 | `server/` | FastAPI REST server for self-hosted Mem0 (Docker: FastAPI + PostgreSQL/pgvector + Neo4j) |
 | `openmemory/` | Self-hosted memory platform — `api/` (FastAPI + Alembic + MCP server) and `ui/` (Next.js 15 + React 19) |
 | `mem0-plugin/` | AI editor plugins (Claude Code, Cursor, Codex) — MCP server connection, lifecycle hooks, skills |
-| `skills/` | Claude Code skill definitions — `mem0/`, `mem0-cli/`, `mem0-vercel-ai-sdk/` |
+| `skills/` | Claude Code skill definitions. Reference skills (SDK knowledge, always-on): `mem0/`, `mem0-cli/`, `mem0-vercel-ai-sdk/`. Pipeline skills (run on demand): `mem0-integrate/`, `mem0-test-integration/` |
 | `docs/` | Documentation site (Mintlify) |
 | `tests/` | Python SDK tests (pytest) |
 | `evaluation/` | Benchmarking framework — LOCOMO evals, experiment runner, score generation |
@@ -387,7 +387,9 @@ Model Context Protocol support in multiple places:
 ### Plugin & Skills System
 
 - `mem0-plugin/` provides integrations for Claude Code, Cursor, and Codex via MCP server connections and lifecycle hooks for automatic memory capture.
-- `skills/` contains structured skill definitions for AI agents, covering SDK usage, CLI workflows, and Vercel AI SDK patterns.
+- `skills/` contains structured skill definitions for AI agents, split into two categories:
+  - **Reference skills** (always-on SDK knowledge): `mem0` (Python + TS SDKs, framework integrations), `mem0-cli` (terminal workflows), `mem0-vercel-ai-sdk` (Vercel AI provider).
+  - **Pipeline skills** (run on demand): `mem0-integrate` wires Mem0 into an existing repo via a TDD pipeline; `mem0-test-integration` verifies what the integrator produced on the same branch. The two are loosely coupled via `.mem0-integration/` artifacts.
 
 ### Adding a New Provider
 

README.md

@@ -47,7 +47,7 @@
 | Benchmark | Old | New  | Tokens  | Latency p50  |
 | --- | --- | --- | --- | --- |
 | **LoCoMo** | 71.4 | **91.6** | 7.0K  | 0.88s  |
-| **LongMemEval** | 67.8 | **93.4** | 6.8K  | 1.09s  |
+| **LongMemEval** | 67.8 | **94.8** | 6.8K  | 1.09s  |
 | **BEAM (1M)** | — | **64.1** | 6.7K  | 1.00s  |
 | **BEAM (10M)** | — | **48.6** | 6.9K  | 1.05s  |
 
@@ -58,12 +58,13 @@ All benchmarks run on the same production-representative model stack. Single-pas
 - **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
 - **91.6 on LoCoMo** -- +20 points over the previous algorithm
-- **93.4 on LongMemEval** -- +26 points, with +53.6 on assistant memory recall
+- **94.8 on LongMemEval** -- +27 points, with +53.6 on assistant memory recall
 - **64.1 on BEAM (1M)** -- production-scale memory evaluation at 1M tokens
 - [Read the full paper](https://mem0.ai/research)
 
@@ -147,6 +148,27 @@ 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
+```
+
+Use `/mem0-integrate` to wire Mem0 into an existing repo via a test-first pipeline, then `/mem0-test-integration` to verify. 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-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).

docs/api-reference/events/get-event.mdx

@@ -5,3 +5,5 @@ openapi: get /v1/event/{event_id}/
 ---
 
 Retrieve details about a specific event by passing its `event_id`. This endpoint is particularly helpful for tracking the status, payload, and completion details of asynchronous memory operations.
+
+For `POST /v3/memories/add/`, the event confirms that the write pipeline completed. Temporal reasoning enrichment runs asynchronously by default, so the event may be `SUCCEEDED` slightly before temporal ranking signals are available to subsequent `search` calls.

docs/api-reference/memory/add-memories.mdx

@@ -83,4 +83,3 @@ The request is queued for background processing. The response contains an `event
 <Info>
 Poll the event status via `GET /v1/event/{event_id}/`. Status will be `SUCCEEDED` or `FAILED` once processing completes.
 </Info>
-

docs/api-reference/memory/get-memories.mdx

@@ -64,4 +64,3 @@ memories = client.get_all(
 <Info>
 The response is a paginated envelope with `count`, `next`, `previous`, and `results`. Use `page` and `page_size` query params to step through results.
 </Info>
-

docs/api-reference/memory/search-memories.mdx

@@ -49,6 +49,7 @@ related_memories = client.search(
     {
       "id": "ea925981-272f-40dd-b576-be64e4871429",
       "memory": "Likes to play cricket and plays cricket on weekends.",
+      "user_id": "alice",
       "metadata": {
         "category": "hobbies"
       },

docs/api-reference/organizations-projects.mdx

@@ -109,6 +109,19 @@ client.project.update(
 )
 ```
 
+#### Toggle Memory Decay
+
+`decay` is a per-project boolean that turns on [Memory Decay](/platform/features/memory-decay) — a search-time ranking bias that reinforces recently-accessed memories and gently dampens stale ones. The flag is `false` by default; set it via the same project-update endpoint:
+
+```bash cURL
+curl -X PATCH https://api.mem0.ai/api/v1/orgs/organizations/$ORG_ID/projects/$PROJECT_ID/ \
+  -H "Authorization: Token $MEM0_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"decay": true}'
+```
+
+The current state is returned on every project read (and supports `?fields=decay` for a minimal response). Toggling has no effect on stored memories, only on how v3 search ranks them.
+
 ### Delete Project
 
 <Warning>

docs/changelog/highlights.mdx

@@ -4,6 +4,34 @@ description: "Major product launches, headline features, and milestones for Mem0
 mode: "wide"
 ---
 
+<Update label="2026-05-13" description="Temporal Reasoning for Mem0 Platform v3">
+
+**Temporal Reasoning — Time-Aware Retrieval for Platform v3**
+
+Mem0 Platform v3 can now interpret time-aware memories and queries so assistants retrieve the right information for questions about the past, upcoming plans, and current state.
+
+- **Time-aware search intent** — Queries like `last week`, `upcoming`, `right now`, and `as of March 2025` return contextually appropriate results automatically
+- **Enabled by default** — No per-request toggle required for v3 writes or searches
+- **Anchored relative queries** — `reference_date` anchors relative search phrases for tests, backfills, and reproducible demos
+- **Normal response shape** — Temporal reasoning affects ranking while preserving existing client response patterns
+
+See [Temporal Reasoning](/platform/features/temporal-reasoning) for usage details.
+
+</Update>
+
+<Update label="2026-05-08" description="Memory Decay">
+
+**Memory Decay — Recently-Used Memories Surface Higher, Automatically**
+
+Per-project search-time ranking bias that boosts recently-touched memories and gently dampens stale ones. Off by default; opt in per project via the `decay` field on the project endpoint, or via `client.project.update(decay=True)` in the SDKs (Python `v2.0.2` / TypeScript `v3.0.3`).
+
+- **Soft bias, never a filter.** The scaling factor stays in `0.3×–1.5×`. Decay can reorder candidates but never zeros them out — anything that surfaced before decay can still surface after.
+- **Reinforcement loop.** Every memory returned in a search has its access history updated, so frequently-used facts naturally float to the top over time.
+- **Public score still clamped to `[0, 1]`.** Existing API contract preserved; no client-side changes needed.
+- **v3 search only**, fully reversible. See [Memory Decay docs](/platform/features/memory-decay).
+
+</Update>
+
 <Update label="2026-04-14" description="Mem0 SDK v2.0.0 / v3.0.0">
 
 **New Memory Algorithm — State-of-the-Art Accuracy at ~3-4x Lower Cost**
@@ -99,4 +127,4 @@ Major expansion of the provider ecosystem:
 
 First skill launch — a dedicated Mem0 skill providing platform API reference, quickstart patterns, and integration examples directly inside agent sessions. Available on [skills.sh](https://skills.sh) for any compatible AI coding agent.
 
-</Update>
+</Update>

docs/changelog/openclaw.mdx

@@ -4,6 +4,36 @@ description: "Release notes for the OpenClaw plugin and agent harness."
 mode: "wide"
 ---
 
+<Update label="2026-04-29" description="v1.0.11">
+
+**New Features:**
+- **Skills-mode auto-setup:** `enableSkillsConfig()` now runs automatically after onboarding — enables triage, recall (with reranking + keyword search), and dream consolidation with `tools.profile = "full"` and disables the built-in session-memory hook to avoid conflicts
+- **Memory runtime capability:** Plugin now exposes `runtime.getMemorySearchManager()` and `resolveMemoryBackendConfig()` on the registered memory capability, enabling OpenClaw gateway to query memory status and backend config directly
+- **Dimension-aware collections:** OSS wizard detects embedder dimension changes and creates a new collection (`mem0_<dims>d`) automatically, with a warning about old memories being inaccessible under the new embedder
+- **Tool documentation in skills:** Both `memory-triage` and `memory-dream` SKILL.md files now include full tool reference sections listing all available tools with parameters
+
+**Improvements:**
+- **Auto-capture and auto-recall default to enabled:** `autoCapture` and `autoRecall` now default to `true` (was `false`). Manifest descriptions updated accordingly. Ignored in skills mode
+- **`memory_update` over delete+add:** Skills now prefer `memory_update` for in-place edits — atomic and preserves edit history. Consolidation pattern updated: update best memory, delete redundant ones
+- **Search threshold lowered:** Default `searchThreshold` reduced from `0.5` to `0.1` for broader recall. Removed hardcoded `0.6` recall-specific override — all searches now use the configured threshold
+- **Embedder dimension propagation:** Vector store config auto-resolves dimensions from embedder config when not explicitly set. Syncs `dimension` and `embeddingModelDims` fields for Qdrant/PGVector compatibility
+- **Config file write safety:** `writeFullConfig()` now re-reads and deep-merges the `plugins` section before writing, preserving `installs` and `slots` written by the OpenClaw gateway
+- **Additional embedder models:** Added `mxbai-embed-large` (1024), `all-minilm` (384), and `snowflake-arctic-embed` (1024) to known embedder dimensions
+
+**Security:**
+- Bumped `protobufjs` to `>=7.5.5` via pnpm overrides (GHSA-xq3m-2v4x-88gg) ([#5012](https://github.com/mem0ai/mem0/pull/5012))
+
+**Fixes:**
+- Moved `bootstrapTelemetryFlag()` and removed `ensureInstallRecord()` from module-level side effects — both now run inside `register()` to avoid crashes when loaded outside OpenClaw gateway
+- Fixed OSS history DB path resolution: absolute paths no longer passed through `resolvePath()`, preventing double-prefix bugs
+- Manifest `providerAuthEnvVars` replaced with spec-compliant `setup.providers` format using `id` + `envVars`
+
+**Dependencies:**
+- Bumped `mem0ai` from `3.0.1` to `3.0.2`
+- Bumped `pluginApi` and `minGatewayVersion` compat to `>=2026.4.24`
+
+</Update>
+
 <Update label="2026-04-23" description="v1.0.10">
 
 **Security:**

docs/changelog/platform.mdx

@@ -4,6 +4,24 @@ description: "Release notes for the Mem0 hosted platform — backend, dashboard,
 mode: "wide"
 ---
 
+<Update label="2026-05-13" description="">
+
+**New Features:**
+- **Memory:** Added Temporal Reasoning for Platform v3 to improve ranking for time-aware queries such as `last week`, `upcoming`, `right now`, and `as of ...`
+- **Search:** Added `reference_date` support to anchor relative temporal queries for tests, backfills, and reproducible demos
+
+**Improvements:**
+- **API:** Temporal reasoning preserves the normal client response shape for search and get-all results
+
+</Update>
+
+<Update label="2026-05-04" description="">
+
+**New Features:**
+- **Memory Decay:** Per-project search-time ranking bias that boosts recently-used memories and gently dampens stale ones. Opt-in via `decay` on the project endpoint; off by default. The scaling factor stays in `0.3×–1.5×`, the public `score` remains clamped to `[0, 1]`, and the bias never filters a candidate out. See [Memory Decay docs](/platform/features/memory-decay).
+
+</Update>
+
 <Update label="2026-04-16" description="">
 
 **Improvements:**
@@ -294,4 +312,3 @@ mode: "wide"
 - **Core:** Fixed unicode error in user_id, agent_id, run_id and app_id
 
 </Update>
-

docs/changelog/sdk.mdx

@@ -7,6 +7,20 @@ mode: "wide"
 <Tabs>
 <Tab title="Python">
 
+<Update label="2026-05-08" description="v2.0.2">
+
+**Bug Fixes:**
+- **Telemetry:** Stitch OSS and platform PostHog identities on `MemoryClient` init so `$identify` events fire and a single user is no longer tracked as two or three disconnected personas ([#5040](https://github.com/mem0ai/mem0/pull/5040))
+- **Security:** Harden against SQL injection and prompt injection ([#4997](https://github.com/mem0ai/mem0/pull/4997))
+
+**New Features:**
+- **SDK:** Expose `decay` on `project.update` ([#5062](https://github.com/mem0ai/mem0/pull/5062))
+
+**Improvements:**
+- **Plugin:** Hand `mem0` search decisions to the agent ([#4992](https://github.com/mem0ai/mem0/pull/4992))
+
+</Update>
+
 <Update label="2026-04-25" description="v2.0.1">
 
 **Bug Fixes:**
@@ -41,7 +55,7 @@ mode: "wide"
 **Breaking Changes:**
 - **`add()` returns ADD-only events** — No more `"UPDATE"` or `"DELETE"` events. Memories accumulate; nothing is overwritten ([#4805](https://github.com/mem0ai/mem0/pull/4805))
 - **`search()` default `threshold` is now `0.1`** — Pass `threshold=0.0` for previous behavior ([#4805](https://github.com/mem0ai/mem0/pull/4805))
-- **`search()` `score` is now a combined multi-signal score** — The top-level `score` fuses semantic similarity, BM25 keyword match, and entity boost into one value. Absolute numbers shift versus the old raw cosine score; retune any hard thresholds against representative queries. Per-signal scores are not exposed on the response ([#4805](https://github.com/mem0ai/mem0/pull/4805), [#4836](https://github.com/mem0ai/mem0/pull/4836))
+- **`search()` `score` is now a combined multi-signal score** — The top-level `score` fuses semantic similarity, BM25 keyword match, entity signals, and temporal boosts into one value. Absolute numbers shift versus the old raw cosine score; retune any hard thresholds against representative queries ([#4805](https://github.com/mem0ai/mem0/pull/4805), [#4836](https://github.com/mem0ai/mem0/pull/4836))
 - **`search()` default `rerank` is now `False`** — Pass `rerank=True` for previous behavior ([#4805](https://github.com/mem0ai/mem0/pull/4805))
 - **`top_k` default changed 100 → 20** in `Memory.get_all()` and `Memory.search()` (sync + async). Pass `top_k=100` explicitly to restore the old behavior ([#4843](https://github.com/mem0ai/mem0/pull/4843))
 - **Entity ID validation:** `user_id` / `agent_id` / `run_id` are trimmed; empty-string and whitespace-only values now raise `ValueError` ([#4843](https://github.com/mem0ai/mem0/pull/4843))
@@ -910,6 +924,18 @@ See the [OSS v1 to v2 migration guide](https://docs.mem0.ai/migration/oss-v1-to-
 </Tab>
 
 <Tab title="TypeScript">
+<Update label="2026-05-08" description="v3.0.3">
+
+**Bug Fixes:**
+- **Telemetry:** Stitch OSS and platform PostHog identities on `MemoryClient` init so `$identify` events fire and a single user is no longer tracked as two or three disconnected personas ([#5040](https://github.com/mem0ai/mem0/pull/5040))
+- **Vector Stores:** Fix inverted vector distance in PGVector implementation ([#4944](https://github.com/mem0ai/mem0/pull/4944))
+- **Security:** Harden against SQL injection and prompt injection ([#4997](https://github.com/mem0ai/mem0/pull/4997))
+
+**New Features:**
+- **SDK:** Expose `decay` on `project.update` ([#5062](https://github.com/mem0ai/mem0/pull/5062))
+
+</Update>
+
 <Update label="2026-04-25" description="v3.0.2">
 
 **Bug Fixes:**

docs/core-concepts/memory-operations/search.mdx

@@ -156,6 +156,10 @@ const memories = memory.search("food preferences", {
   Expect an array of memory documents. Platform responses include vectors, metadata, and timestamps; OSS returns your stored schema.
 </Info>
 
+<Note>
+  On Mem0 Platform v3, time-aware queries use Temporal Reasoning internally while preserving the normal search response shape. See <Link href="/platform/features/temporal-reasoning">Temporal Reasoning</Link>.
+</Note>
+
 ## Filter patterns
 
 Filters help narrow down search results. Common use cases:
@@ -251,4 +255,4 @@ For the full list of filter logic, comparison operators, and optional search par
     icon="rocket"
     href="/cookbooks/operations/support-inbox"
   />
-</CardGroup>
+</CardGroup>

docs/docs.json

@@ -72,7 +72,8 @@
                           "platform/features/entity-scoped-memory",
                           "platform/features/async-client",
                           "platform/features/multimodal-support",
-                          "platform/features/custom-categories"
+                          "platform/features/custom-categories",
+                          "platform/features/temporal-reasoning"
                         ]
                       },
                       {
@@ -83,7 +84,8 @@
                           "platform/advanced-memory-operations",
                           "platform/features/criteria-retrieval",
                           "platform/features/contextual-add",
-                          "platform/features/custom-instructions"
+                          "platform/features/custom-instructions",
+                          "platform/features/memory-decay"
                         ]
                       },
                       {
@@ -1143,4 +1145,4 @@
       "destination": "/introduction"
     }
   ]
-}
+}

docs/integrations/codex.mdx

@@ -30,91 +30,100 @@ export MEM0_API_KEY="m0-your-api-key"
 
 ## Installation
 
-### Option A — Repo Marketplace (Recommended for Teams)
+### Option A — Direct MCP (Recommended)
 
-Add a `.agents/plugins/marketplace.json` to your repository root:
+The fastest way to connect Codex to Mem0 — no downloads, no marketplace. Codex reads MCP servers from `~/.codex/config.toml` as TOML. Add:
 
-```json
-{
-  "name": "mem0-plugins",
-  "interface": {
-    "displayName": "Mem0 Plugins"
-  },
-  "plugins": [
-    {
-      "name": "mem0",
-      "source": {
-        "source": "local",
-        "path": "./plugins/mem0"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Productivity"
-    }
-  ]
-}
+```toml
+[mcp_servers.mem0]
+url = "https://mcp.mem0.ai/mcp"
+bearer_token_env_var = "MEM0_API_KEY"
 ```
 
-Then in Codex, browse the repo's plugin directory and install Mem0.
+Make sure `MEM0_API_KEY` is exported in the shell you launch Codex from, then restart Codex.
 
-### Option B — Personal Marketplace
+<Info>
+  Codex's `codex mcp add` CLI only supports stdio MCP servers. Because Mem0's MCP is HTTP/streamable, you configure it by editing `config.toml` directly (or via the **Plugins → Connect to a custom MCP → Streamable HTTP** UI in the Codex app).
+</Info>
 
-Add to `~/.agents/plugins/marketplace.json`:
+### Option B — Sideload the Plugin (Advanced)
 
-```json
-{
-  "name": "mem0-plugins",
-  "interface": {
-    "displayName": "Mem0 Plugins"
-  },
-  "plugins": [
-    {
-      "name": "mem0",
-      "source": {
-        "source": "local",
-        "path": "/path/to/mem0-plugin"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Productivity"
-    }
-  ]
-}
+For the full plugin experience — MCP server **plus** the Mem0 SDK skill, memory protocol skill, and opt-in lifecycle hooks — sideload the plugin from a local clone. The Mem0 repo already ships a marketplace manifest at [`.agents/plugins/marketplace.json`](https://github.com/mem0ai/mem0/blob/main/.agents/plugins/marketplace.json), so there's no JSON to author by hand. This follows the Codex [build-plugins](https://developers.openai.com/codex/plugins/build) local-testing workflow.
+
+<Info>
+  Don't combine Option B with Option A. The plugin manifest declares its MCP server via [`.codex-mcp.json`](https://github.com/mem0ai/mem0/blob/main/mem0-plugin/.codex-mcp.json), so Codex auto-registers the `mem0` MCP server when the plugin loads. Adding the same `[mcp_servers.mem0]` block to `~/.codex/config.toml` will create a duplicate registration.
+</Info>
+
+**Step 1.** Clone the Mem0 repository anywhere on disk:
+
+```bash
+git clone https://github.com/mem0ai/mem0.git ~/codex-plugins/mem0-source
 ```
 
-### Option C — Manual MCP Configuration
+**Step 2.** Register the bundled marketplace with Codex's CLI:
 
-Add to your Codex MCP config:
-
-```json
-{
-  "mcpServers": {
-    "mem0": {
-      "type": "http",
-      "url": "https://mcp.mem0.ai/mcp/",
-      "headers": {
-        "Authorization": "Token ${MEM0_API_KEY}"
-      }
-    }
-  }
-}
+```bash
+codex plugin marketplace add ~/codex-plugins/mem0-source
 ```
 
+This points Codex at the repo's `.agents/plugins/marketplace.json`. The bundled file uses `path: "./mem0-plugin"`, which Codex resolves relative to the clone root.
+
+<Info>
+  **Why we recommend this over hand-authoring `~/.agents/plugins/marketplace.json`:** Codex requires `source.path` in any marketplace manifest to be **relative** (starting with `./`) and **inside the marketplace root**. The repo's bundled manifest already satisfies this — the marketplace root is the clone directory, and `mem0-plugin/` lives inside it. With a personal `~/.agents/plugins/marketplace.json`, the root is `~/` and the clone has to live under `~/` too. The CLI form sidesteps that constraint.
+</Info>
+
+**Step 3.** Restart Codex, run `/plugins`, browse the `Mem0 Plugins` marketplace, and install **Mem0**.
+
+**Step 4 (optional) — enable lifecycle hooks.** Codex doesn't auto-wire hooks from plugin manifests; it only reads them from `~/.codex/hooks.json` (or `<repo>/.codex/hooks.json`). Run the bundled installer once to merge the Mem0 entries into your global hooks file:
+
+```bash
+python3 ~/codex-plugins/mem0-source/mem0-plugin/scripts/install_codex_hooks.py
+```
+
+Then enable the hooks feature flag in `~/.codex/config.toml`:
+
+```toml
+[features]
+codex_hooks = true
+```
+
+Restart Codex. The installer registers three hooks pointing at scripts inside your clone:
+
+| Event | Behavior |
+|-------|----------|
+| `SessionStart` | Loads prior memories as bootstrap context |
+| `UserPromptSubmit` | Injects relevant memories before each prompt |
+| `Stop` | Reminds the agent to persist learnings at turn end |
+
+Re-running the installer is idempotent. To remove the hooks: `python3 ~/codex-plugins/mem0-source/mem0-plugin/scripts/install_codex_hooks.py --uninstall`.
+
+<Warning>
+  The hooks file stores absolute paths into your clone (e.g. `~/codex-plugins/mem0-source/mem0-plugin/scripts/...`). If you move or delete the clone, the hooks will break silently — re-run the installer from the new location, or run `--uninstall` first.
+</Warning>
+
+### Managing the Plugin
+
+Codex provides CLI commands for managing marketplaces after install:
+
+```bash
+codex plugin marketplace upgrade               # pull latest plugin versions
+codex plugin marketplace remove mem0-plugins   # unregister the marketplace
+```
+
+To pull updates to the plugin source itself, `git pull` inside your clone (`~/codex-plugins/mem0-source`) and then run `codex plugin marketplace upgrade` to refresh Codex's plugin cache. Plugins are cached at `~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/`.
+
 <Info icon="check">
-  Start a new Codex task and ask: *"List my mem0 entities"* or *"Search my memories for hello"*. If the `mem0` tools appear and respond, you're all set.
+  After either option, start a new Codex task and ask: *"List my mem0 entities"* or *"Search my memories for hello"*. If the `mem0` tools appear and respond, you're all set.
 </Info>
 
 ## What's Included
 
-| Component | Plugin Install | MCP Only |
-|-----------|:--------------:|:--------:|
+| Component | Sideloaded Plugin | Direct MCP |
+|-----------|:-----------------:|:----------:|
 | MCP Server (9 memory tools) | Yes | Yes |
 | Memory Protocol Skill | Yes | No |
 | Mem0 SDK Skill | Yes | No |
+| Lifecycle Hooks (opt-in) | Yes | No |
 
 ## Available MCP Tools
 
@@ -134,7 +143,7 @@ Once installed, the following tools are available in every Codex session:
 
 ## Memory Protocol Skill
 
-Codex uses a skill-based approach instead of lifecycle hooks. When installed via the plugin marketplace, the memory protocol skill instructs the agent to:
+When the plugin is sideloaded, the memory protocol skill instructs the agent to:
 
 ### On Every New Task
 1. Call `search_memories` with a query related to the current task to load relevant context
@@ -199,8 +208,12 @@ You: Add WebSocket support for real-time notification delivery.
 
 - **"Connection failed"** — Verify `MEM0_API_KEY` is set in your shell: `echo $MEM0_API_KEY`
 - **No tools appearing** — Restart your Codex session after plugin installation
-- **Plugin not found** — Ensure `.agents/plugins/marketplace.json` is at the repository root and `source.path` points to the correct plugin directory
-- **Skills not loading** — Verify the `skills` field in `plugin.json` points to a valid directory containing `SKILL.md` files
+- **Duplicate `mem0` MCP server / "tool collision" errors** — You combined Option A (Direct MCP) with Option B (sideload). The sideloaded plugin auto-registers `mem0` from `.codex-mcp.json`, so remove the `[mcp_servers.mem0]` block from `~/.codex/config.toml`.
+- **`plugin/read failed in TUI`** — Codex can't find the plugin directory the marketplace points at. If you used `codex plugin marketplace add <path>`, confirm the path is your clone root and that `<clone>/.agents/plugins/marketplace.json` exists. If you hand-authored `~/.agents/plugins/marketplace.json`, `source.path` must be relative (start with `./`), inside the marketplace root (`~/` for personal installs), and end in `mem0-plugin` — e.g. `"./codex-plugins/mem0-source/mem0-plugin"`.
+- **Plugin not found in `/plugins`** — Run `codex plugin marketplace add ~/path/to/clone` again, or confirm the marketplace was registered with `codex plugin marketplace remove mem0-plugins` then re-add.
+- **Skills not loading** — Verify the `skills` field in `plugin.json` points to a valid directory containing `SKILL.md` files.
+- **Hooks not firing** — Confirm `codex_hooks = true` is in `~/.codex/config.toml` under `[features]`, and that `~/.codex/hooks.json` contains the Mem0 entries (re-run the installer if not). Restart Codex after enabling the flag.
+- **Hooks broke after moving the clone** — The installer bakes absolute paths into `~/.codex/hooks.json` pointing at scripts inside your clone. If you moved or renamed the clone directory, run `python3 <new-clone>/mem0-plugin/scripts/install_codex_hooks.py` from the new location — the installer is idempotent and replaces the old entries.
 
 <CardGroup cols={2}>
   <Card title="Mem0 MCP Setup" icon="puzzle-piece" href="/platform/mem0-mcp">

docs/integrations/openclaw.mdx

@@ -1,6 +1,6 @@
 ---
 title: OpenClaw
-description: "Add long-term memory to OpenClaw agents using the Mem0 plugin with auto-recall and auto-capture support."
+description: "Add long-term memory to OpenClaw agents using the Mem0 plugin with skills-based memory extraction and recall."
 ---
 
 Add long-term memory to [OpenClaw](https://github.com/openclaw/openclaw) agents with the `@mem0/openclaw-mem0` plugin. Your agent forgets everything between sessions — this plugin fixes that by automatically watching conversations, extracting what matters, and bringing it back when relevant.
@@ -12,11 +12,12 @@ Add long-term memory to [OpenClaw](https://github.com/openclaw/openclaw) agents
 </Frame>
 
 The plugin provides:
-1. **Auto-Recall** — Before the agent responds, memories matching the current message are injected into context
-2. **Auto-Capture** — After the agent responds, the exchange is sent to Mem0 which decides what's worth keeping
-3. **Agent Tools** — Eight tools for explicit memory operations during conversations
+1. **Triage** — The agent extracts durable facts from conversations using a structured protocol with importance gates and domain overlays
+2. **Recall** — Before each turn, relevant memories are retrieved with reranking and injected into context
+3. **Dream** — Periodic memory consolidation: merges duplicates, resolves conflicts, prunes stale entries
+4. **Agent Tools** — Eight tools for explicit memory operations during conversations
 
-Both auto-recall and auto-capture are opt-in (`autoRecall: true`, `autoCapture: true` in config). Once enabled, they run silently with no manual intervention required.
+Skills mode, `autoRecall`, and `autoCapture` are all enabled by default during `openclaw mem0 init`.
 
 ## Requirements
 
@@ -24,12 +25,12 @@ Check your OpenClaw version:
 
 ```bash
 openclaw --version
-# OpenClaw 2026.4.15 (041266a)
+# OpenClaw 2026.4.25 (aa36ee6)
 ```
 
 | OpenClaw Version | Plugin Support |
 |------------------|----------------|
-| `>= 2026.4.15`   | Fully supported |
+| `>= 2026.4.25`   | Fully supported |
 
 ## Installation
 
@@ -100,9 +101,9 @@ You no longer need manual config editing to get started. Everything happens insi
   </Step>
 </Steps>
 
-That's it. No API key, no config file editing, no environment variables. The plugin is now active and auto-capture and auto-recall are running on every turn.
+That's it. No API key, no config file editing, no environment variables. The plugin is now active with skills-based memory (triage, recall, and dream) running automatically.
 
-<Note>The chat flow uses the same underlying config as manual setup — it writes `apiKey` and `userId` into `openclaw.json` for you. You can still open the file to inspect or override values afterward.</Note>
+<Note>The chat flow uses the same underlying config as manual setup — it writes `apiKey`, `userId`, and `skills` config into `openclaw.json` for you. You can still open the file to inspect or override values afterward.</Note>
 
 #### Option 2: Manual Config
 
@@ -131,7 +132,19 @@ That's it. No API key, no config file editing, no environment variables. The plu
             "enabled": true,
             "config": {
               "apiKey": "${MEM0_API_KEY}",
-              "userId": "alice"  // any unique identifier you choose for this user
+              "userId": "alice",  // any unique identifier you choose for this user
+              "skills": {
+                "triage": { "enabled": true },
+                "recall": {
+                  "enabled": true,
+                  "tokenBudget": 1500,
+                  "rerank": true,
+                  "keywordSearch": true,
+                  "identityAlwaysInclude": true
+                },
+                "dream": { "enabled": true },
+                "domain": "companion"
+              }
             }
           }
         }
@@ -328,8 +341,8 @@ openclaw mem0 status --json
 |-----|------|---------|-------------|
 | `mode` | `"platform"` \| `"open-source"` | `"platform"` | Which backend to use |
 | `userId` | `string` | OS username | Scope memories per user |
-| `autoRecall` | `boolean` | `false` | Inject memories before each turn (opt-in) |
-| `autoCapture` | `boolean` | `false` | Store facts after each turn (opt-in) |
+| `autoRecall` | `boolean` | `true` | Inject memories before each turn. Ignored when `skills` is configured. |
+| `autoCapture` | `boolean` | `true` | Store facts after each turn. Ignored when `skills` is configured. |
 | `topK` | `number` | `5` | Max memories per recall |
 | `searchThreshold` | `number` | `0.3` | Min similarity (0–1) |
 
@@ -426,9 +439,11 @@ If `openclaw plugins update` fails:
 | **Platform** | Conversations sent to `api.mem0.ai` for extraction and storage | Mem0 cloud |
 | **Open-source** | Embeddings generated via configured provider (default: OpenAI API). Vectors stored locally. | `~/.mem0/vector_store.db` (SQLite) |
 
-### Enabling Auto-Capture and Auto-Recall
+### Auto-Capture and Auto-Recall
 
-Auto-capture and auto-recall are disabled by default (opt-in). To enable either or both:
+Auto-capture and auto-recall are **enabled by default**. When skills mode is configured (the default after `openclaw mem0 init`), these are ignored in favor of the skills-based triage/recall/dream protocol.
+
+To disable either:
 
 ```json5
 {
@@ -436,8 +451,8 @@ Auto-capture and auto-recall are disabled by default (opt-in). To enable either
     "entries": {
       "openclaw-mem0": {
         "config": {
-          "autoCapture": true,   // send conversations to Mem0 for extraction
-          "autoRecall": true     // inject relevant memories into context
+          "autoCapture": false,   // disable automatic fact extraction
+          "autoRecall": false     // disable automatic memory injection
         }
       }
     }
@@ -445,7 +460,7 @@ Auto-capture and auto-recall are disabled by default (opt-in). To enable either
 }
 ```
 
-Without these enabled, the agent can still use memory tools (`memory_add`, `memory_search`, etc.) explicitly — only the automatic background behavior is off.
+The agent can always use memory tools (`memory_add`, `memory_search`, etc.) explicitly regardless of these settings.
 
 ### Credential Protection
 

docs/llms.txt

@@ -185,8 +185,10 @@ If the user is on a pre-current major (Python < 2, TS < 3, or Platform `output_f
 ### Features - Advanced Retrieval
 - [Advanced Retrieval](https://docs.mem0.ai/platform/features/advanced-retrieval) [Platform]: Use when the user needs keyword search, reranking, or hybrid retrieval.
 - [Criteria-Based Retrieval](https://docs.mem0.ai/platform/features/criteria-retrieval) [Platform]: Use when targeting memories by custom criteria, not just semantic similarity.
+- [Temporal Reasoning](https://docs.mem0.ai/platform/features/temporal-reasoning) [Platform]: Use when time-aware searches like last week, upcoming, or right now need better result ordering.
 - [Contextual Add](https://docs.mem0.ai/platform/features/contextual-add) [Platform]: Use when `add()` should consider the surrounding conversation, not just the latest turn.
 - [Custom Instructions](https://docs.mem0.ai/platform/features/custom-instructions) [Platform]: Use when tailoring what Mem0 extracts and stores on Platform.
+- [Memory Decay](https://docs.mem0.ai/platform/features/memory-decay) [Platform]: Use when search results should boost recently-reinforced memories and dampen stale ones — opt-in per project, search-time only, never filters candidates out.
 - [Advanced Memory Operations](https://docs.mem0.ai/platform/advanced-memory-operations) [Platform]: Use when basic CRUD is not enough - batch ops, complex filters, workflows.
 
 ### Features - Data Management

docs/migration/platform-v2-to-v3.mdx

@@ -42,7 +42,7 @@ Previously, when an agent said something like "I've booked your flight for March
 
 ### Retrieval is hybrid now
 
-Search now uses hybrid retrieval, which improves ranking quality — especially for queries involving exact keywords, proper nouns, or entities that appear across multiple memories. The response shape is unchanged:
+Search now uses hybrid retrieval, which improves ranking quality — especially for queries involving exact keywords, proper nouns, entities that appear across multiple memories, and time-aware queries (via Temporal Reasoning). The response shape is unchanged:
 
 ```json
 {
@@ -58,7 +58,7 @@ Search now uses hybrid retrieval, which improves ranking quality — especially
 }
 ```
 
-The top-level `score` remains a `[0, 1]` value. Relative ranking between results stays comparable to v2, but absolute numbers shift since the scoring method changed — retune any hard thresholds in your app against representative queries.
+The top-level `score` remains a `[0, 1]` value. Relative ranking between results stays comparable to v2, but absolute numbers shift since the scoring method changed — retune any hard thresholds in your app against representative queries. Temporal signals are applied internally during ranking and are not returned as extra client-facing fields.
 
 ## API Changes
 
@@ -289,6 +289,7 @@ If your application previously read graph relations from the API response (`rela
 - **V1 and V2 endpoints continue to work.** There is no requirement to migrate to V3 endpoints immediately.
 - **Existing memories are preserved.** The new algorithm does not modify or re-process previously stored memories.
 - **Search response shape is unchanged.** The top-level `score` and `results[]` array are the same; existing code that reads `score` continues to work. What changed is the scoring method behind the number (multi-signal fusion instead of pure cosine), so the absolute values shift even when ranking stays comparable.
+- **Search remains backward-compatible at the top level.** Existing code that reads `results[]` and `score` continues to work. Temporal signals are applied internally during retrieval and do not change the client response shape.
 - **List response shape changed.** `get_all` now returns a paginated envelope (`{count, next, previous, results}`) instead of a bare `{results: [...]}`. Update code that reads `response["results"]` to continue working, or switch to the client SDKs which handle both shapes.
 
 ## Performance Improvements

docs/openapi.json

@@ -419,7 +419,7 @@
 													},
 													"results": {
 														"type": "array",
-														"description": "Array of results produced by the event."
+														"description": "Array of results produced by the event. For add events, this confirms the write completed; temporal reasoning enrichment runs asynchronously by default."
 													},
 													"created_at": {
 														"type": "string",
@@ -2071,7 +2071,7 @@
 					"memories"
 				],
 				"summary": "Search memories (V3)",
-				"description": "Relevance-ranked search across stored memories. V3 uses hybrid retrieval — the returned `score` is a combined `[0, 1]` value; per-signal component scores are not exposed on the response. Entity IDs **must** be passed inside the `filters` object — top-level `user_id` / `agent_id` / `run_id` are rejected with 400. At least one entity ID is required.",
+				"description": "Relevance-ranked search across stored memories. V3 uses hybrid retrieval and can also apply temporal reasoning for time-aware queries. Entity IDs **must** be passed inside the `filters` object — top-level `user_id` / `agent_id` / `run_id` are rejected with 400. At least one entity ID is required.",
 				"operationId": "memories_search_v3",
 				"requestBody": {
 					"required": true,
@@ -2112,6 +2112,21 @@
 										"type": "boolean",
 										"default": false,
 										"description": "Apply the managed reranker for better ordering (adds latency)."
+									},
+									"reference_date": {
+										"oneOf": [
+											{
+												"type": "integer"
+											},
+											{
+												"type": "number"
+											},
+											{
+												"type": "string"
+											}
+										],
+										"nullable": true,
+										"description": "Optional query anchor time for relative temporal interpretation. Accepts Unix epoch, YYYY-MM-DD, or ISO datetime."
 									}
 								}
 							},

docs/platform/features/mcp-integration.mdx

@@ -53,7 +53,7 @@ For detailed per-client instructions, see the [Mem0 MCP Quickstart](/platform/me
 
 ## Available tools
 
-The MCP server exposes 9 memory tools to your AI client:
+The MCP server exposes 11 memory tools to your AI client:
 
 | Tool | Purpose |
 |------|---------|
@@ -66,6 +66,8 @@ The MCP server exposes 9 memory tools to your AI client:
 | `delete_entities` | Remove user/agent/app entities |
 | `get_memory` | Retrieve single memory by ID |
 | `list_entities` | View stored entities |
+| `list_events` | List memory operation events with filters and pagination |
+| `get_event_status` | Check the status of an async memory operation by `event_id` |
 
 ## How it works
 

docs/platform/features/memory-decay.mdx

@@ -0,0 +1,191 @@
+---
+title: Memory Decay
+description: "Boost recently-used memories and gently dampen stale ones at search time, without filtering anything out."
+---
+
+# Memory Decay
+
+Older memories drift in relevance at different speeds. A user's coffee order matters every morning; a one-off project name from last quarter rarely matters again. Memory Decay makes that intuition explicit at search time: every time a memory is returned in a search it gets a small reinforcement, and memories that haven't been touched in a while have their ranking score gently dampened.
+
+It is **a soft ranking bias, never a filter.** Decay never zeroes a candidate out — at worst it scales its score by `0.3×`. Anything that would have surfaced without decay can still surface with decay on, just with a different ranking among similarly-scored results.
+
+<Info>
+  **Use Memory Decay when…**
+  - Search results are crowded with old facts the user no longer cares about.
+  - You want recently-used memories to drift to the top automatically — without writing custom scoring logic.
+  - You want this preference applied per project so cohorts can be compared side-by-side.
+</Info>
+
+<Warning>
+  Memory Decay is **opt-in per project** and **off by default**. Search behavior is bit-identical to today until you turn it on. The toggle applies to v3 search only.
+</Warning>
+
+## How it works
+
+Every memory carries a small piece of bookkeeping: when was it last retrieved, and how often. Memory Decay turns that history into a *scaling factor* in the range `0.3×` to `1.5×` and multiplies it into the ranking score at search time.
+
+| Memory state | Scaling factor | Ranking effect |
+|---|---|---|
+| Just accessed | ≈ **1.5×** | Strong boost |
+| Touched today | 1.2 – 1.4× | Mild boost |
+| Idle for a few days | 0.6 – 1.0× | Mild dampening |
+| Idle for weeks | 0.4 – 0.6× | Stronger dampening |
+| Idle for many months / years | ≈ **0.3×** | Floor — never lower |
+
+The bounds matter: `0.3` is the floor and `1.5` is the ceiling, so decay can meaningfully reorder candidates without ever dominating the underlying relevance score.
+
+At search time the pipeline:
+
+1. Widens the candidate pool (`top_k × 3`, with a floor of 50) so reordering has room.
+2. Multiplies each candidate's score by its scaling factor.
+3. Sorts on the unclamped product so the full `0.3×–1.5×` range can rearrange candidates.
+4. Returns the public `score` clamped to `[0, 1]` so the API contract is preserved.
+5. Truncates to the `top_k` you requested.
+6. Records a fire-and-forget reinforcement against each returned memory — its access history grows by one, capped at the most recent 20 touches.
+
+Memories created before decay was enabled don't yet have an access history. They use a sensible fallback: their `updated_at` is treated as a single past touch, so the same scale above applies based on how stale that update is — a recently-updated legacy memory enters near the neutral band, a long-stale one sits closer to the floor. Once surfaced in a search after decay is on, they accumulate access history naturally and behave like any other memory.
+
+## Configure access
+
+- Set `MEM0_API_KEY` in your environment, or pass it to the SDK constructor.
+- Initialize the client with the organization and project you want to scope to.
+
+The toggle lives on the project. You enable decay by patching the project's `decay` field; everything else — your `add` calls, your `search` calls, your application code — stays exactly the same.
+
+## Enable decay for a project
+
+### 1. Turn the flag on
+
+The toggle is exposed on the standard project-update endpoint, the same place where `multilingual` and `custom_categories` live.
+
+<CodeGroup>
+```python Python
+client.project.update(decay=True)
+```
+
+```javascript JavaScript
+await client.project.update({ decay: true });
+```
+
+```bash cURL
+curl -X PATCH https://api.mem0.ai/api/v1/orgs/organizations/$ORG_ID/projects/$PROJECT_ID/ \
+  -H "Authorization: Token $MEM0_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"decay": true}'
+```
+
+```json Response
+{ "message": "Updated decay" }
+```
+</CodeGroup>
+
+### 2. Confirm the state
+
+`decay` is returned on every project read. To fetch only this field, use `?fields=decay`.
+
+<CodeGroup>
+```python Python
+response = client.project.get(fields=["decay"])
+print(response["decay"])
+```
+
+```javascript JavaScript
+const response = await client.project.get({ fields: ["decay"] });
+console.log(response.decay);
+```
+
+```bash cURL
+curl "https://api.mem0.ai/api/v1/orgs/organizations/$ORG_ID/projects/$PROJECT_ID/?fields=decay" \
+  -H "Authorization: Token $MEM0_API_KEY"
+```
+
+```json Response
+{ "decay": true }
+```
+</CodeGroup>
+
+### 3. Turn it back off
+
+The toggle is fully reversible. Setting it to `false` immediately restores the pre-decay ranking; nothing about your stored memories is modified or lost.
+
+<CodeGroup>
+```python Python
+client.project.update(decay=False)
+```
+
+```javascript JavaScript
+await client.project.update({ decay: false });
+```
+
+```bash cURL
+curl -X PATCH https://api.mem0.ai/api/v1/orgs/organizations/$ORG_ID/projects/$PROJECT_ID/ \
+  -H "Authorization: Token $MEM0_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"decay": false}'
+```
+</CodeGroup>
+
+<Note>
+  The toggle is idempotent. Re-applying the same value is a no-op, and access history accumulated while decay was on is preserved if you flip it back on later.
+</Note>
+
+## What changes when decay is on
+
+- **Search ranking reorders.** A relevant memory you reinforced an hour ago will tend to outrank an equally-relevant memory that was last touched a month ago.
+- **The candidate pool over-fetches** to give the scaling factor room to reorder. You still get exactly the `top_k` you requested, but the items returned can come from a deeper slice of the pre-decay ranking than before.
+- **The public `score` field stays in `[0, 1]`.** Even when the internal product exceeds 1, the field returned to the client is clamped, so existing assertions and downstream UI logic continue to work.
+
+## What stays the same
+
+- **Public API shape** — every endpoint accepts the same parameters and returns the same fields. You don't touch your client code.
+- **Threshold semantics on the request side** — your `threshold` is still applied during candidate selection.
+- **Memory creation and storage** — every new memory still lands the same way. Decay is a search-time concern.
+- **Per-memory data** — categories, metadata, timestamps, embeddings: untouched.
+
+<Warning>
+  Because the scaling factor is applied *after* the threshold filter has already run, an item that passed the request `threshold` can come back with a public `score` slightly below it (a stale candidate dampened by `0.3×`). This is intentional — decay is a soft bias, not a filter. If you require a hard `score >= threshold` invariant on the response, filter client-side after the call.
+</Warning>
+
+## Lifecycle of a memory under decay
+
+| Stage | Scaling factor | Effect |
+|---|---|---|
+| Just added | ≈ 1.5× | Strong boost — fresh facts surface easily. |
+| Reinforced on a recent search | 1.2 – 1.5× | Sustains its boost for the next several searches. |
+| Idle for a few days | 0.6 – 1.0× | Falls back into the neutral band. |
+| Idle for weeks | 0.4 – 0.6× | Mild dampening — can still surface for strong matches. |
+| Pre-decay legacy memory (no access history) | 0.3 – 1.0× | Falls back to `updated_at`: recently-updated entries land near 1.0×, long-stale entries approach the 0.3× floor. |
+
+The reinforcement is bounded: each memory tracks at most the last 20 access timestamps, so the boost stays well-behaved no matter how many times a memory is retrieved.
+
+## FAQ
+
+**Will decay ever drop a result that would otherwise surface?**
+No. The floor is `0.3×` — the scaling factor can dampen a score, never zero it. Threshold filtering happens *before* decay, so any candidate that cleared the threshold is in the pool decay reorders.
+
+**Why is the public score sometimes below my requested threshold?**
+The threshold is applied to the candidate pool pre-decay; the scaling factor then reshapes scores in the `0.3×–1.5×` band. A stale-but-relevant candidate can come back with a final score slightly under your threshold by design — the candidate stays visible but visibly dampened. Filter client-side if you need a hard floor on the response.
+
+**Does decay change how I add memories?**
+No. The `client.add(...)` path is unchanged. Decay is a search-time ranking adjustment.
+
+**What if I had memories before turning decay on?**
+They use a fallback: the memory's `updated_at` is treated as a single historical touch, so the same scaling applies based on how stale that update is — a recently-updated legacy memory enters near the neutral band (~1.0×), a long-stale one closer to the floor (~0.3×). Once retrieved they accumulate access history and behave like any other memory.
+
+**Can I tune how aggressively decay scales scores?**
+Not in this version. The current scaling is calibrated to be conservative — wide enough to meaningfully reorder candidates, narrow enough to never dominate the underlying relevance score. Per-project tuning is on the roadmap.
+
+**Can I see the scaling factor per result?**
+Internal scoring details are persisted on the search Event for support and debugging. They aren't exposed in the public response by design — the response surface stays a single `score` field.
+
+**Does decay interact with reranking?**
+Yes — they layer cleanly. The reranker produces a richer relevance score; decay then biases that score by reinforcement history before final truncation to `top_k`.
+
+## What's next
+
+This release is deliberately the simplest version of decay we could ship — every memory contributes to ranking through its access history alone, so the signal can be evaluated in isolation. On the roadmap:
+
+- **Category-aware weighting.** A fact tagged `health` will be able to carry more weight than a passing observation tagged `misc`, so important categories don't get dampened the same way as noise.
+- **Auto-tuning per project.** Project-scoped automatic adjustment of how aggressively decay scales scores, based on observed access patterns — replacing the fixed scaling band with one that fits your workload.
+
+Both extensions are forward-compatible — no migration on your side will be needed when they ship.

docs/platform/features/temporal-reasoning.mdx

@@ -0,0 +1,145 @@
+---
+title: Temporal Reasoning
+description: "Time-aware memory retrieval for Mem0 Platform v3 so queries like 'last week', 'upcoming', and 'right now' return the right memories."
+icon: "clock"
+badge: "v3"
+---
+
+Some memories matter because of **when** they happened, not just because they sound similar. Temporal Reasoning lets Mem0 Platform v3 understand time-aware queries and return the most contextually appropriate results.
+
+<Info>
+  **Use Temporal Reasoning when…**
+  - Users ask questions like "what happened last week?" or "what do I have coming up?"
+  - Your app stores both past events and future plans for the same person
+  - You want time-aware retrieval without building your own date-parsing layer
+</Info>
+
+<Warning>
+  Temporal Reasoning is a **Mem0 Platform v3** feature. It is not available on OSS memory stores or older Platform endpoints.
+</Warning>
+
+## Configure access
+
+Confirm your `MEM0_API_KEY` is set and that you are using the v3 Platform client:
+
+```python
+from mem0 import MemoryClient
+
+client = MemoryClient(api_key="your-api-key")
+```
+
+## How it works
+
+When a memory describes an event, a future plan, or an ongoing state, Temporal Reasoning recognizes the time context so the right results surface at search time.
+
+A query like `what did I do last week?` should return a completed past event — not an upcoming appointment and not a stable fact that hasn't changed. Temporal Reasoning handles that distinction automatically.
+
+### Memory types Temporal Reasoning handles
+
+| Type | What it represents | Example |
+| --- | --- | --- |
+| Dated occurrence | Something that happened at a known time | "I finished the Q1 review on March 10, 2025." |
+| Future plan | A future commitment or scheduled item | "I have a dentist appointment on March 18, 2025." |
+| Ongoing state | A fact that remains true over time | "I am the product lead at Acme Corp." |
+| Relationship | A durable connection between people or entities | "Priya manages Jordan." |
+| Preference | A stable preference or habit | "I prefer morning meetings." |
+
+Results come back in the normal search response shape — Temporal Reasoning affects ranking, not the response format.
+
+## Configure it
+
+Temporal Reasoning is enabled by default for all v3 searches and writes. There is no per-request toggle.
+
+Two parameters give you precise control when you need it:
+
+- `timestamp` on `add()` — anchors an imported memory to the time it actually happened, rather than the time it was added to Mem0
+- `reference_date` on `search()` — resolves relative phrases like `last week` against a fixed point in time
+
+<CodeGroup>
+```python Python
+from datetime import datetime, timezone
+from mem0 import MemoryClient
+
+client = MemoryClient(api_key="your-api-key")
+
+# Import a historical memory anchored to when it happened
+client.add(
+    [{"role": "user", "content": "I finished the Q1 review on March 10, 2025."}],
+    user_id="jordan",
+    timestamp=int(datetime(2025, 3, 10, tzinfo=timezone.utc).timestamp()),
+)
+
+# Search with a relative query anchored to a known date
+results = client.search(
+    "what did I do last week?",
+    filters={"user_id": "jordan"},
+    reference_date="2025-03-21T00:00:00Z",
+)
+```
+
+```javascript JavaScript
+import { MemoryClient } from "mem0ai";
+
+const client = new MemoryClient({ apiKey: "your-api-key" });
+
+// Import a historical memory anchored to when it happened
+await client.add(
+  [{ role: "user", content: "I finished the Q1 review on March 10, 2025." }],
+  {
+    userId: "jordan",
+    timestamp: Math.floor(new Date("2025-03-10T00:00:00Z").getTime() / 1000),
+  }
+);
+
+// Search with a relative query anchored to a known date
+const results = await client.search("what did I do last week?", {
+  filters: { user_id: "jordan" },
+  referenceDate: "2025-03-21T00:00:00Z",
+});
+```
+</CodeGroup>
+
+<Tip>
+  `reference_date` is especially useful in automated tests and demos because it makes relative phrases like `last week` resolve consistently every time.
+</Tip>
+
+## Supported query patterns
+
+<AccordionGroup>
+  <Accordion title="Historical questions">
+    Examples: `last week`, `last month`, `in March 2025`, `on 2025-03-10`
+  </Accordion>
+  <Accordion title="Upcoming questions">
+    Examples: `upcoming`, `next week`, `tomorrow`, `what do I have coming up?`
+  </Accordion>
+  <Accordion title="Current-state questions">
+    Examples: `right now`, `currently`, `where do I work now?`
+  </Accordion>
+  <Accordion title="As-of questions">
+    Examples: `as of March 2025`, `where was I living as of 2024?`
+  </Accordion>
+  <Accordion title="Duration questions">
+    Examples: `how long have I lived here?`, `since when have I worked there?`
+  </Accordion>
+</AccordionGroup>
+
+## Verify the feature is working
+
+- Run a temporal search with a time-aware query (e.g., "what did I do last week?") and confirm the memory that fits the time window ranks first.
+- Use `reference_date` in test queries so relative phrases resolve consistently across runs.
+- For backfilled data, pass `timestamp` on `add()` to confirm the memory reflects the right point in time.
+
+## Best practices
+
+- Use explicit dates in source conversations when events or plans matter temporally.
+- Pass `timestamp` during historical imports so the ingestion time does not become the only time anchor.
+- Scope searches with `filters` so time-aware ranking operates inside the right user boundary.
+- Use `reference_date` in automated tests and reproducible demos.
+
+<CardGroup cols={1}>
+  <Card title="Memory Timestamps" icon="calendar" href="/platform/features/timestamp">
+    Anchor imported memories to when they actually happened.
+  </Card>
+</CardGroup>
+
+<Snippet file="get-help.mdx" />

docs/platform/mem0-mcp.mdx

@@ -10,7 +10,7 @@ estimatedTime: "~2 minutes"
   - Mem0 Platform account (<a href="https://app.mem0.ai?utm_source=oss&utm_medium=platform-mem0-mcp" rel="nofollow">Sign up here</a>)
   - API key (<a href="https://app.mem0.ai/settings/api-keys?utm_source=oss&utm_medium=platform-mem0-mcp" rel="nofollow">Get one from dashboard</a>)
   - Node.js 14+ (for npx)
-  - An MCP-compatible client (Claude, Claude Code, Cursor, Windsurf, VS Code, OpenCode)
+  - An MCP-compatible client (Claude, Claude Code, Codex, Cursor, Windsurf, VS Code, OpenCode)
 </Info>
 
 ## What is Mem0 MCP?
@@ -46,6 +46,8 @@ The MCP server exposes these memory tools to your AI client:
 | `delete_all_memories` | Bulk delete all memories in scope |
 | `delete_entities` | Delete a user/agent/app/run entity and its memories |
 | `list_entities` | Enumerate users/agents/apps/runs stored in Mem0 |
+| `list_events` | List memory operation events with filters and pagination |
+| `get_event_status` | Check the status of an async memory operation by `event_id` |
 
 ---
 
@@ -86,6 +88,33 @@ You can also configure individual clients:
     ```
   </Accordion>
 
+  <Accordion title="Codex">
+    **Direct MCP (fastest, MCP only).** Codex reads MCP servers from `~/.codex/config.toml` as TOML (not JSON). Add:
+
+    ```toml
+    [mcp_servers.mem0]
+    url = "https://mcp.mem0.ai/mcp"
+    bearer_token_env_var = "MEM0_API_KEY"
+    ```
+
+    Export `MEM0_API_KEY` in the shell you launch Codex from, then restart Codex. `codex mcp add` only supports stdio servers, so HTTP servers must be added via `config.toml` directly — or via the **Plugins → Connect to a custom MCP → Streamable HTTP** UI in the Codex app.
+
+    <Note>
+      Codex uses the server name `mem0` (not `mem0-mcp` like the other clients on this page) so it matches the name the bundled plugin registers if you ever sideload it later.
+    </Note>
+
+    **Sideloaded plugin (full experience).** If you want the memory protocol skill, Mem0 SDK skill, and opt-in lifecycle hooks alongside the MCP server, sideload the plugin from a clone of `mem0ai/mem0`. The repo ships a marketplace manifest at `.agents/plugins/marketplace.json`, so you can register it with one CLI call:
+
+    ```bash
+    git clone https://github.com/mem0ai/mem0.git ~/codex-plugins/mem0-source
+    codex plugin marketplace add ~/codex-plugins/mem0-source
+    ```
+
+    Then run `codex` and `/plugins`, browse the **Mem0 Plugins** marketplace, and install **Mem0**. Don't combine this with the Direct MCP setup above — the sideloaded plugin auto-registers `mem0` via `.codex-mcp.json`, so a manual `[mcp_servers.mem0]` block would create a duplicate.
+
+    See the [Codex integration guide](/integrations/codex) for full details, lifecycle-hook setup, and management commands (`codex plugin marketplace upgrade` / `remove`).
+  </Accordion>
+
   <Accordion title="Cursor">
     ```bash
     npx mcp-add \

docs/vibecoding.mdx

@@ -22,13 +22,35 @@ We follow the llms.txt standard:
 
 ## Agent Skills
 
-Teach your coding assistant how to build with Mem0:
+Mem0 ships two kinds of skills for AI coding assistants. Both work with Claude Code, Codex, Cursor, Windsurf, OpenCode, OpenClaw, and any assistant that supports the skills standard.
+
+### Reference skills — always on
+
+Teach your assistant Mem0's SDK surface so it writes correct code in everyday development:
 
 ```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
 ```
 
-Works with Claude Code, Cursor, Windsurf, and any assistant that supports skills. Once installed, your assistant understands Mem0's full API, framework integrations, and common patterns.
+- `mem0` — Python and TypeScript SDKs (Platform + OSS), plus framework integrations (LangChain, CrewAI, OpenAI Agents, LangGraph, LlamaIndex, etc.)
+- `mem0-cli` — terminal workflows for the `mem0` CLI (both Node and Python builds)
+- `mem0-vercel-ai-sdk` — `@mem0/vercel-ai-provider` and `createMem0`
+
+### Pipeline skills — run on demand
+
+Let your assistant execute an end-to-end workflow in an existing repo. Invoked as slash commands:
+
+```bash
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate
+npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration
+```
+
+- `/mem0-integrate` — wire Mem0 into an existing repository using a goal-driven, test-first pipeline. Detects the stack, asks whether to use Platform or OSS, writes failing tests first, and keeps the integration additive and feature-flagged.
+- `/mem0-test-integration` — verify what `/mem0-integrate` produced. Runs the repo's native test suite and a real end-to-end smoke flow against your API key, then produces a scorecard.
+
+See the [skills index](https://github.com/mem0ai/mem0/tree/main/skills) for the full catalog.
 
 ## MCP Server Setup
 

mem0-plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mem0",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search to Claude workflows using the Mem0 Platform MCP server.",
   "author": {
     "name": "Mem0",

mem0-plugin/.codex-mcp.json

@@ -1,7 +1,7 @@
 {
   "mcpServers": {
     "mem0": {
-      "url": "https://mcp.mem0.ai/mcp/",
+      "url": "https://mcp.mem0.ai/mcp",
       "bearer_token_env_var": "MEM0_API_KEY"
     }
   }

mem0-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mem0",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search to Codex workflows using the Mem0 Platform MCP server.",
   "author": {
     "name": "Mem0",

mem0-plugin/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mem0",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search using the Mem0 Platform MCP server.",
   "author": {
     "name": "Mem0",

mem0-plugin/README.md

@@ -49,62 +49,62 @@ This installs the full plugin including the MCP server, lifecycle hooks (automat
 
 ### Codex
 
-**Option A — Repo marketplace** (recommended for teams):
+**Option A — Direct MCP** (fastest, MCP only):
 
-Add the plugin marketplace to your repo root (already included in this repository):
+Codex reads MCP servers from `~/.codex/config.toml` as TOML. Add:
 
-```
-.agents/plugins/marketplace.json
+```toml
+[mcp_servers.mem0]
+url = "https://mcp.mem0.ai/mcp"
+bearer_token_env_var = "MEM0_API_KEY"
 ```
 
-Then in Codex, browse the repo's plugin directory and install Mem0.
+Export `MEM0_API_KEY` in your shell and restart Codex. `codex mcp add` only supports stdio servers, so HTTP servers like Mem0's must be added via `config.toml` directly (or via the **Plugins → Connect to a custom MCP → Streamable HTTP** UI in the Codex app).
 
-**Option B — Personal marketplace**:
+**Option B — Sideload the plugin** (full experience: MCP + skills + opt-in hooks):
 
-Add to `~/.agents/plugins/marketplace.json`:
+Clone the repo and register the bundled marketplace with one CLI call:
 
-```json
-{
-  "name": "mem0-plugins",
-  "interface": {
-    "displayName": "Mem0 Plugins"
-  },
-  "plugins": [
-    {
-      "name": "mem0",
-      "source": {
-        "source": "local",
-        "path": "/path/to/mem0/mem0-plugin"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Productivity"
-    }
-  ]
-}
+```bash
+git clone https://github.com/mem0ai/mem0.git ~/codex-plugins/mem0-source
+codex plugin marketplace add ~/codex-plugins/mem0-source
 ```
 
-**Option C — Manual MCP configuration**:
+This points Codex at the repo's `.agents/plugins/marketplace.json`, which references `mem0-plugin/` as the local source. Restart Codex, run `/plugins`, and install **Mem0** from the **Mem0 Plugins** marketplace.
 
-Add to your Codex MCP config:
+> **Don't combine with Option A.** The plugin manifest auto-registers `mem0` as an MCP server via `mem0-plugin/.codex-mcp.json` — adding a manual `[mcp_servers.mem0]` block would duplicate the registration.
 
-```json
-{
-  "mcpServers": {
-    "mem0": {
-      "type": "http",
-      "url": "https://mcp.mem0.ai/mcp/",
-      "headers": {
-        "Authorization": "Token ${MEM0_API_KEY}"
-      }
-    }
-  }
-}
+**Optional — enable lifecycle hooks.** Codex doesn't auto-wire hooks from plugin manifests; it only reads `~/.codex/hooks.json` (or `<repo>/.codex/hooks.json`) ([docs](https://developers.openai.com/codex/hooks)). Run the bundled installer once to merge Mem0's entries:
+
+```bash
+python3 ~/codex-plugins/mem0-source/mem0-plugin/scripts/install_codex_hooks.py
 ```
 
-This installs the MCP server and the Mem0 SDK skill. Codex uses the skill-based memory protocol instead of lifecycle hooks.
+This merges three entries into `~/.codex/hooks.json` with absolute paths pointing into your clone:
+
+| Event | What it does |
+|-------|--------------|
+| `SessionStart` | Loads prior memories as bootstrap context |
+| `UserPromptSubmit` | Injects relevant memories into the prompt |
+| `Stop` | Reminds the agent to persist learnings at turn end |
+
+Re-running the installer is idempotent (replaces the Mem0 entries rather than duplicating) and preserves any other hooks you have. To remove: `python3 .../install_codex_hooks.py --uninstall`. If you move or delete the clone directory, re-run the installer from the new location — the hooks file stores absolute paths.
+
+Codex hooks also require the `codex_hooks` feature flag in `~/.codex/config.toml`:
+
+```toml
+[features]
+codex_hooks = true
+```
+
+The installer prints a reminder if the flag isn't set. Restart Codex after editing the config.
+
+**Managing the plugin:**
+
+```bash
+codex plugin marketplace upgrade               # pull latest plugin versions
+codex plugin marketplace remove mem0-plugins   # unregister the marketplace
+```
 
 ### Cursor
 
@@ -145,17 +145,43 @@ After installing, confirm the MCP server is connected:
 
 ## What's included
 
-| Component | Claude Code / Cowork | Cursor (Marketplace) | Cursor (Deeplink/Manual) | Codex |
-|-----------|:--------------------:|:--------------------:|:------------------------:|:-----:|
-| MCP Server | Yes | Yes | Yes | Yes |
-| Lifecycle Hooks | Yes | Yes | No | No |
-| Mem0 SDK Skill | Yes | Yes | No | Yes |
-| Memory Protocol Skill | No | No | No | Yes |
+| Component | Claude Code / Cowork | Cursor (Marketplace) | Cursor (Deeplink/Manual) | Codex (Sideload) | Codex (Direct MCP) |
+|-----------|:--------------------:|:--------------------:|:------------------------:|:----------------:|:------------------:|
+| MCP Server | Yes | Yes | Yes | Yes | Yes |
+| Lifecycle Hooks | Yes | Yes | No | Opt-in | No |
+| Mem0 SDK Skill | Yes | Yes | No | Yes | No |
+| Memory Protocol Skill | No | No | No | Yes | No |
 
 - **MCP Server** — Connects to the Mem0 remote MCP server (`mcp.mem0.ai`), providing tools to add, search, update, and delete memories. No local dependencies required.
-- **Lifecycle Hooks** — Automatic memory capture at key points: session start, context compaction, task completion, and session end. (Claude Code/Cursor only)
+- **Lifecycle Hooks** — Automatic memory capture at key points. Claude Code and Cursor wire hooks up natively when the plugin is installed (session start, context compaction, task completion, session end). Codex hooks are opt-in via a one-time installer (`scripts/install_codex_hooks.py`) that writes entries into `~/.codex/hooks.json` for `SessionStart`, `UserPromptSubmit`, and `Stop`.
 - **Mem0 SDK Skill** — Guides the AI on how to integrate the Mem0 SDK (Python & TypeScript) into your applications.
-- **Memory Protocol Skill** — Codex-specific skill that instructs the agent to retrieve relevant memories at task start, store learnings on completion, and capture session state before context loss. Replaces lifecycle hooks on platforms that don't support them.
+- **Memory Protocol Skill** — Codex-specific skill that instructs the agent to retrieve relevant memories at task start, store learnings on completion, and capture session state before context loss. Complements the lifecycle hooks on Codex.
+
+## Updating the plugin
+
+When the plugin updates (new version pulled from the marketplace, or a fresh local install), the MCP server connection in your existing Claude Code / Cursor / Codex session is left holding a stale handle and stops responding. **Restart your client to reconnect:**
+
+- **Claude Code:** run `/restart` in the prompt, or close and reopen the CLI.
+- **Cursor:** quit and relaunch.
+- **Codex:** restart the editor session.
+
+Your `MEM0_API_KEY` doesn't need to be re-entered — the auth header is re-read from your environment on the new session. The plugin's MCP config uses `${MEM0_API_KEY}` interpolation at session start, not at install time, so as long as the env var is set persistently (in your shell profile or `~/.claude/settings.json` `env` block), reconnection is automatic on restart.
+
+If reconnection still fails after a restart, check that `MEM0_API_KEY` is reachable in the new shell (`echo $MEM0_API_KEY`) and confirm you're using a key that starts with `m0-` (from https://app.mem0.ai/dashboard/api-keys, not a legacy token).
+
+## Optional: tune categories for coding workflows
+
+mem0 auto-tags every memory with one or more `categories` from a project-level list. The default list is consumer-oriented (`food`, `hobbies`, `music` …) — useful for chat assistants, less so for code. A one-shot script in this plugin replaces it with a coding-focused taxonomy:
+
+```bash
+# Dry-run first -- prints current vs proposed, no changes:
+python mem0-plugin/scripts/setup_coding_categories.py
+
+# Actually write:
+python mem0-plugin/scripts/setup_coding_categories.py --apply
+```
+
+Requires the `mem0ai` Python SDK (`pip install mem0ai`) and `MEM0_API_KEY` set. New memories will then auto-tag against `architecture_decisions`, `anti_patterns`, `task_learnings`, `tooling_setup`, `bug_fixes`, `coding_conventions`, `user_preferences`. Re-run with a different list any time; `project.update(custom_categories=[...])` always replaces.
 
 ## MCP Tools
 

mem0-plugin/hooks/codex-hooks.json

@@ -0,0 +1,39 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CODEX_PLUGIN_ROOT}/scripts/on_session_start.sh",
+            "statusMessage": "Loading mem0 context..."
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CODEX_PLUGIN_ROOT}/scripts/on_user_prompt.sh",
+            "statusMessage": "Checking memory relevance...",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CODEX_PLUGIN_ROOT}/scripts/on_stop_codex.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

mem0-plugin/hooks/cursor-hooks.json

@@ -15,10 +15,6 @@
     "preCompact": [
       {
         "command": "${CURSOR_PLUGIN_ROOT}/scripts/on_pre_compact.sh"
-      },
-      {
-        "command": "python3 ${CURSOR_PLUGIN_ROOT}/scripts/on_pre_compact.py",
-        "timeout": 30
       }
     ],
     "stop": [

mem0-plugin/hooks/hooks.json

@@ -30,12 +30,6 @@
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/scripts/on_pre_compact.sh",
             "statusMessage": "Preparing pre-compaction summary..."
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/on_pre_compact.py",
-            "statusMessage": "Saving session state to mem0...",
-            "timeout": 30
           }
         ]
       }
@@ -57,7 +51,7 @@
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/scripts/on_user_prompt.sh",
-            "statusMessage": "Searching mem0 memories...",
+            "statusMessage": "Checking memory relevance...",
             "timeout": 5
           }
         ]

mem0-plugin/scripts/_identity.py

@@ -0,0 +1,59 @@
+"""Resolve mem0 user_id with deterministic priority.
+
+Resolution priority:
+  1. MEM0_USER_ID env var (explicit override)
+  2. ~/.mem0/identity.json cache (pinned to current MEM0_API_KEY fingerprint)
+  3. Derived: "mem0-" + sha256(MEM0_API_KEY)[:12]
+  4. Fallback: $USER, else "default"
+
+Same MEM0_API_KEY across machines yields the same user_id, which fixes
+the "47 user buckets per account" symptom from running on multiple
+laptops with different $USER values.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+
+_CACHE_PATH = os.path.expanduser("~/.mem0/identity.json")
+
+
+def resolve_user_id() -> str:
+    explicit = os.environ.get("MEM0_USER_ID", "").strip()
+    if explicit:
+        return explicit
+
+    api_key = os.environ.get("MEM0_API_KEY", "").strip()
+    if api_key:
+        digest = hashlib.sha256(api_key.encode("utf-8")).hexdigest()
+        fingerprint = digest[:8]
+
+        try:
+            with open(_CACHE_PATH, "r") as f:
+                cached = json.load(f)
+            if cached.get("api_key_fingerprint") == fingerprint and cached.get("user_id"):
+                return cached["user_id"]
+        except (OSError, json.JSONDecodeError):
+            pass
+
+        derived = "mem0-" + digest[:12]
+        try:
+            os.makedirs(os.path.dirname(_CACHE_PATH), exist_ok=True)
+            with open(_CACHE_PATH, "w") as f:
+                json.dump(
+                    {
+                        "user_id": derived,
+                        "source": "api_key",
+                        "api_key_fingerprint": fingerprint,
+                        "resolved_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+                    },
+                    f,
+                )
+        except OSError:
+            pass
+        return derived
+
+    return os.environ.get("USER") or "default"

mem0-plugin/scripts/_identity.sh

@@ -0,0 +1,57 @@
+# Source this file. Sets MEM0_RESOLVED_USER_ID.
+#
+# Resolution priority:
+#   1. MEM0_USER_ID env var (explicit override)
+#   2. ~/.mem0/identity.json cache (pinned to current MEM0_API_KEY fingerprint)
+#   3. Derived: "mem0-" + sha256(MEM0_API_KEY)[:12]
+#   4. Fallback: $USER, else "default"
+#
+# Same MEM0_API_KEY across machines yields the same user_id, which fixes
+# the "47 user buckets per account" symptom from running on multiple
+# laptops with different $USER values.
+
+_mem0_sha256() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum | cut -d' ' -f1
+  else
+    shasum -a 256 | cut -d' ' -f1
+  fi
+}
+
+_mem0_resolve_identity() {
+  if [ -n "${MEM0_USER_ID:-}" ]; then
+    printf '%s' "$MEM0_USER_ID"
+    return
+  fi
+
+  local api_key="${MEM0_API_KEY:-}"
+  local cache="$HOME/.mem0/identity.json"
+
+  if [ -n "$api_key" ]; then
+    local digest
+    digest=$(printf '%s' "$api_key" | _mem0_sha256)
+    local fp="${digest:0:8}"
+
+    if [ -f "$cache" ]; then
+      local cached_fp cached_id
+      cached_fp=$(jq -r '.api_key_fingerprint // ""' "$cache" 2>/dev/null)
+      cached_id=$(jq -r '.user_id // ""' "$cache" 2>/dev/null)
+      if [ "$cached_fp" = "$fp" ] && [ -n "$cached_id" ]; then
+        printf '%s' "$cached_id"
+        return
+      fi
+    fi
+
+    local derived="mem0-${digest:0:12}"
+    mkdir -p "$HOME/.mem0" 2>/dev/null && \
+      printf '{"user_id":"%s","source":"api_key","api_key_fingerprint":"%s","resolved_at":"%s"}\n' \
+        "$derived" "$fp" "$(date -u +%FT%TZ)" > "$cache" 2>/dev/null
+    printf '%s' "$derived"
+    return
+  fi
+
+  printf '%s' "${USER:-default}"
+}
+
+MEM0_RESOLVED_USER_ID="$(_mem0_resolve_identity)"
+export MEM0_RESOLVED_USER_ID

mem0-plugin/scripts/block_memory_write.sh

@@ -13,6 +13,10 @@
 
 set -euo pipefail
 
+if [ -n "${MEM0_DEBUG:-}" ]; then
+  mkdir -p "$HOME/.mem0" && exec 2>>"$HOME/.mem0/hooks.log"
+fi
+
 INPUT=$(cat)
 
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""' 2>/dev/null || echo "")
@@ -22,7 +26,7 @@ if [ -z "$FILE_PATH" ]; then
 fi
 
 case "$FILE_PATH" in
-  */MEMORY.md|*/memory/*.md|*/.claude/*/memory/*)
+  */MEMORY.md|*/.claude/memory/*)
     echo "BLOCKED: Do not write to $FILE_PATH. Use the mem0 MCP \`add_memory\` tool instead to persist memories. This project uses mem0 for all memory storage." >&2
     exit 2
     ;;

mem0-plugin/scripts/capture_compact_summary.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Capture the post-compaction summary into mem0.
+
+PreCompact hooks fire BEFORE the summary is generated, so they can't
+store the actual compact-summary text. This script runs at
+SessionStart with source=compact, reads the transcript, finds the
+most recent entry flagged isCompactSummary=true, and stores it as a
+memory tagged metadata.type=compact_summary.
+
+Input:  JSON on stdin with transcript_path, session_id, source
+Output: stderr logs only (exit 0 always -- must not block)
+
+Spawned in the background by on_session_start.sh; the user-facing
+bootstrap text continues without waiting on the network.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+import urllib.error
+import urllib.request
+from datetime import date, timedelta
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from _identity import resolve_user_id
+
+log = logging.getLogger("mem0-compact-summary")
+log.setLevel(logging.DEBUG)
+_handler = logging.StreamHandler(sys.stderr)
+_handler.setFormatter(logging.Formatter("[mem0-compact-summary] %(message)s"))
+log.addHandler(_handler)
+
+if os.environ.get("MEM0_DEBUG"):
+    _log_dir = os.path.expanduser("~/.mem0")
+    try:
+        os.makedirs(_log_dir, exist_ok=True)
+        _file_handler = logging.FileHandler(os.path.join(_log_dir, "hooks.log"))
+        _file_handler.setFormatter(logging.Formatter("[mem0-compact-summary] %(asctime)s %(message)s"))
+        log.addHandler(_file_handler)
+    except OSError:
+        pass
+
+API_URL = "https://api.mem0.ai"
+MAX_TAIL_LINES = 2000
+MAX_SUMMARY_CHARS = 50000
+# Compact summaries describe a single session's state -- stale after a quarter.
+COMPACT_SUMMARY_EXPIRY_DAYS = 90
+
+
+def tail_lines(filepath: str, n: int) -> list[str]:
+    try:
+        with open(filepath, "rb") as f:
+            f.seek(0, 2)
+            file_size = f.tell()
+            if file_size == 0:
+                return []
+            chunk_size = min(file_size, n * 4096)
+            f.seek(max(0, file_size - chunk_size))
+            data = f.read().decode("utf-8", errors="replace")
+            return data.splitlines()[-n:]
+    except OSError:
+        return []
+
+
+def find_compact_summary(lines: list[str]) -> str:
+    """Walk transcript backwards, return text content of the most recent
+    entry flagged isCompactSummary=true. Empty string if none found."""
+    for line in reversed(lines):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            entry = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not entry.get("isCompactSummary"):
+            continue
+
+        message = entry.get("message", {})
+        content = message.get("content", [])
+        if isinstance(content, str):
+            return content[:MAX_SUMMARY_CHARS]
+        if isinstance(content, list):
+            parts = []
+            for block in content:
+                if isinstance(block, str):
+                    parts.append(block)
+                elif isinstance(block, dict) and block.get("type") == "text":
+                    parts.append(block.get("text", ""))
+            return "\n".join(parts).strip()[:MAX_SUMMARY_CHARS]
+    return ""
+
+
+def store_summary(api_key: str, summary: str, user_id: str, session_id: str) -> bool:
+    expires = (date.today() + timedelta(days=COMPACT_SUMMARY_EXPIRY_DAYS)).isoformat()
+    body = {
+        "messages": [{"role": "user", "content": summary}],
+        "user_id": user_id,
+        "metadata": {
+            "type": "compact_summary",
+            "source": "session-start-compact",
+            "session_id": session_id,
+        },
+        "infer": False,
+        "expiration_date": expires,
+    }
+
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        f"{API_URL}/v1/memories/",
+        data=data,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Token {api_key}",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            if resp.status in (200, 201):
+                log.info("Compact summary stored")
+                return True
+            log.warning("API returned status %d", resp.status)
+            return False
+    except urllib.error.URLError as e:
+        log.warning("API call failed: %s", e)
+        return False
+
+
+def main():
+    api_key = os.environ.get("MEM0_API_KEY", "")
+    if not api_key:
+        log.debug("MEM0_API_KEY not set, skipping capture")
+        return
+
+    try:
+        hook_input = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, OSError):
+        log.debug("No valid JSON on stdin")
+        return
+
+    transcript_path = hook_input.get("transcript_path", "")
+    if not transcript_path:
+        log.debug("No transcript_path provided")
+        return
+
+    session_id = hook_input.get("session_id", "")
+    user_id = resolve_user_id()
+
+    lines = tail_lines(transcript_path, MAX_TAIL_LINES)
+    if not lines:
+        log.debug("Transcript empty or unreadable: %s", transcript_path)
+        return
+
+    summary = find_compact_summary(lines)
+    if not summary:
+        log.debug("No isCompactSummary entry found")
+        return
+
+    log.info("Capturing compact summary (%d chars)", len(summary))
+    store_summary(api_key, summary, user_id, session_id)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        log.error("Unexpected error: %s", e)
+    sys.exit(0)

mem0-plugin/scripts/install_codex_hooks.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Install Mem0 lifecycle hooks into ~/.codex/hooks.json.
+
+Codex discovers hooks only at ~/.codex/hooks.json or <repo>/.codex/hooks.json,
+and has no plugin-host mechanism for auto-wiring hooks from an installed
+plugin. This installer reads the template at hooks/codex-hooks.json, rewrites
+the ${CODEX_PLUGIN_ROOT} placeholder to the absolute install path of this
+plugin, then merges the entries into ~/.codex/hooks.json.
+
+Re-running is idempotent: existing Mem0 entries (identified by the plugin
+directory name in the command string) are removed before fresh entries are
+added, so upgrades don't leave duplicates.
+
+Usage:
+  python3 install_codex_hooks.py            # install or update
+  python3 install_codex_hooks.py --uninstall   # remove Mem0 entries
+
+After installing, Codex requires the hooks feature flag in ~/.codex/config.toml:
+
+  [features]
+  codex_hooks = true
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+PLUGIN_ROOT = SCRIPT_DIR.parent
+
+CODEX_DIR = Path.home() / ".codex"
+HOOKS_FILE = CODEX_DIR / "hooks.json"
+CONFIG_FILE = CODEX_DIR / "config.toml"
+
+TEMPLATE_FILE = PLUGIN_ROOT / "hooks" / "codex-hooks.json"
+
+# Substring we look for when identifying entries this installer owns.
+# Matches the plugin directory name, which stays stable across install paths.
+OWNER_MARKER = "mem0-plugin"
+
+
+def load_template() -> dict:
+    raw = TEMPLATE_FILE.read_text()
+    raw = raw.replace("${CODEX_PLUGIN_ROOT}", str(PLUGIN_ROOT))
+    return json.loads(raw)
+
+
+def load_existing() -> dict:
+    if not HOOKS_FILE.exists():
+        return {"hooks": {}}
+    try:
+        return json.loads(HOOKS_FILE.read_text())
+    except (json.JSONDecodeError, OSError) as e:
+        print(f"error: failed to read {HOOKS_FILE}: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def is_owned_entry(entry: dict) -> bool:
+    for hook in entry.get("hooks", []):
+        if OWNER_MARKER in hook.get("command", ""):
+            return True
+    return False
+
+
+def strip_owned_entries(config: dict) -> dict:
+    hooks = config.get("hooks", {}) or {}
+    for event in list(hooks.keys()):
+        hooks[event] = [e for e in hooks[event] if not is_owned_entry(e)]
+        if not hooks[event]:
+            del hooks[event]
+    config["hooks"] = hooks
+    return config
+
+
+def merge_template(config: dict, template: dict) -> dict:
+    hooks = config.setdefault("hooks", {})
+    for event, entries in template.get("hooks", {}).items():
+        hooks.setdefault(event, []).extend(entries)
+    return config
+
+
+def write_config(config: dict) -> None:
+    CODEX_DIR.mkdir(parents=True, exist_ok=True)
+    HOOKS_FILE.write_text(json.dumps(config, indent=2) + "\n")
+
+
+def feature_flag_enabled() -> bool:
+    if not CONFIG_FILE.exists():
+        return False
+    content = CONFIG_FILE.read_text()
+    for line in content.splitlines():
+        stripped = line.split("#", 1)[0].strip().replace(" ", "")
+        if stripped == "codex_hooks=true":
+            return True
+    return False
+
+
+def print_feature_flag_hint() -> None:
+    print()
+    print("Codex hooks feature flag is not enabled.")
+    print(f"Add this to {CONFIG_FILE}:")
+    print()
+    print("  [features]")
+    print("  codex_hooks = true")
+    print()
+    print("Then restart Codex.")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Install or remove Mem0 Codex hooks.")
+    parser.add_argument(
+        "--uninstall",
+        action="store_true",
+        help="Remove Mem0 entries from ~/.codex/hooks.json and exit.",
+    )
+    args = parser.parse_args()
+
+    config = load_existing()
+
+    if args.uninstall:
+        config = strip_owned_entries(config)
+        write_config(config)
+        print(f"Removed Mem0 hooks from {HOOKS_FILE}")
+        return 0
+
+    if not TEMPLATE_FILE.exists():
+        print(f"error: template not found at {TEMPLATE_FILE}", file=sys.stderr)
+        return 1
+
+    template = load_template()
+    config = strip_owned_entries(config)
+    config = merge_template(config, template)
+    write_config(config)
+
+    print(f"Installed Mem0 hooks into {HOOKS_FILE}")
+    print(f"Plugin path: {PLUGIN_ROOT}")
+    print("Events: SessionStart, UserPromptSubmit, Stop")
+
+    if not feature_flag_enabled():
+        print_feature_flag_hint()
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mem0-plugin/scripts/on_pre_compact.py

@@ -18,8 +18,12 @@ import json
 import logging
 import os
 import sys
-import urllib.request
 import urllib.error
+import urllib.request
+from datetime import date, timedelta
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from _identity import resolve_user_id
 
 log = logging.getLogger("mem0-capture")
 log.setLevel(logging.DEBUG)
@@ -27,11 +31,25 @@ _handler = logging.StreamHandler(sys.stderr)
 _handler.setFormatter(logging.Formatter("[mem0-capture] %(message)s"))
 log.addHandler(_handler)
 
+if os.environ.get("MEM0_DEBUG"):
+    _log_dir = os.path.expanduser("~/.mem0")
+    try:
+        os.makedirs(_log_dir, exist_ok=True)
+        _file_handler = logging.FileHandler(os.path.join(_log_dir, "hooks.log"))
+        _file_handler.setFormatter(logging.Formatter("[mem0-capture] %(asctime)s %(message)s"))
+        log.addHandler(_file_handler)
+    except OSError:
+        pass
+
 API_URL = "https://api.mem0.ai"
 MAX_TAIL_LINES = 500
 MAX_USER_MESSAGES = 30
 MAX_BASH_COMMANDS = 20
 MAX_ASSISTANT_TEXT = 10000
+# session_state captures churn fast (active codebase, files in flight). Past
+# ~3 months they're stale noise. Durable facts (decisions, conventions) are
+# stored separately by the agent without an expiration_date.
+SESSION_STATE_EXPIRY_DAYS = 90
 
 
 def tail_lines(filepath: str, n: int) -> list[str]:
@@ -149,8 +167,9 @@ def build_content(state: dict, source: str) -> str:
     return "\n".join(parts)
 
 
-def store_memory(api_key: str, content: str, user_id: str, source: str) -> bool:
+def store_memory(api_key: str, content: str, user_id: str, source: str, session_id: str = "") -> bool:
     """Store session state as a memory via the Mem0 REST API."""
+    expires = (date.today() + timedelta(days=SESSION_STATE_EXPIRY_DAYS)).isoformat()
     body = {
         "messages": [
             {"role": "user", "content": content}
@@ -159,7 +178,9 @@ def store_memory(api_key: str, content: str, user_id: str, source: str) -> bool:
         "metadata": {
             "type": "session_state",
             "source": source,
+            "session_id": session_id,
         },
+        "expiration_date": expires,
     }
 
     data = json.dumps(body).encode("utf-8")
@@ -207,7 +228,8 @@ def main():
         log.debug("No transcript_path provided")
         return
 
-    user_id = os.environ.get("MEM0_USER_ID", os.environ.get("USER", "default"))
+    session_id = hook_input.get("session_id", "")
+    user_id = resolve_user_id()
 
     lines = tail_lines(transcript_path, MAX_TAIL_LINES)
     if not lines:
@@ -228,7 +250,7 @@ def main():
         len(state["bash_commands"]),
     )
 
-    store_memory(api_key, content, user_id, source)
+    store_memory(api_key, content, user_id, source, session_id)
 
 
 if __name__ == "__main__":

mem0-plugin/scripts/on_pre_compact.sh

@@ -5,12 +5,16 @@
 # the full context before it gets compressed.
 #
 # Output: Text instructions injected into Claude's context.
-# Claude still has the full conversation and can write an accurate summary.
-# A companion Python script (on_pre_compact.py) also runs to capture
-# transcript state directly via the Mem0 REST API as a safety net.
+# Claude still has the full conversation and can write an accurate summary,
+# which it stores via add_memory(infer=False) so the platform preserves
+# the structure verbatim instead of running a second extraction pass.
 
 set -euo pipefail
 
+if [ -n "${MEM0_DEBUG:-}" ]; then
+  mkdir -p "$HOME/.mem0" && exec 2>>"$HOME/.mem0/hooks.log"
+fi
+
 cat <<'EOF'
 ## CRITICAL: Pre-Compaction Session Summary
 
@@ -18,7 +22,9 @@ Context compaction is about to happen. You are about to lose most of your conver
 
 ### Step 1: Store session summary
 
-Call `add_memory` with a thorough summary covering ALL of the following:
+Call `add_memory` with `infer=False` and a thorough summary covering ALL of the following.
+
+`infer=False` is critical here: you've already done the extraction work yourself using full context. Without it, the platform runs a second LLM pass that loses your structure and pulls fragmented facts. With it, your summary is preserved verbatim.
 
 ```
 ## Session Summary (Pre-Compaction)
@@ -44,11 +50,19 @@ Call `add_memory` with a thorough summary covering ALL of the following:
 the post-compaction agent continue without asking redundant questions]
 ```
 
-Include metadata: `{"type": "session_state", "source": "pre-compaction"}`
+Tool call shape:
+```
+add_memory(
+  messages=[{"role":"user","content":"<the summary above>"}],
+  user_id="<the active user_id from the SessionStart bootstrap>",
+  metadata={"type":"session_state","source":"pre-compaction"},
+  infer=False,
+)
+```
 
 ### Step 2: Store any unstored learnings
 
-If there are learnings from this session that you haven't stored yet, store them as separate memories:
+If there are learnings from this session that you haven't stored yet, store them as separate memories with `infer=False` (same reasoning -- you've already extracted the fact, don't re-extract):
 - Failed approaches -> metadata `{"type": "anti_pattern"}`
 - Successful strategies -> metadata `{"type": "task_learning"}`
 - Architecture decisions -> metadata `{"type": "decision"}`

mem0-plugin/scripts/on_session_start.sh

@@ -11,9 +11,34 @@
 # even if jq is missing or stdin is malformed.
 set -uo pipefail
 
+if [ -n "${MEM0_DEBUG:-}" ]; then
+  mkdir -p "$HOME/.mem0" && exec 2>>"$HOME/.mem0/hooks.log"
+fi
+
+# Skip the bootstrap entirely if no API key is configured -- the agent
+# would otherwise be told to call mem0 MCP tools that will all fail.
+if [ -z "${MEM0_API_KEY:-}" ]; then
+  exit 0
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=_identity.sh
+. "$SCRIPT_DIR/_identity.sh"
+
 INPUT=$(cat)
 SOURCE=$(echo "$INPUT" | jq -r '.source // "startup"' 2>/dev/null || echo "startup")
 
+# Identity line is emitted before every bootstrap variant so the agent
+# uses the same user_id the hooks resolved. Without this, the agent's
+# search_memories/add_memory MCP calls may bind to a different bucket
+# than what the hooks write to.
+echo "## Mem0 Identity"
+echo ""
+echo "Active user_id: \`$MEM0_RESOLVED_USER_ID\`"
+echo ""
+echo "Always include \`{\"user_id\": \"$MEM0_RESOLVED_USER_ID\"}\` (wrapped in an \`AND\` clause) in every \`search_memories\` filter and as \`user_id\` on every \`add_memory\` call. This keeps memories under one bucket regardless of which machine you're on."
+echo ""
+
 if [ "$SOURCE" = "startup" ]; then
   cat <<'EOF'
 ## Mem0 Session Bootstrap
@@ -40,14 +65,22 @@ Continue where you left off.
 EOF
 
 elif [ "$SOURCE" = "compact" ]; then
+  # Capture the just-generated compact summary in the background.
+  # PreCompact fires too early to see this entry; SessionStart-compact
+  # is the first place isCompactSummary=true is in the transcript.
+  echo "$INPUT" | python3 "$SCRIPT_DIR/capture_compact_summary.py" 2>/dev/null &
+
   cat <<'EOF'
 ## Mem0 Post-Compaction Recovery
 
-Context was just compacted. You may have lost important session context.
+Context was just compacted. The Claude Code-generated compact summary
+is being captured to mem0 in the background as `metadata.type=compact_summary`.
 
-1. Call `search_memories` with queries related to what you were working on to reload relevant knowledge.
-2. Check for any session state memories that were saved before compaction.
-3. Continue working based on the recovered context.
+1. Call `search_memories` to reload context, layering up to three angles:
+   - `metadata.type=session_state` -- the rich pre-compaction summary you wrote
+   - `metadata.type=compact_summary` -- the platform-generated condensed summary just now
+   - `metadata.type=decision` / `anti_pattern` -- specific facts you stored during the session
+2. Continue working from the recovered context.
 EOF
 fi
 

mem0-plugin/scripts/on_stop.sh

@@ -12,6 +12,10 @@
 
 set -euo pipefail
 
+if [ -n "${MEM0_DEBUG:-}" ]; then
+  mkdir -p "$HOME/.mem0" && exec 2>>"$HOME/.mem0/hooks.log"
+fi
+
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
 INPUT=$(cat)

mem0-plugin/scripts/on_stop_codex.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Hook: Stop (Codex)
+#
+# Fires when Codex finishes a turn. Reminds the agent to persist any
+# important learnings via the mem0 MCP tools before the turn closes.
+#
+# Input:  JSON on stdin with session_id, turn_id, stop_hook_active,
+#         last_assistant_message, transcript_path, cwd,
+#         hook_event_name, model
+# Output: JSON on stdout (Codex rejects plain text on Stop).
+#         - stop_hook_active=true  -> {"continue": true}  (let the turn end)
+#         - stop_hook_active=false -> {"decision":"block","reason":"..."}
+#           (continue the turn with the reminder as context)
+#
+# We must respect stop_hook_active or we'd loop forever: every "block"
+# reopens the turn, which triggers Stop again when the agent settles.
+
+set -uo pipefail
+
+if [ -n "${MEM0_DEBUG:-}" ]; then
+  mkdir -p "$HOME/.mem0" && exec 2>>"$HOME/.mem0/hooks.log"
+fi
+
+INPUT=$(cat)
+STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null || echo "false")
+
+if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
+  printf '{"continue":true}\n'
+  exit 0
+fi
+
+REASON=$(cat <<'EOF'
+Before finishing, check if there are important learnings from this interaction that should be persisted using the mem0 `add_memory` tool:
+
+1. Were any significant decisions made? -> Store with metadata `{"type": "decision"}`
+2. Were any new patterns or strategies discovered? -> Store with metadata `{"type": "task_learning"}`
+3. Did any approach fail? -> Store with metadata `{"type": "anti_pattern"}`
+4. Did you learn anything about the user's preferences? -> Store with metadata `{"type": "user_preference"}`
+5. Were there environment/setup discoveries? -> Store with metadata `{"type": "environmental"}`
+
+Memories can be as detailed as needed — include full context, reasoning, code snippets, file paths, and examples. Longer, searchable memories are more valuable than vague one-liners.
+
+If nothing notable happened in this interaction, it's fine to skip. Only store genuinely useful learnings.
+EOF
+)
+
+jq -cn --arg reason "$REASON" '{decision:"block", reason:$reason}'
+exit 0

mem0-plugin/scripts/on_task_completed.sh

@@ -9,6 +9,10 @@
 
 set -euo pipefail
 
+if [ -n "${MEM0_DEBUG:-}" ]; then
+  mkdir -p "$HOME/.mem0" && exec 2>>"$HOME/.mem0/hooks.log"
+fi
+
 INPUT=$(cat)
 TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject // "unknown task"' 2>/dev/null || echo "unknown task")
 

mem0-plugin/scripts/on_user_prompt.sh

@@ -1,61 +1,72 @@
 #!/usr/bin/env bash
 # Hook: UserPromptSubmit
 #
-# Fires on every user message. Searches mem0 for relevant memories
-# and injects them into Claude's context before processing.
+# Fires on every user message. Instead of pre-searching mem0 with the
+# raw prompt, this injects a decision rubric telling the agent when
+# and how to search itself. The agent has more context than this
+# script does -- let it decide.
 #
-# Input:  JSON on stdin with prompt, session_id, cwd, transcript_path
-# Output: Matching memories as context text (exit 0)
-#
-# Skips search for very short prompts (< 20 chars) and when
-# MEM0_API_KEY is not set. Uses a 3s timeout to minimize latency.
+# Input:  JSON on stdin (prompt, session_id, cwd, transcript_path)
+# Output: Decision rubric injected into Claude's context (exit 0)
 
-# Intentionally omit -e so the script always exits 0 even if
-# curl or jq fail — must never block the user's prompt.
+# Intentionally omit -e so the script always exits 0 even if jq fails --
+# must never block the user's prompt.
 set -uo pipefail
 
+if [ -n "${MEM0_DEBUG:-}" ]; then
+  mkdir -p "$HOME/.mem0" && exec 2>>"$HOME/.mem0/hooks.log"
+fi
+
 INPUT=$(cat)
 PROMPT=$(echo "$INPUT" | jq -r '.prompt // ""' 2>/dev/null || echo "")
 
-# Skip trivial prompts — not worth a network call
+# Acknowledgements and short replies don't warrant memory context
 if [ ${#PROMPT} -lt 20 ]; then
   exit 0
 fi
 
-API_KEY="${MEM0_API_KEY:-}"
-if [ -z "$API_KEY" ]; then
+# No API key means the agent can't search anyway
+if [ -z "${MEM0_API_KEY:-}" ]; then
   exit 0
 fi
 
-USER_ID="${MEM0_USER_ID:-${USER:-default}}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=_identity.sh
+. "$SCRIPT_DIR/_identity.sh"
+USER_ID="$MEM0_RESOLVED_USER_ID"
 
-# Build request body safely via jq to avoid injection
-BODY=$(jq -n --arg query "$PROMPT" --arg user_id "$USER_ID" \
-  '{query: $query, filters: {user_id: $user_id}, top_k: 5}')
+cat <<EOF
+## Memory check
 
-# Search mem0 for memories relevant to this prompt
-RESPONSE=$(curl -s --max-time 3 \
-  -X POST "https://api.mem0.ai/v2/memories/search/" \
-  -H "Authorization: Token $API_KEY" \
-  -H "Content-Type: application/json" \
-  -d "$BODY" \
-  2>/dev/null || echo "")
+Before responding, decide whether persistent memory context from mem0 would
+improve your answer. The agent -- not this hook -- owns this decision.
 
-if [ -z "$RESPONSE" ]; then
-  exit 0
-fi
+**Search WHEN** the user:
+- references past work, decisions, or things "we" built
+- asks "how should we...", "best way to...", or any decision-style question
+- hits an error, bug, or asks for debugging help
+- requests work that touches their stack, tools, conventions, or preferences
+- starts a non-trivial task in a known project
 
-# Extract memories from response (API returns a flat array)
-MEMORIES=$(echo "$RESPONSE" | jq -r '
-  if type == "array" then . else .results // [] end |
-  if length == 0 then empty else
-  "## Relevant memories from mem0\n\n" +
-  (map(select(.memory != null) | "- " + .memory) | join("\n"))
-  end
-' 2>/dev/null || echo "")
+**Skip WHEN:**
+- the prompt is an acknowledgement or continuation
+- the user is *stating* new info -- that's a write trigger (\`add_memory\`), not a search
+- it's a pure syntax / factual question answerable from general knowledge
+- you already searched this scope earlier in the turn
 
-if [ -n "$MEMORIES" ]; then
-  echo "$MEMORIES"
-fi
+**If searching, do it well:**
+- Run **2-4 parallel** \`search_memories\` calls with different angles, not one
+  query that echoes the user's prompt.
+- Phrase queries as **nouns** ("auth module decisions"), not full sentences.
+- Filter shape: the root must be a logical operator (\`AND\` / \`OR\` / \`NOT\`)
+  with an array, and metadata uses a **nested** object (not dotted keys).
+  Combine \`user_id\` with one \`metadata.type\` clause per call:
+  - \`{"AND": [{"user_id": "$USER_ID"}, {"metadata": {"type": "decision"}}]}\` -- design / architecture
+  - \`{"AND": [{"user_id": "$USER_ID"}, {"metadata": {"type": "anti_pattern"}}]}\` -- debugging, error handling
+  - \`{"AND": [{"user_id": "$USER_ID"}, {"metadata": {"type": "user_preference"}}]}\` -- tooling, stack, style
+  - \`{"AND": [{"user_id": "$USER_ID"}, {"metadata": {"type": "convention"}}]}\` -- established patterns
+- Or scope with just \`{"AND": [{"user_id": "$USER_ID"}]}\` when no metadata filter fits.
+- Empty results are normal -- proceed without context.
+EOF
 
 exit 0

mem0-plugin/scripts/setup_coding_categories.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Replace mem0's default category taxonomy with one tuned for coding workflows.
+
+mem0 auto-tags every memory with one or more `categories`. By default the list
+is consumer-oriented (food, hobbies, music, ...), which is meaningless for code.
+This script replaces the project's category list with a coding-focused one.
+
+The change is project-level (per the platform docs, per-request overrides are
+not supported on the managed API). Run once per project; future memories will
+be tagged using the new list automatically.
+
+Usage:
+  python setup_coding_categories.py            # dry-run: show current vs proposed, no changes
+  python setup_coding_categories.py --apply    # actually call project.update()
+
+Requires the mem0ai Python SDK and MEM0_API_KEY to be set.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+CODING_CATEGORIES = [
+    {
+        "architecture_decisions": (
+            "Design choices, system structure, technology selection, trade-offs evaluated, "
+            "and architectural patterns adopted in the project."
+        )
+    },
+    {
+        "anti_patterns": (
+            "Approaches that failed, debugging dead-ends, common mistakes to avoid, "
+            "and lessons learned from things that didn't work."
+        )
+    },
+    {
+        "task_learnings": (
+            "Strategies and approaches that succeeded for specific tasks, including tooling "
+            "tricks, workflow shortcuts, and effective problem-solving patterns."
+        )
+    },
+    {
+        "tooling_setup": (
+            "Development environment, build tools, dependencies, package managers, deploy "
+            "pipelines, and configuration steps for the project."
+        )
+    },
+    {
+        "bug_fixes": (
+            "Specific bug fixes with root cause analysis, the fix applied, and how the bug "
+            "was diagnosed -- useful for recognising similar issues later."
+        )
+    },
+    {
+        "coding_conventions": (
+            "Code style, naming patterns, file organisation, error-handling conventions, "
+            "and team agreements about how code is written in this project."
+        )
+    },
+    {
+        "user_preferences": (
+            "User's stated preferences for tools, libraries, languages, formatting, "
+            "and ways of working."
+        )
+    },
+]
+
+
+def _print_categories(label: str, cats):
+    print(f"=== {label} ===")
+    if cats:
+        print(json.dumps(cats, indent=2))
+    else:
+        print("(none / using mem0 defaults)")
+    print()
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument(
+        "--apply",
+        action="store_true",
+        help="Actually call project.update(). Without this flag, runs in dry-run mode.",
+    )
+    args = ap.parse_args()
+
+    if not os.environ.get("MEM0_API_KEY"):
+        print("ERROR: MEM0_API_KEY is not set. Export it and try again.", file=sys.stderr)
+        return 1
+
+    try:
+        from mem0 import MemoryClient
+    except ImportError:
+        print(
+            "ERROR: the mem0ai Python SDK is not installed.\n"
+            "Install with: pip install mem0ai\n"
+            "Then re-run this script.",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        client = MemoryClient()
+    except Exception as e:
+        print(
+            f"ERROR initialising MemoryClient: {e}\n"
+            "Most commonly this is an invalid MEM0_API_KEY -- check the key at "
+            "https://app.mem0.ai/dashboard/api-keys",
+            file=sys.stderr,
+        )
+        return 1
+
+    try:
+        current = client.project.get(fields=["custom_categories"])
+        current_cats = current.get("custom_categories") if isinstance(current, dict) else None
+    except Exception as e:
+        print(f"ERROR fetching current categories: {e}", file=sys.stderr)
+        return 1
+
+    _print_categories("Current project categories", current_cats)
+    _print_categories("Proposed coding categories", CODING_CATEGORIES)
+
+    if not args.apply:
+        print("Dry-run only -- no changes made. Re-run with --apply to write.")
+        return 0
+
+    print("Applying coding categories...")
+    try:
+        response = client.project.update(custom_categories=CODING_CATEGORIES)
+    except Exception as e:
+        print(f"ERROR applying update: {e}", file=sys.stderr)
+        return 1
+
+    print("Done.", response if response else "")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mem0-plugin/skills/mem0-codex/SKILL.md

@@ -1,62 +0,0 @@
----
-name: mem0-codex
-description: >
-  Mem0 persistent memory integration for Codex. Automatically retrieve relevant
-  memories at the start of each task, store key learnings when tasks complete,
-  and capture session state before context is lost. Use the mem0 MCP tools
-  (add_memory, search_memories, get_memories, etc.) for all memory operations.
----
-
-# Mem0 Memory Protocol for Codex
-
-You have access to persistent memory via the mem0 MCP tools. Follow this protocol to maintain context across sessions.
-
-## On every new task
-
-1. Call `search_memories` with a query related to the current task or project to load relevant context.
-2. Review returned memories to understand what has been learned in prior sessions.
-3. If appropriate, call `get_memories` to browse all stored memories for this user.
-
-## After completing significant work
-
-Extract key learnings and store them using the `add_memory` tool:
-
-- **Decisions made** -> Include metadata `{"type": "decision"}`
-- **Strategies that worked** -> Include metadata `{"type": "task_learning"}`
-- **Failed approaches** -> Include metadata `{"type": "anti_pattern"}`
-- **User preferences observed** -> Include metadata `{"type": "user_preference"}`
-- **Environment/setup discoveries** -> Include metadata `{"type": "environmental"}`
-- **Conventions established** -> Include metadata `{"type": "convention"}`
-
-Memories can be as detailed as needed -- include full context, reasoning, code snippets, file paths, and examples. Longer, searchable memories are more valuable than vague one-liners.
-
-## Before losing context
-
-If context is about to be compacted or the session is ending, store a comprehensive session summary:
-
-```
-## Session Summary
-
-### User's Goal
-[What the user originally asked for]
-
-### What Was Accomplished
-[Numbered list of tasks completed]
-
-### Key Decisions Made
-[Architectural choices, trade-offs discussed]
-
-### Files Created or Modified
-[Important file paths with what changed]
-
-### Current State
-[What is in progress, pending items, next steps]
-```
-
-Include metadata: `{"type": "session_state"}`
-
-## Memory hygiene
-
-- Do NOT write to MEMORY.md or any file-based memory. Use mem0 MCP tools exclusively.
-- Only store genuinely useful learnings. Skip trivial interactions.
-- Use specific, searchable language in memory content.

mem0-plugin/skills/mem0-mcp/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: mem0-mcp
+description: >
+  Mem0 memory protocol for agents using the mem0 MCP tools (Claude Code, Cursor,
+  Codex, and any other MCP-aware runtime). Decide deliberately when memory context
+  would help, run targeted searches with metadata filters when it would, and store
+  key learnings as work completes. Use the mem0 MCP tools (add_memory,
+  search_memories, get_memories, etc.) for all memory operations.
+---
+
+# Mem0 MCP Memory Protocol
+
+You have access to persistent memory via the mem0 MCP tools. Follow this protocol to maintain context across sessions.
+
+## On every new task
+
+Decide whether persistent memory context would improve your response, then act accordingly. Don't search by default — search deliberately.
+
+### Decide: search or skip?
+
+**Search WHEN** the user:
+- references past work, decisions, or things "we" built
+- asks "how should we...", "best way to...", or any decision-style question
+- hits an error, bug, or asks for debugging help
+- requests work that touches their stack, tools, conventions, or preferences
+- starts a non-trivial task in a known project
+
+**Skip WHEN:**
+- the prompt is an acknowledgement or continuation ("ok", "thanks", "continue")
+- the user is *stating* new info — that's a write trigger (`add_memory`), not a search
+- it's a pure syntax / factual question answerable from general knowledge
+- you already searched this scope earlier in the turn
+
+Empty results are normal. Proceed without context — they don't mean the system is broken.
+
+### How to search well
+
+When you do search, run **2–4 parallel** `search_memories` calls at different angles instead of one query echoing the user's prompt.
+
+**Query phrasing:**
+- Use **nouns**, not sentences. `"auth module decisions"` beats `"what did we decide about auth"`.
+- Strip conversational filler. *"remember when we picked Postgres?"* → search `"Postgres choice"`.
+- Use entity names, not pronouns. Resolve "that thing" from recent context first.
+- Don't search on meta-questions ("what was that?") — use recent context or `get_memories` ordered by `created_at`.
+
+**Metadata filters** match the same `type` values written under "After completing significant work" below.
+
+Two rules from the v2 filter spec:
+
+1. The root **must** be a logical operator (`AND` / `OR` / `NOT`) with an array. A bare `{"user_id": "..."}` won't work.
+2. Metadata uses a **nested** object, not a dotted key. `{"metadata": {"type": "decision"}}`, never `{"metadata.type": "decision"}`. Only top-level metadata keys are filterable.
+
+Combine `user_id` with one metadata clause per call:
+
+| `metadata.type` clause | Use for |
+|--------|---------|
+| `{"metadata": {"type": "decision"}}` | design / architecture / "how should we" questions |
+| `{"metadata": {"type": "anti_pattern"}}` | debugging, error handling, things that failed before |
+| `{"metadata": {"type": "user_preference"}}` | tooling, stack, style — always include for code work |
+| `{"metadata": {"type": "convention"}}` | established patterns in this project |
+
+Full filter (replace `<your_user_id>` with the active user_id from your runtime):
+```python
+filters={"AND": [{"user_id": "<your_user_id>"}, {"metadata": {"type": "decision"}}]}
+```
+
+### Worked example
+
+User asks: *"Refactor the auth module to use JWT."*
+
+Don't:
+```python
+search_memories(query="Refactor the auth module to use JWT")
+# Hits whatever shares words. Misses prior decisions and preferences.
+```
+
+Do (parallel — substitute the active `user_id` for `<your_user_id>`):
+```python
+search_memories(query="auth module decisions",
+                filters={"AND": [{"user_id": "<your_user_id>"}, {"metadata": {"type": "decision"}}]})
+search_memories(query="JWT",
+                filters={"AND": [{"user_id": "<your_user_id>"}]})
+search_memories(query="auth refactor failures",
+                filters={"AND": [{"user_id": "<your_user_id>"}, {"metadata": {"type": "anti_pattern"}}]})
+search_memories(query="auth",
+                filters={"AND": [{"user_id": "<your_user_id>"}, {"metadata": {"type": "user_preference"}}]})
+```
+
+## After completing significant work
+
+Extract key learnings and store them using the `add_memory` tool:
+
+- **Decisions made** -> Include metadata `{"type": "decision"}`
+- **Strategies that worked** -> Include metadata `{"type": "task_learning"}`
+- **Failed approaches** -> Include metadata `{"type": "anti_pattern"}`
+- **User preferences observed** -> Include metadata `{"type": "user_preference"}`
+- **Environment/setup discoveries** -> Include metadata `{"type": "environmental"}`
+- **Conventions established** -> Include metadata `{"type": "convention"}`
+
+> `metadata.type` (which you set explicitly) and `categories` (which the platform auto-tags after the project's custom-category list — see `scripts/setup_coding_categories.py`) are complementary. Always set `metadata.type` for explicit filtering; the platform fills in `categories` on its own. Don't try to set `categories` on `add_memory` calls — per-request overrides aren't supported on the managed API.
+
+### Expiration: high-churn vs durable
+
+Some memory types are state snapshots that go stale fast; others are durable facts that should outlive the session that created them. Mark the difference with `expiration_date` on writes.
+
+| Type | Expiration | Why |
+|---|---|---|
+| `session_state`, `compact_summary` | `expiration_date` ≈ today + 90 days | Describe a single moment of project state. Useless after a quarter; clutter the recall surface. |
+| `decision`, `anti_pattern`, `convention`, `user_preference`, `task_learning`, `environmental` | omit `expiration_date` | Durable facts. A decision made last year is still a decision; same for a convention or a user preference. |
+
+`add_memory` accepts `expiration_date` as a string (`"YYYY-MM-DD"`). The two server-side hooks (`on_pre_compact.py`, `capture_compact_summary.py`) already set this for the types they write. When you write directly via the MCP tool, follow the same rule.
+
+### Recency filter on recall
+
+When the user is asking about *current* state ("where were we", "what's the active task", "the latest decision on X"), filter recall to recent memories so stale snapshots don't surface:
+
+```python
+# Last 90 days only
+{"AND": [{"user_id": "<id>"}, {"metadata": {"type": "session_state"}}, {"created_at": {"gte": "<90 days ago, YYYY-MM-DD>"}}]}
+```
+
+Skip the recency filter when the user is asking about durable facts ("what conventions does this project use", "have we hit this bug before") — those are timeless and recency would hide them.
+
+Memories can be as detailed as needed -- include full context, reasoning, code snippets, file paths, and examples. Longer, searchable memories are more valuable than vague one-liners.
+
+### Use `infer=False` for already-structured content
+
+When you've done the extraction work yourself — pre-compaction summaries, decisions, anti-patterns, conventions you've explicitly identified — pass `infer=False` so the platform stores your text verbatim instead of running a second extraction pass over it.
+
+```python
+add_memory(
+    messages=[{"role": "user", "content": "<your structured fact>"}],
+    user_id="<active user_id>",
+    metadata={"type": "decision"},
+    infer=False,
+)
+```
+
+Stick to one mode per distinct piece of content — don't mix `infer=True` (default) and `infer=False` for the same fact, you'll get duplicates. Default (`infer=True`) is right for raw conversational signal you want extracted; `infer=False` is right for pre-extracted structure.
+
+## Before losing context
+
+If context is about to be compacted or the session is ending, store a comprehensive session summary:
+
+```
+## Session Summary
+
+### User's Goal
+[What the user originally asked for]
+
+### What Was Accomplished
+[Numbered list of tasks completed]
+
+### Key Decisions Made
+[Architectural choices, trade-offs discussed]
+
+### Files Created or Modified
+[Important file paths with what changed]
+
+### Current State
+[What is in progress, pending items, next steps]
+```
+
+Include metadata: `{"type": "session_state"}`
+
+## Memory hygiene
+
+- Do NOT write to MEMORY.md or any file-based memory. Use mem0 MCP tools exclusively.
+- Only store genuinely useful learnings. Skip trivial interactions.
+- Use specific, searchable language in memory content.

mem0-plugin/skills/mem0/SKILL.md

@@ -1,25 +1,34 @@
 ---
 name: mem0
 description: >
-  Integrate Mem0 Platform into AI applications for persistent memory, personalization, and semantic search.
-  Use this skill when the user mentions "mem0", "memory layer", "remember user preferences",
-  "persistent context", "personalization", or needs to add long-term memory to chatbots, agents,
-  or AI apps. Covers Python and TypeScript SDKs, framework integrations (LangChain, CrewAI,
-  Vercel AI SDK, OpenAI Agents SDK, Pipecat), and the full Platform API. Use even when the user
-  doesn't explicitly say "mem0" but describes needing conversation memory, user context retention,
-  or knowledge retrieval across sessions.
+  Mem0 Platform SDK for adding persistent memory to AI applications.
+  TRIGGER when: user mentions "mem0", "MemoryClient", "memory layer",
+  "remember user preferences", "persistent context", "personalization",
+  or needs to add long-term memory to chatbots, agents, or AI apps.
+  Covers Python SDK (mem0ai), TypeScript SDK (mem0ai), and framework integrations
+  (LangChain, CrewAI, OpenAI Agents SDK, Pipecat, LlamaIndex, AutoGen, LangGraph).
+  Also covers the open-source self-hosted Memory class.
+  This is the DEFAULT mem0 skill for ambiguous queries.
+  DO NOT TRIGGER when: user asks about CLI commands, terminal usage, or shell
+  scripts (use mem0-cli), or Vercel AI SDK / @mem0/vercel-ai-provider / createMem0
+  (use mem0-vercel-ai-sdk).
 license: Apache-2.0
 metadata:
   author: mem0ai
-  version: "0.1.0"
+  version: "0.1.1"
   category: ai-memory
   tags: "memory, personalization, ai, python, typescript, vector-search"
-compatibility: Requires Python 3.10+ or Node.js 18+, pip install mem0ai or npm install mem0ai, MEM0_API_KEY env var, and internet access to api.mem0.ai
+compatibility: Requires Python 3.10+ or Node.js 18+, pip install mem0ai or npm install mem0ai, MEM0_API_KEY env var (Platform), and internet access to api.mem0.ai. Uses Mem0 v3 API.
 ---
 
 # Mem0 Platform Integration
 
-Mem0 is a managed memory layer for AI applications. It stores, retrieves, and manages user memories via API — no infrastructure to deploy.
+> **Skill Graph:** This skill is part of the Mem0 skill graph:
+> - **mem0** (this skill) -- Platform Client SDK + OSS (Python + TypeScript)
+> - **[mem0-cli](https://github.com/mem0ai/mem0/tree/main/skills/mem0-cli)** -- Command-line interface
+> - **[mem0-vercel-ai-sdk](https://github.com/mem0ai/mem0/tree/main/skills/mem0-vercel-ai-sdk)** -- Vercel AI SDK provider
+
+Mem0 is a managed memory layer for AI applications. It stores, retrieves, and manages user memories via API — no infrastructure to deploy. For self-hosted usage, see the OSS section in the client references below.
 
 ## Step 1: Install and authenticate
 
@@ -68,14 +77,14 @@ client.add(messages, user_id="alice")
 
 ### Search memories
 ```python
-results = client.search("dietary preferences", user_id="alice")
+results = client.search("dietary preferences", filters={"user_id": "alice"})
 for mem in results.get("results", []):
     print(mem["memory"])
 ```
 
 ### Get all memories
 ```python
-all_memories = client.get_all(user_id="alice")
+all_memories = client.get_all(filters={"user_id": "alice"})
 ```
 
 ### Update a memory
@@ -100,12 +109,12 @@ openai = OpenAI()
 
 def chat(user_input: str, user_id: str) -> str:
     # 1. Retrieve relevant memories
-    memories = mem0.search(user_input, user_id=user_id)
+    memories = mem0.search(user_input, filters={"user_id": user_id})
     context = "\n".join([m["memory"] for m in memories.get("results", [])])
 
     # 2. Generate response with memory context
     response = openai.chat.completions.create(
-        model="gpt-4.1-nano-2025-04-14",
+        model="gpt-5-mini",
         messages=[
             {"role": "system", "content": f"User context:\n{context}"},
             {"role": "user", "content": user_input},
@@ -123,11 +132,20 @@ def chat(user_input: str, user_id: str) -> str:
 
 ## Common edge cases
 
-- **Search returns empty:** Memories process asynchronously. Wait 2-3s after `add()` before searching. Also verify `user_id` matches exactly (case-sensitive).
+- **Search returns empty:** Memories process asynchronously. Wait 2-3s after `add()` before searching. Also verify `user_id` matches exactly (case-sensitive) and use `filters={"user_id": "..."}` syntax.
 - **AND filter with user_id + agent_id returns empty:** Entities are stored separately. Use `OR` instead, or query separately.
 - **Duplicate memories:** Don't mix `infer=True` (default) and `infer=False` for the same data. Stick to one mode.
 - **Wrong import:** Always use `from mem0 import MemoryClient` (or `AsyncMemoryClient` for async). Do not use `from mem0 import Memory`.
-- **Immutable memories:** Cannot be updated or deleted once created. Use `client.history(memory_id)` to track changes over time.
+- **v3 defaults:** `top_k=20`, `threshold=0.1`, `rerank=False`. Adjust as needed for your use case.
+
+## v2 Compatibility
+
+If you're using SDK v2.x, note these differences:
+- **Entity IDs:** Pass `user_id` as top-level kwarg to `search()` instead of inside `filters`
+- **Defaults:** `top_k=100`, no threshold, `rerank=True`
+- **Graph memory:** Available via `enable_graph=True`
+
+See the [migration guide](https://docs.mem0.ai/migration/oss-v2-to-v3) for details.
 
 ## Live documentation search
 
@@ -141,7 +159,17 @@ python ${CLAUDE_SKILL_DIR}/scripts/mem0_doc_search.py --index
 
 No API key needed — searches docs.mem0.ai directly.
 
-## References
+## Client SDK References
+
+Language-specific deep references (Platform + OSS):
+
+| Language | File |
+|----------|------|
+| Python (MemoryClient + AsyncMemoryClient + Memory OSS) | [client/python.md](client/python.md) |
+| TypeScript/Node.js (MemoryClient + Memory OSS) | [client/node.md](client/node.md) |
+| Python vs TypeScript differences | [client/differences.md](client/differences.md) |
+
+## Platform References
 
 Load these on demand for deeper detail:
 
@@ -152,5 +180,12 @@ Load these on demand for deeper detail:
 | API reference (endpoints, filters, object schema) | [references/api-reference.md](references/api-reference.md) |
 | Architecture (pipeline, lifecycle, scoping, performance) | [references/architecture.md](references/architecture.md) |
 | Platform features (retrieval, graph, categories, MCP, etc.) | [references/features.md](references/features.md) |
-| Framework integrations (LangChain, CrewAI, Vercel AI, etc.) | [references/integration-patterns.md](references/integration-patterns.md) |
+| Framework integrations (LangChain, CrewAI, OpenAI Agents, etc.) | [references/integration-patterns.md](references/integration-patterns.md) |
 | Use cases & examples (real-world patterns with code) | [references/use-cases.md](references/use-cases.md) |
+
+## Related Mem0 Skills
+
+| Skill | When to use | Link |
+|-------|-------------|------|
+| mem0-cli | Terminal commands, scripting, CI/CD, agent tool loops | [GitHub](https://github.com/mem0ai/mem0/tree/main/skills/mem0-cli) |
+| mem0-vercel-ai-sdk | Vercel AI SDK provider with automatic memory | [GitHub](https://github.com/mem0ai/mem0/tree/main/skills/mem0-vercel-ai-sdk) |

mem0-plugin/skills/mem0/client/differences.md

@@ -0,0 +1,129 @@
+# Python vs TypeScript SDK Differences
+
+Quick-reference cheatsheet for developers working across both Mem0 SDKs.
+
+## Constructor
+
+| Aspect | Python | TypeScript |
+|--------|--------|------------|
+| Import (Platform) | `from mem0 import MemoryClient` | `import MemoryClient from 'mem0ai'` |
+| Import (OSS) | `from mem0 import Memory` | `import { Memory } from 'mem0ai/oss'` |
+| Constructor | `MemoryClient(api_key="m0-xxx")` | `new MemoryClient({ apiKey: 'm0-xxx' })` |
+| Required param | `api_key` (positional or kwarg) | `apiKey` (in options object) |
+
+Both read from `MEM0_API_KEY` env var if no key provided.
+
+## Method Naming
+
+| Operation | Python | TypeScript |
+|-----------|--------|------------|
+| Add | `add()` | `add()` |
+| Search | `search()` | `search()` |
+| Get | `get()` | `get()` |
+| Get all | `get_all()` | `getAll()` |
+| Update | `update()` | `update()` |
+| Delete | `delete()` | `delete()` |
+| Delete all | `delete_all()` | `deleteAll()` |
+| History | `history()` | `history()` |
+| Batch update | `batch_update()` | `batchUpdate()` |
+| Batch delete | `batch_delete()` | `batchDelete()` |
+| List users | `users()` | `users()` |
+| Delete users | `delete_users()` | `deleteUsers()` |
+| Get project | `project.get()` | `getProject()` |
+| Update project | `project.update()` | `updateProject()` |
+| Create webhook | `create_webhook()` | `createWebhook()` |
+| Get webhooks | `get_webhooks()` | `getWebhooks()` |
+| Update webhook | `update_webhook()` | `updateWebhook()` |
+| Delete webhook | `delete_webhook()` | `deleteWebhook()` |
+| Create export | `create_memory_export()` | `createMemoryExport()` |
+| Get export | `get_memory_export()` | `getMemoryExport()` |
+| Feedback | `feedback()` | `feedback()` |
+
+**Rule:** Python uses `snake_case`, TypeScript uses `camelCase` for method names.
+
+## Parameter Passing
+
+```python
+# Python: kwargs
+client.add(messages, user_id="alice", metadata={"source": "chat"})
+client.search("query", filters={"user_id": "alice"}, top_k=5, rerank=True)
+```
+
+```typescript
+// TypeScript: options object with camelCase for top-level params, snake_case for filter keys
+await client.add(messages, { userId: 'alice', metadata: { source: 'chat' } });
+await client.search('query', { filters: { user_id: 'alice' }, topK: 5, rerank: true });
+```
+
+**v3:** Python uses `snake_case` everywhere. TypeScript uses `camelCase` for top-level params (`userId`, `topK`) but `snake_case` for filter keys (`user_id`, `agent_id`).
+
+## Architectural Differences
+
+| Aspect | Python | TypeScript |
+|--------|--------|------------|
+| HTTP library | httpx | axios |
+| Default timeout | 300s | 60s |
+| Sync support | Yes (`MemoryClient`) | No (all async) |
+| Async support | Yes (`AsyncMemoryClient`) | All methods are async |
+| Project management | `client.project.*` (separate class) | `client.getProject()` / `client.updateProject()` |
+| Context manager | `async with AsyncMemoryClient()` | Not supported |
+
+## Platform Features: Python-only
+
+These methods exist in Python but not TypeScript:
+
+| Method | Description |
+|--------|-------------|
+| `get_summary(filters)` | Get summary of memories |
+| `reset()` | Delete ALL data (users + memories) |
+| `project.create(name)` | Create a new project |
+| `project.delete()` | Delete current project |
+| `project.get_members()` | List project members |
+| `project.add_member(email, role)` | Add member to project |
+| `project.update_member(email, role)` | Change member role |
+| `project.remove_member(email)` | Remove member |
+
+## Platform Features: TypeScript-only
+
+| Method | Description |
+|--------|-------------|
+| `deleteUser(data)` | Convenience method for single entity deletion |
+| `ping()` | Health check endpoint |
+
+## OSS Config Naming
+
+| Python config key | TypeScript config key |
+|-------------------|----------------------|
+| `vector_store` | `vectorStore` |
+| `history_db_path` | `historyDbPath` |
+| `custom_instructions` | `customInstructions` |
+
+## OSS Scope Parameter Naming
+
+| Python | TypeScript |
+|--------|------------|
+| `user_id="alice"` | `userId: 'alice'` |
+| `agent_id="bot"` | `agentId: 'bot'` |
+| `run_id="session"` | `runId: 'session'` |
+
+## Entity ID Passing (v3)
+
+| Method | Python | TypeScript |
+|--------|--------|------------|
+| add() | Top-level: `user_id="alice"` | Top-level: `{ userId: 'alice' }` |
+| search() | In filters: `filters={"user_id": "alice"}` | In filters: `{ filters: { user_id: 'alice' } }` |
+| get_all() | In filters: `filters={"user_id": "alice"}` | In filters: `{ filters: { user_id: 'alice' } }` |
+
+## Common Gotcha
+
+When searching/filtering, both Python and TypeScript use `snake_case` for filter keys. TypeScript only uses `camelCase` for top-level method parameters:
+
+```python
+# Python - snake_case in filters
+results = client.search("query", filters={"user_id": "alice"})
+```
+
+```typescript
+// TypeScript - snake_case in filters, camelCase for top-level params
+const results = await client.search('query', { filters: { user_id: 'alice' }, topK: 20 });
+```

mem0-plugin/skills/mem0/client/node.md

@@ -0,0 +1,418 @@
+# Mem0 Node.js / TypeScript SDK Reference
+
+Complete reference for the `mem0ai` npm package. Covers both the Platform client (managed API) and the Open Source self-hosted variant.
+
+---
+
+## Platform Client
+
+### Installation
+
+```bash
+npm install mem0ai
+export MEM0_API_KEY="m0-your-api-key"
+```
+
+### MemoryClient
+
+```typescript
+import MemoryClient from 'mem0ai';
+
+const client = new MemoryClient({ apiKey: 'm0-xxx' });
+```
+
+**Constructor:** `new MemoryClient({ apiKey })`. If `apiKey` is not provided, reads from `MEM0_API_KEY` environment variable.
+
+- HTTP library: `axios`
+- Timeout: 60 seconds
+- Base URL: `https://api.mem0.ai`
+- All methods are async (return `Promise`)
+
+---
+
+### Memory Methods
+
+#### add(messages, options?)
+
+Store new memories from messages.
+
+```typescript
+const messages = [
+    { role: 'user', content: "I'm a vegetarian and allergic to nuts." },
+    { role: 'assistant', content: "Got it! I'll remember that." },
+];
+await client.add(messages, { userId: 'alice' });
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `messages` | `Message[]` | Array of `{role, content}` objects |
+| `options.userId` | string | User identifier |
+| `options.agentId` | string | Agent identifier |
+| `options.appId` | string | Application identifier |
+| `options.runId` | string | Session identifier |
+| `options.metadata` | object | Custom key-value pairs |
+| `options.infer` | boolean | If false, store raw text (default: true) |
+
+**Returns:** `Promise<any>` -- list of events
+
+#### search(query, options?)
+
+Search memories by semantic similarity.
+
+```typescript
+const results = await client.search('dietary preferences', { filters: { user_id: 'alice' }, topK: 20 });
+for (const mem of results.results) {
+    console.log(mem.memory, mem.score);
+}
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | string | Natural language search query |
+| `options.filters` | object | Filter object with entity IDs (`user_id`, `agent_id`, etc.) and/or `AND`/`OR`/`NOT` conditions |
+| `options.topK` | number | Number of results (default: 20) |
+| `options.rerank` | boolean | Enable semantic reranking (default: false) |
+| `options.threshold` | number | Minimum similarity (default: 0.1) |
+
+**Returns:** `Promise<SearchResult>` -- `{results: [{id, memory, score, ...}]}`
+
+#### get(memoryId)
+
+```typescript
+const memory = await client.get('ea925981-...');
+```
+
+#### getAll(options?)
+
+Retrieve all memories. Requires at least one entity identifier in filters.
+
+```typescript
+const memories = await client.getAll({ filters: { user_id: 'alice' } });
+// With filters
+const filtered = await client.getAll({
+    filters: { AND: [{ user_id: 'alice' }, { categories: { contains: 'health' } }] },
+});
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `options.filters` | object | Filter object with entity IDs (`user_id`, `agent_id`, etc.) and/or `AND`/`OR`/`NOT` conditions |
+| `options.page` | number | Page number |
+| `options.pageSize` | number | Results per page |
+
+#### update(memoryId, data)
+
+```typescript
+await client.update('ea925981-...', { text: 'Updated: vegan since 2024' });
+await client.update('ea925981-...', { text: 'Updated', metadata: { verified: true } });
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `memoryId` | string | Memory ID |
+| `data.text` | string | New content |
+| `data.metadata` | object | New metadata |
+| `data.timestamp` | string | New timestamp |
+
+#### delete(memoryId)
+
+```typescript
+await client.delete('ea925981-...');
+```
+
+#### deleteAll(options?)
+
+```typescript
+await client.deleteAll({ userId: 'alice' });
+```
+
+#### history(memoryId)
+
+```typescript
+const history = await client.history('ea925981-...');
+// Returns: [{previousValue, newValue, action, timestamps}]
+```
+
+---
+
+### Batch Methods
+
+#### batchUpdate(memories)
+
+```typescript
+await client.batchUpdate([
+    { memoryId: 'uuid-1', text: 'Updated text' },
+    { memoryId: 'uuid-2', text: 'Another update' },
+]);
+```
+
+#### batchDelete(memories)
+
+```typescript
+await client.batchDelete(['uuid-1', 'uuid-2', 'uuid-3']);
+```
+
+---
+
+### User/Entity Management
+
+#### users()
+
+```typescript
+const users = await client.users();
+// Returns: {results: [{type: "user", name: "alice"}, ...]}
+```
+
+#### deleteUser(data) / deleteUsers(data)
+
+```typescript
+await client.deleteUser({ userId: 'alice' });  // Single entity
+await client.deleteUsers({ agentId: 'bot-1' }); // Flexible
+```
+
+---
+
+### Project Management
+
+```typescript
+// Get project config
+const config = await client.getProject({ fields: ['customCategories'] });
+
+// Update project settings
+await client.updateProject({
+    customInstructions: 'Extract dietary preferences and health info',
+    customCategories: [{ health: 'Medical and dietary info' }],
+});
+```
+
+---
+
+### Webhooks
+
+```typescript
+// List
+const webhooks = await client.getWebhooks({ projectId: 'proj_123' });
+
+// Create
+const webhook = await client.createWebhook({
+    url: 'https://your-app.com/webhook',
+    name: 'Memory Logger',
+    projectId: 'proj_123',
+    eventTypes: ['memory_add', 'memory_update'],
+});
+
+// Update
+await client.updateWebhook({
+    webhookId: 'wh_123',
+    name: 'Updated Logger',
+    url: 'https://new-url.com',
+});
+
+// Delete
+await client.deleteWebhook({ webhookId: 'wh_123' });
+```
+
+---
+
+### Feedback
+
+```typescript
+await client.feedback({
+    memoryId: 'mem-123',
+    feedback: 'POSITIVE',
+    feedbackReason: 'Accurately captured preference',
+});
+```
+
+---
+
+### Export
+
+```typescript
+const exportReq = await client.createMemoryExport({
+    schema: JSON.stringify({ type: 'object', properties: { name: { type: 'string' } } }),
+    filters: { user_id: 'alice' },
+});
+
+const result = await client.getMemoryExport({ memoryExportId: exportReq.id });
+```
+
+---
+
+### TypeScript Types
+
+Key interfaces from `mem0.types.ts`:
+
+```typescript
+interface Message { role: string; content: string; }
+interface Memory { id: string; memory: string; userId: string; categories: string[]; score?: number; /* ... */ }
+interface MemoryOptions { userId?: string; agentId?: string; appId?: string; runId?: string; metadata?: object; /* ... */ }
+interface SearchOptions { filters?: object; topK?: number; rerank?: boolean; threshold?: number; /* ... */ }
+interface MemoryHistory { id: string; memoryId: string; previousValue: string; newValue: string; action: string; /* ... */ }
+interface FeedbackPayload { memoryId: string; feedback: string; feedbackReason?: string; }
+interface WebhookCreatePayload { url: string; name: string; projectId: string; eventTypes: string[]; }
+```
+
+---
+
+## Open Source / Self-Hosted
+
+### Installation
+
+```bash
+npm install mem0ai
+```
+
+### Memory Class
+
+```typescript
+import { Memory } from 'mem0ai/oss';
+
+const m = new Memory();  // Uses default config
+```
+
+**Import:** `from 'mem0ai/oss'` (NOT the default export -- that is `MemoryClient` for Platform)
+
+### Configuration
+
+```typescript
+const config = {
+    llm: {
+        provider: 'openai',        // openai, groq, anthropic, google, ollama, lmstudio, mistral, azure
+        config: {
+            model: 'gpt-5-mini',
+            apiKey: 'sk-xxx',
+        },
+    },
+    embedder: {
+        provider: 'openai',        // openai, ollama, lmstudio, google, azure, langchain, anthropic
+        config: {
+            model: 'text-embedding-3-small',
+            apiKey: 'sk-xxx',
+        },
+    },
+    vectorStore: {
+        provider: 'qdrant',        // memory, qdrant, redis, supabase, langchain, azure_ai_search, pgvector
+        config: {
+            collectionName: 'my_memories',
+            host: 'localhost',
+            port: 6333,
+        },
+    },
+    historyDbPath: 'history.db',
+    customInstructions: '...',
+    disableHistory: false,
+};
+
+const m = new Memory(config);
+// Or from dict with validation:
+const m2 = Memory.fromConfig(config);
+```
+
+### Methods
+
+All methods are async (return `Promise`):
+
+#### add(messages, config)
+
+```typescript
+await m.add('I prefer dark mode', { userId: 'alice' });
+await m.add([
+    { role: 'user', content: 'I like hiking' },
+    { role: 'assistant', content: 'Great outdoor activity!' },
+], { userId: 'alice' });
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `messages` | `string \| Message[]` | Content to store |
+| `config.userId` | string | User identifier (at least one scope required) |
+| `config.agentId` | string | Agent identifier |
+| `config.runId` | string | Session identifier |
+| `config.metadata` | object | Custom key-value pairs |
+| `config.filters` | object | Additional filters |
+| `config.infer` | boolean | LLM inference (default: true) |
+
+**Returns:** `Promise<{results: [...], relations?: [...]}>`
+
+#### search(query, config)
+
+```typescript
+const results = await m.search('dietary preferences', { filters: { user_id: 'alice' }, topK: 5 });
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | string | Search query |
+| `config.filters` | object | Filter object with entity IDs (`user_id`, `agent_id`, `run_id`, etc.) |
+| `config.topK` | number | Max results (default: 20) |
+
+#### get(memoryId) / getAll(config) / update(memoryId, data) / delete(memoryId) / deleteAll(config) / history(memoryId)
+
+Same interface patterns. Note: OSS `update` takes a string for data, not an object.
+
+```typescript
+await m.update('mem-id', 'new content');
+```
+
+#### reset()
+
+Clear the entire vector store and history.
+
+```typescript
+await m.reset();
+```
+
+---
+
+## Key Differences: Platform vs OSS
+
+| Aspect | Platform (`MemoryClient`) | OSS (`Memory`) |
+|--------|--------------------------|----------------|
+| **Import** | `import MemoryClient from 'mem0ai'` | `import { Memory } from 'mem0ai/oss'` |
+| **Auth** | API key required (`MEM0_API_KEY`) | No API key -- config-based |
+| **Execution** | API calls to `api.mem0.ai` | Local execution |
+| **Infrastructure** | Fully managed | Self-managed vector DB, embedder, LLM |
+| **Param style** | Top-level: `camelCase` (`userId`, `topK`), filter keys: `snake_case` (`user_id`) | Top-level: `camelCase` (`userId`, `topK`), filter keys: `snake_case` (`user_id`) |
+| **Batch ops** | `batchUpdate`, `batchDelete` | Not available |
+| **Webhooks** | Full CRUD | Not available |
+| **Export** | `createMemoryExport` | Not available |
+| **Feedback** | `feedback()` | Not available |
+| **Project mgmt** | `getProject`, `updateProject` | Not available |
+| **User listing** | `users()`, `deleteUser()` | Not available |
+| **History** | Platform-managed | SQLite (configurable) |
+
+---
+
+## v2 Compatibility
+
+If you're using SDK v2.x:
+
+**Naming Changes:**
+- Top-level params now use camelCase: `topK`, `rerank` (not `top_k`)
+- Filter keys use snake_case: `user_id`, `agent_id`
+- OSS: `limit` renamed to `topK`
+
+**API Changes:**
+```typescript
+// v2 - top-level entity IDs, snake_case
+await client.search("query", { user_id: "alice", top_k: 20 });
+
+// v3 - filters object with snake_case keys, camelCase top-level params
+await client.search("query", { filters: { user_id: "alice" }, topK: 20 });
+```
+
+**Default Changes:**
+| Param | v2 | v3 |
+|-------|----|----|
+| `topK` | 100 | 20 |
+| `threshold` | none | 0.1 |
+| `rerank` | true | false |
+
+**Removed:**
+- `OutputFormat` and `API_VERSION` enums
+- `organizationId`, `projectId` from constructor
+- `enableGraph`, `asyncMode`, `outputFormat`, `immutable`, `expirationDate`, `filterMemories`, `batchSize`, `forceAddOnly`, `includes`, `excludes`, `keywordSearch`
+
+See the [v2 to v3 migration guide](https://docs.mem0.ai/migration/oss-v2-to-v3) for details.

mem0-plugin/skills/mem0/client/python.md

@@ -0,0 +1,487 @@
+# Mem0 Python SDK Reference
+
+Complete reference for the `mem0ai` Python package. Covers both the Platform client (managed API) and the Open Source self-hosted variant.
+
+---
+
+## Platform Client
+
+### Installation
+
+```bash
+pip install mem0ai
+export MEM0_API_KEY="m0-your-api-key"
+```
+
+### MemoryClient (Synchronous)
+
+```python
+from mem0 import MemoryClient
+
+client = MemoryClient(api_key="m0-xxx")
+```
+
+**Constructor:** `MemoryClient(api_key=None)`. If `api_key` is not provided, reads from `MEM0_API_KEY` environment variable. Raises `ValueError` if no key found.
+
+- HTTP library: `httpx`
+- Timeout: 300 seconds
+- Base URL: `https://api.mem0.ai`
+
+### AsyncMemoryClient (Asynchronous)
+
+```python
+from mem0 import AsyncMemoryClient
+
+client = AsyncMemoryClient(api_key="m0-xxx")
+
+# Or use as context manager
+async with AsyncMemoryClient(api_key="m0-xxx") as client:
+    results = await client.search("query", filters={"user_id": "alice"})
+```
+
+Same methods as `MemoryClient`, all `async`/`await`. Supports async context manager.
+
+---
+
+### Memory Methods
+
+#### add(messages, **kwargs)
+
+Store new memories from messages.
+
+```python
+messages = [
+    {"role": "user", "content": "I'm a vegetarian and allergic to nuts."},
+    {"role": "assistant", "content": "Got it! I'll remember that."}
+]
+client.add(messages, user_id="alice")
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `messages` | str \| dict \| list[dict] | required | Message content. Strings auto-convert to user messages |
+| `user_id` | str | None | User identifier |
+| `agent_id` | str | None | Agent identifier |
+| `app_id` | str | None | Application identifier |
+| `run_id` | str | None | Session/run identifier |
+| `metadata` | dict | None | Custom key-value pairs |
+| `infer` | bool | True | If False, store raw text without LLM inference |
+| `custom_categories` | list | None | Override project categories |
+| `custom_instructions` | str | None | Override extraction instructions |
+| `timestamp` | int \| float \| str | None | Custom timestamp (Unix epoch or ISO 8601) |
+
+**Returns:** `dict` -- list of events: `[{"id": "...", "event": "ADD", "data": {"memory": "..."}}]`
+
+#### search(query, **kwargs)
+
+Search memories by semantic similarity.
+
+```python
+results = client.search("dietary preferences", filters={"user_id": "alice"})
+for mem in results.get("results", []):
+    print(mem["memory"], mem["score"])
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `query` | str | required | Natural language search query |
+| `filters` | dict | None | Filter object with entity IDs and/or `AND`/`OR`/`NOT` conditions (e.g., `{"user_id": "alice"}`) |
+| `top_k` | int | 10 | Number of results |
+| `rerank` | bool | False | Enable deep semantic reranking (+150-200ms) |
+| `threshold` | float | 0.1 | Minimum similarity score |
+| `fields` | list | None | Specific fields to return |
+| `categories` | list | None | Filter by category |
+
+**Returns:** `dict` -- `{"results": [{id, memory, user_id, categories, score, created_at, ...}]}`
+
+#### get(memory_id)
+
+Retrieve a single memory by ID.
+
+```python
+memory = client.get(memory_id="ea925981-...")
+```
+
+**Returns:** `dict` -- full memory object
+
+#### get_all(**kwargs)
+
+Retrieve all memories with optional filtering. Requires at least one entity identifier.
+
+```python
+memories = client.get_all(filters={"user_id": "alice"})
+# With compound filters
+memories = client.get_all(filters={"AND": [{"user_id": "alice"}, {"categories": {"contains": "health"}}]})
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `filters` | dict | None | Filter object with entity IDs and/or `AND`/`OR`/`NOT` conditions |
+| `top_k` | int | None | Limit results |
+| `page` | int | None | Page number |
+| `page_size` | int | None | Results per page |
+
+**Returns:** `dict` -- `{"results": [...]}`
+
+#### update(memory_id, text=None, metadata=None, timestamp=None)
+
+Update a memory's content, metadata, or timestamp. At least one parameter required.
+
+```python
+client.update("ea925981-...", text="Updated: vegan since 2024")
+client.update("ea925981-...", metadata={"verified": True})
+```
+
+**Returns:** `dict` -- updated memory
+
+#### delete(memory_id)
+
+Permanently delete a single memory.
+
+```python
+client.delete("ea925981-...")
+```
+
+#### delete_all(**kwargs)
+
+Delete all memories matching filters. Irreversible.
+
+```python
+client.delete_all(user_id="alice")
+```
+
+#### history(memory_id)
+
+Get the change history of a memory.
+
+```python
+history = client.history("ea925981-...")
+# Returns: [{previous_value, new_value, action, timestamps}]
+```
+
+---
+
+### Batch Methods
+
+#### batch_update(memories)
+
+Update up to 1000 memories in a single request.
+
+```python
+client.batch_update([
+    {"memory_id": "uuid-1", "text": "Updated text"},
+    {"memory_id": "uuid-2", "text": "Another update", "metadata": {"verified": True}},
+])
+```
+
+#### batch_delete(memories)
+
+Delete up to 1000 memories in a single request.
+
+```python
+client.batch_delete([
+    {"memory_id": "uuid-1"},
+    {"memory_id": "uuid-2"},
+])
+```
+
+---
+
+### User/Entity Management
+
+#### users()
+
+List all users, agents, and sessions that have memories.
+
+```python
+users = client.users()
+# Returns: {"results": [{"type": "user", "name": "alice"}, ...]}
+```
+
+#### delete_users(user_id=None, agent_id=None, app_id=None, run_id=None)
+
+Delete a specific entity and all its memories.
+
+```python
+client.delete_users(user_id="alice")
+```
+
+#### reset()
+
+Delete ALL users, agents, sessions, and memories. Complete data reset.
+
+```python
+client.reset()
+```
+
+---
+
+### Export & Summary
+
+#### create_memory_export(schema, **kwargs)
+
+Create a structured export of memories.
+
+```python
+import json
+
+schema = json.dumps({
+    "type": "object",
+    "properties": {
+        "name": {"type": "string"},
+        "preferences": {"type": "array", "items": {"type": "string"}},
+    }
+})
+export = client.create_memory_export(schema=schema, user_id="alice")
+```
+
+#### get_memory_export(**kwargs)
+
+Retrieve a previously created export.
+
+```python
+result = client.get_memory_export(memory_export_id=export["id"])
+```
+
+#### get_summary(filters=None)
+
+Get a summary of memories.
+
+```python
+summary = client.get_summary(filters={"user_id": "alice"})
+```
+
+---
+
+### Feedback
+
+#### feedback(memory_id, feedback=None, feedback_reason=None)
+
+Provide quality feedback on a memory.
+
+```python
+client.feedback(
+    memory_id="mem-123",
+    feedback="POSITIVE",  # POSITIVE | NEGATIVE | VERY_NEGATIVE | None (clear)
+    feedback_reason="Accurately captured preference"
+)
+```
+
+---
+
+### Webhooks
+
+```python
+# List
+webhooks = client.get_webhooks(project_id="proj_123")
+
+# Create
+webhook = client.create_webhook(
+    url="https://your-app.com/webhook",
+    name="Memory Logger",
+    project_id="proj_123",
+    event_types=["memory_add", "memory_update"]
+)
+
+# Update
+client.update_webhook(webhook_id=123, name="Updated", url="https://new-url.com")
+
+# Delete
+client.delete_webhook(webhook_id=123)
+```
+
+---
+
+### Project Management
+
+Access via `client.project.*`:
+
+```python
+# Get project config
+config = client.project.get(fields=["custom_categories", "custom_instructions"])
+
+# Update project settings
+client.project.update(
+    custom_instructions="Extract dietary preferences and health info",
+    custom_categories=[{"health": "Medical and dietary info"}],
+    multilingual=True,
+)
+
+# Create/delete project
+client.project.create(name="My Project", description="...")
+client.project.delete()
+
+# Member management
+members = client.project.get_members()
+client.project.add_member(email="user@example.com", role="READER")  # READER or OWNER
+client.project.update_member(email="user@example.com", role="OWNER")
+client.project.remove_member(email="user@example.com")
+```
+
+---
+
+## Open Source / Self-Hosted
+
+### Installation
+
+```bash
+pip install mem0ai
+```
+
+### Memory Class
+
+```python
+from mem0 import Memory
+
+m = Memory()  # Uses default config (OpenAI embedder + in-memory vector store)
+```
+
+**Import:** `from mem0 import Memory` (NOT `MemoryClient` -- that is the Platform client)
+
+### Configuration
+
+```python
+config = {
+    "llm": {
+        "provider": "openai",        # openai, groq, azure, ollama, lmstudio, google, anthropic, mistral
+        "config": {
+            "model": "gpt-5-mini",
+            "api_key": "sk-xxx",
+        }
+    },
+    "embedder": {
+        "provider": "openai",        # openai, ollama, azure, lmstudio, google, huggingface
+        "config": {
+            "model": "text-embedding-3-small",
+            "api_key": "sk-xxx",
+        }
+    },
+    "vector_store": {
+        "provider": "qdrant",        # faiss, qdrant, pgvector, redis, supabase, azure_ai_search, memory
+        "config": {
+            "collection_name": "my_memories",
+            "host": "localhost",
+            "port": 6333,
+        }
+    },
+    "history_db_path": "history.db",              # SQLite path for change history
+    "custom_instructions": "...",                  # Custom LLM prompt for extraction
+}
+
+m = Memory.from_config(config)
+```
+
+### Context Manager
+
+```python
+with Memory(config) as m:
+    m.add("I prefer dark mode", user_id="alice")
+    results = m.search("preferences", filters={"user_id": "alice"})
+# SQLite connections released automatically
+```
+
+### Methods
+
+All methods mirror the Platform client but run locally:
+
+#### add(messages, *, user_id, agent_id, run_id, metadata, infer=True)
+
+```python
+m.add("I'm a vegetarian", user_id="alice")
+m.add([
+    {"role": "user", "content": "I like hiking"},
+    {"role": "assistant", "content": "Great outdoor activity!"}
+], user_id="alice")
+```
+
+At least one of `user_id`, `agent_id`, `run_id` required.
+
+**Returns:** `{"results": [...], "relations": [...]}`
+
+#### search(query, *, filters=None, top_k=20, threshold=0.1, rerank=False)
+
+```python
+results = m.search("dietary preferences", filters={"user_id": "alice"}, top_k=5)
+```
+
+Entity IDs (`user_id`, `agent_id`, `run_id`) must be passed inside the `filters` dict.
+
+Supports filter operators: `eq`, `ne`, `in`, `nin`, `gt`, `gte`, `lt`, `lte`, `contains`, `not_contains`.
+
+#### get(memory_id) / get_all(**kwargs) / update(memory_id, data, metadata=None) / delete(memory_id) / delete_all(**kwargs) / history(memory_id)
+
+Same interface as Platform client.
+
+#### reset()
+
+Clear the entire vector store collection and history database. Recreates the vector store.
+
+```python
+m.reset()
+```
+
+#### close()
+
+Release SQLite connections. Called automatically when using context manager.
+
+### AsyncMemory
+
+```python
+from mem0 import AsyncMemory
+
+m = AsyncMemory(config)
+await m.add("text", user_id="alice")
+results = await m.search("query", filters={"user_id": "alice"})
+```
+
+---
+
+## Key Differences: Platform vs OSS
+
+| Aspect | Platform (`MemoryClient`) | OSS (`Memory`) |
+|--------|--------------------------|----------------|
+| **Import** | `from mem0 import MemoryClient` | `from mem0 import Memory` |
+| **Auth** | API key required (`MEM0_API_KEY`) | No API key -- config-based |
+| **Execution** | API calls to `api.mem0.ai` | Local execution |
+| **Infrastructure** | Fully managed | Self-managed vector DB, embedder, LLM |
+| **Entity filtering** | `filters={"user_id": "..."}` | `filters={"user_id": "..."}` |
+| **Batch ops** | `batch_update`, `batch_delete` | Not available |
+| **Webhooks** | Full CRUD | Not available |
+| **Export** | `create_memory_export`, `get_memory_export` | Not available |
+| **Feedback** | `feedback()` | Not available |
+| **Project mgmt** | `client.project.*` | Not available |
+| **User listing** | `users()`, `delete_users()` | Not available |
+| **Custom prompts** | Via project settings | Direct config (`custom_instructions`) |
+| **History** | Platform-managed | SQLite (configurable) |
+| **Async** | `AsyncMemoryClient` | `AsyncMemory` |
+
+---
+
+## v2 Compatibility
+
+If you're using SDK v2.x or the v2 API:
+
+**API Changes:**
+- **Entity IDs in search/get_all:** Pass `user_id`, `agent_id` as top-level kwargs instead of inside `filters`
+  ```python
+  # v2
+  results = client.search("query", user_id="alice")
+  # v3
+  results = client.search("query", filters={"user_id": "alice"})
+  ```
+- **add() returns:** v2 returns ADD, UPDATE, DELETE events; v3 returns ADD only
+
+**Default Changes:**
+| Param | v2 | v3 |
+|-------|----|----|
+| `top_k` | 100 | 20 |
+| `threshold` | None | 0.1 |
+| `rerank` | True | False |
+
+**Removed Parameters:**
+- Constructor: `org_id`, `project_id`
+- add(): `async_mode`, `output_format`, `enable_graph`, `immutable`, `expiration_date`, `filter_memories`, `batch_size`, `force_add_only`, `includes`, `excludes`, `keyword_search`
+- search()/get_all(): `enable_graph`
+- Config: `enable_graph`, `graph_store`, `custom_fact_extraction_prompt` (renamed to `custom_instructions`)
+
+See the [v2 to v3 migration guide](https://docs.mem0.ai/migration/oss-v2-to-v3) for full details.

mem0-plugin/skills/mem0/references/api-reference.md

@@ -8,13 +8,15 @@ All endpoints require: `Authorization: Token <MEM0_API_KEY>`
 
 | Operation | Method | URL |
 |-----------|--------|-----|
-| Add Memories | `POST` | `/v1/memories/` |
-| Search Memories | `POST` | `/v2/memories/search/` |
-| Get All Memories | `POST` | `/v2/memories/` |
+| Add Memories | `POST` | `/v3/memories/add/` |
+| Search Memories | `POST` | `/v3/memories/search/` |
+| Get All Memories | `POST` | `/v3/memories/` |
 | Get Single Memory | `GET` | `/v1/memories/{memory_id}/` |
 | Update Memory | `PUT` | `/v1/memories/{memory_id}/` |
 | Delete Memory | `DELETE` | `/v1/memories/{memory_id}/` |
 
+Note: v1/v2 endpoints still work (backward compatible).
+
 ## Memory Object Structure
 
 | Field | Type | Description |
@@ -27,8 +29,6 @@ All endpoints require: `Authorization: Token <MEM0_API_KEY>`
 | `run_id` | string (nullable) | Run/session identifier |
 | `metadata` | object | Custom key-value pairs |
 | `categories` | array of strings | Auto-assigned category tags |
-| `immutable` | boolean | If true, prevents modification |
-| `expiration_date` | datetime (nullable) | Auto-expiry date |
 | `hash` | string | Content hash |
 | `created_at` | datetime | Creation timestamp |
 | `updated_at` | datetime | Last modification timestamp |
@@ -50,10 +50,9 @@ Memories can be scoped to different levels:
 
 ## Processing Model
 
-- Memories are processed **asynchronously by default** (`async_mode=true`)
-- Add responses return queued events (`ADD`, `UPDATE`, `DELETE`) for tracking
-- Set `async_mode=false` for synchronous processing when needed
-- Graph metadata is processed asynchronously -- use `get_all()` for complete graph data
+- Memories are processed **asynchronously** (v3 default)
+- Add responses return queued `ADD` events only (v3 is ADD-only, no UPDATE/DELETE)
+- Poll status via `GET /v1/event/{event_id}/`
 
 ## Filter System
 
@@ -106,19 +105,17 @@ Root must be `AND`, `OR`, or `NOT`. Simple shorthand `{"user_id": "alice"}` also
 
 ## Response Formats
 
-### Add Response
+### Add Response (v3)
 
 ```json
-[
-  {
-    "id": "mem_01JF8ZS4Y0R0SPM13R5R6H32CJ",
-    "event": "ADD",
-    "data": { "memory": "The user moved to Austin in 2025." }
-  }
-]
+{
+  "message": "Memory processing has been queued for background execution",
+  "status": "PENDING",
+  "event_id": "evt-uuid"
+}
 ```
 
-Event types: `ADD`, `UPDATE`, `DELETE`. A single add can trigger multiple events.
+v3 is ADD-only. No UPDATE or DELETE events.
 
 ### Search Response
 
@@ -137,4 +134,17 @@ Event types: `ADD`, `UPDATE`, `DELETE`. A single add can trigger multiple events
 }
 ```
 
-With `enable_graph=true`, includes additional `relations` array with entity relationships.
+In v3, `score` is a combined multi-signal relevance score.
+
+### Get All Response (v3)
+
+```json
+{
+  "count": 123,
+  "next": "https://api.mem0.ai/v3/memories/?page=2&page_size=50",
+  "previous": null,
+  "results": [...]
+}
+```
+
+v3 returns paginated envelope. Use `page` and `page_size` query params.

mem0-plugin/skills/mem0/references/architecture.md

@@ -25,9 +25,9 @@ User Input → Retrieve relevant memories → Enrich LLM prompt → Generate res
 
 Mem0 handles the complexity of extraction, deduplication, conflict resolution, and semantic retrieval so your application only needs to call `search()` and `add()`.
 
-**Dual storage architecture:**
+**Storage architecture:**
 - **Vector store**: Embeddings for semantic similarity search
-- **Graph store** (optional): Entity nodes and relationship edges for structured knowledge
+- **Entity store**: Automatic entity linking for relationship-aware retrieval
 
 ---
 
@@ -40,41 +40,32 @@ Messages In
     │
     ▼
 ┌─────────────────────┐
-│  1. EXTRACTION       │  LLM analyzes messages, extracts key facts
+│  1. EXTRACTION       │  Single LLM call extracts all distinct new facts
 │     (infer=True)     │  If infer=False, stores raw text as-is
 └─────────┬───────────┘
           │
           ▼
 ┌─────────────────────┐
-│  2. CONFLICT         │  Checks existing memories for duplicates
-│     RESOLUTION       │  Latest truth wins (newer overrides older)
-│                      │  Only runs when infer=True
+│  2. DEDUPLICATION    │  Hash-based dedup (MD5 prevents exact duplicates)
+│                      │  No UPDATE/DELETE - v3 is ADD-only
 └─────────┬───────────┘
           │
           ▼
 ┌─────────────────────┐
-│  3. STORAGE          │  Generates embeddings → vector store
-│                      │  Optional: entity extraction → graph store
-│                      │  Indexes metadata, categories, timestamps
+│  3. STORAGE          │  Batch embed → vector store
+│                      │  Entity extraction → entity store
 └─────────┬───────────┘
           │
           ▼
     Memory Object
-    (id, memory, categories, structured_attributes)
 ```
 
-### Processing modes
+### Processing (v3)
 
-**Async (default, `async_mode=True`):**
-- API returns immediately: `{"status": "PENDING", "event_id": "..."}`
-- Processing happens in background
+v3 processes memories asynchronously by default:
+- API returns immediately: `{"status": "PENDING", "event_id": "evt-..."}`
+- Poll status via `GET /v1/event/{event_id}/`
 - Use webhooks for completion notifications
-- Best for: high-throughput, non-blocking workflows
-
-**Sync (`async_mode=False`):**
-- API waits for full processing
-- Returns complete memory object with `id`, `event`, `memory`
-- Best for: real-time access immediately after add
 
 ### Extraction modes
 
@@ -93,7 +84,7 @@ Messages In
 
 ---
 
-## Retrieval Pipeline
+## Retrieval Pipeline (v3)
 
 ### What happens when you call `client.search()`
 
@@ -102,45 +93,37 @@ Query In
     │
     ▼
 ┌─────────────────────┐
-│  1. QUERY EMBEDDING  │  Convert query to vector representation
+│  1. PREPROCESSING    │  Lemmatize keywords, extract entities
 └─────────┬───────────┘
           │
           ▼
 ┌─────────────────────┐
-│  2. VECTOR SEARCH    │  Cosine similarity across stored embeddings
-│                      │  Scoped by filters (user_id, agent_id, etc.)
-└─────────┬───────────┘
-          │
-          ▼  (optional enhancements)
-┌─────────────────────┐
-│  3a. KEYWORD SEARCH  │  Expands results with specific terms (+10ms)
-│  3b. RERANKING       │  Deep semantic reordering (+150-200ms)
-│  3c. FILTER MEMORIES │  Precision filtering, removes low-relevance (+200-300ms)
-└─────────┬───────────┘
-          │
-          ▼  (if enable_graph=True)
-┌─────────────────────┐
-│  4. GRAPH LOOKUP     │  Finds entity relationships
-│                      │  Appends relations WITHOUT reranking vector results
+│  2. PARALLEL SCORING │  Semantic search (vector similarity)
+│                      │  BM25 keyword search (term matching)
+│                      │  Entity matching (entity graph boost)
 └─────────┬───────────┘
           │
           ▼
-    Results + Relations
+┌─────────────────────┐
+│  3. SCORE FUSION     │  Combine signals into single score
+│                      │  Optional: rerank=True for deep reordering
+└─────────┬───────────┘
+          │
+          ▼
+    Results (combined score per memory)
 ```
 
-### Retrieval enhancement combinations
+### v3 Search Defaults
 
-| Configuration | Latency | Best for |
-|--------------|---------|----------|
-| Base search only | ~100ms | Simple lookups |
-| `keyword_search=True` | ~110ms | Entity-heavy queries, broad coverage |
-| `rerank=True` | ~250-300ms | User-facing results, top-N precision |
-| `keyword_search=True` + `rerank=True` | ~310ms | Balanced (recommended for most apps) |
-| `rerank=True` + `filter_memories=True` | ~400-500ms | Safety-critical, production systems |
+| Parameter | Default | Notes |
+|-----------|---------|-------|
+| `top_k` | 20 | Was 100 in v2 |
+| `threshold` | 0.1 | Was None in v2 |
+| `rerank` | False | Was True in v2 |
 
 ### Implicit null scoping
 
-When you search with `user_id="alice"` only, Mem0 returns memories where `agent_id`, `app_id`, and `run_id` are all null. This prevents cross-scope leakage by default.
+When you search with `filters={"user_id": "alice"}` only, Mem0 returns memories where `agent_id`, `app_id`, and `run_id` are all null. This prevents cross-scope leakage by default.
 
 To include memories with non-null fields, use explicit filters:
 ```python
@@ -150,53 +133,23 @@ filters={"OR": [{"user_id": "alice"}]}
 
 ---
 
-## Memory Lifecycle
+## Memory Lifecycle (v3)
 
-```
-CREATE ──→ ACTIVE ──→ UPDATE ──→ ACTIVE
-  │           │                     │
-  │           ▼                     ▼
-  │       EXPIRED              EXPIRED
-  │      (still stored,       (still stored,
-  │       not retrieved)       not retrieved)
-  │           │                     │
-  ▼           ▼                     ▼
-DELETE    DELETE               DELETE
-(permanent)
-```
+v3 uses ADD-only extraction. Memories accumulate over time rather than being consolidated.
 
 ### Creation
-- Triggered by `client.add(messages, user_id="...")`
-- Messages processed through extraction → conflict resolution → storage
-- Gets unique UUID, `created_at` timestamp
-- Optional: custom `timestamp`, `expiration_date`, `metadata`, `immutable`
+- `client.add(messages, user_id="...")`
+- Single-pass extraction → deduplication → storage
+- Returns `{"event_id": "...", "status": "PENDING"}`
 
 ### Updates
-- `client.update(memory_id, text="...")` replaces text and reindexes
-- `client.batch_update([...])` for up to 1000 memories at once
-- Immutable memories (`immutable=True`) cannot be updated — must delete and re-add
-
-### Deduplication
-- Automatic during `add()` with `infer=True`
-- Conflict resolution merges duplicate facts
-- Latest truth wins when contradictions detected
-- Prevents memory bloat from repeated information
-
-### Expiration
-- Optional `expiration_date` parameter (ISO 8601 or `YYYY-MM-DD`)
-- After expiration: memory NOT returned in searches but remains in storage
-- Useful for time-sensitive info (events, temporary preferences, session state)
+- `client.update(memory_id, text="...")` replaces text
+- Batch: `client.batch_update([...])`
 
 ### Deletion
-- Single: `client.delete(memory_id)` — permanent, no recovery
-- Batch: `client.batch_delete([memory_ids])` — up to 1000
-- Bulk: `client.delete_all(user_id="alice")` — all memories for entity
-- `delete_all()` without filters raises error to prevent accidental data loss
-
-### History tracking
-- `client.history(memory_id)` returns version timeline
-- Shows all changes: `{previous_value, new_value, action, timestamps}`
-- Useful for audit trails and debugging
+- Single: `client.delete(memory_id)`
+- Batch: `client.batch_delete([...])`
+- Bulk: `client.delete_all(filters={"user_id": "alice"})`
 
 ---
 
@@ -214,8 +167,6 @@ DELETE    DELETE               DELETE
   "categories": ["health", "preferences"],
   "created_at": "2025-03-12T12:34:56Z",
   "updated_at": "2025-03-12T12:34:56Z",
-  "expiration_date": null,
-  "immutable": false,
   "structured_attributes": {
     "day": 12, "month": 3, "year": 2025,
     "hour": 12, "minute": 34,
@@ -239,8 +190,6 @@ DELETE    DELETE               DELETE
 | `categories` | array | Auto-assigned or custom category tags |
 | `created_at` | datetime | Creation timestamp |
 | `updated_at` | datetime | Last modification timestamp |
-| `expiration_date` | datetime | Auto-expiry date (stops retrieval, data persists) |
-| `immutable` | boolean | If true, prevents modification |
 | `structured_attributes` | object | Temporal breakdown for time-based queries |
 | `score` | float | Semantic similarity (search results only, 0-1) |
 
@@ -322,7 +271,7 @@ Mem0 supports three layers of memory, from shortest to longest lived:
 ```python
 def chat(user_input: str, user_id: str, session_id: str) -> str:
     # 1. Retrieve user memories (long-term preferences)
-    user_mems = mem0.search(user_input, user_id=user_id)
+    user_mems = mem0.search(user_input, filters={"user_id": user_id})
 
     # 2. Retrieve session memories (current task context)
     session_mems = mem0.search(user_input, filters={
@@ -350,18 +299,13 @@ def chat(user_input: str, user_id: str, session_id: str) -> str:
 
 | Operation | Typical Latency |
 |-----------|----------------|
-| Base vector search | ~100ms |
-| + keyword_search | +10ms |
+| Hybrid search (v3 default) | ~100-150ms |
 | + reranking | +150-200ms |
-| + filter_memories | +200-300ms |
-| Add (async, default) | < 50ms response, background processing |
-| Add (sync) | 500ms-2s depending on extraction complexity |
-| Graph operations | Slight overhead for large stores |
+| Add (async) | < 50ms response |
 
 ### Processing
 
-- **Async mode (default):** Returns immediately, processes in background
-- **Sync mode:** Waits for full extraction + storage pipeline
+- **Async (default):** Returns immediately, processes in background
 - **Batch operations:** Up to 1000 memories per batch_update/batch_delete
 - **Webhooks:** Real-time notifications when async processing completes
 

mem0-plugin/skills/mem0/references/features.md

@@ -5,7 +5,7 @@ Additional platform capabilities beyond core CRUD operations.
 ## Table of Contents
 
 - [Advanced Retrieval](#advanced-retrieval)
-- [Graph Memory](#graph-memory)
+- [Entity Linking](#entity-linking)
 - [Custom Categories](#custom-categories)
 - [Custom Instructions](#custom-instructions)
 - [Criteria Retrieval](#criteria-retrieval)
@@ -18,124 +18,58 @@ Additional platform capabilities beyond core CRUD operations.
 
 ## Advanced Retrieval
 
-Three enhancement options for tuning search precision, recall, and latency.
+### Hybrid Search (v3 Default)
 
-### Keyword Search (`keyword_search=True`)
+v3 uses multi-signal hybrid search combining:
+- **Semantic search** (vector similarity)
+- **BM25 keyword search** (normalized term matching)
+- **Entity matching** (entity graph boost)
 
-Expands results to include memories with specific terms, names, and technical keywords.
-
-- Latency: +10ms
-- Recall: Significantly increased
-- Best for: entity-heavy queries, comprehensive coverage
+This is automatic — no configuration needed.
 
 ### Reranking (`rerank=True`)
 
 Deep semantic reordering of results — most relevant first.
 
 - Latency: +150-200ms
-- Accuracy: Significantly improved
+- Default: `False` (was `True` in v2)
 - Best for: user-facing results, top-N precision
 
-### Filter Memories (`filter_memories=True`)
-
-Precision filtering — removes low-relevance results entirely.
-
-- Latency: +200-300ms
-- Precision: Maximized
-- Best for: safety-critical applications, production systems
-
-### Recommended Combinations
-
 **Python:**
 ```python
-# Fast & broad
-results = client.search(query, keyword_search=True, user_id="user123")
-
-# Balanced (recommended for most apps)
-results = client.search(query, keyword_search=True, rerank=True, user_id="user123")
-
-# High precision (critical apps)
-results = client.search(query, rerank=True, filter_memories=True, user_id="user123")
+results = client.search(query, filters={"user_id": "user123"}, rerank=True)
 ```
 
 **TypeScript:**
 ```typescript
 const results = await client.search(query, {
-    user_id: 'user123',
-    keyword_search: true,
+    filters: { user_id: 'user123' },
     rerank: true,
 });
 ```
 
 ---
 
-## Graph Memory
+## Entity Linking
 
-Entity-level knowledge graph that creates relationships between memories.
+v3 replaces graph memory with built-in entity linking. Entities (proper nouns, quoted text, compound noun phrases) are automatically extracted and linked across memories.
 
 ### How It Works
 
-1. **Extraction**: LLM analyzes conversation and identifies entities and relationships
-2. **Storage**: Embeddings go to vector store; entity nodes and edges go to graph store
-3. **Retrieval**: Vector search returns semantic matches; graph relations are appended to results
+1. **Extraction**: During `add()`, entities are automatically extracted from memory text
+2. **Storage**: Entities are stored in a parallel collection (`{collection}_entities`)
+3. **Retrieval**: During `search()`, query entities are matched and used to boost relevant memories
 
-Graph relations **augment** vector results without reordering them. Vector similarity always determines hit sequence.
+Entity linking is automatic — no configuration required. The boost is folded into the combined `score` on each result.
 
-### Enabling Graph Memory
+### v2 Migration Note
 
-**Per request:**
-```python
-client.add(messages, user_id="alice", enable_graph=True)
-client.search("query", user_id="alice", enable_graph=True)
-client.get_all(filters={"AND": [{"user_id": "alice"}]}, enable_graph=True)
-```
+If you were using `enable_graph=True` in v2:
+- Remove `enable_graph` from all API calls
+- Remove `graph_store` from OSS configuration
+- Entity relationships are now consumed through retrieval ranking, not exposed as a separate `relations` array
 
-**Project-level (default for all operations):**
-```python
-client.project.update(enable_graph=True)
-```
-
-```javascript
-await client.updateProject({ enable_graph: true });
-```
-
-### Relation Structure
-
-Each relation in the response contains:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `source` | string | Source entity name |
-| `source_type` | string | Source entity type (e.g., "Person") |
-| `relationship` | string | Relationship label (e.g., "lives_in") |
-| `target` | string | Target entity name |
-| `target_type` | string | Target entity type (e.g., "City") |
-| `score` | number | Confidence score |
-
-**Example:**
-```json
-{
-  "relations": [
-    {
-      "source": "Joseph",
-      "source_type": "Person",
-      "relationship": "lives_in",
-      "target": "Seattle",
-      "target_type": "City",
-      "score": 0.92
-    }
-  ]
-}
-```
-
-### Technical Notes
-
-- Graph Memory adds processing time; see docs for current plan availability
-- Works optimally with rich conversation histories containing entity relationships
-- Best suited for long-running assistants tracking evolving information
-- Graph writes and reads toggle independently per request
-- Multi-agent context supported via `user_id`, `agent_id`, `run_id` scoping
-- Add operations are asynchronous; graph metadata may not be immediately available
+See the [v2 to v3 migration guide](https://docs.mem0.ai/migration/oss-v2-to-v3) for details.
 
 ---
 
@@ -160,7 +94,7 @@ client.project.update(custom_categories=new_categories)
 ```
 
 ```javascript
-await client.updateProject({ custom_categories: new_categories });
+await client.updateProject({ customCategories: newCategories });
 ```
 
 **Retrieve active categories:**
@@ -185,7 +119,7 @@ client.project.update(custom_instructions="Your guidelines here...")
 ```
 
 ```javascript
-await client.updateProject({ custom_instructions: "Your guidelines here..." });
+await client.updateProject({ customInstructions: "Your guidelines here..." });
 ```
 
 ### Template Structure
@@ -229,7 +163,7 @@ client.project.update(retrieval_criteria=retrieval_criteria)
 
 ```typescript
 await client.updateProject({
-    retrieval_criteria: [
+    retrievalCriteria: [
         { name: 'joy', description: 'Positive emotions', weight: 3 },
         { name: 'urgency', description: 'Time-sensitive items', weight: 4 },
     ],
@@ -281,7 +215,7 @@ for item in feedback_data:
 ```typescript
 await client.feedback('mem-123', {
     feedback: 'POSITIVE',
-    feedback_reason: 'Accurately captured dietary preference',
+    feedbackReason: 'Accurately captured dietary preference',
 });
 ```
 
@@ -349,23 +283,18 @@ Use the `name` field in messages to identify speakers. Mem0 maps names to entity
 
 ## MCP Integration
 
-Model Context Protocol integration enables AI clients (Claude Desktop, Cursor, custom agents) to manage Mem0 memory autonomously.
+Model Context Protocol integration enables AI clients (Claude, Claude Code, Cursor, Windsurf, VS Code, OpenCode) to manage Mem0 memory autonomously.
 
-### Configuration
+### Setup
 
-```json
-{
-  "mcpServers": {
-    "mem0": {
-      "command": "uvx",
-      "args": ["mem0-mcp-server"],
-      "env": {
-        "MEM0_API_KEY": "m0-your-api-key",
-        "MEM0_DEFAULT_USER_ID": "your-user-id"
-      }
-    }
-  }
-}
+Add Mem0 MCP to your clients with a single command:
+
+```bash
+npx mcp-add \
+  --name mem0-mcp \
+  --type http \
+  --url "https://mcp.mem0.ai/mcp" \
+  --clients "claude,claude code,cursor,windsurf,vscode,opencode"
 ```
 
 ### Available MCP Tools
@@ -377,7 +306,7 @@ The MCP server exposes 9 memory tools that AI agents can use autonomously:
 
 ### How It Works
 
-1. Configure the MCP server in your AI client
+1. Add Mem0 MCP to your AI client using the setup command above
 2. The agent autonomously decides when to store/retrieve memories
 3. No manual API calls needed — the agent manages memory as part of its reasoning
 

mem0-plugin/skills/mem0/references/integration-patterns.md

@@ -27,7 +27,7 @@ from langchain_core.messages import SystemMessage, HumanMessage
 from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
 from mem0 import MemoryClient
 
-llm = ChatOpenAI(model="gpt-4.1-nano-2025-04-14")
+llm = ChatOpenAI(model="gpt-5-mini")
 mem0 = MemoryClient()
 
 prompt = ChatPromptTemplate.from_messages([
@@ -38,7 +38,7 @@ prompt = ChatPromptTemplate.from_messages([
 
 def retrieve_context(query: str, user_id: str):
     """Retrieve relevant memories from Mem0"""
-    memories = mem0.search(query, user_id=user_id)
+    memories = mem0.search(query, filters={"user_id": user_id})
     memory_list = memories['results']
     serialized = ' '.join([m["memory"] for m in memory_list])
     return [
@@ -116,73 +116,24 @@ result = crew.kickoff()
 
 ## Vercel AI SDK
 
-Source: [docs.mem0.ai/integrations/vercel-ai-sdk](https://docs.mem0.ai/integrations/vercel-ai-sdk)
+> **Dedicated skill available.** For comprehensive Vercel AI SDK documentation, see the [mem0-vercel-ai-sdk skill](https://github.com/mem0ai/mem0/tree/main/skills/mem0-vercel-ai-sdk).
 
 Install: `npm install @mem0/vercel-ai-provider`
 
-### Basic Text Generation with Memory
+Quick example (wrapped model with automatic memory):
 
 ```typescript
 import { generateText } from "ai";
 import { createMem0 } from "@mem0/vercel-ai-provider";
 
-const mem0 = createMem0({
-    provider: "openai",
-    mem0ApiKey: "m0-xxx",
-    apiKey: "openai-api-key",
-});
-
-const { text } = await generateText({
-    model: mem0("gpt-4-turbo", { user_id: "borat" }),
-    prompt: "Suggest me a good car to buy!",
-});
-```
-
-### Streaming with Memory
-
-```typescript
-import { streamText } from "ai";
-import { createMem0 } from "@mem0/vercel-ai-provider";
-
 const mem0 = createMem0();
-
-const { textStream } = streamText({
-    model: mem0("gpt-4-turbo", { user_id: "borat" }),
+const { text } = await generateText({
+    model: mem0("gpt-5-mini", { user_id: "borat" }),
     prompt: "Suggest me a good car to buy!",
 });
-
-for await (const textPart of textStream) {
-    process.stdout.write(textPart);
-}
 ```
 
-### Using Memory Utilities Standalone
-
-```typescript
-import { openai } from "@ai-sdk/openai";
-import { generateText } from "ai";
-import { retrieveMemories, addMemories } from "@mem0/vercel-ai-provider";
-
-// Retrieve memories and inject into any provider
-const prompt = "Suggest me a good car to buy.";
-const memories = await retrieveMemories(prompt, { user_id: "borat", mem0ApiKey: "m0-xxx" });
-
-const { text } = await generateText({
-    model: openai("gpt-4-turbo"),
-    prompt: prompt,
-    system: memories,
-});
-
-// Store new memories
-await addMemories(
-    [{ role: "user", content: [{ type: "text", text: "I love red cars." }] }],
-    { user_id: "borat", mem0ApiKey: "m0-xxx" }
-);
-```
-
-### Supported Providers
-
-`openai`, `anthropic`, `google`, `groq`
+Supported providers: `openai`, `anthropic`, `google`, `groq`, `cohere`
 
 ---
 
@@ -199,7 +150,7 @@ mem0 = MemoryClient()
 @function_tool
 def search_memory(query: str, user_id: str) -> str:
     """Search through past conversations and memories"""
-    memories = mem0.search(query, user_id=user_id, top_k=3)
+    memories = mem0.search(query, filters={"user_id": user_id}, top_k=3)
     if memories and memories.get('results'):
         return "\n".join([f"- {mem['memory']}" for mem in memories['results']])
     return "No relevant memories found."
@@ -216,7 +167,7 @@ agent = Agent(
     Use search_memory to recall past conversations.
     Use save_memory to store important information.""",
     tools=[search_memory, save_memory],
-    model="gpt-4.1-nano-2025-04-14"
+    model="gpt-5-mini"
 )
 
 result = Runner.run_sync(agent, "I love Italian food and I'm planning a trip to Rome next month")
@@ -232,21 +183,21 @@ travel_agent = Agent(
     name="Travel Planner",
     instructions="You are a travel planning specialist. Use search_memory and save_memory tools.",
     tools=[search_memory, save_memory],
-    model="gpt-4.1-nano-2025-04-14"
+    model="gpt-5-mini"
 )
 
 health_agent = Agent(
     name="Health Advisor",
     instructions="You are a health and wellness advisor. Use search_memory and save_memory tools.",
     tools=[search_memory, save_memory],
-    model="gpt-4.1-nano-2025-04-14"
+    model="gpt-5-mini"
 )
 
 triage_agent = Agent(
     name="Personal Assistant",
     instructions="""Route travel questions to Travel Planner, health questions to Health Advisor.""",
     handoffs=[travel_agent, health_agent],
-    model="gpt-4.1-nano-2025-04-14"
+    model="gpt-5-mini"
 )
 
 result = Runner.run_sync(triage_agent, "Plan a healthy meal for my Italy trip")
@@ -303,7 +254,7 @@ from langchain_openai import ChatOpenAI
 from mem0 import MemoryClient
 from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
 
-llm = ChatOpenAI(model="gpt-4")
+llm = ChatOpenAI(model="gpt-5-mini")
 mem0 = MemoryClient()
 
 class State(TypedDict):
@@ -315,7 +266,7 @@ def chatbot(state: State):
     user_id = state["mem0_user_id"]
 
     # Retrieve relevant memories
-    memories = mem0.search(messages[-1].content, user_id=user_id)
+    memories = mem0.search(messages[-1].content, filters={"user_id": user_id})
     context = "Relevant context:\n"
     for memory in memories["results"]:
         context += f"- {memory['memory']}\n"
@@ -368,7 +319,7 @@ memory = Mem0Memory.from_client(
 from llama_index.core.agent import FunctionCallingAgent
 from llama_index.llms.openai import OpenAI
 
-llm = OpenAI(model="gpt-4")
+llm = OpenAI(model="gpt-5-mini")
 agent = FunctionCallingAgent.from_tools(
     tools=[],
     llm=llm,
@@ -401,14 +352,14 @@ USER_ID = "alice"
 
 agent = ConversableAgent(
     "chatbot",
-    llm_config={"config_list": [{"model": "gpt-4", "api_key": os.environ["OPENAI_API_KEY"]}]},
+    llm_config={"config_list": [{"model": "gpt-5-mini", "api_key": os.environ["OPENAI_API_KEY"]}]},
     code_execution_config=False,
     human_input_mode="NEVER",
 )
 
 def get_context_aware_response(question: str) -> str:
     # Retrieve memories for context
-    relevant_memories = memory_client.search(question, user_id=USER_ID)
+    relevant_memories = memory_client.search(question, filters={"user_id": USER_ID})
     context = "\n".join([m["memory"] for m in relevant_memories.get("results", [])])
 
     prompt = f"""Answer considering previous interactions:

mem0-plugin/skills/mem0/references/quickstart.md

@@ -27,7 +27,7 @@ messages = [
 client.add(messages, user_id="user123")
 
 # Search memories
-results = client.search("What are my dietary restrictions?", user_id="user123")
+results = client.search("What are my dietary restrictions?", filters={"user_id": "user123"})
 print(results)
 ```
 
@@ -39,7 +39,7 @@ from mem0 import AsyncMemoryClient
 client = AsyncMemoryClient(api_key="your-api-key")
 
 await client.add(messages, user_id="user123")
-results = await client.search("query", user_id="user123")
+results = await client.search("query", filters={"user_id": "user123"})
 ```
 
 ## TypeScript / JavaScript Setup
@@ -59,11 +59,11 @@ const messages = [
     {"role": "user", "content": "I'm a vegetarian and allergic to nuts."},
     {"role": "assistant", "content": "Got it! I'll remember your dietary preferences."}
 ];
-await client.add(messages, { user_id: "user123" });
+await client.add(messages, { userId: "user123" });
 
 // Search memories
 const results = await client.search("What are my dietary restrictions?", {
-    user_id: "user123"
+    filters: { user_id: "user123" }
 });
 console.log(results);
 ```
@@ -86,7 +86,7 @@ curl -X POST https://api.mem0.ai/v1/memories/ \
   }'
 
 # Search memories
-curl -X POST https://api.mem0.ai/v2/memories/search/ \
+curl -X POST https://api.mem0.ai/v3/memories/search/ \
   -H "Authorization: Token $MEM0_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{

mem0-plugin/skills/mem0/references/sdk-guide.md

@@ -2,6 +2,8 @@
 
 Complete SDK reference for Python and TypeScript. All methods use `MemoryClient` (Platform API).
 
+> **For language-specific deep references (including OSS):** See [client/python.md](../client/python.md) and [client/node.md](../client/node.md). For Python vs TypeScript differences: [client/differences.md](../client/differences.md).
+
 ## Initialization
 
 **Python:**
@@ -38,16 +40,12 @@ client.add(messages, user_id="alice")
 
 # With metadata
 client.add(messages, user_id="alice", metadata={"source": "onboarding"})
-
-# With graph memory
-client.add(messages, user_id="alice", enable_graph=True)
 ```
 
 **TypeScript:**
 ```typescript
-await client.add(messages, { user_id: "alice" });
-await client.add(messages, { user_id: "alice", metadata: { source: "onboarding" } });
-await client.add(messages, { user_id: "alice", enable_graph: true });
+await client.add(messages, { userId: "alice" });
+await client.add(messages, { userId: "alice", metadata: { source: "onboarding" } });
 ```
 
 ### Parameters
@@ -59,32 +57,14 @@ await client.add(messages, { user_id: "alice", enable_graph: true });
 | `agent_id` | string | Agent identifier |
 | `run_id` | string | Session identifier |
 | `metadata` | object | Custom key-value pairs |
-| `enable_graph` | boolean | Activate knowledge graph |
 | `infer` | boolean | If `false`, store raw text without inference (default: `true`) |
-| `immutable` | boolean | Prevents modification after creation |
-| `expiration_date` | string | Auto-expiry date (`YYYY-MM-DD`) |
-| `includes` | string | Preference filters for inclusion |
-| `excludes` | string | Preference filters for exclusion |
-| `async_mode` | boolean | Async processing (default: `true`). Set `false` to wait |
 
 ### Advanced Add Options
 
 ```python
-# Immutable -- cannot be modified or overwritten
-client.add(messages, user_id="alice", immutable=True)
-
-# Expiring memory
-client.add(messages, user_id="alice", expiration_date="2025-12-31")
-
-# Selective extraction
-client.add(messages, user_id="alice", includes="dietary preferences", excludes="payment info")
-
 # Agent + session scoping
 client.add(messages, user_id="alice", agent_id="nutrition-agent", run_id="session-456")
 
-# Synchronous processing (wait for completion)
-client.add(messages, user_id="alice", async_mode=False)
-
 # Raw text -- skip LLM inference
 client.add(
     [{"role": "user", "content": "User prefers dark mode."}],
@@ -99,7 +79,7 @@ client.add(
 
 **Python:**
 ```python
-results = client.search("dietary preferences?", user_id="alice")
+results = client.search("dietary preferences?", filters={"user_id": "alice"})
 
 # With filters and reranking
 results = client.search(
@@ -109,20 +89,14 @@ results = client.search(
     rerank=True,
     threshold=0.5
 )
-
-# With graph relations
-results = client.search("colleagues", user_id="alice", enable_graph=True)
-
-# Keyword search
-results = client.search("vegetarian", user_id="alice", keyword_search=True)
 ```
 
 **TypeScript:**
 ```typescript
-const results = await client.search("dietary preferences", { user_id: "alice" });
+const results = await client.search("dietary preferences", { filters: { user_id: "alice" } });
 const results = await client.search("work experience", {
     filters: { AND: [{ user_id: "alice" }, { categories: { contains: "professional_details" } }] },
-    top_k: 5,
+    topK: 5,
     rerank: true,
 });
 ```
@@ -132,19 +106,17 @@ const results = await client.search("work experience", {
 | Name | Type | Description |
 |------|------|-------------|
 | `query` | string | Natural language search query |
-| `user_id` | string | Filter by user |
-| `filters` | object | V2 filter object (AND/OR operators) |
-| `top_k` | number | Number of results (default: 10) |
-| `rerank` | boolean | Enable reranking for better relevance |
-| `threshold` | number | Minimum similarity score (default: 0.3) |
-| `keyword_search` | boolean | Use keyword-based search |
-| `enable_graph` | boolean | Include graph relations |
+| `filters` | object | Filter object (AND/OR operators). Use `{"user_id": "..."}` to filter by user |
+| `top_k` | number | Number of results (default: 10 for Platform) |
+| `rerank` | boolean | Enable reranking for better relevance (default: `false`) |
+| `threshold` | number | Minimum similarity score (default: 0.1) |
 
 ### Common Filter Patterns
 
+**Python:**
 ```python
-# Single user (shorthand)
-client.search("query", user_id="alice")
+# Single user filter
+filters={"user_id": "alice"}
 
 # OR across agents
 filters={"OR": [{"user_id": "alice"}, {"agent_id": {"in": ["travel-agent", "sports-agent"]}}]}
@@ -177,6 +149,21 @@ filters={"AND": [
 ]}
 ```
 
+**TypeScript:**
+```typescript
+// Single user filter
+filters: { user_id: "alice" }
+
+// OR across agents
+filters: { OR: [{ user_id: "alice" }, { agent_id: { in: ["travel-agent", "sports-agent"] } }] }
+
+// Category filtering (partial match)
+filters: { AND: [{ user_id: "alice" }, { categories: { contains: "finance" } }] }
+
+// Category filtering (exact match)
+filters: { AND: [{ user_id: "alice" }, { categories: { in: ["personal_information"] } }] }
+```
+
 ---
 
 ## get() / getAll() -- Retrieve Memories
@@ -187,7 +174,7 @@ filters={"AND": [
 memory = client.get(memory_id="ea925981-...")
 
 # All memories for a user
-memories = client.get_all(filters={"AND": [{"user_id": "alice"}]})
+memories = client.get_all(filters={"user_id": "alice"})
 
 # With date range
 memories = client.get_all(
@@ -196,15 +183,12 @@ memories = client.get_all(
         {"created_at": {"gte": "2024-07-01", "lte": "2024-07-31"}}
     ]}
 )
-
-# With graph data
-memories = client.get_all(filters={"AND": [{"user_id": "alice"}]}, enable_graph=True)
 ```
 
 **TypeScript:**
 ```typescript
 const memory = await client.get("ea925981-...");
-const memories = await client.getAll({ filters: { AND: [{ user_id: "alice" }] } });
+const memories = await client.getAll({ filters: { user_id: "alice" } });
 ```
 
 **Note:** `get_all` requires at least one of `user_id`, `agent_id`, `app_id`, or `run_id` in filters.
@@ -224,8 +208,6 @@ client.update(memory_id="ea925981-...", text="Updated", metadata={"verified": Tr
 await client.update("ea925981-...", { text: "Updated: vegan since 2024" });
 ```
 
-Cannot update immutable memories.
-
 ---
 
 ## delete() / deleteAll() -- Remove Memories
@@ -239,7 +221,7 @@ client.delete_all(user_id="alice")  # Irreversible bulk delete
 **TypeScript:**
 ```typescript
 await client.delete("ea925981-...");
-await client.deleteAll({ user_id: "alice" });
+await client.deleteAll({ userId: "alice" });
 ```
 
 ---
@@ -299,10 +281,73 @@ data = client.get_memory_export(memory_export_id=export["id"])
 2. **SQL operators rejected** -- use `gte`, `lt`, etc. Not `>=`, `<`.
 3. **Metadata filtering is limited** -- only top-level keys with `eq`, `contains`, `ne`.
 4. **Wildcard `*` excludes null** -- only matches non-null values.
-5. **Default threshold is 0.3** -- increase for stricter matching.
+5. **Default threshold is 0.1** -- increase for stricter matching.
 6. **Async processing** -- memories process asynchronously. Wait 2-3s after `add()` before searching.
-7. **Immutable memories** -- cannot be updated or deleted once created.
 
 ## Naming Conventions
 
-Python uses `snake_case` (`user_id`, `memory_id`, `get_all`). TypeScript uses `camelCase` for methods (`getAll`, `deleteAll`, `batchUpdate`) but `snake_case` for API parameters (`user_id`, `agent_id`).
+Python uses `snake_case` everywhere (`user_id`, `memory_id`, `get_all`). TypeScript uses `camelCase` for methods (`getAll`, `deleteAll`, `batchUpdate`) and top-level parameters (`userId`, `topK`, `pageSize`), but filter keys use `snake_case` (`user_id`, `agent_id`).
+
+---
+
+## v2 to v3 Migration
+
+### Breaking Changes in v3
+
+**1. Entity IDs in search() and getAll()**
+
+v3 requires entity IDs (`user_id`, `agent_id`, `run_id`) inside `filters` instead of as top-level parameters:
+
+```python
+# v2 (deprecated)
+client.search("query", user_id="alice")
+client.get_all(user_id="alice")
+
+# v3
+client.search("query", filters={"user_id": "alice"})
+client.get_all(filters={"user_id": "alice"})
+```
+
+```typescript
+// v2 (deprecated)
+await client.search("query", { user_id: "alice" });
+await client.getAll({ user_id: "alice" });
+
+// v3
+await client.search("query", { filters: { user_id: "alice" } });
+await client.getAll({ filters: { user_id: "alice" } });
+```
+
+**2. TypeScript Parameter Naming**
+
+v3 TypeScript uses camelCase for all parameters:
+
+| v2 | v3 |
+|----|-----|
+| `user_id` | `userId` |
+| `agent_id` | `agentId` |
+| `run_id` | `runId` |
+| `top_k` | `topK` |
+| `page_size` | `pageSize` |
+
+**3. Default Values Changed**
+
+| Parameter | v2 Default | v3 Default |
+|-----------|------------|------------|
+| `threshold` | 0.3 | 0.1 |
+| `rerank` | (not specified) | `false` |
+
+**4. Removed Parameters**
+
+The following parameters are no longer supported:
+
+| Parameter | Status |
+|-----------|--------|
+| `enable_graph` | Removed from add/search/getAll |
+| `keyword_search` | Removed from search |
+| `filter_memories` | Removed |
+| `immutable` | Removed from add |
+| `expiration_date` | Removed from add |
+| `includes` | Removed from add |
+| `excludes` | Removed from add |
+| `async_mode` | Removed from add |

mem0-plugin/skills/mem0/references/use-cases.md

@@ -39,7 +39,7 @@ Use these known facts about the user to personalize your response:
 {context if context else 'No prior context yet.'}"""
 
     response = openai_client.chat.completions.create(
-        model="gpt-4.1-nano-2025-04-14",
+        model="gpt-5-mini",
         messages=[
             {"role": "system", "content": system_prompt},
             {"role": "user", "content": user_input},
@@ -72,14 +72,14 @@ const openai = new OpenAI();
 
 async function chat(userInput: string, userId: string): Promise<string> {
     // 1. Retrieve relevant memories
-    const memories = await mem0.search(userInput, { user_id: userId });
+    const memories = await mem0.search(userInput, { filters: { user_id: userId } });
     const context = memories.results
         ?.map((m: any) => `- ${m.memory}`)
         .join('\n') || 'No prior context yet.';
 
     // 2. Generate response with memory context
     const response = await openai.chat.completions.create({
-        model: 'gpt-4.1-nano-2025-04-14',
+        model: 'gpt-5-mini',
         messages: [
             { role: 'system', content: `You are Ray, a personal fitness coach.\nUser context:\n${context}` },
             { role: 'user', content: userInput },
@@ -90,7 +90,7 @@ async function chat(userInput: string, userId: string): Promise<string> {
     // 3. Store interaction
     await mem0.add(
         [{ role: 'user', content: userInput }, { role: 'assistant', content: reply }],
-        { user_id: userId }
+        { userId: userId }
     );
     return reply;
 }
@@ -182,7 +182,7 @@ await client.updateProject({
 async function logInteraction(userId: string, message: string, priority = 'normal') {
     await client.add(
         [{ role: 'user', content: message }],
-        { user_id: userId, metadata: { priority, source: 'support_chat' } }
+        { userId: userId, metadata: { priority, source: 'support_chat' } }
     );
 }
 
@@ -230,7 +230,7 @@ def consult(user_id: str, question: str) -> str:
     context = "\n".join([f"- {m['memory']}" for m in memories.get("results", [])])
 
     response = openai_client.chat.completions.create(
-        model="gpt-4.1-nano-2025-04-14",
+        model="gpt-5-mini",
         messages=[
             {"role": "system", "content": f"You are a health coach. Patient context:\n{context}"},
             {"role": "user", "content": question},
@@ -264,20 +264,20 @@ const openai = new OpenAI();
 async function savePatientInfo(userId: string, info: string) {
     await mem0.add(
         [{ role: 'user', content: info }],
-        { user_id: userId, run_id: 'healthcare_session', metadata: { type: 'patient_information' } }
+        { userId: userId, runId: 'healthcare_session', metadata: { type: 'patient_information' } }
     );
 }
 
 async function consult(userId: string, question: string): Promise<string> {
     const memories = await mem0.search(question, {
-        user_id: userId,
-        top_k: 5,
+        filters: { user_id: userId },
+        topK: 5,
         threshold: 0.7,
     });
     const context = memories.results?.map((m: any) => `- ${m.memory}`).join('\n') || '';
 
     const response = await openai.chat.completions.create({
-        model: 'gpt-4.1-nano-2025-04-14',
+        model: 'gpt-5-mini',
         messages: [
             { role: 'system', content: `You are a health coach. Patient context:\n${context}` },
             { role: 'user', content: question },
@@ -287,7 +287,7 @@ async function consult(userId: string, question: string): Promise<string> {
 
     await mem0.add(
         [{ role: 'user', content: question }, { role: 'assistant', content: reply }],
-        { user_id: userId, run_id: 'healthcare_session' }
+        { userId: userId, runId: 'healthcare_session' }
     );
     return reply;
 }
@@ -333,7 +333,7 @@ def draft_content(user_id: str, topic: str) -> str:
     style_context = "\n".join([f"- {m['memory']}" for m in prefs.get("results", [])])
 
     response = openai_client.chat.completions.create(
-        model="gpt-4.1-nano-2025-04-14",
+        model="gpt-5-mini",
         messages=[
             {"role": "system", "content": f"Write content matching these style preferences:\n{style_context}"},
             {"role": "user", "content": f"Write a blog post about: {topic}"},
@@ -359,7 +359,7 @@ const openai = new OpenAI();
 async function storePreferences(userId: string, preferences: string) {
     await mem0.add(
         [{ role: 'user', content: preferences }],
-        { user_id: userId, run_id: 'editing_session', metadata: { type: 'preferences' } }
+        { userId: userId, runId: 'editing_session', metadata: { type: 'preferences' } }
     );
 }
 
@@ -370,7 +370,7 @@ async function draftContent(userId: string, topic: string): Promise<string> {
     const styleContext = prefs.results?.map((m: any) => `- ${m.memory}`).join('\n') || '';
 
     const response = await openai.chat.completions.create({
-        model: 'gpt-4.1-nano-2025-04-14',
+        model: 'gpt-5-mini',
         messages: [
             { role: 'system', content: `Write content matching these preferences:\n${styleContext}` },
             { role: 'user', content: `Write a blog post about: ${topic}` },
@@ -465,10 +465,10 @@ async function storeScopedMemory(
     userId: string, agentId: string, runId: string, appId: string
 ) {
     await client.add(messages, {
-        user_id: userId,
-        agent_id: agentId,
-        run_id: runId,
-        app_id: appId,
+        userId: userId,
+        agentId: agentId,
+        runId: runId,
+        appId: appId,
     });
 }
 
@@ -520,7 +520,7 @@ def personalized_search(user_id: str, query: str, search_results: list) -> str:
     user_context = "\n".join([f"- {m['memory']}" for m in memories.get("results", [])])
 
     response = openai_client.chat.completions.create(
-        model="gpt-4.1-nano-2025-04-14",
+        model="gpt-5-mini",
         messages=[
             {"role": "system", "content": f"Personalize search results using user context:\n{user_context}"},
             {"role": "user", "content": f"Query: {query}\n\nSearch results:\n{search_results}"},
@@ -551,11 +551,11 @@ const mem0 = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
 const openai = new OpenAI();
 
 async function personalizedSearch(userId: string, query: string, searchResults: string[]): Promise<string> {
-    const memories = await mem0.search(query, { user_id: userId, top_k: 5 });
+    const memories = await mem0.search(query, { filters: { user_id: userId }, topK: 5 });
     const context = memories.results?.map((m: any) => `- ${m.memory}`).join('\n') || '';
 
     const response = await openai.chat.completions.create({
-        model: 'gpt-4.1-nano-2025-04-14',
+        model: 'gpt-5-mini',
         messages: [
             { role: 'system', content: `Personalize results using user context:\n${context}` },
             { role: 'user', content: `Query: ${query}\nResults: ${searchResults.join(', ')}` },
@@ -563,7 +563,7 @@ async function personalizedSearch(userId: string, query: string, searchResults:
     });
     const reply = response.choices[0].message.content!;
 
-    await mem0.add([{ role: 'user', content: query }], { user_id: userId });
+    await mem0.add([{ role: 'user', content: query }], { userId: userId });
     return reply;
 }
 ```
@@ -631,14 +631,14 @@ const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
 async function storeEmail(userId: string, sender: string, subject: string, body: string, date: string) {
     await client.add(
         [{ role: 'user', content: `Email from ${sender}: ${subject}\n\n${body}` }],
-        { user_id: userId, metadata: { email_type: 'incoming', sender, subject, date } }
+        { userId: userId, metadata: { email_type: 'incoming', sender, subject, date } }
     );
 }
 
 async function searchEmails(userId: string, query: string) {
     return client.search(query, {
         filters: { AND: [{ user_id: userId }, { categories: { contains: 'email' } }] },
-        top_k: 10,
+        topK: 10,
     });
 }
 ```

mem0-ts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mem0ai",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "The Memory Layer For Your AI Apps",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

mem0-ts/src/client/config.ts

@@ -0,0 +1,165 @@
+/**
+ * Best-effort read/write of ~/.mem0/config.json from the TS SDK.
+ *
+ * Used to stitch PostHog identities: SDKs and CLIs persist anonymous
+ * distinct_id values here, and the TS MemoryClient reads those on init to
+ * fire $identify and merge them into the email identity.
+ *
+ * Node-only. Browsers (no `process.versions.node`) no-op.
+ */
+
+export interface Mem0AnonIds {
+  oss?: string;
+  cli?: string;
+  aliasedPairs: string[];
+}
+
+interface NodeFs {
+  fs: typeof import("fs");
+  path: typeof import("path");
+  crypto: typeof import("crypto");
+  configPath: string;
+}
+
+async function getNodeFs(): Promise<NodeFs | null> {
+  if (typeof process === "undefined" || !process.versions?.node) return null;
+  try {
+    const [fs, path, os, crypto] = await Promise.all([
+      import("fs"),
+      import("path"),
+      import("os"),
+      import("crypto"),
+    ]);
+    const fsMod = (fs as any).default ?? fs;
+    const pathMod = (path as any).default ?? path;
+    const osMod = (os as any).default ?? os;
+    const cryptoMod = (crypto as any).default ?? crypto;
+    const dir = process.env.MEM0_DIR || pathMod.join(osMod.homedir(), ".mem0");
+    return {
+      fs: fsMod,
+      path: pathMod,
+      crypto: cryptoMod,
+      configPath: pathMod.join(dir, "config.json"),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function loadConfig(node: NodeFs): Record<string, any> | null {
+  try {
+    if (!node.fs.existsSync(node.configPath)) return null;
+    const parsed = JSON.parse(node.fs.readFileSync(node.configPath, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeConfig(node: NodeFs, config: Record<string, any>): void {
+  node.fs.mkdirSync(node.path.dirname(node.configPath), { recursive: true });
+  node.fs.writeFileSync(node.configPath, JSON.stringify(config, null, 4));
+}
+
+function aliasPairMarker(node: NodeFs, anonId: string, email: string): string {
+  return node.crypto
+    .createHash("sha256")
+    .update(`${anonId}\0${email}`, "utf8")
+    .digest("hex");
+}
+
+function randomUserId(node: NodeFs): string {
+  if (typeof node.crypto.randomUUID === "function") {
+    return node.crypto.randomUUID();
+  }
+  return (
+    Math.random().toString(36).substring(2, 15) +
+    Math.random().toString(36).substring(2, 15)
+  );
+}
+
+export async function getOrCreateMem0UserId(): Promise<string | null> {
+  const node = await getNodeFs();
+  if (!node) return null;
+  try {
+    const config = loadConfig(node) ?? {};
+    if (typeof config.user_id === "string" && config.user_id) {
+      return config.user_id;
+    }
+    const userId = randomUserId(node);
+    config.user_id = userId;
+    writeConfig(node, config);
+    return userId;
+  } catch {
+    return null;
+  }
+}
+
+export async function readMem0AnonIds(): Promise<Mem0AnonIds | null> {
+  const node = await getNodeFs();
+  if (!node) return null;
+  const config = loadConfig(node);
+  if (!config) return null;
+  const telemetry =
+    config.telemetry && typeof config.telemetry === "object"
+      ? config.telemetry
+      : {};
+  return {
+    oss: typeof config.user_id === "string" ? config.user_id : undefined,
+    cli:
+      typeof telemetry.anonymous_id === "string"
+        ? telemetry.anonymous_id
+        : undefined,
+    aliasedPairs: Array.isArray(telemetry.aliased_pairs)
+      ? telemetry.aliased_pairs.filter(
+          (item: unknown) => typeof item === "string",
+        )
+      : [],
+  };
+}
+
+export async function isMem0Aliased(
+  anonId: string,
+  email: string,
+): Promise<boolean> {
+  if (!anonId || !email) return false;
+  const node = await getNodeFs();
+  if (!node) return false;
+  const config = loadConfig(node);
+  if (!config) return false;
+  const telemetry =
+    config.telemetry && typeof config.telemetry === "object"
+      ? config.telemetry
+      : {};
+  const aliasedPairs = Array.isArray(telemetry.aliased_pairs)
+    ? telemetry.aliased_pairs
+    : [];
+  return aliasedPairs.includes(aliasPairMarker(node, anonId, email));
+}
+
+export async function markMem0Aliased(
+  anonId: string,
+  email: string,
+): Promise<void> {
+  const node = await getNodeFs();
+  if (!node) return;
+  try {
+    const config = loadConfig(node) ?? {};
+    const telemetry =
+      config.telemetry && typeof config.telemetry === "object"
+        ? config.telemetry
+        : {};
+    const aliasedPairs = Array.isArray(telemetry.aliased_pairs)
+      ? telemetry.aliased_pairs
+      : [];
+    const marker = aliasPairMarker(node, anonId, email);
+    if (!aliasedPairs.includes(marker)) {
+      aliasedPairs.push(marker);
+    }
+    telemetry.aliased_pairs = aliasedPairs;
+    config.telemetry = telemetry;
+    writeConfig(node, config);
+  } catch {
+    // Best-effort: read-only filesystems and unwritable paths just skip.
+  }
+}

mem0-ts/src/client/mem0.ts

@@ -20,7 +20,18 @@ import {
   CreateMemoryExportPayload,
   GetMemoryExportPayload,
 } from "./mem0.types";
-import { captureClientEvent, generateHash } from "./telemetry";
+import {
+  captureClientEvent,
+  generateHash,
+  isTelemetryEnabled,
+  telemetry,
+} from "./telemetry";
+import {
+  getOrCreateMem0UserId,
+  isMem0Aliased,
+  markMem0Aliased,
+  readMem0AnonIds,
+} from "./config";
 import { camelToSnake, camelToSnakeKeys, snakeToCamelKeys } from "./utils";
 import { createExceptionFromResponse, MemoryError } from "../common/exceptions";
 
@@ -118,6 +129,8 @@ export default class MemoryClient {
         this.telemetryId = generateHash(this.apiKey);
       }
 
+      await this._maybeAliasAnonToEmail();
+
       captureClientEvent("init", this, {
         client_type: "MemoryClient",
       }).catch((error: any) => {
@@ -132,6 +145,30 @@ export default class MemoryClient {
     }
   }
 
+  private async _maybeAliasAnonToEmail(): Promise<void> {
+    if (!isTelemetryEnabled()) return;
+    try {
+      const email = this.telemetryId;
+      if (!email || !email.includes("@")) return;
+      const sharedAnonId = await getOrCreateMem0UserId();
+      const anonIds = await readMem0AnonIds();
+      if (!anonIds && !sharedAnonId) return;
+      const candidates = [anonIds?.oss || sharedAnonId, anonIds?.cli].filter(
+        (id): id is string => !!id && id !== email,
+      );
+      const seen = new Set<string>();
+      for (const anonId of candidates) {
+        if (seen.has(anonId) || (await isMem0Aliased(anonId, email))) continue;
+        seen.add(anonId);
+        if (await telemetry.captureIdentify(anonId, email)) {
+          await markMem0Aliased(anonId, email);
+        }
+      }
+    } catch (error: any) {
+      console.error("Failed to alias telemetry identity:", error);
+    }
+  }
+
   private _captureEvent(methodName: string, args: any[]) {
     captureClientEvent(methodName, this, {
       success: true,

mem0-ts/src/client/mem0.types.ts

@@ -50,6 +50,13 @@ export interface PromptUpdatePayload {
   memoryDepth?: string | null;
   usecaseSetting?: string | number;
   multilingual?: boolean;
+  /**
+   * Toggle Memory Decay for this project. When `true`, search-time ranking
+   * boosts recently-used memories and gently dampens stale ones; when `false`,
+   * ranking is restored to the pre-decay behaviour. Off by default.
+   * See https://docs.mem0.ai/platform/features/memory-decay
+   */
+  decay?: boolean;
   [key: string]: any;
 }
 

mem0-ts/src/client/telemetry.ts

@@ -32,8 +32,12 @@ class UnifiedTelemetry implements TelemetryClient {
     this.host = host;
   }
 
-  async captureEvent(distinctId: string, eventName: string, properties = {}) {
-    if (!MEM0_TELEMETRY) return;
+  async captureEvent(
+    distinctId: string,
+    eventName: string,
+    properties = {},
+  ): Promise<boolean> {
+    if (!MEM0_TELEMETRY) return false;
 
     const eventProperties = {
       client_version: version,
@@ -61,9 +65,50 @@ class UnifiedTelemetry implements TelemetryClient {
 
       if (!response.ok) {
         console.error("Telemetry event capture failed:", await response.text());
+        return false;
       }
+      return true;
     } catch (error) {
       console.error("Telemetry event capture failed:", error);
+      return false;
+    }
+  }
+
+  async captureIdentify(anonId: string, email: string): Promise<boolean> {
+    if (!MEM0_TELEMETRY) return false;
+    if (!anonId || !email || anonId === email) return false;
+
+    const payload = {
+      api_key: this.apiKey,
+      distinct_id: email,
+      event: "$identify",
+      properties: {
+        $anon_distinct_id: anonId,
+        client_source: "typescript",
+        $lib: "posthog-node",
+      },
+    };
+
+    try {
+      const response = await fetch(this.host, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(payload),
+      });
+
+      if (!response.ok) {
+        console.error(
+          "Telemetry identify capture failed:",
+          await response.text(),
+        );
+        return false;
+      }
+      return true;
+    } catch (error) {
+      console.error("Telemetry identify capture failed:", error);
+      return false;
     }
   }
 
@@ -72,6 +117,10 @@ class UnifiedTelemetry implements TelemetryClient {
   }
 }
 
+function isTelemetryEnabled(): boolean {
+  return MEM0_TELEMETRY;
+}
+
 const telemetry = new UnifiedTelemetry(POSTHOG_API_KEY, POSTHOG_HOST);
 
 async function captureClientEvent(
@@ -101,4 +150,4 @@ async function captureClientEvent(
   );
 }
 
-export { telemetry, captureClientEvent, generateHash };
+export { telemetry, captureClientEvent, generateHash, isTelemetryEnabled };

mem0-ts/src/client/telemetry.types.ts

@@ -3,7 +3,7 @@ export interface TelemetryClient {
     distinctId: string,
     eventName: string,
     properties?: Record<string, any>,
-  ): Promise<void>;
+  ): Promise<boolean>;
   shutdown(): Promise<void>;
 }
 

mem0-ts/src/client/tests/telemetry-aliasing.test.ts

@@ -0,0 +1,410 @@
+/**
+ * Tests for PostHog identity stitching in the TS MemoryClient.
+ *
+ * Covers $identify firing, idempotency via pair markers, and the node/browser
+ * gate. Mocks fs and fetch; never touches the real ~/.mem0/config.json.
+ */
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { MemoryClient } from "../mem0";
+import { telemetry } from "../telemetry";
+import {
+  getOrCreateMem0UserId,
+  isMem0Aliased,
+  markMem0Aliased,
+  readMem0AnonIds,
+} from "../config";
+import { TEST_API_KEY } from "./helpers";
+import { setupMockFetch, installConsoleSuppression } from "./setup";
+
+installConsoleSuppression();
+
+function setupMockFetchWithPostHog(): jest.Mock {
+  return setupMockFetch(
+    new Map([["us.i.posthog.com", { status: 200, body: "ok" }]]),
+  );
+}
+
+// ─── config.ts (node-only fs read/write) ──────────────────────
+
+describe("config.ts — readMem0AnonIds / markMem0Aliased", () => {
+  let tmpHome: string;
+  const originalMem0Dir = process.env.MEM0_DIR;
+
+  beforeEach(() => {
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "mem0-ts-test-"));
+    process.env.MEM0_DIR = tmpHome;
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(tmpHome)) {
+      fs.rmSync(tmpHome, { recursive: true, force: true });
+    }
+    if (originalMem0Dir === undefined) {
+      delete process.env.MEM0_DIR;
+    } else {
+      process.env.MEM0_DIR = originalMem0Dir;
+    }
+  });
+
+  test("returns null when config file does not exist", async () => {
+    expect(await readMem0AnonIds()).toBeNull();
+  });
+
+  test("reads OSS user_id only", async () => {
+    fs.writeFileSync(
+      path.join(tmpHome, "config.json"),
+      JSON.stringify({ user_id: "oss-uuid" }),
+    );
+    const ids = await readMem0AnonIds();
+    expect(ids).toEqual({
+      oss: "oss-uuid",
+      cli: undefined,
+      aliasedPairs: [],
+    });
+  });
+
+  test("reads CLI anonymous_id and aliased_pairs", async () => {
+    fs.writeFileSync(
+      path.join(tmpHome, "config.json"),
+      JSON.stringify({
+        telemetry: { anonymous_id: "cli-anon", aliased_pairs: ["pair-marker"] },
+      }),
+    );
+    const ids = await readMem0AnonIds();
+    expect(ids).toEqual({
+      oss: undefined,
+      cli: "cli-anon",
+      aliasedPairs: ["pair-marker"],
+    });
+  });
+
+  test("getOrCreateMem0UserId creates and reuses shared SDK user_id", async () => {
+    const first = await getOrCreateMem0UserId();
+    const second = await getOrCreateMem0UserId();
+    expect(first).toBeTruthy();
+    expect(second).toBe(first);
+    const written = JSON.parse(
+      fs.readFileSync(path.join(tmpHome, "config.json"), "utf8"),
+    );
+    expect(written.user_id).toBe(first);
+  });
+
+  test("returns null on malformed JSON", async () => {
+    fs.writeFileSync(path.join(tmpHome, "config.json"), "{not json");
+    expect(await readMem0AnonIds()).toBeNull();
+  });
+
+  test("markMem0Aliased preserves other fields", async () => {
+    fs.writeFileSync(
+      path.join(tmpHome, "config.json"),
+      JSON.stringify({
+        user_id: "oss-uuid",
+        telemetry: { anonymous_id: "cli-anon" },
+      }),
+    );
+    await markMem0Aliased("oss-uuid", "user@example.com");
+    const written = JSON.parse(
+      fs.readFileSync(path.join(tmpHome, "config.json"), "utf8"),
+    );
+    expect(written.user_id).toBe("oss-uuid");
+    expect(written.telemetry.anonymous_id).toBe("cli-anon");
+    expect(written.telemetry.aliased_pairs).toHaveLength(1);
+    expect(await isMem0Aliased("oss-uuid", "user@example.com")).toBe(true);
+  });
+
+  test("markMem0Aliased creates telemetry section when missing", async () => {
+    fs.writeFileSync(
+      path.join(tmpHome, "config.json"),
+      JSON.stringify({ user_id: "oss-uuid" }),
+    );
+    await markMem0Aliased("oss-uuid", "user@example.com");
+    const written = JSON.parse(
+      fs.readFileSync(path.join(tmpHome, "config.json"), "utf8"),
+    );
+    expect(written.telemetry.aliased_pairs).toHaveLength(1);
+  });
+
+  test("markMem0Aliased tracks each pair independently", async () => {
+    fs.writeFileSync(
+      path.join(tmpHome, "config.json"),
+      JSON.stringify({ user_id: "oss-uuid" }),
+    );
+    await markMem0Aliased("oss-uuid", "user@example.com");
+    expect(await isMem0Aliased("oss-uuid", "user@example.com")).toBe(true);
+    expect(await isMem0Aliased("other-uuid", "user@example.com")).toBe(false);
+    expect(await isMem0Aliased("oss-uuid", "other@example.com")).toBe(false);
+  });
+
+  test("markMem0Aliased does not throw when target dir is unwritable", async () => {
+    // Point at a path that cannot be written to (a file-as-dir collision).
+    fs.writeFileSync(path.join(tmpHome, "blocker"), "x");
+    process.env.MEM0_DIR = path.join(tmpHome, "blocker"); // file used as dir
+    await expect(
+      markMem0Aliased("oss-uuid", "user@example.com"),
+    ).resolves.toBeUndefined();
+  });
+});
+
+// ─── telemetry.captureIdentify ───────────────────────────────
+
+describe("telemetry.captureIdentify", () => {
+  test("fires $identify with $anon_distinct_id", async () => {
+    const fetchMock = jest.fn(async () => ({
+      ok: true,
+      status: 200,
+      text: async () => "ok",
+    })) as unknown as typeof fetch;
+    global.fetch = fetchMock as any;
+
+    await telemetry.captureIdentify("anon-uuid", "user@example.com");
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [, init] = (fetchMock as jest.Mock).mock.calls[0];
+    const payload = JSON.parse(init.body);
+    expect(payload.event).toBe("$identify");
+    expect(payload.distinct_id).toBe("user@example.com");
+    expect(payload.properties.$anon_distinct_id).toBe("anon-uuid");
+    expect(payload.properties.$process_person_profile).toBeUndefined();
+  });
+
+  test("skips when anon equals email", async () => {
+    const fetchMock = jest.fn() as unknown as typeof fetch;
+    global.fetch = fetchMock as any;
+    await telemetry.captureIdentify("user@example.com", "user@example.com");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  test("skips when either input is empty", async () => {
+    const fetchMock = jest.fn() as unknown as typeof fetch;
+    global.fetch = fetchMock as any;
+    await telemetry.captureIdentify("", "user@example.com");
+    await telemetry.captureIdentify("anon", "");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
+
+// ─── MemoryClient init aliasing ──────────────────────────────
+
+describe("MemoryClient — _maybeAliasAnonToEmail", () => {
+  let tmpHome: string;
+  const originalMem0Dir = process.env.MEM0_DIR;
+
+  beforeEach(() => {
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "mem0-ts-init-"));
+    process.env.MEM0_DIR = tmpHome;
+  });
+
+  afterEach(() => {
+    if (fs.existsSync(tmpHome)) {
+      fs.rmSync(tmpHome, { recursive: true, force: true });
+    }
+    if (originalMem0Dir === undefined) {
+      delete process.env.MEM0_DIR;
+    } else {
+      process.env.MEM0_DIR = originalMem0Dir;
+    }
+  });
+
+  // Construct a non-initialised client so we can call _maybeAliasAnonToEmail
+  // in isolation (the real constructor's _initializeClient also fires it).
+  function makeStubClient(telemetryId: string): MemoryClient {
+    const client = Object.create(MemoryClient.prototype) as MemoryClient;
+    (client as any).apiKey = TEST_API_KEY;
+    (client as any).host = "https://api.mem0.ai";
+    (client as any).telemetryId = telemetryId;
+    return client;
+  }
+
+  test("fires $identify on first init and persists pair marker", async () => {
+    fs.writeFileSync(
+      path.join(tmpHome, "config.json"),
+      JSON.stringify({ user_id: "oss-uuid" }),
+    );
+    const fetchMock = setupMockFetchWithPostHog();
+
+    const client = makeStubClient("test@example.com");
+    await (client as any)._maybeAliasAnonToEmail();
+
+    const identifyCalls = (fetchMock.mock.calls as any[]).filter(
+      ([, init]: [string, RequestInit]) => {
+        if (!init?.body) return false;
+        return JSON.parse(init.body as string).event === "$identify";
+      },
+    );
+    expect(identifyCalls.length).toBe(1);
+    const body = JSON.parse(identifyCalls[0][1].body);
+    expect(body.distinct_id).toBe("test@example.com");
+    expect(body.properties.$anon_distinct_id).toBe("oss-uuid");
+
+    const written = JSON.parse(
+      fs.readFileSync(path.join(tmpHome, "config.json"), "utf8"),
+    );
+    expect(written.telemetry.aliased_pairs).toHaveLength(1);
+  });
+
+  test("platform-first init creates shared anon ID and identifies it", async () => {
+    const fetchMock = setupMockFetchWithPostHog();
+
+    const client = makeStubClient("test@example.com");
+    await (client as any)._maybeAliasAnonToEmail();
+
+    const written = JSON.parse(
+      fs.readFileSync(path.join(tmpHome, "config.json"), "utf8"),
+    );
+    expect(written.user_id).toBeTruthy();
+    expect(written.telemetry.aliased_pairs).toHaveLength(1);
+
+    const identifyCalls = (fetchMock.mock.calls as any[]).filter(
+      ([, init]: [string, RequestInit]) => {
+        if (!init?.body) return false;
+        return JSON.parse(init.body as string).event === "$identify";
+      },
+    );
+    expect(identifyCalls.length).toBe(1);
+    const body = JSON.parse(identifyCalls[0][1].body);
+    expect(body.distinct_id).toBe("test@example.com");
+    expect(body.properties.$anon_distinct_id).toBe(written.user_id);
+  });
+
+  test("second init does not refire $identify", async () => {
+    fs.writeFileSync(
+      path.join(tmpHome, "config.json"),
+      JSON.stringify({
+        user_id: "oss-uuid",
+        telemetry: {},
+      }),
+    );
+    await markMem0Aliased("oss-uuid", "test@example.com");
+    const fetchMock = setupMockFetchWithPostHog();
+
+    const client = makeStubClient("test@example.com");
+    await (client as any)._maybeAliasAnonToEmail();
+
+    const identifyCalls = (fetchMock.mock.calls as any[]).filter(
+      ([, init]: [string, RequestInit]) => {
+        if (!init?.body) return false;
+        return JSON.parse(init.body as string).event === "$identify";
+      },
+    );
+    expect(identifyCalls.length).toBe(0);
+  });
+
+  test("fires $identify for both OSS and CLI anon ids", async () => {
+    fs.writeFileSync(
+      path.join(tmpHome, "config.json"),
+      JSON.stringify({
+        user_id: "oss-uuid",
+        telemetry: { anonymous_id: "cli-anon" },
+      }),
+    );
+    const fetchMock = setupMockFetchWithPostHog();
+
+    const client = makeStubClient("test@example.com");
+    await (client as any)._maybeAliasAnonToEmail();
+
+    const identifyCalls = (fetchMock.mock.calls as any[]).filter(
+      ([, init]: [string, RequestInit]) => {
+        if (!init?.body) return false;
+        return JSON.parse(init.body as string).event === "$identify";
+      },
+    );
+    expect(identifyCalls.length).toBe(2);
+    const anonIds = identifyCalls.map(
+      (c: [string, RequestInit]) =>
+        JSON.parse(c[1].body as string).properties.$anon_distinct_id,
+    );
+    expect(anonIds).toContain("oss-uuid");
+    expect(anonIds).toContain("cli-anon");
+
+    const written = JSON.parse(
+      fs.readFileSync(path.join(tmpHome, "config.json"), "utf8"),
+    );
+    expect(written.telemetry.aliased_pairs).toHaveLength(2);
+  });
+
+  test("noop when telemetryId is not an email", async () => {
+    fs.writeFileSync(
+      path.join(tmpHome, "config.json"),
+      JSON.stringify({ user_id: "oss-uuid" }),
+    );
+    const fetchMock = setupMockFetch();
+
+    const client = makeStubClient("not-an-email");
+    await (client as any)._maybeAliasAnonToEmail();
+
+    const identifyCalls = (fetchMock.mock.calls as any[]).filter(
+      ([, init]: [string, RequestInit]) => {
+        if (!init?.body) return false;
+        return JSON.parse(init.body as string).event === "$identify";
+      },
+    );
+    expect(identifyCalls.length).toBe(0);
+  });
+
+  test("does not throw when config read fails", async () => {
+    fs.writeFileSync(path.join(tmpHome, "config.json"), "{not json");
+    setupMockFetch();
+
+    const client = makeStubClient("test@example.com");
+    await expect(
+      (client as any)._maybeAliasAnonToEmail(),
+    ).resolves.toBeUndefined();
+  });
+
+  test("noop when telemetry disabled — no fs read, no fs write, no events", async () => {
+    fs.writeFileSync(
+      path.join(tmpHome, "config.json"),
+      JSON.stringify({ user_id: "oss-uuid" }),
+    );
+    const fetchMock = setupMockFetch();
+
+    jest.resetModules();
+    const original = process.env.MEM0_TELEMETRY;
+    process.env.MEM0_TELEMETRY = "false";
+    try {
+      const { MemoryClient: ColdClient } = await import("../mem0");
+      const client = Object.create(ColdClient.prototype);
+      client.apiKey = TEST_API_KEY;
+      client.host = "https://api.mem0.ai";
+      client.telemetryId = "test@example.com";
+      await client._maybeAliasAnonToEmail();
+    } finally {
+      if (original === undefined) delete process.env.MEM0_TELEMETRY;
+      else process.env.MEM0_TELEMETRY = original;
+      jest.resetModules();
+    }
+
+    const identifyCalls = (fetchMock.mock.calls as any[]).filter(
+      ([, init]: [string, RequestInit]) => {
+        if (!init?.body) return false;
+        return JSON.parse(init.body as string).event === "$identify";
+      },
+    );
+    expect(identifyCalls.length).toBe(0);
+
+    const written = JSON.parse(
+      fs.readFileSync(path.join(tmpHome, "config.json"), "utf8"),
+    );
+    expect(written.telemetry?.aliased_pairs).toBeUndefined();
+  });
+});
+
+// ─── Browser env path (no process.versions.node) ─────────────
+
+describe("config.ts in browser-like environment", () => {
+  test("readMem0AnonIds returns null when not Node", async () => {
+    const originalProcess = global.process;
+    // @ts-expect-error force-undefining global to simulate a browser
+    delete global.process;
+    try {
+      jest.resetModules();
+      const { readMem0AnonIds: browserRead } = await import("../config");
+      expect(await browserRead()).toBeNull();
+    } finally {
+      global.process = originalProcess;
+      jest.resetModules();
+    }
+  });
+});

mem0-ts/src/oss/src/memory/index.ts

@@ -53,6 +53,7 @@ import {
   ScoredResult,
 } from "../utils/scoring";
 import { getDefaultVectorStoreDbPath } from "../utils/sqlite";
+import { getOrCreateMem0UserId } from "../../../client/config";
 
 // Entity params that must be passed via filters - check both snake_case and camelCase
 const ENTITY_PARAMS = [
@@ -466,7 +467,12 @@ export class Memory {
         this.telemetryId === "anonymous" ||
         this.telemetryId === "anonymous-supabase"
       ) {
-        this.telemetryId = await this.vectorStore.getUserId();
+        this.telemetryId =
+          (await getOrCreateMem0UserId()) ||
+          (await this.vectorStore.getUserId());
+        try {
+          await this.vectorStore.setUserId(this.telemetryId);
+        } catch {}
       }
       return this.telemetryId;
     } catch (error) {

mem0-ts/src/oss/src/vector_stores/pgvector.ts

@@ -1,9 +1,33 @@
 import type { Client as ClientType } from "pg";
 import pkg from "pg";
-const { Client } = pkg;
+const { Client, escapeIdentifier } = pkg;
 import { VectorStore } from "./base";
 import { SearchFilters, VectorStoreConfig, VectorStoreResult } from "../types";
 
+const SAFE_IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]{0,127}$/;
+
+function validateIdentifier(
+  name: string,
+  label: string = "identifier",
+): string {
+  if (!SAFE_IDENTIFIER_RE.test(name)) {
+    throw new Error(
+      `Invalid ${label} '${name}': only letters, digits, and underscores are allowed, ` +
+        `must start with a letter or underscore, and be at most 128 characters.`,
+    );
+  }
+  return name;
+}
+
+function escapeFilterKey(key: string): string {
+  if (!SAFE_IDENTIFIER_RE.test(key)) {
+    throw new Error(
+      `Invalid filter key '${key}': only letters, digits, and underscores are allowed.`,
+    );
+  }
+  return key;
+}
+
 interface PGVectorConfig extends VectorStoreConfig {
   dbname?: string;
   user: string;
@@ -25,10 +49,13 @@ export class PGVector implements VectorStore {
   private _initPromise?: Promise<void>;
 
   constructor(config: PGVectorConfig) {
-    this.collectionName = config.collectionName || "memories";
+    this.collectionName = validateIdentifier(
+      config.collectionName || "memories",
+      "collectionName",
+    );
     this.useDiskann = config.diskann || false;
     this.useHnsw = config.hnsw || false;
-    this.dbName = config.dbname || "vector_store";
+    this.dbName = validateIdentifier(config.dbname || "vector_store", "dbname");
     this.config = config;
 
     this.client = new Client({
@@ -41,6 +68,10 @@ export class PGVector implements VectorStore {
     this.initialize().catch(console.error);
   }
 
+  private col(): string {
+    return escapeIdentifier(this.collectionName);
+  }
+
   async initialize(): Promise<void> {
     if (!this._initPromise) {
       this._initPromise = this._doInitialize();
@@ -102,31 +133,28 @@ export class PGVector implements VectorStore {
   }
 
   private async createDatabase(dbName: string): Promise<void> {
-    // Create database (cannot be parameterized)
-    await this.client.query(`CREATE DATABASE ${dbName}`);
+    await this.client.query(`CREATE DATABASE ${escapeIdentifier(dbName)}`);
   }
 
   private async createCol(embeddingModelDims: number): Promise<void> {
-    // Create the table
+    const dims = Math.floor(embeddingModelDims);
     await this.client.query(`
-      CREATE TABLE IF NOT EXISTS ${this.collectionName} (
+      CREATE TABLE IF NOT EXISTS ${this.col()} (
         id UUID PRIMARY KEY,
-        vector vector(${embeddingModelDims}),
+        vector vector(${dims}),
         payload JSONB
       );
     `);
 
-    // Create indexes based on configuration
     if (this.useDiskann && embeddingModelDims < 2000) {
       try {
-        // Check if vectorscale extension is available
         const result = await this.client.query(
           "SELECT * FROM pg_extension WHERE extname = 'vectorscale'",
         );
         if (result.rows.length > 0) {
           await this.client.query(`
-            CREATE INDEX IF NOT EXISTS ${this.collectionName}_diskann_idx
-            ON ${this.collectionName}
+            CREATE INDEX IF NOT EXISTS ${escapeIdentifier(this.collectionName + "_diskann_idx")}
+            ON ${this.col()}
             USING diskann (vector);
           `);
         }
@@ -136,8 +164,8 @@ export class PGVector implements VectorStore {
     } else if (this.useHnsw) {
       try {
         await this.client.query(`
-          CREATE INDEX IF NOT EXISTS ${this.collectionName}_hnsw_idx
-          ON ${this.collectionName}
+          CREATE INDEX IF NOT EXISTS ${escapeIdentifier(this.collectionName + "_hnsw_idx")}
+          ON ${this.col()}
           USING hnsw (vector vector_cosine_ops);
         `);
       } catch (error) {
@@ -153,16 +181,15 @@ export class PGVector implements VectorStore {
   ): Promise<void> {
     const values = vectors.map((vector, i) => ({
       id: ids[i],
-      vector: `[${vector.join(",")}]`, // Format vector as string with square brackets
+      vector: `[${vector.join(",")}]`,
       payload: payloads[i],
     }));
 
     const query = `
-      INSERT INTO ${this.collectionName} (id, vector, payload)
+      INSERT INTO ${this.col()} (id, vector, payload)
       VALUES ($1, $2::vector, $3::jsonb)
     `;
 
-    // Execute inserts in parallel using Promise.all
     await Promise.all(
       values.map((value) =>
         this.client.query(query, [value.id, value.vector, value.payload]),
@@ -182,7 +209,8 @@ export class PGVector implements VectorStore {
 
       if (filters) {
         for (const [key, value] of Object.entries(filters)) {
-          filterConditions.push(`payload->>'${key}' = $${filterIndex}`);
+          const safeKey = escapeFilterKey(key);
+          filterConditions.push(`payload->>'${safeKey}' = $${filterIndex}`);
           filterValues.push(value);
           filterIndex++;
         }
@@ -195,7 +223,7 @@ export class PGVector implements VectorStore {
 
       const searchQuery = `
         SELECT id, ts_rank_cd(to_tsvector('simple', payload->>'textLemmatized'), plainto_tsquery('simple', $1)) AS score, payload
-        FROM ${this.collectionName}
+        FROM ${this.col()}
         WHERE to_tsvector('simple', payload->>'textLemmatized') @@ plainto_tsquery('simple', $1)
         ${filterClause}
         ORDER BY score DESC
@@ -221,13 +249,14 @@ export class PGVector implements VectorStore {
     filters?: SearchFilters,
   ): Promise<VectorStoreResult[]> {
     const filterConditions: string[] = [];
-    const queryVector = `[${query.join(",")}]`; // Format query vector as string with square brackets
+    const queryVector = `[${query.join(",")}]`;
     const filterValues: any[] = [queryVector, topK];
     let filterIndex = 3;
 
     if (filters) {
       for (const [key, value] of Object.entries(filters)) {
-        filterConditions.push(`payload->>'${key}' = $${filterIndex}`);
+        const safeKey = escapeFilterKey(key);
+        filterConditions.push(`payload->>'${safeKey}' = $${filterIndex}`);
         filterValues.push(value);
         filterIndex++;
       }
@@ -240,7 +269,7 @@ export class PGVector implements VectorStore {
 
     const searchQuery = `
       SELECT id, vector <=> $1::vector AS distance, payload
-      FROM ${this.collectionName}
+      FROM ${this.col()}
       ${filterClause}
       ORDER BY distance
       LIMIT $2
@@ -251,13 +280,13 @@ export class PGVector implements VectorStore {
     return result.rows.map((row) => ({
       id: row.id,
       payload: row.payload,
-      score: row.distance,
+      score: Math.max(0, Math.min(1, 1 - Number(row.distance))),
     }));
   }
 
   async get(vectorId: string): Promise<VectorStoreResult | null> {
     const result = await this.client.query(
-      `SELECT id, payload FROM ${this.collectionName} WHERE id = $1`,
+      `SELECT id, payload FROM ${this.col()} WHERE id = $1`,
       [vectorId],
     );
 
@@ -274,10 +303,10 @@ export class PGVector implements VectorStore {
     vector: number[],
     payload: Record<string, any>,
   ): Promise<void> {
-    const vectorStr = `[${vector.join(",")}]`; // Format vector as string with square brackets
+    const vectorStr = `[${vector.join(",")}]`;
     await this.client.query(
       `
-      UPDATE ${this.collectionName}
+      UPDATE ${this.col()}
       SET vector = $1::vector, payload = $2::jsonb
       WHERE id = $3
       `,
@@ -286,14 +315,13 @@ export class PGVector implements VectorStore {
   }
 
   async delete(vectorId: string): Promise<void> {
-    await this.client.query(
-      `DELETE FROM ${this.collectionName} WHERE id = $1`,
-      [vectorId],
-    );
+    await this.client.query(`DELETE FROM ${this.col()} WHERE id = $1`, [
+      vectorId,
+    ]);
   }
 
   async deleteCol(): Promise<void> {
-    await this.client.query(`DROP TABLE IF EXISTS ${this.collectionName}`);
+    await this.client.query(`DROP TABLE IF EXISTS ${this.col()}`);
   }
 
   private async listCols(): Promise<string[]> {
@@ -315,7 +343,8 @@ export class PGVector implements VectorStore {
 
     if (filters) {
       for (const [key, value] of Object.entries(filters)) {
-        filterConditions.push(`payload->>'${key}' = $${paramIndex}`);
+        const safeKey = escapeFilterKey(key);
+        filterConditions.push(`payload->>'${safeKey}' = $${paramIndex}`);
         filterValues.push(value);
         paramIndex++;
       }
@@ -328,14 +357,14 @@ export class PGVector implements VectorStore {
 
     const listQuery = `
       SELECT id, payload
-      FROM ${this.collectionName}
+      FROM ${this.col()}
       ${filterClause}
       LIMIT $${paramIndex}
     `;
 
     const countQuery = `
       SELECT COUNT(*)
-      FROM ${this.collectionName}
+      FROM ${this.col()}
       ${filterClause}
     `;
 

mem0-ts/src/oss/tests/pgvector.unit.test.ts

@@ -0,0 +1,126 @@
+/// <reference types="jest" />
+
+const searchRows = [
+  {
+    id: "a",
+    payload: { data: "exactly x-axis" },
+    distance: "0",
+  },
+  {
+    id: "b",
+    payload: { data: "close to x-axis" },
+    distance: "0.006116251198662548",
+  },
+  {
+    id: "c",
+    payload: { data: "y-axis" },
+    distance: "1",
+  },
+  {
+    id: "d",
+    payload: { data: "opposite x-axis" },
+    distance: "2",
+  },
+];
+
+function mockPgQuery(sql: string) {
+  if (sql.includes("SELECT 1 FROM pg_database")) {
+    return { rows: [{ "?column?": 1 }] };
+  }
+
+  if (sql.includes("FROM information_schema.tables")) {
+    return { rows: [{ table_name: "memories" }] };
+  }
+
+  if (sql.includes("vector <=> $1::vector AS distance")) {
+    return { rows: searchRows };
+  }
+
+  return { rows: [] };
+}
+
+jest.mock("pg", () => {
+  const clients: any[] = [];
+
+  const Client = jest.fn().mockImplementation((config: any) => {
+    const client = {
+      config,
+      connect: jest.fn().mockResolvedValue(undefined),
+      end: jest.fn().mockResolvedValue(undefined),
+      query: jest
+        .fn()
+        .mockImplementation(async (sql: string) => mockPgQuery(sql)),
+    };
+
+    clients.push(client);
+    return client;
+  });
+
+  const escapeIdentifier = (str: string) => `"${str.replace(/"/g, '""')}"`;
+
+  return {
+    __esModule: true,
+    default: { Client, escapeIdentifier },
+    Client,
+    escapeIdentifier,
+    __mock: { Client, clients },
+  };
+});
+
+import { PGVector } from "../src/vector_stores/pgvector";
+
+describe("PGVector - search()", () => {
+  beforeEach(() => {
+    const pg = require("pg");
+    pg.__mock.Client.mockClear();
+    pg.__mock.clients.length = 0;
+  });
+
+  test("returns similarity score (1 - distance) clamped to [0, 1]", async () => {
+    const store = new PGVector({
+      collectionName: "memories",
+      user: "postgres",
+      password: "postgres",
+      host: "localhost",
+      port: 5432,
+      embeddingModelDims: 3,
+      dimension: 3,
+    } as any);
+
+    await store.initialize();
+
+    const results = await store.search([1, 0, 0], 4);
+
+    expect(results).toEqual([
+      {
+        id: "a",
+        payload: { data: "exactly x-axis" },
+        score: 1,
+      },
+      {
+        id: "b",
+        payload: { data: "close to x-axis" },
+        score: 0.9938837488013375,
+      },
+      {
+        id: "c",
+        payload: { data: "y-axis" },
+        score: 0,
+      },
+      {
+        id: "d",
+        payload: { data: "opposite x-axis" },
+        score: 0,
+      },
+    ]);
+
+    const pg = require("pg");
+    expect(pg.__mock.Client).toHaveBeenCalledTimes(2);
+
+    const activeClient = pg.__mock.clients[1];
+    expect(activeClient.query).toHaveBeenCalledWith(
+      expect.stringContaining("vector <=> $1::vector AS distance"),
+      ["[1,0,0]", 4],
+    );
+  });
+});

mem0/client/main.py

@@ -19,8 +19,8 @@ from mem0.client.types import (
 from mem0.client.utils import api_error_handler
 
 # Exception classes are referenced in docstrings only
-from mem0.memory.setup import get_user_id, setup_config
-from mem0.memory.telemetry import capture_client_event
+from mem0.memory.setup import get_user_id, is_aliased, mark_aliased, read_anon_ids, setup_config
+from mem0.memory.telemetry import capture_client_event, client_telemetry
 
 logger = logging.getLogger(__name__)
 
@@ -33,6 +33,32 @@ setup_config()
 ENTITY_PARAMS = frozenset({"user_id", "agent_id", "app_id", "run_id"})
 
 
+def _maybe_alias_anon_to_email(user_email):
+    """Fire $identify per prior anon ID so PostHog merges them into email.
+
+    Idempotent via telemetry.aliased_pairs: only writes markers when
+    telemetry is actually enabled, so disabling/re-enabling MEM0_TELEMETRY still works.
+    Best-effort: never raises.
+    """
+    if client_telemetry.posthog is None:
+        return
+    if not user_email or "@" not in user_email:
+        return
+    try:
+        anon_ids = read_anon_ids()
+        seen = set()
+        for anon_id in (anon_ids.get("oss"), anon_ids.get("cli")):
+            if not anon_id or anon_id == user_email or anon_id in seen:
+                continue
+            seen.add(anon_id)
+            if is_aliased(anon_id, user_email):
+                continue
+            if client_telemetry.capture_identify(anon_id, user_email):
+                mark_aliased(anon_id, user_email)
+    except Exception as e:
+        logger.debug("Failed to alias anon telemetry to %r: %s", user_email, e)
+
+
 class MemoryClient:
     """Client for interacting with the Mem0 API.
 
@@ -108,6 +134,7 @@ class MemoryClient:
             user_email=self.user_email,
         )
 
+        _maybe_alias_anon_to_email(self.user_email)
         capture_client_event("client.init", self, {"sync_type": "sync"})
 
     def _validate_api_key(self):
@@ -985,6 +1012,7 @@ class AsyncMemoryClient:
             user_email=self.user_email,
         )
 
+        _maybe_alias_anon_to_email(self.user_email)
         capture_client_event("client.init", self, {"sync_type": "async"})
 
     def _validate_api_key(self):

mem0/client/project.py

@@ -398,6 +398,7 @@ class Project(BaseProject):
         custom_categories: Optional[List[str]] = None,
         retrieval_criteria: Optional[List[Dict[str, Any]]] = None,
         multilingual: Optional[bool] = None,
+        decay: Optional[bool] = None,
     ) -> Dict[str, Any]:
         """
         Update project settings.
@@ -407,6 +408,9 @@ class Project(BaseProject):
             custom_categories: New categories for the project
             retrieval_criteria: New retrieval criteria for the project
             multilingual: Whether to use the input language for memory storage and retrieval
+            decay: Toggle Memory Decay for this project. When True, search-time
+                ranking boosts recently-used memories and gently dampens stale ones; when
+                False, ranking is restored to the pre-decay behaviour. Off by default.
 
         Returns:
             Dictionary containing the API response.
@@ -423,11 +427,12 @@ class Project(BaseProject):
             and custom_categories is None
             and retrieval_criteria is None
             and multilingual is None
+            and decay is None
         ):
             raise ValueError(
                 "At least one parameter must be provided for update: "
                 "custom_instructions, custom_categories, retrieval_criteria, "
-                "multilingual"
+                "multilingual, decay"
             )
 
         payload = self._prepare_params(
@@ -436,6 +441,7 @@ class Project(BaseProject):
                 "custom_categories": custom_categories,
                 "retrieval_criteria": retrieval_criteria,
                 "multilingual": multilingual,
+                "decay": decay,
             }
         )
         response = self._client.patch(
@@ -451,6 +457,7 @@ class Project(BaseProject):
                 "custom_categories": custom_categories,
                 "retrieval_criteria": retrieval_criteria,
                 "multilingual": multilingual,
+                "decay": decay,
                 "sync_type": "sync",
             },
         )
@@ -715,6 +722,7 @@ class AsyncProject(BaseProject):
         custom_categories: Optional[List[str]] = None,
         retrieval_criteria: Optional[List[Dict[str, Any]]] = None,
         multilingual: Optional[bool] = None,
+        decay: Optional[bool] = None,
     ) -> Dict[str, Any]:
         """
         Update project settings.
@@ -724,6 +732,9 @@ class AsyncProject(BaseProject):
             custom_categories: New categories for the project
             retrieval_criteria: New retrieval criteria for the project
             multilingual: Whether to use the input language for memory storage and retrieval
+            decay: Toggle Memory Decay for this project. When True, search-time
+                ranking boosts recently-used memories and gently dampens stale ones; when
+                False, ranking is restored to the pre-decay behaviour. Off by default.
 
         Returns:
             Dictionary containing the API response.
@@ -740,11 +751,12 @@ class AsyncProject(BaseProject):
             and custom_categories is None
             and retrieval_criteria is None
             and multilingual is None
+            and decay is None
         ):
             raise ValueError(
                 "At least one parameter must be provided for update: "
                 "custom_instructions, custom_categories, retrieval_criteria, "
-                "multilingual"
+                "multilingual, decay"
             )
 
         payload = self._prepare_params(
@@ -753,6 +765,7 @@ class AsyncProject(BaseProject):
                 "custom_categories": custom_categories,
                 "retrieval_criteria": retrieval_criteria,
                 "multilingual": multilingual,
+                "decay": decay,
             }
         )
         response = await self._client.patch(
@@ -768,6 +781,7 @@ class AsyncProject(BaseProject):
                 "custom_categories": custom_categories,
                 "retrieval_criteria": retrieval_criteria,
                 "multilingual": multilingual,
+                "decay": decay,
                 "sync_type": "async",
             },
         )

mem0/memory/setup.py

@@ -1,6 +1,8 @@
 import json
+import logging
 import os
 import uuid
+from hashlib import sha256
 
 # Set up the directory path
 VECTOR_ID = str(uuid.uuid4())
@@ -8,28 +10,113 @@ home_dir = os.path.expanduser("~")
 mem0_dir = os.environ.get("MEM0_DIR") or os.path.join(home_dir, ".mem0")
 os.makedirs(mem0_dir, exist_ok=True)
 
+_logger = logging.getLogger(__name__)
+
+
+def _config_path():
+    return os.path.join(mem0_dir, "config.json")
+
+
+def _load_config():
+    """Load ~/.mem0/config.json, returning {} on missing/malformed file."""
+    path = _config_path()
+    if not os.path.exists(path):
+        return {}
+    try:
+        with open(path, "r") as f:
+            data = json.load(f)
+        return data if isinstance(data, dict) else {}
+    except Exception as e:
+        _logger.debug("Failed to load mem0 config %s: %s", path, e)
+        return {}
+
+
+def _write_config(config):
+    """Best-effort write of ~/.mem0/config.json. Never raises."""
+    path = _config_path()
+    try:
+        with open(path, "w") as f:
+            json.dump(config, f, indent=4)
+    except Exception as e:
+        _logger.debug("Failed to write mem0 config %s: %s", path, e)
+
 
 def setup_config():
-    config_path = os.path.join(mem0_dir, "config.json")
-    if not os.path.exists(config_path):
-        user_id = str(uuid.uuid4())
-        config = {"user_id": user_id}
-        with open(config_path, "w") as config_file:
-            json.dump(config, config_file, indent=4)
+    """Ensure ~/.mem0/config.json exists with a top-level user_id.
+
+    Idempotent: backfills user_id for users whose config was written by the
+    CLI (which writes telemetry.anonymous_id but no top-level user_id).
+    Without this, OSS Python telemetry is silently dropped because
+    get_user_id() returns None when user_id is missing.
+    """
+    config = _load_config()
+    if config.get("user_id"):
+        return
+    config["user_id"] = str(uuid.uuid4())
+    _write_config(config)
 
 
 def get_user_id():
-    config_path = os.path.join(mem0_dir, "config.json")
-    if not os.path.exists(config_path):
+    config = _load_config()
+    if not config:
         return "anonymous_user"
+    return config.get("user_id")
 
-    try:
-        with open(config_path, "r") as config_file:
-            config = json.load(config_file)
-            user_id = config.get("user_id")
-            return user_id
-    except Exception:
-        return "anonymous_user"
+
+def read_anon_ids():
+    """Return anon IDs and alias markers from ~/.mem0/config.json.
+
+    Returns a dict with keys "oss", "cli", "aliased_pairs" (IDs may be
+    None). OSS Python writes top-level "user_id"; the CLI writes
+    "telemetry.anonymous_id". They may coexist depending on which surface ran
+    first.
+    """
+    config = _load_config()
+    telemetry = config.get("telemetry") if isinstance(config.get("telemetry"), dict) else {}
+    aliased_pairs = telemetry.get("aliased_pairs")
+    return {
+        "oss": config.get("user_id"),
+        "cli": telemetry.get("anonymous_id"),
+        "aliased_pairs": aliased_pairs if isinstance(aliased_pairs, list) else [],
+    }
+
+
+def _alias_pair_marker(anon_id, email):
+    return sha256(f"{anon_id}\0{email}".encode("utf-8")).hexdigest()
+
+
+def is_aliased(anon_id, email):
+    """Return whether anon_id -> email has already been identified."""
+    if not anon_id or not email:
+        return False
+    config = _load_config()
+    telemetry = config.get("telemetry") if isinstance(config.get("telemetry"), dict) else {}
+    aliased_pairs = telemetry.get("aliased_pairs")
+    if not isinstance(aliased_pairs, list):
+        return False
+    return _alias_pair_marker(anon_id, email) in aliased_pairs
+
+
+def mark_aliased(anon_id, email):
+    """Persist an anon_id -> email alias marker so $identify fires once per pair.
+
+    The marker is hashed to avoid storing platform emails in the local config.
+    """
+    if not anon_id or not email:
+        return
+    config = _load_config()
+    telemetry = config.get("telemetry")
+    if not isinstance(telemetry, dict):
+        telemetry = {}
+    aliased_pairs = telemetry.get("aliased_pairs")
+    if not isinstance(aliased_pairs, list):
+        aliased_pairs = []
+    marker = _alias_pair_marker(anon_id, email)
+    if marker not in aliased_pairs:
+        aliased_pairs.append(marker)
+    telemetry["aliased_pairs"] = aliased_pairs
+    config["telemetry"] = telemetry
+    _write_config(config)
 
 
 def get_or_create_user_id(vector_store=None):

mem0/memory/telemetry.py

@@ -48,7 +48,8 @@ MEM0_TELEMETRY_SAMPLE_RATE = _parse_sample_rate(os.environ.get("MEM0_TELEMETRY_S
 
 # Events that bypass sampling and always fire. Keep this set in sync with the
 # event names passed to capture_event() in mem0/memory/main.py.
-_LIFECYCLE_EVENTS = frozenset({"mem0.init", "mem0.reset", "mem0._create_procedural_memory"})
+# $identify is included so PostHog person-merging is never lost to sampling.
+_LIFECYCLE_EVENTS = frozenset({"mem0.init", "mem0.reset", "mem0._create_procedural_memory", "$identify"})
 
 
 def _sampling_before_send(msg):
@@ -112,6 +113,23 @@ class AnonymousTelemetry:
         except Exception as e:
             _logger.debug("Failed to capture telemetry event %r: %s", event_name, e)
 
+    def capture_identify(self, anon_id, email):
+        """Fire $identify with $anon_distinct_id so PostHog merges anon_id into email."""
+        if self.posthog is None:
+            return False
+        if not anon_id or not email or anon_id == email:
+            return False
+        try:
+            self.posthog.capture(
+                distinct_id=email,
+                event="$identify",
+                properties={"$anon_distinct_id": anon_id, "client_source": "python"},
+            )
+            return True
+        except Exception as e:
+            _logger.debug("Failed to capture $identify for %r: %s", email, e)
+            return False
+
     def close(self):
         if self.posthog is not None:
             self.posthog.shutdown()

mem0/reranker/llm_reranker.py

@@ -58,24 +58,35 @@ class LLMReranker(BaseReranker):
         # Initialize LLM using the factory
         self.llm = LlmFactory.create(llm_provider, llm_config)
 
-        # Default scoring prompt
-        self.scoring_prompt = getattr(self.config, 'scoring_prompt', None) or self._get_default_prompt()
-        
-    def _get_default_prompt(self) -> str:
-        """Get the default scoring prompt template."""
-        return """You are a relevance scoring assistant. Given a query and a document, you need to score how relevant the document is to the query.
+        # Honor custom scoring_prompt from config if provided
+        custom_prompt = getattr(self.config, 'scoring_prompt', None)
+        if custom_prompt:
+            import warnings
+            warnings.warn(
+                "LLMRerankerConfig.scoring_prompt is deprecated and will be removed in a future version. "
+                "The prompt is now used as the system message.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            self._system_prompt = custom_prompt
+        else:
+            self._system_prompt = self._SYSTEM_PROMPT
 
-Score the relevance on a scale from 0.0 to 1.0, where:
-- 1.0 = Perfectly relevant and directly answers the query
-- 0.8-0.9 = Highly relevant with good information
-- 0.6-0.7 = Moderately relevant with some useful information  
-- 0.4-0.5 = Slightly relevant with limited useful information
-- 0.0-0.3 = Not relevant or no useful information
+    _SYSTEM_PROMPT = (
+        "You are a relevance scoring assistant. "
+        "Given a query and a document, score how relevant the document is to the query.\n\n"
+        "Score the relevance on a scale from 0.0 to 1.0, where:\n"
+        "- 1.0 = Perfectly relevant and directly answers the query\n"
+        "- 0.8-0.9 = Highly relevant with good information\n"
+        "- 0.6-0.7 = Moderately relevant with some useful information\n"
+        "- 0.4-0.5 = Slightly relevant with limited useful information\n"
+        "- 0.0-0.3 = Not relevant or no useful information\n\n"
+        "Respond with only a single numerical score between 0.0 and 1.0. "
+        "Do not include any explanation or additional text."
+    )
 
-Query: "{query}"
-Document: "{document}"
-
-Provide only a single numerical score between 0.0 and 1.0. Do not include any explanation or additional text."""
+    # Maximum character length for query and document inputs to prevent prompt flooding.
+    _MAX_INPUT_LEN = 4000
 
     def _extract_score(self, response_text: str) -> float:
         """Extract numerical score from LLM response."""
@@ -119,12 +130,17 @@ Provide only a single numerical score between 0.0 and 1.0. Do not include any ex
                 doc_text = str(doc)
             
             try:
-                # Generate scoring prompt
-                prompt = self.scoring_prompt.format(query=query, document=doc_text)
-                
-                # Get LLM response
+                # Truncate inputs to prevent prompt flooding, then send as separate
+                # system/user messages so instructions cannot be overridden by user data.
+                safe_query = query[: self._MAX_INPUT_LEN]
+                safe_doc = doc_text[: self._MAX_INPUT_LEN]
+                user_message = f"Query: {safe_query}\n\nDocument: {safe_doc}"
+
                 response = self.llm.generate_response(
-                    messages=[{"role": "user", "content": prompt}]
+                    messages=[
+                        {"role": "system", "content": self._system_prompt},
+                        {"role": "user", "content": user_message},
+                    ]
                 )
                 
                 # Extract score from response

mem0/vector_stores/azure_mysql.py

@@ -1,5 +1,6 @@
 import json
 import logging
+import re
 from contextlib import contextmanager
 from typing import Any, Dict, List, Optional
 
@@ -25,6 +26,17 @@ from mem0.vector_stores.base import VectorStoreBase
 
 logger = logging.getLogger(__name__)
 
+_SAFE_IDENTIFIER_RE = re.compile(r'^[a-zA-Z_][a-zA-Z0-9_]{0,127}$')
+
+
+def _validate_identifier(name: str, label: str = "identifier") -> str:
+    if not _SAFE_IDENTIFIER_RE.match(name):
+        raise ValueError(
+            f"Invalid {label} '{name}': only letters, digits, and underscores are allowed, "
+            "must start with a letter or underscore, and be at most 128 characters."
+        )
+    return name
+
 
 class OutputData(BaseModel):
     id: Optional[str]
@@ -72,7 +84,7 @@ class AzureMySQL(VectorStoreBase):
         self.user = user
         self.password = password
         self.database = database
-        self.collection_name = collection_name
+        self.collection_name = _validate_identifier(collection_name, "collection_name")
         self.embedding_model_dims = embedding_model_dims
         self.use_azure_credential = use_azure_credential
         self.ssl_ca = ssl_ca
@@ -174,7 +186,7 @@ class AzureMySQL(VectorStoreBase):
             vector_size (int, optional): Vector dimension (uses self.embedding_model_dims if not provided)
             distance (str): Distance metric (cosine, euclidean, dot_product)
         """
-        table_name = name or self.collection_name
+        table_name = _validate_identifier(name, "table_name") if name else self.collection_name
         dims = vector_size or self.embedding_model_dims
 
         with self._get_cursor(commit=True) as cur:

mem0/vector_stores/cassandra.py

@@ -1,5 +1,6 @@
 import json
 import logging
+import re
 import uuid
 from typing import Any, Dict, List, Optional
 
@@ -19,6 +20,17 @@ from mem0.vector_stores.base import VectorStoreBase
 
 logger = logging.getLogger(__name__)
 
+_SAFE_IDENTIFIER_RE = re.compile(r'^[a-zA-Z_][a-zA-Z0-9_]{0,127}$')
+
+
+def _validate_identifier(name: str, label: str = "identifier") -> str:
+    if not _SAFE_IDENTIFIER_RE.match(name):
+        raise ValueError(
+            f"Invalid {label} '{name}': only letters, digits, and underscores are allowed, "
+            "must start with a letter or underscore, and be at most 128 characters."
+        )
+    return name
+
 
 class OutputData(BaseModel):
     id: Optional[str]
@@ -59,8 +71,8 @@ class CassandraDB(VectorStoreBase):
         self.port = port
         self.username = username
         self.password = password
-        self.keyspace = keyspace
-        self.collection_name = collection_name
+        self.keyspace = _validate_identifier(keyspace, "keyspace")
+        self.collection_name = _validate_identifier(collection_name, "collection_name")
         self.embedding_model_dims = embedding_model_dims
         self.secure_connect_bundle = secure_connect_bundle
         self.protocol_version = protocol_version
@@ -156,7 +168,7 @@ class CassandraDB(VectorStoreBase):
             vector_size (int, optional): Vector dimension (uses self.embedding_model_dims if not provided)
             distance (str): Distance metric (cosine, euclidean, dot_product)
         """
-        table_name = name or self.collection_name
+        table_name = _validate_identifier(name, "table_name") if name else self.collection_name
         dims = vector_size or self.embedding_model_dims
 
         try:
@@ -375,12 +387,10 @@ class CassandraDB(VectorStoreBase):
             List[str]: List of collection names
         """
         try:
-            query = f"""
-                SELECT table_name
-                FROM system_schema.tables
-                WHERE keyspace_name = '{self.keyspace}'
-            """
-            rows = self.session.execute(query)
+            prepared = self.session.prepare(
+                "SELECT table_name FROM system_schema.tables WHERE keyspace_name = ?"
+            )
+            rows = self.session.execute(prepared, (self.keyspace,))
             return [row.table_name for row in rows]
         except Exception as e:
             logger.error(f"Failed to list collections: {e}")

mem0/vector_stores/pgvector.py

@@ -7,6 +7,7 @@ from pydantic import BaseModel
 
 # Try to import psycopg (psycopg3) first, then fall back to psycopg2
 try:
+    from psycopg import sql
     from psycopg.types.json import Json
     from psycopg_pool import ConnectionPool
     PSYCOPG_VERSION = 3
@@ -14,6 +15,7 @@ try:
     logger.info("Using psycopg (psycopg3) with ConnectionPool for PostgreSQL connections")
 except ImportError:
     try:
+        from psycopg2 import sql
         from psycopg2.extras import Json, execute_values
         from psycopg2.pool import ThreadedConnectionPool as ConnectionPool
         PSYCOPG_VERSION = 2
@@ -144,6 +146,10 @@ class PGVector(VectorStoreBase):
                 cur.close()
                 self.connection_pool.putconn(conn)
 
+    def _col(self) -> "sql.Identifier":
+        """Return a safely-quoted SQL identifier for the collection table."""
+        return sql.Identifier(self.collection_name)
+
     def create_col(self) -> None:
         """
         Create a new collection (table in PostgreSQL).
@@ -152,39 +158,45 @@ class PGVector(VectorStoreBase):
         with self._get_cursor(commit=True) as cur:
             cur.execute("CREATE EXTENSION IF NOT EXISTS vector")
             cur.execute(
-                f"""
-                CREATE TABLE IF NOT EXISTS {self.collection_name} (
+                sql.SQL("""
+                CREATE TABLE IF NOT EXISTS {} (
                     id UUID PRIMARY KEY,
-                    vector vector({self.embedding_model_dims}),
+                    vector vector({}),
                     payload JSONB
                 );
-                """
+                """).format(self._col(), sql.Literal(self.embedding_model_dims))
             )
             if self.use_diskann and self.embedding_model_dims < 2000:
                 cur.execute("SELECT * FROM pg_extension WHERE extname = 'vectorscale'")
                 if cur.fetchone():
                     # Create DiskANN index if extension is installed for faster search
                     cur.execute(
-                        f"""
-                        CREATE INDEX IF NOT EXISTS {self.collection_name}_diskann_idx
-                        ON {self.collection_name}
+                        sql.SQL("""
+                        CREATE INDEX IF NOT EXISTS {} ON {}
                         USING diskann (vector);
-                        """
+                        """).format(
+                            sql.Identifier(f"{self.collection_name}_diskann_idx"),
+                            self._col(),
+                        )
                     )
             elif self.use_hnsw:
                 cur.execute(
-                    f"""
-                    CREATE INDEX IF NOT EXISTS {self.collection_name}_hnsw_idx
-                    ON {self.collection_name}
+                    sql.SQL("""
+                    CREATE INDEX IF NOT EXISTS {} ON {}
                     USING hnsw (vector vector_cosine_ops)
-                    """
+                    """).format(
+                        sql.Identifier(f"{self.collection_name}_hnsw_idx"),
+                        self._col(),
+                    )
                 )
             cur.execute(
-                f"""
-                CREATE INDEX IF NOT EXISTS {self.collection_name}_text_lemmatized_idx
-                ON {self.collection_name}
+                sql.SQL("""
+                CREATE INDEX IF NOT EXISTS {} ON {}
                 USING gin(to_tsvector('simple', payload->>'text_lemmatized'));
-                """
+                """).format(
+                    sql.Identifier(f"{self.collection_name}_text_lemmatized_idx"),
+                    self._col(),
+                )
             )
 
     def insert(self, vectors: list[list[float]], payloads=None, ids=None) -> None:
@@ -195,14 +207,14 @@ class PGVector(VectorStoreBase):
         if PSYCOPG_VERSION == 3:
             with self._get_cursor(commit=True) as cur:
                 cur.executemany(
-                    f"INSERT INTO {self.collection_name} (id, vector, payload) VALUES (%s, %s, %s)",
+                    sql.SQL("INSERT INTO {} (id, vector, payload) VALUES (%s, %s, %s)").format(self._col()),
                     data,
                 )
         else:
             with self._get_cursor(commit=True) as cur:
                 execute_values(
                     cur,
-                    f"INSERT INTO {self.collection_name} (id, vector, payload) VALUES %s",
+                    sql.SQL("INSERT INTO {} (id, vector, payload) VALUES %s").format(self._col()),
                     data,
                 )
 
@@ -233,17 +245,17 @@ class PGVector(VectorStoreBase):
                 filter_conditions.append("payload->>%s = %s")
                 filter_params.extend([k, str(v)])
 
-        filter_clause = "WHERE " + " AND ".join(filter_conditions) if filter_conditions else ""
+        filter_clause = sql.SQL("WHERE " + " AND ".join(filter_conditions)) if filter_conditions else sql.SQL("")
 
         with self._get_cursor() as cur:
             cur.execute(
-                f"""
+                sql.SQL("""
                 SELECT id, vector <=> %s::vector AS distance, payload
-                FROM {self.collection_name}
-                {filter_clause}
+                FROM {}
+                {}
                 ORDER BY distance
                 LIMIT %s
-                """,
+                """).format(self._col(), filter_clause),
                 (vectors, *filter_params, top_k),
             )
 
@@ -270,21 +282,19 @@ class PGVector(VectorStoreBase):
                 filter_conditions.append("payload->>%s = %s")
                 filter_params.extend([k, str(v)])
 
-        filter_clause = ""
-        if filter_conditions:
-            filter_clause = "AND " + " AND ".join(filter_conditions)
+        filter_clause = sql.SQL("AND " + " AND ".join(filter_conditions)) if filter_conditions else sql.SQL("")
 
         try:
             with self._get_cursor() as cur:
                 cur.execute(
-                    f"""
+                    sql.SQL("""
                     SELECT id, ts_rank_cd(to_tsvector('simple', payload->>'text_lemmatized'), plainto_tsquery('simple', %s)) AS score, payload
-                    FROM {self.collection_name}
+                    FROM {}
                     WHERE to_tsvector('simple', payload->>'text_lemmatized') @@ plainto_tsquery('simple', %s)
-                    {filter_clause}
+                    {}
                     ORDER BY score DESC
                     LIMIT %s
-                    """,
+                    """).format(self._col(), filter_clause),
                     (query, query, *filter_params, top_k),
                 )
 
@@ -302,7 +312,7 @@ class PGVector(VectorStoreBase):
             vector_id (str): ID of the vector to delete.
         """
         with self._get_cursor(commit=True) as cur:
-            cur.execute(f"DELETE FROM {self.collection_name} WHERE id = %s", (vector_id,))
+            cur.execute(sql.SQL("DELETE FROM {} WHERE id = %s").format(self._col()), (vector_id,))
 
     def update(
         self,
@@ -321,7 +331,7 @@ class PGVector(VectorStoreBase):
         with self._get_cursor(commit=True) as cur:
             if vector:
                cur.execute(
-                    f"UPDATE {self.collection_name} SET vector = %s WHERE id = %s",
+                    sql.SQL("UPDATE {} SET vector = %s WHERE id = %s").format(self._col()),
                     (vector, vector_id),
                 )
             if payload:
@@ -329,13 +339,13 @@ class PGVector(VectorStoreBase):
                 if PSYCOPG_VERSION == 3:
                     # psycopg3 uses psycopg.types.json.Json
                     cur.execute(
-                        f"UPDATE {self.collection_name} SET payload = %s WHERE id = %s",
+                        sql.SQL("UPDATE {} SET payload = %s WHERE id = %s").format(self._col()),
                         (Json(payload), vector_id),
                     )
                 else:
                     # psycopg2 uses psycopg2.extras.Json
                     cur.execute(
-                        f"UPDATE {self.collection_name} SET payload = %s WHERE id = %s",
+                        sql.SQL("UPDATE {} SET payload = %s WHERE id = %s").format(self._col()),
                         (Json(payload), vector_id),
                     )
 
@@ -352,7 +362,7 @@ class PGVector(VectorStoreBase):
         """
         with self._get_cursor() as cur:
             cur.execute(
-                f"SELECT id, vector, payload FROM {self.collection_name} WHERE id = %s",
+                sql.SQL("SELECT id, vector, payload FROM {} WHERE id = %s").format(self._col()),
                 (vector_id,),
             )
             result = cur.fetchone()
@@ -374,7 +384,7 @@ class PGVector(VectorStoreBase):
     def delete_col(self) -> None:
         """Delete a collection."""
         with self._get_cursor(commit=True) as cur:
-            cur.execute(f"DROP TABLE IF EXISTS {self.collection_name}")
+            cur.execute(sql.SQL("DROP TABLE IF EXISTS {}").format(self._col()))
 
     def col_info(self) -> dict[str, Any]:
         """
@@ -385,14 +395,14 @@ class PGVector(VectorStoreBase):
         """
         with self._get_cursor() as cur:
             cur.execute(
-                f"""
+                sql.SQL("""
                 SELECT
                     table_name,
-                    (SELECT COUNT(*) FROM {self.collection_name}) as row_count,
-                    (SELECT pg_size_pretty(pg_total_relation_size('{self.collection_name}'))) as total_size
+                    (SELECT COUNT(*) FROM {}) as row_count,
+                    (SELECT pg_size_pretty(pg_total_relation_size({}::regclass))) as total_size
                 FROM information_schema.tables
                 WHERE table_schema = 'public' AND table_name = %s
-            """,
+            """).format(self._col(), sql.Literal(self.collection_name)),
                 (self.collection_name,),
             )
             result = cur.fetchone()
@@ -421,17 +431,18 @@ class PGVector(VectorStoreBase):
                 filter_conditions.append("payload->>%s = %s")
                 filter_params.extend([k, str(v)])
 
-        filter_clause = "WHERE " + " AND ".join(filter_conditions) if filter_conditions else ""
-
-        query = f"""
-            SELECT id, vector, payload
-            FROM {self.collection_name}
-            {filter_clause}
-            LIMIT %s
-        """
+        filter_clause = sql.SQL("WHERE " + " AND ".join(filter_conditions)) if filter_conditions else sql.SQL("")
 
         with self._get_cursor() as cur:
-            cur.execute(query, (*filter_params, top_k))
+            cur.execute(
+                sql.SQL("""
+                SELECT id, vector, payload
+                FROM {}
+                {}
+                LIMIT %s
+                """).format(self._col(), filter_clause),
+                (*filter_params, top_k),
+            )
             results = cur.fetchall()
         return [[OutputData(id=str(r[0]), score=None, payload=r[2]) for r in results]]
 

openclaw/README.md

@@ -2,7 +2,9 @@
 
 Long-term memory for [OpenClaw](https://github.com/openclaw/openclaw) agents, powered by [Mem0](https://mem0.ai).
 
-Your agent forgets everything between sessions. This plugin fixes that — it stores conversations, extracts what matters, and brings it back when relevant. Enable `autoRecall` and `autoCapture` in config to run this automatically, or use agent tools for explicit control.
+Your agent forgets everything between sessions. This plugin fixes that — it stores conversations, extracts what matters, and brings it back when relevant.
+
+By default, the plugin runs in **skills mode**: the agent controls what to remember (triage), how to recall (recall), and periodic cleanup (dream). Skills mode, `autoRecall`, and `autoCapture` are all enabled by default during `openclaw mem0 init`.
 
 ## Requirements
 
@@ -10,12 +12,12 @@ Check your OpenClaw version:
 
 ```bash
 openclaw --version
-# OpenClaw 2026.4.15 (041266a)
+# OpenClaw 2026.4.25 (aa36ee6)
 ```
 
 | OpenClaw Version | Plugin Support |
 |------------------|----------------|
-| `>= 2026.4.15`   | Fully supported |
+| `>= 2026.4.25`   | Fully supported |
 
 ## Quick Start
 
@@ -50,7 +52,19 @@ openclaw --version
            "enabled": true,
            "config": {
              "apiKey": "${MEM0_API_KEY}",
-             "userId": "alice"
+             "userId": "alice",
+             "skills": {
+               "triage": { "enabled": true },
+               "recall": {
+                 "enabled": true,
+                 "tokenBudget": 1500,
+                 "rerank": true,
+                 "keywordSearch": true,
+                 "identityAlwaysInclude": true
+               },
+               "dream": { "enabled": true },
+               "domain": "companion"
+             }
            }
          }
        }
@@ -182,11 +196,24 @@ All `oss` fields are optional. See the [Mem0 OSS docs](https://docs.mem0.ai/open
   <img src="https://raw.githubusercontent.com/mem0ai/mem0/main/docs/images/openclaw-architecture.png" alt="Architecture" width="800" />
 </p>
 
-**Auto-Recall** (`autoRecall: true`) — Before the agent responds, the plugin searches Mem0 for relevant memories and injects them into context.
+### Skills Mode (Default)
 
-**Auto-Capture** (`autoCapture: true`) — After the agent responds, the conversation is filtered through a noise-removal pipeline and sent to Mem0. New facts get stored, stale ones updated, duplicates merged.
+Enabled automatically during `openclaw mem0 init`. The agent controls memory through three skills:
 
-Both are opt-in. Once enabled, they run silently — no prompting, no manual calls required. Without them, the agent can still use memory tools (`memory_add`, `memory_search`, etc.) explicitly.
+- **Triage** — Extracts durable facts from conversations using a structured protocol. Categories, importance gates, and domain overlays control what gets stored.
+- **Recall** — Before each turn, rewrites the user message into search queries, retrieves relevant memories with reranking, and injects them into context.
+- **Dream** — Periodic memory consolidation: merges duplicates, resolves conflicts, and prunes stale entries.
+
+When skills mode is active, the skills handle memory operations. `autoRecall` and `autoCapture` remain `true` by default alongside skills mode. The built-in `session-memory` hook is disabled to avoid conflicts.
+
+### Auto-Recall & Auto-Capture
+
+When skills mode is not configured, the plugin uses `autoRecall` and `autoCapture` (both enabled by default):
+
+- **Auto-Recall** — Before the agent responds, the plugin searches Mem0 for relevant memories and injects them into context.
+- **Auto-Capture** — After the agent responds, the conversation is filtered through a noise-removal pipeline and sent to Mem0. New facts get stored, stale ones updated, duplicates merged.
+
+Set `autoRecall: false` or `autoCapture: false` to disable individually. The agent can also use memory tools (`memory_add`, `memory_search`, etc.) explicitly regardless of these settings.
 
 ### Memory Scopes
 
@@ -260,10 +287,25 @@ openclaw mem0 help --json                                   # discover all comma
 | --- | ---- | ------- | ----------- |
 | `mode` | `"platform"` \| `"open-source"` | `"platform"` | Backend mode |
 | `userId` | `string` | OS username | User identifier. All memories scoped to this value. |
-| `autoRecall` | `boolean` | `false` | Inject relevant memories before each turn |
-| `autoCapture` | `boolean` | `false` | Extract and store facts after each turn |
+| `autoRecall` | `boolean` | `true` | Inject relevant memories before each turn. Ignored when `skills` is set. |
+| `autoCapture` | `boolean` | `true` | Extract and store facts after each turn. Ignored when `skills` is set. |
 | `topK` | `number` | `5` | Max memories returned per recall |
-| `searchThreshold` | `number` | `0.3` | Minimum similarity score (0-1) |
+| `searchThreshold` | `number` | `0.1` | Minimum similarity score (0-1) |
+
+### Skills Mode (Recommended)
+
+Enabled by default during `openclaw mem0 init`. `autoRecall` and `autoCapture` are also `true` by default and work alongside skills mode.
+
+| Key | Type | Default | Description |
+| --- | ---- | ------- | ----------- |
+| `skills.triage.enabled` | `boolean` | `true` | Enable fact extraction from conversations |
+| `skills.recall.enabled` | `boolean` | `true` | Enable memory recall before each turn |
+| `skills.recall.tokenBudget` | `number` | `1500` | Max tokens for injected memories |
+| `skills.recall.rerank` | `boolean` | `true` | Rerank search results for relevance |
+| `skills.recall.keywordSearch` | `boolean` | `true` | Augment with keyword-based search |
+| `skills.recall.identityAlwaysInclude` | `boolean` | `true` | Always include identity memories |
+| `skills.dream.enabled` | `boolean` | `true` | Enable periodic memory consolidation |
+| `skills.domain` | `string` | `"companion"` | Domain overlay for triage rules |
 
 ### Platform Mode
 
@@ -306,13 +348,15 @@ To avoid plaintext credentials:
 - Use env var references: `"apiKey": "${MEM0_API_KEY}"`
 - Use SecretRef: `"apiKey": {"source": "env", "provider": "default", "id": "MEM0_API_KEY"}`
 
-### Auto-Capture & Auto-Recall
+### Memory Processing
 
-Both are **disabled by default** (`false`). When enabled:
-- `autoCapture`: sends conversation content to your configured backend (cloud or local) after each agent turn
-- `autoRecall`: queries your memory store before each agent turn and injects results into agent context
+In **skills mode** (default after `openclaw mem0 init`), the agent uses structured protocols (triage, recall, dream) to decide what to store and recall. The built-in `session-memory` hook is disabled to avoid conflicts.
 
-Do not enable `autoCapture` in platform mode if your conversations contain sensitive data you do not want stored on Mem0 cloud.
+Without skills, `autoCapture` and `autoRecall` are both enabled by default:
+- `autoCapture`: sends conversation content to your configured backend after each agent turn
+- `autoRecall`: queries your memory store before each agent turn and injects results into context
+
+In platform mode, conversation content is sent to `api.mem0.ai` for processing. Do not use with sensitive data you do not want stored on Mem0 cloud.
 
 ### Persistence Locations
 

openclaw/cli/commands.ts

@@ -43,6 +43,7 @@ import {
   readPluginAuth,
   writePluginAuth,
   writePluginConfigField,
+  enableSkillsConfig,
   OPENCLAW_CONFIG_FILE,
 } from "./config-file.ts";
 import { jsonOut, jsonErr, redactSecrets } from "./json-helpers.ts";
@@ -50,6 +51,7 @@ import {
   LLM_PROVIDERS, EMBEDDER_PROVIDERS, VECTOR_PROVIDERS,
   buildOssLlmConfig, buildOssEmbedderConfig, buildOssVectorConfig,
   validateOssFlags, checkQdrantConnectivity, checkOllamaConnectivity, checkPgConnectivity,
+  collectionNameForDims,
 } from "./oss-wizard.ts";
 
 // ============================================================================
@@ -213,10 +215,11 @@ function saveLoginConfig(
   const userId = resolveUserId(userIdFlag, existingAuth.userId);
 
   writePluginAuth({ apiKey, userId, mode: "platform", ...(userEmail && { userEmail }) });
+  enableSkillsConfig(userId);
 
   if (!silent) {
     console.log(`  Configuration saved to ${OPENCLAW_CONFIG_FILE}`);
-    console.log(`  Mode: platform`);
+    console.log(`  Mode: platform (skills enabled)`);
     console.log(`  User ID: ${userId}`);
   }
 }
@@ -226,10 +229,11 @@ function saveOssConfig(userIdFlag?: string, silent?: boolean): void {
   const userId = resolveUserId(userIdFlag, existingAuth.userId);
 
   writePluginAuth({ apiKey: "", userId, mode: "open-source" });
+  enableSkillsConfig(userId);
 
   if (!silent) {
     console.log(`  Configuration saved to ${OPENCLAW_CONFIG_FILE}`);
-    console.log(`  Mode: open-source`);
+    console.log(`  Mode: open-source (skills enabled)`);
     console.log(`  User ID: ${userId}`);
   }
 }
@@ -350,6 +354,17 @@ async function runOssWizardInteractive(
   }
 
   const vecCfg = buildOssVectorConfig(vecDef.id, vecInput as any);
+
+  // Warn if switching embedder dimensions — old collection will have wrong vector size
+  const existingVecCfg = existingAuth as any;
+  const oldDims = existingVecCfg?.oss?.vectorStore?.config?.dimension as number | undefined;
+  if (oldDims && dims && oldDims !== dims) {
+    console.log(`\n  ⚠ Dimension change detected: ${oldDims} → ${dims}`);
+    console.log(`    Old collection had ${oldDims}-dim vectors. New embedder produces ${dims}-dim vectors.`);
+    console.log(`    A new collection "${collectionNameForDims(dims)}" will be created.`);
+    console.log(`    Old memories in the previous collection will NOT be accessible with the new embedder.\n`);
+  }
+
   writePluginConfigField(["oss", "vectorStore"], vecCfg);
 
   // === Step 4: User ID ===
@@ -370,6 +385,8 @@ async function runOssWizardInteractive(
   console.log(`    LLM:       ${llmDef.id} (${llmCfg.config.model})`);
   console.log(`    Embedder:  ${embDef.id} (${embCfg.config.model})`);
   console.log(`    Vector:    ${vecDef.id} (${vecDef.id === "qdrant" ? vecCfg.config.url : vecCfg.config.host})`);
+  console.log(`    Dims:      ${dims ?? "unknown"}`);
+  console.log(`    Collection:${dims ? " " + collectionNameForDims(dims) : " (default)"}`);
   console.log(`    User ID:   ${userIdValue}`);
   console.log("");
   console.log("  Run: openclaw gateway restart");
@@ -539,6 +556,15 @@ export function registerCliCommands(
                   }
                 }
 
+                // Warn on dimension change
+                const prevAuth = readPluginAuth() as any;
+                const prevDims = prevAuth?.oss?.vectorStore?.config?.dimension as number | undefined;
+                const newDims = dims;
+                let dimWarning: string | undefined;
+                if (prevDims && newDims && prevDims !== newDims) {
+                  dimWarning = `Dimension change: ${prevDims} → ${newDims}. New collection "${collectionNameForDims(newDims)}" will be used. Old memories not accessible with new embedder.`;
+                }
+
                 writePluginConfigField(["oss", "llm"], llmCfg);
                 writePluginConfigField(["oss", "embedder"], { provider: embCfg.provider, config: embCfg.config });
                 writePluginConfigField(["oss", "vectorStore"], vecCfg);
@@ -550,9 +576,10 @@ export function registerCliCommands(
                   mode: "open-source",
                   config: {
                     llm: { provider: llmCfg.provider, model: llmCfg.config.model },
-                    embedder: { provider: embCfg.provider, model: embCfg.config.model },
-                    vectorStore: { provider: vecCfg.provider, ...(vecId === "qdrant" ? { url: vecCfg.config.url } : { host: vecCfg.config.host }) },
+                    embedder: { provider: embCfg.provider, model: embCfg.config.model, dims: newDims },
+                    vectorStore: { provider: vecCfg.provider, ...(vecId === "qdrant" ? { url: vecCfg.config.url } : { host: vecCfg.config.host }), collectionName: newDims ? collectionNameForDims(newDims) : undefined },
                   },
+                  ...(dimWarning && { warning: dimWarning }),
                   userId: resolveUserId(opts.userId, existingAuth.userId),
                   message: "Open-source mode configured. Restart the gateway: openclaw gateway restart",
                 };
@@ -889,7 +916,7 @@ export function registerCliCommands(
                 runId?: string,
               ): SearchOptions => {
                 const base = buildSearchOptions(userIdOverride, lim, runId);
-                base.threshold = 0.3;
+                base.threshold = 0.1;
                 return base;
               };
 

openclaw/cli/config-file.ts

@@ -19,7 +19,6 @@ export const OPENCLAW_CONFIG_FILE = join(OPENCLAW_CONFIG_DIR, "openclaw.json");
 export const DEFAULT_BASE_URL = "https://api.mem0.ai";
 
 const PLUGIN_ID = "openclaw-mem0";
-const NPM_PACKAGE = "@mem0/openclaw-mem0";
 
 // ============================================================================
 // Types
@@ -76,11 +75,44 @@ function readFullConfig(): Record<string, unknown> {
   }
 }
 
-/** Write the full ~/.openclaw/openclaw.json (preserves all non-plugin config) */
+/**
+ * Write the full ~/.openclaw/openclaw.json.
+ *
+ * Re-reads the file immediately before writing and deep-merges the
+ * `plugins` section so that fields written by other processes (e.g.
+ * OpenClaw gateway adding `installs`, `slots`) are not clobbered.
+ */
 function writeFullConfig(config: Record<string, unknown>): void {
   if (!exists(OPENCLAW_CONFIG_DIR)) {
     mkdirp(OPENCLAW_CONFIG_DIR, 0o700);
   }
+
+  if (exists(OPENCLAW_CONFIG_FILE)) {
+    try {
+      const diskText = readText(OPENCLAW_CONFIG_FILE);
+      if (diskText.trim()) {
+        const disk = JSON.parse(diskText) as Record<string, unknown>;
+        const diskPlugins = disk.plugins as Record<string, unknown> | undefined;
+        const ourPlugins = config.plugins as Record<string, unknown> | undefined;
+        if (diskPlugins && ourPlugins) {
+          const OPENCLAW_MANAGED = ["installs", "slots"];
+          for (const key of OPENCLAW_MANAGED) {
+            if (key in diskPlugins) {
+              ourPlugins[key] = diskPlugins[key];
+            }
+          }
+          for (const key of Object.keys(diskPlugins)) {
+            if (!(key in ourPlugins)) {
+              ourPlugins[key] = diskPlugins[key];
+            }
+          }
+        }
+      }
+    } catch {
+      // disk unreadable — write our version as-is
+    }
+  }
+
   writeText(
     OPENCLAW_CONFIG_FILE,
     JSON.stringify(config, null, 2),
@@ -122,82 +154,6 @@ export function writePluginAuth(auth: PluginAuthConfig): void {
   writeFullConfig(full);
 }
 
-/**
- * Ensure the plugin has a valid install record and is in plugins.allow.
- *
- * OpenClaw's `plugins update` command requires a `plugins.installs.<id>`
- * record with `source: "npm"` and `spec` to know how to update. Without
- * this, `openclaw plugins update` prints "No install record" and skips.
- *
- * Similarly, if `plugins.allow` exists as an array, the plugin ID must
- * be in it or OpenClaw treats the plugin as untrusted.
- *
- * This is safe to call multiple times — it only writes missing fields.
- */
-export function ensureInstallRecord(): void {
-  try {
-    const full = readFullConfig() as any;
-
-    const entry = full?.plugins?.entries?.[PLUGIN_ID];
-    const record = full?.plugins?.installs?.[PLUGIN_ID];
-    const allow = full?.plugins?.allow;
-    const specPinned = record?.spec && /\d+\.\d+\.\d+/.test(record.spec);
-    if (
-      entry?.enabled === true &&
-      record?.source &&
-      record?.spec &&
-      !specPinned &&
-      Array.isArray(allow) &&
-      allow.includes(PLUGIN_ID)
-    ) {
-      return;
-    }
-
-    ensurePluginStructure(full);
-
-    let changed = false;
-
-    // Ensure install record exists for `openclaw plugins update` support
-    if (!full.plugins.installs) full.plugins.installs = {};
-    if (!full.plugins.installs[PLUGIN_ID]) {
-      full.plugins.installs[PLUGIN_ID] = {
-        source: "npm",
-        spec: `${NPM_PACKAGE}@latest`,
-        resolvedName: NPM_PACKAGE,
-        installedAt: new Date().toISOString(),
-      };
-      changed = true;
-    } else {
-      const record = full.plugins.installs[PLUGIN_ID];
-      if (!record.source) {
-        record.source = "npm";
-        changed = true;
-      }
-      if (!record.spec || /\d+\.\d+\.\d+/.test(record.spec)) {
-        record.spec = record.source === "clawhub"
-          ? `clawhub:${NPM_PACKAGE}`
-          : `${NPM_PACKAGE}@latest`;
-        changed = true;
-      }
-      if (!record.resolvedName) {
-        record.resolvedName = NPM_PACKAGE;
-        changed = true;
-      }
-    }
-
-    if (!Array.isArray(full.plugins.allow)) {
-      full.plugins.allow = [PLUGIN_ID];
-      changed = true;
-    } else if (!full.plugins.allow.includes(PLUGIN_ID)) {
-      full.plugins.allow.push(PLUGIN_ID);
-      changed = true;
-    }
-
-    if (changed) writeFullConfig(full);
-  } catch {
-    // Best-effort — don't break plugin loading if config is unreadable
-  }
-}
 
 /** Ensure the nested plugin entry structure exists in the config object. */
 function ensurePluginStructure(full: any): void {
@@ -231,6 +187,50 @@ export function writePluginConfigField(
   writeFullConfig(full);
 }
 
+/**
+ * Default skills configuration — matches configure.py output.
+ * Enables triage, recall (with reranking), and dream consolidation.
+ */
+const DEFAULT_SKILLS_CONFIG = {
+  triage: { enabled: true },
+  recall: {
+    enabled: true,
+    tokenBudget: 1500,
+    rerank: true,
+    keywordSearch: true,
+    identityAlwaysInclude: true,
+  },
+  dream: { enabled: true },
+  domain: "companion",
+};
+
+/**
+ * Enable skills-mode config after onboarding.
+ *
+ * Sets skills config on the plugin entry, tools.profile = "full",
+ * and disables the built-in session-memory hook to avoid conflicts.
+ * Preserves any existing skills config if already set.
+ */
+export function enableSkillsConfig(userId: string): void {
+  const full = readFullConfig() as any;
+  ensurePluginStructure(full);
+
+  const cfg = full.plugins.entries[PLUGIN_ID].config;
+  if (!cfg.skills) {
+    cfg.skills = { ...DEFAULT_SKILLS_CONFIG };
+  }
+
+  if (!full.tools) full.tools = {};
+  full.tools.profile = "full";
+
+  if (!full.hooks) full.hooks = {};
+  if (!full.hooks.internal) full.hooks.internal = {};
+  if (!full.hooks.internal.entries) full.hooks.internal.entries = {};
+  full.hooks.internal.entries["session-memory"] = { enabled: false };
+
+  writeFullConfig(full);
+}
+
 /** Get the configured base URL from openclaw.json or default */
 export function getBaseUrl(): string {
   const auth = readPluginAuth();

openclaw/cli/oss-wizard.ts

@@ -56,8 +56,15 @@ export const KNOWN_EMBEDDER_DIMS: Record<string, number> = {
   "text-embedding-3-large": 3072,
   "text-embedding-ada-002": 1536,
   "nomic-embed-text": 768,
+  "mxbai-embed-large": 1024,
+  "all-minilm": 384,
+  "snowflake-arctic-embed": 1024,
 };
 
+export function collectionNameForDims(dims: number): string {
+  return `mem0_${dims}d`;
+}
+
 // ============================================================================
 // Config builders
 // ============================================================================
@@ -105,7 +112,8 @@ export function buildOssEmbedderConfig(
     config.url = input.url || def.defaultUrl;
   }
 
-  const dims = KNOWN_EMBEDDER_DIMS[model] ?? undefined;
+  const dims = KNOWN_EMBEDDER_DIMS[model] ?? def.defaultDims;
+  if (dims) config.embeddingDims = dims;
   return { provider: providerId, config, dims };
 }
 
@@ -138,7 +146,11 @@ export function buildOssVectorConfig(
     config.dbname = input.dbname || "postgres";
   }
 
-  if (input.dims) config.dimension = input.dims;
+  if (input.dims) {
+    config.dimension = input.dims;
+    config.embeddingModelDims = input.dims;
+    config.collectionName = collectionNameForDims(input.dims);
+  }
   return { provider: providerId, config };
 }
 

openclaw/config.ts

@@ -231,8 +231,8 @@ export const mem0ConfigSchema = {
                 return "default";
               }
             })(),
-      autoCapture: cfg.autoCapture === true,
-      autoRecall: cfg.autoRecall === true,
+      autoCapture: cfg.autoCapture !== false,
+      autoRecall: cfg.autoRecall !== false,
       // v3.0.0: customPrompt renamed to customInstructions (backwards-compat: accept either)
       customInstructions:
         typeof cfg.customInstructions === "string"
@@ -247,7 +247,7 @@ export const mem0ConfigSchema = {
           ? (cfg.customCategories as Record<string, string>)
           : DEFAULT_CUSTOM_CATEGORIES,
       searchThreshold:
-        typeof cfg.searchThreshold === "number" ? cfg.searchThreshold : 0.5,
+        typeof cfg.searchThreshold === "number" ? cfg.searchThreshold : 0.1,
       topK: typeof cfg.topK === "number" ? cfg.topK : 5,
       needsSetup,
       oss: ossConfig,

openclaw/index.test.ts

@@ -561,3 +561,52 @@ What is the deployment plan?`,
     expect(result).toHaveLength(2);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Auto-recall threshold filtering
+// The recall hook in index.ts filters search results using cfg.searchThreshold.
+// These tests verify the threshold is honored and no hardcoded floor overrides it.
+// ---------------------------------------------------------------------------
+describe("auto-recall threshold respects cfg.searchThreshold", () => {
+  const typicalV3Results = [
+    { id: "1", score: 0.553, memory: "User prefers dark mode" },
+    { id: "2", score: 0.496, memory: "User works on mem0 project" },
+    { id: "3", score: 0.471, memory: "User likes TypeScript" },
+    { id: "4", score: 0.45, memory: "User's timezone is PST" },
+    { id: "5", score: 0.42, memory: "User uses VS Code" },
+    { id: "6", score: 0.35, memory: "User mentioned family trip" },
+  ];
+
+  function applyThresholdFilter(
+    results: typeof typicalV3Results,
+    searchThreshold: number,
+  ) {
+    return results.filter((r) => (r.score ?? 0) >= searchThreshold);
+  }
+
+  it("default 0.5 threshold returns results scoring >= 0.5", () => {
+    const filtered = applyThresholdFilter(typicalV3Results, 0.5);
+    expect(filtered).toHaveLength(1);
+    expect(filtered[0].id).toBe("1");
+  });
+
+  it("threshold 0.4 returns results scoring >= 0.4", () => {
+    const filtered = applyThresholdFilter(typicalV3Results, 0.4);
+    expect(filtered).toHaveLength(5);
+  });
+
+  it("threshold 0.3 returns all results", () => {
+    const filtered = applyThresholdFilter(typicalV3Results, 0.3);
+    expect(filtered).toHaveLength(6);
+  });
+
+  it("threshold 0.6 correctly filters everything below", () => {
+    const filtered = applyThresholdFilter(typicalV3Results, 0.6);
+    expect(filtered).toHaveLength(0);
+  });
+
+  it("threshold 0 returns all results", () => {
+    const filtered = applyThresholdFilter(typicalV3Results, 0);
+    expect(filtered).toHaveLength(6);
+  });
+});

openclaw/index.ts

@@ -54,15 +54,12 @@ import {
 import { PlatformBackend } from "./backend/platform.ts";
 import type { Backend } from "./backend/base.ts";
 import { registerCliCommands } from "./cli/commands.ts";
-import { readPluginAuth, ensureInstallRecord } from "./cli/config-file.ts";
+import { readPluginAuth } from "./cli/config-file.ts";
 import { registerAllTools } from "./tools/index.ts";
 import type { ToolDeps } from "./tools/index.ts";
 import { captureEvent } from "./telemetry.ts";
 import { bootstrapTelemetryFlag } from "./fs-safe.ts";
 
-bootstrapTelemetryFlag();
-ensureInstallRecord();
-
 // ============================================================================
 // Re-exports (for tests and external consumers)
 // ============================================================================
@@ -100,6 +97,8 @@ const memoryPlugin = definePluginEntry({
   description: "Mem0 memory backend — Mem0 platform or self-hosted open-source",
 
   register(api: OpenClawPluginApi) {
+    bootstrapTelemetryFlag();
+
     // Read auth from openclaw.json plugin config (picks up post-startup login).
     // This is the single source of truth — set via `openclaw mem0 login`.
     const pluginAuth = readPluginAuth();
@@ -207,8 +206,57 @@ const memoryPlugin = definePluginEntry({
           },
           effectiveUserId: _effectiveUserId,
         }),
+        runtime: {
+          async getMemorySearchManager(_params: any) {
+            try {
+              const userId = _effectiveUserId();
+              let memoryCount = 0;
+              try {
+                const memories = await provider.getAll({
+                  user_id: userId,
+                  page_size: 1,
+                  source: "OPENCLAW",
+                });
+                memoryCount = Array.isArray(memories) ? memories.length : 0;
+              } catch {
+                // Non-fatal: status still works without count
+              }
+              return {
+                manager: {
+                  status() {
+                    return {
+                      backend: cfg.mode,
+                      files: 0,
+                      chunks: memoryCount,
+                      dirty: false,
+                      workspaceDir: pluginStateDir ?? "",
+                      userId,
+                    };
+                  },
+                  async probeEmbeddingAvailability() {
+                    return { ok: true };
+                  },
+                  async close() {},
+                },
+              };
+            } catch (err) {
+              return {
+                manager: null,
+                error: `mem0 ${cfg.mode} backend unavailable: ${String(err)}`,
+              };
+            }
+          },
+          resolveMemoryBackendConfig(_params: any) {
+            return {
+              backend: cfg.mode,
+              baseUrl: cfg.baseUrl ?? "https://api.mem0.ai",
+              userId: cfg.userId,
+            };
+          },
+          async closeAllMemorySearchManagers() {},
+        },
       });
-      api.logger.debug("openclaw-mem0: publicArtifacts capability registered");
+      api.logger.debug("openclaw-mem0: memory capability + runtime registered");
     }
 
     // Helper: build add options
@@ -681,12 +729,8 @@ function registerHooks(
           ),
         );
 
-        // Client-side threshold filter for auto-recall — use a stricter
-        // threshold (0.6) than explicit tool searches (0.5) to avoid
-        // injecting irrelevant memories into agent context
-        const recallThreshold = Math.max(cfg.searchThreshold, 0.6);
         longTermResults = longTermResults.filter(
-          (r) => (r.score ?? 0) >= recallThreshold,
+          (r) => (r.score ?? 0) >= cfg.searchThreshold,
         );
 
         // Dynamic thresholding: drop memories scoring less than 50% of
@@ -709,7 +753,7 @@ function registerHooks(
             undefined,
             recallSessionKey,
           );
-          broadOpts.threshold = 0.5;
+          broadOpts.threshold = cfg.searchThreshold;
           const broadResults = await provider.search(
             "recent decisions, preferences, active projects, and configuration",
             broadOpts,

openclaw/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-mem0",
   "name": "Memory (Mem0)",
   "description": "Mem0 memory backend for OpenClaw — platform (mem0.ai cloud) or self-hosted open-source. Auto-recall and auto-capture are opt-in (disabled by default). Supports OpenAI, Anthropic, Ollama (fully local), Qdrant, and PGVector providers.",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "kind": "memory",
   "skills": ["skills"],
   "commandAliases": [
@@ -17,9 +17,17 @@
       "memory_update", "memory_delete", "memory_event_list", "memory_event_status"
     ]
   },
-  "providerAuthEnvVars": {
-    "mem0": ["MEM0_API_KEY"],
-    "openclaw-mem0-oss": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"]
+  "setup": {
+    "providers": [
+      {
+        "id": "mem0",
+        "envVars": ["MEM0_API_KEY"]
+      },
+      {
+        "id": "openclaw-mem0-oss",
+        "envVars": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"]
+      }
+    ]
   },
   "providerAuthChoices": [
     {
@@ -171,13 +179,13 @@
       },
       "autoCapture": {
         "type": "boolean",
-        "default": false,
-        "description": "Opt-in. When true, extracts durable facts after each agent turn. Disabled by default."
+        "default": true,
+        "description": "When true, extracts durable facts after each agent turn. Enabled by default. Ignored in skills mode."
       },
       "autoRecall": {
         "type": "boolean",
-        "default": false,
-        "description": "Opt-in. When true, injects relevant memories before each agent turn. Disabled by default."
+        "default": true,
+        "description": "When true, injects relevant memories before each agent turn. Enabled by default. Ignored in skills mode."
       },
       "customInstructions": {
         "type": "string"

openclaw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mem0/openclaw-mem0",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "type": "module",
   "description": "Mem0 memory backend for OpenClaw — platform or self-hosted open-source",
   "license": "Apache-2.0",
@@ -35,19 +35,19 @@
   },
   "dependencies": {
     "@sinclair/typebox": "0.34.47",
-    "mem0ai": "3.0.1"
+    "mem0ai": "3.0.2"
   },
   "openclaw": {
     "extensions": [
       "./dist/index.js"
     ],
     "compat": {
-      "pluginApi": ">=2026.3.28",
-      "minGatewayVersion": ">=2026.3.28"
+      "pluginApi": ">=2026.4.24",
+      "minGatewayVersion": ">=2026.4.24"
     },
     "build": {
-      "openclawVersion": "2026.4.1",
-      "pluginSdkVersion": "2026.4.1"
+      "openclawVersion": "2026.4.24",
+      "pluginSdkVersion": "2026.4.24"
     },
     "install": {
       "npmSpec": "@mem0/openclaw-mem0"
@@ -59,5 +59,10 @@
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vitest": "^4.0.18"
+  },
+  "pnpm": {
+    "overrides": {
+      "protobufjs@<7.5.5": "^7.5.5"
+    }
   }
 }

openclaw/pnpm-lock.yaml

@@ -4,6 +4,9 @@ settings:
   autoInstallPeers: true
   excludeLinksFromLockfile: false
 
+overrides:
+  protobufjs@<7.5.5: ^7.5.5
+
 importers:
 
   .:
@@ -12,8 +15,8 @@ importers:
         specifier: 0.34.47
         version: 0.34.47
       mem0ai:
-        specifier: 3.0.1
-        version: 3.0.1(@anthropic-ai/sdk@0.40.1)(@azure/identity@4.13.0)(@azure/search-documents@12.2.0)(@cloudflare/workers-types@4.20260313.1)(@google/genai@1.45.0)(@langchain/core@0.3.80(openai@4.104.0(ws@8.19.0)(zod@3.25.76)))(@mistralai/mistralai@1.15.1)(@qdrant/js-client-rest@1.13.0(typescript@5.9.3))(@supabase/supabase-js@2.99.1)(@types/jest@29.5.14)(@types/pg@8.11.0)(better-sqlite3@12.8.0)(cloudflare@4.5.0)(compromise@14.15.0)(groq-sdk@0.3.0)(natural@8.1.1)(ollama@0.5.18)(pg@8.20.0)(redis@5.12.1)(ws@8.19.0)
+        specifier: 3.0.2
+        version: 3.0.2(@anthropic-ai/sdk@0.40.1)(@azure/identity@4.13.0)(@azure/search-documents@12.2.0)(@cloudflare/workers-types@4.20260313.1)(@google/genai@1.45.0)(@langchain/core@0.3.80(openai@4.104.0(ws@8.19.0)(zod@3.25.76)))(@mistralai/mistralai@1.15.1)(@qdrant/js-client-rest@1.13.0(typescript@5.9.3))(@supabase/supabase-js@2.99.1)(@types/jest@29.5.14)(@types/pg@8.11.0)(better-sqlite3@12.8.0)(cloudflare@4.5.0)(compromise@14.15.0)(groq-sdk@0.3.0)(natural@8.1.1)(ollama@0.5.18)(pg@8.20.0)(redis@5.12.1)(ws@8.19.0)
     devDependencies:
       '@types/node':
         specifier: ^22.15.0
@@ -363,8 +366,8 @@ packages:
   '@protobufjs/base64@1.1.2':
     resolution: {integrity: sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==}
 
-  '@protobufjs/codegen@2.0.4':
-    resolution: {integrity: sha512-YyFaikqM5sH0ziFZCN3xDC7zeGaB/d0IUb9CATugHWbd1FRFwWwt4ld4OYMPWu5a3Xe01mGAULCdqhMlPl29Jg==}
+  '@protobufjs/codegen@2.0.5':
+    resolution: {integrity: sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==}
 
   '@protobufjs/eventemitter@1.1.0':
     resolution: {integrity: sha512-j9ednRT81vYJ9OfVuXG6ERSTdEL1xVsNgqpkxMsbIabzSo3goCjDIveeGv5d03om39ML71RdmrGNjG5SReBP/Q==}
@@ -375,8 +378,8 @@ packages:
   '@protobufjs/float@1.0.2':
     resolution: {integrity: sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==}
 
-  '@protobufjs/inquire@1.1.0':
-    resolution: {integrity: sha512-kdSefcPdruJiFMVSbn801t4vFK7KB/5gd2fYvrxhuJYg8ILrmn9SKSX2tZdV6V+ksulWqS7aXjBcRXl3wHoD9Q==}
+  '@protobufjs/inquire@1.1.1':
+    resolution: {integrity: sha512-mnzgDV26ueAvk7rsbt9L7bE0SuAoqyuys/sMMrmVcN5x9VsxpcG3rqAUSgDyLp0UZlmNfIbQ4fHfCtreVBk8Ew==}
 
   '@protobufjs/path@1.1.2':
     resolution: {integrity: sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==}
@@ -384,8 +387,8 @@ packages:
   '@protobufjs/pool@1.1.0':
     resolution: {integrity: sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==}
 
-  '@protobufjs/utf8@1.1.0':
-    resolution: {integrity: sha512-Vvn3zZrhQZkkBE8LSuW3em98c0FwgO4nxzv6OdSxPKJIEKY2bGbHn+mhGIPerzI4twdxaP8/0+06HBpwf345Lw==}
+  '@protobufjs/utf8@1.1.1':
+    resolution: {integrity: sha512-oOAWABowe8EAbMyWKM0tYDKi8Yaox52D+HWZhAIJqQXbqe0xI/GV7FhLWqlEKreMkfDjshR5FKgi3mnle0h6Eg==}
 
   '@qdrant/js-client-rest@1.13.0':
     resolution: {integrity: sha512-bewMtnXlGvhhnfXsp0sLoLXOGvnrCM15z9lNlG0Snp021OedNAnRtKkerjk5vkOcbQWUmJHXYCuxDfcT93aSkA==}
@@ -1505,8 +1508,8 @@ packages:
   md5@2.3.0:
     resolution: {integrity: sha512-T1GITYmFaKuO91vxyoQMFETst+O71VUPEU3ze5GNzDm0OWdP8v1ziTaAEPUr/3kLsY3Sftgz242A1SetQiDL7g==}
 
-  mem0ai@3.0.1:
-    resolution: {integrity: sha512-6phM544/3NRcCg7n5DBNRc9uUEMqGTe7sksULM2KM/FTihH27yTl5nPms8cnNpSKM5/ZKJ9jnkpzwGlvYYbtBQ==}
+  mem0ai@3.0.2:
+    resolution: {integrity: sha512-smB9q27jrJu2D5WZje65+zMVptdS/WsqALxd2kjiZhEpThd/qkS8T3bumatcTu6Zb+LsT28FRpeWjXGTJjyQXQ==}
     engines: {node: '>=18'}
     peerDependencies:
       '@anthropic-ai/sdk': ^0.40.1
@@ -1845,8 +1848,8 @@ packages:
     resolution: {integrity: sha512-Pdlw/oPxN+aXdmM9R00JVC9WVFoCLTKJvDVLgmJ+qAffBMxsV85l/Lu7sNx4zSzPyoL2euImuEwHhOXdEgNFZQ==}
     engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0}
 
-  protobufjs@7.5.4:
-    resolution: {integrity: sha512-CvexbZtbov6jW2eXAvLukXjXUW1TzFaivC46BpWc/3BpcCysb5Vffu+B3XHMm8lVEuy2Mm4XGex8hBSg1yapPg==}
+  protobufjs@7.5.6:
+    resolution: {integrity: sha512-M71sTMB146U3u0di3yup8iM+zv8yPRNQVr1KK4tyBitl3qFvEGucq/rGDRShD2rsJhtN02RJaJ7j5X5hmy8SJg==}
     engines: {node: '>=12.0.0'}
 
   proxy-from-env@1.1.0:
@@ -2536,7 +2539,7 @@ snapshots:
     dependencies:
       google-auth-library: 10.6.1
       p-retry: 4.6.2
-      protobufjs: 7.5.4
+      protobufjs: 7.5.6
       ws: 8.19.0
     transitivePeerDependencies:
       - bufferutil
@@ -2634,24 +2637,24 @@ snapshots:
 
   '@protobufjs/base64@1.1.2': {}
 
-  '@protobufjs/codegen@2.0.4': {}
+  '@protobufjs/codegen@2.0.5': {}
 
   '@protobufjs/eventemitter@1.1.0': {}
 
   '@protobufjs/fetch@1.1.0':
     dependencies:
       '@protobufjs/aspromise': 1.1.2
-      '@protobufjs/inquire': 1.1.0
+      '@protobufjs/inquire': 1.1.1
 
   '@protobufjs/float@1.0.2': {}
 
-  '@protobufjs/inquire@1.1.0': {}
+  '@protobufjs/inquire@1.1.1': {}
 
   '@protobufjs/path@1.1.2': {}
 
   '@protobufjs/pool@1.1.0': {}
 
-  '@protobufjs/utf8@1.1.0': {}
+  '@protobufjs/utf8@1.1.1': {}
 
   '@qdrant/js-client-rest@1.13.0(typescript@5.9.3)':
     dependencies:
@@ -3687,7 +3690,7 @@ snapshots:
       crypt: 0.0.2
       is-buffer: 1.1.6
 
-  mem0ai@3.0.1(@anthropic-ai/sdk@0.40.1)(@azure/identity@4.13.0)(@azure/search-documents@12.2.0)(@cloudflare/workers-types@4.20260313.1)(@google/genai@1.45.0)(@langchain/core@0.3.80(openai@4.104.0(ws@8.19.0)(zod@3.25.76)))(@mistralai/mistralai@1.15.1)(@qdrant/js-client-rest@1.13.0(typescript@5.9.3))(@supabase/supabase-js@2.99.1)(@types/jest@29.5.14)(@types/pg@8.11.0)(better-sqlite3@12.8.0)(cloudflare@4.5.0)(compromise@14.15.0)(groq-sdk@0.3.0)(natural@8.1.1)(ollama@0.5.18)(pg@8.20.0)(redis@5.12.1)(ws@8.19.0):
+  mem0ai@3.0.2(@anthropic-ai/sdk@0.40.1)(@azure/identity@4.13.0)(@azure/search-documents@12.2.0)(@cloudflare/workers-types@4.20260313.1)(@google/genai@1.45.0)(@langchain/core@0.3.80(openai@4.104.0(ws@8.19.0)(zod@3.25.76)))(@mistralai/mistralai@1.15.1)(@qdrant/js-client-rest@1.13.0(typescript@5.9.3))(@supabase/supabase-js@2.99.1)(@types/jest@29.5.14)(@types/pg@8.11.0)(better-sqlite3@12.8.0)(cloudflare@4.5.0)(compromise@14.15.0)(groq-sdk@0.3.0)(natural@8.1.1)(ollama@0.5.18)(pg@8.20.0)(redis@5.12.1)(ws@8.19.0):
     dependencies:
       '@anthropic-ai/sdk': 0.40.1
       '@azure/identity': 4.13.0
@@ -4020,18 +4023,18 @@ snapshots:
       ansi-styles: 5.2.0
       react-is: 18.3.1
 
-  protobufjs@7.5.4:
+  protobufjs@7.5.6:
     dependencies:
       '@protobufjs/aspromise': 1.1.2
       '@protobufjs/base64': 1.1.2
-      '@protobufjs/codegen': 2.0.4
+      '@protobufjs/codegen': 2.0.5
       '@protobufjs/eventemitter': 1.1.0
       '@protobufjs/fetch': 1.1.0
       '@protobufjs/float': 1.0.2
-      '@protobufjs/inquire': 1.1.0
+      '@protobufjs/inquire': 1.1.1
       '@protobufjs/path': 1.1.2
       '@protobufjs/pool': 1.1.0
-      '@protobufjs/utf8': 1.1.0
+      '@protobufjs/utf8': 1.1.1
       '@types/node': 22.19.15
       long: 5.3.2
 

openclaw/providers.ts

@@ -280,13 +280,29 @@ class OSSProvider implements Mem0Provider {
       config.llm = defaultLlm;
     }
 
-    if (this.ossConfig?.vectorStore)
-      config.vectorStore = { ...this.ossConfig.vectorStore };
+    if (this.ossConfig?.vectorStore) {
+      const vs = { ...this.ossConfig.vectorStore } as Record<string, unknown>;
+      const vsCfg = (vs.config ?? {}) as Record<string, unknown>;
+      // Resolve dims from embedder config if vector store doesn't have them
+      const embedderDims = (config.embedder as any)?.config?.embeddingDims;
+      if (!vsCfg.dimension && embedderDims) {
+        vsCfg.dimension = embedderDims;
+      }
+      // Sync both dimension fields — Qdrant reads dimension, PGVector reads embeddingModelDims
+      if (vsCfg.dimension && !vsCfg.embeddingModelDims) {
+        vsCfg.embeddingModelDims = vsCfg.dimension;
+      } else if (vsCfg.embeddingModelDims && !vsCfg.dimension) {
+        vsCfg.dimension = vsCfg.embeddingModelDims;
+      }
+      vs.config = vsCfg;
+      config.vectorStore = vs;
+    }
 
     if (this.ossConfig?.historyDbPath) {
-      const dbPath = this.resolvePath
-        ? this.resolvePath(this.ossConfig.historyDbPath)
-        : this.ossConfig.historyDbPath;
+      const raw = this.ossConfig.historyDbPath;
+      const isAbsolute = raw.startsWith("/") || /^[A-Za-z]:[/\\]/.test(raw);
+      const dbPath =
+        isAbsolute || !this.resolvePath ? raw : this.resolvePath(raw);
       config.historyDbPath = dbPath;
     }
 

openclaw/skills/memory-dream/SKILL.md

@@ -14,6 +14,49 @@ metadata:
 
 You are performing a memory consolidation pass. Your goal is to review all stored memories for this user and improve their overall quality. Think of this as compressing raw observations into clean, durable knowledge.
 
+## Available Tools
+
+### memory_search
+Semantic search across stored memories.
+- `query` (required): search query
+- `limit`: max results
+- `userId`, `agentId`: scope overrides
+- `scope`: `"all"` (default), `"session"`, or `"long-term"`
+- `categories`: filter by category array
+
+### memory_add
+Store new facts in long-term memory.
+- `facts` (required): array of facts — ALL must share the same category
+- `category`: `"identity"`, `"preference"`, `"decision"`, `"rule"`, `"project"`, `"configuration"`, `"technical"`, `"relationship"`
+- `importance`: 0.0–1.0
+
+### memory_get
+Retrieve a single memory by ID.
+- `memoryId` (required): the memory ID
+
+### memory_list
+List all stored memories for a user or agent.
+- `userId`, `agentId`: scope overrides
+- `scope`: `"all"` (default), `"session"`, or `"long-term"`
+
+### memory_update
+Update an existing memory's text in place. Atomic and preserves edit history.
+- `memoryId` (required): the memory ID to update
+- `text` (required): the new text (replaces old)
+
+### memory_delete
+Delete memories by ID, query, or bulk.
+- `memoryId`: specific memory ID to delete
+- `all`: delete ALL memories (requires `confirm: true`)
+- `userId`, `agentId`: scope overrides
+
+### memory_event_list
+List recent background processing events (platform mode only).
+
+### memory_event_status
+Get status of a specific background event.
+- `event_id` (required): the event ID to check
+
 Follow these four phases in order. Do not skip phases.
 
 ## Phase 1: Orient

openclaw/skills/memory-triage/SKILL.md

@@ -18,6 +18,56 @@ Your primary role is to extract relevant pieces of information from the conversa
 
 **The core question**: "Would a new agent — with no prior context — benefit from knowing this?" If no → do nothing. Most turns produce zero memory operations. That is correct and expected.
 
+## Available Tools
+
+### memory_search
+Semantic search across stored memories.
+- `query` (required): search query
+- `limit`: max results (default: configured topK)
+- `userId`, `agentId`: scope overrides
+- `scope`: `"all"` (default), `"session"`, or `"long-term"`
+- `categories`: filter by category array
+- `filters`: advanced filter object
+
+### memory_add
+Store new facts in long-term memory.
+- `facts` (required): array of facts to store — ALL must share the same category
+- `text`: alternative single-fact string
+- `category`: `"identity"`, `"preference"`, `"decision"`, `"rule"`, `"project"`, `"configuration"`, `"technical"`, `"relationship"`
+- `importance`: 0.0–1.0 (omit for category default)
+- `userId`, `agentId`: scope overrides
+- `metadata`: additional key-value metadata
+- `longTerm`: true (default) for persistent, false for session-scoped
+
+### memory_get
+Retrieve a single memory by ID.
+- `memoryId` (required): the memory ID
+
+### memory_list
+List all stored memories for a user or agent.
+- `userId`, `agentId`: scope overrides
+- `scope`: `"all"` (default), `"session"`, or `"long-term"`
+
+### memory_update
+Update an existing memory's text in place. Atomic and preserves edit history.
+- `memoryId` (required): the memory ID to update
+- `text` (required): the new text (replaces old)
+
+### memory_delete
+Delete memories by ID, query, or bulk.
+- `memoryId`: specific memory ID to delete
+- `query`: search query to find and delete matching memories
+- `all`: delete ALL memories (requires `confirm: true`)
+- `confirm`: safety gate for bulk operations
+- `userId`, `agentId`: scope overrides
+
+### memory_event_list
+List recent background processing events (platform mode only).
+
+### memory_event_status
+Get status of a specific background event.
+- `event_id` (required): the event ID to check
+
 ## Decision Gate
 
 Every candidate fact must pass ALL four gates:
@@ -28,7 +78,7 @@ Every candidate fact must pass ALL four gates:
 
 **Gate 2 — NOVELTY**: Check your recalled memories below — is this already known?
   - Already known and unchanged → SKIP
-  - Known but materially changed → UPDATE (find old → forget → store new)
+  - Known but materially changed → UPDATE (find old → update in place)
   - Genuinely new → proceed
   - **Material difference test**: Only UPDATE if new information adds real context, details, or changes meaning. Cosmetic differences (synonyms, rephrasing, punctuation) are NOT updates. "Loves daily walks" vs "enjoys daily walks" = no material change = SKIP.
 
@@ -196,8 +246,9 @@ Categories: `identity`, `configuration`, `rule`, `preference`, `decision`, `tech
 
 When a recalled memory needs updating (fact changed, status changed, new detail added):
 1. `memory_search` to find the existing memory
-2. `memory_delete` on the old memory's ID
-3. `memory_add` with the corrected/expanded fact
+2. `memory_update` on the memory's ID with the corrected/expanded text
+
+`memory_update` is preferred over delete+add because it is **atomic and preserves edit history**.
 
 **Choose the MORE COMPLETE version.** When both old and new have unique context, COMBINE them into a unified memory using the user's stated words.
 
@@ -206,10 +257,10 @@ When a recalled memory needs updating (fact changed, status changed, new detail
   - "User likes Python" → "User enjoys Python" = NOT material = SKIP
   - When both have unique context, combine: Old "Trip to Paris in September with Jack" + New "User can't wait to visit Eiffel Tower" → "Trip to Paris in September 2025 with friend Jack, user says they can't wait to visit the Eiffel Tower and try authentic French pastries"
 
-**Consolidation**: When a rich new fact encompasses multiple existing memories, update one to the comprehensive version and forget the others.
+**Consolidation**: When a rich new fact encompasses multiple existing memories, `memory_update` the best one to the comprehensive version and `memory_delete` the rest.
   - Old: "User has a dog" + "Dog's name is Poppy" + "User walks dog daily"
   - New: "User has a dog named Poppy and says taking him for walks is the best part of their day"
-  - Action: forget all three old memories, store one consolidated memory
+  - Action: `memory_update` the best version with consolidated text, `memory_delete` the redundant ones
 
 **Temporary vs permanent changes**: A temporary constraint (e.g., injury pausing a hobby) does NOT contradict the underlying preference. Store the constraint as a new memory; don't delete the preference.
   - Old: "User enjoys hiking on weekends"
@@ -267,8 +318,7 @@ User: "Never use Docker for local dev, it ate 40GB of disk last time and my Mac
 Recalled: ["As of 2026-03-15, user is planning trip to Paris in September with friend Jack"]
 User: "Can't wait for the Paris trip, definitely want to hit the Eiffel Tower and try authentic French pastries"
 → memory_search("Paris trip planning")
-→ memory_delete(memoryId: "mem-id-of-old")
-→ memory_add(facts: ["As of 2026-03-30, user is planning trip to Paris in September 2025 with friend Jack, says they can't wait to visit the Eiffel Tower and try authentic French pastries"], category: "project")
+→ memory_update(memoryId: "mem-id-of-old", text: "As of 2026-03-30, user is planning trip to Paris in September 2025 with friend Jack, says they can't wait to visit the Eiffel Tower and try authentic French pastries")
 ```
 
 ### Example 6: Outcome over intent
@@ -327,8 +377,8 @@ Agent: "Hello! How can I help?"
 Recalled: ["User has a dog", "Dog's name is Poppy", "User walks dog daily"]
 User: "Poppy learned fetch! Our walks are even better now, honestly it's the best part of my day"
 → memory_search("dog Poppy walks") → find all three old memory IDs
-→ memory_delete(memoryId: "id-1"), memory_delete(memoryId: "id-2"), memory_delete(memoryId: "id-3")
-→ memory_add(facts: ["User has a dog named Poppy and says taking him for walks is the best part of their day. Poppy recently learned fetch, making walks more enjoyable."], category: "preference")
+→ memory_update(memoryId: "id-1", text: "User has a dog named Poppy and says taking him for walks is the best part of their day. Poppy recently learned fetch, making walks more enjoyable.")
+→ memory_delete(memoryId: "id-2"), memory_delete(memoryId: "id-3")
 ```
 
 ### Example 12: NOOP — generic greeting, nothing to store

openclaw/sqlite-resilience.test.ts

@@ -443,7 +443,7 @@ describe("OSSProvider — _buildConfig branch coverage", () => {
       config: expect.objectContaining({ model: "gpt-4", apiKey: "sk-l" }),
     });
     expect(capturedConfig!.vectorStore).toEqual({ provider: "qdrant", config: { host: "localhost", port: 6333 } });
-    expect(capturedConfig!.historyDbPath).toBe("/resolved/tmp/history.db");
+    expect(capturedConfig!.historyDbPath).toBe("/tmp/history.db");
     expect(capturedConfig!.disableHistory).toBe(true);
   });
 
@@ -732,4 +732,58 @@ describe("OSSProvider — customInstructions passthrough", () => {
     expect(capturedConfig).toBeDefined();
     expect(capturedConfig!.customInstructions).toBe("Extract only user preferences.");
   });
+
+  it("preserves absolute Unix historyDbPath without resolvePath mangling", async () => {
+    const { createProvider } = await import("./index.ts");
+    const cfg = mem0ConfigSchema.parse({
+      mode: "open-source",
+      oss: {
+        historyDbPath: "/home/user/.myapp/history.db",
+        disableHistory: true,
+      },
+    });
+    const api = { resolvePath: (p: string) => `/stateDir/${p}` } as any;
+    const provider = createProvider(cfg, api);
+
+    await provider.search("test", { user_id: "u1" });
+
+    expect(capturedConfig).toBeDefined();
+    expect(capturedConfig!.historyDbPath).toBe("/home/user/.myapp/history.db");
+  });
+
+  it("preserves absolute Windows historyDbPath without resolvePath mangling", async () => {
+    const { createProvider } = await import("./index.ts");
+    const cfg = mem0ConfigSchema.parse({
+      mode: "open-source",
+      oss: {
+        historyDbPath: "C:\\Users\\me\\history.db",
+        disableHistory: true,
+      },
+    });
+    const api = { resolvePath: (p: string) => `/stateDir/${p}` } as any;
+    const provider = createProvider(cfg, api);
+
+    await provider.search("test", { user_id: "u1" });
+
+    expect(capturedConfig).toBeDefined();
+    expect(capturedConfig!.historyDbPath).toBe("C:\\Users\\me\\history.db");
+  });
+
+  it("still resolves relative historyDbPath via resolvePath", async () => {
+    const { createProvider } = await import("./index.ts");
+    const cfg = mem0ConfigSchema.parse({
+      mode: "open-source",
+      oss: {
+        historyDbPath: "data/history.db",
+        disableHistory: true,
+      },
+    });
+    const api = { resolvePath: (p: string) => `/resolved/${p}` } as any;
+    const provider = createProvider(cfg, api);
+
+    await provider.search("test", { user_id: "u1" });
+
+    expect(capturedConfig).toBeDefined();
+    expect(capturedConfig!.historyDbPath).toBe("/resolved/data/history.db");
+  });
 });

openclaw/tests/cli-commands.test.ts

@@ -16,6 +16,7 @@ vi.mock("../cli/config-file.ts", () => ({
   readPluginAuth: vi.fn().mockReturnValue({}),
   writePluginAuth: vi.fn(),
   writePluginConfigField: vi.fn(),
+  enableSkillsConfig: vi.fn(),
   getBaseUrl: vi.fn().mockReturnValue("https://api.mem0.ai"),
   OPENCLAW_CONFIG_FILE: "/mock/.openclaw/openclaw.json",
 }));
@@ -42,6 +43,7 @@ import {
   readPluginAuth,
   writePluginAuth,
   writePluginConfigField,
+  enableSkillsConfig,
   getBaseUrl,
 } from "../cli/config-file.ts";
 import { loadDreamPrompt } from "../skill-loader.ts";
@@ -178,7 +180,7 @@ function createMockCfg() {
     topK: 5,
     autoCapture: true,
     autoRecall: true,
-    searchThreshold: 0.5,
+    searchThreshold: 0.1,
     customInstructions: "",
     customCategories: {},
     skills: {},

openclaw/tests/config.test.ts

@@ -44,14 +44,14 @@ describe("mem0ConfigSchema.parse() — defaults", () => {
     expect(cfg.userId.length).toBeGreaterThan(0);
   });
 
-  it("autoCapture defaults to false", () => {
+  it("autoCapture defaults to true", () => {
     const cfg = mem0ConfigSchema.parse({ apiKey: "test-key" });
-    expect(cfg.autoCapture).toBe(false);
+    expect(cfg.autoCapture).toBe(true);
   });
 
-  it("autoRecall defaults to false", () => {
+  it("autoRecall defaults to true", () => {
     const cfg = mem0ConfigSchema.parse({ apiKey: "test-key" });
-    expect(cfg.autoRecall).toBe(false);
+    expect(cfg.autoRecall).toBe(true);
   });
 
   it("topK defaults to 5", () => {
@@ -59,9 +59,9 @@ describe("mem0ConfigSchema.parse() — defaults", () => {
     expect(cfg.topK).toBe(5);
   });
 
-  it("searchThreshold defaults to 0.5", () => {
+  it("searchThreshold defaults to 0.1", () => {
     const cfg = mem0ConfigSchema.parse({ apiKey: "test-key" });
-    expect(cfg.searchThreshold).toBe(0.5);
+    expect(cfg.searchThreshold).toBe(0.1);
   });
 
   it("customInstructions defaults to DEFAULT_CUSTOM_INSTRUCTIONS", () => {

openclaw/tests/oss-wizard.test.ts

@@ -7,6 +7,7 @@ import {
   buildOssLlmConfig,
   buildOssEmbedderConfig,
   buildOssVectorConfig,
+  collectionNameForDims,
   validateOssFlags,
   checkQdrantConnectivity,
   checkOllamaConnectivity,
@@ -90,9 +91,9 @@ describe("buildOssEmbedderConfig", () => {
     expect(result.dims).toBe(768);
   });
 
-  it("returns unknown dims for custom model", () => {
+  it("falls back to provider default dims for custom model", () => {
     const result = buildOssEmbedderConfig("ollama", { model: "custom-embed" });
-    expect(result.dims).toBeUndefined();
+    expect(result.dims).toBe(768);
   });
 });
 
@@ -147,6 +148,49 @@ describe("buildOssVectorConfig", () => {
   });
 });
 
+describe("collectionNameForDims", () => {
+  it("generates dimension-based collection name", () => {
+    expect(collectionNameForDims(1536)).toBe("mem0_1536d");
+    expect(collectionNameForDims(768)).toBe("mem0_768d");
+    expect(collectionNameForDims(384)).toBe("mem0_384d");
+  });
+});
+
+describe("buildOssVectorConfig dimension safety", () => {
+  it("sets both dimension and embeddingModelDims when dims provided", () => {
+    const result = buildOssVectorConfig("qdrant", { dims: 768 });
+    expect(result.config.dimension).toBe(768);
+    expect(result.config.embeddingModelDims).toBe(768);
+  });
+
+  it("sets collectionName based on dims", () => {
+    const result = buildOssVectorConfig("qdrant", { dims: 768 });
+    expect(result.config.collectionName).toBe("mem0_768d");
+  });
+
+  it("uses different collection names for different dims", () => {
+    const r1 = buildOssVectorConfig("qdrant", { dims: 1536 });
+    const r2 = buildOssVectorConfig("qdrant", { dims: 768 });
+    expect(r1.config.collectionName).not.toBe(r2.config.collectionName);
+  });
+
+  it("omits dimension fields when dims not provided", () => {
+    const result = buildOssVectorConfig("qdrant", {});
+    expect(result.config.dimension).toBeUndefined();
+    expect(result.config.embeddingModelDims).toBeUndefined();
+    expect(result.config.collectionName).toBeUndefined();
+  });
+
+  it("works with pgvector too", () => {
+    const result = buildOssVectorConfig("pgvector", {
+      host: "localhost", port: "5432", user: "me", password: "pw", dbname: "test", dims: 768,
+    });
+    expect(result.config.dimension).toBe(768);
+    expect(result.config.embeddingModelDims).toBe(768);
+    expect(result.config.collectionName).toBe("mem0_768d");
+  });
+});
+
 describe("checkQdrantConnectivity", () => {
   it("returns error for unreachable host", async () => {
     const result = await checkQdrantConnectivity("http://localhost:19999");

openclaw/tests/tools.test.ts

@@ -34,7 +34,7 @@ function createMockToolDeps(overrides = {}): ToolDeps {
       topK: 5,
       autoCapture: true,
       autoRecall: true,
-      searchThreshold: 0.5,
+      searchThreshold: 0.1,
       customInstructions: "test",
       customCategories: {},
     } as any,

openclaw/tsup.config.ts

@@ -8,7 +8,8 @@ export default defineConfig({
   dts: true,
   sourcemap: true,
   clean: true,
-  external: [/^node:/, /^openclaw\//, "fs", "os", "path", "url", "readline", "module"],
+  external: [/^node:/, /^openclaw\//, "fs", "os", "path", "url", "readline", "module",
+             "mem0ai", /^mem0ai\//, "better-sqlite3", "@sinclair/typebox"],
   define: {
     __OPENCLAW_PLUGIN_VERSION__: JSON.stringify(pkg.version),
   },

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mem0ai"
-version = "2.0.1"
+version = "2.0.2"
 description = "Long-term memory for AI Agents"
 authors = [
     { name = "Mem0", email = "support@mem0.ai" }
@@ -153,3 +153,6 @@ known-first-party = ["mem0", "mem0_cli"]
 [tool.isort]
 profile = "black"
 known_first_party = ["mem0", "mem0_cli"]
+# isort scope kept aligned with [tool.ruff.lint.isort] above.
+# black-equivalent profile here matches the formatter behaviour ruff applies.
+# Plugin-version bumps need a touch here to fire required CI checks (path-filter trap).

skills/README.md

@@ -0,0 +1,49 @@
+# Mem0 Skills for AI Coding Assistants
+
+Mem0 ships structured skill definitions for Claude Code, Codex, Cursor, OpenCode, OpenClaw, and any assistant that supports the [skills standard](https://github.com/anthropic-experimental/skills). Skills teach the assistant how to work with Mem0 — either by loading SDK knowledge into context, or by executing an end-to-end workflow on demand.
+
+## Two Categories
+
+### Reference skills — always on
+
+Installed once, loaded into context so the assistant writes correct Mem0 code. Use these for day-to-day development.
+
+| Skill | Surface | Install |
+|-------|---------|---------|
+| [`mem0`](./mem0/) | Python + TypeScript SDKs (Platform + OSS), framework integrations | `npx skills add https://github.com/mem0ai/mem0 --skill mem0` |
+| [`mem0-cli`](./mem0-cli/) | Terminal workflows (`mem0` CLI, both Node and Python) | `npx skills add https://github.com/mem0ai/mem0 --skill mem0-cli` |
+| [`mem0-vercel-ai-sdk`](./mem0-vercel-ai-sdk/) | `@mem0/vercel-ai-provider` and `createMem0` | `npx skills add https://github.com/mem0ai/mem0 --skill mem0-vercel-ai-sdk` |
+
+### Pipeline skills — run on demand
+
+Invoked as a slash command to execute a specific end-to-end workflow. These do real work: they create branches, write tests, run code.
+
+| Skill | Trigger | Install |
+|-------|---------|---------|
+| [`mem0-integrate`](./mem0-integrate/) | `/mem0-integrate` — wire Mem0 into an existing repo via TDD | `npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate` |
+| [`mem0-test-integration`](./mem0-test-integration/) | `/mem0-test-integration` — verify what `/mem0-integrate` produced | `npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration` |
+
+The two pipeline skills are designed to run in sequence on the same workspace:
+
+```
+/mem0-integrate          →  mem0-integrate/<slug> branch + .mem0-integration/ artifacts
+/mem0-test-integration   →  scorecard (compile + runtime verification, real API smoke test)
+```
+
+## Choosing a Skill
+
+- **Writing Mem0 code in a new or existing project?** → `mem0`
+- **Using the terminal CLI?** → `mem0-cli`
+- **Building with `@ai-sdk/*`?** → `mem0-vercel-ai-sdk`
+- **Want the assistant to wire Mem0 into an existing repo for you?** → `mem0-integrate`, then `mem0-test-integration`
+
+## Links
+
+- [Vibecoding with Mem0](https://docs.mem0.ai/vibecoding) — canonical landing page
+- [Claude Code integration](https://docs.mem0.ai/integrations/claude-code)
+- [Mem0 Platform Dashboard](https://app.mem0.ai)
+- [Mem0 Documentation](https://docs.mem0.ai)
+
+## License
+
+Apache-2.0

skills/mem0-integrate/LICENSE

@@ -0,0 +1,189 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but not
+      limited to compiled object code, generated documentation, and
+      conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2024 Mem0.ai
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.