╭─────────╮
                          │  SOLUM  │
                          ╰─────────╯

The bedrock for living AI agents.

Persistent autonomous agents built on Elixir/OTP.

Quick Start · What Works Today · Coming Soon · Docs · Discord

---

Alpha Preview

Demo (GIF) Placeholder

TODO: Replace with real demo GIF.

Suggested path: docs/media/demo-alpha.gif

Dashboard Screenshot Placeholder

TODO: Replace with current dashboard screenshot.

Suggested path: docs/media/dashboard-alpha.png

Architecture Diagram Placeholder

TODO: Replace with polished architecture diagram.

Suggested path: docs/media/architecture-alpha.png

---

Why Solum

Most agent frameworks run request-by-request: call model, return text, lose continuity.

Solum treats an agent as a long-running OTP process:

• persistent state
• supervised fault tolerance
• async tool execution
• memory compaction over time
• sub-agent orchestration via message passing

This follows the architecture direction documented in docs/ARCHITECTURE.md and the Context HUD framing from docs/blog-hivemind-intro.md.

---

What Works Today (Alpha)

• Always-on agent processes (GenServer-based) with supervised restarts
• Multi-agent orchestration (spawn and coordinate sub-agents)
• Tool execution pipeline with async/background execution
• Sedimentary memory model and context assembly
• WAL-backed persistence foundations
• CLI workflows for running and chatting with agents
• Live dashboard foundations via Phoenix LiveView
• Core test suite (500+ tests referenced in project blog)

Coming Soon

• Polished Context HUD experience end-to-end
• Better onboarding and first-run setup flow
• Richer channel/file attachment support across integrations
• Production release packaging and installer flow
• Expanded reliability and dashboard UX polish

---

Architecture (Current Shape)

Solum.Application
│
├── AgentSupervisor          DynamicSupervisor for agent processes
│   ├── Agent "sol"          conversation loop, memory, tool dispatch
│   ├── Agent "coder-*"      sub-agents for specialized tasks
│   └── Agent "..."          horizontally scalable agent pool
│
├── Context.Store            SQLite + compaction pipeline
│   ├── L1 (10-min)
│   ├── L2 (hourly)
│   └── L3-L5 (daily+)
│
├── Tool.Service             async tools + orchestration hooks
├── ChannelSupervisor        Signal / Telegram / CLI adapters
├── Config                   live-reloadable runtime config
└── SolumWeb                 dashboard (Phoenix LiveView)

For deeper detail, see docs/ARCHITECTURE.md.

---

Quick Start

# Prereq: Elixir 1.19+ and OTP 27+
git clone https://github.com/solum-org/solum.git
cd solum
mix deps.get

# Configure local agent settings
cp config/agent.example.toml config/agent.toml
$EDITOR config/agent.toml

# Setup + run
mix solum.setup
mix solum.start

Open another shell and chat:

mix solum.cli chat --agent sol "Hello."

Dashboard:

open http://localhost:4000

---

Alpha Call To Action

Solum is in active alpha. If you want to shape the architecture with us:

• try it on a real workflow
• file issues with logs and repro steps
• join design/implementation discussion on Discord

Start here:

• GitHub: https://github.com/solum-org/solum
• Docs: https://solum.dev/docs
• Discord: https://discord.gg/solum

---

 ░▒▓ solum — the ground beneath the agent ▓▒░

MIT License