# Memory OS

> A 6-layer memory operating system for Hermes Agent that provides persistent, local memory infrastructure with Qdrant vector search, structured facts, and surgical context injection.

Memory OS is an open-source, MIT-licensed memory operating system built by Claudio Drews for Hermes Agent. It runs entirely on your local machine and works with any LLM provider — OpenRouter, OpenAI, Anthropic, Ollama, or local models — with no cloud memory subscription or vendor lock-in. The project was created to solve the persistent problem of agent amnesia: losing context, decisions, and structured knowledge between sessions.

## What It Is

Memory OS is a complete local memory infrastructure layer for Hermes Agent, not a simple plugin. It stacks six distinct memory layers — from flat markdown files to a Qdrant vector database — that work in concert to give an agent genuine long-term recall. The system automatically injects the right context at the right moment using relevance-gated retrieval, per-session deduplication, and a social-closer filter that skips trivial messages. The result is what the README describes as "surgical token efficiency": the LLM receives exactly what it needs, nothing more.

## The Six-Layer Architecture

Each layer handles a different scope and type of memory:

- **Layer 1 – Workspace**: Markdown files (`MEMORY.md`, `USER.md`, `CREATIVE.md`) injected into the system prompt every turn
- **Layer 2 – Sessions**: SQLite with FTS5 full-text search across the entire conversation history
- **Layer 3 – Structured Facts**: A dedicated SQLite store with entity resolution, trust scoring, and an automatic feedback loop that trains trust scores over time
- **Layer 4 – Fabric (Cross-Session)**: A heavily forked version of the Icarus plugin with LLM-powered session extraction and multi-source injection across 16 tools
- **Layer 5 – Vector Database**: Qdrant running locally with 4096-dimensional cosine similarity plus BM25 sparse search, a 4-level fallback cascade, weekly decay scanning, and semantic deduplication (cosine > 0.92 triggers a merge)
- **Layer 6 – LLM Wiki**: A self-curating knowledge vault organized into `concepts/`, `entities/`, and `comparisons/` directories, continuously ingested into Qdrant

The flow is: `pre_llm_call` triggers surgical recall from all four retrieval sources; `post_llm_call` and `on_session_end` trigger automatic learning extraction and capture.

## Infrastructure and Requirements

Memory OS requires Hermes Agent, Docker (for Qdrant, Redis, and an ARQ Worker), and Python 3.11+. The entire memory stack runs locally — no data leaves the machine. The bundled Icarus fork (`icarus/`) is not upstream-compatible with the original `esaradev/icarus-plugin`; key additions include LLM-powered session extraction, multi-source injection, CREATIVE.md isolation, backtick sanitization, a system injection filter, and social closer detection. A companion project, Vault Curator v3 (`ClaudioDrews/vault-curator`), handles frontmatter enrichment, semantic linking, and MOC index generation for the wiki layer.

## How It Differs from Cloud Memory Solutions

The README explicitly positions Memory OS against cloud-first alternatives like mem0, Zep, and Letta, noting that those solutions require cloud memory subscriptions and do not offer full local infrastructure. Memory OS's stated differentiators include: fully local memory infrastructure, no memory subscription, provider-agnostic LLM support, Hermes-native integration, structured facts with trust scores, a self-curating wiki, and intelligent decay with archival — none of which the README attributes to the compared alternatives.

## Current Status

The repository was created on May 31, 2026, and last pushed on June 1, 2026, making it a very recent release. It is written primarily in Python, licensed under MIT, and hosted at `github.com/ClaudioDrews/memory-os`. At the time of indexing the project had 38 stars and 1 fork with no open issues.

## Features
- 6-layer memory architecture
- Local memory infrastructure (no cloud)
- Qdrant vector database with hybrid search (cosine + BM25)
- Structured facts store with trust scoring and entity resolution
- Full-text search across entire conversation history (SQLite FTS5)
- Self-curating LLM Wiki (concepts, entities, comparisons)
- Surgical context injection with relevance gating
- Per-session deduplication
- Social-closer filter for trivial message skipping
- Weekly decay scanner and semantic deduplication
- LLM-powered session extraction via forked Icarus plugin
- 16 Fabric tools (fabric_recall, fabric_write, fabric_brief, etc.)
- CREATIVE.md workspace isolation
- 4-level retrieval fallback cascade
- Provider-agnostic: OpenRouter, OpenAI, Anthropic, Ollama, local models
- ARQ async worker queue via Redis
- Vault Curator v3 integration for wiki enrichment

## Integrations
Hermes Agent, Qdrant, Redis, Docker, OpenRouter, OpenAI, Anthropic, Ollama, Vault Curator v3, Icarus Plugin (forked)

## Platforms
CLI, API

## Pricing
Open Source

## Version
main

## Links
- Website: https://github.com/ClaudioDrews/memory-os
- Documentation: https://github.com/ClaudioDrews/memory-os/blob/main/setup/install.md
- Repository: https://github.com/ClaudioDrews/memory-os
- EveryDev.ai: https://www.everydev.ai/tools/memory-os