MemTensor/MemOS

Overview

MemOS (“Memory Operating System”) from MemTensor is two products in one repository, and they share no code.

The first is the Python service in src/memos (PyPI MemoryOS, import memos). It is a FastAPI server that turns chat messages into memory items with LLM prompts, stores them as nodes in a graph database (Neo4j, Neo4j Community + Qdrant, PolarDB, Postgres or NebulaGraph) with embeddings, and searches them through several parallel recall paths. The memories are typed: long-term facts, user memories, preferences, tool traces, skills and raw-file chunks. A scheduler does the expensive LLM extraction in the background. The library also contains the older MOS/GeneralMemCube API and the KV-cache and LoRA “activation” and “parametric” memory types from the MemOS paper. The REST server does not wire up those two types.

The second is apps/memos-local-plugin, a TypeScript package (the largest code base in the repo, and why GitHub reports the project as TypeScript). It is a local-first memory plugin for OpenClaw, Hermes Agent and DeepSeek Harness, built on one SQLite file. It records step-level traces, gives them value with a reward signal, induces policies and “world models”, and crystallizes skills. The README’s newer claims (“self-evolving”, skill reuse) describe this plugin, not the Python server.

This overview follows the Python service in detail and covers the plugin in its own section.

Architecture

flowchart LR
  C["Client / agent"] --> API["FastAPI server_api"]
  API --> ADD["AddHandler"]
  API --> SRCH["SearchHandler"]
  ADD --> VIEW["SingleCubeView / CompositeCubeView"]
  SRCH --> VIEW
  VIEW --> READER["MultiModalStructMemReader"]
  READER --> LLM["Extraction LLM"]
  VIEW --> TREE["SimpleTreeTextMemory"]
  TREE --> MGR["MemoryManager"]
  MGR --> GDB["Graph DB + vectors"]
  VIEW --> SCHED["MemScheduler (local or Redis queue)"]
  SCHED --> READER
  SCHED --> TREE
  TREE --> SEARCHER["Searcher: parallel paths"]
  SEARCHER --> GDB
  SEARCHER --> NET["Internet retriever"]

Component	Path	Role
REST app	src/memos/api/server_api.py, api/routers/server_router.py	/product/add, /product/search, chat, feedback, delete, scheduler status
Component wiring	src/memos/api/handlers/component_init.py	Builds the graph DB, LLMs, embedder, reader, text memory, searcher, feedback and scheduler from env config
Cube views	src/memos/multi_mem_cube/	Per-cube add and search. A cube id defaults to the user id
Mem reader	src/memos/mem_reader/multi_modal_struct.py	Parses messages and files into chunks (fast) or LLM-extracted memories (fine)
Tree text memory	src/memos/memories/textual/tree.py, tree_text_memory/	Graph-backed memory: manager, reorganizer, searcher, recall, reranker
Graph stores	src/memos/graph_dbs/	Neo4j, Neo4j Community, PolarDB, Postgres, NebulaGraph backends
Scheduler	src/memos/mem_scheduler/	Task queue and handlers (mem_read, add, feedback, organize)
Plugins	src/memos/plugins/	Hook registry. Some hooks, such as memory versioning, have no implementation in the repo
Local plugin	apps/memos-local-plugin/	Separate TS memory engine with SQLite, three-tier retrieval and skills

How a request flows

A self-hosted POST /product/add followed by POST /product/search:

1. Startup. server_router calls handlers.init_server() at import time. That builds every component once: graph DB, LLMs, embedder, MultiModalStructMemReader, SimpleTreeTextMemory, Searcher, SimpleMemFeedback and the scheduler (component_init.py). The ASGI app is memos.api.server_api:app (server_api.py).
2. Route. /product/add goes to AddHandler.handle_add_memories, which builds a SingleCubeView per writable cube (default: the user id) (add_handler.py).
3. Fast write. async_mode defaults to "async" (product_models.py). In async mode the reader runs in fast mode: messages are parsed and windowed into raw chunks with no LLM call, then written to the graph straight away (single_cube.py, multi_modal_struct.py).
4. Schedule. _schedule_memory_tasks submits a mem_read message with the new ids to the scheduler (single_cube.py). The HTTP call returns.
5. Fine extraction. The mem_read handler loads the raw chunks and calls fine_transfer_simple_mem. It adds the resulting memories, then hard-deletes the raw chunks and their working-memory bindings (mem_read_handler.py, L395-L425). Fine mode runs four extractors in parallel: facts, tool trajectories, skills and preferences (multi_modal_struct.py).
6. Store. MemoryManager._add_memories_batch writes nodes to the graph store in batches of 5. It queues them for the reorganizer only when reorganize is enabled (manager.py).
7. Search. /product/search defaults to mode=fast and top_k=10. SingleCubeView dispatches to fast, fine or mixture search (single_cube.py). Searcher._retrieve_paths then runs working memory, long-term + user memory, internet and, when requested, keyword, tool, skill and preference paths in a thread pool (searcher.py).
8. Return. Results are reranked, deduplicated, trimmed to top_k and grouped by type (text_mem, pref_mem, tool_mem, skill_mem). The search endpoint only returns memories. Prompt injection happens in the chat endpoints or in the caller.

Key components

Two-stage ingestion

The fast/fine split is the central design choice. A write is visible to search almost immediately as raw chunks, and quality improves later when the scheduler swaps the chunks for extracted memories. The price is a window in which search returns raw text. If the scheduler is behind or down, those chunks stay. Synchronous callers can pass async_mode="sync" to get fine extraction inline.

Hybrid recall

For long-term and user memory, GraphMemoryRetriever.retrieve runs graph recall (by parsed keys and tags) and vector recall in parallel, and optionally BM25 and full-text recall. It merges them by node id (recall.py). Graph recall keeps nodes whose key matches a parsed key or whose tags overlap the query’s by at least two. Working memory is read in full rather than searched. Query expansion via chain-of-thought sub-queries is also optional (searcher.py). In the server’s default config, BM25, CoT, full-text and fast-graph are all off (env flags BM25_CALL, VEC_COT_CALL, FULLTEXT_CALL, FAST_GRAPH), so out of the box this is graph + vector recall plus a reranker (config.py).

Organization and lifecycle

MemoryManager keeps per-type capacities. The library defaults are 20 working, 1500 long-term and 480 user memories, and the server raises long-term and user to 1e6 (manager.py). A sync add trims working memory to its limit. Conflict handling, where NodeHandler detects contradictory or redundant pairs and merges them with an LLM, lives in GraphStructureReorganizer. That reorganizer only runs its threads when MOS_ENABLE_REORGANIZE=true (reorganizer.py, L185-L210). The default server therefore does not resolve contradictions. The memory-version pipeline in the reader is a plugin hook with no implementation in this repo.

Feedback

/product/feedback, or /product/add with is_feedback, sends a natural-language correction to SimpleMemFeedback. It uses the searcher and an LLM to edit or replace existing memories, synchronously or as a scheduler task.

The local plugin (TypeScript)

apps/memos-local-plugin/core is a separate engine. Storage is a better-sqlite3 database with float32 vector BLOBs and brute-force cosine search in JS (vector.ts). At turn start it retrieves from three tiers in parallel: skills, then traces and episodes, then world models (retrieve.ts). A task-level reward is back-propagated along a trace as a discounted value with exponential time decay. This value sets which traces surface, and which crystallize into skills (backprop.ts). Adapters run it in-process (OpenClaw, DeepSeek Harness) or over a JSON-RPC bridge (Hermes), with a local HTTP viewer.

Extending it

• Providers. Each category (LLM, embedder, vector DB, graph DB, chunker, reranker, memory, scheduler) follows the same pattern: a base.py class, a pydantic config in configs/, and an entry in the factory’s backend_to_class.
• Plugins. memos.plugins discovers plugins at startup and lets them register components and hooks around add, search and the dream pipeline. Handlers are decorated with @hookable.
• Cubes. writable_cube_ids and readable_cube_ids fan one request out to several cubes, which is how shared and per-user memory are combined.
• Library use. MOS / GeneralMemCube still offer add, search and chat in-process, and the FastMCP server in api/mcp_serve.py wraps that MOS API.

Running it

• Docker. docker/docker-compose.yml starts the API, Neo4j 5.26 and Qdrant. Copy docker/.env.example, set LLM and embedder keys, then docker compose up. The default graph backend is neo4j-community, with vectors in Qdrant.
• Local. make install (Poetry, all extras), then make serve (uvicorn memos.api.server_api:app). Redis is optional and enables the Redis-stream scheduler queue. A SQLite file backs scheduler bookkeeping.
• Required. An OpenAI-compatible LLM (or Ollama, vLLM, Qwen, DeepSeek), an embedder, and one supported graph store. Internet retrieval needs a Tavily, Bocha or Xinyu key and runs only when a search request sets internet_search.
• Local plugin. install.sh for OpenClaw/Hermes, or dsh plugin for DeepSeek Harness. It needs Node.js and an LLM/embedding provider, and no server.

Strengths and caveats

• Strength: rich memory model. Typed memories (facts, user, preference, tool, skill, raw file) with sources, tags, status and history are far more structured than a flat fact list.
• Strength: write latency. The fast-then-fine pipeline keeps /add cheap and moves LLM work to a queue that can scale out on Redis.
• Strength: pluggable everywhere. Five graph backends, two vector DBs and ten LLM backends sit behind uniform factories.
• Caveat: heavy and sprawling. The default server needs a graph DB, a vector DB, several LLM roles and many env flags. Code paths (MOS, cube views, scheduler, plugins) overlap, and many features are off by default.
• Caveat: contradiction handling is opt-in. Without the reorganizer, new facts are added next to old ones. Nothing merges or retires them.
• Caveat: two unrelated engines. Benchmarks and “self-evolving” claims cannot be attributed to one code path without checking which product was measured. The TS plugin’s memory does not interoperate with the Python server’s graph.

Sources: code at a7367d0, deepwiki-open wiki (12 pages), OpenDeepWiki wiki (27 pages), verified Q&A.