v1.16.3

Changelog

• 59d4b64 Merge branch 'main' into fix/local-sync-relations
• d38bbab Merge pull request #489 from Gentleman-Programming/fix/local-sync-relations
• 68a19f8 fix(plugin): debounce save-nudge to stop per-message repeats
• f4cc070 fix(sync): include memory_relations in local chunk sync

v1.16.2

Highlights

• Adds observation lifecycle state derived from review_after.
• Adds mem_review for listing memories that need review and marking one reviewed.
• Adds Pi-native review support through the Engram HTTP server for gentle-engram.
• Pins critical observations in context so important memory is harder to bury.

Changes

Memory lifecycle

• Surface computed observation state as active or needs_review.
• Add store-level review queries and local-only review reset behavior.
• Expose lifecycle metadata through MCP save/search responses.

MCP, HTTP, and Pi

• Add MCP mem_review for direct agent integrations.
• Add HTTP review routes used by gentle-engram Pi-native tools.
• Add compact Pi chrome for review list and mark-reviewed flows.

TUI and docs

• Show lifecycle state in the TUI list/detail views.
• Document mem_review, lifecycle metadata, HTTP routes, and Pi setup behavior.

Install

brew upgrade engram

Compatibility notes

• mark_reviewed resets the local review cycle only; lifecycle review timestamps are not synced yet.
• Pi users should pair this with gentle-engram@0.1.8 for native mem_review support.

gentle-engram v0.1.8

Highlights

• Adds Pi-native mem_review support for gentle-engram.
• Adds compact Pi tool chrome for listing memories that need review and marking one reviewed.
• Publishes the package as gentle-engram@0.1.8.

Install

pi install npm:gentle-engram@0.1.8

Notes

• Requires an Engram binary/server with the new review HTTP routes from v1.16.2.
• mark_reviewed resets the local review cycle only; lifecycle review timestamps are not synced yet.

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