Nemo

An iMessage-first AI concierge. You text Nemo a task ("get my Lufthansa refund", "find me the top 3 coffee makers under $100"), a named worker picks it up, plans it, executes real tool calls, and reports back in the same thread. Anything sensitive (spending money, submitting a form, sending an email) stops and asks for a YES/NO in the conversation first.

How it works

1. Ingest — a text arrives (iMessage/SMS via LinqApp, or the web dev simulator) and a router classifies it: a new task, a status question, an approval reply, small talk, or a management command.
2. Plan — the Intent Compiler structures the request and the Planner turns it into a small dependency graph of steps, each declaring the tools and permissions it needs.
3. Execute — a BullMQ worker runs each step's tool loop. Steps flagged as sensitive pause for the user's approval and resume when they answer.
4. Learn — when a task completes cleanly, Nemo can save a generalized version of the approach as a skill and adapt it the next time a similar task comes in. Recurring requests ("check my inbox every morning") become routines.

Every judgment call (routing, planning, skill matching) is an LLM structured-output call validated with Zod, and when something isn't configured Nemo fails honestly instead of faking a result.

Layout

apps/
  api/      Fastify — message ingestion, LinqApp webhook, dev simulator SSE
  worker/   BullMQ — planning, tool execution, approvals, routines, resume
  web/      Next.js — landing page, dev simulator, connections, Auth.js login
packages/
  db/         Drizzle schema + migrations (Postgres), encrypted credential store
  core/       Runtime: intent compiler, planner, permission/approval engines,
              tool registry, memory, skills, routines, audit log
  llm/        LLMProvider interface — Groq and Gemini providers
  messaging/  MessagingChannel interface — LinqApp and dev-simulator channels
  tools/      Gmail/Calendar/Drive (via Composio), web_search (Tavily),
              browser, calculator, notification, verification
  browser/    Playwright-backed BrowserTool
  config/     Shared, schema-validated env loading

Requirements

• Node 20+, pnpm
• Postgres and Redis
• API keys for the services below (only the ones you use)

Service	Used for	Where to get a key
Groq or Gemini	The LLM (LLM_PROVIDER)	console.groq.com/keys, aistudio.google.com/apikey
Composio	Gmail / Calendar / Drive tools	composio.dev dashboard
Tavily	web_search tool (free tier)	app.tavily.com
LinqApp	Real iMessage/SMS/RCS (optional — use the simulator without it)	dashboard.linqapp.com
Google OAuth client	Web login only	Google Cloud Console

Setup

pnpm install
cp .env.example .env    # then fill in the blanks — every variable is documented inline
pnpm run build          # build the shared packages once
pnpm db:generate
pnpm db:migrate

Generate the random secrets (NEMO_CREDENTIAL_ENCRYPTION_KEY, AUTH_SECRET, GATEWAY_AUTH_TOKEN) with:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

.env is gitignored — never commit it.

Running

pnpm dev:api      # :4000
pnpm dev:worker
pnpm dev:web      # :3000

Open http://localhost:3000/simulator to text Nemo from the browser. It calls the same /ingest/message path real messages use, so what you see is the real pipeline, not seeded data.

Security notes

• The dev simulator is unauthenticated. Its endpoints (/users/resolve, /events/stream, and channel: "dev_simulator" on /ingest/message) let anyone who can reach the API spawn tasks and spend your LLM/search quota. They are off unless ENABLE_DEV_SIMULATOR=true — set that for local development only, never on a publicly reachable deployment.
• The LinqApp webhook (/webhooks/linq) verifies an HMAC signature over the raw request body using LINQ_WEBHOOK_SECRET.
• OAuth/connection credentials are encrypted at rest with AES-256-GCM (NEMO_CREDENTIAL_ENCRYPTION_KEY) and never reach an LLM prompt.
• Gmail/Calendar/Drive access goes through Composio; the web app's Google login only requests basic identity scopes.

A note on "spec §N" comments

Comments throughout the code cite sections of the original product spec (e.g. "spec §19"). That document isn't part of this repository; the comments still explain the intent of the code they sit on.

License

Nemo is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only). If you run a modified version as a network service, the AGPL requires you to make your modified source available to its users.