memory-mcp

Persistent memory for AI agents over the Model Context Protocol (MCP). Filesystem-backed, dependency-light, with keyword search — so an agent can remember things across sessions without a database, embeddings, or API keys.

Why

Most agents forget everything between runs. memory-mcp gives any MCP-compatible client (Claude Desktop, Claude Code, and others) five simple tools to write, read, search, list, and delete memories that persist on disk as plain JSON. The storage layer is standard-library only and independently tested, so it's easy to audit and hard to break.

Related MCP server: engram

Tools

Example

What the agent sees when it calls memory_write, then memory_read, then memory_search (these are the literal text responses the tools return over MCP):

> memory_write(key="project-x-decision", content="We chose Postgres over SQLite for project X because we need concurrent writes.", tags=["project-x", "decisions"])
Stored 'project-x-decision' (updated_at=2026-07-25T20:43:59Z). Tags: project-x, decisions

> memory_read(key="project-x-decision")
key: project-x-decision
tags: project-x, decisions
created_at: 2026-07-25T20:43:59Z
updated_at: 2026-07-25T20:43:59Z
---
We chose Postgres over SQLite for project X because we need concurrent writes.

> memory_search(query="postgres")
1 match(es) for 'postgres':
- [1] project-x-decision: We chose Postgres over SQLite for project X because we need concurrent writes.

On disk, that entry is stored as plain JSON (~/.memory-mcp/store.json by default):

{
  "version": 1,
  "entries": [
    {
      "key": "project-x-decision",
      "content": "We chose Postgres over SQLite for project X because we need concurrent writes.",
      "tags": ["project-x", "decisions"],
      "created_at": "2026-07-25T20:43:59Z",
      "updated_at": "2026-07-25T20:43:59Z"
    }
  ]
}

Install

pip install git+https://github.com/M-Ashrey/memory-mcp

Requires Python 3.10+.

Use with Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "memory": {
      "command": "memory-mcp"
    }
  }
}

By default, memories are stored under a local file resolved from the MEMORY_MCP_PATH environment variable. Set it to control where data lives:

{
  "mcpServers": {
    "memory": {
      "command": "memory-mcp",
      "env": { "MEMORY_MCP_PATH": "/path/to/memory.json" }
    }
  }
}

Develop

git clone https://github.com/M-Ashrey/memory-mcp
cd memory-mcp
pip install -e ".[dev]"
pytest

The store logic (memory_mcp/store.py) has no third-party dependencies and its tests never import the MCP server, so the test suite runs even without the mcp SDK installed.

Related

Part of a small set of AI-agent tooling — see also the Claude MCP starter kit.

Support this work

memory-mcp is free and MIT licensed. If it's useful to you, you can help keep it maintained through GitHub Sponsors or Ko-fi.

Contributing

Bug reports and pull requests are welcome at github.com/M-Ashrey/memory-mcp/issues. See SECURITY.md to report a vulnerability privately.

License

MIT