v1.12.0

What's New

Engram now nudges agents that forget to save memories, and shows an activity score at session end so you can spot sessions with potential context loss.

Features

Save Reminder on Inactivity

When no mem_save has been called for 10+ minutes in an active session, engram appends a short reminder to mem_search and mem_context responses:

No mem_save calls for this project for 15 minutes. Did you make any decisions, fix bugs, or discover something worth persisting?

Cost: ~30 tokens per nudge. Works with any MCP agent.

Session Activity Score

When mem_session_summary is called, engram appends an activity score:

Session activity: 47 tool calls, 2 saves

If the session had high activity but zero saves, it flags it:

Session activity: 31 tool calls, 0 saves -- high activity with no saves, consider persisting important decisions

DELETE /sessions and /prompts endpoints

New HTTP endpoints for hard-deleting sessions and prompts (PR #174 by @egdev6):

• DELETE /sessions/{id} -- deletes session and its prompts, returns 409 if it has observations
• DELETE /prompts/{id} -- deletes a single prompt

Documentation overhaul

• Fixed Go version requirement (1.25 does not exist)
• Fixed module path in docs
• Added 3 missing HTTP endpoints to docs
• Added obsidian-export CLI command to all doc pages
• Restructured DOCS.md from 690-line mega-doc to focused ~400-line technical reference
• Deduplicated CLI and MCP tools references across files

Upgrade

brew update && brew upgrade engram

Links

• Full changelog
• Documentation

v1.12.0-beta.1

🧠 Engram v1.10.0-beta.1 — Obsidian Brain Visualization

Beta release. This tag ships an experimental feature for early testers. Main latest stable is unaffected. Feedback welcome — see Feedback below.

✨ New: Obsidian Brain

Visualize your AI agent's entire memory as a navigable knowledge graph in Obsidian. Every observation becomes a Markdown note. Sessions, projects, and topic clusters become connected hubs. Open Obsidian's Graph View and see how your agent's brain actually thinks.

Agent memory (SQLite)
    ↓ engram-beta obsidian-export
Obsidian vault (Markdown + YAML frontmatter + wikilinks)
    ↓ Obsidian Graph View
Interactive cognitive map of your agent's knowledge

What you get

• CLI exporter: engram-beta obsidian-export --vault <path> — one command, full export
• Incremental sync: only writes what changed since last export
• Daemon mode: --watch --interval 10m runs forever, keeps your vault live
• Graph config bootstrap: ships an opinionated "engram-brain" visual layout (color groups by type, tuned forces, clean look)
• Hub notes: auto-generated session hubs and topic cluster hubs with backlinks
• Safe namespace: writes only inside {vault}/engram/, never touches your existing notes
• Zero dependencies: pure Go, single binary, works offline

Install side-by-side as engram-beta

This beta installs as a separate binary called engram-beta so it never replaces your stable engram. Both binaries share the same ~/.engram/engram.db, so memories captured by your stable agent are immediately visible to the beta.

macOS (Apple Silicon):

curl -L https://github.com/Gentleman-Programming/engram/releases/download/v1.12.0-beta.1/engram_1.12.0-beta.1_darwin_arm64.tar.gz -o /tmp/engram-beta.tar.gz
tar -xzf /tmp/engram-beta.tar.gz -C /tmp
sudo mv /tmp/engram /usr/local/bin/engram-beta
sudo chmod +x /usr/local/bin/engram-beta
engram-beta version

macOS (Intel), Linux, and go install instructions in the full guide.

Verify both coexist:

engram version       # your stable, untouched
engram-beta version  # v1.12.0-beta.1

60-second quick start

# 1. Create a vault folder
mkdir -p ~/Obsidian/engram

# 2. Export your full brain + bootstrap the graph layout
engram-beta obsidian-export --vault ~/Obsidian/engram --graph-config force

# 3. Open Obsidian → "Open folder as vault" → ~/Obsidian/engram
# 4. Cmd+G (Mac) or Ctrl+G → Graph View

You should see hundreds (or thousands) of connected nodes clustered by session and topic, color-coded by type.

Keep it synced automatically

# Sync every 10 minutes, runs forever, Ctrl+C to stop
engram-beta obsidian-export --vault ~/Obsidian/engram --watch

# Or every 5 minutes, only one project
engram-beta obsidian-export --vault ~/Obsidian/engram --watch --interval 5m --project engram

Full docs

📖 Complete Obsidian Brain guide (all flags, graph config modes, launchd setup, troubleshooting):
docs/beta/obsidian-brain.md

---

🧪 What's experimental about this?

• Behavior is locked — flags work as documented, tests cover all paths, smoke-tested live against 1,700+ observations
• Flag names may evolve before stable release based on your feedback
• Not in main README yet — that's intentional. The README stays clean for stable features. Beta docs live in docs/beta/.
• Not shipped via homebrew latest — you have to explicitly install this tag

If your feedback validates the feature, it graduates to stable in a future minor release. The docs move into the main README, docs/beta/obsidian-brain.md gets deleted, and that's the promotion path.

📦 What's in the binary

27 tasks across obsidian-plugin + 21 tasks across obsidian-auto-sync = 48 implementation tasks, all under Strict TDD:

• internal/obsidian/ — new package (exporter, slug, markdown, state, hub, graph, watcher + tests)
• cmd/engram/ — new obsidian-export subcommand with 8 flags
• plugin/obsidian/ — optional TypeScript community plugin for in-Obsidian sync
• docs/beta/obsidian-brain.md — full beta documentation
• 60 new tests, zero regressions across the 10 existing Go packages

Full SDD audit trail persisted in Engram memory under topic keys sdd/obsidian-plugin/* and sdd/obsidian-auto-sync/*.

🗣️ Feedback

This is a beta specifically to get your input. Things I'd love to hear:

• Scale: does the graph layout feel right at your scale (100 / 1k / 10k+ observations)?
• Visual defaults: are the 6 color groups useful, or do you wish they were configurable?
• Daemon mode: did --watch crash, leak memory, or behave unexpectedly?
• Graph config bootstrap: did --graph-config=preserve clobber something you cared about?
• Missing features: what's the one thing you wish it did that it doesn't?
• Next step: should the next iteration invest in embeddings + semantic graph edges, or keep it metadata-only?

File issues at github.com/Gentleman-Programming/engram/issues with the beta:obsidian label.

🚫 Not in scope for this beta

Explicitly deferred — don't file issues for these, they're known:

• Embeddings / RAG / semantic search
• Bidirectional sync (Obsidian edits → Engram)
• Mobile Obsidian support
• Custom hub templates
• Integration with engram serve (manual daemon only for now)

⬆️ Upgrading from stable

No migration needed. This is purely additive:

• No schema changes
• No config file changes
• No breaking changes to existing CLI commands, MCP tools, or HTTP API
• All existing tests pass

Roll back anytime by installing a stable tag: brew upgrade engram (skips prereleases by default).

🙏 Thanks

Big thanks to early testers and anyone who opens an issue with the beta:obsidian label. This feature exists because the question "how do I actually see what my agent knows?" was asked one too many times.

v1.11.0

Changelog

• 387128e feat(project): fix project name drift with auto-detection, normalization, and migration tools

v1.10.10

Engram v1.10.10 — Correct Version for go install

Users installing via go install now see the correct version instead of dev.

Bug Fix

• Version resolution from Go module info — added a runtime fallback using debug.ReadBuildInfo() that reads the version embedded by Go's module system when ldflags aren't set
• go install github.com/Gentleman-Programming/engram/cmd/engram@v1.10.10 now correctly reports engram 1.10.10
• Goreleaser builds (Homebrew, GitHub release binaries) are unaffected — they continue using ldflags as before

v1.10.9

Engram v1.10.9 — Deferred Tools & Honest Update Checks

Reduces MCP session startup cost and makes version check failures visible.

What's New

• Deferred rare tools — 4 infrequently-used MCP tools (mem_delete, mem_update, mem_suggest_topic_key, mem_capture_passive) are now deferred at session startup, reducing the initial token cost for agents that list available tools
• Honest update check failures — when the GitHub version check fails (network error, rate limit, etc.), the error is now surfaced in the TUI instead of being silently swallowed

v1.10.8

Engram v1.10.8 — FTS5 Topic Search Fix

Fixes mem_search not finding observations by topic_key, and adds a direct search fallback for edge cases where FTS5 tokenization misses results.

Bug Fix

• topic_key added to FTS5 index — searching for topic keys like architecture/auth-model now returns matches via full-text search
• Direct search fallback — if FTS5 returns zero results, a LIKE-based fallback query runs against key text fields to catch cases where FTS5 tokenization fails (e.g., slash-separated keys, special characters)

Docs

• Added "Intended Usage" mental model page to docs

v1.10.7

Engram v1.10.7 — Sync Embedded OpenCode Plugin

Syncs the embedded OpenCode plugin template (used by engram setup opencode) with the chat.message hook fix from v1.10.6.

What Changed

• Embedded plugin updated — users running engram setup opencode now get the fixed plugin that uses chat.message instead of the broken prompt event
• Existing users who already ran setup need to re-run engram setup opencode to pick up the fix

v1.10.6

Engram v1.10.6 — OpenCode Prompt Capture Fix

Fixes the OpenCode plugin's prompt capture mechanism which stopped working after an SDK change.

Bug Fix

• Replaced dead prompt event — the OpenCode plugin now uses the chat.message hook to capture user prompts, replacing the previous prompt event handler that was silently failing after an OpenCode SDK update
• User prompts are now correctly saved to Engram's user_prompts table again

v1.10.5

Engram v1.10.5 — Claude Code Eager Memory Tools

Improves the Claude Code plugin to load memory tools eagerly at session start and leverage ToolSearch for better tool discovery.

What's New

• Eager tool loading — memory tools (mem_save, mem_search, mem_context, etc.) are loaded at session start instead of waiting for first use, reducing latency on the first memory operation
• Auto-ToolSearch — the plugin now uses Claude Code's ToolSearch capability so agents can discover Engram tools naturally through conversation context

v1.10.4

Highlights

• Fix session inflation: OpenCode Task() sub-agent executions no longer register as separate Engram sessions
• Fix pre-existing bug in session.created event handler reading the wrong property path

What Changed

• The OpenCode plugin now detects sub-agent sessions via parentID (set by OpenCode on all Task() sessions) and skips session registration for them
• Secondary detection via title suffix subagent) provides defense-in-depth
• Sub-agent session IDs are tracked to prevent cross-hook inflation via tool.execute.after
• Fixed event.properties.id to event.properties.info.id (correct path per OpenCode SDK types)

Impact

Before this fix, a single user conversation using sub-agents could generate 170+ sessions in the Engram DB. After this fix, only the real user session is registered.

Included Work

• fix(plugin): skip sub-agent session registration in OpenCode plugin