# morpheusais/morpheus architecture

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

- Interactive diagram: https://gitdiagram.com/morpheusais/morpheus
- Repository: https://github.com/morpheusais/morpheus

## Overview

1. **What this repo is**
   - Morpheus is a **desktop smart-agent client**: a local app that combines a UI, a local LLM runtime, document retrieval, and wallet/chain actions.
   - The README frames the key use case as chatting with an agent that can answer wallet questions and execute Ethereum transactions after user approval.

2. **Top-level application boundary**
   - The root of the repo looks like the **main Electron app**: `main.js`, `preload.js`, `src/index.js`, `src/index.html`, and `src/index.css`.
   - That shell is the boundary between the renderer UI and privileged local capabilities exposed through preload/IPC.

3. **Local LLM subsystem**
   - `src/service/ollama/ollama.js` and `modules/ollama-manager.js` show the model layer is built around **Ollama**.
   - This is the inference runtime used by the agent, with the README noting the default model is Llama2.
   - The `ui/ollama-manager.js` and the separate `ui/` package suggest there is also a smaller UI/client variant that reuses the same local model-management idea.

4. **Agent orchestration layer**
   - `src/agent/app.js`, `src/agent/Prompts/limitlessprompt.txt`, and `src/agent/memory.txt` indicate the agent has a **prompt/memory-driven orchestration layer**.
   - `src/agent/certificates/` suggests support material for trust/authentication or agent-specific credentials.
   - This is where user intent is turned into LLM calls and downstream tool actions.

5. **Document/RAG pipeline**
   - `src/service/document/parse/*` supports ingesting multiple file types: PDF, DOCX, HTML, Markdown, ODT, TXT.
   - `src/service/document/parse/clean.js` normalizes extracted text before downstream use.
   - `src/service/embedding.js` and `src/service/vector.js` indicate a **retrieval/embedding pipeline**: parse documents → clean text → embed/index → query for context.

6. **Wallet and transaction subsystem**
   - The README emphasizes MetaMask-based interaction, especially “What is my balance?”, “What is my address?”, and “Send ETH to Ethereum Address.”
   - That implies a hard boundary: the agent can propose actions, but **MetaMask remains the approval gate** before funds move.
   - The repo does not show a full chain indexer or price oracle; the wallet flow appears intentionally narrow and approval-centric.

7. **MetaMask agent subproject**
   - `src/agent/metamask-agent/` is a nested application with its own **backend and frontend**.
   - Backend: Python (`backend/main.py`, `agents/metamask.py`, `utils/functions.py`, `requirements.txt`) likely implements agent logic and tool functions.
   - Frontend: Vue/Electron (`frontend/src/renderer/*`, `frontend/src/background/*`, `dist_electron/*`) provides the chat UI and wallet interaction surface.
   - This subproject is a distinct boundary from the root Electron app: it looks like a self-contained wallet-agent client.

8. **Cross-runtime integration**
   - The Metamask agent frontend has Electron background code (`src/background/background.js`, `metamask-sdk.js`, `sdk.js`) that likely bridges UI events to wallet SDK calls.
   - The Python backend and Electron frontend imply an **IPC or local-process bridge** between JavaScript UI and Python agent execution.
   - This is an important diagram boundary because it separates UI, orchestration, and the wallet SDK layer.

9. **Smart contract development and deployment**
   - `contract_library/` is a separate **Hardhat + TypeScript** project for Ethereum contracts.
   - It contains contracts, tests, and deployment scripts (`scripts/deploy.ts`, `test/Lock.ts`, `hardhat.config.ts`).
   - This subsystem is not the runtime agent itself; it is the on-chain contract authoring/deployment side of the ecosystem.

10. **Static chain/DEX configuration**
   - `public/data/*.json` includes `uniswap.json`, `sushiswap.json`, `pancakeswap.json`, `1inch.json`, `router.json`, and `dex.json`.
   - These look like **static integration/config assets** for DEX routing or chain interaction logic, likely consumed by the agent or UI rather than fetched dynamically.

11. **Packaging and release structure**
   - `build_scripts/`, `forge.config.js`, `build/`, and the macOS/Linux/Windows assets in `public/` point to a **desktop packaging pipeline**.
   - The repo contains platform-specific release artifacts and signing/entitlement configuration, which matter for understanding distribution but not core runtime flow.

12. **Legacy/alternate UI**
   - The standalone `ui/` directory contains its own `index.html`, `chat.js`, `background.js`, `settings.js`, and packaging helpers.
   - This appears to be an **alternate or earlier client shell** around the same agent/ollama concepts, useful to treat as a parallel UI boundary rather than the main architecture.

13. **Overall data flow**
   - Typical flow is: user input in desktop UI → preload/background bridge → agent orchestration → Ollama model and/or document retrieval → optional tool action.
   - For wallet actions, the flow continues through the MetaMask agent layer → MetaMask approval UI → on-chain transaction.
   - For knowledge tasks, the flow goes through document parsing/embedding/vector retrieval before the LLM responds.

14. **How to diagram the repo**
   - Draw three main planes: **desktop client/UI**, **local AI + retrieval services**, and **wallet/on-chain integration**.
   - Put the **Metamask agent subproject** as a separate nested service with its own frontend/backend split.
   - Put **contract_library** as a separate build/deploy lane connected to Ethereum, not to the local chat loop.

Main entry points: [`src/agent/app.js`](https://github.com/morpheusais/morpheus/blob/main/src/agent/app.js) (Agent core), [`src/agent/metamask-agent/backend/main.py`](https://github.com/morpheusais/morpheus/blob/main/src/agent/metamask-agent/backend/main.py) (Agent backend), [`src/index.js`](https://github.com/morpheusais/morpheus/blob/main/src/index.js) (Renderer UI), [`main.js`](https://github.com/morpheusais/morpheus/blob/main/main.js) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_desktop["Desktop client"]
  node_main_shell["App shell<br/>electron app<br/>[main.js]"]
  node_preload_bridge["Preload<br/>ipc bridge<br/>[preload.js]"]
  node_renderer_ui["Renderer UI<br/>ui entry<br/>[index.js]"]
  node_ui_assets["UI assets<br/>html/css<br/>[index.html]"]
  node_alt_ui["Legacy UI<br/>alternate client<br/>[index.html]"]
  node_alt_ui_logic["UI logic<br/>client scripts<br/>[chat.js]"]
end

subgraph group_group_ai["AI + retrieval"]
  node_agent_core["Agent core<br/>orchestrator<br/>[app.js]"]
  node_agent_prompt["System prompt"]
  node_agent_memory["Memory<br/>state<br/>[memory.txt]"]
  node_ollama_runtime["Ollama<br/>model runtime<br/>[ollama.js]"]
  node_ollama_mgr["Model manager<br/>model control<br/>[ollama-manager.js]"]
  node_doc_ingest["Document ingest<br/>parser pipeline<br/>[index.js]"]
  node_doc_reader["Reader<br/>document IO<br/>[reader.js]"]
  node_embed_index["Embeddings<br/>vector pipeline<br/>[embedding.js]"]
  node_vector_store[("Vector store<br/>retrieval index<br/>[vector.js]")]
end

subgraph group_group_wallet["Wallet integration"]
  node_wallet_frontend["Wallet UI<br/>frontend app<br/>[App.vue]"]
  node_wallet_background["Wallet bridge<br/>electron background<br/>[background.js]"]
  node_wallet_backend["Agent backend<br/>python service<br/>[main.py]"]
  node_wallet_tools["Tool funcs<br/>python tools<br/>[functions.py]"]
  node_public_dex["DEX config<br/>static assets<br/>[dex.json]"]
end

subgraph group_group_contracts["Contracts"]
  node_contracts_root["Contract lib<br/>hardhat project<br/>[hardhat.config.ts]"]
  node_contracts_src["Contracts<br/>solidity"]
  node_deploy_scripts["Deploy<br/>ts scripts<br/>[deploy.ts]"]
end

node_main_shell -->|"ipc"| node_preload_bridge
node_main_shell -->|"loads"| node_renderer_ui
node_renderer_ui -->|"renders"| node_ui_assets
node_renderer_ui -->|"chat"| node_agent_core
node_agent_core -->|"infer"| node_ollama_runtime
node_ollama_mgr -->|"manage"| node_ollama_runtime
node_agent_core -->|"uses"| node_agent_prompt
node_agent_core -->|"reads/writes"| node_agent_memory
node_agent_core -->|"ingest"| node_doc_reader
node_doc_reader -->|"parses"| node_doc_ingest
node_doc_ingest -->|"normalizes"| node_embed_index
node_embed_index -->|"indexes"| node_vector_store
node_agent_core -->|"retrieves"| node_vector_store
node_alt_ui -->|"runs"| node_alt_ui_logic
node_alt_ui_logic -->|"connects"| node_agent_core
node_wallet_frontend -->|"bridges"| node_wallet_background
node_wallet_background -->|"calls"| node_wallet_backend
node_wallet_backend -->|"executes"| node_wallet_tools
node_wallet_backend -->|"uses"| node_public_dex
node_agent_core -->|"tooling"| node_wallet_backend
node_contracts_root -->|"contains"| node_contracts_src
node_contracts_root -->|"deploys"| node_deploy_scripts

click node_main_shell "https://github.com/morpheusais/morpheus/blob/main/main.js"
click node_preload_bridge "https://github.com/morpheusais/morpheus/blob/main/preload.js"
click node_renderer_ui "https://github.com/morpheusais/morpheus/blob/main/src/index.js"
click node_ui_assets "https://github.com/morpheusais/morpheus/blob/main/src/index.html"
click node_alt_ui "https://github.com/morpheusais/morpheus/blob/main/ui/index.html"
click node_alt_ui_logic "https://github.com/morpheusais/morpheus/blob/main/ui/chat.js"
click node_agent_core "https://github.com/morpheusais/morpheus/blob/main/src/agent/app.js"
click node_agent_prompt "https://github.com/morpheusais/morpheus/blob/main/src/agent/Prompts/limitlessprompt.txt"
click node_agent_memory "https://github.com/morpheusais/morpheus/blob/main/src/agent/memory.txt"
click node_ollama_runtime "https://github.com/morpheusais/morpheus/blob/main/src/service/ollama/ollama.js"
click node_ollama_mgr "https://github.com/morpheusais/morpheus/blob/main/modules/ollama-manager.js"
click node_doc_ingest "https://github.com/morpheusais/morpheus/blob/main/src/service/document/parse/index.js"
click node_doc_reader "https://github.com/morpheusais/morpheus/blob/main/src/service/document/reader.js"
click node_embed_index "https://github.com/morpheusais/morpheus/blob/main/src/service/embedding.js"
click node_vector_store "https://github.com/morpheusais/morpheus/blob/main/src/service/vector.js"
click node_wallet_frontend "https://github.com/morpheusais/morpheus/blob/main/src/agent/metamask-agent/frontend/src/renderer/App.vue"
click node_wallet_background "https://github.com/morpheusais/morpheus/blob/main/src/agent/metamask-agent/frontend/src/background/background.js"
click node_wallet_backend "https://github.com/morpheusais/morpheus/blob/main/src/agent/metamask-agent/backend/main.py"
click node_wallet_tools "https://github.com/morpheusais/morpheus/blob/main/src/agent/metamask-agent/backend/utils/functions.py"
click node_public_dex "https://github.com/morpheusais/morpheus/blob/main/public/data/dex.json"
click node_contracts_root "https://github.com/morpheusais/morpheus/blob/main/contract_library/hardhat.config.ts"
click node_contracts_src "https://github.com/morpheusais/morpheus/tree/main/contract_library/contracts"
click node_deploy_scripts "https://github.com/morpheusais/morpheus/blob/main/contract_library/scripts/deploy.ts"

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_main_shell,node_preload_bridge,node_renderer_ui,node_ui_assets,node_alt_ui,node_alt_ui_logic toneBlue
class node_agent_core,node_agent_prompt,node_agent_memory,node_ollama_runtime,node_ollama_mgr,node_doc_ingest,node_doc_reader,node_embed_index,node_vector_store toneAmber
class node_wallet_frontend,node_wallet_background,node_wallet_backend,node_wallet_tools,node_public_dex toneMint
class node_contracts_root,node_contracts_src,node_deploy_scripts toneRose
```

## Components

### Desktop client

Electron shell and alternate UI surfaces

- [App shell](https://github.com/morpheusais/morpheus/blob/main/main.js): electron app · Root Electron application boundary for the desktop client. · `main.js`
- [Preload](https://github.com/morpheusais/morpheus/blob/main/preload.js): ipc bridge · Privileged bridge between renderer and local capabilities. · `preload.js`
- [Renderer UI](https://github.com/morpheusais/morpheus/blob/main/src/index.js): ui entry · Main desktop interface for chat and interaction. · `src/index.js`
- [UI assets](https://github.com/morpheusais/morpheus/blob/main/src/index.html): html/css · Primary renderer markup and styling. · `src/index.html`
- [Legacy UI](https://github.com/morpheusais/morpheus/blob/main/ui/index.html): alternate client · Standalone UI shell around the same agent concepts. · `ui/index.html`
- [UI logic](https://github.com/morpheusais/morpheus/blob/main/ui/chat.js): client scripts · Legacy chat, settings, background, and local UI behavior. · `ui/chat.js`

### AI + retrieval

Local model runtime, prompts, and document retrieval

- [Agent core](https://github.com/morpheusais/morpheus/blob/main/src/agent/app.js): orchestrator · Prompt-driven agent orchestration and execution entrypoint. · `src/agent/app.js`
- [System prompt](https://github.com/morpheusais/morpheus/blob/main/src/agent/Prompts/limitlessprompt.txt): prompt · Primary prompt text steering agent behavior. · `src/agent/Prompts/limitlessprompt.txt`
- [Memory](https://github.com/morpheusais/morpheus/blob/main/src/agent/memory.txt): state · Persistent agent memory and working context. · `src/agent/memory.txt`
- [Ollama](https://github.com/morpheusais/morpheus/blob/main/src/service/ollama/ollama.js): model runtime · Local model inference layer used by the agent. · `src/service/ollama/ollama.js`
- [Model manager](https://github.com/morpheusais/morpheus/blob/main/modules/ollama-manager.js): model control · Shared Ollama configuration and model lifecycle management. · `modules/ollama-manager.js`
- [Document ingest](https://github.com/morpheusais/morpheus/blob/main/src/service/document/parse/index.js): parser pipeline · Multi-format document parsing and normalization pipeline. · `src/service/document/parse/index.js`
- [Reader](https://github.com/morpheusais/morpheus/blob/main/src/service/document/reader.js): document IO · Document loading and source reading boundary. · `src/service/document/reader.js`
- [Embeddings](https://github.com/morpheusais/morpheus/blob/main/src/service/embedding.js): vector pipeline · Embedding generation for retrieval and context lookup. · `src/service/embedding.js`
- [Vector store](https://github.com/morpheusais/morpheus/blob/main/src/service/vector.js): retrieval index · Queryable vector layer for retrieval-augmented responses. · `src/service/vector.js`

### Wallet integration

MetaMask agent boundary and transaction flow

- [Wallet UI](https://github.com/morpheusais/morpheus/blob/main/src/agent/metamask-agent/frontend/src/renderer/App.vue): frontend app · MetaMask agent frontend and interaction surface. · `src/agent/metamask-agent/frontend/src/renderer/App.vue`
- [Wallet bridge](https://github.com/morpheusais/morpheus/blob/main/src/agent/metamask-agent/frontend/src/background/background.js): electron background · Electron background layer that connects UI to wallet SDK calls. · `src/agent/metamask-agent/frontend/src/background/background.js`
- [Agent backend](https://github.com/morpheusais/morpheus/blob/main/src/agent/metamask-agent/backend/main.py): python service · Python backend that implements agent logic and tool execution. · `src/agent/metamask-agent/backend/main.py`
- [Tool funcs](https://github.com/morpheusais/morpheus/blob/main/src/agent/metamask-agent/backend/utils/functions.py): python tools · Backend functions and tool definitions for wallet actions. · `src/agent/metamask-agent/backend/utils/functions.py`
- [DEX config](https://github.com/morpheusais/morpheus/blob/main/public/data/dex.json): static assets · Static chain and DEX metadata used by wallet or agent flows. · `public/data/dex.json`

### Contracts

Hardhat contract development and deployment

- [Contract lib](https://github.com/morpheusais/morpheus/blob/main/contract_library/hardhat.config.ts): hardhat project · Ethereum contract authoring and deployment subproject. · `contract_library/hardhat.config.ts`
- [Contracts](https://github.com/morpheusais/morpheus/tree/main/contract_library/contracts): solidity · On-chain contract sources and tests for the Hardhat project. · `contract_library/contracts`
- [Deploy](https://github.com/morpheusais/morpheus/blob/main/contract_library/scripts/deploy.ts): ts scripts · Deployment and test scripts for contract workflows. · `contract_library/scripts/deploy.ts`

## Connections

- App shell → Preload: ipc · Renderer requests pass through preload for privileged access.
- App shell → Renderer UI: loads · Electron host loads the main renderer entry.
- Renderer UI → UI assets: renders · Main renderer uses the HTML/CSS asset bundle.
- Renderer UI → Agent core: chat · User interactions are routed into the agent orchestration layer.
- Agent core → Ollama: infer · Agent sends prompts to the local model runtime.
- Model manager → Ollama: manage · Model manager configures and supervises inference runtime.
- Agent core → System prompt: uses · Prompt template shapes agent behavior.
- Agent core → Memory: reads/writes · Agent retains conversational or working memory.
- Agent core → Reader: ingest · Agent pulls source documents for knowledge tasks.
- Reader → Document ingest: parses · Reader feeds multiple file types into the parser pipeline.
- Document ingest → Embeddings: normalizes · Clean text is prepared for embeddings and indexing.
- Embeddings → Vector store: indexes · Embeddings are stored for retrieval queries.
- Agent core → Vector store: retrieves · Agent queries indexed context during response generation.
- Legacy UI → UI logic: runs · Legacy client uses its own chat and background scripts.
- UI logic → Agent core: connects · Alternate UI also drives the same core agent concepts.
- Wallet UI → Wallet bridge: bridges · Frontend wallet actions are forwarded through the Electron background.
- Wallet bridge → Agent backend: calls · Background layer communicates with the Python backend.
- Agent backend → Tool funcs: executes · Backend delegates wallet-specific tool functions.
- Agent backend → DEX config: uses · Backend or UI may consume static DEX and chain configuration.
- Agent core → Agent backend: tooling · Agent can hand off wallet actions to the MetaMask agent boundary.
- Contract lib → Contracts: contains · Hardhat project contains Solidity contracts and tests.
- Contract lib → Deploy: deploys · Contract project includes deployment scripts.
