Related Pages

Related topics: Core Memory System: MemCube, Textual/Activation/Parametric Memory, Scheduler and Retrieval, Deployment, Configuration, Evaluation, and Operations

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, 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).

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

graph TB
  subgraph "Cloud Track"
    CloudAPI[MemOS Cloud API<br/>memos.openmem.net]
  end

  subgraph "Local Track"
    CorePy[MemOS Core · Python<br/>src/memos/*]
    Cube[MemCube<br/>composable KB units]
    PluginMgr[Plugin Manager<br/>entry-point discovery]
  end

  subgraph "Local Plugin · TypeScript"
    L1[L1 Traces<br/>episodes + tags]
    L2[L2 Policies<br/>cross-task induction]
    L3[L3 World Model<br/>abstractions]
    Skill[Skill Crystallization<br/>Tier-1 retrieval]
    Retrieval[Hybrid Retrieval<br/>vec + FTS5 + pattern]
    Feedback[Feedback + Decision Repair]
  end

  subgraph "Agent Adapters"
    OpenClaw[memos-local-openclaw<br/>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 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.

Local Plugin (`memos-local-plugin`)

The local track is a Node/TypeScript package declared in 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):

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.

The LLM layer (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, 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).
• Skills. Crystallized, prompt-ready procedures. Per 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, 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 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).

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.
• 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)

Related Pages

Related topics: MemOS Overview and Architecture, Local Plugins: memos-local-plugin and memos-local-openclaw for Hermes/OpenClaw, Deployment, Configuration, Evaluation, and Operations

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.

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.

flowchart TB
    User[User / Agent] --> API[MemOS API Layer]
    API --> View{SingleCubeView<br/>or CompositeCubeView}
    View --> TextMem[Textual Memory<br/>graph + tree]
    View --> ActMem[Activation Memory<br/>KV cache]
    View --> ParaMem[Parametric Memory<br/>LoRA]
    API --> Sched[MemScheduler<br/>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.

The legacy load path is GeneralMemCube.init_from_dir(<path>), 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.

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.

Three Memory Types

MemOS distinguishes three memory substrates, each tuned for a different access pattern:

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.

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.

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.

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.

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.

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.

The examples/mem_scheduler/ folder contains Redis-backed asynchronous memory workflow examples. Source: examples/README.md:13-13.

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.

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.

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).
• 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) and a hardcoded agent:main default (#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.

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.

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 and apps/memos-local-plugin/core/feedback/README.md:11-22.

See Also

• README.md — project overview, deployment options, and release history.
• src/memos/plugins/README.md — plugin architecture and Hook runtime.
• examples/README.md — runnable examples for mem_cube, mem_scheduler, mem_reader, mem_chat, and mem_mcp.
• apps/memos-local-plugin/README.md — Reflect2Evolve layered memory (L1/L2/L3 + Skills).
• Release v2.0.20 — search pipeline hooks for context rendering.

Related Pages

Related topics: MemOS Overview and Architecture, Core Memory System: MemCube, Textual/Activation/Parametric Memory, Scheduler and Retrieval

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

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.

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.

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.

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.

flowchart LR
    subgraph Agents
        H[Hermes Agent<br/>Python]
        O[OpenClaw<br/>Gateway]
    end
    subgraph Local Plugin Core
        TS[memos-local-plugin<br/>TypeScript core<br/>L1/L2/L3 + Skills]
        BR[node bridge.cts<br/>JSON-RPC 2.0]
    end
    subgraph Storage
        SQL[(SQLite + FTS5<br/>traces / policies /<br/>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.

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

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.

4. Retrieval: Hybrid Channels with Reciprocal Rank Fusion

The retrieval layer fuses multiple channels into a single ranking:

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.

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.

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.

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.

See Also

• Plugin System (core)
• Memory Layers and Reflect2Evolve
• Hybrid Retrieval (FTS5 + Vector)
• LLM Provider Abstraction

Related Pages

Related topics: MemOS Overview and Architecture, Core Memory System: MemCube, Textual/Activation/Parametric Memory, Scheduler and Retrieval, Local Plugins: memos-local-plugin and memos-local-openclaw for Hermes/OpenClaw

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

Deployment Options

MemOS supports four primary deployment paths:

Source: 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

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, 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

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

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

LLM Provider Matrix

The local plugin's LLM layer (core/llm/) is a single LlmClient facade backed by five real providers and two sentinels:

Source: 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

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

The desktop integration uses pnpm workspaces with dev, build, build:desktop, lint, typecheck, and clean scripts, pinning [email protected]. Source: 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, 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, 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 — project overview, deployment table, LLM provider list
• apps/memos-local-plugin/core/config/README.md — config layer semantics and security guarantees
• apps/memos-local-plugin/core/llm/README.md — provider matrix for the local plugin
• apps/memos-local-plugin/core/retrieval/README.md — retrieval configuration surface
• apps/memos-local-plugin/core/feedback/README.md — feedback pipeline and test layout
• apps/openwork-memos-integration/README.md — desktop deployment

Doramagic Pitfall Log

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
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/MemTensor/MemOS/issues/1950

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/MemTensor/MemOS

3. Configuration risk: Configuration risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/MemTensor/MemOS/issues/1966

4. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/MemTensor/MemOS

5. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/MemTensor/MemOS

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/MemTensor/MemOS

7. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/MemTensor/MemOS

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/MemTensor/MemOS/issues/1961

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/MemTensor/MemOS

10. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/MemTensor/MemOS

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using MemOS with real data or production workflows.

• bug: ghost trace in episode.trace_ids_json causes infinite rescore loop - github / github_issue
• feat: support configurable FTS5 tokenizer for better CJK search - github / github_issue
• fix: - github / github_issue
• Release v2.0.20 - github / github_release
• Release v2.0.19 - github / github_release
• Release v2.0.17 - github / github_release
• Release v2.0.16 - github / github_release
• Release v2.0.15 - github / github_release
• Release v2.0.14 - github / github_release
• Release v2.0.13 - github / github_release
• Release v2.0.12 - github / github_release
• Release v2.0.11 - github / github_release