Skip to main content
Glama

Memini

A self-hosted knowledge service for an engineer or a team lead. Code repositories, work messages and meeting notes go in; an MCP server and an HTTP API come out.

It answers three kinds of questions:

  • Code: where and how is X implemented, across many repositories.

  • Decisions: what was decided about X, when, by whom, in which thread or meeting, and what it replaced.

  • My context: which meetings did I attend about X, which messages were sent to me.

Status

Milestone M0, the service skeleton, is done: the service runs under docker compose, applies its migrations, issues tokens and answers the MCP status tool. It does not index or search anything yet: code search is M1.

Related MCP server: openai-cookbook

Run the service

Memini runs as a long-lived service: one process (HTTP API, MCP endpoint, job worker and scheduler) and one Postgres database, started by Docker Compose. It needs Docker with compose.

git clone https://github.com/npavlov/memini.git
cd memini
docker compose up -d --wait

This builds the image from the checkout, starts Postgres and the service, applies the migrations and returns once both are healthy. The containers restart on failure and with Docker, unless you stop them. The service is published on 127.0.0.1:6364 only; the database on 127.0.0.1:55432. Data lives in the memini-db volume.

Get the first admin token from inside the container, once. It is printed once, on stdout; keep it in a file only you can read:

mkdir -p ~/.config/memini
(umask 077; docker compose exec -T memini memini bootstrap > ~/.config/memini/admin.token)

Everything else is the CLI on the host, a client of the service's HTTP API: from the checkout, run it with uv run memini …. It needs the service URL, MEMINI_URL (default http://127.0.0.1:6364), and a token, in MEMINI_TOKEN or in the file MEMINI_TOKEN_FILE names; it never takes a token on the command line. Create a workspace, add a repository, sync it and see the run, then make a read token for agents:

export MEMINI_TOKEN_FILE=~/.config/memini/admin.token
uv run memini workspace create demo
uv run memini source add demo shop --location https://git.example.com/team/shop.git --ref main --schedule 1h
uv run memini sync demo shop --wait
uv run memini runs demo
TOKEN=$(uv run memini token create --scope read --name laptop)

Connect an MCP client, for example Claude Code:

claude mcp add --transport http memini http://127.0.0.1:6364/mcp --header "Authorization: Bearer $TOKEN"

Or, in a client's JSON configuration:

{"mcpServers": {"memini": {"type": "http", "url": "http://127.0.0.1:6364/mcp",
                           "headers": {"Authorization": "Bearer <token>"}}}}

Backup and restore: scripts/backup.sh writes a pg_dump archive of the database, scripts/restore.sh FILE restores it into an empty stack; mirrors are cloned again and the credential key is kept apart. See docs/operations/backup.md.

Day to day:

Task

Command

Logs (JSON lines; tokens and secrets masked)

docker compose logs -f memini

Stop, keeping the data

docker compose stop

Update to a new checkout

git pull && docker compose up -d --wait

Check it end to end

make smoke

Health: GET /healthz; readiness, with the database: GET /readyz; the HTTP API schema: GET /openapi.json.

Embeddings

Search and git sync need an embedding model. The default is Qwen3-Embedding 0.6B, served by Ollama on your machine; no text leaves it.

  1. Install Ollama and pull the model (about 640 MB): ollama pull qwen3-embedding:0.6b

  2. Copy .env.example to .env, uncomment MEMINI_EMBEDDING_PROVIDER=openai_compatible, then docker compose up -d --wait.

That one setting implies the rest: the model, 1024 dimensions, the pinned Ollama digest and the query instruction. In compose the service reaches Ollama at http://host.docker.internal:11434/v1; a service run from source uses http://127.0.0.1:11434/v1. .env.example lists every value. On Linux, Ollama listens on 127.0.0.1 only: set OLLAMA_HOST=0.0.0.0:11434 for its service and keep port 11434 closed to other machines. Without a provider the service still starts, but it does not sync git sources and search answers embeddings_not_configured. Changing the model, dimension, digest or document prefix changes the index fingerprint: run memini reindex --workspace NAME afterwards.

Tools

Over MCP, and over HTTP with the same arguments as query parameters. All need a token with the read scope and see only the workspaces the token may read.

MCP tool

HTTP

What it does

search

GET /v1/search

Hybrid search over everything: code, and Markdown files of repositories

search_code

GET /v1/search/code

Code search: semantic, exact, regex or symbol; filters by repository, path glob, language

get_symbol

GET /v1/symbols

Definitions of a symbol, by name or qualified name

read_source

GET /v1/workspaces/{ws}/sources/{src}/files/{path}

A file or line range, or a directory listing

status

Stream lag, last runs, and whether the base is current

Every hit carries its source, a timestamp and a locator: shop@3f2a…:src/app.py#L12-L30 for code, chat:general/1772323200.000100#msg-1772323260.000200 for a message, with a link to it and an anchor that record_decision takes as evidence. read_source reads the service's own mirror at the pinned commit by default, so it matches search results; ref takes a branch, a tag or a full commit id. Search needs an embedding provider (MEMINI_EMBEDDING_*); reading files does not. An index_mismatch error means the embedding model or the chunker changed: run docker compose exec memini memini reindex --workspace NAME. Over HTTP, send a time zone offset's + as %2B, or use Z.

Repositories are added with memini source add, which calls POST /v1/workspaces/{ws}/sources with an admin token (see /openapi.json); the service mirrors and indexes them on their schedule, or at memini sync (POST /v1/workspaces/{ws}/sources/{src}/sync).

Commands

Client commands call the HTTP API of the running service. Run them from the host (uv run memini … in the checkout) with MEMINI_URL and MEMINI_TOKEN or MEMINI_TOKEN_FILE; --url URL and --token-file FILE override them for one run. Reading needs a token with the read scope, changing anything admin. Read commands take --json for the API's answer as it is.

memini workspace create <name> | list
memini source add <ws> <name> --location URL_OR_PATH --ref REF [--ref ...] [--schedule DURATION]
                  [--include GLOB ...] [--exclude GLOB ...] [--no-builtin-excludes] [--visibility V]
                  [--retention-days N] [--llm-policy P]
memini source add <ws> <name> --kind push [--visibility V] [--retention-days N] [--llm-policy P]
memini source list <ws> | show <ws> <source> | remove <ws> <source>
memini source edit <ws> <source> [--name NEW] [--ref REF ...] [--schedule DURATION | --no-schedule] ...
memini streams <ws> <source>                     # lag, last run and queued sync of each ref
memini sync <ws> <source> [--stream KEY ...] [--wait]
memini runs <ws> [--source NAME] [--stream KEY] [--limit N] [--before CURSOR]
memini run <run-id>                              # one run with its report
memini token create --scope {read,ingest,admin} [--scope ...] [--workspace NAME] [--name LABEL]
                    [--expires-in DURATION]      # prints the token alone, once
memini token list | revoke <id-or-prefix>
memini search <query> [--code] [--mode MODE] [--workspace NAME] [--repository NAME] [--limit N]
memini decision record <ws> --statement TEXT [--kind decision|open_question] [--decided-at TIME]
                       --evidence SOURCE:EXTERNAL_ID[#ANCHOR] [--participant PERSON_ID ...]
                       [--supersedes ITEM_ID[:replaces|answers] ...]   # needs the ingest scope
memini decision supersede <ws> <item-id> --supersedes ITEM_ID[:replaces|answers] [...]
memini decision close|retract <ws> <item-id>

Operator commands work on the database directly, so they run inside the service's container: docker compose exec memini memini …. They come before a token exists, or below the API.

memini serve [--migrate]
memini migrate
memini bootstrap [--name LABEL] [--expires-in DURATION] [--force]   # the first admin token
memini workspace llm <name> [none|local|cloud]   # which LLM may read a workspace; cloud is an opt-in
memini reindex --workspace <name>
memini replay --workspace <name> --source <name> --recipe PATH   # after a parser fix, no source calls
memini eval [--suite PATH] [--baseline PATH [--write-baseline]] [--fake-embeddings] ...
memini credentials set|list|delete|rotate-key ...   # credentials of sources, encrypted; secrets on stdin

workspace llm sits in the workspace group but is an operator command: no token, an admin one included, may opt a workspace in to a cloud LLM, so the HTTP API has no route for it.

bootstrap gives the principal MEMINI_PRINCIPAL (default owner) a token with the read and admin scopes for every workspace. It refuses while that principal has such a token that is active; with --force it makes another one, for an operator who lost theirs (revoke the old one with memini token revoke).

Exit codes: 0 done; 1 failed (no such thing, refused by the service, a failed run waited for); 2 wrong usage or configuration (no token, a bad URL); 3 the service or the database cannot be reached; 4 eval only: a metric fell below the baseline; 5 the service refused the token (unknown, revoked, expired, or without the scope or workspace); 130 interrupted. Errors are one line on stderr, with the API's error code and request id.

Settings

Every setting, its default and what a change needs (restart or reindex): docs/configuration.md, generated by make config-docs.

Settings come from MEMINI_* environment variables, or a TOML file named by MEMINI_CONFIG_FILE: MEMINI_DATABASE_URL (or MEMINI_DATABASE_URL_FILE, a file that holds it), MEMINI_HTTP_HOST, MEMINI_HTTP_PORT, MEMINI_LOG_LEVEL, MEMINI_PRINCIPAL; the embedding provider, MEMINI_EMBEDDING_* (off until MEMINI_EMBEDDING_PROVIDER is set); the git connector, MEMINI_GIT_* (mirror directory, limits, allowed transports, an https token or an ssh key); search, MEMINI_SEARCH_* (timeout, candidates, rank fusion constant). Secrets are read from the environment only, never from the TOML file. With compose, MEMINI_HTTP_PORT, MEMINI_DB_PORT, MEMINI_DB_PASSWORD and MEMINI_LOG_LEVEL in the shell or a .env file change the published ports, the database password and the log level.

Develop

Running from source, the tests and the project rules are in CONTRIBUTING.md.

Contributing

Issues and pull requests are welcome. Setup, checks and project rules: CONTRIBUTING.md. Report a vulnerability privately, as described in SECURITY.md.

License

Apache-2.0.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP-compatible clients to search and query a team knowledge graph, retrieve document context, upload files for indexing, explore entities and connections, and monitor workspace usage and server health.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-based hybrid semantic code search over repositories, providing tools for searching code by meaning or keyword, retrieving symbol definitions, finding usages, reading chunks, and listing indexed repos.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables coding agents to index and search multi-project codebases through semantic and full-text retrieval, symbol lookup, and reference search via a local MCP endpoint.
      MIT