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
W1: dynamic vault dir + workspace store (foundation)
Ronalds Palacis1fae0a436234
diff --git a/instrumentation.ts b/instrumentation.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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;}