HUB
Sign inSign up
omnimem logo

richarvey/omnimem

By richarvey

•Updated 9 days ago

Self-hosted semantic memory for AI agents, served over MCP. https://omnimem.org

Image
Machine learning & AI
Developer tools
0

3.0K

richarvey/omnimem repository overview

OmniMem

omnimem.org⁠ · Source⁠ · Docker guide⁠ · Docs⁠ · Releases⁠ · Issues⁠ · GitHub mirror⁠

⁠OmniMem

Stop living the same session twice.

Every coding agent session starts from zero. It doesn't know your project, it doesn't remember what failed last week, and it will confidently suggest the exact thing that didn't work last time.

OmniMem gives your AI agent a memory that lasts across sessions, projects and machines. It's served over MCP, so it works with whichever agent you like. It runs on your own kit and it's free.

claude> answer the settings form with a 303 redirect

⚠ WARNING: previously abandoned approach

  303 from omnimem://: WebKitGTK never follows it (effort: 4/5)
  → answer with a page that replaces itself instead

That warning came from memory, not luck. A mistake you've already paid for doesn't get to charge you twice.

⁠What's in the image

OmniMem 7 is one binary, so this is one container. No Valkey, no web UI container, no RSS worker, no Compose file with four services. One image, one volume, one port.

  • Runs omnimem serve: the MCP server, the RSS scheduler and the background enrichment worker in a single process
  • Your memories live in one SQLite file on the /data volume
  • Embeddings run locally (all-MiniLM-L6-v2 on ONNX Runtime), no GPU and no API calls
  • Built for linux/amd64 and linux/arm64, so a Raspberry Pi or a Graviton box is as welcome as your laptop
  • Debian 13 slim underneath, running as uid 1000, with a built-in health check
  • It's the headless build. If you'd like the tray app with its settings window, the desktop installers are on the releases page⁠

⁠Quick start

docker run -d --name omnimem \
  --restart unless-stopped \
  -p 127.0.0.1:8765:8765 \
  -v omnimem-data:/data \
  -e MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  richarvey/omnimem:latest

The token isn't optional. Inside a container OmniMem has to listen beyond localhost, and it refuses to do that without authentication. Leave it out and the container exits with an error telling you so.

Grab the token for your clients, then check it's up:

docker exec omnimem printenv MCP_AUTH_TOKEN
curl http://127.0.0.1:8765/healthz

That should answer {"status": "ok"}. The first start downloads the embedding model (cached on the volume afterwards), so give it a minute before docker ps shows the container as healthy.

⁠With Compose

services:
  omnimem:
    image: richarvey/omnimem:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:8765:8765"
    volumes:
      - omnimem-data:/data
    env_file:
      - omnimem.env

volumes:
  omnimem-data:

And omnimem.env beside it:

MCP_AUTH_TOKEN=paste-a-long-random-token-here
# ANTHROPIC_API_KEY=sk-ant-...   # optional, see below

⁠Connect your agent

Point your client at http://127.0.0.1:8765/mcp and send the token as a bearer header. For Claude Code:

claude mcp add --transport http omnimem http://127.0.0.1:8765/mcp \
  --header "Authorization: Bearer your-token-here" \
  --scope user

The server hands its own usage guide to every agent that connects, so there's no instructions file to copy around. There are connection guides⁠ for claude.ai, Claude Desktop, Cursor, GitHub Copilot, GitLab Duo, Kiro, OpenCode, Codex CLI, Lumo, Mistral and Open Design.

⁠Configuration

Everything is set with environment variables. The ones most people touch:

VariableDefault in the imageWhat it does
MCP_AUTH_TOKENnone, you must set itBearer token your clients send. Required unless OAuth is on
ANTHROPIC_API_KEYunsetSwitches on the optional Claude Haiku extras: fact extraction, query expansion, deeper contradiction checks and RSS summaries
OMNIMEM_DB/data/omnimem.dbWhere the SQLite database lives. feeds.yml and backups/ sit beside it
HF_HOME/data/hf-cacheEmbedding model cache, kept on the volume so it downloads once
MCP_HOST0.0.0.0Listen address inside the container
OAUTH_ENABLED, OAUTH_BASE_URL, OAUTH_ADMIN_USER, OAUTH_ADMIN_PASSWORDoffOAuth 2.1 with a login page, for claude.ai and other clients that sign in
RSS_SCHEDULE_HOURS6How often the feeds in /data/feeds.yml are fetched

Without ANTHROPIC_API_KEY everything still works, and nothing leaves the machine. The configuration reference⁠ has every other setting.

Volume: /data is the only one. A named volume sorts out ownership itself. If you bind mount a folder instead, chown 1000:1000 it first.

Port: 8765. It serves /mcp, the OAuth routes and /healthz, and that's the whole list, so a reverse proxy just forwards everything to it. See multiple machines⁠ for proxies, tunnels and claude.ai.

⁠Tags

  • latest is the newest release. It never moves for a development build
  • <version> (for example 7.0.12) is a fixed release, multi-arch. Pin one of these when you want upgrades to be your decision
  • <version>-amd64 and <version>-arm64 are the single-architecture builds behind it

⁠Updating and backups

docker compose pull && docker compose up -d

The database migrates itself on start. Take a backup first anyway, and don't copy the SQLite file while OmniMem is writing to it:

docker exec omnimem omnimem export /data/backups/omnimem-$(date +%Y%m%d).json

Or ask your agent to call dump_to_file. Restore with omnimem import or the restore_from_file tool.

⁠What it remembers

  • Episodic: the decisions you made, the bugs you fixed, the patterns you found
  • Project context: your stack, goals and current state, so the agent turns up briefed
  • Knowledge: articles from the RSS feeds you pick, fetched on a schedule and embedded
  • Preferences: rules about how you like to work, picked up from your conversations
  • Skills: SKILL.md documents compiled from your experience in a domain, and nothing changes without your say-so

Plus a graveyard for dead ends, experience scoring so hard-won lessons surface first, contradiction detection, semantic deduplication and a one-call session briefing. Features in depth⁠ covers the lot.

⁠Coming from the 6.x containers?

6.x ran four containers with Valkey underneath, using the richarvey/omnimem-mcp, richarvey/omnimem-web and richarvey/omnimem-rss images. Those carry on in the v6.7.x branch⁠. To move to 7:

  1. On 6.x, call dump_to_file (or use the web UI's Backups page)
  2. Copy the JSON onto the new volume: docker cp backup.json omnimem:/data/backups/
  3. Import it: docker exec omnimem omnimem import /data/backups/backup.json

Every memory is re-embedded on import at roughly 8 ms each, so a few thousand take under a minute. Clients that used /sse need to switch to /mcp, and the old VALKEY_*, WEB_* and MCP_TRANSPORT settings are gone.

⁠Troubleshooting

  • The container exits straight away: run docker logs omnimem. The usual cause is no MCP_AUTH_TOKEN and no OAuth, which OmniMem refuses on purpose
  • The first start is slow: it's downloading the embedding model. Later starts read it from the volume
  • Clients get 401: the token after Bearer has to match MCP_AUTH_TOKEN exactly
  • Clients get 421: the Host header isn't trusted, and connecting by the machine's IP counts too. Set OAUTH_BASE_URL or MCP_PUBLIC_URL to the public address, or add names to MCP_ALLOWED_HOSTS

⁠Licence

MIT. Free to use, fork and modify. No enterprise tier, no hosted version, no strings.

Built by Ric Harvey @ SquareCows Ltd⁠, an AI and automation consultancy for people who'd rather own their tools.

Tag summary

Content type

Image

Digest

sha256:e2336da76…

Size

58.3 MB

Last updated

9 days ago

docker pull richarvey/omnimem