Migration Guide

Overview

Synapse Layer follows semantic versioning. Minor and patch releases (e.g. 2.4.3 → 2.4.4) are backward-compatible — update the package and you're done. This guide covers transitions that require configuration or code changes.

v1.x → v2.x

The v2.x release introduced the Cognitive Security Pipeline, MCP server support, and framework integrations. Key changes:

1. Update the package

pip install --upgrade synapse-layer

2. Authentication change

v2.x uses x-connect-token header authentication (introduced in v1.2.0). If you were using query-parameter authentication, migrate to headers:

# v1.x (deprecated pattern)
client = Synapse(api_key="sk_token")  # query param internally

# v2.x (current — header-first auth)
client = Synapse(api_key="sk_connect_your_token")  # x-connect-token header
# Or via environment variable:
# export SYNAPSE_TOKEN=sk_connect_your_token

3. Database migration

v1.1.8 migrated from Supabase to PostgreSQL. If you're on v1.1.7 or earlier, you need to provision a PostgreSQL database:

# Set your database URL
export DATABASE_URL="postgresql://user:pass@host:5432/synapse"

# Run migrations
python -m synapse_memory.migrations

4. MCP server (new in v2.x)

v2.x includes a built-in MCP server with 13 tools. To start using it:

# Start the MCP server (stdio transport for Claude Desktop)
uvx --from synapse-layer synapse-layer

v2.3.x → v2.4.x

This is a non-breaking upgrade. Update the package:

pip install --upgrade synapse-layer

What changed

• v2.4.0: Added GC cron endpoint for expired memory cleanup, Smithery publish automation, 13-tool MCP server card.
• v2.4.1: Canonical version governance, TypeScript SDK sync, Glama/server.json registry metadata.
• v2.4.2: Governance fixes — removed prohibited compliance claims from public manifests.
• v2.4.3: Security — pinned cryptography≥48.0.1 (GHSA-537c-gmf6-5ccf).
• v2.4.4: Restored MCP Registry ownership marker. No functional changes.

GC Cron setup (optional, v2.4.0+)

If you want automatic cleanup of expired memories, configure the GC cron:

# Set the cron secret in your environment
export CRON_SECRET="your-secure-random-secret"

# Schedule via cron (every hour)
0 * * * * curl -X POST https://your-forge-url/api/cron/gc \
  -H "Authorization: Bearer $CRON_SECRET"

Dependency Updates

Key dependency floors as of v2.4.4:

Post-Migration Verification

After upgrading, verify your installation:

# Check installed version
python -c "import synapse_memory; print(synapse_memory.__version__)"

# Run health check (if using Forge)
curl -s https://your-forge-url/api/health | python -m json.tool

# Test store and recall
python -c "
from synapse_layer import Synapse
client = Synapse(api_key='your_token')
client.remember('Migration test memory')
results = client.recall('migration test')
print(f'Recall returned {len(results)} results')
for r in results:
    print(f'  TQ={r["trust_quotient"]:.2f} | {r["content"]}')
"