# Changelog

> Where every release of the engine, the SDKs, the MCP package, the skills and Sypnia Cloud will be listed, how an entry is written, and what the version numbers promise.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/reference/changelog/

For agents: Sypnia's changelog page and its rules. Nothing is released yet, so there are no entries. Once releases exist: one entry per release, newest first, per component (engine, SDKs, @sypnia/mcp, skills, Sypnia Cloud), with fixed headings (Added, Changed, Fixed, Security, Deprecated, Removed, To do when upgrading). Versions follow semantic versioning; inside version 1 the API, the event schema, the settings and the database only add.

This page is for anyone who upgrades Sypnia or wants to know what changed. It covers what is released as software, the open-source engine, the SDKs, `@sypnia/mcp` and the skills **\[Engine]**, and what changes in the service, Sypnia Cloud **\[Cloud]**.

> **Note: No release yet**
>
> Sypnia is written documentation-first: these docs are the contract, and the code is being written to match them. Nothing has been released, so this page has no entries. The first one will be version 1.0.0 of the engine and the SDKs. What follows is how the page will be kept.

## Releases

No releases yet.

## How this page is kept

- **One entry per release**, newest first. A release that changed nothing you can see still gets a line.
- **Written for the person upgrading**, in plain words: what changed for you, not what changed in the code.
- **The same day as the release.** A release without its entry is not finished.
- **Never rewritten.** A mistake in an entry is corrected with a visible note, not by editing history.

Each component has its own version and its own entries:

| Component                                         | Version is seen in                                                                                  |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| The engine and the Console                        | `sypnia version`, and the `Sypnia-Version` header of every API answer                               |
| `@sypnia/browser`, `@sypnia/node`, `@sypnia/next` | The package version in your `package.json`                                                          |
| `@sypnia/mcp`                                     | The package version                                                                                 |
| The agent skills                                  | The plugin's version                                                                                |
| Sypnia Cloud                                      | Entries are dated. The service has no version of its own; it runs a released version of the engine. |

## What an entry looks like

Every entry uses the same headings, in this order, and leaves out the ones that are empty:

| Heading                  | Holds                                                                                         |
| ------------------------ | --------------------------------------------------------------------------------------------- |
| **To do when upgrading** | Anything the upgrade asks of you. Most releases have none. Always first, so nobody misses it. |
| **Added**                | New things.                                                                                   |
| **Changed**              | Things that behave differently.                                                               |
| **Fixed**                | Bugs.                                                                                         |
| **Security**             | Fixes for security problems, with how serious each is and which versions it affects.          |
| **Deprecated**           | Things that still work and will be removed in the next major version.                         |
| **Removed**              | Things that are gone. Only in a major version.                                                |

An entry, as it will look. The version and the two fixes are an illustration, not a real release:

```md
## Engine 1.0.1 — <date>

### To do when upgrading
Nothing. Run `sypnia migrate`, then replace the engine.

### Fixed
- A session that crossed midnight was counted on both days in the daily numbers.
- `sypnia doctor` reported the storage check as failed on a bucket with a prefix.
```

When something on the [Planned](https://docs.sypnia.com/reference/planned) page ships, its entry says so and the item leaves that page.

## What the version numbers promise

Versions are three numbers, `major.minor.patch`.

| A change in               | Means                                                                                           |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| **Patch**, 1.0.0 to 1.0.1 | Fixes only. Safe to take at once.                                                               |
| **Minor**, 1.0 to 1.1     | New things. Nothing you use stops working.                                                      |
| **Major**, 1 to 2         | Something was removed or changed in a way that needs your attention. Announced here in advance. |

Inside version 1, these only ever add:

| What                     | The promise                                                                                                                                                           | Where it is written                                                                  |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| The HTTP API under `/v1` | New endpoints, new optional parameters, new fields and new values in answers. A breaking change would be `/v2`, with `/v1` kept working for at least 12 months.       | [Errors, limits, pagination](https://docs.sypnia.com/api/errors-limits-pagination)   |
| The event schema         | New event types and new fields. The engine keeps fields it does not know, so a newer SDK works with an older engine.                                                  | [Event schema](https://docs.sypnia.com/reference/event-schema)                       |
| The engine's settings    | New settings with defaults. A setting the engine does not know is a warning in `sypnia doctor`, never a failure to start, so an old setting does not stop an upgrade. | [Configuration reference](https://docs.sypnia.com/self-hosting/configuration)        |
| The database             | Migrations only add. An older engine works against a newer schema, so you can go back.                                                                                | [Upgrades](https://docs.sypnia.com/self-hosting/upgrades-backups-retention#upgrades) |
| The MCP tools            | New tools and new fields in results.                                                                                                                                  | [Tools reference](https://docs.sypnia.com/mcp/tools-reference)                       |

## Engine and Cloud

|                    | Sypnia engine (open source, self-hosted)                | Sypnia Cloud (paid service, with a free tier)                    |
| ------------------ | ------------------------------------------------------- | ---------------------------------------------------------------- |
| Who upgrades       | You, when you choose. See Upgrades, backups, retention. | We do. You do nothing.                                           |
| What you read here | Each engine release, and what to do when upgrading.     | Dated entries for changes in the app, the plans and the service. |
| SDKs               | You choose when to update the package in your app.      | The same: the SDK is in your app, not in our service.            |

## Follow changes

Until the repositories open, this page is the place. Afterwards, each repository's releases carry the same entries, and you can watch a repository to be told of new ones.
