richarvey/omnimem repository overview

_{omnimem.org⁠ · Developed on Squarecows⁠, mirrored to GitHub⁠ · Issues on GitHub⁠}

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. It has no idea you lost an evening working out why WebKitGTK quietly ignores a redirect from a custom URL scheme.

So you explain everything again, and the agent confidently suggests the exact thing that didn't work. Same alarm, same song. You're Bill Murray and your agent is Punxsutawney.

OmniMem fixes that. It gives your AI agent a memory that lasts across sessions, projects and machines, 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.

⁠One program, two ways to run it

OmniMem 7 is a single binary. The MCP server, the memory engine, the embedding model, RSS ingestion and the database all live in one process, with your memories in one SQLite file. No containers to wrangle, no database server to babysit.

• On your desktop it sits in the tray (or the menu bar on a Mac). The icon tells you it's running, copies the MCP address for you, and opens a settings window where you can browse memories, review skills, edit your feeds, take backups and change settings.
• On a server it's omnimem serve: a systemd service from the .deb or .rpm, or a container, configured with environment variables (one .env file for the service), with nothing graphical anywhere near it.

The embedding model (all-MiniLM-L6-v2 on ONNX Runtime) runs locally. Nothing leaves the machine unless you add an Anthropic API key for the optional Claude Haiku features: fact extraction, query expansion, deeper contradiction checks and RSS summaries.

⁠Install

Everything is on the releases page⁠, each file with a .sha256 beside it.

Linux builds need glibc 2.38 or newer: Debian 13, Ubuntu 24.04, Fedora 39 and later.

Then point your agent at http://127.0.0.1:8765/mcp. In the desktop app the tray menu does it for you: Add to Claude Code and Add to Claude Desktop check first so OmniMem is never added twice, and Copy MCP URL covers everything else. By hand, for Claude Code, that's:

claude mcp add --transport http --scope user omnimem http://127.0.0.1:8765/mcp

The server hands its own usage guide to every agent that connects, so there's no instructions file to copy around. The quick start⁠ covers the rest.

⁠What it remembers

Five kinds of memory, all searched together when your agent recalls something:

• Episodic: the decisions you made, the bugs you fixed, the patterns you found. The hard-won stuff you shouldn't have to relearn every morning.
• Project context: your stack, goals and current state, so the agent turns up briefed instead of cold.
• Knowledge: articles from RSS feeds you pick, fetched on a schedule, embedded and stored (and summarised by Claude Haiku if you've given it a key). A feed can also feed a compiled skill directly.
• Preferences: rules about how you like to work ("always update the README after a feature lands"), picked up from your conversations and surfaced when they apply.
• Skills: SKILL.md documents compiled from your experience in a domain, so the agent works your way from the first prompt. Nothing changes without your say-so. See the skill compiler⁠.

The top result might be a decision from six months ago on another project, yesterday's fix, or an article that landed on Tuesday night. It doesn't matter where it came from, as long as it's useful.

⁠What makes it different

It isn't a key-value store with an MCP wrapper. OmniMem tries to behave the way memory actually does: things fade, they sometimes contradict each other, and the hard-won stuff earns its place.

• Hooks for Claude Code⁠: memory that works without the agent choosing to use it, because mostly it doesn't. omnimem hook puts the project's briefing in the opening context of every session, stops a tool call that repeats a known dead end before it runs (handing back what failed and what worked instead), and records what a session changed when it ends. Over ten paired runs on one task, every attempt at the abandoned approach was stopped, no treated run hit a failing test suite against 8 of 10 without, and it cost 27% less.
• The graveyard⁠: every dead end is logged with what you tried, why it failed and how long it cost you. The agent checks it before suggesting a library or pattern.
• Experience scoring⁠: something that took four attempts and a weird workaround to crack is gold. The harder it was, the more readily it comes back.
• Memory lifecycle⁠: ACTIVE → DEPRIORITISED → ARCHIVED → DELETED. "Forget about X" usually means stop bringing it up, not wipe it from existence.
• Contradiction detection⁠: a quick check on every write, and a deeper look with Claude Haiku when you want one.
• Semantic deduplication⁠: near-duplicates get flagged as they're written and cleaned up in bulk with find_duplicates().
• One-call briefing⁠: briefing() hands over project context, experience stats, stale memories, new articles, contradictions and skill suggestions in one go.
• The skill compiler⁠: turns reinforced lessons and dead ends into loadable skills, behind a propose-and-accept gate so a one-off opinion can't quietly become policy.
• Auto-maintenance⁠: duplicates archived, contradictions flagged, expired articles tidied, all in the background.
• Licence and provenance⁠: every memory records whether it can be redistributed and who's speaking (you, the agent, or a source it retrieved), so a later session can tell evidence from inference.

The ranking behind every recall:

score = similarity x surface_score x recency x experience_weight x date_boost

Similarity on its own isn't enough, so lifecycle state, age, how hard a lesson was to learn and whether it happened on the date you asked about all get a say. What gets dropped as irrelevant is decided on similarity alone.

⁠Works with any MCP agent

One memory for all of them: claude.ai⁠, Claude Code⁠, Claude Desktop⁠, Cursor⁠, GitHub Copilot⁠, GitLab Duo⁠, AWS Kiro⁠, OpenCode⁠, OpenAI Codex CLI⁠ and Open Design⁠. 48 tools, served over streamable HTTP.

Run it on one machine and put it behind a reverse proxy, and every laptop and agent you use shares the same memory. A shared token covers your own clients; OAuth 2.1 with a login page covers claude.ai and anything else that signs in. See multiple machines⁠.

⁠How it fits together

flowchart LR
    agent["AI agent<br/>Claude Code · claude.ai · Cursor · ..."]
    user["You, in the settings window"]

    subgraph omnimem["omnimem (one process)"]
        mcp["MCP server<br/>streamable HTTP · token · OAuth 2.1"]
        panel["Settings panel<br/>desktop app only, never on the network"]
        rss["RSS scheduler"]
        enrich["Enrichment worker"]
        engine["Memory engine<br/>recall · lifecycle · skills"]
        embed["Embedder<br/>ONNX Runtime"]
        store[("SQLite file<br/>vectors searched in memory")]
    end

    agent -- ":8765/mcp" --> mcp
    user --> panel
    mcp --> engine
    panel --> engine
    rss --> engine
    enrich --> engine
    engine --> embed
    engine --> store

Over the network it answers /mcp, the OAuth routes and /healthz, and that's the whole list. The settings window talks to the process directly, so there's no dashboard port for anyone else to find. More in the architecture doc⁠.

⁠Self-hosted, open source, yours

No SaaS. No vendor lock-in. No context shipped off to someone else's servers.

• One file holds your memories. Back it up the way you back up any file, or use dump_to_file() for a portable JSON export.
• Local embeddings: no API calls to turn text into vectors, and no GPU needed.
• Linux on x86_64 and arm64, so it's as happy on a Raspberry Pi or a Graviton box as on your laptop, plus Windows on x64 and Macs on Apple silicon.
• MIT licensed: fork it, extend it, run it wherever you like.

⁠Coming from 6.x?

OmniMem 6 was a Docker Compose stack: Valkey, a Python MCP server, a web UI and an RSS worker. Version 7 does the same job as one program, and your memories come with you:

1. Take a backup on 6.x with dump_to_file().
2. Import it with omnimem import <file>, or restore it from the settings window's Backups page. Every memory gets re-embedded from its text (roughly 8 ms each), which also brings back any memory 6.x had stopped finding.

The tools, the vectors and your compiled skills behave as they did, so nothing needs retuning. Recall scoring has three deliberate changes since 6.x: recency declines from day one rather than staying flat for 90 days (older memories rank a little lower; nothing extra is dropped), an abandoned outcome no longer scores 0.1, and recording an abandonment no longer suppresses anything. Your agents just need their URL changing from /sse to /mcp. The quick start⁠ has the details, and 6.x itself carries on in the v6.7.x branch.

⁠Documentation

Per-namespace specs, if you want to know exactly what gets stored and by whom: overview⁠ · episodic⁠ · project⁠ · knowledge⁠ · preference⁠ · skill⁠

⁠Contributing

Found a bug or want something? Open an issue on GitHub⁠. The code is developed on Squarecows⁠, where pull requests are welcome, and mirrored to GitHub.

It's a Cargo workspace (Rust 1.91 or newer): cargo test runs the suite without needing GTK, and scripts/desktop-check.sh builds and smoke-tests the desktop app in a container. The scripts/*-package.sh scripts build each installer locally the way CI does. New MCP tools, extra scoring multipliers and other embedding models are all fair game.

⁠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.