Mnema

Your AI assistant answers from its training data, not your team's. Mnema is a
self-hostable knowledge workspace that publishes your docs, decisions, and
step-by-step workflows to any MCP-aware AI client (Claude, ChatGPT, Cursor,
Windsurf, Cline) over the Model Context Protocol — so your agents read your
context, live, with no uploads or copy-paste.

This is the open-core repository (fair-code, Mnema Community License).
It is the full core product and runs on its own; the enterprise modules are separate.

Quickstart (self-host, ~90 seconds)

Requirements: Docker + Docker Compose. (Working on the code itself, outside
Docker? Node 22 — nvm use picks it up from .nvmrc — and
pnpm 10; see CONTRIBUTING.md.)

git clone https://github.com/nbkdoesntknowcoding/mnema.git
cd mnema
./scripts/self-host-init.sh          # generates secrets + the OAuth keypair, writes .env
docker compose up -d --build         # postgres, redis, api, collab, workers, web

Then:

• Open http://localhost:4321 and create an account at /auth/local (email + password).
• Connect an MCP client to your server: http://localhost:8080/mcp
  (in Claude/Cursor, add it as a custom MCP/connector URL; you'll be sent back here to log in and approve).

That's it — the first workspace comes with a welcome doc and an example flow, so your
first connection has something real to read.

Optional: set VOYAGE_API_KEY (semantic search) and GEMINI_API_KEY (autocomplete)
in .env — bring your own keys. Both stay disabled until set.

Documentation

• Connect an AI client — Claude, ChatGPT, Cursor, Windsurf, Antigravity
• Embed Mnema in your own app — REST API + an API key
• REST API reference — every public endpoint, auth, scopes, examples

What's in the core (this repo) vs. licensed

The free layer carries the full product; the gates sit on what organizations and
R&D need. Plainly:

The knowledge graph, meeting intelligence, org/IAM+SSO, audit, and multi-workspace
mode are commercial add-ons — the core runs perfectly without them, and its CI
proves it builds and boots with the enterprise modules entirely absent. Licensing:
LICENSE for the core; enterprise inquiries via the website.

Docs, flows, collaboration, and live MCP are free forever, registered or not.
Version history and export are also free — we just ask for your email (a free
community license, entered in Settings). Your history is recorded from day
one; registering reveals it.

Self-host notes

• Pin to a release tag. For a stable deployment, check out a tagged release
  rather than tracking main: git fetch --tags && git checkout vX.Y.Z, then
  docker compose up -d --build. Release tags are immutable and signed; upgrade
  by checking out a newer tag and rebuilding. See RELEASING.md
  and CHANGELOG.md.
• HTTPS / reverse proxy. Behind TLS, expose the collab WebSocket as
  wss://<your-host>/collab (WebSocket upgrade enabled) and set
  PUBLIC_COLLAB_URL=wss://<your-host>/collab, then rebuild the web app
  (PUBLIC_* vars are baked in at build time). Otherwise the browser falls back to
  ws://localhost:1234, which is blocked as mixed content on an HTTPS page — and
  every document shows "disconnected." Re-run ./scripts/self-host-init.sh --url https://<your-host>
  to regenerate .env for a public host.
• Backups. Everything lives in Postgres + the named volumes. Back up with
  docker compose exec postgres pg_dump -U mnema mnema > backup.sql and snapshot the
  pgdata / redis_data volumes.
• Requirements. Comes up on a 4 GB machine. Migrations apply automatically on
  first up (idempotent).

Troubleshooting (self-host)

• docker compose up exits immediately with "set POSTGRES_PASSWORD in .env" (or
  REDIS_PASSWORD). There's no .env yet — the compose refuses to boot with
  empty credentials. Run ./scripts/self-host-init.sh first (it writes .env
  with generated secrets); add --force to regenerate one that already exists.
• "port is already allocated" on startup. The stack publishes three ports on
  127.0.0.1: 4321 (web), 8080 (api), 1234 (collab). Stop whatever holds the
  port, or change the host side of that service's ports: entry in
  docker-compose.yml.
• Every document shows "disconnected" (HTTPS deploys). The browser is trying
  ws://localhost:1234 — blocked as mixed content on an HTTPS page. Set
  PUBLIC_COLLAB_URL=wss://<your-host>/collab, proxy that path with WebSocket
  upgrade enabled, and rebuild the web image — see the HTTPS note above.
  ./scripts/self-host-init.sh --url https://<your-host> --force regenerates
  .env with the whole URL block derived for you.
• Changed a PUBLIC_* var in .env but the app ignores it. PUBLIC_* values
  are baked into the web image at build time, not read at runtime. Rebuild it:
  docker compose up -d --build web.
• First boot looks stuck. Startup is gated: postgres healthy → migrate
  completes → api healthy → web starts. Watch docker compose ps and
  docker compose logs -f migrate api. (non-fatal on re-run) lines from
  migrate are normal — the migrations are idempotent and re-runs are safe.
• The login page shows SSO buttons, or sign-up is nowhere to be found.
  Self-host sign-in lives at /auth/local (email + password). Keep both
  AUTH_PROVIDER=password and PUBLIC_AUTH_PROVIDER=password in .env — the
  PUBLIC_ one is baked at build time, so rebuild the web image after changing it.

Run it with an AI agent (alternative)

Open the repo in Claude Code (or any coding agent) and paste:

Set up and run Mnema (this repo) for self-hosting. Confirm Docker is running,
then run ./scripts/self-host-init.sh --defaults and docker compose up -d --build.
Wait for all services healthy, open the web URL, create an account at /auth/local,
and report the URLs. Fix any error you hit and continue.

Stack

pnpm monorepo — api (Fastify + Drizzle/Postgres), collab (Hocuspocus/Yjs),
workers (BullMQ/Redis), web (Astro + React). Node 22, Postgres 16 + pgvector, Redis 7.

License

The core is licensed under the Mnema Community License (a Sustainable-Use
fair-code license): free to use, modify, and self-host for your own internal or
personal use; commercial hosting/reselling requires an agreement. See LICENSE,
CONTRIBUTING.md, and TRADEMARK.md.

"Mnema" is a trademark of the maintainer — forks may use the code, not the name.