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.

feat(demo): self-resetting public playground (#8)

Ronalds Palacis454df240f323
diff --git a/demo/Dockerfile b/demo/Dockerfile
new file mode 100644
index 0000000..4b84e83
--- /dev/null
+++ b/demo/Dockerfile
@@ -0,0 +1,20 @@
+# Public playground image.
+#
+# Wraps the published app image — same binary users deploy, no rebuild — and swaps the entrypoint
+# for a supervisor that seeds a throwaway vault and resets it on an interval. Pin the base tag to a
+# released version so the demo can never run code older than the security fixes in it; bump on
+# release. Must be >= 0.1.2 (path-traversal + stored-XSS fixes) before it is ever exposed publicly.
+FROM ghcr.io/rwnalds/engram-app:0.1.2
+
+# git is already present in the base image (used for the vault sync loop); the seed script needs it.
+COPY demo/seed.sh /demo/seed.sh
+COPY demo/entrypoint.sh /demo/entrypoint.sh
+RUN chmod +x /demo/seed.sh /demo/entrypoint.sh
+
+# No volume, no persisted state — the vault lives inside the container and dies with it.
+ENV VAULT_DIR=/demo-vault \
+ ENGRAM_DATA_DIR=/demo-data \
+ RESET_INTERVAL_SECONDS=21600
+
+EXPOSE 3000
+ENTRYPOINT ["/demo/entrypoint.sh"]
diff --git a/demo/README.md b/demo/README.md
new file mode 100644
index 0000000..1ae14b3
--- /dev/null
+++ b/demo/README.md
@@ -0,0 +1,56 @@
+# Engram — public playground
+
+The open, resettable demo behind [the "try it live" link](https://github.com/rwnalds/engram).
+No login, no signup: anyone can read, write, supersede, delete, break it. It heals on a timer.
+
+It exists so you can watch the one thing Engram does differently without cloning anything: search
+the seeded vault for **retainer price** and see the live 2026 note come back while the retired 2025
+one is withheld with a reason.
+
+## How it works
+
+- **[`Dockerfile`](./Dockerfile)** wraps the published `ghcr.io/rwnalds/engram-app` image — the same
+ binary you'd deploy — and swaps in a supervisor entrypoint. Pinned to a released tag so the demo
+ can never run code older than its security fixes. **Must be ≥ 0.1.2.**
+- **[`seed.sh`](./seed.sh)** writes a fictional 18-note vault with a small fabricated git history, so
+ the Activity page shows real per-agent commits (`claude-code`, `cursor-agent`, a read-write
+ teammate). Deterministic — every reset produces the identical vault.
+- **[`entrypoint.sh`](./entrypoint.sh)** seeds the vault, starts the app, and on an interval (or on
+ exit) tears it down and re-seeds. Because there is **no persistent volume**, a restart resets
+ everything too.
+
+It runs `AUTH_DISABLED=true` with git sync off. Nothing it does touches a real vault or pushes
+anywhere.
+
+## Deploy (Railway)
+
+1. New service from this repo.
+2. **Settings → Build**: Dockerfile path `demo/Dockerfile`, root directory the repo root (the build
+ needs `demo/` in context).
+3. **Do not add a volume.** Ephemeral is the point.
+4. Variables — all optional:
+
+ | Variable | Default | Notes |
+ |---|---|---|
+ | `RESET_INTERVAL_SECONDS` | `21600` (6h) | Lower it on a high-traffic day so graffiti doesn't linger. |
+ | `PORT` | `3000` | Railway sets this; the app honours it. |
+
+5. Deploy, open the URL, confirm `/api/health` returns 200.
+
+## When a new version ships
+
+Bump the `FROM` tag in `demo/Dockerfile` to the new release and redeploy. The demo does not
+auto-follow `latest` on purpose — a demo pinned to a known-good tag can't be broken by a bad push.
+
+## What's deliberately allowed
+
+This is a playground, so the open behaviours are intended, not oversights:
+
+- **Anyone can write or delete any note.** The reset heals it.
+- **Anyone can create MCP tokens** on the Connect page. Ephemeral; wiped on reset.
+- **Anyone can connect a vault repo** in Workspaces. It clones into throwaway state and is wiped on
+ reset; it does not touch the seeded demo vault permanently.
+
+What is **not** allowed — and is enforced by the app, not by this wrapper — is reading files outside
+the vault or landing script in another visitor's browser. Both were fixed in 0.1.2, which is why the
+base tag floor is 0.1.2.
diff --git a/demo/entrypoint.sh b/demo/entrypoint.sh
new file mode 100755
index 0000000..ce5a903
--- /dev/null
+++ b/demo/entrypoint.sh
@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+#
+# Public-playground supervisor.
+#
+# The demo is deliberately open — no auth, anyone can write, delete, supersede, break it. That is
+# only safe because it is disposable: this loop re-seeds the vault and wipes app state on a fixed
+# interval, and again whenever the app exits. A defaced or emptied vault heals itself.
+#
+# It restarts the whole app process rather than mutating a running vault, so the reset is atomic:
+# no half-written files, no index race, no leftover tokens a visitor created. Because the container
+# has NO persistent volume, a Railway restart resets everything too — the interval just guarantees
+# it happens even if nobody restarts it.
+set -u
+
+cd /app || { echo "[demo] /app missing — is this built FROM the engram-app image?"; exit 1; }
+
+export VAULT_DIR="${VAULT_DIR:-/demo-vault}"
+export ENGRAM_DATA_DIR="${ENGRAM_DATA_DIR:-/demo-data}"
+export AUTH_DISABLED="true" # open dashboard — this is the whole point of a playground
+export GIT_SYNC_ENABLED="false" # never push the demo vault anywhere
+export ENGRAM_DISABLE_GIT_SYNC="1" # and skip the boot git-sync entirely
+export NODE_ENV="production"
+
+# How often to wipe back to the seed. Default 6h — short enough that launch-day graffiti doesn't
+# linger, long enough that someone mid-exploration isn't reset out from under. Override on Railway.
+RESET_INTERVAL_SECONDS="${RESET_INTERVAL_SECONDS:-21600}"
+
+reseed() {
+ rm -rf "$ENGRAM_DATA_DIR"
+ mkdir -p "$ENGRAM_DATA_DIR"
+ /demo/seed.sh "$VAULT_DIR"
+}
+
+echo "[demo] reset interval: ${RESET_INTERVAL_SECONDS}s · vault: $VAULT_DIR"
+
+# Reset on SIGTERM so a graceful Railway shutdown still leaves a clean slate for next boot.
+trap 'kill "${APP:-0}" 2>/dev/null; exit 0' TERM INT
+
+while true; do
+ reseed
+ bun run start &
+ APP=$!
+ echo "[demo] app started (pid $APP), next reset in ${RESET_INTERVAL_SECONDS}s"
+
+ # Sleep in the background so a crash is noticed immediately instead of after the full interval.
+ sleep "$RESET_INTERVAL_SECONDS" &
+ TIMER=$!
+ wait -n "$APP" "$TIMER"
+
+ # Whichever fired first, tear the app down and loop into a fresh reseed.
+ kill "$APP" "$TIMER" 2>/dev/null
+ wait "$APP" 2>/dev/null
+ echo "[demo] cycling — reseeding"
+ sleep 2
+done
diff --git a/demo/seed.sh b/demo/seed.sh
new file mode 100755
index 0000000..e0c2a5e
--- /dev/null
+++ b/demo/seed.sh
@@ -0,0 +1,317 @@
+#!/usr/bin/env bash
+#
+# Seed the public playground vault: 18 markdown notes and a small, fabricated git history so the
+# Activity page has something to show. Deterministic — every reset produces the identical vault,
+# including commit dates, so the demo always looks the same no matter when you hit it.
+#
+# The content is a fictional company. Nothing here is real. The one thing it demonstrates for real
+# is the price story: docs/pricing-2025.md is superseded by docs/pricing-2026.md, so a search for
+# "retainer price" returns the live note and withholds the dead one with a reason.
+#
+# Usage: seed.sh <vault-dir>
+set -euo pipefail
+
+VAULT="${1:?usage: seed.sh <vault-dir>}"
+rm -rf "$VAULT"
+mkdir -p "$VAULT"/{clients/northwind,clients/vertex,decisions,projects,people,docs,archive}
+
+w() { mkdir -p "$(dirname "$VAULT/$1")"; cat > "$VAULT/$1"; }
+
+w docs/pricing-2026.md <<'EOF'
+---
+title: Pricing (2026)
+type: doc
+tags: [pricing, commercial]
+status: locked
+created: 2026-01-08
+valid_until: 2026-12-31
+supersedes: "[[pricing-2025]]"
+---
+# Pricing (2026)
+
+The standard retainer is **EUR 2,500 per month**, billed monthly.
+
+| Tier | Monthly | Includes |
+|---|---|---|
+| Standard | EUR 2,500 | Core workspace, support, quarterly review |
+| Plus | EUR 4,000 | Everything in Standard + dedicated integration work |
+
+Supersedes [[pricing-2025]] — repriced for the 2026 renewal cycle.
+
+> Try it: search this vault for **retainer price**. This note comes back as `authoritative`;
+> the 2025 note is withheld with the reason "superseded by pricing-2026".
+EOF
+
+w docs/pricing-2025.md <<'EOF'
+---
+title: Pricing (2025 pilot)
+type: doc
+tags: [pricing, commercial]
+status: superseded
+superseded_by: "[[pricing-2026]]"
+superseded_at: 2026-01-08
+superseded_reason: repriced for the 2026 renewal
+created: 2025-02-11
+---
+# Pricing (2025 pilot)
+
+> [!warning] Retired — kept for history
+> Replaced by [[pricing-2026]]. Search withholds this note.
+
+The standard retainer is **EUR 2,000 per month**, billed quarterly in advance. This price covers
+the full pilot engagement. Pricing questions about the retainer price should reference this note.
+The price was held flat for the pilot.
+EOF
+
+w docs/support-sla.md <<'EOF'
+---
+title: Support SLA
+type: doc
+tags: [support, commercial]
+status: canonical
+created: 2026-02-02
+---
+# Support SLA
+
+First response within one business day. Sev-1 within four hours.
+Escalation path: on-call, then [[maya-okonkwo]].
+EOF
+
+w docs/security-posture.md <<'EOF'
+---
+title: Security posture
+type: doc
+tags: [security]
+status: locked
+created: 2026-03-14
+---
+# Security posture
+
+Secrets encrypted at rest. Per-agent tokens scoped read or write.
+Reviewed quarterly. See [[adopt-authority-ranking]].
+EOF
+
+w docs/onboarding-runbook.md <<'EOF'
+---
+title: Client onboarding runbook
+type: doc
+tags: [process]
+status: active
+created: 2026-02-20
+---
+# Client onboarding runbook
+
+1. Kickoff call, scope confirmed in writing
+2. Workspace provisioned
+3. Integration review at day 14
+4. Handover to [[maya-okonkwo]]
+EOF
+
+w decisions/adopt-authority-ranking.md <<'EOF'
+---
+title: Adopt authority-aware ranking
+type: decision
+tags: [architecture]
+status: locked
+created: 2026-01-22
+---
+# Adopt authority-aware ranking
+
+An agent quoted a retired price from [[pricing-2025]]. Search ranked it above the live note
+because both use the word "price" equally often.
+
+**Decision:** rank by relevance x authority. Retired notes are withheld from search and reported
+with a reason.
+EOF
+
+w decisions/move-to-whatsapp-first.md <<'EOF'
+---
+title: WhatsApp-first client comms
+type: decision
+tags: [ops]
+status: proposed
+created: 2026-06-30
+---
+# WhatsApp-first client comms
+
+> [!note] Proposed, not decided
+Draft. Do not quote as settled.
+EOF
+
+w decisions/deprecate-legacy-export.md <<'EOF'
+---
+title: Deprecate the legacy export
+type: decision
+tags: [product]
+status: locked
+created: 2026-04-03
+---
+# Deprecate the legacy export
+
+Legacy CSV export retired in favour of the JSON API. See [[archive/legacy-export]].
+EOF
+
+w clients/northwind/northwind.md <<'EOF'
+---
+title: Northwind Labs
+type: client
+tags: [client, active]
+status: active
+created: 2026-01-15
+related: ["[[maya-okonkwo]]"]
+---
+# Northwind Labs
+
+Contract signed 2026-01-15. Contact [[maya-okonkwo]].
+Pricing: see [[pricing-2026]].
+
+| Field | Value |
+|---|---|
+| Plan | Standard |
+| Started | 2026-01-15 |
+EOF
+
+w clients/northwind/northwind-integration.md <<'EOF'
+---
+title: Northwind integration notes
+type: doc
+tags: [client]
+status: active
+created: 2026-03-02
+---
+# Northwind integration notes
+
+Webhook endpoint live. Retry policy agreed at 5 attempts.
+Blocked on their SSO rollout, revisit after Q3.
+EOF
+
+w clients/vertex/vertex.md <<'EOF'
+---
+title: Vertex Systems
+type: client
+tags: [client, active]
+status: active
+created: 2026-02-28
+related: ["[[tomas-lindqvist]]"]
+---
+# Vertex Systems
+
+Contact [[tomas-lindqvist]]. Plus tier. Renewal 2027-02.
+EOF
+
+w people/maya-okonkwo.md <<'EOF'
+---
+title: Maya Okonkwo
+type: person
+tags: [contact]
+status: active
+created: 2026-01-15
+---
+# Maya Okonkwo
+
+Head of Platform at [[northwind]]. Main technical contact.
+Prefers async, reviews on Thursdays.
+EOF
+
+w people/tomas-lindqvist.md <<'EOF'
+---
+title: Tomas Lindqvist
+type: person
+tags: [contact]
+status: active
+created: 2026-02-28
+---
+# Tomas Lindqvist
+
+CTO at [[vertex]]. Decision maker on renewals.
+EOF
+
+w projects/atlas.md <<'EOF'
+---
+title: Atlas
+type: project
+tags: [project]
+status: active
+created: 2026-02-01
+---
+# Atlas
+
+Internal search rewrite. Depends on [[adopt-authority-ranking]].
+Owner: [[maya-okonkwo]] on the client side.
+EOF
+
+w projects/beacon.md <<'EOF'
+---
+title: Beacon
+type: project
+tags: [project]
+status: draft
+created: 2026-06-18
+---
+# Beacon
+
+Early exploration. Not committed.
+EOF
+
+w archive/legacy-export.md <<'EOF'
+---
+title: Legacy CSV export
+type: doc
+tags: [product]
+created: 2025-08-01
+---
+# Legacy CSV export
+
+Retired. Replaced by the JSON API. See [[deprecate-legacy-export]].
+EOF
+
+w archive/q1-forecast.md <<'EOF'
+---
+title: Q1 2025 forecast
+type: doc
+created: 2025-01-05
+---
+# Q1 2025 forecast
+
+Historical. Numbers superseded by actuals.
+EOF
+
+w SCHEMA.md <<'EOF'
+---
+title: Vault schema
+status: locked
+---
+# Vault schema
+
+Folders: `clients/` `decisions/` `projects/` `people/` `docs/` `archive/`
+
+`status:` drives ranking. `locked`/`canonical` outrank `current`; `draft`/`proposed` are demoted;
+`superseded` and anything under `archive/` are withheld from agents.
+EOF
+
+# --- fabricated git history: gives the Activity page real per-agent commits to show ---
+cd "$VAULT"
+git init -q -b main
+git config user.name "Engram"
+git config user.email "[email protected]"
+
+commit() { GIT_AUTHOR_DATE="$1" GIT_COMMITTER_DATE="$1" git commit -q -m "$2"; }
+
+git add SCHEMA.md docs/pricing-2025.md people docs/onboarding-runbook.md
+commit "2026-01-06T09:12:00" "ronalds: seed the vault"
+git add decisions/adopt-authority-ranking.md
+commit "2026-01-22T14:03:00" "claude-code: 1 change(s) — write decisions/adopt-authority-ranking.md"
+git add docs/pricing-2026.md
+commit "2026-01-08T11:55:00" "claude-code: supersede docs/pricing-2025.md -> docs/pricing-2026.md: repriced for the 2026 renewal"
+git add clients/northwind/northwind.md docs/support-sla.md
+commit "2026-02-02T10:41:00" "claude-code: 2 change(s) — write clients/northwind/northwind.md; write docs/support-sla.md"
+git add projects/atlas.md clients/vertex
+commit "2026-02-28T16:20:00" "cursor-agent: 2 change(s) — write projects/atlas.md; write clients/vertex/vertex.md"
+git add clients/northwind/northwind-integration.md docs/security-posture.md
+commit "2026-03-14T09:30:00" "teammate-agent (read-write): 2 change(s) — append clients/northwind/northwind-integration.md; write docs/security-posture.md"
+git add decisions/deprecate-legacy-export.md archive
+commit "2026-04-03T13:08:00" "claude-code: 3 change(s) — write decisions/deprecate-legacy-export.md; move docs/legacy-export.md -> archive/legacy-export.md"
+git add projects/beacon.md decisions/move-to-whatsapp-first.md
+commit "2026-06-30T08:44:00" "ronalds: 2 change(s) — write projects/beacon.md; write decisions/move-to-whatsapp-first.md"
+
+echo "[seed] vault ready at $VAULT ($(git rev-list --count HEAD) commits, $(find . -name '*.md' | wc -l | tr -d ' ') notes)"