Skip to content
Back to search

OmniMem

Self-hosted semantic memory for AI Agents. Persistent sessions, experience scoring, and a graveyard for dead ends, backed by knowledge acquired from the RSS you read and stored in a Valkey vector search then exposed as an MCP server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/richarvey/OmniMem with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/richarvey/OmniMem'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/richarvey--omnimem/badge.svg)](/listings/richarvey--omnimem)

HTML

<a href="/listings/richarvey--omnimem"><img src="/api/listings/richarvey--omnimem/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

The installer checks Docker is installed, generates secure passwords, writes a sensible `.env`, and starts everything from the pre-built Docker Hub images:

curl -fsSL https://code.squarecows.com/ric/omnimem/raw/branch/main/install.sh | bash

Or build from source:

git clone https://code.squarecows.com/ric/omnimem.git && cd omnimem
cp .env.example .env
# Set VALKEY_PASSWORD and ANTHROPIC_API_KEY in .env
docker compose up -d

Then point your agent at it — **Claude Code** (`~/.claude.json`):

{
  "mcpServers": {
    "omnimem": {
      "type": "sse",
      "url": "http://localhost:8765/sse"
    }
  }
}

The server delivers its usage guide to any connecting agent automatically via the MCP `instructions` field — no configuration file needed. The web dashboard is at `http://localhost:8080`.

The full walkthrough, including auth tokens, permission settings, and the other agents, is in [docs/quick-start.md](docs/quick-start.md).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 198 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # \<OmniMem\><br><sub><sub>[omnimem.org](https://omnimem.org)</sub></sub>
  2. [![Security Scans](https://codeberg.org/ric_harvey/omnimem/badges/workflows/security.yml/badge.svg)](https://codeberg.org/ric_harvey/omnimem/actions)
  3. [![Docker Build](https://codeberg.org/ric_harvey/omnimem/badges/workflows/docker.yml/badge.svg)](https://codeberg.org/ric_harvey/omnimem/actions)
  4. [![Coverage](https://codeberg.org/ric_harvey/omnimem/raw/branch/badges/coverage-badge.svg)](https://codeberg.org/ric_harvey/omnimem/actions)
  5. <sub>Development happens on [Codeberg](https://codeberg.org/ric_harvey/omnimem) — issues and PRs there please.</sub>
  6. **Stop living the same session twice.**
  7. Every Claude Code session starts from zero. No memory of your project. No memory of what failed last week. No memory that you spent three hours last Tuesday discovering why `onnxruntime` explodes on Alpine before finding something that actually works.
  8. So you explain the project again. Claude suggests the same broken library again. Same alarm. Same song. You are Bill Murray and Claude is Punxsutawney.
  9. OmniMem fixes that. It is a self-hosted MCP server that gives your AI agent persistent memory across sessions, projects, and machines. It runs on your own hardware and it is free forever.
  10. ```
  11. claude> use onnxruntime for the embeddings
  12. ⚠ WARNING: previously abandoned approach
  13. onnxruntime — SIGILL crash on Alpine musl libc (effort: 4/5)
  14. → switched to sentence-transformers instead
  15. ```
  16. That warning came from memory, not luck. The mistake you already paid for does not get to charge you twice.
  17. ---
  18. ## Get going quickly
  19. > [!TIP]
  20. > One command gets the full stack running from the pre-built Docker Hub images:
  21. >
  22. > ```bash
  23. > curl -fsSL https://codeberg.org/ric_harvey/omnimem/raw/branch/main/install.sh | bash
  24. > ```
  25. >
  26. > Then point your agent at it — the [quick start](docs/quick-start.md) walks through the rest, or jump to the fuller [quick start section](#quick-start) below.
  27. ---
  28. ## What it remembers
  29. Five kinds of memory, all searched together at recall time:
  30. - **Episodic** — the decisions you made, the bugs you fixed, the patterns you discovered. The things that took real effort to learn and should not have to be re-learned every morning.
  31. - **Project context** — your stack, goals, and current state. The agent arrives at every session already briefed rather than starting cold.
  32. - **Knowledge** — RSS feeds you configure, fetched on a schedule, summarised by Claude Haiku, embedded, and stored. When a relevant article landed last week, it surfaces as a starting point worth reading.
  33. - **Preferences** — prescriptive rules about how you want to work ("always update the README after a feature lands"), extracted from your conversations automatically and surfaced whenever they apply.
  34. - **Skills** — SKILL.md documents compiled from your accumulated experience in a domain, so the agent works your way from the first prompt. Derived from the other namespaces, never hand-edited, and every change goes through your review. See [the skill compiler](docs/skill-compiler.md).
  35. The top recall result might be a decision from six months ago on a different project, a solution from yesterday, or an article that landed on Tuesday night. It does not matter where it came from as long as it is useful.
  36. ---
  37. ## What makes it different
  38. Not just a key-value store with an MCP wrapper. OmniMem models how memory actually works: things fade over time, they sometimes contradict each other, and the hard-won stuff earns its place.
  39. - **[The Graveyard](docs/features.md#the-graveyard)** — every dead end gets logged with what you tried, why it failed, and how much time you burned. The agent checks it before suggesting a library or pattern.
  40. - **[Experience scoring](docs/features.md#experience-scoring)** — something that took four attempts and a weird platform workaround to crack is gold. The harder it was, the more readily it surfaces next time.
  41. - **[Memory lifecycle](docs/features.md#memory-is-not-binary)** — `ACTIVE → DEPRIORITISED → ARCHIVED → DELETED`. "Forget about X" usually means stop bringing it up, not wipe it from existence. Deprioritised memories can earn their way back.
  42. - **[Contradiction detection](docs/features.md#contradiction-detection)** — if a new memory disagrees with something stored, OmniMem catches it. Fast heuristic on every write, optional deeper analysis via Claude Haiku.
  43. - **[Semantic deduplication](docs/features.md#semantic-deduplication)** — near-identical memories get flagged at write time and cleaned up in bulk with `find_duplicates()`.
  44. - **[One-call briefing](docs/features.md#session-briefing)** — a single `briefing()` returns project context, experience stats, stale memories, new articles, contradiction warnings, and skill suggestions. No three-step warm-up.
  45. - **[The skill compiler](docs/skill-compiler.md)** — distils reinforced lessons and dead ends into loadable skills, behind a propose-and-accept gate so bad lessons cannot become policy silently.
  46. - **[Auto-maintenance](docs/features.md#automatic-maintenance)** — duplicates archived, contradictions flagged, expired knowledge cleaned up, all in the background.
  47. - **[Web UI](docs/web-ui.md)** — browse, search, and manage everything from an htmx dashboard, with telemetry and a Prometheus `/metrics` endpoint.
  48. The ranking formula behind every recall:
  49. ```
  50. score = similarity x surface_score x recency x experience_weight
  51. ```
  52. Four factors decide what comes back. Semantic similarity alone is not enough — lifecycle state, age, and how hard the lesson was to learn all play a role.
  53. ---
  54. ## Works with any MCP agent
  55. One memory layer for all of them: [claude.ai](guides/claude-ai.md), [Claude Code](guides/claude-code.md), [Claude Desktop](guides/claude-desktop.md), [Cursor](guides/cursor.md), [GitHub Copilot](guides/github-copilot.md), [GitLab Duo](guides/gitlab-duo.md), [AWS Kiro](guides/kiro.md), [OpenCode](guides/opencode.md), [OpenAI Codex CLI](guides/codex.md), and [Open Design](guides/open-design.md).
  56. ---
  57. ## Architecture
  58. Four containers. Nothing leaves your machine. Local embeddings via sentence-transformers, storage in Valkey with vector search, and both front doors share the same memory engine.
  59. ```mermaid
  60. flowchart TB
  61. agent["AI agent<br/>Claude Code · claude.ai · Cursor · Copilot · ..."]
  62. browser["Browser"]
  63. agent -- "MCP · Streamable HTTP / SSE · :8765" --> mcp
  64. browser -- "HTTP · :8080" --> webui
  65. subgraph stack["Docker Compose stack"]
  66. mcp["MCP server<br/>Python · FastMCP<br/><i>remember · recall · briefing<br/>compile_skill · record_experience</i>"]
  67. webui["Web UI<br/>Starlette · htmx · Jinja2<br/><i>dashboard · search · skills<br/>projects · backups · /metrics</i>"]
  68. rss["RSS worker<br/>feedparser · APScheduler<br/>Claude Haiku summaries"]
  69. valkey[("Valkey + valkey-search<br/>HNSW vector indexes<br/><i>idx:episodic · idx:project · idx:knowledge<br/>idx:preference · idx:skill</i>")]
  70. mcp <--> valkey
  71. webui <--> valkey
  72. rss --> valkey
  73. end
  74. ```
  75. The full picture — the recall pipeline, storage model, and design decisions — is in [docs/architecture.md](docs/architecture.md).
  76. ---
  77. ## Self-hosted, open source, yours
  78. No SaaS. No vendor lock-in. No context shipped to someone else's servers.
  79. - **Valkey** is an open source Redis fork. All your data stays in a named Docker volume on your own machine.
  80. - **Multi-arch Docker images** for amd64 and arm64. It runs on a Raspberry Pi, AWS Graviton, or Apple Silicon just as well as x86.
  81. - **sentence-transformers** runs embeddings locally with no API calls.
  82. - **MIT licensed** means fork it, extend it, run it wherever you want.
  83. - **One backup command** calls `dump_to_file()` and exports everything to a JSON file you own.
  84. Expose the MCP port through your reverse proxy and every machine you work from shares the same memory. One deployment, everywhere — see [docs/remote-access.md](docs/remote-access.md).
  85. ---
  86. ## Quick start
  87. The installer checks Docker is installed, generates secure passwords, writes a sensible `.env`, and starts everything from the pre-built Docker Hub images:
  88. ```bash
  89. curl -fsSL https://codeberg.org/ric_harvey/omnimem/raw/branch/main/install.sh | bash
  90. ```
  91. Or build from source:
  92. ```bash
  93. git clone https://codeberg.org/ric_harvey/omnimem.git && cd omnimem
  94. cp .env.example .env
  95. # Set VALKEY_PASSWORD and ANTHROPIC_API_KEY in .env
  96. docker compose up -d
  97. ```
  98. Then point your agent at it — **Claude Code** (`~/.claude.json`):
  99. ```json
  100. {
  101. "mcpServers": {
  102. "omnimem": {
  103. "type": "sse",
  104. "url": "http://localhost:8765/sse"
  105. }
  106. }
  107. }
  108. ```
  109. The server delivers its usage guide to any connecting agent automatically via the MCP `instructions` field — no configuration file needed. The web dashboard is at `http://localhost:8080`.
  110. The full walkthrough, including auth tokens, permission settings, and the other agents, is in [docs/quick-start.md](docs/quick-start.md).
  111. ---
  112. ## Documentation
  113. | | |
  114. |---|---|
  115. | [Quick start](docs/quick-start.md) | Installer, building from source, connecting your agent |
  116. | [Features in depth](docs/features.md) | Lifecycle, graveyard, experience scoring, dedup, contradictions, briefing |
  117. | [The skill compiler](docs/skill-compiler.md) | Compiling experience into loadable skills |
  118. | [MCP tool reference](docs/mcp-tools.md) | All 30+ tools |
  119. | [Configuration reference](docs/configuration.md) | Every environment variable |
  120. | [RSS & knowledge](docs/rss-knowledge.md) | Passive knowledge ingestion and promotion |
  121. | [Multiple machines](docs/remote-access.md) | Reverse proxy, OAuth 2.1 for claude.ai, troubleshooting |
  122. | [Web UI](docs/web-ui.md) | The management dashboard and Prometheus metrics |
  123. | [Architecture](docs/architecture.md) | Containers, recall pipeline, design decisions |
  124. | [Memory type specs](docs/memory-types.md) | The storage model, field by field |
  125. | [Connection guides](guides/) | Per-agent setup |
  126. | Deployment guides | [macOS](guides/omnimem-setup-macos.md) · [Raspberry Pi](guides/omnimem-setup-raspberry-pi.md) · [AWS](guides/omnimem-setup-aws-linux.md) · [GCP](guides/omnimem-setup-gcp-linux.md) · [Linux + Tailscale Funnel](guides/omnimem-setup-linux-tailscale.md) |
  127. Per-namespace storage specifications, if you want to know exactly what gets written to Valkey and by whom: [overview](docs/memory-types.md) · [episodic](docs/memory-episodic.md) · [project](docs/memory-project.md) · [knowledge](docs/memory-knowledge.md) · [preference](docs/memory-preference.md) · [skill](docs/memory-skill.md)
  128. ---
  129. ## Contributing
  130. Issues and PRs are welcome. Development happens on [Codeberg](https://codeberg.org/ric_harvey/omnimem) — issues and PRs there please. OmniMem is designed to be extended and the scoring pipeline is structured so new multipliers can be added without touching the core. New MCP tools, additional namespace types, and alternative embedding backends are all reasonable directions.
  131. ---
  132. ## Licence
  133. MIT. Free to use, fork, and modify. No enterprise tier, no hosted version, no strings.
  134. ---
  135. *Built by Ric Harvey @ [SquareCows Ltd](https://squarecows.com), an AI and automation consultancy for people who would rather own their tools.*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.