Mnema

The context engine for AI work. Mnema is a collaborative knowledge workspace that publishes your team's docs, decisions, and workflows to any MCP-aware AI client (Claude, ChatGPT, Cursor, and more) — so your agents answer from your context, not their training data.

This is the open-core repository (fair-code, Mnema Community License). It contains the full core product; the enterprise modules are available separately.

What's in the core (this repo)

• Docs & editor — a real-time collaborative Markdown editor (Yjs), folders, versions, comments.
• Search — hybrid keyword + semantic retrieval (Postgres FTS + pgvector).
• Flows — build and walk step-by-step workflows via the MCP server.
• MCP server — read + propose/commit writes over the Model Context Protocol; works with Claude, ChatGPT, Cursor, Windsurf, Cline, and the OpenAI API.
• Auth — built-in email + password, or bring your own identity provider via generic OIDC.
• Self-hostable — Postgres + Redis + Node; single-workspace, unlimited docs.

What's in the enterprise edition (not in this repo)

The knowledge graph engine, meeting intelligence (bot, transcription, summaries), org/IAM + SSO, audit logs, and multi-workspace/multi-tenant mode are commercial add-ons. The core runs perfectly without them. See the website for details.

Quick start (self-host)

Requirements: Docker + Docker Compose.

git clone https://github.com/nbkdoesntknowcoding/mnema.git
cd mnema
cp .env.example .env
# edit .env — at minimum set AUTH_PROVIDER=password and generate the secrets
# (each: openssl rand -hex 32). See the comments in .env.example.

docker compose -f infra/docker-compose.prod.yml --env-file .env up -d --build
# apply the schema:
docker compose -f infra/docker-compose.prod.yml --env-file .env exec -T postgres \
  sh -c 'for f in /app/apps/api/drizzle/migrations/*.sql; do psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -f "$f"; done'

Then open the web app and sign up at /auth/local (email + password).

For embeddings/autocomplete set VOYAGE_API_KEY and GEMINI_API_KEY (bring your own).

Behind a reverse proxy (HTTPS)

The realtime editor connects to the collab server (Yjs/Hocuspocus, port 1234) over a WebSocket. On an HTTPS deployment you must expose it as wss:// through your proxy with WebSocket upgrade, and point the web app at it:

• Route wss://<your-host>/collab → the collab port 1234 (enable the WebSocket upgrade).
• Set PUBLIC_COLLAB_URL=wss://<your-host>/collab in .env, 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 (or unreachable behind Docker) — and every document shows "disconnected."

Run it with an AI agent (fastest)

Clone the repo, open it in Claude Code (or any coding agent) and paste this prompt — it sets everything up and runs Mnema locally, fixing issues as it goes:

Set up and run Mnema (this repo) locally for self-hosting. Work through it and fix any error you hit:

1. Confirm Docker is running. This is a pnpm monorepo (apps/api, apps/web, packages/*), Node 22.
2. Generate 5 secrets with openssl rand -hex 32 (four for WORKOS_COOKIE_PASSWORD, COLLAB_INTERNAL_SECRET, SECRETBOX_MASTER_KEY, API_INTERNAL_SECRET; one for JWT_SECRET).
3. Generate the MCP OAuth RSA keypair into ./keys: openssl genpkey -algorithm RSA -out keys/private.pem -pkeyopt rsa_keygen_bits:2048 && openssl rsa -in keys/private.pem -pubout -out keys/public.pem.
4. Create .env from .env.example: AUTH_PROVIDER=password, local DATABASE_URL/REDIS_URL, the secrets from step 2, OAUTH_*_KEY_PATH=./keys/*.pem, and keep the "unused on self-host" WorkOS/Razorpay dummy values.
5. Start Postgres (pgvector/pgvector:pg16) and Redis (redis:7) via Docker.
6. pnpm install, then pnpm -r --filter "./packages/**" build.
7. Apply the schema: run every apps/api/drizzle/migrations/*.sql in order against the DB (psql -f).
8. Start the backend pnpm --filter @boppl/api dev (api + collab + workers) and the web pnpm --filter @boppl/web dev.
9. Open the web URL, go to /auth/local, create an account, and confirm you reach the app.
10. Report the local URLs and anything you fixed. If a service crashes on a missing env var, add a sane local default and continue.

Stack

pnpm monorepo — API (Fastify + Drizzle/Postgres), collab (Hocuspocus/Yjs), web (Astro + React), shared TS packages. Node 22.

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.

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