Gentleman-Programming/engram v3.7.0 on GitHub

Engram v3.7.0

A minor release that adds organization-scoped memory, a background daemon for engram serve, and a faster store and sync path. It pairs Engram with gentle-engram 0.7.0, the Pi companion package.

Highlights

Org-scoped memory: observations can carry an optional org field that groups projects by organization. It is set from the repository's .engram/config.json grouping label and is carried through every write path (insert, topic-key revision, import, upsert and rescued-mutation journaling). org is returned in search results and previews and can filter FTS, LIKE and topic-key lookups. The MCP tools mem_save, mem_search, mem_current_project, mem_list_projects and mem_session_summary accept it, the Obsidian exporter takes an --org filter, and the Pi-native tool schema matches the MCP schema. Content-hash deduplication includes org, so identical content in different organizations is kept separately. The field is optional everywhere: existing rows, imports and clients without it behave as before. Thanks @Deyvis17GY (#1151).
GET /search org filter: the HTTP endpoint now reads a trimmed org query parameter. A blank or missing value keeps unfiltered results, matching /projects and MCP mem_search. The Pi-native mem_search forwards org to the server instead of only declaring it (#2327).
Daemon mode: new docker-style lifecycle commands: engram run -d (detached start that prints the PID and port), engram ps, engram stop (graceful, then forced), engram logs [-f] and engram restart. engram serve now exits with a non-zero code when the same instance already owns the port, instead of exiting 0 in a silent crash loop. Thanks @carolitascl (#2229).
Server version skew: engram cloud status and an identity-confirmed engram ps show the running server version next to the installed CLI version and report a pending restart when they differ. Engram does not restart the server automatically (#2311). The upgrade guide now explains how to verify the running server version (#2251).
Claude Code memory-write opt-in: engram setup claude-code --allow-memory-writes grants twelve fixed memory tools under both MCP prefixes for unattended setups. Delete and project-merge tools are excluded, and the default prompt-based setup is unchanged (#2314).
Pi companion 0.7.0: engram setup pi now pins npm:gentle-engram@0.7.0. A managed npm:gentle-engram@0.6.0 pin is replaced instead of being kept alongside the new version, and pi-engram init upgrades it the same way. Earlier managed migrations, custom/local entries, unrelated settings and MCP configuration are preserved (#2329). gentle-engram 0.7.0 is published under the npm candidate dist-tag and promoted to latest by the maintainer: published to npm under the candidate dist-tag (publish run); promotion to latest follows the maintainer review of the published pair.
Obsidian docs: the Obsidian Brain guide now uses the stable engram command; engram-beta is no longer required. Thanks @matheo (#2007, closes #2306).
Contribution governance: PR checks accept Refs #N as an approved, non-closing issue reference alongside Closes/Fixes/Resolves, so partial PRs can link an umbrella issue without closing it. status:approved is still enforced on every referenced issue. Thanks @Reaan06 (#1617).
Fixes: sync preserves local edits behind unrelated chunk timestamps (#2309); engram doctor detects invalid pending cloud journal projects (#2308); migrate-copy admits the v3.6.0 catalog (#2252); Claude Code no longer captures desktop synthetic prompts (#2246), avoids unnecessary session argument rewrites (#2248), and preserves resume ownership while reporting registration failures (#2310).

Thanks to the community contributors in this release: @Deyvis17GY, @carolitascl, @matheo and @Reaan06.

Maintenance

Performance: store startup does less redundant work: column introspection and FTS trigger inspection are batched, redundant FTS creation and observation normalization are skipped, and fresh observation and sync columns are initialized directly (#2270, #2276, #2274, #2279, #2319, #2325, #2321). Context and save paths read less data: discarded context work is bounded by a byte budget, compact context reads only rendered fields, global context project-name hydration is bounded, established saves skip project enumeration, and save relevance checks avoid token collections (#2258, #2262, #2268, #2254, #2303). Sync defers historical payload reads, persists scoped chunk delete evidence to avoid historical downloads, aggregates synced chunk IDs without per-row filesystem checks, and skips no-op legacy project updates (#2256, #2294, #2296, #2281). Health probes use bounded store reads (#2260), checkout-root detection reuses Git metadata (#2300), and Windows generation identity is read from metadata handles (#2266).

Release tooling observes the exact Core and Pi artifact workflows and published Pi and Core persistence together (#2132, #2245). Internal refactors separate doctor repair argument parsing, consolidation selection and Git export publication (#2285, #2292, #2289). Test reliability and speed improvements cover PowerShell cancellation, SubagentStop fixtures, session marker cleanup, EINTR handling, the Claude matrix, shared candidate CLI fixtures and Pi PATH/real HTTP integrations (#2264, #2283, #2317, #2287, #2323, #2272, #1906).

Verification

Push CI for the release commit: green.
The release workflow runs module metadata and published Pi companion checks before GoReleaser; its companion preflight requires gentle-engram@0.7.0 on npm.
These checks do not claim an installed upgrade test in every environment or downstream Shell bundle upgrades.

Upgrade

Back up your Engram data and relevant configuration before upgrading, keep a known-good installation, and validate your integrations afterwards. See the release and rollback policy.

Homebrew:

brew update
brew upgrade engram
engram version

If an Engram server is already running, restart it with the supervisor that started it and confirm the server version with engram cloud status or engram ps.
Pi users: after upgrading the core, run engram setup pi, or pi install npm:gentle-engram@0.7.0, then restart Pi.
Alternatively, download the archive for your OS and architecture below and verify it against checksums.txt. See the installation guide.

Full changelog

16c5bf4 feat(release): observe exact Core and Pi artifact workflows (#2132)
164babd fix(claude): skip desktop synthetic prompt captures (#2246)
03b8223 feat(release): observe published Pi and Core persistence together (#2245)
a465b6c fix(claude): avoid unnecessary session argument rewrites (#2248)
81536de docs: verify running server version after upgrades (#2251)
590b403 fix(store): admit the v3.6.0 catalog in migrate-copy (#2252)
2102090 perf(mcp): skip project enumeration for established saves (#2254)
b392045 perf(sync): defer historical payload reads until endpoints remain unresolved (#2256)
6efffff perf(store): bound discarded context work by byte budget (#2258)
0bf44c8 perf(server): use bounded store reads for health probes (#2260)
0a019b2 test(plugin): distinguish PowerShell cancellation from child exits (#2264)
0c3d47a perf(store): read only rendered fields for compact context (#2262)
b8598e6 perf(store): capture Windows generation identity from metadata handles (#2266)
598c58e perf(mcp): bound global context project-name hydration (#2268)
59ee7f2 perf(store): batch additive column introspection during startup (#2270)
0369adb perf(tests): reuse the candidate CLI across package fixtures (#2272)
2c321d5 perf(store): avoid redundant FTS creation for fresh databases (#2274)
97b5449 perf(store): batch FTS trigger inspection during startup (#2276)
b0ecb20 perf(store): skip redundant observation normalization on healthy startup (#2279)
2c71ca1 perf(store): avoid no-op legacy sync project updates (#2281)
8fd46ac test(plugin): isolate SubagentStop capture fixtures per case (#2283)
5dfd6fa refactor(cli): isolate doctor repair argument parsing (#2285)
9dd1f29 refactor(sync): separate Git export content from publication (#2289)
a025adf refactor(test): read EINTR errno through libc byte view (#2287)
51e73c7 refactor(cli): separate consolidation selections from execution (#2292)
edf7127 perf(sync): persist scoped chunk delete evidence to avoid historical downloads (#2294)
6259693 perf(project): reuse Git metadata within checkout-root detection (#2300)
9567b54 perf(store): aggregate synced chunk IDs without per-row filesystem checks (#2296)
9130b8e perf(store): avoid token collections in save relevance checks (#2303)
ed53379 docs(obsidian): obsidian-export is already in the stable release (#2007)
13fd703 fix(sync): preserve local edits behind unrelated chunk timestamps (#2309)
bfdf6ab fix(doctor): detect invalid pending cloud journal projects (#2308)
76e8972 fix(claude): preserve resume ownership and report registration failures (#2310)
ee0f473 test(pi): verify qualified PATH and real HTTP integrations (#1906)
cb02c5d feat(cli): run engram serve in the background as a daemon (#2229)
ac6349b fix(cli): report running server release skew and pending restart (#2311)
8d7ab6e feat(setup): add explicit Claude memory-write permission opt-in (#2314)
a957599 fix(test): retain owned session marker paths for cleanup (#2317)
3b8b8cf perf(store): initialize fresh observation columns directly (#2319)
18b7338 refactor(store): avoid redundant fresh sync state alterations (#2321)
3ce741e perf(test): check Claude matrix prerequisites once per Bash route (#2323)
ed7131a perf(store): initialize fresh sync columns directly (#2325)
820c7ba feat(store): add an optional org field to group projects by organization (#1151)
0efd6ad fix(search): honor the org filter on GET /search (#2327)
6391e4d feat(governance): accept Refs #N as non-closing approved issue reference (#1617)
f96b613 chore(pi): prepare gentle-engram 0.7.0 and pin it in engram setup (#2329)

Full comparison: v3.6.2...v3.7.0