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
feat: add-repo-by-URL+token (PAT path) + deploy docs for both GitHub paths
Ronalds Palacisaa15c4319ace
diff --git a/.gitignore b/.gitignoreindex 98ee58c..ea7dd92 100644--- a/.gitignore+++ b/.gitignore@@ -11,7 +11,8 @@ next-env.d.ts.DS_Store.vercel.gstack/-# local app state (token hashes) — never commit+# local app state (token hashes, github token, repo clones) — never commit.cortex/**/.cortex/+.cortex-data/sample-vault/.gitignorediff --git a/DEPLOY.md b/DEPLOY.mdindex 9e2c7f1..40d4cc0 100644--- a/DEPLOY.md+++ b/DEPLOY.md@@ -1,58 +1,65 @@# Deploying Cortex-Cortex deploys as one container. The **app** repo is this repo; the **vault** is a separate-remote repo the app clones + git-syncs into a volume. No machine keeps a local vault copy.+Cortex deploys as one container (this repo). Vault repos are **connected in the dashboard**+(Workspaces) — no repo lives in this repo, and no laptop keeps a vault copy. The active+workspace is what the dashboard shows and what agents read/write.## 1. Push this repo to GitHub-Already a git repo. Create a remote (private is fine) and push `main`.+Already a git repo — create a remote and push `main`.-## 2. Create the vault repo (if you don't have one)-A separate repo of markdown (e.g. `youruser/second-brain`). Cortex clones it into its volume.-Give it the folders in `SCHEMA.md` (`clients/`, `decisions/`, …).+## 2. Dashboard login — Google OAuth+1. Google Cloud Console → Credentials → Create OAuth client ID → Web application.+2. Redirect URI: `https://<your-app>.up.railway.app/api/auth/callback`+3. Copy the Client ID + Secret.-## 3. Google OAuth (dashboard login)-1. Google Cloud Console → **APIs & Services → Credentials → Create OAuth client ID** → **Web application**.-2. **Authorized redirect URI:** `https://<your-app>.up.railway.app/api/auth/callback`-3. Copy the **Client ID** and **Client secret**.--## 4. Railway-1. **New Project → Deploy from GitHub repo** → this repo. It builds via the root `Dockerfile`.+## 3. Railway+1. **New Project → Deploy from GitHub repo** → this repo (builds via root `Dockerfile`).2. **Add a Volume**, mount path `/data`.3. **Variables:**| Variable | Value ||---|---|| `NEXT_PUBLIC_APP_NAME` | e.g. `Klyiro Brain` |-| `VAULT_DIR` | `/data` |-| `GIT_REMOTE` | the vault repo URL (`https://github.com/youruser/second-brain.git`) |-| `GIT_TOKEN` | GitHub token with **push** access to the vault repo |-| `GIT_SYNC_ENABLED` | `true` |+| `CORTEX_DATA_DIR` | `/data` (app state + vault clones live here) |+| `GIT_SYNC_ENABLED` | `true` (auto commit+push the active vault) || `GIT_AUTHOR_NAME` / `GIT_AUTHOR_EMAIL` | commit identity |-| `AUTH_SECRET` | `openssl rand -base64 32` |+| `AUTH_SECRET` | `openssl rand -base64 32`, or Railway "Generate" || `APP_URL` | `https://<your-app>.up.railway.app` |-| `ALLOWED_EMAILS` | comma-separated team emails |-| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | from step 3 |-| `MCP_TOKEN` | a long random string (agents send this) |-| `ANTHROPIC_API_KEY` | for `brain_capture` (optional) |+| `ALLOWED_EMAILS` | comma-separated team emails (Google login) |+| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | from step 2 |+| `ANTHROPIC_API_KEY` + `HARNESS_ENABLED=true` | optional, for `brain_capture` |+| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | optional — see step 5 (OAuth path) |++Deploy, then sign in with Google.++## 4. Connect a vault repo (in the dashboard → Workspaces)+Two ways — pick one:++- **URL + token (zero setup):** paste the repo URL + a GitHub token with access. Works with+ no GitHub OAuth app — the simplest path, especially for self-hosting.+- **Connect GitHub (nicer):** if you set the GitHub OAuth app in step 5, click *Connect GitHub*+ and pick a repo from a list.-4. Deploy. On first boot the app clones `GIT_REMOTE` into `/data`. The dashboard is gated by- Google login (allowlist); the MCP is gated by `MCP_TOKEN`.+Add repos, switch the active one, remove — all in the UI. MCP tokens (per teammate/agent) are+created on the **Connect** page.-## 5. Connect agents to the MCP-**Claude Code:**+## 5. (Optional) GitHub OAuth app — for the "Connect GitHub" flow+Each deployment uses **its own** GitHub OAuth app (secrets can't be shared, and the callback is+host-specific — so there's no shared central app for self-hosters):+1. GitHub → Settings → Developer settings → **OAuth Apps → New OAuth App**.+2. **Authorization callback URL:** `https://<your-app>.up.railway.app/api/github/callback`+3. Set `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` in Railway.++Skip this entirely if you use the URL + token path in step 4.++## 6. Connect agents to the MCP+Dashboard → **Connect** → copy the command. Agents always hit the same endpoint and only ever+see the **active** vault:```bashclaude mcp add --transport http cortex https://<your-app>.up.railway.app/api/mcp \- --header "Authorization: Bearer $MCP_TOKEN"-```-**Hermes** (`~/.hermes/config.yaml`):-```yaml-mcp_servers:- cortex:- url: https://<your-app>.up.railway.app/api/mcp- headers:- Authorization: "Bearer <MCP_TOKEN>"+ --header "Authorization: Bearer <token from the Connect page>"```## Notes-- **No auth locally:** leave `AUTH_SECRET` empty (or `AUTH_DISABLED=true`) and the dashboard is open.-- **Security:** never expose the MCP without `MCP_TOKEN`. Rotate `GIT_TOKEN` if leaked.+- **No auth locally:** leave `AUTH_SECRET` empty (or `AUTH_DISABLED=true`) and the dashboard is open; the MCP is open until a token exists.+- Git tokens are stored **encrypted** at rest (keyed off `AUTH_SECRET`); token hashes and vault clones live under `CORTEX_DATA_DIR`, never in a vault repo.diff --git a/app/(app)/workspaces/page.tsx b/app/(app)/workspaces/page.tsxindex 909ad1a..fe0b9e2 100644--- a/app/(app)/workspaces/page.tsx+++ b/app/(app)/workspaces/page.tsx@@ -31,6 +31,7 @@ export default function WorkspacesPage() {const { mutate } = useSWRConfig();const [busy, setBusy] = useState<string | null>(null);const [err, setErr] = useState("");+ const [manual, setManual] = useState({ url: "", token: "", name: "" });const repos = reposData?.repos ?? [];const addedNames = new Set(repos.map((r) => r.fullName));@@ -51,6 +52,31 @@ export default function WorkspacesPage() {setBusy(null);}}+ async function addManual() {+ if (!manual.url.trim()) return;+ setBusy("manual");+ setErr("");+ try {+ const res = await fetch("/api/repos", {+ method: "POST",+ headers: { "content-type": "application/json" },+ body: JSON.stringify({+ cloneUrl: manual.url.trim(),+ token: manual.token.trim() || undefined,+ name: manual.name.trim() || undefined,+ }),+ });+ const d = await res.json();+ if (!res.ok) setErr(d.error || "add failed");+ else {+ setManual({ url: "", token: "", name: "" });+ refresh(mutate);+ }+ } finally {+ setBusy(null);+ }+ }+async function switchTo(id: string) {await fetch("/api/repos/active", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ id }) });refresh(mutate);@@ -123,9 +149,48 @@ export default function WorkspacesPage() {)}</section>+ <section className="mt-8 space-y-2">+ <h2 className="text-sm font-medium">Add a repo by URL + token</h2>+ <p className="text-sm text-muted-foreground">+ Paste a repo URL and a GitHub token with access to it. Works without connecting GitHub — the+ zero-setup path for self-hosting.+ </p>+ {err && <p className="text-xs text-destructive">{err}</p>}+ <div className="space-y-2">+ <input+ value={manual.url}+ onChange={(e) => setManual((m) => ({ ...m, url: e.target.value }))}+ placeholder="https://github.com/you/vault.git"+ className="w-full rounded-md border border-border bg-background px-2.5 py-1.5 text-sm outline-none placeholder:text-muted-foreground"+ />+ <input+ value={manual.token}+ onChange={(e) => setManual((m) => ({ ...m, token: e.target.value }))}+ type="password"+ placeholder="GitHub token with repo access (for private repos / push)"+ className="w-full rounded-md border border-border bg-background px-2.5 py-1.5 text-sm outline-none placeholder:text-muted-foreground"+ />+ <div className="flex gap-2">+ <input+ value={manual.name}+ onChange={(e) => setManual((m) => ({ ...m, name: e.target.value }))}+ placeholder="name (optional)"+ className="w-56 rounded-md border border-border bg-background px-2.5 py-1.5 text-sm outline-none placeholder:text-muted-foreground"+ />+ <button+ onClick={addManual}+ disabled={busy === "manual"}+ className="rounded-md bg-primary px-3 py-1.5 text-sm font-medium text-primary-foreground disabled:opacity-50"+ >+ {busy === "manual" ? "Adding…" : "Add repo"}+ </button>+ </div>+ </div>+ </section>+{gh?.connected && (<section className="mt-8 space-y-2">- <h2 className="text-sm font-medium">Add a repo</h2>+ <h2 className="text-sm font-medium">Add from GitHub</h2>{err && <p className="text-xs text-destructive">{err}</p>}<div className="scrollbar-none max-h-96 overflow-y-auto overflow-hidden rounded-lg border border-border"><table className="w-full text-sm">diff --git a/app/api/repos/route.ts b/app/api/repos/route.tsindex 7a66d89..a168304 100644--- a/app/api/repos/route.ts+++ b/app/api/repos/route.ts@@ -9,17 +9,23 @@ export function GET() {}export async function POST(req: Request) {- const { fullName, cloneUrl, branch, setActive } = await req.json().catch(() => ({}));- const url = cloneUrl || (fullName ? `https://github.com/${fullName}.git` : "");- if (!url) return Response.json({ error: "cloneUrl or fullName required" }, { status: 400 });+ const b = await req.json().catch(() => ({}));+ const url = b.cloneUrl || b.url || (b.fullName ? `https://github.com/${b.fullName}.git` : "");+ if (!url) return Response.json({ error: "repo url or fullName required" }, { status: 400 });+ // "owner/repo" derived from the URL, for a nice default name.+ const derived = String(url)+ .replace(/^https?:\/\/[^/]+\//, "")+ .replace(/^git@[^:]+:/, "")+ .replace(/\.git$/, "");try {const repo = await addRepo({- name: fullName || url,- fullName,+ name: b.name || b.fullName || derived || url,+ fullName: b.fullName || (derived.includes("/") ? derived : undefined),url,- token: githubToken() ?? undefined,- branch,- setActive,+ // Explicit pasted token (PAT path) wins; else the OAuth-connected token.+ token: b.token || githubToken() || undefined,+ branch: b.branch,+ setActive: b.setActive,});rebuildIndex();return Response.json({ ok: true, repo });