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. Notes are ordinary Markdown files in
~/.agents/memgrove — not a database — and the agent decides what is worth saving and reads a
note back when it is relevant.
- One store, every agent: project notes stay separate from user-wide preferences, and every connected client sees both.
- Readable and portable: inspect, edit, or back up the files with ordinary tools. There is no config file, no runtime state, and no database.
- Cross-platform: Python 3.11+, standard library only; Linux, macOS, and Windows.
- Safer edits: version checks refuse stale writes instead of overwriting a newer note, and a basic secret-pattern guard blocks common credentials before they are stored. It is not a full secret scanner.
Data note: Notes are unencrypted local files. The tool does not sync or back them up, and when an agent reads a note, that text may be sent to its model provider.
Install
Requires Python 3.11 or newer and either uv or pipx:
uv tool install memgrove # or: pipx install memgrove
memgrove --version
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. Already have notes in Claude Code?
Import them.
On Windows the same commands work in PowerShell; see
Windows notes.
Connect an agent
Claude Code:
claude mcp add memgrove memgrove mcp --scope user
Also set "autoMemoryEnabled": false in ~/.claude/settings.json; otherwise Claude Code's native
memory keeps writing a separate store.
OpenCode — ~/.config/opencode/opencode.json:
{ "mcp": { "servers": { "memgrove": { "type": "local", "command": ["memgrove", "mcp"] } } } }
DSH, an agent with no MCP client, and the details of how the server's usage contract reaches the model are in docs/agents.md.
Check it works
In a new session, ask the agent to remember something — "remember that this project uses pnpm" —
then, from that project directory, look at the store (--cwd acts on another project):
memgrove list
memgrove index
On the next session's first turn the agent should call memgrove_index and see that note. If
nothing arrives, check memgrove --version and the client's MCP log.
How it works
Retrieval is the index. memgrove_index returns the whole table of contents, memgrove_read
loads one note, and memgrove_write saves one and consolidates its scope before returning: no
keyword search, no model call, and nothing injected behind the agent's back. The server does not
record conversations by itself; the agent chooses what is worth saving and when to read it back.
Each note is one Markdown file with a name, a one-line description, and one of four types
(user, feedback, project, reference), in one of two scopes: global for what applies
everywhere and projects/<slug> for one working directory. A rewrite changes only the fields you
pass, so fixing a body cannot move a note to another section of the index.
Documentation
| Document | Contents |
|---|---|
| docs/agents.md | MCP setup per client, the instructions contract, manual connection |
| docs/usage.md | CLI reference, exit codes, consolidation, store layout, importing Claude Code notes |
| docs/windows.md | Windows install and shell differences |
| docs/design.md | the design, the alternatives dropped, and the closed decisions |
| docs/roadmap.md | the changelog |
| docs/research.md | how Claude Code and Qoder actually work |
Development
git clone https://github.com/m-hosseinpour/memgrove.git
cd memgrove
uv tool install . # refresh after a pull: uv tool install --reinstall .
export MEMGROVE_ROOT=$(mktemp -d) # the suite must not touch the real store
python3 -m unittest discover -s tests -v
python -m memgrove and bin/memgrove run the checkout without installing. Repository rules,
the Windows test command, and the release process are in
AGENTS.md.
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.1
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.1.tar.gz | 79.1 kB | With provenance | Details for memgrove-0.4.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| memgrove-0.4.1-py3-none-any.whl | Python 3 | none | any | Details for memgrove-0.4.1-py3-none-any.whl |
Total release size: 117.1 kB
Release files / memgrove-0.4.1.tar.gz
| Download URL | memgrove-0.4.1.tar.gz |
|---|---|
| Size | 79.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4c9aa1b4aeb749aaab87edb26ce6668c2d586fae31450e5c675106dd8d974485
|
|
BLAKE2b-256 checksum How to use checksums |
d449010084903005e67f3bb5e18a4724a2ca980a07499bd749393da9240e8533
|
| 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.1-py3-none-any.whl
| Download URL | memgrove-0.4.1-py3-none-any.whl |
|---|---|
| Size | 38.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f06420213f17602d7d82364af693745d512ee16efcc999a198de3df918c5dafd
|
|
BLAKE2b-256 checksum How to use checksums |
644a7ddadc06b1aa00a492e93dcc573985d8fd28fd783eff7823c5bdd9de8ecb
|
| 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.1
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.1.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.