Graphmory MCP server
Commit Nov 4, 2026Provides governed memory for AI agents by managing local Markdown notes with cited recall and guarded writes.
Also known as Grunte12/graphmory
- Stars
- 2
- Tools
- 6
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 4, 2026
- License
- MIT
What is Graphmory MCP?
Graphmory provides governed memory for AI agents by managing local Markdown notes with cited recall and guarded writes. It exposes 6 tools, such as recall, read, remember.
Summary generated from the project's README
About Graphmory MCP server
Providing governed memory for AI agents is what Graphmory enables by managing local Markdown notes that you own. It functions as a local MCP server that connects to your existing Obsidian vault or Markdown folder, allowing agents to search through information using keyword matching, semantic meaning, and authored links. This setup works with various MCP clients including Claude Code, Cursor, Zed, and GitHub Copilot.
Unlike standard retrieval systems that may fill with noise, this server uses a curator model to verify evidence before saving new information. It employs six specific tools: recall, read, remember, link, status, and sync. The system ensures accuracy through cited recall, where every answer includes a note path and hash, and guarded writes that prevent low-confidence or conflicting memories from being saved without your approval. It manages the lifecycle of your notes by tracking expiry and revalidation triggers to prevent stale facts from being used.
What you can do with it
- 1Verify agent claims with citationsAsk an AI agent to retrieve information from your notes while ensuring every answer points back to a specific source file.
- 2Prevent incorrect memory writesEnsure your coding agent does not save unverified or conflicting information into your knowledge base.
- 3Maintain a clean knowledge vaultAutomatically flag outdated information for revalidation so your agent does not rely on stale facts.
- 4Synchronize notes across devicesKeep your agent's memory consistent by pushing and pulling your Markdown vault through Git.
Written from the project's README. Every use case is checked against a quote from it.
Graphmory MCP tools 6
Detected from the READMErecallreadrememberlinkstatussync
| recall | — | |
| read | — | |
| remember | — | |
| link | — | |
| status | — | |
| sync | — |
Configuration
GRAPHMORY_VAULT
| Name | Description | |
|---|---|---|
| GRAPHMORY_VAULT | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablegrunte12/graphmory is public and reachablegithub.com/grunte12/graphmory ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-04github.com/grunte12/graphmory ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubGraphmory is governed memory for AI agents: a local MCP server over plain Markdown notes that you own. Agents search them by keyword, meaning and [[links]], every answer points back to its source, and new memories are checked before they are saved.
Status: experimental, pre-1.0. The contracts, tests and deterministic evals are in place. Only a single-model live pilot is published; there is no cross-model benchmark yet.
Watch the film
https://github.com/user-attachments/assets/910ec002-b976-4b80-aa1b-e4754af3497d
Why Graphmory
Memory that saves everything fills up with noise, stale facts and guesses. Graphmory keeps a small set of curated notes that any agent can search, and makes every answer prove itself.
- Cited recall. Answers come back with the note path and a hash of the note, so each claim can be checked against the original.
- Honest when nothing matches. If no note supports an answer, the result is "No supporting note", not a guess.
- Guarded writes. A new memory needs evidence. It is checked before it is saved, and the save returns a receipt hash. Conflicts and low-confidence memories are never written silently.
- Memory that ages. Notes carry a status, an expiry and revalidation triggers. Stale or replaced notes are not recalled; replaced notes stay as history. When a source changes, summaries built on it are flagged for a recheck.
- Plain files. Notes are Markdown in a folder or Obsidian vault, with optional private Git sync. No database and no vector server.
- Any MCP client. Six tools, one server: Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Cline, Zed and others.
How it works

Three roles share the work:
| Role | Does |
|---|---|
| Main agent | The coding agent you chat with. Decides what a finished task means, what is worth remembering, and whether a change is allowed |
| Curator | A small, cheap model in your agent host. Reads the original notes, verifies the evidence and returns a short cited brief |
| Graphmory | Finds candidate notes and guards every write. Runs on your machine and never invents or rewrites meaning |

Search combines three lanes: keyword matching (BM25F over note sections), meaning (a local BGE embedding model) and the [[links]] you author between notes, followed up to 3 hops. The lanes are merged with Reciprocal Rank Fusion into one ranking. Details: MCP recall.
Quick start
-
Install Graphmory (not on npm yet, so install from this repository; Node.js 20+ and Git are required):
git clone https://github.com/Grunte12/graphmory.git cd graphmory npm install -g . -
Set it up. Ask your coding agent: "Install Graphmory from this checkout using
adapters/generic-agent/INSTALL.md." It asks where your vault lives, whether to sync through Git, and which small model the Curator should use. Manual commands for Codex, Claude Code and Cursor are in host setup. -
Check it:
graphmory doctorExpect
vault ok,curator model ok (<model>),mcp tools: recall · read · remember · link · status · syncandmeaning search ok. Any line that saysneeds attentioncomes with the fix. -
Connect your agent to the MCP server, below.
Optional: graphmory semantic-warmup downloads the local meaning model once (about 130 MB) so the first recall does not wait.
Connect your agent
graphmory-mcp is a standard stdio MCP server. Point it at your vault with GRAPHMORY_VAULT.
Claude Code (.mcp.json) and Cursor (.cursor/mcp.json):
{"mcpServers":{"graphmory":{"command":"graphmory-mcp","env":{"GRAPHMORY_VAULT":"/path/to/vault"}}}}
Codex (config.toml):
[mcp_servers.graphmory]
command = "graphmory-mcp"
env = { GRAPHMORY_VAULT = "/path/to/vault" }
OpenCode (opencode.json):
{"mcp":{"graphmory":{"type":"local","command":["graphmory-mcp"],"environment":{"GRAPHMORY_VAULT":"/path/to/vault"}}}}
Other hosts: MCP host configuration. For a client that cannot start a local process, Streamable HTTP is available behind a bearer token.
The six tools
| Tool | What it does |
|---|---|
recall |
Finds a ranked shortlist for a question: up to ten candidates per page, each with path, heading, excerpt, note hash and the search lanes that found it. Pages with a cursor; a query is limited to 8 pages |
read |
Opens the original note, or one section of it, so the Curator can verify a candidate. A stale hash is refused |
remember |
Saves a decision with its evidence in a new note, or updates an existing note and keeps its other content. Returns APPLIED, TENSION or BLOCKED |
link |
Lets the Curator keep the graph connected: adds or removes relation links (part of, depends on, evidence for, related) and repairs broken links, across many notes in one call |
status |
Shows what needs attention: an interrupted write, memory waiting for you, notes due for revalidation, vault health and Git sync state. With ask, it puts your decisions to you in the host's question UI |
sync |
Pulls from the vault's private Git remote (fast-forward only) or pushes to it. A push lists the changed files and waits for your approval |
What remember returns:
| Outcome | Meaning |
|---|---|
APPLIED |
Saved as a new note, with a receipt hash for what was written. A replaced note stays as history |
TENSION |
An active note overlaps or conflicts. Nothing is written until the agent has read it and answered |
BLOCKED |
Evidence is missing or stale, a secret was found, or confidence is low. Nothing is written. Low-confidence memory waits in a private queue, and the host asks you to approve, reject or decide later |
The agent cannot approve its own low-confidence memory or restore an interrupted write: the server asks you through MCP elicitation, and no tool argument answers for you. Guides: recall and citation, guarded writes, status and owner decisions, Git sync, links, memory contracts.
Documentation
| Topic | Read |
|---|---|
| Install and hosts | Installation · Codex, Cursor and Claude Code · MCP hosts · Vault layout · Troubleshooting |
| Using it | CLI reference · Portable Brain Sync · Demo workflow · Managed retrieval |
| Design | Memory contracts · Learning loop · Positioning and RAG · Research foundations · Glossary |
| Evaluation | Evaluation · Evaluation index · Cost and scale · Live model results · npm run eval |
Project
MIT license · Changelog · Privacy · Security · Support · Contributing · All docs · Citation · Third-party notices
Graphmory was previously called memory patch harness. Per-vault sync metadata is still stored under .memory-patch-harness/.
Graphmory MCP questions
What tools does Graphmory MCP provide?
It exposes 6 tools, including recall, read, remember, link, status.
What kind of files does Graphmory use?
It uses plain Markdown files stored in a folder or an Obsidian vault.
How does Graphmory ensure memory accuracy?
It uses cited recall where every answer includes a note path and hash, and it performs guarded writes that check evidence before saving.
Does Graphmory require a database or vector server?
No, it operates on plain files without needing a database or a separate vector server.
Which AI clients can connect to Graphmory?
It works with various MCP clients including Claude Code, Cursor, Gemini CLI, GitHub Copilot, and Zed.