docs changes

[Dhravya]

No description provided.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	supermemory-app	f9075bc	Commit Preview URL	Jan 18 2026, 04:55 AM

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
🔵 In progress View logs	supermemory-mcp	a62de97	Jan 17 2026, 02:42 AM

[Dhravya]

• docs changes #678 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add the label Main to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: Documentation & API Method Rename

Summary

This PR updates documentation across the repository and renames the API method from client.memories.add() to client.add() in published packages. The changes are primarily documentation reorganization with important breaking API changes.

---

✅ Positives

• Comprehensive documentation update: Excellent reorganization of docs with new sections for integrations, filtering, and search
• Consistent API rename: The client.memories.add() → client.add() change is applied consistently across all TypeScript and Python packages
• Import organization: Python imports now follow proper alphabetical ordering (stdlib → third-party → local)

---

⚠️ Critical Issues

1. Breaking API Change Without Tests 🔴

The API method rename (client.memories.add → client.add) is a breaking change affecting published packages:

• packages/tools/ (has Vitest tests)
• packages/openai-sdk-python/ (has pytest tests)
• packages/pipecat-sdk-python/ (no tests found)

Action Required:

• Run existing tests to verify they still pass with the new API
• If tests reference the old client.memories.add method, they need updating
• Consider deprecation warnings instead of immediate removal for a smoother migration path

2. Inconsistent Import Formatting in Python ⚠️

packages/openai-sdk-python/src/supermemory_openai/middleware.py:

• Lines now use alphabetical ordering which is good
• However, blank line between import groups seems inconsistent (stdlib → blank → third-party → blank → local)
• Ensure this matches your Python project's style guide or use a formatter like ruff or black

Example from the diff:

import asyncio
import os
from dataclasses import dataclass
from typing import Any, Literal, Optional, Union, cast

import supermemory  # Third-party
from openai import AsyncOpenAI, OpenAI  # Third-party

The blank line placement should be consistent (one blank line between each group).

3. String Formatting Inconsistency ⚠️

packages/pipecat-sdk-python/src/supermemory_pipecat/service.py:75-77:

system_prompt: str = Field(
    default="Based on previous conversations, I recall:\n\n"
)

While this improves readability, ensure it follows your project's line length limits (typically 88 or 100 chars for Python). The original single line was within limits.

---

📋 Recommendations

1. Version Bump & Changelog

   • This is a breaking change for published packages
   • Bump major version (or minor if pre-1.0)
   • Add migration guide in CHANGELOG/release notes

2. Test Coverage

   • Run test suites: cd packages/tools && bun test
   • Run Python tests: cd packages/openai-sdk-python && pytest
   • Verify all tests pass with renamed method

3. Backward Compatibility (Optional)

   • Consider adding a deprecated client.memories.add() that calls client.add() with a deprecation warning
   • This gives users time to migrate gracefully

4. Documentation

   • The docs updates look great and comprehensive
   • Consider adding a migration guide section for users upgrading from older versions

---

Code Quality Notes

• ✅ TypeScript changes follow consistent patterns
• ✅ No security issues detected (no new credential handling, no injection risks)
• ✅ Python type hints properly maintained
• ✅ Error handling patterns preserved

---

Verdict

Request Changes - Please verify tests pass with the new API and consider versioning/migration strategy for this breaking change.

[claude]

PR Review: Documentation Changes + API Standardization

Summary

This PR contains extensive documentation updates and standardizes the Supermemory client API usage from client.memories.add() to client.add() across multiple packages.

---

✅ Code Quality & Type Safety

Good:

• API method changes are consistent across all affected files
• TypeScript usage remains correct throughout
• No type safety issues introduced

Python Formatting:

• ✅ Import ordering improvements in openai-sdk-python and pipecat-sdk-python follow Python conventions (stdlib → third-party → local)
• ✅ Line length improvements in pipecat-sdk-python/service.py for better readability
• ✅ Trailing comma additions follow Python formatting best practices

---

🔍 API Changes Analysis

Changed Pattern:

// Before
await client.memories.add({ content, containerTags })

// After  
await client.add({ content, containerTags })

Affected Packages:

• ✅ packages/ai-sdk/src/tools.ts (published package)
• ✅ packages/tools/src/ - ai-sdk.ts, claude-memory.ts, openai/* (published package)
• ✅ packages/openai-sdk-python (published package)
• ✅ packages/pipecat-sdk-python (published package)
• ✅ apps/mcp/src/client.ts

Breaking Change Assessment:

• ✅ NOT BREAKING - The client.add() method is already the predominant pattern used throughout the codebase
• ✅ This standardizes on the simpler, direct API rather than the namespaced version
• ✅ The external Supermemory SDK supports both approaches

---

🧪 Test Coverage

Status:

• ✅ No test updates required - existing tests in packages/tools, packages/ai-sdk, and Python packages don't mock these specific API calls
• ✅ Tests use the client interface generically, so no breaking changes to test code

---

📝 Documentation Changes

Scope: 70+ documentation files updated in apps/docs/

Spot Checks Recommended:

• Verify all code examples in docs were updated to use client.add() consistently
• Check that SDK installation guides reflect current package versions
• Ensure API reference docs match the new standardized pattern

---

🔒 Security

Review:

• ✅ No new security vulnerabilities introduced
• ✅ No credential exposure issues
• ✅ No injection vulnerabilities in updated code
• ✅ API changes don't affect authorization/authentication logic

---

⚡ Performance

• ✅ No performance impact - direct method call is equivalent to namespaced one
• ✅ No new N+1 queries or memory leaks introduced

---

📦 Published Package Considerations

Breaking API Surface:
This affects 4 published packages. However:

• ✅ The changes are internal implementation updates (how these packages call the Supermemory SDK)
• ✅ The public API of these packages remains unchanged
• ✅ Users of @supermemory/tools, @supermemory/ai-sdk, etc. won't be affected

Minor Issue - Type Declarations:

• ⚠️ packages/ai-sdk/package.json shows a type declaration hash change (index-CITmF79o.d.ts → index-h2cm3lSK.d.ts). This is auto-generated, but verify the build produces correct types.

---

✨ Recommendations

1. Verify Documentation: Do a quick search through the updated docs to ensure all examples consistently use client.add() rather than client.memories.add()

2. Build Check: Run bun run build and bun run check-types to verify the type declaration changes in packages/ai-sdk are correct

3. Consider Adding: A migration note in changelogs for the published packages mentioning the standardization (even though it's not breaking)

---

🎯 Verdict

LGTM ✅

This is a clean refactor that standardizes API usage across the codebase. The code quality is good, no security issues, and the changes are consistent. The extensive documentation updates should improve developer experience.

Minor note: Just verify the build succeeds and docs examples are consistent.

[claude]

PR Review: Documentation Updates and API Simplification

Summary

This PR updates documentation extensively and simplifies the SDK API by changing client.memories.add() to client.add() across all SDKs and integrations.

---

✅ Positive Changes

1. API Simplification

The API change from client.memories.add() to client.add() is cleaner and more intuitive. This is consistent across:

• TypeScript SDKs (tools, ai-sdk)
• Python SDKs (openai-sdk-python, pipecat-sdk-python)
• MCP server
• All documentation examples

2. Code Quality - Python

The Python code quality improvements are excellent:

• Proper import ordering (stdlib → third-party → local)
• Improved code formatting with better line breaks
• Consistent trailing commas in multi-line calls
• Better error message formatting

3. Documentation Structure

Significant improvements to documentation organization with new comprehensive guides on:

• Content types, filtering, graph memory
• User profiles, customization
• Integration guides for OpenAI, Pipecat, AI SDK, n8n, Zapier
• Clearer examples across all sections

---

⚠️ Concerns & Questions

1. Breaking API Change - Missing Version Bumps

This is a breaking change but published packages don't have version bumps:

packages/ai-sdk/package.json:

• Only changes: types field (build artifact hash)
• ❌ No version bump despite breaking API change to client.add()

Expected:

• Should bump major version (e.g., 1.x.x → 2.0.0) since this breaks existing code
• Or minor version if still in 0.x (e.g., 0.1.x → 0.2.0)

Other published packages likely need version bumps too:

• packages/tools
• packages/openai-sdk-python
• packages/pipecat-sdk-python

Please verify if version bumps are handled separately or need to be added to this PR.

---

2. Test Coverage - Missing Updates

The packages have existing tests, but no test updates are included in this PR:

Files that need test updates:

• packages/tools/test/vercel.test.ts
• packages/tools/test/claude-memory.test.ts
• packages/tools/src/tools.test.ts
• packages/ai-sdk/src/tools.test.ts
• packages/openai-sdk-python/tests/test_middleware.py
• packages/openai-sdk-python/tests/test_tools.py

Issue: Tests likely still call client.memories.add(), which will fail after this change.

Required Action: Update all tests to use client.add() instead of client.memories.add().

---

3. Migration Documentation

For a breaking change, consider adding:

• A migration guide explaining the API change
• Deprecation notice (if supporting both temporarily)
• Clear indication in changelog/release notes

The existing migration/from-mem0.mdx was updated but doesn't mention this API change.

---

🔍 Code Review Details

TypeScript Changes

All TypeScript changes follow the same pattern (✅ safe):

// Old
await client.memories.add({ ... })

// New  
await client.add({ ... })

Files affected:

• packages/ai-sdk/src/tools.ts:93
• packages/tools/src/ai-sdk.ts:90
• packages/tools/src/claude-memory.ts:332, 391
• packages/tools/src/openai/middleware.ts:366
• packages/tools/src/openai/tools.ts:144
• packages/tools/src/vercel/middleware.ts:140
• apps/mcp/src/client.ts:79

Python Changes

API Change (packages/openai-sdk-python/src/supermemory_openai/middleware.py):

# Lines 229-230
response = await client.add(**add_params)  # Changed from client.memories.add()
response = client.add(**add_params)        # Sync fallback

Code Quality Improvements (✅ excellent):

• Import reordering to follow PEP 8
• Better formatting with proper line breaks
• Consistent trailing commas
• Improved error message formatting

Pipecat SDK (packages/pipecat-sdk-python/src/supermemory_pipecat/service.py):

• Line 229: Changed to await self._supermemory_client.add(**add_params)
• Added proper line breaks for readability

---

📋 Action Items

Critical (Must Fix):

1. Bump package versions for all published packages with breaking changes
2. Update all test files to use new client.add() API
3. Run all tests to ensure nothing breaks:
   • bun test for TypeScript packages
   • pytest for Python packages

Recommended:

4. Add a migration section to docs explaining the API change
5. Consider adding a changelog entry for this breaking change

---

🎯 Verdict

Conditionally Approve - pending critical fixes:

The PR makes excellent improvements to documentation and simplifies the API. However, published packages need version bumps and tests must be updated before merging to avoid breaking production code.

Once tests pass and versions are bumped, this is ready to merge! 🚀

[claude]

PR Review: Documentation Changes

Summary

This PR primarily consists of documentation restructuring and reorganization in the apps/docs/ directory, with a critical API-breaking change across multiple published packages.

---

Critical Issue: Breaking API Change

Multiple packages have changed the API from client.memories.add() to client.add():

Affected Published Packages:

• packages/ai-sdk/src/tools.ts (line 93)
• packages/tools/src/ai-sdk.ts (line 90)
• packages/tools/src/claude-memory.ts (lines 332, 391, ...)
• packages/tools/src/openai/middleware.ts (line 366)
• packages/tools/src/openai/tools.ts (line 144)
• packages/tools/src/vercel/middleware.ts (line 140)
• packages/openai-sdk-python/src/supermemory_openai/middleware.py
• apps/mcp/src/client.ts (line 79)

Issues:

1. No version bump - packages/ai-sdk/package.json only changes the types hash, not the version number
2. Breaking change - This will break existing code for users calling client.memories.add()
3. No tests updated - Existing tests don't cover this API change
4. No deprecation path - Users upgrading will get runtime errors

Recommendations:

• Bump package versions following semver (major version bump for breaking change)
• Add deprecation warning for client.memories.add() or provide backward compatibility
• Update CHANGELOG with migration guide
• Verify all integration tests pass with the new API
• Consider keeping both APIs temporarily with deprecation warnings

---

Code Quality Issues

1. Python Import Reordering (packages/openai-sdk-python/)

Files: middleware.py, tools.py

Changes are purely cosmetic (alphabetizing imports). This follows Python conventions but adds noise to the diff.

Good: Follows PEP 8 import ordering
Note: Consider using automated formatters (black, ruff) in CI to prevent manual formatting PRs

2. Pipecat SDK Import Changes (packages/pipecat-sdk-python/)

File: service.py

• Moves pydantic import after pipecat imports
• No functional changes

---

Documentation Changes

The bulk of this PR is documentation reorganization:

• New comprehensive guides for memory operations, filtering, user profiles
• Integration guides for OpenAI, Pipecat, AI SDK, n8n, Zapier
• Removed outdated content (org-settings.mdx, consolidated filtering docs)
• Updated internal links and navigation structure

No issues found in documentation changes - this is a positive improvement.

---

Missing Test Coverage

For published packages (tools, ai-sdk, Python SDKs), the API change should be covered by tests. Action needed: Verify tests pass and cover the client.add() method.

---

Security and Performance

• No security vulnerabilities introduced
• No performance concerns
• No credential exposure

---

Verdict

Request Changes

This PR needs version bumps and a migration strategy before merging. The breaking API change affects multiple published packages used by external developers.

Required before merge:

1. Semver-compliant version bumps for all affected packages
2. Update package CHANGELOGs
3. Run full test suite to verify API changes
4. Consider backward compatibility layer or clear migration docs

[claude]

PR Review: Documentation Changes

Summary

This PR primarily contains documentation restructuring and updates, with minor API method changes across the codebase. The changes refactor the SDK API from client.memories.add() to client.add().

---

Code Changes Review

✅ Published Packages (TypeScript)

packages/tools/ (ai-sdk.ts, claude-memory.ts, openai/middleware.ts, openai/tools.ts, vercel/middleware.ts)

• Breaking change: client.memories.add() → client.add()
• This is a breaking API change for a published package that will require users to update their code
• Recommendation: This needs a major version bump (per semver) and should be documented in a CHANGELOG/migration guide

packages/ai-sdk/ (src/tools.ts, package.json)

• Same breaking API change: client.memories.add() → client.add()
• The package.json change shows updated types file hash (index-CITmF79o.d.ts → index-h2cm3lSK.d.ts) which is likely auto-generated
• Same concern: Breaking change needs version bump

✅ Published Packages (Python)

packages/openai-sdk-python/src/supermemory_openai/middleware.py

• Code quality improvements ✨
  • Import statements properly sorted (follows PEP 8 style)
  • Better code formatting with multi-line dictionaries
  • Consistent trailing commas added
  • Breaking API change: client.memories.add() → client.add()
• Good: Handles both sync/async clients with try/except TypeError pattern
• Recommendation: Needs major version bump due to breaking change

packages/openai-sdk-python/src/supermemory_openai/tools.py

• Same API refactor (only 4 lines changed based on file stats)

packages/pipecat-sdk-python/src/supermemory_pipecat/service.py

• Import sorting improvements (PEP 8 compliance)
• String formatting improvements with multi-line defaults
• Breaking API change: await self._supermemory_client.memories.add() → await self._supermemory_client.add()
• Recommendation: Needs major version bump

✅ Apps (No tests required)

apps/mcp/src/client.ts

• Same API refactor: client.memories.add() → client.add()
• Internal app change, no versioning concerns

---

Documentation Changes Review

Based on the file list, extensive documentation has been added/updated:

• New integration guides (OpenAI, Pipecat, AI SDK, memory-graph, n8n, Zapier)
• New concept docs (content types, customization, filtering, graph memory, super-rag, user profiles)
• Restructured add-memories, search, and user-profiles docs
• Migration guides updated

Note: Not reviewing doc content in detail as it's a large surface area and primarily prose/examples.

---

Critical Issues

🚨 Breaking API Changes Without Version Bumps

All published packages have breaking changes but I don't see version bumps in:

• packages/tools/package.json (not in diff)
• packages/ai-sdk/package.json (only types hash changed)
• Python package version files (not in diff)

Required Actions:

1. Bump major versions for all affected packages:

   • @supermemory/tools → new major version
   • @supermemory/ai-sdk → new major version
   • supermemory-openai → new major version
   • supermemory-pipecat → new major version

2. Add migration guide in docs explaining the API change:

   // Before
   await client.memories.add({ content: '...' })
   
   // After
   await client.add({ content: '...' })

3. Update CHANGELOG for each package documenting breaking changes

---

Test Coverage

❌ No test changes detected for packages that have test infrastructure:

• packages/tools (has Vitest) - No test updates
• packages/ai-sdk (has Vitest) - No test updates
• packages/openai-sdk-python (has pytest) - No test updates
• packages/pipecat-sdk-python (has pytest) - No test updates

Recommendation: While the API change is straightforward (method rename), existing tests should be updated to verify:

• The new client.add() method works correctly
• The old client.memories.add() method is removed or deprecated

---

Minor Issues

✅ Code formatting (Python): Import sorting and formatting improvements are good and follow Python conventions

⚠️ Type definitions: The packages/ai-sdk/package.json types file hash change suggests auto-generated types. Ensure the build process regenerates types correctly for the new API.

---

Verdict

🔴 Recommend changes before merge

1. Add version bumps to all affected package.json/setup.py files
2. Consider adding/updating tests for the API changes
3. Add migration documentation
4. Consider deprecation strategy if you want to maintain backwards compatibility temporarily

The documentation improvements look extensive and valuable, but the breaking changes need proper semver handling.

[claude]

PR Review: Documentation Changes

This PR contains comprehensive documentation updates and an important API migration from client.memories.add() to client.add() across multiple packages.

---

✅ Code Changes Review

API Migration (Breaking Change for Published Packages):

• All occurrences of client.memories.add() have been updated to client.add()
• Affected packages:
  • packages/tools/ (ai-sdk.ts, claude-memory.ts, openai/middleware.ts, openai/tools.ts, vercel/middleware.ts)
  • packages/ai-sdk/ (tools.ts)
  • packages/openai-sdk-python/ (middleware.py, tools.py)
  • packages/pipecat-sdk-python/ (service.py)
  • apps/mcp/ (client.ts)

Python Code Quality:

• ✅ Import ordering now follows PEP 8 (stdlib → third-party → local)
• ✅ String formatting improved (multi-line strings properly formatted)
• ✅ Type hints ordering alphabetized (e.g., Dict, List, Optional, TypedDict, Union)

---

⚠️ Issues Found

1. CRITICAL: package.json Types Field Change

- "types": "./dist/index-CITmF79o.d.ts",
+ "types": "./dist/index-h2cm3lSK.d.ts",

Location: packages/ai-sdk/package.json:28

Issue: The types field points to a build-generated hash filename. This change suggests:

• Either the build output was committed (which should be in .gitignore)
• Or this is a breaking change that should be reverted

Fix: This field should either:

• Be removed from git tracking (add dist/ to .gitignore and remove from the commit)
• Or use a static filename like ./dist/index.d.ts

The hash-based filename changes every build and will cause merge conflicts and unnecessary diffs in every PR.

---

2. Documentation Changes

The bulk of this PR is documentation restructuring:

• ✅ New comprehensive guides added
• ✅ Email updated from support@supermemory.ai → support@supermemory.com
• ✅ Navigation structure simplified
• No technical issues detected in the docs themselves

---

🧪 Test Coverage

✅ No test updates needed - the API migration is a simple method rename and existing tests don't mock client.memories.add() directly.

---

📋 Recommendations

Before merging:

1. Fix the package.json types field - Remove the hash-based filename change or use a static path
2. Version bump - Since this changes the API in published packages (@supermemory/ai-sdk, supermemory-openai, supermemory-pipecat), consider if this is a breaking change that requires a major version bump
3. Run the build - Ensure bun run build succeeds after the API changes
4. Verify Python packages - Run pytest for the Python SDKs to ensure the API changes work correctly

Optional:

• Consider adding a deprecation notice or migration guide for users of the old client.memories.add() API if this is being released to existing users

---

Summary

The code changes are clean and consistent across all packages. The main concern is the package.json types field change which appears to be a build artifact that shouldn't be committed.