memgrove
Persistent, local-first Markdown memory for AI coding agents.
Give Claude Code, OpenCode, DeepSeek Harness (DSH), and other
Model Context Protocol (MCP) clients one shared store for
useful notes across projects and sessions. Memories are ordinary Markdown files on your
machine—not a database or opaque binary format—and the memgrove CLI and MCP server read and
write the same store.
MCP gives connected agents tools to read and write notes; it does not record every conversation automatically. Agents choose what is worth remembering and retrieve notes when relevant.
- One memory store, multiple agents: keep project-specific notes separate from user-wide preferences and share both with every connected MCP client.
- Readable and portable: inspect, edit, or back up the Markdown files with ordinary tools.
- No per-agent plugin: connect through MCP, or use the
memgrovecommand directly. - Safer concurrent edits: version checks refuse stale writes instead of silently overwriting newer notes. A basic secret-pattern guard blocks some common credentials; it is not a full secret scanner.
- Lightweight and cross-platform: Python 3.11+, standard library only; Linux, macOS, and Windows.
Data note: Notes are unencrypted local files. The tool does not sync or back them up. When an agent reads a note, that text may be sent to the model provider configured for that agent.
Install
Requires Python 3.11 or newer and either uv or pipx:
uv tool install memgrove # or: pipx install memgrove
memgrove --version
One console script, no per-agent plugin. Upgrade with uv tool upgrade memgrove (or
pipx upgrade memgrove), pin a release with memgrove==<version>, and run the server
without installing it with uvx --from memgrove memgrove mcp.
For Claude Code, connect the MCP server with:
claude mcp add memgrove memgrove mcp --scope user
For OpenCode, DSH, and other MCP clients, use the configuration examples in MCP.
For an agent without an MCP client, write the manual connection guide into the store:
mkdir -p ~/.agents/memgrove
memgrove protocol > ~/.agents/memgrove/PROTOCOL.md
The store is created on the first write at ~/.agents/memgrove. See
Migrating from Claude Code to import existing notes.
For Claude Code, also set "autoMemoryEnabled": false in ~/.claude/settings.json; otherwise its
native memory continues writing separately. More detail is in docs/design.md
§9–§10.
To work on the code, use a checkout and install that instead:
git clone https://github.com/m-hosseinpour/memgrove.git
cd memgrove
uv tool install .
After pulling an update to the checkout, refresh the installed command:
uv tool install --reinstall .
The checkout also runs without any install:
python -m memgrove --help # every platform
./bin/memgrove --help # Linux/macOS
bin\memgrove.cmd --help # Windows
MEMGROVE_ROOT points memgrove at a different root (used by the tests).
How it works
Retrieval is the index. No keyword search, no model call, and nothing injected behind the
agent's back. memgrove_index returns the whole table of contents, memgrove_read loads one note,
and memgrove_write saves one — then consolidates the store before it returns, so there is no
queued state and no background pass.
A rewrite changes only the fields the caller passes: name, description and type keep their
current values when omitted, so fixing a typo in the body cannot move a note to another section
of the index. A new note defaults to the filename stem, an empty description and project.
MCP
Register the server once per agent; there is nothing else to install per agent.
// Claude Code: ~/.claude.json (user scope), or `claude mcp add memgrove memgrove mcp --scope user`
{ "mcpServers": { "memgrove": { "command": "memgrove", "args": ["mcp"] } } }
// opencode: ~/.config/opencode/opencode.json
{ "mcp": { "servers": { "memgrove": { "type": "local", "command": ["memgrove", "mcp"], "enabled": true } } } }
# DSH: ~/.dsh/cordis.patch.yml (rewrite the file live, no restart needed)
- insert:
- id: mcp-memgrove
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: memgrove
transport: stdio
command: memgrove
args: ['mcp']
Tools:
| Tool | Arguments | Returns |
|---|---|---|
memgrove_index |
cwd? |
the table of contents of the global and the project store |
memgrove_read |
store, path, cwd? |
body, version, modified, type, description |
memgrove_write |
store, path, content, if_version, name?, description?, type?, cwd? |
the new version; consolidates the store first |
The server's usage contract — the two scopes, the four types, what not to save, if_version —
travels in the MCP instructions field of initialize / server/discover, which is what that
field is for. It opens with the session bootstrap: on the first user turn in the context, before
acting on it — even when the turn begins by loading a skill or reading files — call memgrove_index
with cwd; once per conversation, since a later user message is not a new session, and again
only after a compaction or a resume that did not carry the index, when it is no longer in context.
MCP has no channel that pushes the index into a client's context, so this contract is the
portable way to get it in front of the model without an adapter per client. No AGENTS.md
section is needed.
cwd exists for clients that run one server for several projects (DSH does); a per-project
client can omit it and the server uses its own working directory.
Manual usage
The CLI is the same store by hand. --scope defaults to project and --cwd to the current
directory, so a command run inside a project needs neither:
memgrove write --path pnpm-not-npm.md --name pnpm-not-npm \
--description "the lockfile is pnpm; npm install breaks CI" --if-version new <<'EOF'
The lockfile is pnpm. `npm install` rewrites it and breaks CI.
EOF
memgrove read --path pnpm-not-npm.md
memgrove list
memgrove index # the table of contents of both scopes
memgrove forget --path pnpm-not-npm.md
memgrove dream # a manual consolidation pass
memgrove dream --all # every project scope
memgrove migrate --dry-run # Claude Code notes: preview, write nothing
memgrove mcp # the MCP server on stdio
memgrove protocol # print PROTOCOL.md, the hand-wiring guide
memgrove --version
Pass --cwd /path/to/project to act on another project, and --scope global for the global
store.
Exit codes: 0 ok, 1 invalid input, 2 version conflict (the current content is returned so
the caller can merge), 3 content looked like a secret and was refused. migrate uses the same
codes for a batch: 3 if any note was refused, 1 if any note was invalid or collided with a
different existing note, 0 otherwise.
Migrating from Claude Code
Claude Code keeps auto memory per project under
${CLAUDE_CONFIG_DIR:-~/.claude}/projects/<slug>/memory/, in the note format this store reads.
memgrove migrate copies the notes in, skips the generated MEMORY.md, and lets this store rebuild
the index:
memgrove migrate --dry-run # the plan, no writes
memgrove migrate # every project, into projects/<slug>
memgrove migrate --global user,feedback # promote those types to global/
memgrove migrate --cwd /path/to/project # one project (e.g. a custom autoMemoryDirectory)
Claude Code's directory name cannot be decoded back to a path — it turns every non-alphanumeric
into -, so a dot is lost — so the importer reads the real cwd from the project's session logs
and builds the scope with the store's own slug. A project whose cwd cannot be recovered is
reported and skipped rather than written where no memgrove command would read it; --cwd resolves
a project from the cwd you already know.
Notes stay in their own project scope by default: one may say type: feedback and still be
about a single repository, and Claude Code kept it under one project. Each note goes through the
store's write path, so the filename rules, the size cap, the empty-body check and the secret
refusal apply, and --dry-run runs the same checks without writing. An existing file is never
overwritten: an identical note is exists, a different one is a collision (exit 1), and a
note the store already has under another filename — same type and name, or the same description
by the consolidation rule — is exists too, so a rerun cannot overturn what the first pass
kept. Consolidation then runs once per touched scope; replaced and merged say what the pass
deleted, and a migrated note it removed is reported as removed.
Consolidation
Every memgrove write/memgrove forget and every memgrove_write consolidates the scope it
touched before returning. The rules are deterministic — no model call:
- two files of the same type with the same
nameare one note; the newermodifiedwins and the older file is removed (its body is not merged); - two files of the same type whose descriptions use the same words are duplicates: word Jaccard 0.95 over descriptions of at most 19 distinct words, where only an identical word set can reach it. The older's unique lines are appended to the newest body, then the older file is removed; a description with more distinct words is never merged on similarity;
MEMORY.mdis rebuilt from the files, so a line for a deleted file cannot survive.
A pass deletes a file only while its bytes still match what it read, and writes a merged keeper
with the version it read, so a concurrent agent either wins cleanly or leaves both files for the
next pass. The pass is idempotent: running it twice changes nothing. memgrove dream runs it by
hand (--all for every project).
A description with more than 19 distinct words is not compared for similarity at all: at that
size the same 0.95 would begin to accept a qualifier, so two notes that long are left apart rather
than guessed at (the same-name rule still applies).
A restatement in other words is not merged, and rename-and-contradict is not detected —
the same fact under a different name or in a differently worded description stays as two
notes. That is deliberate: one added qualifier ("… tag blue", "… only") is what turns a
duplicate into a different note, and guessing that from text without a model is how the wrong
half of a pair gets deleted.
Store layout
$MEMGROVE_ROOT/
├── PROTOCOL.md # optional, for hand-wired agents; `memgrove protocol` prints it
├── global/{MEMORY.md,*.md} # user-wide preferences and facts
└── projects/<slug>/{MEMORY.md,*.md}
<slug> is the absolute cwd with every unsafe character replaced by - and ./_ kept:
/home/u/proj becomes -home-u-proj. On Windows the path is case-folded first, so
C:/Users/u/proj becomes c--users-u-proj and the same project cannot get two scopes from two
spellings. Each project gets one directory and no path escapes $MEMGROVE_ROOT.
There is no config file, no runtime state, and no git repository: the store is the notes and the
index. On Windows each scope also holds a .memgrove.lock file; the OS releases the lock when the
process exits, the file is invisible to the index, and it can be deleted while memgrove is not
running.
Windows
Everything above works unchanged; the differences are the shell and a few file-system rules.
-
Install with
uv tool install memgrove(orpipx install memgrove) in PowerShell;uv tool install .is the checkout form from Install.memgrove.exelands onPATH; open a new terminal so the PATH update is visible (Get-Command memgroveconfirms it). -
There is no bash requirement. Use the installed
memgrove,python -m memgrove, orbin\memgrove.cmdas the no-install launcher. -
README shell examples use bash heredocs. In PowerShell, pass the body inline or from a file:
memgrove write --path pnpm-not-npm.md --name pnpm-not-npm ` --description "the lockfile is pnpm; npm install breaks CI" ` --if-version new --content-file body.md
-
Notes written by Notepad or another CRLF editor are read correctly; the store writes LF, so one note has the same bytes on every OS.
memory.mdis reserved in any casing, because on a case-insensitive volume it is the generatedMEMORY.md. -
Claude Code's user config is
%USERPROFILE%\.claude.json;claude mcp add memgrove memgrove mcp --scope userworks in PowerShell as written. opencode and DSH use their own config files under the home directory, with the same JSON/YAML shown above. -
The CLI prints UTF-8 JSON regardless of the console code page. Windows PowerShell 5.1 can still garble non-ASCII output when it reads a native command; use PowerShell 7+, or run
[Console]::OutputEncoding = [Text.Encoding]::UTF8once per session. The same applies to saving the guide: PS 5.1's>writes UTF-16, so useNew-Item -ItemType Directory -Force -Path $HOME\.agents\memgrove memgrove protocol | Out-File -Encoding utf8 $HOME\.agents\memgrove\PROTOCOL.md
Development
bin/memgrove POSIX launcher for development (python3 -m memgrove, no install needed)
bin/memgrove.cmd Windows launcher for development
memgrove/store.py files, frontmatter, version tokens, conflicts, secret refusal, locking
memgrove/index.py MEMORY.md generation (atomic, no line budget)
memgrove/dream.py consolidation, called after every change and by `memgrove dream`
memgrove/mcp.py MCP stdio server: memgrove_index / memgrove_read / memgrove_write
memgrove/migrate.py import Claude Code's per-project notes and rebuild the index
memgrove/cli.py argparse surface
memgrove/PROTOCOL.md the agent-facing contract; `memgrove protocol` prints it, the shell saves it
.github/workflows/ the test suite on Linux and Windows, and the tag-triggered release
docs/ research.md, design.md, roadmap.md, operations.md
tests/ unittest (stdlib only)
Tests use the standard library only:
export MEMGROVE_ROOT=$(mktemp -d) # tests refuse to touch the real store
python3 -m unittest discover -s tests -v
On Windows:
$env:MEMGROVE_ROOT = Join-Path $env:TEMP "memgrove-test"
python -m unittest discover -s tests -v
A release is a tag. Bump __version__ in memgrove/__init__.py, commit, and push v<version>:
GitHub Actions runs the suite on Linux and Windows, builds the wheel and the sdist, uploads them
to PyPI through Trusted Publishing, and creates the GitHub Release with both files attached
(.github/workflows/release.yml). The one-time PyPI setup is in
docs/operations.md.
Background and rationale: docs/ — research.md (how Claude Code and Qoder actually
work, and which claims are verified), design.md (the design and the alternatives dropped),
roadmap.md (history), and operations.md (setup, env vars, and how to verify this machine).
README and PROTOCOL.md are English; the documents under docs/ are Persian.
Design notes
- No database, no search index. The index is regenerated from the files by scanning the directory, which is cheap at this scale and makes drift impossible.
- The index has no line budget. It is the whole retrieval path, so truncating it would hide notes rather than save context.
if_versionis mandatory on write unless--forceis passed: a blind overwrite is exactly what the token exists to prevent.- A rewrite keeps what it is not given.
name,descriptionandtypeare the only optional fields; omitting one leaves the file's current value in place, so a body-only fix cannot move a note to another section of the index. An empty--descriptionclears the description; an empty--namekeeps the current one. The store writes exactly three frontmatter keys (name,description,metadata) and drops any other hand-written key. nameanddescriptionare one line. A line break in either is refused before anything is written: the frontmatter is parsed line by line, so a value with a break would be cut there. Multiple lines belong in the body.- Schema is Claude Code's, minus session provenance. Four types (
user,feedback,project,reference) and the same frontmatter shape, but nooriginSessionId: no client hands the tool a session id, so the field was always empty and claimed a provenance the store could not have. Notes another tool wrote with that field are still read; the next rewrite drops it, while other metadata keys another tool added are left alone. - Concurrency rests on the version token, held under a short-lived lock.
writeanddeletetake an exclusive lock on the scope for the read-check-replace, because a token check without a lock is check-then-act: two writers holding the same token would both pass. On POSIX the lock is the directory's own inode — no file, no state, gone with the process. Windows cannot lock a directory handle, so there the lock is one byte of a.memgrove.lockfile in the scope; it is still kernel state rather than bookkeeping, and the OS drops it when the process dies. memgrove readtakes a flat.mdname..., absolute paths andMEMORY.md(in any case) are refused; the generated index ismemgrove index. A hand-written file with invalid UTF-8 is decoded with replacement characters instead of failing the command.- The store is local to one machine. There is no remote, no sync and no backup inside the
tool: the version token and the short-lived lock only protect writers on the same machine, and
a shared or network-backed store is not safe to write from two agents. Copy
~/.agents/memgroveelsewhere on a schedule if you want a backup; the tool will not do it. PROTOCOL.mdis not part of the agent's onboarding. The MCPinstructionsfield is. The protocol file is only for connecting an agent that has no MCP client; it ships inside the package andmemgrove protocolprints it, but the server never exposes it as a tool or a resource.- When testing, set
MEMGROVE_ROOTto a scratch directory. The default root is the real store.
License
MIT — see LICENSE.
If memgrove is useful in your workflow, consider starring the repository to help other developers looking for shared memory for their coding agents find it.
Metadata
Release files for memgrove 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| memgrove-0.4.0.tar.gz | 91.6 kB | With provenance | Details for memgrove-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| memgrove-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for memgrove-0.4.0-py3-none-any.whl |
Total release size: 135.1 kB
Release files / memgrove-0.4.0.tar.gz
| Download URL | memgrove-0.4.0.tar.gz |
|---|---|
| Size | 91.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8b6b5df086a02bbb44438167a4b8b7b386cc73c4c09c3a160aa9aa6f8674cec9
|
|
BLAKE2b-256 checksum How to use checksums |
84f1c4b22345fa7e78fc7ccf222e4efcca7ca1d045776c0d3664523b5f13cac3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / memgrove-0.4.0-py3-none-any.whl
| Download URL | memgrove-0.4.0-py3-none-any.whl |
|---|---|
| Size | 43.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a1a3aeba3098ebd6ee0c5c2cca6c8a2b913f37b3ad380aee8852e34a82093d3c
|
|
BLAKE2b-256 checksum How to use checksums |
f2b6bccb13818f5042ab695022344709bffa456b2b5697596eb045847f5cb824
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for memgrove 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for memgrove-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.