Memory OS: A 7-Layer Memory Stack for Hermes Agent, With a Ground Truth Layer That Does the Real Work
A 7-layer memory operating system for Hermes Agent — persistent memory with Qdrant, structured facts, fabric recall, auto-curated wiki, and surgical context injection. Runs locally, any LLM provider.
At a glance
- What is it?
- Memory OS wires Qdrant, SQLite/FTS5, a forked Icarus plugin and an auto-curated wiki into Hermes Agent, then adds a Ground Truth layer that instructs the agent to trust what was injected. The interesting part is that last layer, and the fact that the project admits layers 2 through 6 are useless without it.
- Who is it for?
- Adopt Memory OS if you already run Hermes Agent and want memory to stay on your own hardware: the stack is Docker plus SQLite plus Qdrant, the licence is MIT, and the README is unusually candid that injection without Layer 7 produces memory-zero behaviour. Do not adopt it if you are not a Hermes user, or if you want a memory layer you can drop into an arbitrary agent framework; the Icarus plugin fork and the Ground Truth files are Hermes-specific.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 98 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The failure mode Memory OS was built around: an agent that rediscovers what it already knows
The README frames the problem in terms of repetition. You configure Hermes Agent, teach it preferences, work through hard problems, and the next session starts from zero. Four symptoms are listed: repeating context at the start of every conversation, losing the thread of decisions made weeks earlier, structured facts about your stack and projects having nowhere to live, and existing memory solutions being either cloud-locked or too shallow to matter.
That last complaint is the design brief. Memory OS is local-first by construction: Qdrant, Redis and an ARQ worker run in Docker on your machine, sessions and facts live in SQLite files, and the README states the memory infrastructure runs entirely on your machine with no memory subscription and no vendor lock-in. The LLM provider is a separate choice, and the project claims compatibility with any provider Hermes supports, naming OpenRouter, OpenAI, Anthropic and Ollama.
The audience is therefore narrow and specific: people already running Hermes Agent, comfortable with Docker and Python 3.11+, who want persistent memory they host themselves. It is not a general-purpose memory library for arbitrary agents.
Seven layers, two directions of flow, and one layer that changes the meaning of the other six
The architecture is a stack of seven named layers. Layer 1 is flat workspace files (MEMORY.md, USER.md, CREATIVE.md) injected into the system prompt every turn. Layer 2 is state.db, SQLite with FTS5, giving full-text search over conversation history. Layer 3 is memory_store.db, also SQLite, adding HRR, FTS5 and trust scoring, described as durable facts with entity resolution and a feedback loop that trains trust scores over time. Layer 4 is the Icarus plugin, heavily forked, providing LLM-powered session extraction, multi-source injection and 16 tools including fabric_recall, fabric_write and fabric_brief. Layer 5 is Qdrant, configured as 4096-dimensional cosine plus BM25 sparse, with a four-level fallback chain (hybrid, then dense, then lexical, then SQLite), a weekly decay scanner and semantic dedup that merges points above cosine 0.92. Layer 6 is an auto-curated wiki vault organised into concepts, entities and comparisons, continuously ingested into Qdrant. Layer 7 is the Ground Truth hierarchy: SOUL.md and rulebook.md.
The data flow runs in two directions. On pre_llm_call, recall is pulled from four sources at once: Fabric, Qdrant, sessions and facts. Each source is gated by relevance thresholds, per-session deduplication stops the same context appearing twice, and a social-closer filter skips trivial messages. After the model responds, post_llm_call and on_session_end trigger extraction and capture.
The four-level fallback in Layer 5 is the most concrete engineering detail in the README. If hybrid search fails, dense search runs; if that fails, lexical; if that fails, SQLite answers. That is a degradation path rather than a single point of failure, and it is the kind of choice that matters when Qdrant is a Docker container that can be down while you are mid-session.
Layer 7 is the project's actual thesis, and the README is honest about why
The README devotes a section to arguing that Layer 7 is the most important layer, and the argument is worth restating because it is the least common claim in this category. Layers 1 through 6 capture, store and inject memory. Layer 7 tells the agent to use it.
Without the Ground Truth hierarchy, the README says four things happen: Qdrant points are injected but the agent calls the Qdrant API to verify them; Fabric entries are injected but the agent runs fabric_recall to re-find them; session history is injected but the agent runs session_search to re-discover it; facts are injected but the agent probes fact_store to confirm them. The project calls the result memory-zero behavior despite perfect injection, and attributes it to rediscovery burning tokens, context and time.
This is a design position, not a feature. It says that retrieval quality is not the bottleneck; the bottleneck is whether the model treats injected context as authoritative. The mechanism is two files, SOUL.md and rulebook.md, that establish an identity-level hierarchy. If you disagree with that framing, or if your agent already trusts its context, Layer 7 is overhead. If you have watched an agent re-query a vector store for something already sitting in its prompt, this is the part of the project aimed at you.
Installing it: one script, or a ten-step manual path as fallback
Version 0.2.0 introduced a one-command install. The README gives it verbatim:
curl -sSL https://raw.githubusercontent.com/ClaudioDrews/memory-os/main/setup.sh | bash
According to the release notes, that script sets up the entire stack: Docker services, SQLite databases, the Icarus plugin and the environment. The previous 10-step manual guide is retained as a troubleshooting fallback rather than the primary path.
The stated requirements are Hermes Agent, Docker (for Qdrant, Redis and an ARQ worker), and Python 3.11 or newer. The v0.2.0 notes also mention idempotent database initialization, provider-agnostic LLM extraction, O(1) path lookups, FTS5-powered session search and semantic dedup at scale among 20-plus audit fixes.
Two things are worth flagging. First, piping a remote script into bash is a trust decision, and the README offers no checksum or signature to verify before execution; you can read setup.sh at the raw URL first, and that is the reasonable move. Second, the release notes state the installer was tested end-to-end including on modest machines where Docker build times exposed UX gaps that are now handled gracefully. That is a claim from the project, not an independent measurement, and build time on your hardware is the thing most likely to make the first run feel slow.
Where Memory OS is the wrong tool, and what it costs to keep running
The clearest limitation is structural: this is a Hermes Agent memory OS, not a portable memory layer. Layer 4 is a heavily forked Icarus plugin, Layer 7 is a pair of files that speak to Hermes' identity handling, and the pipeline hangs off Hermes hooks (pre_llm_call, post_llm_call, on_session_end). If you are building on a different agent framework, none of that transfers without porting work the README does not describe.
The second limitation is operational surface. A working install means a Qdrant container, a Redis container, an ARQ worker, at least two SQLite databases, a wiki vault that is continuously ingested, and a weekly decay scanner. That is a lot of moving parts for a single-user memory system, and each one is a place where something can stop without the agent telling you. The four-level fallback in Layer 5 softens this for reads, but it also means a silent degradation to SQLite-only recall can look like normal operation.
Storage growth is the third. Semantic dedup merges points above cosine 0.92 and a decay scanner runs weekly, which suggests the project expects the vector store to accumulate. There is no figure in the supplied material for index size, ingestion throughput, or recall latency, so any capacity planning has to come from your own measurements.
On maintenance and licence: the project is MIT-licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are preserved; that is a summary of the licence text, not legal advice, and you should read the LICENSE file and your own counsel's view before shipping it inside a product. Dependencies carry their own licences, and Qdrant, Redis and Hermes Agent are separate projects with their own terms. Upgrades are the other recurring cost. With no numbered releases retrieved in the supplied material, the practical upgrade path is tracking main and re-reading the v0.2.0-style change notes, which means database migrations land on you rather than on a release cadence you can schedule.
How it differs from a plain RAG pipeline or a hosted memory service
The obvious comparison is a conventional RAG setup: chunk documents, embed them, retrieve top-k at query time, paste into the prompt. Memory OS contains that pattern inside Layer 5 and then refuses to rely on it alone. Retrieval is gated by per-source relevance thresholds, deduplicated per session, and filtered so trivial social messages never reach the prompt. The project's framing is surgical injection rather than a firehose, and the four-level fallback means a vector outage degrades rather than fails.
The second comparison is a hosted memory service, the cloud-locked option the README complains about. The difference is where the data sits and who can read it. Memory OS keeps Qdrant, Redis and SQLite on your hardware and treats the LLM provider as a swappable component, which means the memory store survives a provider change. The trade is that you operate the store.
The third comparison, and the more interesting one, is stock Hermes. The README includes a comparison table whose content is truncated in the supplied material, so the specific rows cannot be quoted here. What can be said from the architecture is that stock Hermes has no equivalent of the Ground Truth hierarchy, and the project's whole argument is that this is the difference between injected context being used and being ignored. Whether that holds in your sessions is the thing to check, not the layer count.
Who should install this, and what to confirm first
Memory OS is for Hermes Agent users who have felt the amnesia problem directly and want the fix on their own hardware. The MIT licence removes the usual commercial friction, the local-first design removes the provider-lock concern, and the README's willingness to say that six of seven layers are inert without the seventh is a sign the author has debugged this in production rather than assembled it from parts.
It is not for you if you are not on Hermes Agent, if you want a memory component you can embed in another framework, or if you are unwilling to run Docker services alongside your agent. The ten-step manual guide exists for troubleshooting, not as a lighter alternative.
Before you commit, verify four things on your own machine. Run setup.sh and watch the Docker build times, since that is where the release notes admit modest hardware struggled. Confirm your Hermes version exposes the pre_llm_call, post_llm_call and on_session_end hooks the pipeline is built on. Check that your embedding model produces 4096-dimensional vectors, because the Qdrant collection is declared at 4096d cosine and a mismatch will not announce itself politely. And read SOUL.md and rulebook.md before the agent does, because Layer 7 is where you are handing the agent a rule about what to trust, and that rule should be yours.
Editorial conclusion
Adopt Memory OS if you already run Hermes Agent and want memory to stay on your own hardware: the stack is Docker plus SQLite plus Qdrant, the licence is MIT, and the README is unusually candid that injection without Layer 7 produces memory-zero behaviour. Do not adopt it if you are not a Hermes user, or if you want a memory layer you can drop into an arbitrary agent framework; the Icarus plugin fork and the Ground Truth files are Hermes-specific. Before committing, verify three things on your own machine: that the setup.sh one-command install completes against your Docker build times (the README notes modest hardware exposed UX gaps that are now handled), that your Hermes version exposes the pre_llm_call, post_llm_call and on_session_end hooks the pipeline depends on, and that the 4096-dimension Qdrant collection matches the embedding model you actually configure, since a dimension mismatch is the first thing that will silently break hybrid recall.
Community notes