API Stability & Versioning

ContextOS adheres strictly to Semantic Versioning. Starting from v1.0.0, version numbers dictate the nature of changes:

• MAJOR (v2.0.0): Incompatible, breaking changes (e.g., removing deprecated CLI flags, breaking MCP tool signatures).
• MINOR (v1.1.0): Backwards-compatible new features (e.g., adding a new LLM provider, introducing new configuration keys).
• PATCH (v1.0.1): Backwards-compatible bug fixes, performance improvements, and security patches.

The following surfaces are considered the Public API of ContextOS and are protected by our SemVer guarantees in all v1.x releases:

1. CLI Commands

Commands (init, serve, query, etc.) and their primary flags will not be removed or functionally altered in a breaking way.

2. MCP Tool Interface

The names, arguments, and general return structures of the official MCP tools (get_context, reindex_context, etc.) are stable. Tools will not be removed, and required parameters will not be added to existing tools without a major version bump.

3. Configuration File

Keys defined in the official configuration schema will not be removed or have their types changed. We publish a JSON schema for validating your .contextos/config.json.

// In your .contextos/config.json
{
  "$schema": "https://raw.githubusercontent.com/siddharthakatiyar/ContextOS/main/config.schema.json",
  "maxTokenBudget": 2000
}

When we need to retire a feature, we follow a strict deprecation lifecycle:

1. Announcement: The deprecation is announced in a MINOR release. A warning will be logged to the console/daemon when the deprecated feature is used.
2. Grace Period: The feature will remain fully functional for at least 6 months or until the next MAJOR release (whichever is longer).
3. Removal: The feature is completely removed in a MAJOR release.