Engram

by rwnalds

2 stars
252 downloads
Not rated
GitHub

About

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.

Details

Author
rwnalds
GitHub stars
2
Downloads
252
Categories
AI, Developer Tools, Other

- Shared memory for a team running multiple agents — one vault, many agents reading and writing
- Memory that knows what's still true — retire a price, a term, or a changed API doc and your agents
- Long-term memory for Claude Code and other coding agents — stop re-explaining your project every session
- 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

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name Engram
    Command (node, npx, python, etc.)

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

The README includes setup instructions such as bun install.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "engram": {
            "engram": {
                "command": "bun",
                "args": [
                    "dev",
                    "#",
                    "http://localhost:3000",
                    "\u2014",
                    "runs",
                    "against",
                    "./sample-vault"
                ]
            }
        }
    }
}

McpServers

{
    "engram": {
        "command": "bun",
        "args": [
            "dev",
            "#",
            "http://localhost:3000",
            "\u2014",
            "runs",
            "against",
            "./sample-vault"
        ]
    }
}

The second brain your AI agents read and write.

▶ Watch the full-length video(real-time, full quality)

↗ Try the live demo— no signup. Searchretainer priceand watch the retired note get withheld.

Engram is a self-hostedMCP server + dashboardthat gives Claude Code, Cursor, Hermes, and anyModel Context Protocolagentshared, long-term memory they readand write— over a plain,git-backed folder of markdown you own. Built for the case a single agent's memory never hits:a team running several agents against one brain.

Autonomous agents forget everything between sessions — and worse, they can't tell what they remember isstill true. An agent pulls an old README, a retired price, an API doc you changed months ago, and quotes it with full confidence, because keyword and vector search both rank by resemblance, not truth. Engram makes"is this still true"a first-class, written property: mark a fact superseded or expired and searchwithholds 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 it sane when the writers are a fleet, not just you.

Unlike a headless memory store,you can watch it happen.A fast dashboard lets yousearch your brain, see exactly what every agent and teammate changed (with per-filediffs),jump backinto recent notes, and curate it all — while agents read and write the same vault over one MCP endpoint. No database: your.mdfiles are the source of truth, git is the durable store, and an in-memory index powers full-text search + a wikilinkknowledge graph.

Opinionated abouthowit stores memory— git-backed markdown, no database, agents write (not just read), self-hosted.Unopinionated aboutwhatyou keep in it— any markdown vault, any folder structure, any MCP client. Point it at a fresh repo or your existingObsidian vault: no import step, no lock-in.

What it's for·How it compares·Features·Works with·Quick start·MCP tools·Deploy·FAQ·Contributing

- Shared memory for a team running multiple agents— one vault, many agents reading and writing concurrently, with per-agent read/write tokens and a git audit trail of who changed what.
- Memory that knows what's still true— retire a price, a term, or a changed API doc and your agents stop quoting it; they're told what they skipped and why. The failure a single agent's memory never fixes.
- Long-term memory for Claude Codeand other coding agents — stop re-explaining your project every session.
- A self-hosted, Obsidian-compatible second brainexposed over MCP — your notes, your server, your git repo.
- Memory you can see, not a black box— a dashboard to search, watch (with diffs), and curate what your agents remember.
- Markdown RAG without the vector database— full-text search + a link graph over human-readable files.

Most agent memory is built to answer"what did I store about this?"Engram is built to answer"what is still true about this?"— a different question, and the one that bites when an agent quotes a price you retired months ago.

The row that matters is the third one. Similarity search cannot tell a contradiction from a duplicate — a retired price and a live one are textually identical, so the retired one oftenoutranksthe live one by being longer and more detailed. That can't be fixed at read time, which is why Engram writes the retirement down when it happens.

This exact pair ships insample-vault/. Runbun dev, searchacme price, and watch the retired note get withheld with a reason.

Categories, not feature-by-feature audits of specific products, and accurate to the best of my knowledge as of July 2026. If something here misrepresents a tool you maintain, open a PR — I'll fix it.

- MCP server— 15brain_tools over one bearer-authenticated HTTP endpoint (POST /api/mcp, streamable HTTP JSON-RPC). Connect any MCP client to a single URL.Per-agent token scopes: a read-only token never even sees the write tools.
- Human dashboard— asearch-first home, file tree, note viewer withObsidian callouts, wikilinks, and backlinks, Preview / Edit / Split editor with autosave, ⌘K search +in-page keyboard navigation, "jump back in" recents, and aforce-directed knowledge graph.
- Authority-aware search— ranking knowsrelevance, not truth, so a superseded note repeats your query words as often as the live one. Every hit carries anauthority(authoritativecurrentprovisionalsupersededarchived) derived from the note's folder and frontmatter — so your agents quote the locked doc, not the dead one. Markdown RAG that won't hand back yesterday's answer.
- Temporal validity + explainable rejection— mark a factsuperseded_byanother note or give it avalid_untildate, and searchwithholds it by default(even if it'slocked) — then hands the agent anexcludedlist of what it skipped, each with a reason ("expired 2026-06-01"). One atomicbrain_supersederetires the old fact and links the new one in a single commit, so add-and-retire can't drift apart. This is the difference between an agent that
remembersand one that knows what'sstill true.
- Write-time contradiction guards— authority ranking fixes
reading; these stop the vault accepting the contradiction in the first place. Engram refuses to create a second live note on a subject a live note already covers (theacme-pricing-2026.md-beside-acme-pricing.mdbug) and points the agent atbrain_supersedeinstead; refuses to overwrite a note the caller hasn't read; and warns when astatus:isn't a word the ranking model knows, so a typo can't silently strip a note's authority.
- Audit trail + access control— every write is attributed ingitto the token or human that made it, with expandableper-file diffsin the activity feed. Give an agent aread-only tokenand it never even sees the write tools; awritetoken can create, edit, move, and archive.
- The Curator
(optional)— Engram's built-inagent harnessover your vault.Chatwith your notes (grounded answers, wikilink citations). Or handbrain_capturea rough dump — a meeting note, a voice transcript — and anagentic loop searches what already exists, then files, merges, or archivesand returns a manifest of what it touched. It reads before it overwrites and never deletes. Opus / Sonnet / Haiku, your key.
- Markdown-native— plain.md+ YAML frontmatter +
[[wikilinks]]. Drop in an existingObsidian vaultand it just works.
- Git-backed— optional auto commit + push of every change. Full history, no lock-in, your data lives inyourrepo.
- No database— files are the source of truth; an in-memory MiniSearch index + a ported wikilink graph power search and backlinks. Nothing to provision.
- Multi-workspace— connect multiple vault repos (URL + token or GitHub OAuth), rename, switch the active one, or remove them — all from the UI.
- Self-hosted— one Docker container. Railway / Render / Fly / any host with a volume.Notserverless (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 — orOAuth for Claude.ai custom connectors— for MCP, created/revoked in the UI. Secrets encrypted at rest.
- Runtime config— toggle git-sync and the Curator right from the home; manage commit author, keys, and OAuth inSettings— no redeploy.

Any client that speaks theModel Context Protocol— one endpoint, bearer-token auth. Most-used first:

- Claude Code— Anthropic's agentic coding CLI
- Codex— OpenAI's coding agent (CLI + IDE)
- Hermes— always-on autonomous agent runtime
- openclaw— open-source coding agent
- Cursor— AI code editor
- Cline— VS Code agent
- Windsurf— agentic IDE
- Claude Desktop— Anthropic's desktop app
- …and any other MCP client — Continue, Goose, Zed, Amp, and the rest

If it speaks MCP, it can read and write Engram as shared memory.

Want to poke at it first?There's a live demo— open, no signup, resets a few times a day. Break it all you like.

bun install bun dev # http://localhost:3000 — runs against ./sample-vault
VAULT_DIR=/path/to/your/obsidian-or-markdown/vault bun dev

-

Hosted mode (team):the dashboard + HTTP MCP server above — self-host it once, many agents and teammates connect overPOST /api/mcp. This is the main mode.

Local mode (stdio):a plain stdio MCP server over a folder, no HTTP/auth/git — for a single machine, Claude Desktop / Cursor, or a registry's Docker introspection:

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

Samebrain_tools. Built fromDockerfile.mcp.

Each mode ships as its own image, and they are not interchangeable:

Deploying the stdio image as a web service is the one mistake worth calling out: it can only 502, because there is nothing listening. It now refuses to start on a PaaS and tells you this instead.

Agents only ever see the active vault — no repo, workspace, or GitHub tools are exposed. Aread-scope token sees only the read tools.brain_captureappears only when the Curator isfull.

Connect an agent (the dashboard →Connectpage shows the exact command + token):

claude mcp add --transport http engram https://<host>/api/mcp \ --header "Authorization: Bearer <token>"

Runs anywhere you can run a Docker container with a persistent volume — Railway, Render, Fly, or your own box.Serverless (Vercel) won't work: Engram holds a volume, a file watcher, and an in-memory index that a serverless function can't keep alive.

Most runtime config (git-sync, AI capture, GitHub OAuth, app name) is editable in theSettingspage — 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 bundledrender.yaml(Docker + a/datadisk).

Deploying from a prebuilt image instead of the repo? Useghcr.io/rwnalds/engram-app:latest— notengram:latest, which is the stdio server and cannot answer HTTP. Set the healthcheck to/api/health.

How do I give Claude Code long-term memory?Deploy Engram, connect a markdown vault, andclaude mcp addthe endpoint. Thebrain_tools let Claude 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,readorwrite— a read-only token can't mutate your notes.

How do I stop an agent from quoting outdated facts?Retire the fact and search stops surfacing it. When a value changes, callbrain_supersede(old, new)— one atomic commit marks the old notesuperseded_bythe new one, and it'swithheld from search by default(even if it'slocked). Or setvalid_until: 2026-12-31on a note and it self-expires. Retired matches don't vanish silently:brain_searchreturns them in anexcludedlist with a reason ("expired 2026-06-01"), so the agent can saywhat it ignored and whyinstead of quoting it.

What stops an agent just adding a second, contradicting note?Engram refuses the write. Told "the price is now X", an agent that can't overwrite a note it never read will happilyadd*acme-pricing-2026.mdnext toacme-pricing.md— nothing is corrupted, and you now have two live notes disagreeing about one number. That write is rejected with a pointer tobrain_supersede, which retires the old note and adds the new one in a single commit. Passallow_conflict: truewhen both notes genuinely belong.

How do I know what an agent changed?Every write is committed to git attributed to the token or human behind it, and the dashboard's activity feed shows per-file diffs — a built-in audit trail for autonomous agents.

Does it work with my Obsidian vault?Yes. It reads plain markdown with frontmatter and[[wikilinks]], and renders Obsidian-style callouts and 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.

Can I chat with my notes?Yes — enable the optionalCurator, a chat agent that searches and reads your vault to answer with wikilink citations (Opus / Sonnet / Haiku). It's read-only in chat, so it helps you think without changing anything, and it runs on your own Anthropic key.

Can I see what my agents changed?Yes — theActivityview reads your vault's git history and shows every change (agents and teammates alike), expandable to per-file diffs. Since it's just git, you get the full audit trail for free.

Is my data locked in?No. It's just.mdfiles in a git repo you own. Turn Engram off and you still have every note and its full 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.

Issues and PRs welcome — especially where the validity model breaks against a vault shaped differently from mine.

- CONTRIBUTING.md— setup, conventions, and the pre-PR checklist.
-
docs/curator.md— how the optional Curator agent loop works.
-
SECURITY.md— please report vulnerabilities privately, not as an issue.

bun install && bun dev bun test # the ranking/authority suite, incl. the stale-truth fixtures

If Engram is useful to you,starring the repogenuinely helps other people find it.

Next.js 16 (App Router) · React 19 · TypeScript · Tailwind v4 · shadcn/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 · chat with your markdown notes · git-backed agent activity feed · audit trail for AI agents · authority-aware search · read-only vs write MCP tokens · agent access control · self-organizing notes · agentic note capture · AI that files your notes · temporal validity · stale memory · agents quoting outdated facts · supersede · note expiry · shared memory for a team of agents · Basic Memory alternative · mem0 alternative.

Creates commit messages from staged files in a local git repository.

Anchor is local repo and org memory for AI coding agents. It indexes GitHub PR history, current code, tests, regressions, architecture, and cross-repo impact locally, then exposes concise cited context through MCP and CLI workflows. Local-first. Read-only GitHub access. No CLI telemetry. No SaaS. No remote LLM calls.

An MCP server that equips your AI coding assistant with live, verified Android knowledge — so it builds from official sources, not from memory.

An MCP server for interacting with the AtomGit API for version control and code hosting.

Design system MCP server — query tokens, components, icons, and WCAG contrast data from Git-backed design systems.

Provides code context from local git repositories.

Local-first documentation for AI agents. Indexes docs from any git repo into SQLite for offline, instant, private access to up-to-date library documentation.

DOS is a small open-source kernel that doesn't believe your AI agents: it verifies what actually shipped from git evidence, arbitrates file collisions between parallel agents, and refuses with structured reasons.

Prevents regression by providing Blast Radius data to AI based on your git history

Fabrx is a no-code platform where users can setup custom document processing workflows

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.