v1.16.1

Engram v1.16.1 is a quality and reliability release: seven bug fixes across the MCP session model, cloud sync, project migration, the macOS and Windows builds, and the plugin cache — plus expanded documentation for MCP project overrides, team usage, and topic keys. Every fix was validated by adversarial review before merge.

Highlights

• Active session resolution for mem_save (#386): saves without an explicit session now attach to the active session resolved from the shared store, instead of falling back to manual-save-{project}. This fixes UUID sessions that stayed empty at observation_count: 0.
• Edited memories re-export on sync (#447): mem_update edits are no longer skipped by engram sync. The export now checks UpdatedAt, not just CreatedAt.
• No more case-only duplicate projects (#438): project migration normalizes names before comparing, so a repo whose remote is Repo_Name no longer ping-pongs against a local repo_name.
• macOS 26.4 binaries run again (#402): darwin builds are adhoc re-signed during release, fixing the AMFI SIGKILL (exit 137) on Apple Silicon.
• Cloud upgrade repair applies partial fixes (#446): repairable mutations are now applied even when a blocker is queued, and the message names the real blocker (seq + entity_key) instead of the wrong entry.
• Plugin cache no longer recurses (#217): the plugin version is synced with the marketplace manifest so installs stop creating nested empty cache directories.
• Clearer Windows background sync (#421): autosync token logging now names both ENGRAM_CLOUD_TOKEN and the cloud.json fallback, and the prompt hook emits UTF-8 under PowerShell 5.1.

Contribution highlights

Thanks to the contributors and issue reporters who shaped this release:

• @carlosmoradev authored the new Team Usage guide (#409, closing #305) — scope conventions, language strategy for shared memory, and how scope interacts with sync today.
• Issue reports #386, #438, #446, #447, #217, #421, #401, #402 drove the fixes.
• Adversarial review caught two fixes that looked correct but were not — a session registry that could not cross the HTTP/MCP process boundary, and a plugin source change that breaks Claude Code clients older than v2.1.69 — before either shipped.

Pi companion notes

No new gentle-engram npm package was published in this release. The Pi companion remains gentle-engram@0.1.7; this release updates the main Engram binary and documentation.

Fixes included

• mem_save / prompt / summary / passive saves resolve the most-recent active session from the store before falling back to manual-save-{project}.
• engram sync re-exports observations edited via mem_update (now checks UpdatedAt).
• Project migration normalizes names, preventing case-only duplicate projects (regression of #136).
• darwin release binaries are adhoc re-signed to satisfy AMFI on macOS 26.4.
• cloud upgrade repair --apply applies the repairable subset alongside a blocker and reports the correct blocker.
• Plugin plugin.json version synced with the marketplace manifest to stop recursive cache directories.
• Windows autosync token logging clarified; prompt hook output set to UTF-8.
• New documentation: MCP --project / ENGRAM_PROJECT override, VS Code/WSL setup, Linux EXDEV troubleshooting, a topic_key guide, a Windows Task Scheduler template, and the Team Usage guide.

Changelog

• #449 fix(mcp): resolve active session from store for mem_save instead of manual-save fallback (#386)
• #450 fix(sync): re-export edited observations by checking UpdatedAt in filterNewData (#447)
• #451 fix(server): normalize project names before migrate to prevent case-only duplicates (#438)
• #452 fix(store): apply repairable cloud-upgrade mutations even when a blocker is queued (#446)
• #453 fix(release): adhoc re-sign darwin binaries to prevent AMFI SIGKILL on macOS 26.4 (#402)
• #454 fix(cloud): clarify autosync token error log and add UTF-8 PS1 output encoding (#421)
• #455 fix(plugin): sync plugin.json version to 0.1.1 to stop recursive cache dirs (#217)
• #456 docs: mcp project override, VS Code/WSL, EXDEV, topic_key guide, Task Scheduler
• #409 docs: add team usage guide (#305, by @carlosmoradev)

v1.16.0

Engram v1.16.0 lands a broad, high-impact wave of fixes and features: opt-in HTTP auth and constant-time token comparisons, new CLI delete sub-commands, a TUI clipboard shortcut, cross-project personal search, case-insensitive legacy project matching, a cloud allowlist wildcard, Pi setup hardening, and a wholesale docs refresh. Multiple external contributors and issue reporters drove this release.

Highlights

Security

• Optional local auth for destructive HTTP endpoints (ENGRAM_HTTP_TOKEN): when set, DELETE /sessions/{id}, DELETE /observations/{id}, DELETE /prompts/{id}, GET /export, POST /import, and POST /projects/migrate require Authorization: Bearer <token>. Unset = open (zero-config preserved). Constant-time compare via hmac.Equal.
• Constant-time token comparisons: bearer and admin token checks in internal/cloud/auth and cloudserver use hmac.Equal instead of ==/!=, eliminating the timing-oracle.
• Obsidian exporter path traversal: internal/obsidian/exporter.go sanitizes project and type components before filepath.Join and adds a post-join containment check, rejecting any path that escapes the export root.

CLI

• engram delete now supports sub-commands: delete observation <id>, delete session <id>, delete prompt <id>, and delete project <name>. All accept --hard. The legacy engram delete <obs_id> form still works.
• store.DeleteProject atomic cascade: orphans memory_relations, removes observations (soft or hard), prompts, and sessions (hard only — the FK constraint blocks session removal while soft-deleted observations still reference them).

TUI

• c keybinding copies the highlighted observation to the clipboard via OSC 52 on Recent Observations, Search Results, Observation Detail, and Session Detail. Works over SSH, no system deps.

Search and scopes

• mem_search accepts all_projects: true to search every project at once instead of the resolved one.
• scope=personal without an explicit project now searches personal observations across all projects (mem_search, mem_context).
• global is a valid scope alongside project and personal (was silently coerced to project).
• Legacy mixed-case project data is now searchable: store queries use LOWER(project) = ? so observations stored as Ebook2Audio are found when queried as ebook2audio — the MCP path normalizes; the CLI was the only path that happened to work before.
• Configurable timestamp display: ENGRAM_TIMEZONE sets the display timezone for the TUI and the cloud dashboard. Falls back to system local; UTC is preserved in storage.

Cloud

• ENGRAM_CLOUD_ALLOWED_PROJECTS accepts * to allow every project (per-project enforcement bypassed). Useful for dev and internal deploys.
• sync --cloud sends the Authorization header when only cloud.json carries the token: resolveCloudRuntimeConfig no longer zeroes the file token before reading the env var.
• cloud status detects a dead local daemon with a 1-second probe and prints actionable guidance; the launchd unit template is documented.

MCP

• handleSessionSummary hardened: it now respects the process-level project override (ENGRAM_PROJECT / engram mcp --project) consistent with every other write tool, and rejects empty or whitespace-only content before AddObservation. This fixes stuck sync_mutation rows that blocked cloud upgrade.

Windows

• CLAUDE_PLUGIN_ROOT is escape-quoted in every hooks.json command entry, so all Claude Code hooks fire on profile paths containing spaces (e.g. C:\Users\John Doe\...).

Pi

• engram setup pi pins npmCommand to a mise-stable form (["mise","exec","node@X.Y.Z","--","npm"]) when mise is detected and no command is configured, preventing duplicate installs when Node drifts. Existing values are preserved.
• Pi status bar maps ambiguous_project to an actionable label instead of the generic error.

Docs

• Wholesale sync: the DOCS.md environment-variables table went from 3 to 17 rows; printUsage() env block synced with code; CLI reference tables in README.md and docs/ARCHITECTURE.md now include doctor, conflicts, delete, and projects prune; Codex troubleshooting for "MCP Transport closed" was added; the new ENGRAM_HTTP_TOKEN, ENGRAM_TIMEZONE, scope=personal cross-project behavior, global scope, * cloud wildcard, and Pi npmCommand pinning are all documented.

Contribution highlights

Thanks to the external contributors and issue reporters who shaped this release:

• @carlosmoradev shipped #408 (all_projects flag for mem_search), #346 (configurable timezone), and #410 (install-from-source version-stamp docs).
• @jlsevillano shipped #337 (dead-daemon detection in cloud status and launchd documentation).
• Issue reports that drove targeted fixes: #180 (Obsidian path traversal), #200 (HTTP auth), #350 (constant-time compare), #260 (cloud wildcard), #146 (MCP search empty for legacy data), #391 (personal-scope filter), #403, #413, #393 (handleSessionSummary gaps), #122 (global scope), #343 (sync --cloud auth header), #209, #218, #219 (CLI delete), #141 (TUI copy), #420 (Windows hooks quoting), #385 (Pi npmCommand), #384 (Pi status bar), #167 (Codex docs).

Pi companion notes

No new gentle-engram npm package was published in this release. The current Pi companion remains gentle-engram@0.1.7; this release updates the main Engram binary, the Pi setup logic in engram setup pi, and the Pi documentation.

Changelog

• #443 docs(codex): add troubleshooting for MCP Transport closed error (closes #167)
• #442 fix(plugin): quote CLAUDE_PLUGIN_ROOT in hooks for paths with spaces (closes #420)
• #441 feat(store,cli): cascade DeleteProject + engram delete session|prompt|project (closes #218, #219)
• #439 fix(pi): show actionable status for ambiguous project errors (closes #384)
• #436 docs: bring docs up to date with recently merged features (closes #435)
• #434 feat(cli): add engram delete command to remove observations (closes #209)
• #433 feat(tui): add clipboard copy keybinding via OSC 52 (closes #141)
• #432 fix(pi): pin npmCommand to stable mise node spec (closes #385)
• #431 feat(cloud): wildcard support for ENGRAM_CLOUD_ALLOWED_PROJECTS (closes #260)
• #430 fix(cloud): fall back to cloud.json token when ENGRAM_CLOUD_TOKEN is unset (closes #343)
• #429 security(server): add optional local auth for destructive HTTP endpoints (closes #200)
• #428 fix(store): handle global scope in normalizeScope (closes #122)
• #427 fix(store): use case-insensitive project filter for legacy mixed-case data (closes #146)
• #426 fix(security): replace timing-unsafe token comparisons with hmac.Equal (closes #350)
• #425 fix(mcp): skip project filter for scope=personal with no explicit project (closes #391)
• #424 fix(mcp): harden handleSessionSummary process override and empty-content guard (closes #403, #413, #393)
• #423 fix(obsidian): prevent path traversal in exporter file path construction (closes #180)
• #410 docs: clarify version stamp PATH gotcha and Claude Code schema error (closes #67)
• #408 feat(mcp): add all_projects flag to mem_search (closes #303)
• #346 feat(timeutil): support configurable timezone for timestamp display (closes #169)
• #337 feat(cloud): detect dead local daemon in cloud status and document launchd unit (closes #279)

v1.15.15

Engram v1.15.15 is a single-fix hotfix release: the legacy cloud-upgrade evaluator now correctly handles relation entities, unblocking cloud upgrade for projects that hit the regression introduced in #379.

Highlights

• Legacy relation upsert payloads are repaired during cloud upgrade: cloud upgrade no longer blocks on entity=relation op=upsert mutations that lacked the fields added by #379. The legacy evaluator whitelists SyncEntityRelation and applies the full repair path before forwarding mutations to the cloud server.

Contribution highlights

Thanks to the report and the precise reproduction that drove this fix:

• #383 came from a user blocked on engram cloud upgrade doctor and engram sync --cloud after upgrading to v1.15.13. The report pointed directly at the missing SyncEntityRelation case in the legacy evaluator and made the fix surgical.

Fixes included

• evaluateCloudUpgradeLegacyMutationTx whitelists SyncEntityRelation/upsert and adds the full case SyncEntityRelation: repair branch, matching the path already used by the chunk canonicalizer and cloud server.

Changelog

• 7af10b9 fix(store): repair legacy relation upsert payloads (closes #383)

v1.15.14

Engram v1.15.14 is a small operational release for cloud operators and Pi users: cloud push limits are now configurable for larger self-hosted projects, and the Pi docs now clearly separate native Engram memory tools from Pi's global MCP gateway.

Highlights

• Cloud push payload limit is configurable: self-hosted cloud servers can set ENGRAM_CLOUD_MAX_PUSH_BYTES when a legitimate project outgrows the default 8 MiB request limit.
• Both cloud push paths respect the same limit: chunk push and mutation push now share the configured max body size and preserve the 8 MiB default when unset.
• Oversized mutation pushes fail clearly: mutation push now returns a structured 413 response instead of relying on an opaque hardcoded limit.
• Pi MCP status docs are clearer: Pi-native Engram mem_* tools use the gentle-engram HTTP path, while error MCP: 0/N servers is Pi's global MCP gateway health and may involve third-party MCP servers such as Notion.
• Pi setup guidance preserves MCP integrations: docs now tell users to keep pi-mcp-adapter when they rely on Notion or direct MCP flows, while troubleshooting missing native Engram tools through gentle-engram first.

Contribution highlights

Thanks to the issue reports and review pressure that shaped this release:

• #316 drove the configurable cloud push payload limit for large self-hosted projects.
• #396 came from real Pi usage where Engram memory worked while the Pi footer showed error MCP: 0/3 servers; the docs now explain that split without telling users to remove pi-mcp-adapter.
• Judgment Day review caught misleading Pi troubleshooting wording before merge, especially around preserving Notion/direct MCP flows.

Pi companion notes

No new gentle-engram npm package was published in this release. The current Pi companion remains gentle-engram@0.1.7; this release updates the main Engram binary/docs and keeps Pi setup guidance aligned with that package.

Fixes included

• ENGRAM_CLOUD_MAX_PUSH_BYTES is parsed from cloud config, validated with safe bounds, and passed into server runtime.
• Cloud chunk and mutation push handlers use the configured max payload size.
• CLI help, cloud docs, architecture docs, and changelog now mention the new cloud limit.
• Pi docs now distinguish native HTTP memory tools from the MCP gateway and add troubleshooting for error MCP: 0/N servers while mem_* still works.

Changelog

• #395 fix(cloud): make push payload limit configurable
• #397 docs(pi): clarify MCP gateway status

gentle-engram v0.1.7

What's fixed

• Allow Pi-native mem_session_summary to accept an explicit project fallback when automatic project detection is unavailable.
• Fall back to nearest local .engram/config.json when an older running Engram server does not support /project/current.
• Surface a clearer version-mismatch diagnostic for /project/current 404s.
• Update engram setup pi, docs, and package metadata to install gentle-engram@0.1.7.

Validation

• cd plugin/pi && npm test
• cd plugin/pi && npm pack --dry-run
• go test ./internal/setup

Published to npm via GitHub Actions with provenance.

gentle-engram v0.1.6

gentle-engram v0.1.6

• Auto-enable Engram core Cloud autosync for Pi-launched/configured Engram processes when token+server are configured.
• Preserve explicit ENGRAM_CLOUD_AUTOSYNC overrides and keep project enrollment/pause enforcement in Engram core/server policy.
• Safely migrate only the known old generated Pi MCP launcher while preserving custom MCP configs.
• Add tests for child env gating, executable MCP launcher parity, and safe init migration.

v1.15.13

Changelog

• 6976950 feat(pi): add native Engram memory tools

v1.15.12

Engram v1.15.12 focuses on agent reliability: Pi setup is now first-class, MCP project selection is safer for long-lived hosts, cloud sync validates persistence before acking, and plugin memory flows survive compaction with clearer UI.

Highlights

• Pi setup is now one command: engram setup pi installs gentle-engram, installs pi-mcp-adapter, and writes Pi MCP config without overwriting an existing Engram server.
• MCP project overrides work for hosted agents: engram mcp --project <name> and ENGRAM_PROJECT are trusted process-level defaults for current-project, read, and write resolution while keeping explicit per-call validation strict.
• Autosync acks are safer: Engram now validates cloud accepted_seqs before acking local mutations, preventing local data from being marked synced when the server did not confirm the whole batch.
• Claude/OpenCode save nudges are restored: compatibility endpoints for latest observations and session lookup now match existing plugin hook behavior.
• Cloud relation mutations unblock sync: relation/upsert mutations are accepted, canonicalized, validated, and retained in cloud mutation chunks.

Contribution highlights

Thanks to the issue reports that shaped this release:

• @yvolchkov and @ardelperal helped tighten the setup path with engram setup pi and the OpenCode auto-start copy.
• @deliriumlabs flagged the broken save-nudge hook, which led to the restored observation/session compatibility endpoints.
• @AshrafAKRahman reported the mem_save content-loss bug, now fixed with stricter validation and backward-compatible payload handling.
• @alexandervazquez98 and @quirozino surfaced the autosync ack safety gap, now guarded by accepted-seq validation.
• @ricardoarz-dev, @aleka, and @samuelcooke-cpu drove the MCP project override work for long-lived agent hosts.
• @parraletz helped unblock cloud relation mutation sync, with @IrrealV and @forNerzul surfacing adjacent repair/local-sync follow-up areas.
• @gabrielizalo helped identify an external OpenCode TUI plugin failure mode and clarify the recovery path.

Pi companion updates

• Published gentle-engram@0.1.4.
• Added compact memory tool chrome for Pi memory calls.
• Added private-block redaction and compaction recovery helpers.
• Kept Engram-specific memory UI in gentle-engram, not in core Pi.

Fixes included

• mem_save now preserves observation content and accepts the backward-compatible observation alias while rejecting empty saves.
• Claude Code plugin context no longer includes bilingual trigger noise.
• OpenCode setup no longer tells users to manually run engram serve &; the plugin auto-starts the HTTP server when needed.

Changelog

• #372 chore(pi): release v0.1.4
• #370 feat(pi): add compact memory tool chrome
• #368 feat(pi): add compaction recovery redaction
• #376 feat(setup): add pi integration setup
• #374 fix(mcp): preserve mem_save observation content
• #378 fix(mcp): trust process project override
• #373 fix(plugin): remove bilingual triggers from claude-code session context
• #377 fix(server): add observations compatibility endpoint
• #379 fix(sync): accept cloud relation mutations
• #375 fix(sync): validate autosync accepted seqs

v1.15.11

Changelog

• 7149cc1 chore: add gentle-engram package gallery logo
• 3253210 chore: update go toolchain to 1.25.10
• f74d564 docs(pi): improve gentle-engram package marketing
• 42160c7 docs(readme): highlight Pi package
• 3702165 feat(plugin): add Pi Engram package
• 1fac309 fix(plugin): align Pi package peer dependency
• e433cfb fix(plugin): align Pi project detection
• d96555f fix(plugin): rename Pi package to gentle-engram

v1.15.10

Summary

• Hardened MCP ambiguous-project recovery so agents can no longer claim user_selected_after_ambiguous_project without a recovery token issued by Engram.
• Added short-lived recovery tokens to ambiguous_project errors for mem_save and mem_save_prompt.
• Added regression coverage for missing, invalid, stale, wrong-project, and valid recovery-token flows.

Details

When project detection is ambiguous, Engram now returns a recovery_token and token_ttl_seconds. A retry using project_choice_reason=user_selected_after_ambiguous_project must include that token, bound to the original ambiguous context and selected project.

This makes accidental or synthetic project-choice claims fail deterministically instead of persisting memory under the wrong project.