> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maximem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> All notable changes to the Synap SDK and API are documented here. This project follows [Semantic Versioning](https://semver.org/) (SemVer).

* **Major** versions introduce breaking changes to the API or SDK interfaces
* **Minor** versions add new features in a backward-compatible manner
* **Patch** versions contain backward-compatible bug fixes

<Tip>
  Subscribe to release notifications by watching the [maximem\_synap\_sdk](https://github.com/maximem-ai/maximem_synap_sdk) repository on GitHub, or join the `#releases` channel on [Discord](https://discord.gg/synap) for real-time updates.
</Tip>

## Compatibility Matrix

Use this table to pick compatible versions when pinning dependencies.

### Core SDK

| `maximem-synap` | Python | `httpx`         | `pydantic`  | `grpcio` | Cloud API |
| --------------- | ------ | --------------- | ----------- | -------- | --------- |
| 0.2.x           | ≥ 3.11 | ≥ 0.27, \< 0.29 | ≥ 2.5, \< 3 | ≥ 1.60   | v1        |
| 0.1.x           | ≥ 3.11 | ≥ 0.27, \< 0.29 | ≥ 2.5, \< 3 | ≥ 1.60   | v1        |

### Integration packages

| Package                            | Pins core SDK    | Pins framework                            | Notes                              |
| ---------------------------------- | ---------------- | ----------------------------------------- | ---------------------------------- |
| `maximem-synap-langchain`          | ≥ 0.1            | `langchain` ≥ 0.2, `langchain-core` ≥ 0.2 |                                    |
| `maximem-synap-langgraph`          | ≥ 0.1            | `langgraph` ≥ 0.2                         |                                    |
| `maximem-synap-llamaindex`         | ≥ 0.1            | `llama-index-core` ≥ 0.11                 |                                    |
| `maximem-synap-openai-agents`      | ≥ 0.1            | `openai` ≥ 1.30                           |                                    |
| `maximem-synap-pydantic-ai`        | ≥ 0.1            | `pydantic-ai` ≥ 0.0.13                    |                                    |
| `maximem-synap-crewai`             | ≥ 0.1            | `crewai` ≥ 0.60                           |                                    |
| `maximem-synap-autogen`            | ≥ 0.1            | `autogen-agentchat` ≥ 0.4                 |                                    |
| `maximem-synap-google-adk`         | ≥ 0.1            | `google-adk` ≥ 0.1                        |                                    |
| `maximem-synap-haystack`           | ≥ 0.1            | `haystack-ai` ≥ 2.5                       |                                    |
| `maximem-synap-agno`               | ≥ 0.1            | `agno` ≥ 1.0                              |                                    |
| `maximem-synap-semantic-kernel`    | ≥ 0.1            | `semantic-kernel` ≥ 1.0                   |                                    |
| `maximem-synap-microsoft-agent`    | ≥ 0.1            | `agent-framework` ≥ 0.1                   |                                    |
| `maximem-synap-nemo-agent-toolkit` | ≥ 0.1            | `nemo-agent-toolkit` ≥ 0.5                |                                    |
| `maximem-synap-livekit-agents`     | ≥ 0.1            | `livekit-agents` ≥ 0.10                   |                                    |
| `maximem-synap-pipecat`            | ≥ 0.1            | `pipecat-ai` ≥ 0.0.50                     |                                    |
| `maximem-synap-vercel-adk`         | n/a (TS package) | `ai` ≥ 3.0                                | Node.js 18+                        |
| `maximem-synap-mastra`             | n/a (TS package) | `@mastra/core` ≥ 0.5                      | Node.js 18+                        |
| `maximem-synap-claude-agent`       | ≥ 0.1            | `claude-agent-sdk` ≥ 0.1                  | Available in Python and TypeScript |

<Note>
  Pin numbers above reflect the minimum tested. Newer minor/patch versions of the framework will typically work, but if a framework ships a breaking change, the integration package will pin around it explicitly. Check the integration package's own changelog for the exact pin if you suspect a compatibility issue.
</Note>

### Cloud API

The Cloud API is versioned at the URL prefix (`/v1/...`). The current SDK targets v1 exclusively. v2 is not on the near-term roadmap.

***

## v0.2.0, 2026-07-06

### Added

* **`precision_level` fetch parameter**: All context fetch calls now accept an optional `precision_level` parameter (`"high"` or `"medium"`). With `"high"` (the default), behavior is unchanged — results go through an additional relevance-refinement pass before being returned. `"medium"` skips the refinement pass for faster responses; recall isn't impacted — the same candidate memories are searched — but outputs are less precisely filtered.

***

## v0.1.2, 2025-01-15

### Added

* **Entity Resolution integration**: The ingestion pipeline now resolves entities across conversations. Mentions of the same entity (e.g., "John", "John Smith", "my manager") are linked to a canonical entity record.
* **Review queue for entity resolution**: Ambiguous entity matches are routed to a review queue for human verification via the Dashboard.
* **Auto-registration of unresolved entities**: New entities that do not match any existing record are automatically registered at the CUSTOMER scope for future lookups.
* **Semantic entity matching**: Entity resolution uses semantic similarity matching, catching variations that exact string matching would miss.

### Changed

* Entity resolution is now integrated before persistence in the ingestion flow.
* Entity resolution runs as a graceful degradation feature: if unavailable, the pipeline continues without resolution and logs a warning.

### Fixed

* Fixed non-deterministic test behavior caused by Python set iteration order in pipeline stage tests.

***

## v0.1.1, 2025-01-10

### Added

* **Memory Architecture Configuration (MACA) system**: Full configuration lifecycle with init, update, review, apply, and rollback operations.
* **Admin API Groups A-D**: Client lifecycle (10 endpoints), instance lifecycle (12 endpoints), config management (10 endpoints), and setup/onboarding (6 endpoints).
* **Dashboard API routes**: Configuration detail and history endpoints for the web UI.
* **Configuration persistence and workflow improvements**: Added storage and workflow support for configuration metadata, approvals, and history.
* **Configuration validation improvements**: Stronger schema and business-rule validation for submitted configuration files.
* **Setup and architecture management improvements**: Better onboarding and dashboard-facing configuration management flows.

### Changed

* Admin API response shapes were standardized for consistency across dashboard routes.
* Configuration version numbers are parsed from semantic version strings ("1.0.0" becomes version `1`).

### Fixed

* Resolved circular import issues in `admin_api/__init__.py` by using lazy imports (inside methods) for cross-manager dependencies.

***

## v0.1.0, 2025-01-05

### Added

* **Initial release** of the Synap SDK and API.
* **Memory ingestion pipeline**: Four-stage async pipeline (extraction, categorization, entity resolution, storage) with `fast` and `long-range` processing modes.
* **Context retrieval**: `POST /v1/context/fetch` with vector search, graph traversal, and re-ranking. Supports `fast` and `accurate` retrieval modes.
* **Context compaction**: `POST /v1/context/compact` with `adaptive`, `aggressive`, `balanced`, and `conservative` strategies.
* **Instance management**: Full CRUD for instances via the Dashboard API, including API key generation and revocation.
* **API key authentication**: `synap_<random>` keys issued from the Dashboard, used as `Authorization: Bearer` for all SDK communication (REST and gRPC).
* **Cloud auth layer**: Production-ready authentication and authorization foundation for SDK and dashboard operations.
* **Memory Architecture Configurators**: Initial configuration system for storage, ingestion, and retrieval controls.
* **Scope system**: Four-level scope chain (USER > CUSTOMER > CLIENT > WORLD) with proper isolation and inheritance.
* **Webhook system**: Five event types (`conversation.started`, `conversation.ended`, `context.retrieved`, `config.applied`, `compaction.completed`) with HMAC-SHA256 signature verification.
* **Analytics**: Usage metrics, latency percentiles, and token tracking with minute/hour/day rollup buckets.
* **Python SDK**: Fully async SDK with typed exceptions and automatic retries.
* **PostgreSQL backend**: Persistent storage for clients, instances, credentials, memories, and analytics data.
* **Production key management integration**: Cloud-integrated key management support.

### Security

* API keys are hashed (SHA-256) at rest and shown to the user only once at generation time.
* Revoking an API key takes effect immediately.
* AuthContext is immutable once created, preventing tampering.

***

<Note>
  Versions prior to 1.0.0 may include breaking changes in minor version increments as the API stabilizes. We recommend pinning to a specific version in production and testing upgrades in staging first.
</Note>