Metadata-Version: 2.4
Name: mimir-memory-mcp
Version: 0.12.0
Summary: Mimir — structured memory MCP server for AI assistants
Project-URL: Repository, https://github.com/jimmy-larsson/mimir
Author: Jimmy Larsson
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: fastmcp>=3.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# Mimir

**Structured memory MCP server for LLMs.**

Mimir provides persistent, structured memory for any LLM application via the [Model Context Protocol](https://modelcontextprotocol.io/). Multi-user, scope-based access control, tiered context loading, full-text search.

Named after [Mímir](https://en.wikipedia.org/wiki/M%C3%ADmir), the Norse keeper of the Well of Wisdom.

## Quick Start

### pip

```bash
pip install mimir-mcp
MIMIR_DB_PATH=./mimir.db MIMIR_PORT=8100 mimir-mcp
```

### Docker

```bash
docker run -p 8100:8100 -v mimir-data:/data mimir-mcp
```

### From Source

```bash
git clone https://github.com/jimmy-larsson/mimir.git
cd mimir
pip install -e ".[dev]"
MIMIR_DB_PATH=./mimir.db mimir-mcp
```

## Configuration

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `MIMIR_DB_PATH` | `/data/mimir.db` | SQLite database file path |
| `MIMIR_PORT` | `8100` | SSE transport port |

## Provisioning Users

Mimir uses API key authentication. Create users via SQL seed file:

```sql
INSERT INTO users (id, name, is_admin, api_key)
VALUES ('myuser', 'My User', TRUE, 'your-uuid-v4-api-key');

INSERT INTO scopes (id, name, description)
VALUES ('myuser', 'My User', 'Personal scope');

INSERT INTO scope_members (scope_id, user_id)
VALUES ('myuser', 'myuser');

INSERT INTO activity_cursor (user_id, last_seen_history_id)
VALUES ('myuser', 0);
```

Load it:

```bash
mimir-mcp seed --file seed.sql
```

## Integrating with Claude Code

See [docs/integration/claude-code.md](docs/integration/claude-code.md) for full setup instructions.

**Quick version:** Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "mimir": {
      "url": "http://localhost:8100/sse",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

Then add the Mimir usage snippet to your `CLAUDE.md` — see integration docs for the full snippet.

## MCP Tools (23)

| Category | Tools |
|----------|-------|
| Session | `start_session`, `end_session`, `save_session` |
| Context | `set_context`, `refresh_context` |
| Items | `add_items`, `update_item`, `complete_items`, `archive_items`, `delete_items`, `convert_item` |
| Navigation | `get_details`, `list_children`, `get_history`, `add_note` |
| Search | `search_items`, `list_items`, `get_facts` |
| Ordering | `reorder_items` |
| Scopes | `list_scopes`, `create_scope`, `add_scope_member`, `remove_scope_member` |

## Development

```bash
pip install -e ".[dev]"
pre-commit install   # installs ruff check/format as a git hook
pytest tests/ -v
```

## License

MIT
