Skip to content

v2.0.0-rc.5

Pre-release
Pre-release

Choose a tag to compare

View all tags
@github-actions github-actions released this 05 Sep 04:30
· 53 commits to main since this release
v2.0.0-rc.5
e108c2f
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Engram v2.0.0-rc.5: Safer storage, session boundaries, and recovery

What's New

This community-testing refresh is 44 commits ahead of v2.0.0-rc.4. It hardens concurrent local SQLite startup, makes session ownership and ended-session handling fail closed, improves cloud-sync recovery and diagnostics, and corrects several MCP, agent-integration, and HTTP contracts.

This is a prerelease for testing and feedback. Do not treat it as a stable production release. Keep a known-good installation available.

Changes

Storage and session integrity

  • Concurrent SQLite startup is more defensive: persistent WAL configuration, version-gated migrations, and an inter-process migration lock prevent concurrent startup from rerunning destructive migration work. Engram also refuses a disappearing SQLite sidecar instead of accepting an unstable database state. (#613, #954)
  • Project-owned sessions fail closed on reassignment: writes that would move an existing project-owned session to another project are rejected before observation, prompt, session, or sync mutations are written. Explicit shared sessions remain usable across projects, while ambiguous legacy ownership is rejected with recovery guidance. (#712, #1006)
  • Ended session IDs are refused honestly: mem_session_start no longer reports success for an already-ended session while leaving it closed. The refusal preserves the existing session and sync state and tells the caller to choose a new ID. (#972, #999)
  • Search and relation handling are more consistent: prompt FTS keeps the FTS table as the driving query table, search-preview truncation counts runes rather than bytes, and not_conflict verdicts persist so resolved pairs are not repeatedly resurfaced. (#977, #856, #491)

Cloud sync and recovery

  • Sync wrappers fail visibly: the PowerShell wrapper preserves Engram exit status, names terminal project results, and fails when it cannot launch Engram instead of reporting a misleading success. (#714)
  • Recovery and compatibility paths are stronger: mutation pushes are normalized before storage, pulled tombstone timestamps are preserved, and a project can be remirrored after recovery. (#948, #961, #985)
  • Policy failures are actionable: denied projects are named without exposing allowlist contents, and policy-forbidden sync failures retain deterministic, project-scoped guidance. (#969, #982)

Agent and MCP integrations

  • Claude Code hook enforcement survives SessionStart and supports both direct-MCP and plugin MCP tool prefixes. Setup also handles Homebrew paths, rejects non-regular MCP configuration files, and resolves symlinked tools in isolated hook paths. (#654, #713, #986, #996)
  • Pi recovery is more robust: Pi can recover its local server after a mid-session loss, preserves compaction recovery integrity, and restores passive capture for standard tools. (#964, #989, #970)
  • MCP contracts are clearer: the baseline is portable and compatible, global stats work without a project, and tool descriptions document global-scope behavior. (#943, #983, #874)

Server and performance

  • GET /health reports the configured release version rather than a stale hard-coded value. (#946, #1000)
  • Empty collection endpoints return [], not null, while retaining HTTP 200 for successful empty results. (#956, #1001)
  • Store-search performance now has a regression ratchet: deterministic benchmarks, a reviewed baseline, and a main-branch CI check make regressions visible. (#897, #1002)

Installing it

Use a prebuilt release asset for RC validation. go install builds report dev rather than the release version.

amd64 means Intel/AMD x86_64. Replace it with arm64 where that asset is available.

Linux:

FILE="engram_2.0.0-rc.5_linux_amd64.tar.gz"
BASE="https://github.com/Gentleman-Programming/engram/releases/download/v2.0.0-rc.5"

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.5_darwin_amd64.tar.gz"
BASE="https://github.com/Gentleman-Programming/engram/releases/download/v2.0.0-rc.5"

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.5_windows_amd64.zip" # Replace amd64 with arm64 on ARM64.
$base = "https://github.com/Gentleman-Programming/engram/releases/download/v2.0.0-rc.5"
$work = Join-Path ([System.IO.Path]::GetTempPath()) "engram-2.0.0-rc.5"
$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. Use a fresh or copied data directory and start multiple Engram processes at the same time. Confirm startup completes and engram doctor reports a healthy store.
  2. For a project-owned session, attempt a write under a different project. Confirm Engram refuses before writing data or a sync mutation. Confirm explicitly shared sessions still work where cross-project attribution is intended.
  3. End a session, then attempt mem_session_start with the same ID. Confirm the call returns structured refusal and no later save is silently attributed to a fallback session.
  4. If you use Cloud sync, exercise a policy-forbidden project and a remirror recovery. Confirm the diagnostic names the affected project and gives a usable recovery path.
  5. Check GET /health on a release build and empty collection endpoints. Confirm the version is 2.0.0-rc.5 and empty collections encode as [].
  6. If you use Claude Code or Pi, restart an existing session and verify hooks, MCP tools, passive capture, and recovery behavior still work.

Please include your OS, agent/client, engram version, the exact command, and the relevant result or error in reports: open an issue.

Validation

Distribution

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

Cloud image:

docker pull ghcr.io/gentleman-programming/engram:v2.0.0-rc.5
Assets 9
Loading