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.
TypeScript agent-memoryai-agentsanthropicclaude-codecursorgitknowledge-baseknowledge-graphllmmarkdownmcpmcp-servermodel-context-protocolnote-takingobsidianpkmragsecond-brainself-hostedzettelkasten
fix(deploy): stdio image must refuse to boot as a web service (#9)
Ronalds Palacis28d1db07ef27
diff --git a/DEPLOY.md b/DEPLOY.mdindex 7a1d760..af8d674 100644--- a/DEPLOY.md+++ b/DEPLOY.md@@ -10,6 +10,12 @@ workspace is what the dashboard shows and what agents read/write.3. Copy the Client ID + Secret.## 2. Railway++> **Deploying from a prebuilt image rather than the repo?** Use `ghcr.io/rwnalds/engram-app:latest`+> and set the healthcheck path to `/api/health`. The similarly-named `ghcr.io/rwnalds/engram` is the+> **stdio** MCP server for Claude Desktop/Cursor — it speaks JSON-RPC on stdin/stdout and never opens+> a port, so as a web service it 502s no matter what else is configured.+1. **New Project → Deploy from GitHub repo** → this repo (builds via root `Dockerfile`).2. **Add a Volume**, mount path `/data`.3. **Variables** — only these five are required on the host; the rest are optional anddiff --git a/README.md b/README.mdindex 360fda0..b1da046 100644--- a/README.md+++ b/README.md@@ -197,7 +197,17 @@ VAULT_DIR=/path/to/your/obsidian-or-markdown/vault bun devbun run mcp:stdio /path/to/your/vault # defaults to ./sample-vault```- Same `brain_*` tools. Image: `Dockerfile.mcp` (`CMD ["bun", "scripts/mcp-stdio.ts"]`).+ Same `brain_*` tools. Built from `Dockerfile.mcp`.++**Each mode ships as its own image, and they are not interchangeable:**++| Image | Mode | Use it for |+|---|---|---|+| `ghcr.io/rwnalds/engram-app` | HTTP — dashboard + `/api/mcp` | **Railway, Render, Fly, any host.** This is the one you deploy. |+| `ghcr.io/rwnalds/engram` | stdio — JSON-RPC on stdin/stdout | Claude Desktop, Cursor, MCP registries. Never opens a port. |++Deploying the stdio image as a web service is the one mistake worth calling out: it can only 502,+because there is nothing listening. It now refuses to start on a PaaS and tells you this instead.## MCP tools@@ -232,6 +242,10 @@ page — only auth/infra bootstrap vars live on the host. Full setup: **[DEPLOY.- **Railway:** New Project → *Deploy from GitHub repo* → add a Volume at `/data`.- **Render:** one-click via the bundled `render.yaml` (Docker + a `/data` disk).+Deploying from a prebuilt image instead of the repo? Use **`ghcr.io/rwnalds/engram-app:latest`** —+not `engram:latest`, which is the stdio server and cannot answer HTTP. Set the healthcheck to+`/api/health`.+## FAQ**How do I give Claude Code long-term memory?**diff --git a/scripts/mcp-stdio.ts b/scripts/mcp-stdio.tsindex 018938b..2842674 100644--- a/scripts/mcp-stdio.ts+++ b/scripts/mcp-stdio.ts@@ -14,7 +14,56 @@* be resolved into env BEFORE the tools module loads (config reads it at import), so imports are* dynamic, inside main().*/+/**+ * The stdio server speaks JSON-RPC on stdin/stdout and never opens a port. Deployed to a PaaS as a+ * web service it fails like this: it prints "ready", reads EOF from a stdin nothing is attached to,+ * exits 0 — and the platform reports a *successful* deploy whose URL 502s forever. Nothing in the+ * logs looks wrong, which is what makes it expensive: engram's own Railway instance sat broken on+ * exactly this, deployed from the wrong one of the two published images.+ *+ * The two are not interchangeable:+ * ghcr.io/rwnalds/engram stdio — Claude Desktop, Cursor, registries (Dockerfile.mcp)+ * ghcr.io/rwnalds/engram-app HTTP — dashboard + /api/mcp, what a PaaS runs (Dockerfile)+ *+ * So refuse, loudly and non-zero, when we can tell we're a web service on a PaaS: a crashed deploy+ * with an explanation beats a green one that never answers. Only unambiguous platform markers+ * count — PORT is an ordinary local env var and must never trip this. Running the stdio server+ * inside a deployed container is legitimate, so ENGRAM_ALLOW_STDIO_ON_PAAS=1 overrides.+ */+const PAAS_MARKERS: ReadonlyArray<readonly [envVar: string, platform: string]> = [+ ["RAILWAY_ENVIRONMENT", "Railway"],+ ["RENDER", "Render"],+ ["FLY_APP_NAME", "Fly.io"],+ ["DYNO", "Heroku"],+ ["KOYEB_APP_NAME", "Koyeb"],+];++function refuseIfDeployedAsWebService() {+ if (process.env.ENGRAM_ALLOW_STDIO_ON_PAAS) return;+ const marker = PAAS_MARKERS.find(([envVar]) => process.env[envVar]);+ if (!marker) return;++ console.error(+ [+ "",+ `[engram] Refusing to start: this is the stdio MCP image, running on ${marker[1]}.`,+ "",+ " It serves JSON-RPC over stdin/stdout and never opens a port, so a web service built from",+ " it can only 502 — and by exiting 0 it would report a deploy that 'succeeded'.",+ "",+ " Deploy the app image instead: ghcr.io/rwnalds/engram-app:latest",+ " dashboard + HTTP MCP at /api/mcp · healthcheck /api/health · volume mounted at /data",+ "",+ " Meant to run the stdio server inside a deployed container? Set ENGRAM_ALLOW_STDIO_ON_PAAS=1",+ "",+ ].join("\n"),+ );+ process.exit(1);+}+async function main() {+ refuseIfDeployedAsWebService();+const vaultArg = process.argv[2];if (vaultArg) process.env.VAULT_DIR = vaultArg;// Local mode: never touch git, never require an Anthropic key for introspection.