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.

W1: dynamic vault dir + workspace store (foundation)

Ronalds Palacis1fae0a436234
diff --git a/instrumentation.ts b/instrumentation.ts
index 9d3c26b..19cde38 100644
--- a/instrumentation.ts
+++ b/instrumentation.ts
@@ -1,7 +1,7 @@
-// Runs once when the server starts. Used to clone the remote vault into VAULT_DIR
-// on first boot (production). No-op unless GIT_SYNC_ENABLED + GIT_REMOTE are set.
+// Runs once when the server starts. Re-clones the active workspace's vault into its
+// dir if missing (e.g. a fresh volume). No-op when no workspace is configured.
export async function register() {
if (process.env.NEXT_RUNTIME !== "nodejs") return;
- const { ensureVaultRepo } = await import("@/lib/git");
- await ensureVaultRepo();
+ const { ensureActiveCloned } = await import("@/lib/repos");
+ await ensureActiveCloned();
}
diff --git a/lib/config.ts b/lib/config.ts
index 37d27de..7767124 100644
--- a/lib/config.ts
+++ b/lib/config.ts
@@ -13,6 +13,14 @@ export const VAULT_DIR = process.env.VAULT_DIR
? path.resolve(process.env.VAULT_DIR)
: path.resolve(process.cwd(), "sample-vault");
+/**
+ * Fixed data dir for app state + managed vault clones (repos.json, tokens.json,
+ * vaults/<id>/). Separate from any vault's content. On Railway set to the volume, e.g. /data.
+ */
+export const DATA_ROOT = process.env.CORTEX_DATA_DIR
+ ? path.resolve(process.env.CORTEX_DATA_DIR)
+ : path.resolve(process.cwd(), ".cortex-data");
+
/** Directory names never treated as vault content (app code, git internals, build output). */
export const VAULT_IGNORE = new Set(
(process.env.VAULT_IGNORE ?? "app,.git,node_modules,.next,.github,infra")
@@ -40,6 +48,10 @@ export const APP_URL = process.env.APP_URL ?? "http://localhost:3000";
export const GOOGLE_CLIENT_ID = process.env.GOOGLE_CLIENT_ID ?? "";
export const GOOGLE_CLIENT_SECRET = process.env.GOOGLE_CLIENT_SECRET ?? "";
+/** GitHub OAuth app — for connecting vault repos from the dashboard. */
+export const GITHUB_CLIENT_ID = process.env.GITHUB_CLIENT_ID ?? "";
+export const GITHUB_CLIENT_SECRET = process.env.GITHUB_CLIENT_SECRET ?? "";
+
export const SESSION_COOKIE = "cortex_session";
/** When true, the git-sync loop commits + pushes vault changes to the remote. */
diff --git a/lib/crypto.ts b/lib/crypto.ts
new file mode 100644
index 0000000..03a5c9f
--- /dev/null
+++ b/lib/crypto.ts
@@ -0,0 +1,29 @@
+import crypto from "node:crypto";
+import { AUTH_SECRET } from "@/lib/config";
+
+function key(): Buffer | null {
+ if (!AUTH_SECRET) return null;
+ return crypto.createHash("sha256").update(AUTH_SECRET).digest();
+}
+
+/** Encrypt a secret (e.g. a git token) at rest with AES-256-GCM keyed off AUTH_SECRET.
+ * Falls back to base64 (obfuscated, not encrypted) when AUTH_SECRET is unset (local dev). */
+export function encryptSecret(plain: string): string {
+ const k = key();
+ if (!k) return `plain:${Buffer.from(plain, "utf8").toString("base64")}`;
+ const iv = crypto.randomBytes(12);
+ const cipher = crypto.createCipheriv("aes-256-gcm", k, iv);
+ const enc = Buffer.concat([cipher.update(plain, "utf8"), cipher.final()]);
+ const tag = cipher.getAuthTag();
+ return `gcm:${iv.toString("base64")}:${tag.toString("base64")}:${enc.toString("base64")}`;
+}
+
+export function decryptSecret(stored: string): string {
+ if (stored.startsWith("plain:")) return Buffer.from(stored.slice(6), "base64").toString("utf8");
+ const [, ivB, tagB, dataB] = stored.split(":");
+ const k = key();
+ if (!k) throw new Error("AUTH_SECRET required to decrypt stored secret");
+ const decipher = crypto.createDecipheriv("aes-256-gcm", k, Buffer.from(ivB, "base64"));
+ decipher.setAuthTag(Buffer.from(tagB, "base64"));
+ return Buffer.concat([decipher.update(Buffer.from(dataB, "base64")), decipher.final()]).toString("utf8");
+}
diff --git a/lib/git.ts b/lib/git.ts
index 1fa02eb..2ba64a4 100644
--- a/lib/git.ts
+++ b/lib/git.ts
@@ -1,42 +1,12 @@
-import fs from "node:fs";
-import path from "node:path";
-import { simpleGit, type SimpleGit } from "simple-git";
-import { VAULT_DIR, GIT_SYNC_ENABLED } from "@/lib/config";
-
-/**
- * On boot: if GIT_SYNC is on and VAULT_DIR isn't yet a git repo, clone GIT_REMOTE
- * into it. This is how the deployed app populates its volume from the remote vault
- * repo — so no machine keeps a local copy, the server just checks one out.
- */
-export async function ensureVaultRepo(): Promise<void> {
- if (!GIT_SYNC_ENABLED) return;
- const remote = process.env.GIT_REMOTE;
- if (!remote) return;
- if (fs.existsSync(path.join(VAULT_DIR, ".git"))) return;
- const token = process.env.GIT_TOKEN;
- const url = token && remote.startsWith("https://")
- ? remote.replace("https://", `https://x-access-token:${token}@`)
- : remote;
- try {
- fs.mkdirSync(VAULT_DIR, { recursive: true });
- await simpleGit().clone(url, VAULT_DIR);
- console.log(`[git] cloned vault repo into ${VAULT_DIR}`);
- } catch (e) {
- console.error("[git] vault clone failed", e);
- }
-}
-
-let git: SimpleGit | null = null;
-function getGit(): SimpleGit {
- if (!git) git = simpleGit(VAULT_DIR);
- return git;
-}
+import { simpleGit } from "simple-git";
+import { GIT_SYNC_ENABLED } from "@/lib/config";
+import { activeVaultDir } from "@/lib/repos";
let timer: ReturnType<typeof setTimeout> | null = null;
let pending: string[] = [];
let running = false;
-/** Debounced commit + pull --rebase + push of vault changes. No-op unless GIT_SYNC_ENABLED. */
+/** Debounced commit + pull --rebase + push of the ACTIVE vault. No-op unless GIT_SYNC_ENABLED. */
export function requestSync(reason: string): void {
if (!GIT_SYNC_ENABLED) return;
pending.push(reason);
@@ -54,7 +24,7 @@ async function runSync(): Promise<void> {
const reasons = pending;
pending = [];
try {
- const g = getGit();
+ const g = simpleGit(activeVaultDir());
await g.add(["-A"]);
const status = await g.status();
if (status.files.length === 0) {
@@ -92,7 +62,7 @@ async function runSync(): Promise<void> {
export async function syncStatus() {
if (!GIT_SYNC_ENABLED) return { enabled: false as const };
try {
- const s = await getGit().status();
+ const s = await simpleGit(activeVaultDir()).status();
return { enabled: true as const, dirty: s.files.length, ahead: s.ahead, behind: s.behind, branch: s.current };
} catch {
return { enabled: true as const, error: true };
diff --git a/lib/repos.ts b/lib/repos.ts
new file mode 100644
index 0000000..49a7ba3
--- /dev/null
+++ b/lib/repos.ts
@@ -0,0 +1,138 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { simpleGit } from "simple-git";
+import { DATA_ROOT, VAULT_DIR } from "@/lib/config";
+import { decryptSecret, encryptSecret } from "@/lib/crypto";
+
+const REPOS_FILE = path.join(DATA_ROOT, "repos.json");
+const VAULTS_DIR = path.join(DATA_ROOT, "vaults");
+
+export interface Repo {
+ id: string;
+ name: string;
+ fullName?: string;
+ url: string;
+ branch: string;
+ active: boolean;
+ addedAt: string;
+}
+interface StoredRepo extends Repo {
+ tokenEnc?: string;
+}
+
+function ensureData() {
+ fs.mkdirSync(VAULTS_DIR, { recursive: true });
+}
+function load(): StoredRepo[] {
+ try {
+ return JSON.parse(fs.readFileSync(REPOS_FILE, "utf8"));
+ } catch {
+ return [];
+ }
+}
+function save(repos: StoredRepo[]) {
+ ensureData();
+ fs.writeFileSync(REPOS_FILE, JSON.stringify(repos, null, 2));
+}
+const strip = ({ tokenEnc, ...r }: StoredRepo): Repo => r;
+
+export function vaultDirFor(id: string): string {
+ return path.join(VAULTS_DIR, id);
+}
+
+/** The active vault dir — the active workspace's clone, or the fallback VAULT_DIR (sample/local). */
+export function activeVaultDir(): string {
+ const active = load().find((r) => r.active);
+ return active ? vaultDirFor(active.id) : VAULT_DIR;
+}
+
+export function listRepos(): Repo[] {
+ return load().map(strip);
+}
+export function getActive(): Repo | null {
+ const a = load().find((r) => r.active);
+ return a ? strip(a) : null;
+}
+export function repoToken(id: string): string | null {
+ const r = load().find((x) => x.id === id);
+ if (!r?.tokenEnc) return null;
+ try {
+ return decryptSecret(r.tokenEnc);
+ } catch {
+ return null;
+ }
+}
+export function activeRepoToken(): string | null {
+ const a = load().find((r) => r.active);
+ return a ? repoToken(a.id) : null;
+}
+
+function authedUrl(url: string, token?: string): string {
+ return token && url.startsWith("https://")
+ ? url.replace("https://", `https://x-access-token:${token}@`)
+ : url;
+}
+
+export async function addRepo(opts: {
+ name: string;
+ url: string;
+ token?: string;
+ branch?: string;
+ fullName?: string;
+ setActive?: boolean;
+}): Promise<Repo> {
+ ensureData();
+ const id = crypto.randomUUID();
+ const all = load();
+ const makeActive = opts.setActive ?? all.length === 0;
+ if (makeActive) all.forEach((r) => (r.active = false));
+
+ const dir = vaultDirFor(id);
+ fs.rmSync(dir, { recursive: true, force: true });
+ await simpleGit().clone(authedUrl(opts.url, opts.token), dir);
+
+ const rec: StoredRepo = {
+ id,
+ name: opts.name,
+ fullName: opts.fullName,
+ url: opts.url,
+ branch: opts.branch || "main",
+ active: makeActive,
+ addedAt: new Date().toISOString(),
+ tokenEnc: opts.token ? encryptSecret(opts.token) : undefined,
+ };
+ all.push(rec);
+ save(all);
+ return strip(rec);
+}
+
+export function setActive(id: string): void {
+ const all = load();
+ if (!all.some((r) => r.id === id)) return;
+ all.forEach((r) => (r.active = r.id === id));
+ save(all);
+}
+
+export function removeRepo(id: string): void {
+ save(load().filter((r) => r.id !== id));
+ try {
+ fs.rmSync(vaultDirFor(id), { recursive: true, force: true });
+ } catch {
+ /* ignore */
+ }
+}
+
+/** Re-clone the active repo if its working dir is missing (e.g. fresh volume). */
+export async function ensureActiveCloned(): Promise<void> {
+ const a = load().find((r) => r.active);
+ if (!a) return;
+ const dir = vaultDirFor(a.id);
+ if (fs.existsSync(path.join(dir, ".git"))) return;
+ try {
+ fs.rmSync(dir, { recursive: true, force: true });
+ await simpleGit().clone(authedUrl(a.url, a.tokenEnc ? decryptSecret(a.tokenEnc) : undefined), dir);
+ } catch (e) {
+ console.error("[repos] re-clone failed", e);
+ }
+}
diff --git a/lib/tokens.ts b/lib/tokens.ts
index 6a9b31f..17f61a2 100644
--- a/lib/tokens.ts
+++ b/lib/tokens.ts
@@ -1,11 +1,10 @@
import crypto from "node:crypto";
import fs from "node:fs";
import path from "node:path";
-import { VAULT_DIR } from "@/lib/config";
+import { DATA_ROOT } from "@/lib/config";
-// App state (token hashes) lives beside the vault but is kept OUT of the vault's
-// git history — so per-teammate keys never land in the knowledge repo.
-const STATE_DIR = process.env.CORTEX_STATE_DIR || path.join(VAULT_DIR, ".cortex");
+// App state (token hashes) lives in the fixed data dir, separate from any vault content.
+const STATE_DIR = process.env.CORTEX_STATE_DIR || DATA_ROOT;
const TOKENS_FILE = path.join(STATE_DIR, "tokens.json");
interface StoredToken {
@@ -25,21 +24,6 @@ const hash = (t: string) => crypto.createHash("sha256").update(t).digest("hex");
function ensureStateDir() {
fs.mkdirSync(STATE_DIR, { recursive: true });
- // Make sure git-sync never commits the state dir into the vault repo.
- try {
- const gi = path.join(VAULT_DIR, ".gitignore");
- let content = "";
- try {
- content = fs.readFileSync(gi, "utf8");
- } catch {
- /* none yet */
- }
- if (!content.split(/\r?\n/).some((l) => l.trim() === ".cortex/")) {
- fs.writeFileSync(gi, `${content && !content.endsWith("\n") ? `${content}\n` : content}.cortex/\n`);
- }
- } catch {
- /* best effort */
- }
}
function load(): StoredToken[] {
diff --git a/lib/vault/scan.ts b/lib/vault/scan.ts
index e125db4..6112681 100644
--- a/lib/vault/scan.ts
+++ b/lib/vault/scan.ts
@@ -1,6 +1,7 @@
import fs from "node:fs";
import path from "node:path";
-import { VAULT_DIR, VAULT_IGNORE } from "@/lib/config";
+import { VAULT_IGNORE } from "@/lib/config";
+import { activeVaultDir } from "@/lib/repos";
export interface ScannedFile {
rel: string;
@@ -9,7 +10,7 @@ export interface ScannedFile {
}
/** Recursively collect .md files under the vault, skipping ignored + dot dirs. */
-export function scanVault(root = VAULT_DIR): ScannedFile[] {
+export function scanVault(root = activeVaultDir()): ScannedFile[] {
const out: ScannedFile[] = [];
function walk(dir: string) {
diff --git a/lib/vault/store.ts b/lib/vault/store.ts
index f11b803..1752c57 100644
--- a/lib/vault/store.ts
+++ b/lib/vault/store.ts
@@ -2,12 +2,14 @@ import fs from "node:fs";
import path from "node:path";
import MiniSearch from "minisearch";
import { watch, type FSWatcher } from "chokidar";
-import { VAULT_DIR, VAULT_IGNORE } from "@/lib/config";
+import { VAULT_IGNORE } from "@/lib/config";
+import { activeVaultDir } from "@/lib/repos";
import { scanVault } from "./scan";
import { parseNote, stemOf } from "./parse";
import type { Graph, GraphEdge, GraphNode, Note, NoteMeta, TreeNode } from "./types";
interface IndexState {
+ dir: string;
notes: Map<string, NoteMeta>;
stemToPath: Map<string, string>;
outEdges: Map<string, Set<string>>;
@@ -18,12 +20,14 @@ interface IndexState {
let state: IndexState | null = null;
let watcher: FSWatcher | null = null;
+let watchedDir = "";
function buildState(): IndexState {
- const files = scanVault();
+ const dir = activeVaultDir();
+ const files = scanVault(dir);
const notes = new Map<string, NoteMeta>();
const stemToPath = new Map<string, string>();
- const linksBySource = new Map<string, string[]>(); // src path -> target stems
+ const linksBySource = new Map<string, string[]>();
const docs: Array<{ id: string; title: string; tags: string; body: string; folder: string; type: string }> = [];
for (const f of files) {
@@ -63,13 +67,18 @@ function buildState(): IndexState {
});
search.addAll(docs);
- return { notes, stemToPath, outEdges, inEdges, search, builtAt: Date.now() };
+ return { dir, notes, stemToPath, outEdges, inEdges, search, builtAt: Date.now() };
}
-function startWatcher() {
- if (watcher) return;
+function startWatcher(dir: string) {
+ if (watcher && watchedDir === dir) return;
+ if (watcher) {
+ watcher.close().catch(() => {});
+ watcher = null;
+ }
+ watchedDir = dir;
try {
- watcher = watch(VAULT_DIR, {
+ watcher = watch(dir, {
ignoreInitial: true,
persistent: true,
depth: 12,
@@ -97,16 +106,16 @@ function startWatcher() {
}
function ensure(): IndexState {
- if (!state) {
- state = buildState();
- startWatcher();
- }
+ const dir = activeVaultDir();
+ if (!state || state.dir !== dir) state = buildState();
+ startWatcher(dir);
return state;
}
-/** Force a synchronous rebuild (call after a write). */
+/** Force a synchronous rebuild (after a write or a workspace switch). */
export function rebuildIndex(): void {
state = buildState();
+ startWatcher(state.dir);
}
export function listNotes(): NoteMeta[] {
@@ -115,7 +124,7 @@ export function listNotes(): NoteMeta[] {
export function getNote(relPath: string): Note | null {
const s = ensure();
- const abs = path.join(VAULT_DIR, relPath);
+ const abs = path.join(s.dir, relPath);
let raw: string;
try {
raw = fs.readFileSync(abs, "utf8");
@@ -207,10 +216,10 @@ export function getTree(): TreeNode {
return root;
}
-/** Read a top-level meta file (SCHEMA.md / INDEX.md) verbatim, or null. */
+/** Read a top-level meta file (SCHEMA.md / INDEX.md) from the active vault, or null. */
export function readVaultFile(name: string): string | null {
try {
- return fs.readFileSync(path.join(VAULT_DIR, name), "utf8");
+ return fs.readFileSync(path.join(activeVaultDir(), name), "utf8");
} catch {
return null;
}
diff --git a/lib/vault/write.ts b/lib/vault/write.ts
index f540fd8..669b2d0 100644
--- a/lib/vault/write.ts
+++ b/lib/vault/write.ts
@@ -1,14 +1,14 @@
import fsp from "node:fs/promises";
import path from "node:path";
import matter from "gray-matter";
-import { VAULT_DIR } from "@/lib/config";
+import { activeVaultDir } from "@/lib/repos";
import { rebuildIndex } from "./store";
import { requestSync } from "@/lib/git";
-/** Resolve a vault-relative path to an absolute path, refusing escapes. */
+/** Resolve a vault-relative path to an absolute path in the active vault, refusing escapes. */
function safeAbs(relPath: string): string {
- const abs = path.resolve(VAULT_DIR, relPath);
- const root = path.resolve(VAULT_DIR);
+ const root = path.resolve(activeVaultDir());
+ const abs = path.resolve(root, relPath);
if (abs !== root && !abs.startsWith(root + path.sep)) throw new Error("path escapes the vault");
return abs;
}