Mnemos

Persistent memory for companies. Listens to WhatsApp, Slack, and meetings, compiles everything into a structured wiki, and answers questions when @-mentioned.

Mnemos is a small product designed to run forever on a single VPS. It captures every conversation flowing through your team's communication channels, processes the raw stream into a structured Markdown wiki using Claude Code, and exposes a private dashboard so you can browse what it remembers. When someone @-mentions Mnemos in WhatsApp or Slack, it answers with full historical context.

This document walks you through deploying Mnemos on a brand-new Ubuntu VPS, end to end.

What you get after install

After running mnemos onboard on a fresh VPS:

• A WhatsApp bot paired to your account that listens to allowlisted groups and DMs, captures every message + attachment, and responds when @-mentioned.
• A Slack connector (optional) that does the same for allowlisted channels.
• A Google Meet / TLDV connector (optional) that pulls meeting transcripts.
• A vault of Markdown files at ~/.mnemos/instances/default/vault/ — the source of truth for everything Mnemos remembers.
• A compile cron that runs every 6 hours (configurable), turning raw captures into wiki entries (people, organizations, decisions, contradictions, insights).
• A private web dashboard at 127.0.0.1:18789 — browse the wiki, trigger compiles, see the raw capture stream.
• Cross-reboot daemons so it all keeps running.

You access the dashboard from your laptop via an SSH tunnel — Mnemos never exposes a public port by default.

Requirements

A fresh Ubuntu 22.04 or 24.04 VPS with:

• A user account with sudo access (or a user where loginctl enable-linger works without sudo)
• Outbound HTTPS (for npm, GitHub, the Anthropic OAuth flow, WhatsApp servers)
• An interactive terminal (SSH session is fine) for the one-time setup

That's it. No domain, no DNS, no HTTPS certificates, no database, no Docker.

Install on a fresh VPS

1. Install Node 22

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt install -y nodejs git

Verify:

node --version   # should print v22.x.x or newer
npm --version

2. Install Claude Code and sign in

Mnemos uses your Claude account (Pro or Max subscription) — not an API key. Install the CLI globally and sign in once:

npm install -g @anthropic-ai/claude-code
claude

Inside Claude Code, type /login and follow the OAuth URL it prints. Once you see "Logged in as ..." you can exit with /exit or Ctrl+D.

3. Install Mnemos

npm install -g mnemos-cli

This installs the mnemos command globally. Confirm:

mnemos --version
mnemos --help

4. Run the onboard wizard

mnemos onboard

The wizard walks through nine steps, in order. None of them write irreversible state until they succeed.

Step 1 — Project

Project name?              Acme Inc
Organization?              Acme
One-line description?      Memory for the Acme team
Auto-compile interval?     6
Communication style?       direct
Default language?          auto

The communication style and language are written into the vault's CLAUDE.md so Mnemos answers in the tone you want.

Step 2 — Claude Code authentication

The wizard checks that claude is installed and that you're signed in. If you skipped step 2 earlier, it offers to install Claude Code, then to launch it interactively so you can run /login. After you exit Claude Code, the wizard verifies the credentials are present and continues.

Step 3 — Vault

Creates ~/.mnemos/instances/default/ with:

vault/                Markdown source of truth
  CLAUDE.md           system prompt (parameterised with your project name etc.)
  .claude/            agents, slash commands, hooks, settings.json
  00_raw/             raw captures from connectors (whatsapp/, slack/, meetings/)
  01_wiki/            structured entries (people/, organizations/, decisions/, ...)
  02_output/          generated artefacts (reports, presentations)
connectors/           bot processes (copied as you enable them)
dashboard/            bundled Next.js standalone web UI
scripts/              cron-compile.sh, health-monitor.sh
config/               mnemos.yaml + .env
credentials/          WhatsApp Baileys auth state
logs/                 per-service logs

Step 4 — WhatsApp

If you enable WhatsApp, the wizard runs npm install inside the connector directory, then offers to pair right now. When you accept, a QR code appears in your terminal — open WhatsApp on your phone, go to Settings → Linked devices → Link a device, and scan it. The wizard waits up to two minutes for the pairing to complete and writes a paired.flag file when it succeeds.

If you skip pairing now, run mnemos pair later.

Step 5 — Slack (optional)

You'll be asked for:

• A Slack bot token (xoxb-...)
• A Slack app token (xapp-...) for Socket Mode
• A comma-separated list of channel IDs to listen to

Create the Slack app at https://api.slack.com/apps with Socket Mode enabled and the standard message scopes (chat:write, app_mentions:read, channels:history, groups:history, im:history). The wizard saves both tokens to config/.env.

Step 6 — Google Meet / TLDV (optional)

Asks for your TLDV API key. Mnemos polls for new transcripts and writes one Markdown file per meeting to 00_raw/meetings/.

Step 7 — Web UI

Generates a 32-character random token, stores it in config/.env as MNEMOS_DASHBOARD_TOKEN, and asks where the dashboard should listen:

• Loopback (127.0.0.1) — recommended; you reach it via SSH tunnel.
• LAN (0.0.0.0) — accessible from the local network.
• Custom IP — bind to a specific interface.

Default port is 18789. The wizard copies the pre-built Next.js standalone dashboard into dashboard/ and writes its environment file pointing at the vault path.

If tailscale is detected and you're logged in, you can opt to expose the dashboard via Tailscale Serve. Otherwise the wizard skips this.

Step 8 — Daemon

The wizard installs platform-appropriate background services:

• Linux — systemd user services in ~/.config/systemd/user/. The wizard runs loginctl enable-linger so the services keep running after you log out.
• macOS — launchd LaunchAgents in ~/Library/LaunchAgents/.

Services installed (each suffixed with the instance name for isolation):

• mnemos-compile-default — runs the compile script every N hours.
• mnemos-whatsapp-default — long-running Baileys MCP server (only if WhatsApp enabled).
• mnemos-slack-default — long-running Slack connector (only if Slack enabled).
• mnemos-web-default — the dashboard server (only if web UI enabled).
• mnemos-claude-default — Claude Code host (installed but not auto-started in v1).

Step 9 — Finalise

Writes the final config/mnemos.yaml, drops a .mnemos-lock.json with the version + install date, and prints a summary:

✓ Mnemos installed

  Instance:      default
  Project:       Acme Inc
  Vault:         /home/youruser/.mnemos/instances/default/vault
  Compile:       every 6h

  Web UI:        http://127.0.0.1:18789?token=a1b2c3...
                 (bind=loopback, port=18789)

  WhatsApp:      paired ✓
  Slack:         enabled
  Meet:          disabled

Access from another machine (this VPS):
  ssh -L 18789:127.0.0.1:18789 [email protected]
  Then open: http://127.0.0.1:18789?token=a1b2c3...

Next steps:
  • mnemos status      ← check health
  • mnemos compile     ← trigger manual compile
  • mnemos logs        ← tail logs

5. Verify it works

From the VPS:

mnemos status

You should see all enabled services as ● active, the vault present, and zero issues.

From your laptop, open the SSH tunnel:

ssh -L 18789:127.0.0.1:18789 [email protected]

In your laptop browser, paste the full URL printed by the wizard (with ?token=...). The first request sets a cookie; subsequent visits to http://127.0.0.1:18789 work without the token in the URL.

Send a test WhatsApp message in an allowlisted group with @<bot-name> hello. You should see Mnemos respond within a few seconds. The message itself is captured to ~/.mnemos/instances/default/vault/00_raw/whatsapp/.

Run mnemos compile manually to verify the compile path works. After it completes, ~/.mnemos/instances/default/vault/01_wiki/INDEX.md should be populated.

Google Drive sync (Phase 1)

Mnemos can pull files out of Google Drive into the vault, where the next compile picks them up.

One-time OAuth client setup (operator only):

1. Go to https://console.cloud.google.com/apis/credentials.
2. Create credentials → OAuth client ID → Web application.
3. Authorised redirect URIs: add <your-dashboard-url>/api/drive/auth/callback for every dashboard you use, e.g.:
   • https://brain.acme.com/api/drive/auth/callback
   • http://127.0.0.1:18789/api/drive/auth/callback (for SSH-tunnel access)
4. Enable the Drive API: https://console.cloud.google.com/apis/library/drive.googleapis.com.
5. Copy the Client ID + Client Secret.

Wire it into a Mnemos instance:

mnemos connect drive

The wizard installs the connector, asks for the OAuth Client ID + Secret, writes them to config/.env, restarts the web service.

Connect a Drive account:

1. Open the dashboard → Connectors → Google Drive.
2. Click Connect Drive → sign in to Google → grant drive.readonly.
3. Pick folders in the tree picker (recursive).
4. Click Import → files land in 00_raw/drive/<folder-path>/<filename> with frontmatter sidecars.
5. Next compile picks them up like any other capture.

Native Google formats are exported automatically: Docs → .md, Sheets → .csv, Slides → .pdf, Drawings → .png. Everything else is downloaded as-is.

The OAuth flow uses drive.readonly only — Mnemos cannot write to or delete from your Drive.

Daily commands

| Command | What it does | |---------|--------------| | mnemos status | Health of every service, last compile time, vault stats. | | mnemos status --json | Same, machine-readable. | | mnemos compile | Trigger a manual compile. Blocks until done. | | mnemos logs | Tail all logs with colour-coded prefixes. | | mnemos logs whatsapp -f | Follow only the WhatsApp connector log. | | mnemos pair | Re-pair WhatsApp (after expiry, device change, etc.). | | mnemos dashboard | Open the dashboard locally, or print the SSH tunnel command if you're in an SSH session. | | mnemos dashboard --url-only | Print the dashboard URL with the token (for scripts). | | mnemos dashboard --restart | Restart the dashboard service. | | mnemos connect slack | Add a Slack connector after onboarding. | | mnemos connect meet | Add the meetings connector after onboarding. | | mnemos agent list | Show installed Claude Code subagents (compiler, weaver, healthcheck, ...). | | mnemos agent add | Add a custom subagent interactively. | | mnemos doctor | Diagnose every component. Prints fixes for each issue. | | mnemos doctor --fix | Try to auto-remediate (restart failed daemons, etc.). | | mnemos update | Update Mnemos to the latest published version. | | mnemos web upgrade | After mnemos update, refresh the bundled dashboard files into the instance and restart the web service. | | mnemos web expose --domain X | Install Caddy + auto-HTTPS reverse proxy at https://X (requires DNS pointing here + ports 80/443 open). | | mnemos web unexpose | Remove the Caddy config; web reverts to loopback-only. | | mnemos web status | Show current bind, port, token, and public URL state. | | mnemos token --show / --rotate | Print or regenerate the dashboard auth token. | | mnemos --instance acme <cmd> | Target a non-default instance. |

Add --help to any command for full options.

6. (Optional) Expose the dashboard publicly

By default the dashboard is loopback-only and you reach it via SSH tunnel. If you'd rather have a permanent public HTTPS URL like https://mnemos.acme.com:

1. Point a subdomain at this VPS. In your DNS provider, create an A (or AAAA) record:

   mnemos.acme.com → <VPS public IP>

   Wait 1-5 minutes for propagation:

   dig +short mnemos.acme.com
   curl -s ifconfig.me      # should match

2. Open ports 80 and 443 on the VPS firewall:

   sudo ufw allow 80,443/tcp

   Make sure no other web server (nginx, apache) is using them.

3. Run expose:

   mnemos web expose --domain mnemos.acme.com

   The CLI will:

   • Install Caddy if missing (via official Cloudsmith apt repo, sudo required).
   • Write a reverse-proxy config at /etc/caddy/conf.d/mnemos-default.conf.
   • Reload Caddy — it auto-fetches a Let's Encrypt cert (~30-60s on first issue).
   • Print the public URL with token.

4. Open https://mnemos.acme.com/?token=... from anywhere. Token sets a 7-day cookie. To revert at any time: mnemos web unexpose.

How the dashboard works

The dashboard is a small Next.js app bundled inside the npm package and copied into ~/.mnemos/instances/<name>/dashboard/ at install time. It runs as a daemon-managed Node process bound to loopback by default.

It does not have a database. It reads the vault Markdown files at request time and renders them. Pages:

• Overview — vault stats, recent wiki entries, recent raw captures, Compile / Healthcheck / Weave action buttons.
• Wiki — all entries grouped by type (concepts, people, organizations, decisions, insights, contradictions). Search and sort.
• Wiki entry — full Markdown render with frontmatter, backlinks.
• Raw — every file in 00_raw/, grouped by source.
• Contradictions — shortcut to open contradictions only.
• Compiles — compile history (parses logs/compile.log).
• Connectors — status of each connector (enabled/disabled, paired/unpaired).

Auth is a single token. Append ?token=<token> to any URL to skip the login screen; it sets a 7-day cookie. There is no multi-user, no roles. This is a single-operator dashboard.

Multiple instances on one VPS

Run a second instance for a different client:

mnemos onboard --instance acme

Everything is namespaced:

• Files live in ~/.mnemos/instances/acme/.
• Daemon services are named mnemos-compile-acme, mnemos-whatsapp-acme, etc.
• The dashboard binds to a different port — change it with --web-port 18790.

All commands accept -i acme or --instance acme.

Updating

mnemos update

This runs npm install -g mnemos-cli@latest, prints the version delta, then runs mnemos doctor. Existing instances and their data are preserved; only the binary and packaged assets change. To pull updated vault templates into an existing instance, you'd need to merge them manually — vault state is not auto-migrated.

Recovering from common issues

Pairing didn't complete in 2 minutes. Run mnemos pair. The QR has a short TTL.

mnemos status shows a service as failed. mnemos logs <service> to see why. mnemos doctor --fix will attempt a restart. If the failure is in the connector code, mnemos logs <service> -f and re-trigger.

You logged out of the VPS and services stopped (Linux only). You skipped lingering. Run sudo loginctl enable-linger $USER, then mnemos onboard --install-daemon to re-enable them.

Compile cron isn't running. systemctl --user list-timers | grep mnemos to confirm the timer is active. On macOS, launchctl list | grep mnemos.

Token leaked / want to rotate it. Edit ~/.mnemos/instances/default/config/.env, change MNEMOS_DASHBOARD_TOKEN, edit ~/.mnemos/instances/default/dashboard/.env to match, then mnemos dashboard --restart.

Want to start completely fresh. mnemos onboard --reset. This asks for double confirmation, then deletes ~/.mnemos/instances/default/ and walks you through onboarding again.

Architecture (one paragraph)

Connectors are independent Node processes that listen to their respective platforms (WhatsApp via Baileys, Slack via Bolt + Socket Mode, meetings via TLDV polling) and write raw captures as Markdown files into 00_raw/<source>/. A systemd timer (or launchd StartInterval on macOS) fires cron-compile.sh every N hours, which spawns Claude Code in the vault directory with claude -p "/compile". Claude reads the unprocessed raw files, updates the structured wiki under 01_wiki/, and commits to the local git repository. The dashboard reads the same Markdown files and renders them on demand. The vault filesystem is the only source of truth; there is no database. When a user @-mentions Mnemos on WhatsApp or Slack, the connector forwards the message to Claude Code via MCP, Claude reads the relevant wiki entries, and the connector posts the reply back. Everything is per-user (no root privileges), per-instance (multiple installs coexist), and self-contained inside ~/.mnemos/.

Configuration files

~/.mnemos/instances/<name>/config/mnemos.yaml — project name, compile interval, communication style, connector flags, web UI bind/port.

~/.mnemos/instances/<name>/config/.env — connector secrets (Slack tokens, TLDV key) and the dashboard token. Loaded by every daemon service via EnvironmentFile=. Edit and mnemos doctor --fix to apply.

~/.mnemos/instances/<name>/config/groups.yaml — WhatsApp group allowlist. Edit then restart the WhatsApp service.

~/.mnemos/instances/<name>/config/channels.yaml — Slack channel allowlist.

~/.mnemos/instances/<name>/vault/CLAUDE.md — the system prompt Claude Code uses. Edit to change Mnemos's behaviour, tone, or memory rules.

Uninstall

mnemos --instance default doctor       # see what's running
# Stop and remove daemons (Linux):
systemctl --user stop 'mnemos-*-default.service' 'mnemos-*-default.timer'
systemctl --user disable 'mnemos-*-default.service' 'mnemos-*-default.timer'
rm ~/.config/systemd/user/mnemos-*-default.*
systemctl --user daemon-reload

# macOS:
launchctl unload ~/Library/LaunchAgents/ai.mnemos.*.default.plist
rm ~/Library/LaunchAgents/ai.mnemos.*.default.plist

# Remove vault + connectors + credentials (this deletes everything Mnemos remembers):
rm -rf ~/.mnemos/instances/default

# Uninstall the CLI itself:
npm uninstall -g mnemos-cli

Requirements summary

• Node.js >= 22.14 (recommended: Node 24)
• macOS or Linux (WSL2 supported when systemd is present; Windows native is not supported for daemons)
• Claude Code (@anthropic-ai/claude-code), with an active Claude.ai sign-in
• For WhatsApp: an Android or iOS phone with the WhatsApp app to scan the pairing QR
• For Slack: a Slack workspace where you can create an app with Socket Mode enabled
• For meetings: a TLDV account with API access