Enables AI clients to search, read, and write markdown notes within a schema-validated vault tied to git history.
Also known as gronare/mindin
- Stars
- 2
- Tools
- 19
- Downloads, 30 days
- 1,244
- Latest version
- 0.19.0
- Last commit
- Nov 15, 2026
- License
- MIT
What is mindin MCP?
mindin enables AI clients to search, read, and write markdown notes within a schema-validated vault tied to git history. It exposes 19 tools, such as search, read_file, write_file.
Summary generated from the project's README
About mindin MCP server
mindin provides a structured memory system for AI agents and developers by managing markdown notes within a schema-validated vault. Users can store their data in local folders, S3 buckets, or a dedicated vault server running via Docker Compose. This setup allows tools like Claude Code, Codex, Cursor, and Claude Desktop to search, read, and write notes that follow strict rules regarding required fields and tag vocabularies.
The system integrates deeply with development workflows by linking notes to git history and specific file paths. It includes specialized lifecycle tools such as close for archiving, backlog_add for deferred tasks, log_append for session tracking, and lint to detect configuration drift. For teams, a vault server enables shared wikis where members of the same email domain can collaborate while maintaining security through automated guards against secrets. The server supports authentication via GitHub, passkeys, or email links.
What you can do with it
- 1Track development session historyUse the system to automatically record one line per repository for every active session.
- 2Manage task lifecyclesInstruct the agent to archive completed work or move deferred items to a backlog.
Written from the project's README. Every use case is checked against a quote from it.
How to install mindin MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall mindin MCP in Claude Code
$ claude mcp add --env 'S3_ACCESS_KEY=<YOUR_S3_ACCESS_KEY>' --env 'S3_SECRET_KEY=<YOUR_S3_SECRET_KEY>' mindin -- uvx mindinInstall mindin MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mindin": {
"command": "uvx",
"args": [
"mindin"
],
"env": {
"S3_ACCESS_KEY": "<YOUR_S3_ACCESS_KEY>",
"S3_SECRET_KEY": "<YOUR_S3_SECRET_KEY>"
}
}
}
}Install mindin MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mindin": {
"type": "stdio",
"command": "uvx",
"args": [
"mindin"
],
"env": {
"S3_ACCESS_KEY": "<YOUR_S3_ACCESS_KEY>",
"S3_SECRET_KEY": "<YOUR_S3_SECRET_KEY>"
}
}
}
}Install mindin MCP in VS Code CLI
$ code --add-mcp '{"name":"mindin","type":"stdio","command":"uvx","args":["mindin"],"env":{"S3_ACCESS_KEY":"<YOUR_S3_ACCESS_KEY>","S3_SECRET_KEY":"<YOUR_S3_SECRET_KEY>"}}'Install mindin MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mindin": {
"command": "uvx",
"args": [
"mindin"
],
"env": {
"S3_ACCESS_KEY": "<YOUR_S3_ACCESS_KEY>",
"S3_SECRET_KEY": "<YOUR_S3_SECRET_KEY>"
}
}
}
}Install mindin MCP in Codex
$ codex mcp add mindin --env 'S3_ACCESS_KEY=<YOUR_S3_ACCESS_KEY>' --env 'S3_SECRET_KEY=<YOUR_S3_SECRET_KEY>' -- uvx mindinInstall mindin MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mindin] command = "uvx" args = ["mindin"] [mcp_servers.mindin.env] S3_ACCESS_KEY = "<YOUR_S3_ACCESS_KEY>" S3_SECRET_KEY = "<YOUR_S3_SECRET_KEY>"
Install mindin MCP in Gemini CLI
$ gemini mcp add -s user -e 'S3_ACCESS_KEY=<YOUR_S3_ACCESS_KEY>' -e 'S3_SECRET_KEY=<YOUR_S3_SECRET_KEY>' mindin uvx -- mindinInstall mindin MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mindin": {
"command": "uvx",
"args": [
"mindin"
],
"env": {
"S3_ACCESS_KEY": "<YOUR_S3_ACCESS_KEY>",
"S3_SECRET_KEY": "<YOUR_S3_SECRET_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for mindin 0.19.0 in an isolated container with no network and no keys. It answered and listed 19 tools.
mindin MCP tools 19
Read from the server with tools/listsearchCHEAP — start here. Full-text search over the local SQLite index of the vault; it never downloads the whole vault. Matches file stem, title, summary, tags and body, folds diacritics, expands synonyms and accepts "quoted phrases". A bare commit sha looks up the notes that mention it. A query that is exactly a note's stem, or its [[stem]] wikilink, puts that note first wherever it lives. Every term is required; when no note has them all, it returns the notes matching the most terms and says so in the header. Inflected forms match through stemming in the vault's languages. Search in the vault's language first; when nothing matches, translate the terms into the vault's other languages and search again, and the reply names them. Excludes the archive and superseded notes unless you ask for them, and reports how many it hid. limit defaults to the vault schema's search.default_limit.
read_fileMODERATE — one round trip to storage. Returns the note with an `etag:` first line; pass that etag back to write_file to refuse a write over someone else's change. Search first. `.vault/schema.yml` reads the vault's schema.
write_fileWRITE — validates the frontmatter against the vault schema, and the body of a new note, or of one that already follows it, against the template of its kind (see `template`), and refuses the write if either does not hold. Stamps `updated` with today and fills `date` when missing. Pass expected_etag from read_file to make the write conditional, or "*" to create a note that must not exist yet.
append_fileWRITE — appends to an existing note and bumps `updated`; the note must still satisfy the schema. A missing note is refused: create it with write_file.
move_fileWRITE — moves or renames a note; the note must satisfy the schema at the destination. Use `close` to archive finished work.
delete_fileWRITE — deletes a note for good. Prefer `close`, which keeps it.
list_filesCHEAP — paths only, no metadata and no bodies. `search` answers context questions better.
set_statusWRITE — changes a note's status without rewriting it: backlog (with a priority: urgent, high, medium, low) parks it, active picks it up again, draft. The triage list at session start is settled with this, append_file or close.
closeWRITE — finishes a note: sets status complete (or superseded with superseded_by when merged_into is given) and moves it into the archive. Run it in the same pass as the last commit of the work; a note left open is what makes the vault drift.
backlog_addWRITE — files an idea as a backlog note in the task folder: title, area (stem or [[stem]]), optional priority (urgent, high, medium, low) and source (who said it and when, or a sha), and either line, one line saying what and why, which files a draft of the task template to write out later, or sections, the task template's sections by key (see `template`), its required ones filled, with line then as the summary. Call it the moment something is deferred, in so many words or in passing; picking the idea up later is setting its status to active.
backlogCHEAP — the backlog sorted by priority then age. Filter by area (a stem, or the prefix a family of stems shares) and by priority.
log_appendWRITE — appends one dated line to the repo log, with the commits it produced. Run once at the end of a session per repo. Creates the log note when it is missing. repo is the main checkout's name, also from a worktree; branch is the branch the commits were made on. area is the stem of the system note (or [[stem]]); it defaults to the repo name.
Show all 19 toolsShow fewer tools
contextCHEAP — the session-start call. Returns the system notes covering the code at `path`, the open tasks for it, the reference notes and the tail of the repo log, in one answer. Use it before searching blind. format "json" adds the system notes' paths and dates and the triage keys, for hooks that read it. remote is the repo's origin URL; the bundle adds the pages that name the repo or its area from the organisation vaults the connection reaches.
changesCHEAP — for tools that follow a vault, such as a board: the notes written, deleted or moved since cursor, each once in its latest state, with its frontmatter and, with include "body", its body. Answers JSON {"cursor", "reset", "more", "changes": [{"key", "action": write|delete|schema, "version", "note"}]}. Without cursor, or when the cursor is too old to follow, reset is true: read the whole vault, then follow from the cursor. more means call again at once. wait holds the answer up to 50 seconds until something changes.
templateCHEAP — the headings a note of a kind is written to, from the vault's schema: each section's key, heading in the vault's language and whether it is required, the section that holds open questions, and a skeleton to fill. Without kind, every kind that has a template. write_file holds a new note to it, and a note that already follows it, unless its status is backlog or draft. Answers JSON.
rulesCHEAP — a vault's own rules for agents: its folders, the frontmatter contract, when and how to write there, and what session start shows from it. Read them before the first write to a vault reached through `vault`; for the main vault they are the server's instructions.
whoamiCHEAP — who this connection signs in as and whether it may write. Answers JSON.
lintMODERATE — reads every note to report drift: broken frontmatter, missing required fields, missing area, unresolved wikilinks, orphans, stale open tasks, archived notes still marked active, duplicate stems and superseded targets that do not exist.
initWRITE — sets a vault up: writes `.vault/schema.yml` and the Obsidian Bases views into the vault root. Run once per vault, right after installing. preset picks the layout of a vault without a schema: default, para, simple, journal, custom; without it, the vault gets default. On a vault that has a schema, it only writes the views that are missing and keeps the rest; a layout is switched with the CLI (`init --preset <name> --force`) or on the account page, never through this tool.
Configuration
S3_ACCESS_KEYSecretAccess key for the vault bucket
S3_SECRET_KEYSecretSecret key for the vault bucket
S3_BUCKETBucket holding the vault
S3_ENDPOINTS3 or MinIO endpoint URL holding the vault
S3_PREFIXKey prefix inside the bucket
S3_REGIONRegion for the vault bucket
VAULT_CACHE_DIRWhere the SQLite index lives
VAULT_PATHDirectory holding the vault. Set this or the four S3_* variables.
VAULT_SCHEMALocal schema file overriding the one in the vault
VAULT_STOP_HOOKSet to off to disable the stop hook
VAULT_STOP_HOOK_COMMITSSet to off to turn off the stop hook's unlogged-commit and stale-note checks alone
VAULT_STOP_HOOK_PROMPTSMessages the user writes after the agent's last vault write before the stop hook asks it to save them (default 3), or off
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablegronare/mindin is public and reachablegithub.com/gronare/mindin ↗Pass
- Package names this repository as its sourcemindin names gronare/mindin as sourcepypi.org/project/mindin/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for mindinpypi.org/project/mindin/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/gronare/mindin ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from mindinPass
- No critical advisory in the package or its dependencies44 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmindin
Memory for Claude and coding agents, kept as markdown notes you own, with a schema that holds and a tie to your git history.
Install
curl -fsSL https://mindin.dev/install.sh | sh
It installs the mindin command with uv, asks where your vault lives (a folder, an S3 bucket or a vault server), and offers to add the vault to Claude Code, Codex and Cursor; it changes nothing in them without a yes. The notes-vault-mcp package and command install and run mindin too.
A vault server
A vault server with Docker Compose, for claude.ai, Claude Desktop, mobile and every machine you work on. On the server:
curl -fsSL https://github.com/gronare/mindin/releases/latest/download/server.sh | sh
You need Docker with Compose v2, a domain pointing at the machine, and ports 80 and 443 open; an SMTP account sends sign-in links, or people sign in with GitHub. The script asks for the domain, the SMTP settings and your email, makes the master key, starts the server and prints the address to open. Install with Docker has what it does and the same steps by hand.
Without the script, on one machine: uv tool install mindin, then mindin setup.
mindin asks before it shares anonymous usage data, and sends nothing until you say yes: then, once a day, a random install id, mindin's version, the OS and CPU type and how mindin runs (plugin, CLI or server) go to signals.mindin.dev, never notes, names, paths or your vault's address. mindin setup --signals yes|no changes the answer. Configuration has the setting.
Use
Add the server's address, https://VAULT_HOST/mcp, as a custom connector in claude.ai. Claude searches, reads and writes your notes. The same search from a shell on a signed-in machine:
$ mindin search "signing in"
1 note · archive and superseded hidden
myapp system 3 days
Areas/myapp.md
## Sign-in Users sign in with passkeys; email links are the fallback.
What you get
- Notes you own. Plain markdown in a folder or an S3 bucket; open them in Obsidian, keep them in git.
- A schema with teeth. Required fields, legal statuses and kinds, a tag vocabulary; a write that breaks the contract is refused. Start from PARA, a simple vault, a journal or your own layout.
- A lifecycle.
closearchives finished work,backlog_addfiles what was deferred,log_appendwrites one line per repo per session,lintreports drift. - Memory tied to code. A note names the paths it describes; the session-start hook prints the commits newer than the note.
- Search that reads your languages. Stemming, folded diacritics, synonyms, and optional search by meaning that runs on your machine.
- Your own vault server. Accounts with passkeys, email links, GitHub or your identity provider, several vaults each, shared vaults, sealed in storage.
- A wiki for your team. Everyone at your company's email domain joins an organisation and its wiki; their Claude searches it beside their own vault, and a guard refuses secrets.
- A vault that moves.
mindin movecopies a vault between a folder, a bucket and a server, and checks every file.
Documentation
docs/ has the install guides, the how-tos for each client, the reference for every tool, command and setting, and how it works.
Contributing
See CONTRIBUTING.md. Report a vulnerability privately, as SECURITY.md describes.
License
MIT. See LICENSE.
mindin MCP questions
How do I add mindin MCP to Claude Code?
Run claude mcp add --env 'S3_ACCESS_KEY=<YOUR_S3_ACCESS_KEY>' --env 'S3_SECRET_KEY=<YOUR_S3_SECRET_KEY>' mindin -- uvx mindin in your terminal. Add --scope user to make it available in every project.
How do I add mindin MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does mindin MCP provide?
It exposes 19 tools, including search, read_file, write_file, append_file, move_file.
Where can I store my notes vault?
You can store your vault in a local folder, an S3 bucket, or a dedicated vault server.
How does the schema enforcement work?
The system uses a schema with required fields, legal statuses, and tag vocabularies to refuse any writes that break the defined contract.
Can I use this with my team?
Yes, you can create a wiki for your team where everyone at your company's email domain joins an organization and searches the shared wiki.
Does mindin collect my private data?
No, mindin only sends anonymous usage data like version and OS if you opt-in, and never sends notes, names, paths, or vault addresses.