MiroMe

MiroMe is an open-source tool that helps someone understand how they show up across the public internet.

Give it a name, an organization, and a few keywords, and it will search public sources, expand into deeper platform data when available, and generate a structured report on visibility, reputation, public signals, and blind spots.

Features

• Simple local setup and plain terminal output
• Live mode with Tavily search and OpenRouter model calls
• Quality-first Tavily collection with multi-angle search, extract, and research passes
• Automatic expansion into LinkedIn, X, and GitHub when baseline web search surfaces those platform links
• Pluggable retrieval architecture so additional platform APIs can be added as connectors
• Clone, configure environment variables, and run with a single command
• Friendly configuration validation and upstream API error messages
• Test suite and GitHub Actions CI for open-source maintenance

Installation

For normal use, install the package only:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .

Quick Start

Clone, install, and configure:

git clone git@github.com:OpenJobsAI/MiroMe.git
cd MiroMe
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .
cp .env.example .env

Set your keys in .env or export them in the shell:

export TAVILY_API_KEY="tvly-..."
export OPENROUTER_API_KEY="sk-or-v1-..."
# Optional platform-native connectors:
export APIFY_API_TOKEN="apify_api_..."

Run a scan:

mirome "Elon Musk" --org "xAI" --keywords "AI, Tesla, SpaceX"

Save the report to disk:

mirome "Elon Musk" --org "xAI" --output out/report.md

Show the installed version:

mirome --version

After installation, prefer the mirome command shown above. Use python -m mirome_cli ... only when you are working directly from source and intentionally skipping installation.

Usage

mirome "Target Name" [--org "Target Org"] [--keywords "foo, bar"] [--format markdown|json] [--output path] [--quiet]

Arguments:

• name: target person name
• --org: optional organization
• --keywords: optional search hints
• --format: output format, markdown or json
• --output: write the generated report to a file
• --quiet: hide progress logs
• --max-results: override the number of retained sources after collection
• --low-signal-threshold: override the low-signal cutoff

Environment Variables

• TAVILY_API_KEY
• OPENROUTER_API_KEY
• APIFY_API_TOKEN optional, enables automatic platform-native expansion through Apify connectors
• MIROME_QUALITY_MODEL default: anthropic/claude-sonnet-4.6
• MIROME_FAST_MODEL default: google/gemini-2.5-flash
• MIROME_HTTP_REFERER default: https://mirome.local
• MIROME_APP_NAME default: MiroMe
• MIROME_MAX_RESULTS default: 18
• MIROME_LOW_SIGNAL_THRESHOLD default: 3
• MIROME_TAVILY_QUERY_COUNT default: 8
• MIROME_TAVILY_RESULTS_PER_QUERY default: 10
• MIROME_TAVILY_EXTRACT_LIMIT default: 12
• MIROME_LINKEDIN_PROFILE_ACTOR_ID default: LpVuK3Zozwuipa5bp
• MIROME_LINKEDIN_PROFILE_URLS optional override, comma-separated LinkedIn profile URLs
• MIROME_LINKEDIN_POSTS_ACTOR_ID default: Wpp1BZ6yGWjySadk3
• MIROME_LINKEDIN_POST_SEED_URLS optional override, comma-separated LinkedIn seed URLs
• MIROME_LINKEDIN_MIN_DELAY default: 2
• MIROME_LINKEDIN_MAX_DELAY default: 4
• MIROME_LINKEDIN_PROXY_COUNTRY default: US
• MIROME_TWITTER_ACTOR_ID default: 61RPP7dywgiy0JPD0
• MIROME_TWITTER_START_URLS optional override, comma-separated X seed URLs
• MIROME_TWITTER_SEARCH_TERMS optional override, comma-separated search terms
• MIROME_TWITTER_HANDLES optional override, comma-separated X handles without @
• MIROME_TWITTER_MAX_ITEMS default: 200
• MIROME_TWITTER_SORT default: Latest
• MIROME_TWITTER_LANGUAGE default: en
• MIROME_GITHUB_ACTOR_ID default: XiZTm8w05bW4YKawz
• MIROME_GITHUB_PROFILE_URLS optional override, comma-separated GitHub profile URLs
• MIROME_GITHUB_REPO_URL optional override, GitHub repository URL

You can also copy .env.example to .env for local development.

For normal use, you should not need to hand-enter LinkedIn, X, or GitHub identifiers. MiroMe first searches the open web, detects platform URLs or handles in the evidence, and then uses the configured platform connectors to pull deeper data from those sources. The platform-specific environment variables above are override knobs for debugging, targeted re-runs, or maintainer workflows.

The default collection profile is intentionally quality-first instead of latency-first. MiroMe fans out across multiple Tavily queries, re-extracts the strongest URLs, and runs targeted research passes for background, trajectory, public statements, and reputation coverage.

When running in normal mode, MiroMe prints start, per-step progress, and completion status messages to stderr so you can see what it is doing without polluting the final report output.

Development

Common contributor commands:

make install-dev
make test
make lint
make compile
make run-example

Equivalent direct commands:

python -m pip install -r requirements-dev.txt

python -m unittest discover -s tests -v

ruff check .

python -m compileall src

mirome "Elon Musk" --org "xAI" --keywords "AI, Tesla, SpaceX"

Project Layout

src/mirome_cli/
  main.py              Entrypoint
  graph.py             LangGraph and local runner wiring
  agents.py            Pipeline node implementations
  retrieval.py         Multi-source connector planning and evidence merge
  clients/             Tavily and OpenRouter adapters
  heuristics.py        Internal fallback and deterministic analysis helpers
  report.py            Markdown/JSON renderers
tests/
  test_pipeline.py     Core pipeline and config tests
  fixtures/profile_scan.json  Internal fixture used by unit tests

Notes on Reliability

• Tavily /research is treated as optional so the main scan can still complete if that endpoint is unavailable.
• The default retrieval profile favors deeper coverage over speed and may issue multiple Tavily requests per scan.
• The schema layer normalizes common LLM confidence outputs such as high, medium, and low.
• MiroMe validates that Tavily and OpenRouter keys are not swapped before making live requests.
• The end-user workflow is live-first; internal fixtures are only used by the automated tests.

Limitations

• This is still an alpha open-source project, not a production SaaS backend.
• The report quality depends heavily on public web coverage and search quality.
• The live mode is synchronous and optimized for simplicity, not throughput.
• Direct-quote extraction and timeline synthesis can still inherit inaccuracies from source material.

Contributing

Please read CONTRIBUTING.md before opening a pull request.

Security

If you find a security issue, please follow SECURITY.md.

Maintainer Notes

• Release process: RELEASE_CHECKLIST.md
• Connector architecture: docs/CONNECTORS.md
• GitHub launch copy and repo setup suggestions: docs/OPEN_SOURCE_LAUNCH.md

License

MIT. See LICENSE.