# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.14.1] - 2026-03-03

### Changed
- `AGENTS.md` folder context mode now defaults to `single`, generating one root context file instead of creating `AGENTS.md` files across touched subfolders.
- Documentation updated to reflect `single` as the default `OPEN_MEM_FOLDER_CONTEXT_MODE` / `folderContextMode`.

## [0.14.0] - 2026-02-23

### Added
- **Interactive setup wizard** — `npx open-mem` now launches a beautiful interactive onboarding wizard (powered by `@clack/prompts`) that guides users through provider selection, dashboard, workflow mode, and context file configuration. Use `--quick` to skip the wizard.
- **OpenCode session bridge** — when no API key is configured, open-mem automatically routes AI compression through OpenCode's own session model. Zero-config AI compression for all users, regardless of auth method (env vars, OAuth, Copilot, etc.).
- **Smart provider detection** — at plugin init, queries OpenCode's configured providers via the SDK client and gives actionable guidance instead of generic warnings.

### Changed
- `chat.message` hook now accepts the new OpenCode model format (`{ providerID, modelID }` object alongside legacy string).
- Auto-detect provider option updated to reflect automatic OpenCode fallback — no separate API key warning removed.
- Wizard messaging reflects that AI compression works out-of-the-box without extra configuration.

## [0.13.0] - 2026-02-23

### Added
- **`npx open-mem` CLI installer** — one-command plugin setup for OpenCode. Automatically finds or creates the config file and adds `open-mem` to the plugin array. Supports `--global`, `--uninstall`, `--dry-run`, `--force`, and `--version` flags. JSONC-aware (preserves comments in existing config files). Cleans OpenCode plugin cache on uninstall.
- AI provider detection in installer — shows which providers are configured after install.

### Changed
- Documentation updated — README Quick Start and Getting Started guide now recommend `npx open-mem` as the primary installation method, with manual `bun add` as alternative.

## [0.12.0] - 2026-02-16

### Changed
- Hardened operator route security model to rely on loopback listener binding instead of header-based locality checks.
- Consolidated architecture script file walking into `scripts/utils/file-walk.ts` with deterministic extension filtering.
- Reduced internal mode resolver API surface by removing dead exports.

## [0.11.0] - 2026-02-08

### Added
- **Pluggable workflow modes** — JSON-based mode definitions that customize observation types, concept vocabulary, entity types, and AI prompt templates. Ships with `code` (default) and `research` modes. Configure via `OPEN_MEM_MODE` env var. New `/v1/workflow-modes` API endpoint.
- **Enhanced session compaction** — compaction hook now injects compressed recent observation narratives, facts, and key decisions with smart budget allocation (40% summaries/index, 40% observation details, 20% decisions). Graceful degradation when full observations unavailable.
- **VitePress documentation website** — 11-page docs site covering getting started, architecture, tools reference, search guide, configuration, platforms, privacy, API, troubleshooting, and changelog. Build with `bun run docs:build`.
- **Dashboard documentation** in README — "Web Dashboard" section describing all 6 pages (Timeline, Sessions, Search, Stats, Operations, Settings) with enable/access instructions.
- **"Why open-mem?" section** in README — competitive positioning highlighting native vector search, knowledge graph, 5 AI providers, revision lineage, and MIT license.
- **Feature highlights comparison table** in README — side-by-side comparison vs typical alternatives.

### Fixed
- CI platform worker tests now use portable bun path and project root.

## [0.10.0] - 2026-02-08

### Added
- **OpenRouter provider support** — access 100+ models via `OPEN_MEM_PROVIDER=openrouter` + `OPENROUTER_API_KEY`. Auto-detected from env vars, default model `google/gemini-2.5-flash-lite`. Embeddings correctly return null (OpenRouter doesn't support them).
- **Provider fallback chain** — automatic failover when primary AI provider returns retryable errors (429/500/503). Configure with `OPEN_MEM_FALLBACK_PROVIDERS=google,anthropic,openai`. Config errors (400/401/403) throw immediately without fallback. Applies only to language models, never to embeddings.
- **Timeline anchor navigation** — `mem-history` tool now accepts `anchor` (observation ID), `depthBefore`, and `depthAfter` parameters for cross-session chronological navigation around a specific observation.
- `src/ai/errors.ts` — shared `isRetryable()`, `isConfigError()`, and `sleep()` utilities extracted from 3 duplicated locations.
- `src/ai/fallback.ts` — `FallbackLanguageModel` wrapper implementing Vercel AI SDK `LanguageModel` interface with try→fail→next semantics.
- `@openrouter/ai-sdk-provider` dependency for OpenRouter integration.

### Changed
- All AI consumers (compressor, summarizer, entity-extractor, conflict-evaluator, reranker) now use `createModelWithFallback()` instead of `createModel()` — transparent fallback when configured.
- `AGENTS.md` generation now includes observation IDs, key concepts, and decision summaries in tables.
- `mem-create` tool description improved for clarity.
- Context injection now includes "When to Save" guidance with `mem-create` reference.

## [0.7.0] - 2026-02-08

### Added (Interop & Ops)
- MCP strict lifecycle support and protocol negotiation (`initialize`, `notifications/initialized`, strict pre-init gating)
- Deterministic MCP validation errors and JSON-schema tool metadata generation
- Runtime ops APIs: `GET /v1/health` and `GET /v1/metrics`
- Platform adapter foundation (`adapters/platform`) with normalized event schema and capability descriptors for OpenCode, Claude Code, and Cursor
- Dashboard Operations page showing runtime health, queue state, and throughput counters
- Benchmark scripts:
  - `bun run bench:search`
  - `bun run bench:platform`
- MCP compatibility matrix documentation (`docs/mcp-compatibility-matrix.md`)
- External compatibility GA scaffolding:
  - verification harness (`scripts/verify-external-clients.ts`)
  - worker bridge smoke checks (`scripts/smoke-platform-workers.ts`)
  - matrix renderer + release gate scripts (`scripts/render-compat-matrix.ts`, `scripts/check-external-compat-gate.ts`)
  - CI workflows for nightly compatibility evidence and release blocking (`.github/workflows/external-compat.yml`, `.github/workflows/release-gate.yml`)

### Added (Core 0.7.0)
- Modular architecture boundaries: `core`, `store`, `runtime`, and `adapters` layers
- `MemoryEngine` interface as single orchestration surface for all transports
- Shared API contracts with Zod schemas and `ok()`/`fail()` envelope (`contracts/api.ts`)
- Config control-plane APIs: `GET /api/config/schema`, `GET /api/config/effective`, `POST /api/config/preview`, `PATCH /api/config`
- Folder-context maintenance endpoints:
  - `POST /api/maintenance/folder-context/dry-run`
  - `POST /api/maintenance/folder-context/clean`
  - `POST /api/maintenance/folder-context/rebuild`
- Maintenance CLI binary `open-mem-maintenance`:
  - `reset-db --project <path>`
  - `folder-context clean|rebuild [--dry-run]`
- Import-boundary validation script (`bun run check:boundaries`)

### Changed
- Tool names renamed from `mem-*` prefix to `memory.*` namespace (e.g. `mem-search` → `memory.find`, `mem-save` → `memory.create`)
- `memory.revise` now uses immutable revision semantics (creates a successor revision)
- `memory.remove` now uses tombstone semantics (soft-delete active observation)
- Active retrieval/search now returns only non-superseded, non-tombstoned observations
- Schema baseline extended to v10 (`scope`, `revision_of`, `deleted_at` + indexes)
- Dashboard Settings now includes editable config with preview/apply and folder-context maintenance controls

### Removed
- Internal backward-compatibility guarantees with pre-`0.7.0` schema internals
- Package self-dependency (`open-mem` depending on itself)
- Legacy `servers/http-server.ts`, `servers/mcp-server.ts`, `servers/sse-broadcaster.ts` — replaced by `adapters/http/`, `adapters/mcp/`, `adapters/http/sse.ts`

### Notes
- Local-first storage remains in project `.open-mem/` (plus optional user-level DB)
- Pre-`0.7.0` local databases are not auto-migrated to immutable lineage semantics; use the maintenance reset flow

## [0.2.0] - 2026-02-06

### Added
- `mem-recall` tool for fetching full observation details by ID
- Progressive disclosure context injection with type icons, token costs, and file grouping
- `<private>` tag support for user-controlled content exclusion from memory
- Structured session summaries with request, investigated, learned, completed, and next steps fields
- Concept vocabulary guidance in AI compression prompts (how-it-works, gotcha, pattern, trade-off, etc.)
- Context injection configuration options (token cost display, observation type filters, full observation count)

### Fixed
- README `OPEN_MEM_CONTEXT_INJECTION` default incorrectly documented as `false` (actual default: `true`)
- Missing `.open-mem/` in project .gitignore

### Changed
- License changed from AGPL-3.0 to MIT

## [0.1.0] - 2026-01-15

### Added
- Initial release
- Automatic observation capture from tool executions
- AI-powered compression using Claude (optional — works without API key)
- SQLite + FTS5 full-text search for fast retrieval
- Context injection into new sessions via system prompt
- Three custom tools: `mem-search`, `mem-save`, `mem-timeline`
- Session summaries with AI-generated narratives
- Progressive disclosure with token budget management
- Configurable sensitive content redaction
- Data retention policies (default: 90 days)
- 162 tests with 395 assertions