Skip to main content

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.

License: MIT PyPI Python 3.11+

  • 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)

Source distribution for memgrove 0.4.1
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)

Table of built distributions (wheels) for memgrove 0.4.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Release history Release notifications | RSS feed

This release

0.4.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page