feat(tools): 7-tool parity and description refresh

.github/workflows/ci-python.yml

@@ -9,97 +9,231 @@ on:
       - "packages/pipecat-sdk-python/**"
       - ".github/workflows/ci-python.yml"
 
+permissions:
+  contents: read
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
+env:
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+
 jobs:
   agent-framework-python:
-    name: agent-framework-python
+    name: agent-framework-python (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.13"]
     defaults:
       run:
         working-directory: packages/agent-framework-python
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: packages/agent-framework-python/pyproject.toml
+
+      - name: Install build and test tools
+        run: python -m pip install build pytest pytest-asyncio
+
+      - name: Build wheel
+        run: python -m build --wheel --outdir "$RUNNER_TEMP/wheels"
+
+      - name: Install wheel and runtime dependencies
+        run: python -m pip install "$RUNNER_TEMP"/wheels/*.whl
 
-      - name: Install package and test dependencies
-        run: |
-          pip install -e .
-          pip install pytest pytest-asyncio
+      - name: Check dependency compatibility
+        run: python -m pip check
+
+      - name: Verify installed wheel
+        run: >-
+          python -c "from pathlib import Path; import supermemory_agent_framework;
+          assert 'site-packages' in Path(supermemory_agent_framework.__file__).parts"
 
       - name: Run tests
-        run: pytest
+        run: python -m pytest
 
   openai-sdk-python:
-    name: openai-sdk-python
+    name: openai-sdk-python (${{ matrix.dependency-lane }}, Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: "3.9"
+            dependency-lane: minimum-supermemory
+            supermemory-version: "3.50.0"
+            expected-supermemory-version: "3.50.0"
+          - python-version: "3.12"
+            dependency-lane: locked
+            supermemory-version: ""
+            expected-supermemory-version: "3.59.0"
     defaults:
       run:
         working-directory: packages/openai-sdk-python
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
-          python-version: "3.12"
+          version: "0.12.5"
+          enable-cache: true
+          working-directory: packages/openai-sdk-python
+          cache-dependency-glob: uv.lock
 
-      - name: Install package and test dependencies
-        run: |
-          pip install -e .
-          pip install pytest pytest-asyncio python-dotenv
+      - name: Install locked dependencies
+        run: uv sync --locked --python "${{ matrix.python-version }}"
 
-      - name: Run tests
-        run: pytest
+      - name: Build wheel
+        run: uv build --wheel --out-dir "$RUNNER_TEMP/wheels"
+
+      - name: Install built wheel
+        run: >-
+          uv pip install --python .venv/bin/python --reinstall --no-deps
+          "$RUNNER_TEMP"/wheels/*.whl
+
+      - name: Install minimum Supermemory SDK
+        if: matrix.supermemory-version != ''
+        run: >-
+          uv pip install --python .venv/bin/python
+          "supermemory==${{ matrix.supermemory-version }}"
+
+      - name: Check dependency compatibility
+        run: uv pip check --python .venv/bin/python
+
+      - name: Verify installed wheel and SDK version
+        run: >-
+          .venv/bin/python -c "from importlib.metadata import version;
+          from pathlib import Path; import supermemory_openai;
+          assert version('supermemory') == '${{ matrix.expected-supermemory-version }}';
+          assert 'site-packages' in Path(supermemory_openai.__file__).parts"
+
+      - name: Run tests without changing the verified environment
+        run: .venv/bin/python -m pytest
 
   cartesia-sdk-python:
-    name: cartesia-sdk-python
+    name: cartesia-sdk-python (${{ matrix.dependency-lane }}, Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
-    timeout-minutes: 5
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: "3.10"
+            dependency-lane: minimum-supermemory
+            supermemory-spec: "supermemory==3.16.0"
+            supermemory-version: "3.16.0"
+          - python-version: "3.12"
+            dependency-lane: current-supermemory
+            supermemory-spec: "supermemory==3.59.0"
+            supermemory-version: "3.59.0"
     defaults:
       run:
         working-directory: packages/cartesia-sdk-python
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: "3.12"
-
-      # Suite stubs cartesia-line / loguru / pydantic at import time, so it
-      # runs against sources with nothing installed.
-      - name: Run tests
-        run: PYTHONPATH=src python -m unittest discover -s tests -v
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: packages/cartesia-sdk-python/pyproject.toml
+
+      - name: Install build tools and lightweight test dependencies
+        run: >-
+          python -m pip install build pytest "loguru>=0.7.3" "pydantic>=2.10.0"
+          "${{ matrix.supermemory-spec }}"
+
+      - name: Build wheel
+        run: python -m build --wheel --outdir "$RUNNER_TEMP/wheels"
+
+      - name: Install wheel without the voice framework
+        run: python -m pip install --no-deps "$RUNNER_TEMP"/wheels/*.whl
+
+      - name: Run tests against the installed wheel and real lightweight dependencies
+        run: >-
+          python -c "from importlib.metadata import version;
+          from pathlib import Path; import loguru, pydantic, supermemory, pytest;
+          assert version('supermemory') == '${{ matrix.supermemory-version }}';
+          result = pytest.main(['-W', 'ignore::pytest.PytestAssertRewriteWarning', 'tests']);
+          import supermemory_cartesia;
+          assert 'site-packages' in Path(supermemory_cartesia.__file__).parts;
+          raise SystemExit(result)"
 
   pipecat-sdk-python:
-    name: pipecat-sdk-python
+    name: pipecat-sdk-python (${{ matrix.dependency-lane }}, Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
-    timeout-minutes: 5
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: "3.10"
+            dependency-lane: minimum-supermemory
+            supermemory-spec: "supermemory==3.16.0"
+            supermemory-version: "3.16.0"
+          - python-version: "3.12"
+            dependency-lane: current-supermemory
+            supermemory-spec: "supermemory==3.59.0"
+            supermemory-version: "3.59.0"
     defaults:
       run:
         working-directory: packages/pipecat-sdk-python
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
-          python-version: "3.12"
-
-      # Suite stubs pipecat-ai / loguru / pydantic at import time, so it
-      # runs against sources with nothing installed.
-      - name: Run tests
-        run: PYTHONPATH=src python -m unittest discover -s tests -v
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: packages/pipecat-sdk-python/pyproject.toml
+
+      - name: Install build tools and lightweight test dependencies
+        run: >-
+          python -m pip install build pytest "loguru>=0.7.3" "pydantic>=2.10.0"
+          "${{ matrix.supermemory-spec }}"
+
+      - name: Build wheel
+        run: python -m build --wheel --outdir "$RUNNER_TEMP/wheels"
+
+      - name: Install wheel without the voice framework
+        run: python -m pip install --no-deps "$RUNNER_TEMP"/wheels/*.whl
+
+      - name: Run tests against the installed wheel and real lightweight dependencies
+        run: >-
+          python -c "from importlib.metadata import version;
+          from pathlib import Path; import loguru, pydantic, supermemory, pytest;
+          assert version('supermemory') == '${{ matrix.supermemory-version }}';
+          result = pytest.main(['-W', 'ignore::pytest.PytestAssertRewriteWarning', 'tests']);
+          import supermemory_pipecat;
+          assert 'site-packages' in Path(supermemory_pipecat.__file__).parts;
+          raise SystemExit(result)"

.github/workflows/ci.yml

@@ -29,5 +29,22 @@ jobs:
       - name: Run TypeScript type checking
         run: bunx turbo run check-types --filter='@supermemory/ai-sdk' --filter='@supermemory/memory-graph'
 
+      - name: Detect Tools package changes
+        id: tools-changes
+        run: |
+          if git diff --quiet "${{ github.event.pull_request.base.sha }}" HEAD -- packages/tools; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Run Tools unit tests
+        if: steps.tools-changes.outputs.changed == 'true'
+        run: bun run --cwd packages/tools test:unit
+
+      - name: Build Tools package
+        if: steps.tools-changes.outputs.changed == 'true'
+        run: bun run --cwd packages/tools build
+
       - name: Run Biome CI (format & lint on changed files)
         run: bunx biome ci --changed --since=origin/main --no-errors-on-unmatched

apps/docs/integrations/voltagent.mdx

@@ -18,7 +18,7 @@ Supermemory integrates with [VoltAgent](https://github.com/VoltAgent/voltagent),
 ## Installation
 
 ```bash
-npm install @supermemory/tools @voltagent/core
+npm install @supermemory/tools @voltagent/core ai@^6 @ai-sdk/openai@^3
 ```
 
 Set up your API key as an environment variable:
@@ -52,9 +52,7 @@ const configWithMemory = withSupermemory({
 const agent = new Agent(configWithMemory)
 
 // Memories are automatically injected and saved
-const result = await agent.generateText({
-  messages: [{ role: "user", content: "What's my name?" }],
-})
+const result = await agent.generateText("What's my name?")
 ```
 
 <Note>
@@ -131,14 +129,13 @@ const configWithMemory = withSupermemory({
 
   // Search tuning
   searchMode: "hybrid",            // "memories" | "documents" | "hybrid"
-  threshold: 0.1,                  // 0.0-1.0 (higher = more accurate)
-  limit: 10,                       // Max results to return
+  threshold: 0.6,                  // 0.0-1.0 (higher = more accurate)
+  limit: 10,                       // Integer from 1 to 100
   rerank: true,                    // Rerank for best relevance
   rewriteQuery: false,             // AI-rewrite query (+400ms latency)
 
   // Context
-  entityContext: "This is John, a software engineer",  // Guides memory extraction (max 1500 chars)
-  metadata: { source: "voltagent" },                   // Attached to saved conversations
+  metadata: { source: "voltagent" },  // Attached to saved conversations
 
   // API
   apiKey: "sk-...",                // Falls back to SUPERMEMORY_API_KEY env var
@@ -154,14 +151,16 @@ const configWithMemory = withSupermemory({
 | `addMemory`       | string   | `"always"`   | Whether to save conversations after each response        |
 | `customId`        | string   | **required** | Custom ID to group messages into a conversation          |
 | `searchMode`      | string   | —            | `"memories"`, `"documents"`, or `"hybrid"`               |
-| `threshold`       | number   | `0.1`        | Similarity threshold (0 = more results, 1 = more accurate) |
-| `limit`           | number   | `10`         | Maximum number of memory results                         |
+| `threshold`       | number   | —            | Similarity threshold (0 = more results, 1 = more accurate) |
+| `limit`           | number   | —            | Maximum number of memory results (integer from 1 to 100) |
 | `rerank`          | boolean  | `false`      | Rerank results for relevance                             |
 | `rewriteQuery`    | boolean  | `false`      | AI-rewrite query for better results (+400ms)             |
-| `entityContext`   | string   | —            | Context for memory extraction (max 1500 chars)           |
+| `entityContext`   | string   | —            | Deprecated and ignored. [Configure it on the container tag instead](/concepts/customization#entity-context). |
 | `metadata`        | object   | —            | Custom metadata attached to saved conversations          |
 | `promptTemplate`  | function | —            | Custom function to format memory data into prompt        |
 
+When `threshold` or `limit` is omitted, the selected Supermemory backend route applies its own default. Set them explicitly when you need consistent search tuning across modes.
+
 ## Search Modes
 
 The `searchMode` option controls what type of results are searched:
@@ -171,4 +170,3 @@ The `searchMode` option controls what type of results are searched:
 | `"memories"`  | Search only memory entries (atomic facts about the user) |
 | `"documents"` | Search only document chunks                            |
 | `"hybrid"`    | Search both memories AND document chunks (recommended) |
-