Skip to content

Self-hosted MCP server + dashboard giving Claude Code, Cursor & Hermes agents shared long-term memory over a git-backed markdown vault. Agent-native, Obsidian-compatible second brain — markdown RAG, no vector DB.

deploy: slim .env.example to bootstrap vars only (clean Railway auto-detect)

Ronalds Palacis3cb019a58145
diff --git a/.env.example b/.env.example
index 888b5a1..dc3f03e 100644
--- a/.env.example
+++ b/.env.example
@@ -1,54 +1,37 @@
# ── Engram ──────────────────────────────────────────────────────────────────
-# Copy to .env.local for local dev; set the same vars on your host for deploy.
+# LOCAL DEV needs nothing here — Engram has sane defaults and the dashboard is OPEN
+# until you set AUTH_SECRET. Copy to .env.local only if you want to override a default.
#
-# Most runtime behavior below is ALSO editable in the dashboard → Settings (persisted
-# under ENGRAM_DATA_DIR). A saved setting OVERRIDES the matching env var and takes effect
-# without a redeploy. Vars tagged "(Settings)" are optional here — set them once in the UI
-# instead. The Auth block bootstraps login itself, so it must stay in env.
-
-NEXT_PUBLIC_APP_NAME="Engram" # (Settings) default app name; the UI value wins at runtime
-
-# Vault = the markdown source of truth.
-# local dev (unset): ./sample-vault (bundled)
-# production: the mounted volume path
-# VAULT_DIR="/data"
-
-# ── Vault sync ── (Settings) all three are editable in the dashboard ─────────
-# Vault repos are connected in the dashboard (Workspaces). Set GIT_SYNC_ENABLED=true to
-# auto commit+push the active repo — or just flip it in Settings → Git sync.
-GIT_SYNC_ENABLED="false"
-GIT_AUTHOR_NAME="Engram"
-GIT_AUTHOR_EMAIL="[email protected]"
-# ENGRAM_DATA_DIR="/data" # app state + vault clones (on Railway: the volume)
-
-# ── Workspaces: GitHub OAuth ── (Settings) editable in Settings → GitHub ─────
-# For the "Connect GitHub" repo flow. Optional — the URL+token path needs no OAuth app.
-GITHUB_CLIENT_ID=""
-GITHUB_CLIENT_SECRET=""
-
-# ── Auth ────────────────────────────────────────────────────────────────────
-# Dashboard: Google sign-in restricted to an email allowlist.
-# Leave AUTH_SECRET empty (or AUTH_DISABLED=true) to keep the dashboard OPEN (local dev).
-ALLOWED_EMAILS="" # comma-separated emails allowed to sign in
-AUTH_SECRET="" # openssl rand -base64 32, or Railway "Generate" (empty => dashboard auth off)
-APP_URL="http://localhost:3000" # public base URL (Google OAuth redirect_uri = APP_URL/api/auth/callback)
+# FOR DEPLOY set the five bootstrap vars below on your host (they gate login + say where
+# state lives, so they can't be configured from inside the app). EVERYTHING ELSE is set
+# in the dashboard → Settings, with no redeploy — see the commented reference at the bottom.
+# Full guide: DEPLOY.md.
+
+# ── Production bootstrap (set these on your host) ─────────────────────────────
+AUTH_SECRET="" # openssl rand -base64 32 (or Railway "Generate"). Empty => dashboard OPEN — local only.
+APP_URL="" # public base URL, e.g. https://your-app.up.railway.app (Google OAuth redirect base). On Railway: https://${{RAILWAY_PUBLIC_DOMAIN}}
+ALLOWED_EMAILS="" # comma-separated Google emails allowed to sign in
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""
-# MCP auth. Optionally set ONE shared token here, and/or create per-teammate tokens
-# in the dashboard Connect page. The MCP is OPEN when no token exists (local dev).
-MCP_TOKEN=""
-# Where per-teammate token hashes persist (kept out of the vault git). Defaults to
-# <vault>/.engram. On Railway put it on the volume, e.g. /data/.engram.
-# ENGRAM_STATE_DIR="/data/.engram"
-
-# Local/OSS single-user mode: no Google auth, MCP open. NEVER true in production.
-AUTH_DISABLED="false"
+# Where app state + vault clones live. REQUIRED on a host with a volume (e.g. Railway),
+# or your data is ephemeral and lost on redeploy. Point it at the mounted volume.
+# ENGRAM_DATA_DIR="/data"
-# ── Harness (brain_capture) — OFF by default ── (Settings) → AI capture ──────
-# Optional server-side auto-filing of rough dumps. Costs extra tokens; a coding
-# agent can do the same over the plain MCP tools for free. Easiest to enable in
-# the dashboard (Settings → AI capture) — toggle + paste the key there.
-HARNESS_ENABLED="false"
-ANTHROPIC_API_KEY=""
-CAPTURE_MODEL="claude-haiku-4-5-20251001"
+# ── Optional — configure in the dashboard → Settings (no redeploy) ────────────
+# Listed for reference only. Uncomment to hard-set via env instead of the UI; a value
+# saved in Settings overrides the env value either way.
+#
+# NEXT_PUBLIC_APP_NAME="Engram" # display name (sidebar + browser tab)
+# GIT_SYNC_ENABLED="false" # auto commit + push the active vault
+# GIT_AUTHOR_NAME="Engram"
+# GIT_AUTHOR_EMAIL="[email protected]"
+# GITHUB_CLIENT_ID="" # "Connect GitHub" repo flow (URL+token path needs no OAuth app)
+# GITHUB_CLIENT_SECRET=""
+# HARNESS_ENABLED="false" # brain_capture auto-filing (costs Anthropic tokens)
+# ANTHROPIC_API_KEY=""
+# CAPTURE_MODEL="claude-haiku-4-5-20251001"
+# MCP_TOKEN="" # one shared MCP key; or create per-teammate tokens on the Connect page
+# ENGRAM_STATE_DIR="/data/.engram" # override where token hashes persist (defaults to ENGRAM_DATA_DIR)
+# VAULT_DIR="/data" # fallback local vault (workspaces are normally connected in the UI)
+# AUTH_DISABLED="false" # single-user local mode: no Google auth, MCP open. NEVER true in production.
diff --git a/railway.toml b/railway.toml
index b447122..95bdc74 100644
--- a/railway.toml
+++ b/railway.toml
@@ -9,5 +9,6 @@ healthcheckTimeout = 100
restartPolicyType = "on_failure"
restartPolicyMaxRetries = 5
-# Deploy this repo (the app). Mount a volume at /data and set VAULT_DIR=/data;
-# the app clones + git-syncs the remote vault repo (GIT_REMOTE) into that volume.
+# Deploy this repo (the app). Mount a volume at /data and set ENGRAM_DATA_DIR=/data;
+# app state + vault clones live there. Vault repos are connected in the dashboard
+# (Workspaces) — no GIT_REMOTE env. Most other config is set in Settings, not here.