v2.0.0-rc.4 — Safer sync, search, and agent integrations

Engram v2.0.0-rc.4: Safer Sync, Search, and Agent Integrations

What's New

This community-testing refresh is 23 commits ahead of v2.0.0-rc.3. It makes imports and autosync safer around stale, malformed, and deleted data; adds CJK substring search; fixes several OpenCode, Codex, and Pi integration paths; and makes the v2 Go installation path valid.

Earlier release candidates remain unchanged.

Changes

Storage, import, and sync

• CJK and short-term search: observation and prompt search now uses a trigram FTS5 contract for CJK substring matching, repairs legacy or incomplete indexes transactionally, and retains bounded escaped fallbacks for one- and two-character searches. (#140, #924)
• Timestamp-aware imports: imports now apply last-write-wins ordering by sync identity, so stale snapshots cannot overwrite newer local observations or resurrect deleted observations and prompts. Import results distinguish imported, updated, and stale records. (#244, #917)
• Safe source-row repair: doctor repair detects active observations with missing required source fields and previews recoverable title repairs by default. Applied repair is transactional, backed up, and idempotent. (#629, #919)
• Autosync keeps healthy projects moving: mutations with absent or invalid project identities are quarantined locally with actionable evidence instead of reaching transport and blocking valid project groups. (#742, #920)
• Deletion and repair correctness: hard project deletion preserves sessions still referenced by another project, while enrolled-project repair detects missing DELETE mutations for soft-deleted observations and prompt tombstones more efficiently. (#769, #916, #858, #912)

Agent and MCP integrations

• MCP guidance matches the active profile: server instructions are now built from the registered tool allowlist, so agents are not directed to unavailable tools. Plugin hooks and skills use the same tool profile. (#711, #878)
• Deterministic unknown-session recovery: writes with an unregistered explicit session_id still fail strictly, but errors now include structured invalid_session_id and retry_without_session_id fields. Tool schemas tell callers to use IDs returned by mem_session_start rather than inventing them. (#683, #906)
• OpenCode session attribution and setup guidance: MCP-qualified write tools resolve to the authoritative parent session, and setup distinguishes written configuration, MCP connectivity, and active-agent tool visibility without claiming Engram can inspect OpenCode's runtime surface. (#925, #929, #869, #923)
• Codex on native Windows: the SubagentStop hook now always emits valid JSON on stdout and keeps diagnostics on stderr. (#804, #915)
• Pi child-process compatibility: gentle-engram now treats @earendil-works/pi-tui as an optional peer dependency, preventing npm from installing a conflicting older copy that could crash Pi child processes. (#853, #876)

Installation and runtime behavior

• Valid v2 Go installs: v2 releases use the Go module path github.com/Gentleman-Programming/engram/v2, so go install can resolve v2 tags correctly. Use go install github.com/Gentleman-Programming/engram/v2/cmd/engram@v2.0.0-rc.4; v1 tags retain the original unversioned path. (#927, #928)
• Optional update checks: set ENGRAM_NO_UPDATE_CHECK=1 (also true, yes, or on) to suppress release-update requests, including in offline workflows. Version and help commands no longer make those requests. (#532, #922)

Installation

Preferred: pinned Go install

go install github.com/Gentleman-Programming/engram/v2/cmd/engram@v2.0.0-rc.4
engram version

Prebuilt binaries

amd64 means Intel/AMD x86_64. Use arm64 for ARM64 systems by replacing amd64 in the asset name where applicable.

Linux:

FILE="engram_2.0.0-rc.4_linux_amd64.tar.gz" # amd64 = x86_64; use arm64 for ARM64
BASE="https://github.com/Gentleman-Programming/engram/releases/download/v2.0.0-rc.4"
curl -fLO "$BASE/$FILE"
curl -fLO "$BASE/checksums.txt"
grep -F "  $FILE" checksums.txt | sha256sum -c -
tar -xzf "$FILE"
mkdir -p "$HOME/.local/bin"
install -m 0755 engram "$HOME/.local/bin/engram"
"$HOME/.local/bin/engram" version

macOS:

FILE="engram_2.0.0-rc.4_darwin_amd64.tar.gz" # amd64 = Intel; use arm64 for Apple Silicon
BASE="https://github.com/Gentleman-Programming/engram/releases/download/v2.0.0-rc.4"
curl -fLO "$BASE/$FILE"
curl -fLO "$BASE/checksums.txt"
grep -F "  $FILE" checksums.txt | shasum -a 256 -c -
tar -xzf "$FILE"
mkdir -p "$HOME/.local/bin"
install -m 0755 engram "$HOME/.local/bin/engram"
"$HOME/.local/bin/engram" version

Windows PowerShell:

$asset = "engram_2.0.0-rc.4_windows_amd64.zip" # Replace amd64 with arm64 on ARM64.
$base = "https://github.com/Gentleman-Programming/engram/releases/download/v2.0.0-rc.4"
$work = Join-Path ([System.IO.Path]::GetTempPath()) "engram-2.0.0-rc.4"
$installDir = Join-Path $env:LOCALAPPDATA "Engram\bin"
New-Item -ItemType Directory -Force -Path $work, $installDir | Out-Null
Invoke-WebRequest "$base/$asset" -OutFile (Join-Path $work $asset)
Invoke-WebRequest "$base/checksums.txt" -OutFile (Join-Path $work "checksums.txt")
$line = Get-Content (Join-Path $work "checksums.txt") | Where-Object { $_ -match ("  " + [regex]::Escape($asset) + "$") }
$expected = ($line -split "\s+")[0].ToLowerInvariant()
$actual = (Get-FileHash (Join-Path $work $asset) -Algorithm SHA256).Hash.ToLowerInvariant()
if (-not $expected -or $actual -ne $expected) { throw "Checksum verification failed for $asset" }
Expand-Archive -Force -Path (Join-Path $work $asset) -DestinationPath $installDir
if ($env:Path -notlike "*$installDir*") { $env:Path = "$installDir;$env:Path" }
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if (($userPath -split ";" | Where-Object { $_ -eq $installDir }).Count -eq 0) {
  $newUserPath = if ([string]::IsNullOrWhiteSpace($userPath)) { $installDir } else { "$($userPath.TrimEnd(';'));$installDir" }
  [Environment]::SetEnvironmentVariable("Path", $newUserPath, "User")
}
& (Join-Path $installDir "engram.exe") version

Community Testing

1. Install the v2 candidate through the /v2 module path and confirm engram version reports engram 2.0.0-rc.4.
2. Search observations and prompts containing CJK text, then try one- and two-character queries.
3. Import an older export over newer local data and confirm newer observations, deletions, and prompt tombstones remain intact.
4. If you use cloud sync, confirm malformed legacy queue rows are reported locally while valid projects continue syncing.
5. Call a write tool with an invented session_id, confirm the structured recovery fields are present, then retry without the ID and verify the write succeeds under normal project resolution.
6. In OpenCode, restart after setup, create a new agent session, and verify Engram MCP tools are visible and qualified writes persist to the parent session.
7. If you use Pi, exercise child-agent startup and report any remaining dependency-resolution failure.

Please include your OS, agent/client, engram version, and the exact command or repair/sync result in reports.

Validation

• Source: 32b903ab4b1f9cb58f21aae3bb068cf7f5d60068, 23 commits after v2.0.0-rc.3.
• CI: run 33679272217 passed Unit Tests, E2E Tests, and Plugin Tests for this exact commit.

Distribution

This prerelease does not update Homebrew. Download a platform asset below and verify it against checksums.txt before running it.