engram

Engram is a self-hosted MCP (Model Context Protocol) server and dashboard that lets Claude Code, Cursor, Hermes, and any MCP-capable agent share a single long-term memory. Memories are stored in plain Markdown folders that you own, are tracked by git, and are Obsidian-compatible. It is aimed at scenarios that a single agent's memory cannot cover: a team running multiple agents at once, sharing the same "second brain".

Purpose

Autonomous agents forget everything between sessions, and worse, they cannot tell whether what they remember is still true. An agent may cite a README that changed months ago, a discontinued price, or API documentation, because both keyword search and vector search rank by similarity rather than by truth. Engram makes "is this still true" a first-class, written-down property: after marking a fact as superseded or expired, retrieval hides it and tells the agent what it skipped and why. Per-agent read/write tokens and a git audit trail of "who wrote what" keep things controllable even when the writers are a swarm of agents rather than just you.

Key capabilities

• MCP server: exposes 15 brain_* tools through a single bearer-authenticated HTTP endpoint (POST /api/mcp, streaming HTTP JSON-RPC). Any MCP client connects to the same URL. Tokens are scoped per agent: read-only tokens cannot even see the write tools.
• Human dashboard: search as the home page, including a file tree, a note viewer supporting Obsidian callouts/wikilinks/backlinks, a preview/edit/split editor with autosave, ⌘K search and in-page keyboard navigation, a "jump back in" recent history, and a force-directed knowledge graph.
• Authority-aware retrieval: ranking knows relevance but not truth, so superseded notes can repeat your query terms just as often as current notes. Every hit carries an authority level (authoritative → current → provisional → superseded → archived), derived from the note's folder and frontmatter, so agents cite locked documents rather than outdated ones.
• Temporal validity + explainable refusal: mark a piece of inMarking it as superseded_by another note, or giving it a valid_until date, will cause retrieval to hide it by default (even if it is locked), and then return an excluded list to the agent explaining what was skipped and why (e.g., "expired 2026-06-01"). An atomic brain_supersede deactivates the old fact and links the new fact in a single commit, so that addition and deactivation do not become disconnected.
• Contradiction guards at write time: authority ranking resolves reads; these guards prevent the repository from accepting contradictions in the first place. If a live note already covers a topic, Engram refuses to create a second live note and directs the agent to use brain_supersede instead; it refuses to overwrite a note the caller has not yet read; and it warns when status: is not a word recognized by the ranking model, so that typos do not silently strip a note of its authority.
• Audit trail + access control: every write is attributed in git to the token or person that made it, and an expandable per-file diff is provided in the activity stream. Give an agent a read-only token, and it cannot even see the write tools; a write token can create, edit, move, and archive.
• Curator (optional): an agent framework built into Engram that runs on your repository. Chat with your notes (grounded answers with wikilink citations). Or hand rough drafts (meeting notes, voice transcripts) to brain_capture, and the agent will loop through searching existing content, then archive, merge, or file it away, and return a list of what it touched. It reads before overwriting, and never deletes. Supports Opus/Sonnet/Haiku, using your own key.
• Markdown native: plain .md + YAML frontmatter + [[wikilinks]]. Drop it directly into an existing Obsidian vault and it works.
• Git support: optional automatic commit + push on every change. Full history, no lock-in, your data lives in your repository.
• No database: files are the source of truth; an in-memory MiniSearch index plus a ported wikilink graph drive search and backlinks. No setup required.
• Multiple workspaces: connect multiple repositories (URL + token or GitHub OAuth), rename, switch the active workspace, or remove them, all from the UI.
• Self-hosted: a Docker container. Deployable on Railway / Render / Fly / any host with a volume. Not serverless (requires a persistent volume, a file watcher, and a long-running index).
• Team authentication: the dashboard supports Google SSO + email allowlist; MCP uses per-agent bearer tokens, or OAuth for Claude.ai custom connectors, all created/revoked in the UI. Secrets are encrypted at rest.
• Runtime configuration: toggle git sync and Curator directly on the home page; manage commit author, secrets, and OAuth in settings, with no redeploy needed.

How to use

There are two ways to run it:

• Hosted mode (team): the dashboard above + an HTTP MCP server—self-host once, many agents and teammates connect via POST /api/mcp. This is the primary mode.
• Local mode (stdio): a plain stdio MCP server pointed at a folder, with no HTTP/auth/git—suitable for a single machine, Claude Desktop / Cursor, or registry Docker introspection.

Local mode command:

bun run mcp:stdio /path/to/your/vault # defaults to ./sample-vault

The same brain_* tools. Built by Dockerfile.mcp.

Each mode is published as its own image, and the two are not interchangeable. Deploying the stdio image as a web service is the one mistake worth calling out: it will only 502, because nothing is listening. Now it refuses to start on a PaaS and tells you so.

Agents can only see the currently active repository—no repository, workspace, or GitHub tools are exposed. A read-scoped token can only see read tools. brain_capture only appears when Curator is full.

Connecting an agent: the dashboard's Connect page shows the exact command and token. Connecting your repository: in the dashboard's Workspaces, connect via URL + token or GitHub OAuth. Sign in with Google, create an MCP token on the Connect page, and point the agent at that URL.

Deployment: anywhere you can run a Docker container with a persistent volume——Railway, Render, Fly, or your own machine. Serverless (Vercel) is not usable: Engram needs a volume, a file watcher, and an in-memory index, which serverless functions cannot keep alive. Deploy this repository (root Dockerfile), mount a volume at /data, and set ENGRAM_DATA_DIR=/data.

Railway: New Project → Deploy from GitHub repo → add a Volume at /data. Render: one-click deploy via the bundled render.yaml (Docker + /data disk).

If using a prebuilt image instead of deploying the repository, use ghcr.io/rwnalds/engram-app:latest——do not use engram:latest, which is a stdio server and cannot respond over HTTP. Set the health check to /api/health.

Most runtime configuration (git sync, AI capture, GitHub OAuth, app name) can be edited on the settings page——only authentication/infrastructure bootstrap variables live on the host. See DEPLOY.md for full setup.

When to use it

• Shared memory for teams co-hosting multiple agents——one repository, multiple agents reading and writing concurrently, per-agent read/write tokens, and a git audit trail recording who changed what.
• Memory that knows what is still true——deactivate a price, term, or changed API doc, and your agents stop citing it, and are told what was skipped and why.
• Long-term memory for Claude Code and other coding agents——no need to re-explain your project every session.
• A self-hosted, Obsidian-compatible second brain exposed via MCP.
• Memory that is visualized rather than a black box——search, inspect (with diffs), and curate what agents remember through a dashboard.
• Markdown RAG without a vector database——full-text search plus a link graph over human-readable files.

Known limitations and notes

• Not serverless, and cannot be deployed on platforms such as Vercel.
• Local stdio mode does not include HTTP/authentication/git.
• The current repository material is as of July 2026, and comparisons with specific products are by category rather than item-by-item audits.
• The built-in Curator uses your own Anthropic key, supporting Opus/Sonnet/Haiku.
• Licensed under MIT. Tech stack: Next.js 16 (App Router) · React 19 · TypeScript · Tailwind v4 · shadcn/ui · bun · MiniSearch · d3-force · MCP SDK.