🧠 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.