# yunus-0x/meridian architecture

> Architecture diagram of the GitHub repository yunus-0x/meridian, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yunus-0x/meridian
- Repository: https://github.com/yunus-0x/meridian

## Overview

Meridian is an autonomous Solana liquidity-management agent. Its scheduled screening and management cycles gather pool/position data, let role-specific LLM agents select tool actions, then deploy, monitor, claim fees, or close Meteora DLMM positions. Closed-position outcomes feed lessons and screening-threshold evolution. The README also documents Telegram chat and alerts, optional Discord signals, and a terminal CLI. Several internal calls are supported by the SOURCE INDEX rather than sampled call sites; optional or externally mediated links are marked dashed where appropriate.

Main entry points: [`tools/executor.js`](https://github.com/yunus-0x/meridian/blob/main/tools/executor.js) (Tool execution), [`index.js`](https://github.com/yunus-0x/meridian/blob/main/index.js) (Cycle orchestrator), [`agent.js`](https://github.com/yunus-0x/meridian/blob/main/agent.js) (Agent harness), [`tools/screening.js`](https://github.com/yunus-0x/meridian/blob/main/tools/screening.js) (Pool screening)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent runtime"]
  node_runtime["Cycle orchestrator<br/>[index.js]"]
  node_harness["Agent harness<br/>[agent.js]"]
  node_prompts["Prompt assembly<br/>[prompt.js]"]
  node_config["Runtime configuration<br/>[config.js]"]
end

subgraph group_trading["Screening and trading"]
  node_screening["Pool screening<br/>[screening.js]"]
  node_executor["Tool execution<br/>[executor.js]"]
  node_dlmm["Position operations<br/>[dlmm.js]"]
  node_wallet["Wallet and swaps<br/>[wallet.js]"]
  node_token["Token research<br/>[token.js]"]
end

subgraph group_learning["Memory and learning"]
  node_state[("Position state<br/>[state.js]")]
  node_decisions[("Decision history<br/>[decision-log.js]")]
  node_lessons[("Performance learning<br/>[lessons.js]")]
  node_poolmemory[("Pool history<br/>[pool-memory.js]")]
  node_thresholds["Signal weights<br/>[signal-weights.js]"]
end

subgraph group_interfaces["User interfaces"]
  node_telegram["Telegram interface<br/>[telegram.js]"]
  node_cli["Terminal interface<br/>[cli.js]"]
  node_discord["Discord listener<br/>[index.js]"]
end

subgraph group_integrations["External integrations"]
  node_solana{{"Solana network"}}
  node_marketdata{{"Pool and token APIs"}}
  node_llm{{"OpenRouter models"}}
  node_meridianapi{{"Meridian API"}}
end

node_operator(("Operator"))

node_operator -->|"starts"| node_runtime
node_runtime -->|"runs cycles"| node_harness
node_harness -->|"builds prompts"| node_prompts
node_harness -->|"dispatches tools"| node_executor
node_prompts -.->|"requests reasoning"| node_llm
node_runtime -->|"fetches candidates"| node_screening
node_runtime -->|"checks positions"| node_dlmm
node_runtime -->|"sends reports"| node_telegram
node_executor -->|"invokes screening"| node_screening
node_executor -->|"invokes position tools"| node_dlmm
node_executor -->|"invokes wallet tools"| node_wallet
node_executor -->|"invokes token tools"| node_token
node_executor -->|"updates position state"| node_state
node_dlmm -->|"submits transactions"| node_solana
node_wallet -->|"reads balances"| node_solana
node_screening -->|"queries pool data"| node_marketdata
node_token -->|"queries token data"| node_marketdata
node_dlmm -->|"records outcomes"| node_lessons
node_lessons -.->|"updates pool history"| node_poolmemory
node_lessons -->|"recalculates weights"| node_thresholds
node_harness -.->|"logs decisions"| node_decisions
node_harness -.->|"loads live state"| node_state
node_telegram -.->|"requests agent actions"| node_runtime
node_operator -->|"issues commands"| node_cli
node_cli -->|"runs tool actions"| node_executor
node_discord -.->|"queues signals"| node_meridianapi
node_screening -->|"loads signal candidates"| node_meridianapi
node_meridianapi -.->|"provides signal candidates"| node_screening

click node_runtime "https://github.com/yunus-0x/meridian/blob/main/index.js"
click node_harness "https://github.com/yunus-0x/meridian/blob/main/agent.js"
click node_prompts "https://github.com/yunus-0x/meridian/blob/main/prompt.js"
click node_config "https://github.com/yunus-0x/meridian/blob/main/config.js"
click node_screening "https://github.com/yunus-0x/meridian/blob/main/tools/screening.js"
click node_executor "https://github.com/yunus-0x/meridian/blob/main/tools/executor.js"
click node_dlmm "https://github.com/yunus-0x/meridian/blob/main/tools/dlmm.js"
click node_wallet "https://github.com/yunus-0x/meridian/blob/main/tools/wallet.js"
click node_token "https://github.com/yunus-0x/meridian/blob/main/tools/token.js"
click node_state "https://github.com/yunus-0x/meridian/blob/main/state.js"
click node_decisions "https://github.com/yunus-0x/meridian/blob/main/decision-log.js"
click node_lessons "https://github.com/yunus-0x/meridian/blob/main/lessons.js"
click node_poolmemory "https://github.com/yunus-0x/meridian/blob/main/pool-memory.js"
click node_thresholds "https://github.com/yunus-0x/meridian/blob/main/signal-weights.js"
click node_telegram "https://github.com/yunus-0x/meridian/blob/main/telegram.js"
click node_cli "https://github.com/yunus-0x/meridian/blob/main/cli.js"
click node_discord "https://github.com/yunus-0x/meridian/blob/main/discord-listener/index.js"

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_runtime,node_harness,node_prompts,node_config toneBlue
class node_screening,node_executor,node_dlmm,node_wallet,node_token toneAmber
class node_state,node_decisions,node_lessons,node_poolmemory,node_thresholds toneMint
class node_telegram,node_cli,node_discord toneRose
class node_solana,node_marketdata,node_llm,node_meridianapi,node_operator toneIndigo
```

## Components

### Agent runtime

- [Cycle orchestrator](https://github.com/yunus-0x/meridian/blob/main/index.js): `index.js`
- [Agent harness](https://github.com/yunus-0x/meridian/blob/main/agent.js): `agent.js`
- [Prompt assembly](https://github.com/yunus-0x/meridian/blob/main/prompt.js): `prompt.js`
- [Runtime configuration](https://github.com/yunus-0x/meridian/blob/main/config.js): `config.js`

### Screening and trading

- [Pool screening](https://github.com/yunus-0x/meridian/blob/main/tools/screening.js): `tools/screening.js`
- [Tool execution](https://github.com/yunus-0x/meridian/blob/main/tools/executor.js): `tools/executor.js`
- [Position operations](https://github.com/yunus-0x/meridian/blob/main/tools/dlmm.js): `tools/dlmm.js`
- [Wallet and swaps](https://github.com/yunus-0x/meridian/blob/main/tools/wallet.js): `tools/wallet.js`
- [Token research](https://github.com/yunus-0x/meridian/blob/main/tools/token.js): `tools/token.js`

### Memory and learning

- [Position state](https://github.com/yunus-0x/meridian/blob/main/state.js): `state.js`
- [Decision history](https://github.com/yunus-0x/meridian/blob/main/decision-log.js): `decision-log.js`
- [Performance learning](https://github.com/yunus-0x/meridian/blob/main/lessons.js): `lessons.js`
- [Pool history](https://github.com/yunus-0x/meridian/blob/main/pool-memory.js): `pool-memory.js`
- [Signal weights](https://github.com/yunus-0x/meridian/blob/main/signal-weights.js): `signal-weights.js`

### User interfaces

- [Telegram interface](https://github.com/yunus-0x/meridian/blob/main/telegram.js): `telegram.js`
- [Terminal interface](https://github.com/yunus-0x/meridian/blob/main/cli.js): `cli.js`
- [Discord listener](https://github.com/yunus-0x/meridian/blob/main/discord-listener/index.js): `discord-listener/index.js`

### External integrations

- **Solana network**
- **Pool and token APIs**
- **OpenRouter models**
- **Meridian API**

### Other components

- **Operator**

## Connections

- Operator → Cycle orchestrator: starts (evidence: `README.md`)
- Cycle orchestrator → Agent harness: runs cycles (evidence: `index.js`)
- Agent harness → Prompt assembly: builds prompts (evidence: `agent.js`)
- Agent harness → Tool execution: dispatches tools (evidence: `agent.js`)
- Prompt assembly → OpenRouter models: requests reasoning (evidence: `README.md`)
- Cycle orchestrator → Pool screening: fetches candidates (evidence: `index.js`)
- Cycle orchestrator → Position operations: checks positions (evidence: `index.js`)
- Cycle orchestrator → Telegram interface: sends reports (evidence: `index.js`)
- Tool execution → Pool screening: invokes screening (evidence: `tools/executor.js`)
- Tool execution → Position operations: invokes position tools (evidence: `tools/executor.js`)
- Tool execution → Wallet and swaps: invokes wallet tools (evidence: `tools/executor.js`)
- Tool execution → Token research: invokes token tools (evidence: `tools/executor.js`)
- Tool execution → Position state: updates position state (evidence: `tools/executor.js`)
- Position operations → Solana network: submits transactions (evidence: `tools/dlmm.js`)
- Wallet and swaps → Solana network: reads balances (evidence: `tools/wallet.js`)
- Pool screening → Pool and token APIs: queries pool data (evidence: `README.md`)
- Token research → Pool and token APIs: queries token data (evidence: `tools/token.js`)
- Position operations → Performance learning: records outcomes (evidence: `tools/dlmm.js`)
- Performance learning → Pool history: updates pool history (evidence: `lessons.js`)
- Performance learning → Signal weights: recalculates weights (evidence: `lessons.js`)
- Agent harness → Decision history: logs decisions (evidence: `README.md`)
- Agent harness → Position state: loads live state (evidence: `README.md`)
- Telegram interface → Cycle orchestrator: requests agent actions (evidence: `README.md`)
- Operator → Terminal interface: issues commands (evidence: `README.md`)
- Terminal interface → Tool execution: runs tool actions (evidence: `cli.js`)
- Discord listener → Meridian API: queues signals (evidence: `README.md`)
- Pool screening → Meridian API: loads signal candidates (evidence: `tools/screening.js`)
- Meridian API → Pool screening: provides signal candidates (evidence: `README.md`)
