# https://github.com/MemTensor/MemOS Project Manual Generated at: 2026-06-26 02:50:22 UTC ## Table of Contents - [MemOS Overview and Architecture](#page-1) - [Core Memory System: MemCube, Textual/Activation/Parametric Memory, Scheduler and Retrieval](#page-2) - [Local Plugins: memos-local-plugin and memos-local-openclaw for Hermes/OpenClaw](#page-3) - [Deployment, Configuration, Evaluation, and Operations](#page-4) ## MemOS Overview and Architecture ### Related Pages Related topics: [Core Memory System: MemCube, Textual/Activation/Parametric Memory, Scheduler and Retrieval](#page-2), [Deployment, Configuration, Evaluation, and Operations](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md) - [src/memos/plugins/README.md](https://github.com/MemTensor/MemOS/blob/main/src/memos/plugins/README.md) - [apps/memos-local-plugin/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/package.json) - [apps/memos-local-openclaw/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-openclaw/package.json) - [apps/memos-local-plugin/core/skill/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md) - [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md) - [apps/memos-local-plugin/core/feedback/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/feedback/README.md) - [apps/memos-local-plugin/core/llm/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/llm/README.md) - [apps/memos-local-plugin/core/memory/l1/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/memory/l1/README.md) - [examples/README.md](https://github.com/MemTensor/MemOS/blob/main/examples/README.md)
# MemOS Overview and Architecture ## Purpose and Scope MemOS is a **Memory Operating System for LLMs and AI agents**. It unifies the store/retrieve/manage loop for long-term memory and enables context-aware, personalized interactions with knowledge bases, multi-modal memory, tool memory, and enterprise-grade optimizations. According to [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md), MemOS positions itself around five pillars: - **Unified Memory API** — a single API to add, retrieve, edit, and delete memory, structured as a graph (inspectable and editable, not a black-box embedding store). - **Multi-Modal Memory** — native support for text, images, tool traces, and personas, retrieved and reasoned together. - **Multi-Cube Knowledge Base Management** — composable memory cubes with isolation, controlled sharing, and dynamic composition across users, projects, and agents. - **Asynchronous Ingestion via MemScheduler** — millisecond-level latency for production stability under high concurrency. - **Memory Feedback & Correction** — natural-language feedback to refine, supplement, or replace existing memories. The project ships a benchmarked advantage on LoCoMo (75.80), LongMemEval (+40.43%), PrefEval-10 (+2568%), and PersonaMem (+40.75%) versus baseline, with ~35.24% token savings ([README.md](https://github.com/MemTensor/MemOS/blob/main/README.md)). ## Core Architecture MemOS is delivered as a monorepo with three production tracks that share a common conceptual model: the Python **MemOS core**, the local TypeScript plugin (`memos-local-plugin`), and the OpenClaw gateway plugin (`memos-local-openclaw-plugin`). ```mermaid graph TB subgraph "Cloud Track" CloudAPI[MemOS Cloud API
memos.openmem.net] end subgraph "Local Track" CorePy[MemOS Core · Python
src/memos/*] Cube[MemCube
composable KB units] PluginMgr[Plugin Manager
entry-point discovery] end subgraph "Local Plugin · TypeScript" L1[L1 Traces
episodes + tags] L2[L2 Policies
cross-task induction] L3[L3 World Model
abstractions] Skill[Skill Crystallization
Tier-1 retrieval] Retrieval[Hybrid Retrieval
vec + FTS5 + pattern] Feedback[Feedback + Decision Repair] end subgraph "Agent Adapters" OpenClaw[memos-local-openclaw
OpenClaw lifecycle hooks] Hermes[Hermes Agent adapter] end CloudAPI --> CorePy CorePy --> Cube CorePy --> PluginMgr PluginMgr -.registers.-> Dream[dream plugin] OpenClaw --> L1 OpenClaw --> L2 OpenClaw --> L3 OpenClaw --> Skill OpenClaw --> Retrieval Hermes --> L1 Retrieval --> Feedback ``` ### Python Core and Plugin System The Python core lives under `src/memos/`. The plugin framework is described in [src/memos/plugins/README.md](https://github.com/MemTensor/MemOS/blob/main/src/memos/plugins/README.md) and consists of: - `base.py` — `MemOSPlugin` base class - `manager.py` — discovery, loading, and initialization - `hooks.py` / `hook_defs.py` — hook registration and core hook constants - `component_bootstrap.py` — runtime context bootstrap helpers Plugins are discovered through a Python entry-point group (`memos.plugins`); the built-in `dream` plugin is registered as `memos.dream:CommunityDreamPlugin`. At startup, `PluginManager` loads installed entry points, keeps the highest-priority implementation when multiple providers expose the same logical name, and initializes enabled plugins. Source: [src/memos/plugins/README.md](https://github.com/MemTensor/MemOS/blob/main/src/memos/plugins/README.md). ### Local Plugin (`memos-local-plugin`) The local track is a Node/TypeScript package declared in [apps/memos-local-plugin/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/package.json) as `@memtensor/memos-local-plugin` v2.0.x. Its description names the architecture: "Reflect2Evolve memory plugin: layered L1/L2/L3 memory, reflection-weighted value backprop, cross-task policy induction, skill crystallization, three-tier retrieval. Adapters for OpenClaw and Hermes Agent via a shared algorithm core." The retrieval module implements a **three-channel hybrid recall** (per [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md)): | Channel | Source | Purpose | |---------|--------|---------| | `vec_summary` / `vec_action` | cosine on `traces.vec_*` | Semantic recall on what was said and what tools were called | | `vec` (skills, world model) | cosine | Tier-1 / Tier-3 semantic recall | | `fts` | FTS5 trigram `MATCH` | Keyword-precise hits, English + CJK ≥ 3 chars | | `pattern` | `LIKE %term%` | CJK bigrams and 2-char ASCII that fall below the trigram window | | `structural` | `instr(error_signatures_json, ...)` | Verbatim error-signature replay | Per-channel results are fused with a Reciprocal Rank Fusion (RRF) score: `1 / (k + rank_i + 1)`. A hit confirmed by both vector and FTS channels gets a noticeably higher RRF, plugging the single-channel-false-positive hole of pure cosine retrieval. An adaptive relevance floor drops candidates below `topRelevance · relativeThresholdFloor` (default `0.4`) before a smart-seed MMR diversifies the result set. Source: [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md). The LLM layer ([apps/memos-local-plugin/core/llm/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/llm/README.md)) exposes five real providers behind a single `LlmClient` facade: `openai_compatible`, `anthropic`, `gemini`, `bedrock`, and `host` (delegates to the OpenClaw host). A sixth sentinel, `local_only`, always throws `LLM_UNAVAILABLE` to explicitly disable LLM calls. All providers share the same surface for text, parsed JSON, and streaming output. ### Memory Layers The local plugin organizes memory into three layers, each with its own directory and lifecycle: - **L1 — Traces.** Per [apps/memos-local-plugin/core/memory/l1/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/memory/l1/README.md), L1 is "storage + a few cheap write-time enrichments" (tags, error signatures). Every finalized episode produces ≥ 1 L1 trace regardless of reward or capture success, so the timeline is never empty. - **L2 — Policies** and **L3 — World Model** are algorithm-heavy: each owns a subscriber, an inducer, and a lifecycle. The L2 policy boundary carries an inline `@repair {json}` tag so the skill packager picks up feedback-derived guidance during the next crystallization ([apps/memos-local-plugin/core/feedback/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/feedback/README.md)). - **Skills.** Crystallized, prompt-ready procedures. Per [apps/memos-local-plugin/core/skill/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md), `applyFeedback` is the single state-transition function: `trial.pass` moves a probationary skill to active, `trial.fail` retires it, `user.positive` revives a retired skill, and `user.negative` pushes it back to retired. Reliability is tracked with a Beta posterior `(passed+1)/(attempts+2)`. ### Agent Adapters and OpenClaw Integration The OpenClaw-facing plugin ([apps/memos-local-openclaw/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-openclaw/package.json), v1.0.9-beta) is declared as a `memory` extension with `installDependencies: true` and ships a `memos-memory-guide` skill. A separate `openwork-memos-integration` app demonstrates desktop usage. ## Deployment Options [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md) lists four deployment modes: **Cloud API** (hosted at `memos.openmem.net`), **Self-Hosted** (Docker), **Quick Mode** (lightweight), and **Full Mode** (complete). Runnable examples for each module live under `examples/` and span embedders, LLMs, chunkers, rerankers, graph databases, textual memory helpers, the dream pipeline, and MemCube load/dump flows ([examples/README.md](https://github.com/MemTensor/MemOS/blob/main/examples/README.md)). ## Community-Relevant Concerns Several active discussions map directly onto the architecture above: - **Multi-agent isolation** (issues #1361, #1318): `patternSearch` historically lacked an `ownerFilter`, letting one agent read another's short CJK queries. The current `memory_search` tool must therefore enforce an owner scope, and the hybrid channels (FTS5 + pattern) are precisely the surface where the bug surfaced. - **CJK search quality** (issue #1961): The built-in FTS5 tokenizer cannot match 2-character Chinese words, so the `pattern` channel exists as a `LIKE` fallback for CJK bigrams; see the channel table above. A configurable FTS5 tokenizer is the proposed fix to widen that window. - **Local providers** (issue #1231): Users want native `ollama` support in `memos-local-openclaw` for both embedding and summarization, complementing the existing `openai_compatible` provider in [apps/memos-local-plugin/core/llm/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/llm/README.md). - **Self-hosted Cloud API** (issue #1433): The OpenClaw plugin currently targets the managed Cloud; exposing a self-hosted MemOS API endpoint is an open feature request. ## See Also - MemOS Plugin System (`src/memos/plugins/README.md`) - Retrieval Algorithms (`apps/memos-local-plugin/core/retrieval/README.md`) - L1 Traces (`apps/memos-local-plugin/core/memory/l1/README.md`) - Skill Crystallization (`apps/memos-local-plugin/core/skill/README.md`) - Feedback & Decision Repair (`apps/memos-local-plugin/core/feedback/README.md`) - LLM Layer (`apps/memos-local-plugin/core/llm/README.md`) - Examples Index (`examples/README.md`) --- ## Core Memory System: MemCube, Textual/Activation/Parametric Memory, Scheduler and Retrieval ### Related Pages Related topics: [MemOS Overview and Architecture](#page-1), [Local Plugins: memos-local-plugin and memos-local-openclaw for Hermes/OpenClaw](#page-3), [Deployment, Configuration, Evaluation, and Operations](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md) - [src/memos/plugins/README.md](https://github.com/MemTensor/MemOS/blob/main/src/memos/plugins/README.md) - [examples/README.md](https://github.com/MemTensor/MemOS/blob/main/examples/README.md) - [examples/data/mem_cube_2/README.md](https://github.com/MemTensor/MemOS/blob/main/examples/data/mem_cube_2/README.md) - [examples/mem_cube/_deprecated/README.md](https://github.com/MemTensor/MemOS/blob/main/examples/mem_cube/_deprecated/README.md) - [apps/memos-local-plugin/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/README.md) - [apps/memos-local-plugin/core/session/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/session/README.md) - [apps/memos-local-plugin/core/skill/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md) - [apps/memos-local-plugin/core/llm/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/llm/README.md) - [apps/memos-local-plugin/core/feedback/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/feedback/README.md) - [apps/memos-local-plugin/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/package.json) - [apps/memos-local-openclaw/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-openclaw/package.json) - [apps/memos-local-plugin/adapters/hermes/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/adapters/hermes/README.md)
# Core Memory System: MemCube, Textual/Activation/Parametric Memory, Scheduler and Retrieval ## Overview MemOS (Memory Operating System) is an open-source memory layer for LLM applications. The core memory system exposes a single, graph-structured API for adding, retrieving, editing, and deleting memory, treating memory as an inspectable resource rather than a black-box embedding store. Source: [README.md:31-40](https://github.com/MemTensor/MemOS/blob/main/README.md). The system is organized around three orthogonal axes: - **Memory container**: `MemCube` and the new `SingleCubeView` / `CompositeCubeView` facades. - **Memory type**: textual (graph + tree), activation (KV cache), and parametric (LoRA adapters). - **Lifecycle infrastructure**: `MemScheduler` for async ingestion and a pipeline-based retriever with hooks for context rendering. ```mermaid flowchart TB User[User / Agent] --> API[MemOS API Layer] API --> View{SingleCubeView
or CompositeCubeView} View --> TextMem[Textual Memory
graph + tree] View --> ActMem[Activation Memory
KV cache] View --> ParaMem[Parametric Memory
LoRA] API --> Sched[MemScheduler
Redis Streams + queues] Sched --> Ingest[Async Ingestion Workers] API --> Retr[Retrieval Pipeline] Retr --> Hooks[Search Pipeline Hooks] Retr --> Context[Rendered Context] TextMem -. feedback .-> FB[Feedback Bus] FB --> Sched ``` ## MemCube: The Composable Memory Container `MemCube` is the unit of memory packaging in MemOS. A MemCube is a typed configuration object — for example `memos.configs.mem_cube.GeneralMemCubeConfig` — that bundles textual, activation, and parametric memory into one addressable artifact. Source: [examples/data/mem_cube_2/README.md:1-1](https://github.com/MemTensor/MemOS/blob/main/examples/data/mem_cube_2/README.md). The legacy load path is `GeneralMemCube.init_from_dir()`, but the current best practice is to initialize the server with `init_server()` from `memos.api.handlers`, then operate on cubes through `SingleCubeView` (one cube) or `CompositeCubeView` (multiple cubes combined). The View layer unifies the API, normalizes the result format with `cube_id` tracking, and integrates cleanly with the MemOS Server. Source: [examples/mem_cube/_deprecated/README.md:11-31](https://github.com/MemTensor/MemOS/blob/main/examples/mem_cube/_deprecated/README.md). Multi-cube management is a first-class feature: knowledge bases can be isolated, shared, and composed dynamically across users, projects, and agents. The `examples/mem_cube/` directory demonstrates load/dump patterns and the lazy/remote cube resolvers. Source: [examples/README.md:9-10](https://github.com/MemTensor/MemOS/blob/main/examples/README.md). ## Three Memory Types MemOS distinguishes three memory substrates, each tuned for a different access pattern: | Type | Substrate | Use case | Search style | |---|---|---|---| | **Textual** | Graph + plaintext tree | Long-term facts, preferences, conversations | Hybrid FTS5 + vector; graph traversal | | **Activation** | KV cache (prefix-prefilled state) | Fast LLM warm-start, prompt continuation | Direct concatenation via `concat_cache` | | **Parametric** | LoRA adapters (MemReader) | Distilled skill/knowledge baked into weights | Adapter loading at inference | Textual memory is the inspectable backbone — exposed as a graph and editable through the unified API, not hidden behind embeddings. Source: [README.md:31-32](https://github.com/MemTensor/MemOS/blob/main/README.md). Activation memory stores KV-cache fragments so the model can resume near-instantly from prior context; the `concat_cache` method stitches them back together. Source: [README.md:88-96](https://github.com/MemTensor/MemOS/blob/main/README.md). Parametric memory materializes extracted knowledge as LoRA adapters via MemReader, giving a deployable model delta that does not need retrieval at inference. Source: [README.md:7-12](https://github.com/MemTensor/MemOS/blob/main/README.md). In the local-plugin stack, these are mirrored by a four-layer algorithm core: L1 trace (step-level grounded records), L2 policy (sub-task strategies), L3 world model (compressed environmental cognition), and crystallized Skills. Source: [apps/memos-local-plugin/README.md:11-19](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/README.md). ## MemScheduler: Asynchronous Ingestion `MemScheduler` runs memory operations asynchronously to keep write latency in the millisecond range under production concurrency. The implementation is built on Redis Streams with isolated queues, supports task priority, auto-recovery, and quota-based scheduling. Source: [README.md:18-21](https://github.com/MemTensor/MemOS/blob/main/README.md). Scheduler tasks can be observed through a stage log (added in v2.0.15) and can target any of the three memory types. As of v2.0.15, the default LLM used by the scheduler was switched to `general_llm` for broader model compatibility. Source: [release notes for v2.0.10–v2.0.15](https://github.com/MemTensor/MemOS/releases/tag/v2.0.15). The `examples/mem_scheduler/` folder contains Redis-backed asynchronous memory workflow examples. Source: [examples/README.md:13-13](https://github.com/MemTensor/MemOS/blob/main/examples/README.md). ## Retrieval & Search Pipeline The retrieval layer is a pipeline of stages that can be extended with hooks. The most recent refactor (v2.0.20, PR #1924) added **search pipeline hooks for context rendering**, allowing custom stages to run before the final context is injected into the LLM. Source: [Release v2.0.20](https://github.com/MemTensor/MemOS/releases/tag/v2.0.20). The default stages combine FTS5 keyword search with vector similarity and graph traversal over textual memory; they can be augmented with web search (e.g., BochaAISearchRetriever), which became part of the standard pipeline in v1.0.0. Source: [README.md:88-96](https://github.com/MemTensor/MemOS/blob/main/README.md). Known limitations that influence the retriever: - The default FTS5 tokenizer drops 2-character CJK tokens and mixed ASCII+CJK tokens below its trigram window, which motivated a configurable tokenizer feature request ([#1961](https://github.com/MemTensor/MemOS/issues/1961)). - In the local plugin's `memory_search` tool, `patternSearch` historically did not apply an `ownerFilter`, which caused memory-isolation leaks across agents in multi-agent setups ([#1361](https://github.com/MemTensor/MemOS/issues/1361)) and a hardcoded `agent:main` default ([#1318](https://github.com/MemTensor/MemOS/issues/1318)). Both have been patched in later releases and should be reviewed when deploying multi-agent topologies. ## Configuration & Extensibility MemOS exposes its plugin framework under `src/memos/plugins/`, with `MemOSPlugin` as the base class, `PluginManager` handling discovery via the `memos.plugins` entry-point group, and `hooks.py` / `hook_defs.py` providing the Hook runtime. The built-in `dream` plugin is a reference implementation registered as `memos.dream:CommunityDreamPlugin`. Source: [src/memos/plugins/README.md:8-39](https://github.com/MemTensor/MemOS/blob/main/src/memos/plugins/README.md). For LLM access inside the local-plugin algorithm core, a `LlmClient` facade wraps five real providers (`openai_compatible`, `anthropic`, `gemini`, `bedrock`, `host`) plus a `local_only` sentinel that throws `LLM_UNAVAILABLE`. All algorithm steps — reflection, reward, induction, decision-repair, skill crystallization — go through this facade. Source: [apps/memos-local-plugin/core/llm/README.md:1-21](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/llm/README.md). Feedback flows through a dedicated `SkillEventBus` and a `FeedbackEventBus`, with Beta-posterior `eta` updates driving skill lifecycle transitions (`probationary → active → retired`). Source: [apps/memos-local-plugin/core/skill/README.md:21-39](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md) and [apps/memos-local-plugin/core/feedback/README.md:11-22](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/feedback/README.md). ## See Also - [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md) — project overview, deployment options, and release history. - [src/memos/plugins/README.md](https://github.com/MemTensor/MemOS/blob/main/src/memos/plugins/README.md) — plugin architecture and Hook runtime. - [examples/README.md](https://github.com/MemTensor/MemOS/blob/main/examples/README.md) — runnable examples for `mem_cube`, `mem_scheduler`, `mem_reader`, `mem_chat`, and `mem_mcp`. - [apps/memos-local-plugin/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/README.md) — Reflect2Evolve layered memory (L1/L2/L3 + Skills). - [Release v2.0.20](https://github.com/MemTensor/MemOS/releases/tag/v2.0.20) — search pipeline hooks for context rendering. --- ## Local Plugins: memos-local-plugin and memos-local-openclaw for Hermes/OpenClaw ### Related Pages Related topics: [MemOS Overview and Architecture](#page-1), [Core Memory System: MemCube, Textual/Activation/Parametric Memory, Scheduler and Retrieval](#page-2)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md) - [apps/memos-local-plugin/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/package.json) - [apps/memos-local-openclaw/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-openclaw/package.json) - [apps/memos-local-plugin/adapters/hermes/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/adapters/hermes/README.md) - [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md) - [apps/memos-local-plugin/core/feedback/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/feedback/README.md) - [apps/memos-local-plugin/core/skill/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md) - [apps/memos-local-plugin/core/llm/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/llm/README.md) - [src/memos/plugins/README.md](https://github.com/MemTensor/MemOS/blob/main/src/memos/plugins/README.md)
# Local Plugins: memos-local-plugin and memos-local-openclaw for Hermes/OpenClaw ## 1. Overview and Scope MemOS ships two distinct "local" memory plugins aimed at agent runtimes that need on-device, self-contained memory without a cloud dependency: - **memos-local-plugin** (v2.x) — a unified, adapter-driven memory core that powers both OpenClaw and Hermes Agent. Its npm package is named `@memtensor/memos-local-plugin`, and the project tagline is "Reflect2Evolve memory plugin: layered L1/L2/L3 memory, reflection-weighted value backprop, cross-task policy induction, skill crystallization, three-tier retrieval." Source: [apps/memos-local-plugin/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/package.json). - **memos-local-openclaw-plugin** (v1.x) — a dedicated OpenClaw-only plugin that advertises "full-write, hybrid-recall, progressive retrieval" and is published as `@memtensor/memos-local-openclaw-plugin`. Source: [apps/memos-local-openclaw/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-openclaw/package.json). Both are positioned under the broader MemOS v2.0 "Stardust" release line and its follow-up local-plugin releases that emphasize 100% local operation, hybrid FTS5 + vector retrieval, smart deduplication, and tiered skill evolution. Source: [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md). The two plugins are **not interchangeable**. The local-plugin is a cross-runtime algorithm core that talks to OpenClaw and Hermes through thin adapters over stdio JSON-RPC 2.0. The local-openclaw-plugin is a single-runtime OpenClaw extension with its own retrieval, embedding, and viewer stack. The README of the root project frames them as siblings: "One core powers self-evolving memory across L1 traces, L2 policies, L3 world models, and crystallized Skills." Source: [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md). ## 2. Architecture: Shared Core Plus Thin Adapters The newer memos-local-plugin centralizes the algorithm in a TypeScript core and exposes it to agents through two adapters. The Hermes adapter is documented in detail: > "Hermes is a Python-based agent. The core of `memos-local-plugin` is written in TypeScript and runs on Node.js. This adapter bridges the two … The Python side is **stateless** — every `MemoryProvider` method is a thin proxy that translates to a JSON-RPC call. All algorithm logic (L1/L2/L3, skills, retrieval, feedback, decision repair) lives in the shared TS core." Source: [apps/memos-local-plugin/adapters/hermes/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/adapters/hermes/README.md). The bridge exposes a clear protocol surface: `session.open`, `turn.start`, `turn.end`, `events.notify`, and `logs.forward` are the documented JSON-RPC methods. The OpenClaw side mirrors this pattern but speaks the OpenClaw lifecycle hooks directly instead of Python's `MemoryProvider`. Source: [apps/memos-local-plugin/adapters/hermes/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/adapters/hermes/README.md). ```mermaid flowchart LR subgraph Agents H[Hermes Agent
Python] O[OpenClaw
Gateway] end subgraph Local Plugin Core TS[memos-local-plugin
TypeScript core
L1/L2/L3 + Skills] BR[node bridge.cts
JSON-RPC 2.0] end subgraph Storage SQL[(SQLite + FTS5
traces / policies /
skills / world model)] end H -- stdio JSON-RPC --> BR O -- openclaw hooks --> TS BR --> TS TS <--> SQL ``` The memos-local-openclaw-plugin is a simpler shape: it is declared in its own `package.json` as a Node `module` whose entry is `index.ts`, ships its own `skill/memos-memory-guide`, and registers itself as the OpenClaw plugin id `memos-local-openclaw-plugin`. Source: [apps/memos-local-openclaw/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-openclaw/package.json). ## 3. Memory Layers and Algorithms The memos-local-plugin core organizes memory into three layers, plus a crystallized "Skill" tier: - **L1 traces** — episodic records of user/assistant turns and tool calls. The retrieval layer indexes two vector columns per trace: `vec_summary` (semantic recall on what was said) and `vec_action` (semantic recall on the agent's action/tool sequence). Source: [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md). - **L2 policies** — inductive guidance distilled from traces. The skill module documents that policies carry repair guidance inline via a compact `@repair {json}` tag inside `policy.boundary`, which the skill packager picks up on the next crystallization. Source: [apps/memos-local-plugin/core/skill/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md). - **L3 world model** — a longer-horizon model that participates in Tier-3 vector retrieval via `world_model.vec`. Source: [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md). - **Skills** — crystallized procedures. Each `SkillRow` contains `procedureJson`, an `invocationGuide` for the system prompt, a learned `eta` value, a `vec` embedding, and `sourcePolicyIds`. Lifecycle is driven by `applySkillFeedback`, with state transitions such as `probationary → active` on `trial.pass` and `any → retired` when `η` falls below `retireEta`. Source: [apps/memos-local-plugin/core/skill/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/skill/README.md). The `core/feedback` module adds a `decision_repairs` table that anchors repairs by `context_hash` and stores `preference` / `anti_pattern` guidance, with a `validated` flag gating downstream use. Source: [apps/memos-local-plugin/core/feedback/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/feedback/README.md). ## 4. Retrieval: Hybrid Channels with Reciprocal Rank Fusion The retrieval layer fuses multiple channels into a single ranking: | Channel | Source | Purpose | | --- | --- | --- | | `vec_summary` | traces cosine | Semantic recall on conversation content | | `vec_action` | traces cosine | Semantic recall on tool / action sequences | | `vec` | skills, world_model cosine | Tier-1 / Tier-3 semantic recall | | `fts` | FTS5 trigram MATCH | Keyword-precise hits, English + CJK ≥ 3 chars | | `pattern` | `LIKE %term%` (CJK bigrams + 2-char ASCII) | Short Chinese names/verbs below the trigram window | | `structural` | `instr(error_signatures_json, ...)` | Verbatim error-signature replay | The ranker applies Reciprocal Rank Fusion: a row confirmed by both vector and FTS gets a noticeably higher RRF than either channel alone. After RRF, an **adaptive relevance threshold** drops every candidate below `topRelevance · relativeThresholdFloor` (default `0.4`). Source: [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md). A known limitation surfaced by the community is that the built-in FTS5 tokenizer is weak for CJK: 2-character Chinese words fall below the 3-character trigram minimum, and mixed ASCII+CJK tokens misbehave. The community is tracking a "configurable FTS5 tokenizer for better CJK search" enhancement. Source: community issue #1961 (referenced in the conversation context). ## 5. LLM Layer and Configuration The `core/llm` module exposes one `LlmClient` facade with five real providers (`openai_compatible`, `anthropic`, `gemini`, `bedrock`, `host`) plus two sentinels (`local_only` always throws `LLM_UNAVAILABLE`). The `openai_compatible` provider supports both native JSON mode (`json_object`) and SSE streaming, and works with OpenAI, Azure, Zhipu, SiliconFlow, and Bailian. Source: [apps/memos-local-plugin/core/llm/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/llm/README.md). Every LLM-dependent algorithm step — reflection, reward scoring, induction, decision-repair, and skill crystallization — must go through this facade; providers are not exported outside `core/llm`. Source: [apps/memos-local-plugin/core/llm/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/llm/README.md). ## 6. Community Considerations and Known Gaps Several community threads target these plugins directly: - **Multi-agent isolation** — Issue #1361 reports that `patternSearch` in `memos-local-openclaw-plugin` v4.x was missing an `ownerFilter`, leaking memories across agents; this was partially addressed in v2.0.13 by scoping sharing state by `hubInstanceId` and fixing owner defaults. Sources: release notes for v2.0.13 and v2.0.12. - **Hardcoded owner** — Issue #1318 flagged that `memory_search` defaulted the owner to `agent:main` instead of the current agent, and issue #1433 requests self-hosted MemOS API support in the OpenClaw plugin. - **Local LLM providers** — Issue #1231 requests native `ollama` provider support for embedding and summarizer in `memos-local-openclaw` to enable truly local deployments. - **Hermes coverage** — Issue #1472 requests a dedicated Hermes Agent MCP plugin, while the current Hermes coverage comes from the JSON-RPC bridge in `adapters/hermes/`. Both plugins share the same MemOS plugin discovery mechanism used by the core server: plugins register under the `memos.plugins` entry-point group and are loaded by `PluginManager` at startup. Source: [src/memos/plugins/README.md](https://github.com/MemTensor/MemOS/blob/main/src/memos/plugins/README.md). ## See Also - [Plugin System (core)](./plugin-system.md) - [Memory Layers and Reflect2Evolve](./memory-layers-reflect2evolve.md) - [Hybrid Retrieval (FTS5 + Vector)](./hybrid-retrieval.md) - [LLM Provider Abstraction](./llm-providers.md) --- ## Deployment, Configuration, Evaluation, and Operations ### Related Pages Related topics: [MemOS Overview and Architecture](#page-1), [Core Memory System: MemCube, Textual/Activation/Parametric Memory, Scheduler and Retrieval](#page-2), [Local Plugins: memos-local-plugin and memos-local-openclaw for Hermes/OpenClaw](#page-3)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md) - [apps/memos-local-plugin/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/package.json) - [apps/memos-local-plugin/core/config/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/config/README.md) - [apps/memos-local-plugin/core/llm/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/llm/README.md) - [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md) - [apps/memos-local-plugin/core/feedback/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/feedback/README.md) - [apps/openwork-memos-integration/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/openwork-memos-integration/README.md) - [apps/openwork-memos-integration/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/openwork-memos-integration/package.json) - [apps/openwork-memos-integration/packages/shared/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/openwork-memos-integration/packages/shared/package.json)
# Deployment, Configuration, Evaluation, and Operations ## Overview MemOS is a memory operating system for large language models. Beyond its core memory APIs, the project ships a complete operational surface — multiple deployment modes, a layered configuration system, pluggable LLM and embedding providers, a desktop integration, and a local plugin aimed at agent runtimes. This page covers how those pieces fit together for operators and integrators. Source: [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md) ## Deployment Options MemOS supports four primary deployment paths: | Option | Description | |--------|-------------| | **Cloud API** | Hosted service at `memos.openmem.net` with dashboard key management | | **Self-Hosted** | Local/private deployment via Docker Compose | | **Quick Mode** | Lightweight in-process deployment for development | | **Full Mode** | Complete stack including scheduler, knowledge base, and graph memory | Source: [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md) The Cloud path issues API keys through the MemOS dashboard, while the self-hosted path installs from `docker/requirements.txt` and sources a `.env` file based on `docker/.env.example` or `docker/.env.example-full`. The recent addition of `memos-local-plugin 2.0` and the Hermes Agent local plugin means operators can now also deploy a fully local memory runtime with no cloud dependency. Source: [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md) ### Desktop Integration The `apps/openwork-memos-integration` workspace packages MemOS into a desktop agent ("Openwork") distributed as a macOS .dmg. It uses a pnpm monorepo with Next.js, React 19, and Node ≥ 20.0.0, exposing the local-first memory features through a desktop UI. Source: [apps/openwork-memos-integration/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/openwork-memos-integration/README.md), [apps/openwork-memos-integration/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/openwork-memos-integration/package.json) ## Configuration ### Local Plugin Config System The `memos-local-plugin` ships a YAML-driven config layer split across `reader.ts`, `writer.ts`, and `index.ts`. Notable behaviors: - First boot with no config file logs a warning and uses defaults so the agent's first turn still works. - Schema drift after upgrade keeps unknown keys verbatim and warns on removed keys, giving forward compatibility. - The writer always re-applies `chmod 600` after writes so the file never becomes world-readable. - `GET /api/config` redacts secret fields before returning to the browser; only the on-disk YAML holds raw values. Source: [apps/memos-local-plugin/core/config/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/config/README.md) ### Retrieval Knobs Every retrieval parameter lives under `algorithm.retrieval.*` in `config.yaml`. The user-facing template exposes only `tier1TopK`, `tier2TopK`, and `tier3TopK`; deeper settings (RRF weights, MMR seed, adaptive threshold floor, channel mix) are documented in `docs/CONFIG-ADVANCED.md` and default to safe values. Source: [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md) ### Environment Variables `.env.example-full` was added in v2.0.15 alongside a corrected `.env.example` to make first-run configuration less error-prone. Both are kept in the `docker/` directory at the project root. Source: [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md) ## LLM Provider Matrix The local plugin's LLM layer (`core/llm/`) is a single `LlmClient` facade backed by five real providers and two sentinels: | Provider | Native JSON | Native Stream | Notes | |----------|-------------|---------------|-------| | `openai_compatible` | yes (`json_object`) | yes (SSE) | OpenAI, Azure, Zhipu, SiliconFlow, Bailian | | `anthropic` | hint-based | yes (SSE) | Messages API | | `gemini` | yes (`responseMimeType`) | yes (SSE) | Google generateContent | | `bedrock` | hint-based | no | Converse API; SigV4 is caller's responsibility | | `host` | hint-based | faked | Delegates to host agent (OpenClaw) via `HostLlmBridge` | | `local_only` | — | — | Always throws `LLM_UNAVAILABLE`; explicit disable | Source: [apps/memos-local-plugin/core/llm/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/llm/README.md) The core MemOS server separately supports `openai`, `azure`, `qwen`, `deepseek`, `ollama`, and `huggingface` as chat model providers via `MOS_CHAT_MODEL_PROVIDER`. Community request #1231 tracks adding native `ollama` support to `memos-local-openclaw` for fully local embeddings and summarization. Source: [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md) ```mermaid flowchart LR A[User / Agent] --> B[MemOS API] B --> C{Deployment Mode} C -->|Cloud| D[memos.openmem.net] C -->|Self-Hosted| E[Docker Compose] C -->|Local Plugin| F[memos-local-plugin] F --> G[LlmClient] G --> H1[openai_compatible] G --> H2[anthropic] G --> H3[gemini] G --> H4[bedrock] G --> H5[host bridge] F --> I[YAML Config + chmod 600] F --> J[SQLite + FTS5] I --> K[algorithm.retrieval.*] ``` ## Operations ### Build, Test, and Install Scripts The local plugin defines a complete dev workflow in its `package.json`: - `build` — TypeScript compile + runtime asset copy - `build:viewer` — Vite viewer bundle - `dev` — `tsc --watch` for the TS layer - `bridge` / `bridge:daemon` — local bridge entry points - `test`, `test:unit`, `test:integration`, `test:e2e` — Vitest suites - `postinstall` — `node scripts/postinstall.cjs` runs after install Source: [apps/memos-local-plugin/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/package.json) The desktop integration uses pnpm workspaces with `dev`, `build`, `build:desktop`, `lint`, `typecheck`, and `clean` scripts, pinning `pnpm@9.15.0`. Source: [apps/openwork-memos-integration/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/openwork-memos-integration/package.json) ### Windows Installation `v2.0.17` enhanced the Windows installation experience for the local plugin, addressing a Windows path bug that surfaced in `v2.0.11` (`fix: fix windows dir error`). The `.ps1` install script and the package's `install.sh` / `install.ps1` assets are shipped to support both POSIX and Windows shells. Source: [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md), [apps/memos-local-plugin/package.json](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/package.json) ### Evaluation Surface LongMemEval is mentioned as the canonical evaluation harness, originally introduced alongside the v1.0.0 MemCube release. v2.0.19 added Chinese translations for the evaluation documentation. The feedback module exposes a testable pipeline (`runRepair`) with cooldown / skip / attach paths exercised by `tests/unit/feedback/feedback.integration.test.ts`, making it the de facto regression target for "did the memory update correctly?" semantics. Source: [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md), [apps/memos-local-plugin/core/feedback/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/feedback/README.md) ### Known Operational Risks Community-reported issues highlight several operational concerns operators should plan for: - **Multi-agent memory isolation** — `patternSearch` previously lacked an `ownerFilter`, leading to cross-agent leakage in `memos-local-openclaw-plugin v4.x` (Issue #1361, fixed in `v2.0.12` via `scope sharing state by hubInstanceId`). - **Hardcoded owner default** — `memory_search` defaulted to `agent:main` instead of the current agent (Issue #1318). - **CJK search quality** — FTS5's default trigram tokenizer misses 2-char Chinese words; a configurable tokenizer is tracked in Issue #1961. - **Self-hosted API parity** — Issue #1433 requests self-hosted MemOS API support inside the OpenClaw plugin. Source: community context (issues #1361, #1318, #1961, #1433) ## See Also - [README.md](https://github.com/MemTensor/MemOS/blob/main/README.md) — project overview, deployment table, LLM provider list - [apps/memos-local-plugin/core/config/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/config/README.md) — config layer semantics and security guarantees - [apps/memos-local-plugin/core/llm/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/llm/README.md) — provider matrix for the local plugin - [apps/memos-local-plugin/core/retrieval/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/retrieval/README.md) — retrieval configuration surface - [apps/memos-local-plugin/core/feedback/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/memos-local-plugin/core/feedback/README.md) — feedback pipeline and test layout - [apps/openwork-memos-integration/README.md](https://github.com/MemTensor/MemOS/blob/main/apps/openwork-memos-integration/README.md) — desktop deployment --- --- ## Pitfall Log Project: MemTensor/MemOS Summary: Found 10 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/MemTensor/MemOS/issues/1950 ## 2. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/MemTensor/MemOS ## 3. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/MemTensor/MemOS/issues/1966 ## 4. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/MemTensor/MemOS ## 5. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/MemTensor/MemOS ## 6. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/MemTensor/MemOS ## 7. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/MemTensor/MemOS ## 8. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/MemTensor/MemOS/issues/1961 ## 9. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/MemTensor/MemOS ## 10. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/MemTensor/MemOS