engram v0.2.0-beta.2

engram v0.2.0-beta.2 Release Notes

v0.2.0-beta.2 is the first beta candidate focused on installability and first-run onboarding after
the v0.2.0-beta.1 review.

What Changed

• Added engram setup, a guided dry-run-first setup path for Claude Code, Codex, and Cursor.
• Added first-orient knowledge onboarding: when no documents are indexed yet, the agent is told to
  ask which existing docs, runbooks, notes, or knowledge folders should be ingested.
• Added engram warmup embeddings for explicit local embedding-cache preparation before first use
  or offline work.
• Improved cold embedding-cache warnings, RocksDB lock recovery messages, and daemon startup
  failure diagnostics.
• Prepared Homebrew packaging for macOS Apple Silicon beta installs.
• Expanded README, MCP setup, security, and contribution guidance for an open-source beta.

Install

Homebrew is the preferred macOS Apple Silicon path once the tap is published:

brew tap ymeiri/engram
brew install engram
engram init
engram setup

Release tarballs remain available from GitHub Releases for users who do not use Homebrew.

First Run

1. Run engram warmup embeddings if you want to prepare the local embedding model cache up front.
2. Run engram init.
3. Run engram setup --agent <claude-code|codex|cursor> and review the dry-run.
4. Re-run setup with --write after approving the planned files.
5. Restart the agent and ask it to run orient.
6. If no documents are indexed yet, the orient packet asks the agent to collect approved knowledge
   paths from the user before ingestion.

Known Limitations

• Homebrew packaging is scoped to macOS Apple Silicon for this beta.
• Setup writes are approval-gated. Dry-run is the default.
• Engram stores data locally under ~/.engram/ unless a project-specific or explicit data path is
  used.
• The first embedding use may download all-MiniLM-L6-v2 from Hugging Face unless the cache has
  already been warmed.

Engram v0.2.0-beta.1

Engram v0.2.0-beta.1 Release Notes

Release date: TBD
Status: Pre-release candidate

Supported Beta Path

This beta is scoped to the local/Codex Brain Loop path:

• local engram serve MCP operation,
• lean orient with current-plan retrieval, trace/cursor fields, used-memory candidate IDs, and
  obligation summary,
• generated Memory OS vault inspection,
• review-gated M6 inventory/export/status paths,
• scoped obligations doctor and advisory harness lifecycle guidance,
• preserved approval boundaries for destructive or broad writes.

Deferred From This Beta

The following remain production-hardening or host-parity gates, not blockers for this beta:

• native Claude prompt-bearing proof,
• effective-hook visibility proof,
• live Claude host-label proof,
• full multi-host parity,
• direct legacy deprecation/deletion,
• broad lifecycle cleanup or broad lint apply_safe,
• exhaustive telemetry completeness,
• OIDC/Vault/native-Claude auth/debugging edge cases,
• new feature work.

T306 resolved the current Rustdoc warning set for this candidate. Future Rustdoc polish remains a
production-hardening activity, not an initial-beta blocker.

Release Gate

Before tagging this beta, the candidate commit must have normal exact-head hosted CI proof, or an
explicit release-owner decision accepting local validation as a fallback while hosted Actions is
externally account-blocked. The expected gate remains:

• exact-head CI green for Format, Docs, Check, Clippy, and Test,
• cargo fmt --all --check passing locally,
• a focused local/Codex smoke confirming current source-rendered harness guidance,
• canonical generated vault status count-aligned,
• obligations(action=doctor, project=engram, cwd=/Users/yuval.meiri/projects/engram) clean,
• a refreshed installed runtime/adapters check.

The local fallback command is ./scripts/local-ci.sh. It mirrors the exact-head local validation
sequence used for this candidate: whitespace diff check, rustfmt, check, clippy, tests with CI-like
incremental/debug settings, and docs.

The local pre-publish packaging command is ./scripts/package-release.sh. It builds the release
binary, verifies that engram --version matches the workspace package version, and writes a tarball
plus SHA-256 checksum under ignored dist/. The archive includes MANIFEST.json with the package
version, host triple, git head, tracked-change state, Cargo.lock hash, and payload file hashes.

The local install-smoke command is ./scripts/package-install-smoke.sh. It builds the package,
verifies the checksum, extracts the archive, verifies MANIFEST.json, installs the packaged binary
into a temporary prefix, confirms PATH resolution and engram --version, starts the packaged
binary with engram serve --http --memory, and verifies /health. The smoke starts the server
from the temporary install workspace and sets ENGRAM_EMBED_CACHE_DIR explicitly, so package
validation no longer relies on the repository root as the process cwd for embedding model cache
discovery.

The post-publish install verifier is ./scripts/verify-published-release-install.sh. After a
release is published, it downloads the expected archive and checksum from GitHub, then runs the
same package install smoke against those downloaded assets with SKIP_PACKAGE_BUILD=1. It also
supports --asset-dir <path> for pre-publish rehearsal against a local release-asset mirror. The
verifier is evidence-only: it does not create a release, upload assets, mark PR #3 ready, merge,
tag, publish, accept the hosted-CI fallback, or mutate release state.

The hosted-CI pre-step blocker verifier is
./scripts/verify-hosted-ci-prestep-blocker.sh <run-id>. It is a read-only GitHub CLI check that
fails unless the run targets the expected head, is the CI pull-request workflow, contains exactly
the expected release-gate jobs, and every job completed with conclusion failure and steps=[].
It is evidence for release-owner waiver review only; it does not accept the waiver or change PR
state.
Add --json to emit machine-readable success evidence for the verified run. Failed checks remain
stderr-only and non-zero.

The beta release-gate evidence command is
./scripts/beta-release-gate-report.sh --hosted-run <run-id>. It verifies the branch is synced,
the tracked tree is clean, PR #3 points at the local head, hosted CI is either green or the
pre-step blocker is verified, and, unless --quick or skip flags are used, the local CI and
package/install smoke commands pass on the same head. It is evidence for release-owner review only;
it does not accept the waiver, mark the PR ready, merge, tag, publish, or change release scope.
Add --json to emit the final evidence object on stdout for automation; validation logs are routed
to stderr in JSON mode so stdout remains parseable. When hosted CI is accepted only as a verified
pre-step blocker candidate, the JSON object embeds the verifier's structured proof under
hosted_ci.verifier; a green hosted-CI path leaves that field null. The same report also emits
release_gate_state, ready_for_release_owner_review,
hosted_ci_fallback_decision_required, and remaining_release_actions so automation can
distinguish full exact-head evidence from quick/incomplete evidence without performing release
actions.

Release-Owner Signoff Checklist

The remaining beta decision is explicit release-owner signoff, not additional product scope. Before
tagging v0.2.0-beta.1, the release owner should confirm:

1. ./scripts/local-ci.sh on the signed-off head is accepted as the local CI-equivalent beta gate
   while hosted GitHub Actions is externally blocked before workflow-step execution.
2. ./scripts/package-install-smoke.sh on the same head is accepted as package/checksum/install
   and packaged HTTP /health proof.
3. The current hosted run can be waived for this beta only if it failed before workflow-step
   execution with steps=[], matching the external billing/spending-limit blocker rather than a
   source or packaging failure. Verify the run with
   ./scripts/verify-hosted-ci-prestep-blocker.sh <run-id> before signoff.
4. ./scripts/beta-release-gate-report.sh --hosted-run <run-id> has been run on the signed-off
   head, or the equivalent branch/PR/CI/local/package evidence has been reviewed manually.
5. The known beta limitations listed in this file are accepted: native Claude prompt-bearing
   behavior, effective-hook visibility, live Claude host labels, full multi-host parity, direct
   legacy deprecation/deletion, broad lifecycle cleanup or broad lint apply_safe, M6 write-apply
   expansion, and exhaustive telemetry/auth/ops/performance/cross-platform hardening remain
   deferred.
6. After signoff, PR #3 may be marked ready, merged, tagged as v0.2.0-beta.1, published with the
   release archive and checksum, and verified with
   ./scripts/verify-published-release-install.sh.

Beta Install Quickstart

For source installs, build and place the binary on PATH before running engram init or
engram serve:

git clone https://github.com/ymeiri/engram.git
cd engram
cargo build --release

mkdir -p "$HOME/.local/bin"
install -m 755 ./target/release/engram "$HOME/.local/bin/engram"
export PATH="$HOME/.local/bin:$PATH"
engram --version

After v0.2.0-beta.1 is published, install the macOS arm64 release artifact with checksum
verification:

version=0.2.0-beta.1
archive="engram-${version}-aarch64-apple-darwin.tar.gz"

curl -LO "https://github.com/ymeiri/engram/releases/download/v${version}/${archive}"
curl -LO "https://github.com/ymeiri/engram/releases/download/v${version}/${archive}.sha256"
shasum -a 256 -c "${archive}.sha256"
tar -xzf "${archive}"

mkdir -p "$HOME/.local/bin"
install -m 755 "engram-${version}-aarch64-apple-darwin/engram" "$HOME/.local/bin/engram"
export PATH="$HOME/.local/bin:$PATH"
engram --version

The expected version output for this beta is:

engram 0.2.0-beta.1

Recent phase-1 local evidence is strong: T317 validated PR #3 head
78f14d0bebd980070a4fcb8d1f259be47517c704 with cargo fmt --all --check,
git diff --check, cargo check --all-targets,
cargo clippy --all-targets -- -D warnings, cargo test --all-targets --jobs 1, and
cargo doc --no-deps. T318 reran hosted GitHub Actions run 27091138284, creating attempt 2 on
that same head, but all five jobs failed before runner assignment with zero steps, runner_id=0,
and billing/spending-limit annotations. That external account gate does not contradict the local
validation, but the normal exact-head hosted-CI release proof is still missing until Actions can run
on the head intended for release or the release owner explicitly accepts the local fallback.

T329 advanced the draft PR #3 head to fe46d0a73d39e3309b149703dda4c108da91fc02 through
docs-only release evidence plus exact lifecycle archive records. Local validation for that head
passed git diff --check, cargo fmt --all --check, cargo check --all-targets, canonical vault
compile with zero skipped files, and cached diff checks. Hosted GitHub Actions run 27096981016
on the same head again failed before workflow steps ran with the same billing/spending-limit
annotations. Treat this as the current hosted-CI blocker.

Fresh AI Council review after T329 places the initial local/Codex beta at about 88-92% ready while
hosted CI is externally blocked and local fallback evidence is accepted, or about 95% ready once
GitHub Actions billing is fixed and exact-head checks pass or the release owner explicitly accepts
local validation as the beta fallback. T330 also records a current-head local/Codex smoke with lean
orient, obligations doctor, vault status/compile, lint-sample evidence, and bounded M6
inventory/temp-export/status/dry-run-apply evidence. This is not a production/GA readiness claim;
production readiness remains materially lower because native Claude proof, effective hooks,
host-label proof, host parity...

v0.1.0 — Initial Public Release

engram v0.1.0

Persistent memory for AI coding agents. One binary. Local and private.

Highlights

• 7 knowledge layers: entities, sessions, documents, tool intelligence, session coordination, knowledge management, work management
• 21 MCP tools accessible from Claude Code, Cursor, Windsurf, or any MCP-compatible agent
• Single Rust binary with embedded SurrealDB — no external services required
• Local ONNX embeddings via fastembed — no API calls, total privacy
• Multi-session support with automatic daemon and conflict detection
• Full CLI for manual interaction with all layers

Quick Start

git clone https://github.com/ymeiri/engram.git
cd engram && cargo build --release
./target/release/engram init
./target/release/engram serve

See the README for MCP client configuration and the Setup Guide for Claude Code, Cursor, and Windsurf.

What's Included

Layer	Capability
Entity Knowledge	Graph of repos, tools, services, concepts with relationships and observations
Session History	Decisions, events, rationale tracking across coding sessions
Document Search	Semantic similarity search over indexed markdown documents
Tool Intelligence	Usage pattern learning and success-rate-based recommendations
Session Coordination	Parallel session awareness and file/component conflict detection
Knowledge Management	Document registry with version detection and deduplication
Work Management	Projects, tasks, PRs with entity connections and scoped observations

Requirements

• Rust 1.80+ (for building from source)
• macOS or Linux

Pre-built binaries coming in a future release.