Skip to main content
Glama
Grunte12

graphmory-mcp

by Grunte12
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

Graphmory 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

Related MCP server: openmemkit

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

System architecture. You give your coding agent a task. In your agent host, the coding agent asks the Curator, which returns a cited brief. The coding agent calls remember and the Curator calls recall and read on the Graphmory MCP server, and every call returns an answer. The engine behind the tools runs keyword, meaning and link search, guarded writes and lifecycle filtering. It reads and writes your Obsidian-compatible Markdown vault, keeps checkpoints and a review queue in private state outside the vault, and can sync the vault through Git. You approve low-confidence memories in a terminal.

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

Inside the engine. Recall: a question is filtered to active notes, then keyword and meaning search run in parallel and the links lane follows authored links up to 3 hops from their top hits. The lanes are fused with RRF into ranked notes, or "No supporting note" when there are no candidates. Remember: a proposal passes evidence and permission, overlap and confidence checks, then a new note is written with a receipt hash and the result is APPLIED. An overlap gives TENSION; a failed check gives BLOCKED, and low confidence waits in a private review queue for the owner.

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

  1. 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 .

  2. 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.

  3. Check it:

    graphmory doctor

    Expect vault ok, curator model ok (<model>), mcp tools: recall · read · remember · link · status · sync and meaning search ok. Any line that says needs attention comes with the fix.

  4. 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/.

This server cannot be deployed

Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mor

    laat
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI assistants to search, read, create, update, and remove personal markdown notes stored locally, providing persistent memory across sessions.
    12 npm
    2
    MIT

  • openmemkit

    Jlnine
    A
    license
    A
    quality
    B
    maintenance
    Enables AI agents to maintain a persistent, queryable memory stored as user-owned Markdown files, with dual-channel retrieval (FTS5 and optional semantic search) and an audited write pipeline.
    11
    MIT

  • Link

    gowtham0992
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI agents to capture, structure, remember, and retrieve source-backed memory as local Markdown files, with reviewable writes and no cloud dependency.
    199
    MIT

  • obsidian-brain

    CaptainKeat
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI clients to search and retrieve notes from a local Markdown vault using hybrid keyword/semantic search, and to save typed memories with append and guarded replacement operations.
    MIT