# hmem MCP server

> Gives AI agents a persistent hierarchical memory so they recall projects, decisions, errors and sessions across devices and providers.

- Repository: https://github.com/Bumblebiber/hmem
- Page: https://hostedmcp.org/servers/bumblebiber/hmem
- Transport: stdio
- Stars: 24
- License: MIT
- Latest version: 1.6.7

## Install

### Claude Code

```sh
claude mcp add hmem -- npx -y hmem-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "hmem": {
      "command": "npx",
      "args": [
        "-y",
        "hmem-mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "hmem": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "hmem-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"hmem","type":"stdio","command":"npx","args":["-y","hmem-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "hmem": {
      "command": "npx",
      "args": [
        "-y",
        "hmem-mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add hmem -- npx -y hmem-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.hmem]
command = "npx"
args = ["-y", "hmem-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user hmem npx -- -y hmem-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "hmem": {
      "command": "npx",
      "args": [
        "-y",
        "hmem-mcp"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `HMEM_AGENT_ID` | no | no |  |
| `HMEM_PATH` | no | no |  |
| `HMEM_PROJECT_DIR` | no | no |  |
| `HMEM_STORAGE_DIR` | no | no | Directory where .hmem SQLite databases are stored. Defaults to ~/.hmem/ |

## Tools (25)

- `hmem`
- `hmem-curate`
- `read_memory`
- `write_memory`
- `append_memory`
- `update_memory`
- `search_memory`
- `find_related`
- `load_project`
- `read_project`
- `create_project`
- `list_projects`
- `flush_context`
- `move_nodes`
- `set_active_device`
- `memory_stats`
- `memory_health`
- `export_memory`
- `import_memory`
- `update_many`
- `tag_bulk`
- `tag_rename`
- `move_memory`
- `rename_id`
- `reset_memory_cache`

## FAQ

### What does hmem give an AI agent?

It provides persistent memory across sessions, devices and AI providers, storing project knowledge in a 5-level hierarchical tree. A single load_project call returns a briefing for about 3000 tokens.

### How does the 5-level lazy loading work?

Level 1 one-line summaries load first, and Levels 2 through 5 are fetched only when detail is needed. Full original text is kept in the deeper levels.

### What storage does hmem use?

It is backed by SQLite with FTS5 full-text search, and search matches are attributed to the right sub-nodes.

### How many MCP tools does hmem expose?

There are two MCP servers: a daily-use hmem server with 13 tools and an opt-in hmem-curate maintenance server with 11 destructive tools.

### Can I use hmem in my own code?

Yes, it ships as a documented TypeScript SDK exposing HmemStore, openCompanyMemory and searchMemory.
