Muv - AI Agent to relocate to Italy

People love Italy and Rome. They love lifestyle, climate and food. What they really hate is bureaucracy. Muv is an AI agent that helps people navigating Italian documents for relocations to Italy.

Comment

About the project

Inspiration

Moving to Rome for work sounds simple until you try it. Codice fiscale, housing contracts, anagrafe, ASL enrollment, banking, and tax basics form a dependency maze—order matters, and one wrong step can cost weeks (for example, trying to enroll in the health system before you have residenza). Official guidance is scattered across Comune di Roma, Agenzia Entrate, INPS, ASL, and EU portals, often in Italian. HR helps with payroll, not municipio appointments or landlord paperwork. Generic chatbots answer confidently but rarely cite sources, remember your journey, or respect what you can do before you have an apartment.

We built Muv (“move to Italy easily”) as a Telegram-native relocation copilot for EU citizens moving to Rome for employment: cited guidance from a curated knowledge base, a personal checklist driven by a real dependency graph, and optional Pro features (drafts, reminders, agentic tools) after invite-code unlock. We chose Telegram so onboarding is one /start—no new app install—and so a live demo can show checklist updates during a pitch.

What we learned

  • Stateful relocation data belongs outside the LLM. Profiles, checklist progress, and tier must live in a database keyed by telegram_user_id, not in the agent’s chat memory. That keeps multi-user sessions honest and makes “what do you remember about me?” a teachable trust moment.
  • RAG only helps if you enforce citations. Procedural advice needs mandatory source URLs from search results, plus clear disclaimers (guidance, not legal or tax advice). Curating knowledge/processed/ and re-ingesting when sources change is ongoing product work, not a one-time script.
  • Product shape is “playbook + search,” not “one big prompt.” A JSON playbook (rome_eu_work) with dependencies lets the agent say what you can do this month with a job contract but no apartment—something flat blog lists cannot do.
  • Freemium maps cleanly onto agent capabilities. Free tier: RAG, profile, checklist. Pro: drafts, reminders, browser/cron-style autonomy—gated in both agent policy (muv_get_tier) and MCP tools so free users get a clear upgrade path (/redeem ROME2026 in the demo).
  • Agent stacks are multi-service. Hermes handles Telegram, skills, and tool orchestration; a dedicated MCP sidecar owns Postgres, vectors, and business rules—a pattern that could later serve WhatsApp or an employer dashboard without rewriting core logic.

How we built it

Architecture

flowchart TB
  Users[Telegram users] --> GW[Hermes gateway]
  GW --> Agent[AI agent + skills]
  Agent --> Ctx[AGENTS.md + SOUL.md]
  Agent --> MCP[muv-mcp HTTP/SSE]
  MCP --> PG[(Postgres + pgvector)]
  KB[knowledge/processed] --> Ingest[rag/ingest.py]
  Ingest --> PG
  1. Hermes gateway — Multi-user Telegram sessions, five pillar skills (checklist, housing, health, tax, social), and persona rules in SOUL.md / AGENTS.md.
  2. muv-mcp — Python MCP server (FastAPI/uvicorn) exposing tier, profile, checklist, invite redeem, RAG search, and Pro-only tools; SQL migrations for users, checklist state, invite codes, and kb_chunks.
  3. Knowledge & RAG — Curated docs from sources.yaml, chunked and embedded into pgvector; answers are grounded with retrievable URLs.
  4. Playbook — knowledge/playbooks/rome_eu_work.json defines EU-work-in-Rome steps and dependencies; checklist tools initialize and update per user.
  5. Deploy & QA — Docker Compose locally; Railway for Postgres + muv-mcp + muv-gateway (Hermes volume for session persistence). scripts/demo_qa.sh and integration tests cover checklist, redeem, and Pro gates; docs/DEMO_WOW.md scripts the live Telegram demo.
  6. Website — Next.js marketing site (/demo, /pitch) on Vercel for product overview and pitch narrative.

Demo flow (~3 minutes)

/start → EU work + move date → dependency-aware checklist → tessera sanitaria question with source links → /redeem ROME2026 → Italian landlord email draft + anagrafe reminder + checklist update persisted in Postgres.

Challenges we faced

Challenge What we did
Fragmented, contradictory sources Curated KB + ingest pipeline; agent instructed to cite muv_rag_search URLs and flag municipio/ASL variance.
Multi-user PII and state Hard rule: no relocation data in Hermes memory; all profile/checklist/tier via MCP + Postgres.
Tier gating across two layers Pro tools gated in MCP and agent policy; Hermes may still list Pro tools globally—agent must refuse when tier is free (documented gap).
Cloud agent tooling Railway constraints (e.g. terminal); Pro demo leans on drafts, reminders, and cron rather than fragile browser automation on the gateway host.
Scope discipline v1 is EU citizens, Rome, employment only—no permesso playbooks, no “submit the comune form for me,” no legal certainty—keeps the MVP demoable and trustworthy.
KB freshness last_verified metadata and re-run ingest after source changes; otherwise RAG drifts from reality.

What’s next

Stripe billing, additional cities/playbooks, employer-sponsored codes, and deeper B2B packs are on the backlog. The open-source core (MIT) plus hosted bot is aimed at design partners among Rome employers and relocation communities.

Try it: Telegram /start, ask about tessera sanitaria, then /redeem ROME2026 for Pro drafts and reminders.

Stack: Hermes Agent + Muv MCP + Postgres/pgvector · deployed on Railway.

Built With

Share this project:

Updates