# memory-mcp

Persistent memory for AI agents over the [Model Context Protocol](https://modelcontextprotocol.io) (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.

## Tools

| Tool | What it does |
|------|--------------|
| `memory_write` | Store or update an entry under a key (with optional tags). |
| `memory_read` | Read an entry back by its key. |
| `memory_search` | Keyword search across content, tags, and keys — returns ranked snippets. |
| `memory_list` | List all keys, optionally filtered by tag. |
| `memory_delete` | Remove an entry by key. |

## 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):

```json
{
  "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

```bash
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`:

```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:

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

## Develop

```bash
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](https://github.com/M-Ashrey/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](https://github.com/sponsors/M-Ashrey) or [Ko-fi](https://ko-fi.com/ashrey122).

## Contributing

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

## License

MIT