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(tokens): read/write scopes + write provenance; fix silent git-sync failure
Ronalds Palacise34a4647cbf9
diff --git a/app/api/mcp/route.ts b/app/api/mcp/route.tsindex ed61ddf..fd5b1c9 100644--- a/app/api/mcp/route.ts+++ b/app/api/mcp/route.ts@@ -1,7 +1,8 @@import { MCP_TOKEN } from "@/lib/config";import { harnessEnabled } from "@/lib/settings";-import { hasAnyToken, verifyToken } from "@/lib/tokens";+import { hasAnyToken, resolveToken, type TokenScope } from "@/lib/tokens";import { oauthEnabled, verifyAccessToken, wwwAuthenticate } from "@/lib/oauth";+import { withActor } from "@/lib/actor";import { TOOLS, TOOL_MAP } from "@/lib/mcp/tools";export const dynamic = "force-dynamic";@@ -11,6 +12,12 @@ const PROTOCOL = "2025-06-18";// eslint-disable-next-line @typescript-eslint/no-explicit-anytype Json = any;+/** The authenticated caller: a name for the audit trail, and what it may do. */+interface Caller {+ name: string;+ scope: TokenScope;+}+function rpc(id: Json, result?: Json, error?: Json) {const msg: Json = { jsonrpc: "2.0", id: id ?? null };if (error) msg.error = error;@@ -18,7 +25,7 @@ function rpc(id: Json, result?: Json, error?: Json) {return msg;}-async function handleMessage(msg: Json): Promise<Json | null> {+async function handleMessage(msg: Json, caller: Caller): Promise<Json | null> {const method: string | undefined = msg?.method;const id = msg?.id;const params = msg?.params;@@ -35,8 +42,14 @@ async function handleMessage(msg: Json): Promise<Json | null> {case "ping":return rpc(id, {});case "tools/list": {- // Hide the auto-filing harness unless it's turned on (agents file notes themselves).- const tools = TOOLS.filter((t) => t.name !== "brain_capture" || harnessEnabled());+ // A read-only token never sees the write tools — it cannot be tempted to call them,+ // and the model never wastes a turn discovering it is forbidden.+ // The auto-filing harness stays hidden unless it's turned on (agents file notes themselves).+ const tools = TOOLS.filter((t) => {+ if (t.name === "brain_capture" && !harnessEnabled()) return false;+ if (t.write && caller.scope !== "write") return false;+ return true;+ });return rpc(id, {tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),});@@ -44,8 +57,18 @@ async function handleMessage(msg: Json): Promise<Json | null> {case "tools/call": {const tool = TOOL_MAP.get(params?.name);if (!tool) return rpc(id, undefined, { code: -32602, message: `unknown tool: ${params?.name}` });+ if (tool.write && caller.scope !== "write") {+ return rpc(id, undefined, {+ code: -32001,+ message: `${tool.name} mutates the vault, and this token is read-only. Ask the operator for a write token.`,+ });+ }+ if (tool.name === "brain_capture" && !harnessEnabled()) {+ return rpc(id, undefined, { code: -32601, message: "brain_capture is off — the operator has not enabled it." });+ }try {- const out = await tool.handler(params?.arguments ?? {});+ // Stamp every write this call causes with the caller's name, for the git audit trail.+ const out = await withActor(caller.name, () => tool.handler(params?.arguments ?? {}));const text = typeof out === "string" ? out : JSON.stringify(out, null, 2);return rpc(id, { content: [{ type: "text", text }] });} catch (e) {@@ -61,13 +84,19 @@ function jsonResponse(body: Json, status = 200) {return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });}-/** A credential is valid if it matches the shared token, a per-teammate token, or a live OAuth access token. */-async function authOk(token: string): Promise<boolean> {- if (!token) return false;- if (MCP_TOKEN !== "" && token === MCP_TOKEN) return true;- if (verifyToken(token)) return true;- if (oauthEnabled() && (await verifyAccessToken(token))) return true;- return false;+/**+ * Resolve a credential to a caller, or null when it is not valid. A named per-teammate token+ * carries its own scope; the shared env token and OAuth sessions are full-access, and an+ * unauthenticated local instance (no auth configured at all) is treated as the operator.+ */+async function authenticate(token: string, authRequired: boolean): Promise<Caller | null> {+ if (!authRequired) return { name: "local", scope: "write" };+ if (!token) return null;+ if (MCP_TOKEN !== "" && token === MCP_TOKEN) return { name: "shared-token", scope: "write" };+ const named = resolveToken(token);+ if (named) return { name: named.name, scope: named.scope };+ if (oauthEnabled() && (await verifyAccessToken(token))) return { name: "oauth", scope: "write" };+ return null;}/** 401 that also advertises the OAuth flow (WWW-Authenticate) so connectors can discover it. */@@ -82,7 +111,8 @@ export async function POST(req: Request) {// locally when nothing is set. On failure, advertise OAuth so Claude.ai can connect.const token = (req.headers.get("authorization") || "").replace(/^Bearer\s+/i, "").trim();const authRequired = MCP_TOKEN !== "" || hasAnyToken() || oauthEnabled();- if (authRequired && !(await authOk(token))) return unauthorized();+ const caller = await authenticate(token, authRequired);+ if (!caller) return unauthorized();let body: Json;try {@@ -92,10 +122,10 @@ export async function POST(req: Request) {}if (Array.isArray(body)) {- const out = (await Promise.all(body.map(handleMessage))).filter(Boolean);+ const out = (await Promise.all(body.map((m) => handleMessage(m, caller)))).filter(Boolean);return out.length === 0 ? new Response(null, { status: 202 }) : jsonResponse(out);}- const res = await handleMessage(body);+ const res = await handleMessage(body, caller);return res ? jsonResponse(res) : new Response(null, { status: 202 });}diff --git a/app/api/notes/[...path]/route.ts b/app/api/notes/[...path]/route.tsindex a1ec8ad..0f99f78 100644--- a/app/api/notes/[...path]/route.ts+++ b/app/api/notes/[...path]/route.ts@@ -1,9 +1,21 @@+import { SESSION_COOKIE } from "@/lib/config";+import { verifySessionToken } from "@/lib/auth";+import { withActor } from "@/lib/actor";import { getBacklinks, getNote, getOutlinks } from "@/lib/vault/store";import { checkFrontmatter } from "@/lib/vault/validate";import { deleteNote, writeNoteRaw } from "@/lib/vault/write";export const dynamic = "force-dynamic";+/** Attribute dashboard writes to the signed-in human, so the git log is not anonymous. */+async function actorFor(req: Request): Promise<string> {+ const cookie = req.headers.get("cookie") ?? "";+ const raw = cookie.split(";").map((c) => c.trim()).find((c) => c.startsWith(`${SESSION_COOKIE}=`));+ if (!raw) return "dashboard";+ const session = await verifySessionToken(raw.slice(SESSION_COOKIE.length + 1));+ return session?.email ? `dashboard (${session.email})` : "dashboard";+}+export async function GET(_req: Request, { params }: { params: Promise<{ path: string[] }> }) {const { path } = await params;const rel = path.map(decodeURIComponent).join("/");@@ -19,7 +31,8 @@ export async function PUT(req: Request, { params }: { params: Promise<{ path: stif (typeof content !== "string") return Response.json({ error: "content (string) required" }, { status: 400 });// Non-strict: a human may autosave half-typed frontmatter. Save it, but tell them it is broken —// otherwise the note silently loses its status and tags. (Agents are refused; see lib/mcp/tools.ts.)- const saved = await writeNoteRaw(rel, content);+ const actor = await actorFor(req);+ const saved = await withActor(actor, () => writeNoteRaw(rel, content));const check = checkFrontmatter(content);return Response.json({ok: true,@@ -32,9 +45,10 @@ export async function PUT(req: Request, { params }: { params: Promise<{ path: st});}-export async function DELETE(_req: Request, { params }: { params: Promise<{ path: string[] }> }) {+export async function DELETE(req: Request, { params }: { params: Promise<{ path: string[] }> }) {const { path } = await params;const rel = path.map(decodeURIComponent).join("/");- await deleteNote(rel);+ const actor = await actorFor(req);+ await withActor(actor, () => deleteNote(rel));return Response.json({ ok: true });}diff --git a/app/api/tokens/route.ts b/app/api/tokens/route.tsindex 4b7fc2a..a1dc61a 100644--- a/app/api/tokens/route.ts+++ b/app/api/tokens/route.ts@@ -7,7 +7,8 @@ export function GET() {}export async function POST(req: Request) {- const { name } = await req.json().catch(() => ({}));+ const { name, scope } = await req.json().catch(() => ({}));// Returns the plaintext token ONCE — only its hash is stored.- return Response.json(createToken(typeof name === "string" ? name : "token"));+ // Scope decides whether the holder may mutate the vault; anything but "read" means full access.+ return Response.json(createToken(typeof name === "string" ? name : "token", scope === "read" ? "read" : "write"));}diff --git a/lib/actor.ts b/lib/actor.tsnew file mode 100644index 0000000..4588ac1--- /dev/null+++ b/lib/actor.ts@@ -0,0 +1,22 @@+import { AsyncLocalStorage } from "node:async_hooks";++/**+ * Who caused the write currently in flight.+ *+ * Agents already write to the vault autonomously, so an anonymous "edit foo.md" in the git+ * log is not an audit trail. Every write funnels through lib/vault/write.ts, which stamps+ * the current actor into the commit message — so the Activity page answers "who did this"+ * without threading an `actor` argument through every tool handler.+ *+ * Set it at the request boundary (the MCP route, the dashboard API), read it in write.ts.+ */+const storage = new AsyncLocalStorage<string>();++export function withActor<T>(actor: string, fn: () => T): T {+ return storage.run(actor, fn);+}++/** The actor for the in-flight request, or "unknown" outside any request (e.g. a git pull). */+export function currentActor(): string {+ return storage.getStore() ?? "unknown";+}diff --git a/lib/git.ts b/lib/git.tsindex 2b4349e..ec1e4f7 100644--- a/lib/git.ts+++ b/lib/git.ts@@ -21,6 +21,34 @@ export function gitVaultDir(): string | null {return fs.existsSync(path.join(dir, ".git")) ? dir : null;}+/**+ * The environment for a git child process.+ *+ * simple-git refuses to run when an editor variable is inherited from the host+ * ("Use of GIT_EDITOR is not permitted without enabling allowUnsafeEditor"), because a+ * hostile value would execute arbitrary code. Plenty of shells and CI images export one, and+ * the only symptom was a console.error while the vault quietly stopped syncing — so strip+ * them rather than re-permitting them. `-m` commits need no editor anyway.+ *+ * GIT_TERMINAL_PROMPT=0 stops a missing credential from hanging the push forever.+ */+function commitEnv(name: string, email: string): Record<string, string> {+ const env: Record<string, string> = {};+ for (const [k, v] of Object.entries(process.env)) {+ if (v === undefined) continue;+ if (k === "GIT_EDITOR" || k === "GIT_SEQUENCE_EDITOR") continue;+ env[k] = v;+ }+ return {+ ...env,+ GIT_AUTHOR_NAME: name,+ GIT_AUTHOR_EMAIL: email,+ GIT_COMMITTER_NAME: name,+ GIT_COMMITTER_EMAIL: email,+ GIT_TERMINAL_PROMPT: "0",+ };+}+/*** Debounced commit + pull --rebase + push of the active vault. No-op unless git-sync is on* AND the vault is its own git repo (see gitVaultDir).@@ -52,15 +80,7 @@ async function runSync(): Promise<void> {return;}const { name, email } = gitAuthor();- await g- .env({- ...process.env,- GIT_AUTHOR_NAME: name,- GIT_AUTHOR_EMAIL: email,- GIT_COMMITTER_NAME: name,- GIT_COMMITTER_EMAIL: email,- })- .commit(`brain: ${reasons.length} change(s) — ${reasons.slice(0, 3).join("; ")}`);+ await g.env(commitEnv(name, email)).commit(`brain: ${reasons.length} change(s) — ${reasons.slice(0, 3).join("; ")}`);try {await g.pull(["--rebase", "--autostash"]);} catch (e) {diff --git a/lib/mcp/tools.ts b/lib/mcp/tools.tsindex 67d578f..ebb1a32 100644--- a/lib/mcp/tools.ts+++ b/lib/mcp/tools.ts@@ -28,6 +28,8 @@ export interface Tool {name: string;description: string;inputSchema: Record<string, unknown>;+ /** True when the tool mutates the vault. Read-only tokens may not call these. */+ write?: boolean;handler: (args: Args) => Promise<unknown> | unknown;}@@ -208,6 +210,7 @@ export const TOOLS: Tool[] = [},{name: "brain_write",+ write: true,description:"Create or overwrite a note. PREFER `body` (markdown, no frontmatter) + `frontmatter` (an object): the YAML is serialised for you and always parses. Hand-writing frontmatter into `content` risks invalid YAML — a note whose frontmatter fails to parse loses its status, tags and title on every read, so a note claiming `status: locked` would rank as an ordinary one. Such a write is REJECTED. Follow SCHEMA.md: kebab-case path, dated names for daily/decisions, frontmatter with title/type/tags/status. Path vault-relative (e.g. decisions/foo-2026-07-09.md).",inputSchema: {@@ -224,6 +227,7 @@ export const TOOLS: Tool[] = [},{name: "brain_edit",+ write: true,description:"Overwrite a note. Pass `content` (full raw markdown incl. frontmatter) — read first with brain_read, then write the whole file back. Also accepts `body` (+ optional `frontmatter`) like brain_write.",inputSchema: {@@ -240,6 +244,7 @@ export const TOOLS: Tool[] = [},{name: "brain_append",+ write: true,description: "Append text to a note (creates it if missing).",inputSchema: {type: "object",@@ -254,6 +259,7 @@ export const TOOLS: Tool[] = [},{name: "brain_move",+ write: true,description:"Move or rename a note. This is how you retire something: when a note stops being true, move it to an archive folder (see brain_schema → conventions.ranking.archiveFolders) rather than deleting it. Archived notes are demoted in search and excluded by default, so they stop misleading agents while the reasoning trail survives. Leave a pointer in the replacement note saying what superseded what.",inputSchema: { type: "object", properties: { from: s("current path"), to: s("new path") }, required: ["from", "to"] },@@ -261,12 +267,14 @@ export const TOOLS: Tool[] = [},{name: "brain_create_folder",+ write: true,description: "Create a new folder in the vault (with a .gitkeep).",inputSchema: { type: "object", properties: { path: s("folder path") }, required: ["path"] },handler: async ({ path }) => ({ ok: true, path: await createFolder(String(path)) }),},{name: "brain_capture",+ write: true,description:"Capture a ROUGH note / brain-dump and let the vault file it automatically: it reads SCHEMA.md + the current folders, picks the right folder + filename, writes clean frontmatter, and structures the body. Use when you have unstructured input and don't want to decide the path yourself.",inputSchema: { type: "object", properties: { text: s("the rough note / brain dump to file") }, required: ["text"] },@@ -274,6 +282,7 @@ export const TOOLS: Tool[] = [},{name: "brain_delete",+ write: true,description:"Delete a note (recoverable via git history). Prefer brain_move into an archive folder — deleting destroys the reasoning trail, archiving only removes it from search. Delete when the note is wrong or duplicated, archive when it is merely no longer true.",inputSchema: { type: "object", properties: { path: s("vault-relative path") }, required: ["path"] },diff --git a/lib/tokens.ts b/lib/tokens.tsindex 4f3d00a..b7a0dc4 100644--- a/lib/tokens.ts+++ b/lib/tokens.ts@@ -7,17 +7,31 @@ import { DATA_ROOT } from "@/lib/config";const STATE_DIR = process.env.ENGRAM_STATE_DIR || DATA_ROOT;const TOKENS_FILE = path.join(STATE_DIR, "tokens.json");+/**+ * What a token is allowed to do.+ *+ * `read` — search, read, list, tree, backlinks, graph, recent, schema.+ * `write` — everything, including move and delete.+ *+ * This, not the Curator, is the lever that decides whether an agent can mutate the vault.+ * A read-only token is the guarantee that a connected agent cannot change your notes.+ */+export type TokenScope = "read" | "write";+interface StoredToken {id: string;name: string;hash: string;created: string;+ /** Absent on tokens created before scopes existed — those are grandfathered as `write`. */+ scope?: TokenScope;}export interface TokenMeta {id: string;name: string;created: string;+ scope: TokenScope;}const hash = (t: string) => crypto.createHash("sha256").update(t).digest("hex");@@ -39,33 +53,39 @@ function save(tokens: StoredToken[]) {fs.writeFileSync(TOKENS_FILE, JSON.stringify(tokens, null, 2));}+/** Tokens minted before scopes existed keep the behaviour they had: full access. */+const scopeOf = (t: StoredToken): TokenScope => t.scope ?? "write";+export function listTokens(): TokenMeta[] {- return load().map(({ id, name, created }) => ({ id, name, created }));+ return load().map((t) => ({ id: t.id, name: t.name, created: t.created, scope: scopeOf(t) }));}/** Create a token. Returns the plaintext value ONCE — only the hash is stored. */-export function createToken(name: string): { id: string; name: string; token: string } {+export function createToken(name: string, scope: TokenScope = "write"): { id: string; name: string; scope: TokenScope; token: string } {const token = crypto.randomBytes(32).toString("hex");const rec: StoredToken = {id: crypto.randomUUID(),name: name?.trim() || "token",hash: hash(token),created: new Date().toISOString(),+ scope: scope === "read" ? "read" : "write",};const all = load();all.push(rec);save(all);- return { id: rec.id, name: rec.name, token };+ return { id: rec.id, name: rec.name, scope: rec.scope!, token };}export function revokeToken(id: string): void {save(load().filter((t) => t.id !== id));}-export function verifyToken(bearer: string): boolean {- if (!bearer) return false;+/** Resolve a bearer token to its identity + scope, or null when unknown. */+export function resolveToken(bearer: string): TokenMeta | null {+ if (!bearer) return null;const h = hash(bearer);- return load().some((t) => t.hash === h);+ const t = load().find((x) => x.hash === h);+ return t ? { id: t.id, name: t.name, created: t.created, scope: scopeOf(t) } : null;}export function hasAnyToken(): boolean {diff --git a/lib/vault/write.ts b/lib/vault/write.tsindex 1b9d982..138bdc6 100644--- a/lib/vault/write.ts+++ b/lib/vault/write.ts@@ -5,6 +5,7 @@ import { activeVaultDir } from "@/lib/repos";import { refreshPaths } from "./store";import { checkFrontmatter, frontmatterErrorMessage } from "./validate";import { requestSync } from "@/lib/git";+import { currentActor } from "@/lib/actor";/** Resolve a vault-relative path to an absolute path in the active vault, refusing escapes. */function safeAbs(relPath: string): string {@@ -19,10 +20,14 @@ export function normalizeNotePath(relPath: string): string {return /\.md$/i.test(p) ? p : `${p}.md`;}-/** Re-index only what changed, then queue a git commit. `touched` are vault-relative paths. */+/**+ * Re-index only what changed, then queue a git commit stamped with who caused it.+ * The actor prefix is what turns the Activity feed into an audit trail rather than a+ * list of anonymous edits. `touched` are vault-relative paths.+ */function after(message: string, touched: string[]) {refreshPaths(touched);- requestSync(message);+ requestSync(`${currentActor()}: ${message}`);}export interface WriteOpts {@@ -95,6 +100,6 @@ export async function createFolder(relPath: string): Promise<string> {const abs = safeAbs(p);await fsp.mkdir(abs, { recursive: true });await fsp.writeFile(path.join(abs, ".gitkeep"), "", "utf8");- requestSync(`mkdir ${p}`);+ requestSync(`${currentActor()}: mkdir ${p}`);return p;}