Self-hosted semantic memory for AI agents, served over MCP. https://omnimem.org
3.0K
omnimem.org · Source · Docker guide · Docs · Releases · Issues · GitHub mirror
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.
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.
omnimem serve: the MCP server, the RSS scheduler and the background enrichment worker in a single process/data volumelinux/amd64 and linux/arm64, so a Raspberry Pi or a Graviton box is as welcome as your laptopdocker 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.
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
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.
Everything is set with environment variables. The ones most people touch:
| Variable | Default in the image | What it does |
|---|---|---|
MCP_AUTH_TOKEN | none, you must set it | Bearer token your clients send. Required unless OAuth is on |
ANTHROPIC_API_KEY | unset | Switches on the optional Claude Haiku extras: fact extraction, query expansion, deeper contradiction checks and RSS summaries |
OMNIMEM_DB | /data/omnimem.db | Where the SQLite database lives. feeds.yml and backups/ sit beside it |
HF_HOME | /data/hf-cache | Embedding model cache, kept on the volume so it downloads once |
MCP_HOST | 0.0.0.0 | Listen address inside the container |
OAUTH_ENABLED, OAUTH_BASE_URL, OAUTH_ADMIN_USER, OAUTH_ADMIN_PASSWORD | off | OAuth 2.1 with a login page, for claude.ai and other clients that sign in |
RSS_SCHEDULE_HOURS | 6 | How 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.
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 itdocker 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.
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.
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:
dump_to_file (or use the web UI's Backups page)docker cp backup.json omnimem:/data/backups/docker exec omnimem omnimem import /data/backups/backup.jsonEvery 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.
docker logs omnimem. The usual cause is no MCP_AUTH_TOKEN and no OAuth, which OmniMem refuses on purposeBearer has to match MCP_AUTH_TOKEN exactlyOAUTH_BASE_URL or MCP_PUBLIC_URL to the public address, or add names to MCP_ALLOWED_HOSTS| Website | omnimem.org |
| Source code | code.squarecows.com/ric/omnimem |
| GitHub mirror | github.com/richarvey/OmniMem |
| Issues | github.com/richarvey/OmniMem/issues |
| Releases and desktop installers | Releases |
| Changelog | CHANGELOG.md |
| Docker guide | guides/docker.md |
| Quick start | docs/quick-start.md |
| Configuration | docs/configuration.md |
| MCP tool reference | docs/mcp-tools.md |
| Hooks for Claude Code | docs/claude-code-hook.md |
| The skill compiler | docs/skill-compiler.md |
| RSS and knowledge | docs/rss-knowledge.md |
| Remote access and OAuth | docs/remote-access.md |
| Architecture | docs/architecture.md |
| Dockerfile | packaging/docker/Dockerfile |
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.
Content type
Image
Digest
sha256:e2336da76…
Size
58.3 MB
Last updated
9 days ago
docker pull richarvey/omnimem