Mimir

Structured memory server for AI assistants.

Mimir stores what an assistant needs to keep: work (threads, tasks, reminders) and knowledge (rules, facts) anchored to the work it is about. Multi-user, scope-based access control, tiered context loading, keyword search, a full audit trail.

The HTTP API is the contract. The MCP surface is a generated adapter over the same operation registry — every operation exists on both, and neither can quietly grow one the other lacks.

Named after Mímir, the Norse keeper of the Well of Wisdom.

1.0 is a clean break

1.0 does not read a 0.x database. New schema, new API, new database file; the server refuses a pre-1.0 file at boot and names the way across:

mimir-mcp migrate --from ./old-mimir.db --to ./mimir.db

The migration is a one-time move into a new file — dry-runnable, with judgement queues for what does not map cleanly. The 0.x tool names and session lifecycle (start_session, end_session, set_context, …) are gone: nothing opens, closes or resumes — every call carries its own authority, and re-reading replaces remembering.

Quick Start

pip

pip install mimir-memory-mcp
# write seed.sql — your principal, scope, membership (see Provisioning below)
MIMIR_DB_PATH=./mimir.db MIMIR_SEED_FILE=./seed.sql MIMIR_PORT=8100 mimir-mcp

Docker

cp seed.sql.example data/seed.sql   # edit: your principal and scope
docker compose up -d --build        # compose provides MIMIR_DB_PATH and MIMIR_SEED_FILE

scripts/setup.sh walks the same steps with a health check.

From Source

git clone https://github.com/jimmy-larsson/mimir.git
cd mimir
pip install -e ".[dev]"
cp seed.sql.example seed.sql        # edit: your principal and scope
MIMIR_DB_PATH=./mimir.db MIMIR_SEED_FILE=./seed.sql mimir-mcp

Configuration

Provisioning

Identity and credentials are separate things, provisioned separately:

1. Principals, scopes, memberships come from a seed file — see seed.sql.example. No credentials live there: 1.0 stores token hashes, so a plaintext key in a seed file would be a recoverable credential on disk. Auto-applied at boot via MIMIR_SEED_FILE while the database has no principals, or loaded by hand: mimir-mcp seed --file seed.sql.

2. Tokens are minted, never seeded. In the hermes deployment, hermes-template's provisioning does this. Standalone, bootstrap the first token at the domain — point MIMIR_DB at the same file the server runs against (the plaintext is printed once and never recoverable):

MIMIR_DB=./mimir.db python -c "
import os
from mimir_mcp.db import init_db
from mimir_mcp import tokens
db = init_db(os.environ['MIMIR_DB'])
row, plaintext = tokens.mint(db, 'your-user-id', label='console', scopes='*',
                             may_write_rules=True, privileged=True)
print(plaintext)"

Docker: run the same snippet inside the container against the volume — docker compose exec mimir env MIMIR_DB=/data/mimir.db python -c "…".

Every further token is minted over the API (POST /tokens / manage_tokens) with that one. A token is a first-class object: a scope subset, capability limits, individually revocable, rotatable with an overlap window. Authority is always token.scopes ∩ live membership, resolved per request.

The Surface

Five item types — thread · task · reminder · rule · fact. Type carries force (a rule binds, a fact informs), anchors carry reach (knowledge loads with the work it is anchored to).

HTTP (the contract)

Authenticate with x-api-key. Every response carries X-Mimir-API-Version.

MCP Tools (15)

Generated from the same registry; served at http://host:8100/mcp.

Integrating with Claude Code

See docs/integration/claude-code.md. Quick version — add to .mcp.json:

{
  "mcpServers": {
    "mimir": {
      "type": "http",
      "url": "http://localhost:8100/mcp",
      "headers": {
        "x-api-key": "YOUR_TOKEN"
      }
    }
  }
}

Development

pip install -e ".[dev]"
pre-commit install   # installs ruff check/format as a git hook
python -m pytest tests/ -q

License

MIT