mnemosyne service grpc client library

mnemosyne, grpc, session, service, client, docker, golang, protobuf
pip install mnemosyne-client==0.18.4


Mnemosyne CircleCI

GoDoc Test Coverage Code Climate Docker Pulls pypi


Mnemosyne is an open-source self-hosted session management service. It's written in Go, making it easy to build and deploy as a static binary.

It provides gRPC interface. Messages are encoded using protobuf.

Quick Start

To install and run service:

$ go get -d
$ cd $GOPATH/src/
$ make
$ mnemosyned -log.environment=development -postgres.address='postgres://localhost/example?sslmode=disable'

Storage Engine

Goal is to support multiple storage's, like PostgreSQL, Redis or MongoDB. Nevertheless currently supported is only PostgreSQL.

Remote Procedure Call API

For communication, Mnemosyne is exposing RPC API that uses protocol buffers, Google’s mature open source mechanism for serializing structured data.

  • Create
  • Get
  • List
  • Exists
  • Abandon
  • SetData
  • Delete


Mnemosyne can be installed in one way, from source. Or can be used as a container using docker image. It is worth to mention that latest tag is released after each successful master branch build. Please use only images tagged using specific version anywhere else than a local development environment.

From source

To install from source both go tools and dep is required.

$ go get -d
$ cd $GOPATH/src/
$ make


mnemosyned accepts command line arguments to control its behavior. Possible options are listed below.

Name Flag Default Type
host -host string
port -port 8080 int
grpc debug mode -grpc.debug false boolean
cluster listen address -cluster.listen string
cluster seeds -cluster.seeds string
time to live -ttl 24m duration
time to clear -ttc 1m duration
logger environment -log.environment production enum(development, production, stackdriver)
logger level -log.level info enum(debug, info, warn, error, dpanic, panic, fatal)
storage -storage postgres enum(postgres)
postgres address -postgres.address postgres://postgres:postgres@postgres/postgres?sslmode=disable string
postgres table -postgres.table session string
postgres schema -postgres.schema mnemosyne string
tls -tls false boolean
tls certificate file -tls.crt string
tls key file -tls.key string


As we know, mnemosyne can be configured in many ways. For the beginning we can start simple:

$ mnemosyned postgres.address="postgres://localhost/test?sslmode=disable"

Mnemosyne will automatically create all required tables/indexes for specified database.


mnemosyned works well with Prometheus. It exposes multiple metrics through /metrics endpoint, it includes:

  • mnemosyned_cache_hits_total
  • mnemosyned_cache_misses_total
  • mnemosyned_cache_refresh_total
  • mnemosyned_storage_postgres_errors_total
  • mnemosyned_storage_postgres_queries_total
  • mnemosyned_storage_postgres_query_duration_seconds
  • mnemosyned_storage_postgres_connections

Additionally to that mnemosyned is using internally promgrpc package to monitor entire incoming and outgoing RPC traffic.



package main

import (


func main() {
	mnemo, err := mnemosyne.New(mnemosyne.MnemosyneOpts{
		Addresses: []string{""},
		Block: true,
	if err != nil {
		// ...
	defer mnemo.Close()

	ses, err := mnemo.Start(context.Background(), "subject-id", "subject-client", map[string]string{
		"username": "",
		"first_name": "John",
		"last_name": "Snow",
	if err != nil {
		// ...



Library is available through pypi and can be installed by typing pip install mnemosyne-client.

from  mnemosynerpc import session_pb2, session_pb2_grpc
import grpc

channel = grpc.insecure_channel('localhost:8080')
stub = session_pb2_grpc.SessionManagerStub(channel)

for i in range(0, 10):
	res = stub.Start(session_pb2.StartRequest(session=session_pb2.Session(subject_id=str(i))))

	res = stub.Get(session_pb2.GetRequest(access_token=res.session.access_token))
	print "%s - %s" % (res.session.access_token, res.session.expire_at.ToJsonString())


TODO: describe