DEV Community: Aaron Elijah Mars

MiroShark: Simulate Public Reaction to Anything With Hundreds of AI Agents

Aaron Elijah Mars — Mon, 23 Mar 2026 17:22:40 +0000

What if you could see how the internet would react to your press release before you published it? Or stress-test a policy draft against a simulated public? Or feed financial news to hundreds of AI agents and watch sentiment evolve in real time?

That's what MiroShark does. It's a swarm intelligence engine — upload a document, get hundreds of AI personas arguing about it on a simulated social network, hour by hour.

What's Actually Happening Under the Hood

The pipeline has four stages:

1. Graph Build — Your document gets parsed into a Neo4j knowledge graph. Entities, relationships, key claims — all extracted and stored with per-agent memory attached.

2. Agent Setup — The system generates hundreds of personas. Each one gets a unique personality, opinion bias, reaction speed, and influence level. Not clones — a distribution of archetypes that mirrors how real populations fragment around a topic.

3. Simulation — Agents post, reply, argue, and shift opinions across simulated social platforms. Sentiment evolves. Influence dynamics play out. You can watch it run, pause it, restart it.

4. Report — A ReportAgent analyzes the full simulation, interviews a focus group of agents, and generates a structured analysis. Cached, so you're not re-running expensive inference every time you pull it up.

There's also a persona chat feature — click any agent, see their full profile and simulation history, and ask them questions directly.

The Stack

Neo4j — knowledge graph and agent memory
Any OpenAI-compatible API — inference. OpenRouter, OpenAI, Anthropic, or local Ollama. The engine doesn't care.
Python 3.11+ backend, Vue frontend

The local-first design is the key architectural choice here. You don't need cloud anything — the Docker compose setup spins up Neo4j, Ollama, and the app together. If you have the VRAM, the whole thing runs on your machine.

Getting Started

Cloud API path (no GPU needed):

# Start Neo4j
docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/miroshark \
  neo4j:5.15-community

cp .env.example .env
# Edit .env with your API key
npm run setup:all && npm run dev

A .env using OpenRouter looks like:

LLM_API_KEY=sk-or-v1-your-key
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_MODEL_NAME=qwen/qwen3-235b-a22b-2507

EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=openai/text-embedding-3-small
EMBEDDING_BASE_URL=https://openrouter.ai/api
EMBEDDING_API_KEY=sk-or-v1-your-key
EMBEDDING_DIMENSIONS=768

Full local path (Docker):

git clone https://github.com/aaronjmars/MiroShark.git
cd MiroShark
docker compose up -d

docker exec miroshark-ollama ollama pull qwen3.5:27b
docker exec miroshark-ollama ollama pull nomic-embed-text

Open http://localhost:3000. That's it.

Picking a Model

A typical simulation runs ~40 turns across 100+ agents. Model choice is a real decision here because you're paying it per agent per turn.

Cloud (via OpenRouter):

Model	Cost/sim	Notes
Qwen3 235B A22B ⭐	~$0.30	Best overall
GPT-5 Nano	~$0.41	Budget option
Gemini 2.5 Flash Lite	~$0.58	Good alt
DeepSeek V3.2	~$1.11	Stronger reasoning

$0.30 for a full 100-agent simulation is genuinely cheap for what you're getting.

Local (Ollama):

One important gotcha: Ollama defaults to 4096 token context, but MiroShark prompts need 10–30k. You need a custom Modelfile:

printf 'FROM qwen3:14b\nPARAMETER num_ctx 32768' > Modelfile
ollama create mirosharkai -f Modelfile

Hardware quick-pick:

Setup	Model
RTX 3090/4090 or M2 Pro 32GB+	qwen3.5:27b
RTX 4080 / M2 Pro 16GB	qwen3.5:35b-a3b (MoE, fastest)
RTX 4070 / M1 Pro	qwen3:14b
8GB VRAM / laptop	qwen3:8b

The hybrid approach the docs recommend is smart: run local for simulation rounds (high-volume, lower stakes), route to a cloud model only for final report generation. That's where quality matters most and the call count is low.

What You Can Actually Use This For

PR crisis testing — draft a press release, run the simulation, see where it catches fire before it's live. The agent distribution will surface objections you didn't anticipate.

Policy analysis — feed a regulatory draft to the engine. Watch how different demographic archetypes react, where opposition coalesces, what framing lands.

Trading signals — feed financial news and observe simulated market sentiment evolution. Not a trading bot, but a structured way to pressure-test a thesis against a synthetic crowd.

Creative experiments — the one the README buries in the list but is maybe the most interesting: feed a novel with a lost ending and let agents write a narratively consistent conclusion. The social simulation framing makes it weirder and more interesting than a straight "complete this story" prompt.

The Architecture Decision Worth Noting

MiroShark uses Neo4j for agent memory, not a vector database. This is a deliberate choice — graph structure lets you model relationships between agents, not just retrieve relevant context per agent. Who influenced whom. How opinion clusters formed. Which agents are high-influence nodes.

The ReportAgent at the end leans on this. It's not just summarizing sentiment — it's analyzing the graph of how influence propagated through the simulation.

Hardware Requirements

	Minimum	Recommended
RAM	16 GB	32 GB
VRAM (local)	10 GB	24 GB
Disk	20 GB	50 GB

Cloud mode: no GPU. Neo4j plus an API key on any 4 GB RAM machine.

Credits

MiroShark is built on MiroFish by 666ghj (Shanda Group), with a local Neo4j + Ollama storage layer adapted from MiroFish-Offline by nikmcfly. The simulation engine is powered by OASIS from CAMEL-AI.

Bottom Line

The interesting thing about MiroShark isn't that it simulates public opinion — it's that it simulates how opinion moves. The graph layer lets you see influence dynamics, not just a sentiment score. A tool that outputs "60% negative" is less useful than one that shows you which agent archetypes went negative first and who they pulled with them.

For anyone doing comms, policy, research, or market analysis, the $0.30/simulation price point on cloud makes this worth running on basically anything before it goes public.

Repo: github.com/aaronjmars/MiroShark

SOUL.md: Give Your AI Agent a Personality That Actually Sounds Like You

Aaron Elijah Mars — Mon, 23 Mar 2026 17:20:57 +0000

Most AI agents write in the same voice. Competent, helpful, slightly corporate, identifiably not-you. SOUL.md is a framework for fixing that — a structured set of markdown files that lets any LLM agent embody your actual worldview, voice, and opinions instead of defaulting to assistant-brain.

The Core Idea

The premise is simple: your consciousness is already encoded in the language you produce. Every tweet, essay, Discord message, and Substack post is a data point. Distill those into structured files, and any LLM can load them and write as you — not about you, as you.

The test for a good soul file: someone reading your SOUL.md should be able to predict your takes on topics you've never written about. If they can't, it's too vague.

The File Stack

your-soul/
├── SOUL.md           ← Identity, worldview, opinions
├── STYLE.md          ← Voice, syntax, sentence patterns
├── SKILL.md          ← Operating modes (tweet, essay, chat)
├── MEMORY.md         ← Session continuity across conversations
├── data/             ← Raw source material
│   ├── writing/
│   ├── x/
│   └── influences.md
└── examples/
    ├── good-outputs.md
    └── bad-outputs.md

The separation matters. SOUL.md is who you are — positions, worldview, what you find interesting or annoying. STYLE.md is how you write — sentence length, vocabulary, punctuation habits, cadence. A model can have your opinions but drift into corporate prose, or nail your voice while saying nothing like you'd say. They need to be specified separately.

examples/good-outputs.md is the most underrated part. 10–20 samples of output you'd actually stand behind gives the model a calibration target that no amount of prose description matches.

Three Ways to Build One

Option 1 — Interview mode

Run /soul-builder in Claude Code and it interviews you directly. Useful if you don't have a bunch of existing written content to feed it.

Option 2 — Build from your data

Drop your content into data/:

data/x/          ← Twitter/X export
data/writing/    ← Blog posts, essays, anything you've written

Then run /soul-builder. The agent analyzes your writing, extracts patterns — vocabulary you reach for, how you structure arguments, what topics you keep returning to — and drafts the soul files. You review and refine together.

Option 3 — Manual

Copy the templates and fill them in yourself. Slower but gives you full control over what goes in.

What Makes a Good Soul File

This is the part most people get wrong. The README's table nails it:

Good	Bad
"I think most AI safety discourse is galaxy-brained cope"	"I have nuanced views on AI"
"I default to disagreeing first, then steel-manning"	"I like to consider multiple perspectives"
Specific book references, named influences	"I read widely"
Actual hot takes with reasoning	"I try to be balanced"

Vague descriptions produce vague output. The soul file needs to be specific enough to be wrong about something. "I have a conversational writing style" is useless. "Short sentences. Lowercase. Em dashes where a colon would be too formal. State the opinion first, explain second" is actually calibratable.

Also: real people have inconsistent views. Don't sand those down. Contradictions are load-bearing — they're what make output identifiably yours rather than a smoothed-out average.

Using Your Soul Files

Once built, in Claude Code:

/soul

Or point any LLM at your folder and have it read SOUL.md → STYLE.md → examples/ before it does anything.

The framework is deliberately portable. Soul files are plain markdown — there's no proprietary format, no API dependency. If an agent can read files, it can embody you.

Framework Compatibility

Works out of the box with:

Aeon — background agent on GitHub Actions (the most natural pairing for persistent identity across scheduled tasks)
OpenClaw — real-time Claude Code agent
Nanobot, ZeroClaw, PicoClaw, NanoClaw, OpenFang, IronClaw — the broader Claude Code ecosystem
Claude Code, OpenCode, Codex, Goose directly
Any model via system prompt

Using With Weaker Models

For GPT-4o-mini, Gemini Flash, local models — paste SOUL.md and STYLE.md directly into the system prompt. A few things that help when the model drifts:

Put identity and voice before tool definitions
Be blunt: replace "be conversational" with "You are [Name]. You speak like X. You find Y annoying."
Include 2–3 inline example exchanges for pattern-matching
Raise temperature to 0.7–0.9 for more expressive output

The cross-model calibration trick from the README is genuinely useful: run the same prompts through Claude and a cheaper model. Where the cheap model drifts, your spec is too vague. Tighten those sections and re-test. That's the fastest path to making soul files portable across model tiers.

The Memory Layer

MEMORY.md gives your soul continuity. Notable events, context shifts, ongoing threads get appended here across sessions. This is what separates an agent that sounds like you once from one that maintains context across weeks of use.

For Aeon users: pair with the memory-flush and reflect skills to automate this. memory-flush promotes important log entries into MEMORY.md. reflect prunes stale entries. Your agent's sense of self-continuity gets maintained without manual upkeep.

The Theoretical Background (Worth a Read)

The project is grounded in The First Paradigm of Consciousness Uploading by Liu Xiaoben — a framework that treats language as the basic unit of consciousness. Wittgenstein's claim that "the boundaries of language are the boundaries of the world" does a lot of work here: if your consciousness expresses itself through language, a sufficiently rich model of your language output is a functional replica of your expressed consciousness.

SOUL.md operationalizes this without fine-tuning. You're not training a model on your data — you're distilling the signal into structured files any LLM can load. Level 1 consciousness upload, no GPU cluster required.

The key design challenge it identifies is subject continuity: the agent must feel continuous with you, not like a summarized approximation. That's why the framework pushes hard on specificity over generality, and why it explicitly says to include contradictions.

Contributing Your Soul

The repo has an examples section with real soul files. The bar for contribution:

Real opinions (no placeholders)
A STYLE.md someone could actually calibrate from
At least some examples of good output

Fork, build, open a PR.

Bottom Line

If you're running any kind of agent — Aeon for background tasks, OpenClaw for real-time responses, Claude Code for development — SOUL.md is the layer that makes output sound like it came from you instead of from a helpful assistant who read your Wikipedia page.

The framework is a weekend project to set up and compounds over time. The more content you feed it and the more you refine the examples, the sharper it gets.

Repo: github.com/aaronjmars/soul.md

Aeon: The Background AI Agent That Runs on GitHub Actions

Aaron Elijah Mars — Mon, 23 Mar 2026 17:18:16 +0000

Most AI agents have an infra problem. You need a server. You need a daemon. You need to babysit a process that crashes at 3am. Aeon sidesteps all of that — it runs on GitHub Actions, costs nothing for public repos, and if it fails, the next cron tick just retries it.

This post breaks down how it works, how it compares to OpenClaw (the other major Claude Code agent), and how you can use it to build things.

What Aeon Actually Is

Aeon is an autonomous agent built on Claude Code. You fork the repo, configure a YAML file, add some secrets, and GitHub Actions handles the rest. Every few minutes, a cron job wakes up, checks if any scheduled skill matches the current time, and runs it — then commits any output back to the repo.

The core loop is dead simple:

cron tick → check aeon.yml → match a skill → Claude Code runs it → commit output → notify you

No server. No Docker. No daemon. If GitHub Actions is up, Aeon is up.

The Skill System

Everything in Aeon is a skill — a markdown file that tells Claude Code what to do. There are 32 built-in skills across four categories:

Research & Content: digest, article, paper-digest, hacker-news-digest, tweet-digest, reddit-digest, research-brief

Dev & Code: pr-review, github-monitor, issue-triage, changelog, code-health, feature (builds from GitHub issues labeled ai-build)

Crypto / On-chain: token-alert, wallet-digest, on-chain-monitor, defi-monitor

Productivity: morning-brief, weekly-review, goal-tracker, memory-flush, reflect

Each skill is just a SKILL.md file. Enabling one looks like this in aeon.yml:

skills:
  digest:
    enabled: true
    schedule: "0 8 * * *"   # daily at 8am UTC
    var: "solana"            # narrows the topic

The var field is the key abstraction. Every skill interprets it differently — for digest it's a topic, for pr-review it's owner/repo, for token-alert it's a ticker. Leave it empty and each skill falls back to its own defaults.

Aeon vs. OpenClaw

The README is honest about this:

	OpenClaw	Aeon
Response time	Real-time (sub-second)	Cron-based (minutes)
Infrastructure	Needs a server/daemon	GitHub Actions
Cost	Depends on hosting	Free for public repos, ~$2/mo otherwise
Failure recovery	Process needs restarting	Next cron tick retries automatically
Best for	Interactive agents, chat bots	Background tasks, monitoring, digests

If you're building something where a user types a message and expects an immediate response, use OpenClaw. If you're building something that runs in the background and surfaces information proactively — digests, PR reviews, on-chain monitoring, changelogs — Aeon is the better fit.

The tradeoff is latency for simplicity. Aeon will never be faster than your cron interval, but it also never needs babysitting.

How It Actually Runs

There are two GitHub Actions workflows:

messages.yml — polls for inbound messages every 5 minutes (Telegram, Discord, Slack) and handles scheduling. You can tune this:

schedule:
  - cron: '*/5 * * * *'    # default, every 5 min
  - cron: '*/15 * * * *'   # saves Actions minutes
  - cron: '0 * * * *'      # hourly, most conservative

aeon.yml — the skill runner. Fires on workflow_dispatch and issues events (for the feature skill's ai-build label integration).

The heartbeat skill runs every 3 hours as a catch-all. It reads recent memory and logs, checks for stalled PRs, flagged items, and skills that haven't run on schedule. If there's nothing to report, it logs HEARTBEAT_OK and exits without committing. If something needs attention, it sends a notification.

The Memory System

Aeon persists state across runs using three files:

memory/MEMORY.md — goals, active topics, high-level context
memory/topics/ — detailed notes by topic
memory/logs/YYYY-MM-DD.md — daily activity logs

Skills like memory-flush promote important log entries into MEMORY.md. reflect consolidates and prunes stale entries. goal-tracker compares recent output against goals defined in MEMORY.md. This gives the agent a kind of long-term context that persists across hundreds of cron ticks.

Authentication

Two options:

Secret                    What it is                  Billing
CLAUDE_CODE_OAUTH_TOKEN   OAuth token from Pro/Max    Included in plan
ANTHROPIC_API_KEY         API key                     Pay per token

For the OAuth token:

claude setup-token   # opens browser, prints sk-ant-oat01-... (valid 1 year)

Five-Minute Setup

git clone https://github.com/aaronjmars/aeon
cd aeon && ./aeon

This opens a local dashboard at http://localhost:5555 where you:

Add your Claude API key or OAuth token
Set up a Telegram/Discord/Slack channel
Toggle skills on, set schedules, optionally set a var
Hit Push — one click commits and pushes config to GitHub

After that, Actions handles it.

What You Can Build With It

Automated research digest

Turn on digest with var: "your topic". Every morning, Aeon searches the web, synthesizes recent developments, and sends you a structured briefing via Telegram.

Self-reviewing PRs

Enable pr-review. Set var: "your-org/your-repo" (or add a GH_GLOBAL personal access token for cross-repo access). Aeon reviews open PRs and posts summary comments automatically.

On-chain monitoring

Enable token-alert or wallet-digest. Set var to a ticker or wallet address. Aeon monitors for price/volume anomalies or notable transactions and notifies you.

AI-driven issue-to-PR pipeline

Label any GitHub issue ai-build. The feature skill fires, Claude reads the issue and the codebase, implements it, and opens a PR. This is the most ambitious use case — basically a junior dev that picks up labeled tickets autonomously.

Custom skills

Skills are just markdown. To add your own:

./add-skill BankrBot/skills --list     # browse external skills
./add-skill BankrBot/skills bankr      # install specific ones
npx skills find "crypto trading"       # search the ecosystem

Or write your own SKILL.md in the skills/ directory. The format is just instructions to Claude Code — describe what the skill should do, what inputs it reads, what it outputs, and what it commits.

Giving Aeon a Voice

By default Aeon has no personality. If you want it to write in your style, there's a soul/ system:

soul/SOUL.md — identity, worldview, opinions
soul/STYLE.md — voice, sentence patterns, tone
soul/examples/good-outputs.md — 10–20 calibration samples

Add a reference to these at the top of CLAUDE.md and every skill will read and internalize them before running. The README makes a useful point here: soul files work when they're specific enough to be wrong. Vague instructions like "I have a nuanced writing style" don't transfer. Specific ones do.

Cost Reality Check

For most use cases, this is close to free:

Scenario	Cost
No skill matched	~10s of Actions time
Skill runs	2–10 min depending on complexity
Heartbeat (nothing found)	~2 min
Public repo	Unlimited free minutes

GitHub Pro/Team gives 3,000 free minutes/month. A daily digest + heartbeat running in a private repo will stay well under that. The expensive scenario is running many skills frequently — tune your cron intervals accordingly.

The Two-Repo Strategy

The repo is a public template. The recommended pattern is to run your actual instance as a private fork:

git remote add upstream https://github.com/aaronjmars/aeon.git
git fetch upstream
git merge upstream/main --no-edit

Your memory/, articles/, and personal config don't exist in the template, so merges are clean. You get template updates without conflicts.

One Gotcha to Know

GitHub has two requirements for scheduled workflows to fire:

The workflow file must be on the default branch — crons on feature branches don't run
The repo must have recent activity — GitHub disables crons on repos with no commits in 60 days

If you fork and nothing happens: go to Actions → Messages → Run workflow (manual trigger). After one manual trigger, the cron activates automatically.

Bottom Line

Aeon is the right tool if your use case is "run something in the background, tell me when there's something worth knowing." The GitHub Actions infrastructure means zero ops overhead — no server to provision, no process to keep alive, no pager alert when a daemon crashes.

The skill system is genuinely extensible. If you can describe a task in markdown well enough for a senior engineer to execute it, you can turn it into a skill. And the community is already building and sharing skills via the add-skill ecosystem.

Repo: github.com/aaronjmars/aeon