# memtensor/memos architecture

> Architecture diagram of the GitHub repository memtensor/memos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/memtensor/memos
- Repository: https://github.com/memtensor/memos

## Overview

MemOS is a memory system for LLM agents, offered as a hosted API, self-hosted service, and agent plugins. The main workflow accepts agent or application memory operations, searches or updates memory, and returns context; asynchronous ingestion and memory evolution add background stages. The graph also preserves the documented multi-cube, feedback, multimodal, and skill capabilities. Some subsystem links reflect README descriptions and the file tree rather than inspected implementations, so uncertain internal wiring is omitted.

Main entry points: [`src/memos/api/handlers/search_handler.py`](https://github.com/memtensor/memos/blob/main/src/memos/api/handlers/search_handler.py) (Memory API), [`apps/memos-local-plugin/bridge.mts`](https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/bridge.mts) (Local plugins), [`apps/memos-local-plugin/core/storage/index.ts`](https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/storage/index.ts) (Memory storage), [`apps/memos-local-plugin/core/capture/capture.ts`](https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/capture/capture.ts) (Experience capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_api["Memory API<br/>[search_handler.py]"]
  node_cloud_plugin["Cloud plugin<br/>[index.js]"]
  node_local_plugin["Local plugins<br/>[bridge.mts]"]
  node_openclaw_local["OpenClaw local<br/>[index.ts]"]
  node_viewer["Memory viewer<br/>[App.tsx]"]
end

subgraph group_memory["Memory lifecycle"]
  node_ingest["Memory ingestion<br/>[query_handler.py]"]
  node_search["Memory search<br/>[search_pipeline.py]"]
  node_recall["Local recall<br/>[retrieve.ts]"]
  node_capture["Experience capture<br/>[capture.ts]"]
  node_session["Sessions and episodes<br/>[manager.ts]"]
end

subgraph group_evolution["Learning and sharing"]
  node_enhance["Memory enhancement"]
  node_feedback["Feedback learning<br/>[feedback.ts]"]
  node_skills["Evolving skills<br/>[skill.ts]"]
  node_world["World models<br/>[l3.ts]"]
end

subgraph group_platform["Service and state"]
  node_storage[("Memory storage<br/>[index.ts]")]
  node_user_cube[("Users and cubes")]
  node_scheduler["Async scheduler<br/>[query_handler.py]"]
  node_hub["Memory hub<br/>[server.ts]"]
end

node_app(("Applications"))
node_agents(("AI agents"))
node_external_llm(("LLM providers"))

node_app -->|"memory requests"| node_api
node_api -->|"searches memories"| node_search
node_search -->|"returns results"| node_api
node_api -->|"checks user and cube"| node_user_cube
node_agents -->|"uses hosted memory"| node_cloud_plugin
node_cloud_plugin -->|"calls cloud API"| node_api
node_agents -->|"uses local memory"| node_local_plugin
node_agents -->|"uses local memory"| node_openclaw_local
node_local_plugin -->|"manages episodes"| node_session
node_session -->|"persists session state"| node_storage
node_local_plugin -->|"captures experience"| node_capture
node_capture -->|"stores memories"| node_storage
node_local_plugin -->|"retrieves context"| node_recall
node_recall -->|"searches memory"| node_storage
node_api -->|"submits async work"| node_scheduler
node_scheduler -->|"dispatches messages"| node_ingest
node_ingest -.->|"enhances memories"| node_enhance
node_agents -->|"corrects memory"| node_feedback
node_feedback -->|"updates memory"| node_storage
node_capture -.->|"supports skill evolution"| node_skills
node_capture -.->|"supports abstraction"| node_world
node_local_plugin -.->|"shares memory"| node_hub
node_viewer -->|"inspects memory"| node_storage
node_enhance -.->|"prompts enhancement"| node_external_llm
node_recall -.->|"judges relevance"| node_external_llm

click node_api "https://github.com/memtensor/memos/blob/main/src/memos/api/handlers/search_handler.py"
click node_cloud_plugin "https://github.com/memtensor/memos/blob/main/apps/MemOS-Cloud-OpenClaw-Plugin/index.js"
click node_local_plugin "https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/bridge.mts"
click node_openclaw_local "https://github.com/memtensor/memos/blob/main/apps/memos-local-openclaw/src/index.ts"
click node_ingest "https://github.com/memtensor/memos/blob/main/src/memos/mem_scheduler/task_schedule_modules/handlers/query_handler.py"
click node_search "https://github.com/memtensor/memos/blob/main/src/memos/mem_scheduler/memory_manage_modules/search_pipeline.py"
click node_recall "https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/retrieval/retrieve.ts"
click node_capture "https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/capture/capture.ts"
click node_session "https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/session/manager.ts"
click node_storage "https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/storage/index.ts"
click node_user_cube "https://github.com/memtensor/memos/blob/main/src/memos/mem_user/mysql_user_manager.py"
click node_scheduler "https://github.com/memtensor/memos/blob/main/src/memos/mem_scheduler/task_schedule_modules/handlers/query_handler.py"
click node_enhance "https://github.com/memtensor/memos/blob/main/src/memos/mem_scheduler/memory_manage_modules/enhancement_pipeline.py"
click node_feedback "https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/feedback/feedback.ts"
click node_skills "https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/skill/skill.ts"
click node_world "https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/memory/l3/l3.ts"
click node_hub "https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/hub/server.ts"
click node_viewer "https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/viewer/src/components/App.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_cloud_plugin,node_local_plugin,node_openclaw_local,node_viewer toneBlue
class node_ingest,node_search,node_recall,node_capture,node_session toneAmber
class node_enhance,node_feedback,node_skills,node_world toneMint
class node_storage,node_user_cube,node_scheduler,node_hub toneRose
class node_app,node_agents,node_external_llm toneIndigo
```

## Components

### Interfaces

- [Memory API](https://github.com/memtensor/memos/blob/main/src/memos/api/handlers/search_handler.py): `src/memos/api/handlers/search_handler.py`
- [Cloud plugin](https://github.com/memtensor/memos/blob/main/apps/MemOS-Cloud-OpenClaw-Plugin/index.js): `apps/MemOS-Cloud-OpenClaw-Plugin/index.js`
- [Local plugins](https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/bridge.mts): `apps/memos-local-plugin/bridge.mts`
- [OpenClaw local](https://github.com/memtensor/memos/blob/main/apps/memos-local-openclaw/src/index.ts): `apps/memos-local-openclaw/src/index.ts`
- [Memory viewer](https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/viewer/src/components/App.tsx): `apps/memos-local-plugin/viewer/src/components/App.tsx`

### Memory lifecycle

- [Memory ingestion](https://github.com/memtensor/memos/blob/main/src/memos/mem_scheduler/task_schedule_modules/handlers/query_handler.py): `src/memos/mem_scheduler/task_schedule_modules/handlers/query_handler.py`
- [Memory search](https://github.com/memtensor/memos/blob/main/src/memos/mem_scheduler/memory_manage_modules/search_pipeline.py): `src/memos/mem_scheduler/memory_manage_modules/search_pipeline.py`
- [Local recall](https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/retrieval/retrieve.ts): `apps/memos-local-plugin/core/retrieval/retrieve.ts`
- [Experience capture](https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/capture/capture.ts): `apps/memos-local-plugin/core/capture/capture.ts`
- [Sessions and episodes](https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/session/manager.ts): `apps/memos-local-plugin/core/session/manager.ts`

### Learning and sharing

- [Memory enhancement](https://github.com/memtensor/memos/blob/main/src/memos/mem_scheduler/memory_manage_modules/enhancement_pipeline.py): `src/memos/mem_scheduler/memory_manage_modules/enhancement_pipeline.py`
- [Feedback learning](https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/feedback/feedback.ts): `apps/memos-local-plugin/core/feedback/feedback.ts`
- [Evolving skills](https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/skill/skill.ts): `apps/memos-local-plugin/core/skill/skill.ts`
- [World models](https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/memory/l3/l3.ts): `apps/memos-local-plugin/core/memory/l3/l3.ts`

### Service and state

- [Memory storage](https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/storage/index.ts): `apps/memos-local-plugin/core/storage/index.ts`
- [Users and cubes](https://github.com/memtensor/memos/blob/main/src/memos/mem_user/mysql_user_manager.py): `src/memos/mem_user/mysql_user_manager.py`
- [Async scheduler](https://github.com/memtensor/memos/blob/main/src/memos/mem_scheduler/task_schedule_modules/handlers/query_handler.py): `src/memos/mem_scheduler/task_schedule_modules/handlers/query_handler.py`
- [Memory hub](https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/hub/server.ts): `apps/memos-local-plugin/core/hub/server.ts`

### Other components

- **Applications**
- **AI agents**
- **LLM providers**

## Connections

- Applications → Memory API: memory requests
- Memory API → Memory search: searches memories
- Memory search → Memory API: returns results
- Memory API → Users and cubes: checks user and cube
- AI agents → Cloud plugin: uses hosted memory
- Cloud plugin → Memory API: calls cloud API
- AI agents → Local plugins: uses local memory
- AI agents → OpenClaw local: uses local memory
- Local plugins → Sessions and episodes: manages episodes
- Sessions and episodes → Memory storage: persists session state
- Local plugins → Experience capture: captures experience
- Experience capture → Memory storage: stores memories
- Local plugins → Local recall: retrieves context
- Local recall → Memory storage: searches memory
- Memory API → Async scheduler: submits async work
- Async scheduler → Memory ingestion: dispatches messages
- Memory ingestion → Memory enhancement: enhances memories
- AI agents → Feedback learning: corrects memory
- Feedback learning → Memory storage: updates memory
- Experience capture → Evolving skills: supports skill evolution
- Experience capture → World models: supports abstraction
- Local plugins → Memory hub: shares memory
- Memory viewer → Memory storage: inspects memory
- Memory enhancement → LLM providers: prompts enhancement
- Local recall → LLM providers: judges relevance