Engram
The second brain your AI agents read and write.
Engram is a self-hosted MCP server + dashboard that gives Claude Code, Cursor, Hermes, and anyModel Context Protocol agent shared, long-term memory — over aplain, git-backed folder of markdown. No database:your notes are the source of truth, an in-memory index powers full-text search and a wikilinkknowledge graph, and git is the durable store.
Think Obsidian, but agent-native — or markdown RAG without a vector database. Point it at anyvault of .md files (or the bundled sample-vault/) and every agent on your team can search, read,and write the same knowledge. Humans edit it in a fast dashboard; agents edit it over one MCP endpoint.
Why it exists: autonomous AI agents forget everything between sessions. Engram is thepersistent memory layer — one knowledge base that humans and agents share, versioned in git,so your Claude Code / Hermes / Cursor agents remember decisions, context, and everything they learn.
What it's for
- Long-term memory for Claude Code and other coding agents — stop re-explaining your project every session.
- Shared memory for a fleet of AI agents — one vault, many agents reading and writing concurrently.
- A team knowledge base agents can actually write to — meeting notes, decisions, client context, SOPs.
- A self-hosted, Obsidian-compatible second brain exposed over MCP — your notes, your server, your git repo.
- Markdown RAG without the vector database — full-text search + a link graph over human-readable files.
Features
- MCP server — 13
brain_*tools over one bearer-authenticated HTTP endpoint (POST /api/mcp,streamable HTTP JSON-RPC). Connect any MCP client to a single URL. - Human dashboard — file tree, note viewer with Obsidian callouts, wikilinks, and backlinks,Preview / Edit / Split editor with autosave, ⌘K command-palette search, and a force-directedknowledge graph.
- Markdown-native — plain
.md+ YAML frontmatter +[[wikilinks]]. Drop in an existingObsidian vault and it just works. - Git-backed — optional auto commit + push of every change. Full history, no lock-in, your datalives in your repo.
- No database — files are the source of truth; an in-memory MiniSearch index + a ported wikilinkgraph power search and backlinks. Nothing to provision.
- Multi-workspace — connect multiple vault repos and switch the active one from the UI.
- Self-hosted — one Docker container. Railway / Render / Fly / any host with a volume.Not serverless (it needs a persistent volume, a file watcher, and a long-running index).
- Team auth — Google SSO + email allowlist for the dashboard; per-agent bearer tokens for MCP(create/revoke in the UI). Secrets encrypted at rest.
- Optional AI auto-filing (
brain_capture) — dump a rough note and it gets filed into the rightplace, with the right frontmatter, automatically. - Runtime Settings page — flip git-sync, capture, and OAuth on/off without a redeploy.
Works with
Claude Code · Claude Desktop · Cursor · Cline · Windsurf · Hermes · any MCP client.One endpoint, bearer-token auth — if it speaks the Model Context Protocol, it can use Engram as memory.
Quick start
bun install
bun dev # http://localhost:3000 — runs against ./sample-vault
Point it at your own vault:
VAULT_DIR=/path/to/your/obsidian-or-markdown/vault bun dev
MCP tools
Agents only ever see the active vault — no repo, workspace, or GitHub tools are exposed.
| Tools | |
|---|---|
| Read | brain_search · brain_read · brain_list · brain_tree · brain_backlinks · brain_graph · brain_schema |
| Write | brain_write · brain_edit · brain_append · brain_move · brain_create_folder · brain_delete |
Connect an agent (the dashboard → Connect page shows the exact command + token):
claude mcp add --transport http engram https://<host>/api/mcp \
--header "Authorization: Bearer <token>"
Deploy
Runs anywhere you can run a Docker container with a persistent volume — Railway, Render, Fly, or yourown box. Serverless (Vercel) won't work: Engram holds a volume, a file watcher, and an in-memoryindex that a serverless function can't keep alive.
- Deploy this repo (root
Dockerfile), mount a volume at/data, setENGRAM_DATA_DIR=/data. - Connect your vault repo(s) in the dashboard (Workspaces) — by URL + token, or GitHub OAuth.
- Sign in with Google, create MCP tokens on the Connect page, point your agents at the URL.
Most runtime config (git-sync, AI capture, GitHub OAuth, app name) is editable in the Settingspage — only auth/infra bootstrap vars live on the host. Full setup: DEPLOY.md.
- Railway: New Project → Deploy from GitHub repo → add a Volume at
/data. - Render: one-click via the bundled
render.yaml(Docker + a/datadisk).
FAQ
How do I give Claude Code long-term memory?Deploy Engram, connect a markdown vault, and claude mcp add the endpoint. The brain_* tools letClaude Code search, read, and write persistent notes across sessions.
Can multiple AI agents share one knowledge base?Yes. Every agent points at the same MCP URL and reads/writes the same active vault — that's the point.Give each agent its own bearer token.
Does it work with my Obsidian vault?Yes. It reads plain markdown with frontmatter and [[wikilinks]], and renders Obsidian-style calloutsand backlinks. No import step.
Do I need a vector database?No. Engram uses full-text search (MiniSearch) plus a wikilink graph over human-readable markdown —no embeddings service, no vector store to run.
Is my data locked in?No. It's just .md files in a git repo you own. Turn Engram off and you still have every note and itsfull history.
Where does it run / is it self-hosted?You host it. One Docker container on Railway / Render / Fly / any VM with a volume. Your keys, your data.
Stack
Next.js 16 (App Router) · React 19 · TypeScript · Tailwind v4 · shadcn/base-ui · bun · MiniSearch ·d3-force · MCP SDK. MIT licensed.
Keywords: MCP server · Model Context Protocol · second brain for AI agents · agent memory ·long-term memory for Claude Code · shared memory for AI agents · self-hosted knowledge base ·Obsidian-compatible · markdown · knowledge graph · wikilinks · PKM · Zettelkasten · git-backed notes ·Hermes agent memory · Cursor memory · RAG without a vector database.
