# Changelog

All notable changes to Engram are documented here.

This project follows [Conventional Commits](https://www.conventionalcommits.org/) and uses [GoReleaser](https://goreleaser.com/) to auto-generate GitHub Release notes from commit history on each tag push.

## Where to Find Release Notes

Full release notes with changelogs per version live on the **[GitHub Releases page](https://github.com/Gentleman-Programming/engram/releases)**.

GoReleaser generates them automatically from commits, filtering by type:

- `feat:` / `fix:` / `refactor:` / `chore:` commits appear in the release notes
- `docs:` / `test:` / `ci:` commits are excluded from the generated changelog

## Breaking Changes

Breaking changes are always marked with a `type:breaking-change` label and documented in the release notes with a migration path. The `fix!:` and `feat!:` commit format triggers a major version bump.

## Unreleased

<!-- Changes that are merged but not yet released are tracked here until the next tag. -->

### Cloud sync

- **fix(cloud):** make chunk and mutation push payload limits configurable with `ENGRAM_CLOUD_MAX_PUSH_BYTES` while preserving the 8 MiB default.

### Cloud user token management (`cloud-user-token-management`)

- **feat(cloud):** add principal/human-user/token/project-grant/audit storage foundation (`cloud_principals`, `cloud_human_users`, `cloud_principal_tokens`, `cloud_project_grants`, `cloud_auth_audit_log`) alongside existing sync tables.
- **feat(cloud):** enforce managed-principal project grants for sync chunk/mutation push and pull while preserving legacy `ENGRAM_CLOUD_ALLOWED_PROJECTS` behavior.
- **feat(cloud):** add managed admin API handlers (`/admin/users`, `/admin/users/{id}/tokens`, `/admin/users/{id}/grants`, and related enable/disable/revoke routes) and dashboard managed-user UX, with audit-backed mutations.
- **feat(cloud):** add dashboard managed-principal sessions and first-admin dashboard bootstrap (`/dashboard/bootstrap`), including audit coverage for admin login and legacy-recovery actions.
- **feat(cloud):** add `engram cloud bootstrap admin --username <name> [--email <email>] [--grant-project <project>]... [--issue-token [name]]` CLI command to create the first managed admin headlessly, with duplicate-bootstrap refusal and `bootstrap.cli` audit events.
- **feat(cloud):** add `ENGRAM_CLOUD_TOKEN_PEPPER` for dedicated managed-token hashing, distinct from `ENGRAM_JWT_SECRET`.
- **feat(cloud):** wire managed-token authentication into `engram cloud serve` — the runtime principal resolver now checks managed token storage first, then falls back to the legacy `ENGRAM_CLOUD_TOKEN`/`ENGRAM_CLOUD_ADMIN` credentials, on every `/sync/*`, `/admin/*`, and dashboard-login request. Requires `ENGRAM_CLOUD_TOKEN_PEPPER` to be set; without it, managed-token auth is disabled and the server starts in legacy-only mode exactly as before. See [DOCS.md — Managed users, tokens, and CLI bootstrap](DOCS.md#managed-users-tokens-and-cli-bootstrap).
- **fix(cloud):** dashboard login/bootstrap audit events no longer send the legacy admin/sync principal's synthetic ID (e.g. `legacy:admin`) as `ActorPrincipalID`, which the real Postgres-backed audit table rejects (a non-numeric value against a `BIGINT` foreign key); this previously would have made every legacy admin dashboard login fail with a 500 once an admin identity store was configured.

### Pi package (`pi-engram`)

- **fix(plugin):** allow `mem_session_summary` to accept an explicit `project` fallback when automatic project detection is unavailable.
- **fix(plugin):** fall back to local `.engram/config.json` and surface a clearer version-mismatch diagnostic when the running Engram server lacks `/project/current`.
- **feat(plugin):** add `gentle-engram` package for Pi marketplace installs, with HTTP event capture, Memory Protocol prompt injection, safe `engram mcp` launcher config, and `pi-engram init` setup helper.

### Cloud dashboard visual parity (`cloud-dashboard-visual-parity`)

New and updated routes registered in `internal/cloud/dashboard/dashboard.go`:

- **feat(dashboard):** add `/dashboard/projects/list` HTMX partial with paginated project list and "Paused" badge when sync is disabled
- **feat(dashboard):** add `/dashboard/projects/{name}/observations|sessions|prompts` HTMX partials for project detail tabs
- **feat(dashboard):** add `/dashboard/contributors/list` HTMX partial with paginated contributor list
- **feat(dashboard):** add `/dashboard/contributors/{contributor}` detail page showing recent sessions, observations, and prompts
- **feat(dashboard):** add `/dashboard/admin/users` and `/dashboard/admin/users/list` (admin-gated)
- **feat(dashboard):** add `/dashboard/admin/health` (admin-gated)
- **feat(dashboard):** add `POST /dashboard/admin/projects/{name}/sync` toggle for per-project sync pause (admin-gated; HTTP 409 on paused push)
- **feat(dashboard):** add `/dashboard/sessions/{project}/{sessionID}`, `/dashboard/observations/{project}/{sessionID}/{syncID}`, `/dashboard/prompts/{project}/{sessionID}/{syncID}` composite-ID detail pages
- **fix(dashboard):** removed dead route `/dashboard/admin/contributors`; user/contributor management consolidated under `/dashboard/admin/users`
- **feat(dashboard):** type pills on browser page sourced from `ListDistinctTypes` DB query
- **feat(dashboard):** principal display name bridged via `MountConfig.GetDisplayName`; falls back to `"OPERATOR"` when nil or empty
- **feat(dashboard):** detail page URL scheme uses `{syncID}` (not `{chunkID}`) as the tertiary path segment

### Cloud autosync restoration (`cloud-autosync-restoration`)

Background mutation-based replication for `engram serve` and `engram mcp`:

- **feat(autosync):** `internal/cloud/autosync.Manager` — lease-guarded background push/pull goroutine enabled by `ENGRAM_CLOUD_AUTOSYNC=1` + `ENGRAM_CLOUD_TOKEN` + `ENGRAM_CLOUD_SERVER`
- **feat(cloudserver):** add `POST /sync/mutations/push` (batch up to 100 mutations, configurable body cap defaulting to 8 MiB, per-project auth + pause gate returning HTTP 409 `sync-paused`)
- **feat(cloudserver):** add `GET /sync/mutations/pull?since_seq=N&limit=M` (server-side filtered by enrolled projects; fail-closed when `EnrolledProjectsProvider` not implemented)
- **feat(autosync):** phases: `idle`, `pushing`, `pulling`, `healthy`, `push_failed`, `pull_failed`, `backoff`, `disabled`
- **feat(autosync):** reason codes: `transport_failed`, `auth_required`, `policy_forbidden`, `server_unsupported`, `internal_error`, `sync-paused`
- **feat(autosync):** exponential backoff — base 1s, max 5min, ×2 per failure, ±25% jitter, ceiling at 10 consecutive failures
- **feat(autosync):** `StopForUpgrade` / `ResumeAfterUpgrade` for upgrade-window pause without releasing the sync lease
- **fix(autosync):** SIGTERM cancels context → `releaseLease()` deferred in `Run()` for graceful shutdown

### BREAKING CHANGE: MCP write tools no longer accept a `project` field

The `project` argument has been removed from the JSON schemas of 7 MCP write tools:
`mem_save`, `mem_save_prompt`, `mem_session_start`, `mem_session_end`, `mem_session_summary`, `mem_capture_passive`, `mem_update`.

**Before:** agents could pass `project: "my-project"` to write tools.
**After:** the project is auto-detected from the server's working directory (cwd). Any `project` argument sent by the LLM is silently discarded.

**Migration:**

- Remove `project` from write tool calls in your agent's memory protocol.
- Use `mem_current_project` (new tool) to inspect which project Engram will use before writing.
- If the cwd is ambiguous (multiple git repos), Engram returns a structured error with `available_projects`. Navigate to one of the repos before writing.
- Read tools (`mem_search`, `mem_context`, `mem_timeline`, `mem_get_observation`, `mem_stats`) still accept an optional `project` override — validated against the store.

### New tool: `mem_current_project`

Returns detection result including `project`, `project_source`, `project_path`, `cwd`, `available_projects`, and `warning`. Never errors — returns success even when the cwd is ambiguous. Recommended as the first call when starting a session to confirm which project will receive writes.

- **feat(project):** add project name auto-detection via git remote and normalization (lowercase + trim + collapse) on all read/write paths
- **feat(cli):** add `engram projects list|consolidate|prune` commands for project hygiene
- **feat(mcp):** add `mem_merge_projects` tool for agent-driven project consolidation
- **feat(mcp):** auto-detect project at MCP startup via `--project` flag, `ENGRAM_PROJECT` env, or git remote
- **feat(mcp):** similar-project warnings when saving to a new project that resembles an existing one
- **fix(sync):** use git remote detection instead of `filepath.Base(cwd)` for project name
