ClaudioDrews/memory-os

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.

What it solves

Memory OS addresses the "amnesia" problem common in AI agents, where users must repeat context, preferences, and project details at the start of every new session. It provides a permanent, local memory infrastructure that allows an agent to remember decisions, reasoning, and structured facts across all past conversations without relying on cloud-based memory subscriptions or specific LLM providers.

How it works

Memory OS implements a seven-layer memory architecture that captures, stores, and injects context into the agent's prompt:

  1. Workspace: Uses markdown files (MEMORY.md, USER.md, CREATIVE.md) injected into every system prompt.
  2. Sessions: A SQLite database with FTS5 for full-text search across conversation history.
  3. Structured Facts: A SQLite store for durable facts with entity resolution and trust scoring.
  4. Fabric: A modified Icarus plugin for LLM-powered session extraction and multi-source injection.
  5. Vector Database: Qdrant for hybrid search (dense and sparse) with semantic deduplication and a decay scanner.
  6. LLM Wiki: An auto-curated vault of concepts and entities.
  7. Ground Truth Hierarchy: A critical identity layer that instructs the agent to treat the injected memory as authoritative, preventing the agent from wasting tokens by trying to re-verify information already provided in the prompt.

Who it’s for

Users of the Hermes Agent who want a long-term collaborator that evolves over time and requires a local, private, and provider-agnostic memory stack.

Highlights

  • Local Infrastructure: Runs entirely on the user's machine using Docker (Qdrant, Redis, ARQ Worker).
  • Provider Agnostic: Compatible with any LLM provider supported by Hermes (e.g., OpenRouter, OpenAI, Anthropic, Ollama).
  • Surgical Injection: Uses relevance thresholds and per-session deduplication to keep prompts token-efficient.
  • Automatic Learning: Performs learning extraction and capture after LLM calls and at the end of sessions.
  • One-Command Install: Includes a setup script for rapid deployment of the entire stack.