How morpheusais/morpheus works
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: app.js Agent core · main.py Agent backend · index.js Renderer UI · main.js App shell
Components 23
Desktop client
Electron shell and alternate UI surfaces
- App shell · Root Electron application boundary for the desktop client.
main.js - Preload · Privileged bridge between renderer and local capabilities.
preload.js - Renderer UI · Main desktop interface for chat and interaction.
src/index.js - UI assets · Primary renderer markup and styling.
src/index.html - Legacy UI · Standalone UI shell around the same agent concepts.
ui/index.html - UI logic · Legacy chat, settings, background, and local UI behavior.
ui/chat.js
AI + retrieval
Local model runtime, prompts, and document retrieval
- Agent core · Prompt-driven agent orchestration and execution entrypoint.
src/agent/app.js - System prompt · Primary prompt text steering agent behavior.
src/agent/Prompts/limitlessprompt.txt - Memory · Persistent agent memory and working context.
src/agent/memory.txt - Ollama · Local model inference layer used by the agent.
src/service/ollama/ollama.js - Model manager · Shared Ollama configuration and model lifecycle management.
modules/ollama-manager.js - Document ingest · Multi-format document parsing and normalization pipeline.
src/service/document/parse/index.js - Reader · Document loading and source reading boundary.
src/service/document/reader.js - Embeddings · Embedding generation for retrieval and context lookup.
src/service/embedding.js - Vector store · Queryable vector layer for retrieval-augmented responses.
src/service/vector.js
Wallet integration
MetaMask agent boundary and transaction flow
- Wallet UI · MetaMask agent frontend and interaction surface.
src/agent/metamask-agent/frontend/src/renderer/App.vue - Wallet bridge · Electron background layer that connects UI to wallet SDK calls.
src/agent/metamask-agent/frontend/src/background/background.js - Agent backend · Python backend that implements agent logic and tool execution.
src/agent/metamask-agent/backend/main.py - Tool funcs · Backend functions and tool definitions for wallet actions.
src/agent/metamask-agent/backend/utils/functions.py - DEX config · Static chain and DEX metadata used by wallet or agent flows.
public/data/dex.json
Contracts
Hardhat contract development and deployment
- Contract lib · Ethereum contract authoring and deployment subproject.
contract_library/hardhat.config.ts - Contracts · On-chain contract sources and tests for the Hardhat project.
contract_library/contracts - Deploy · Deployment and test scripts for contract workflows.
contract_library/scripts/deploy.ts
Connections 22
- 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.