Aura — the household agent that remembers

Build, Ship, Shape: Amazon Developer Hackathon · Alexa+ track · + Open Source mini-challenge

A self-hosted MCP server (Streamable HTTP, protocol 2025-11-25) plus an Agent Skill that gives an Alexa+ style assistant three things it does not have out of the box:

1. Cross-session household memory — who lives here, what they're allergic to, the spend cap, the screen-time curfew, quiet hours, and what the household decided last night.

2. Autonomous re-planning — the agent starts with a plan, then changes it when an observation contradicts it, and says why in a visible timeline.

3. A card and carousel layer — ui:// MCP App templates so the spoken answer stays short while the screen carries the detail, plus a purchase step that refuses to spend without an explicit spoken confirmation.

Say "set up a movie night for everyone" and Aura checks the weather, discovers a 74 % chance of rain, swaps the backyard idea for an indoor film, filters out the PG-13 result because a child is home, drops the priciest snack when the basket blows the ₹2 100 budget, asks before spending above the cap, and commits the night to memory so tomorrow's "what did we watch?" resolves without a single follow-up question.

"Alexa, set up a movie night for everyone"
  ✓ household_profile   Load household rules, members and budget    3 members, budget 25
  ✓ weather_now         Indoors or outdoors decides the plan         Pune: 24.1°, light rain
  ✓ media_search        Candidate titles                            6 result(s)
  ✓ pantry_status       Snacks already in stock                     4 low, allergens peanuts/dairy
  + media_search        RE-PLAN Rain risk 74% → indoor-friendly film
  + learn_fact          RE-PLAN Add a rainy-evening card
  ✓ place_order         Purchase guardrail → needs_confirmation
  ✓ commit_routine      Saved: tomorrow "what did we watch?" just works

Run it

Node 20+ (no API keys, no accounts, no hardware).

npm install
npm start                    # http://localhost:8787

Open http://localhost:8787 — that page is the simulated Alexa+ device the rules allow: a microphone button (Web Speech API), suggestion chips, the card/carousel surface, the live agent timeline, and the household memory inspector.

Two other ways to see it work:

npm run demo      # headless CLI: 4 spoken turns, ASCII cards, full trace, audit log
npm run verify    # 15 acceptance checks (protocol, MCP Apps mime, guardrails, memory)

Deterministic demo data (recommended for recording, because it never shows third-party catalogue titles):

AURA_OFFLINE=1 npm start

Force the clock to show curfew and quiet-hours behaviour on demand:

curl -s localhost:8787/api/agent -H 'content-type: application/json' \
  -d '{"utterance":"good morning","session":"kitchen","hour":23}'

Related MCP server: Aura+

Point a real MCP client at it

npx @modelcontextprotocol/inspector --cli http://localhost:8787/mcp --method tools/list

Claude Desktop / Cursor / Kiro config:

{ "mcpServers": { "aura": { "url": "http://localhost:8787/mcp" } } }

The Agent Skill is served by the server as skill://aura-household/SKILL.md and as the load_agent_skill tool, so any agent that connects picks up Aura's planning policy without reading this repository. To install it as a local skill instead, copy skills/aura-household/ into .kiro/skills/, .claude/skills/ or .github/skills/.

How it is built

src/server.js      McpServer + Streamable HTTP (stateless), 13 tools, 5 resources, 3 prompts,
                   /api/agent (simulated device), /api/resource (MCP Apps host), bearer-token option
src/agent.js       classify -> plan -> act -> observe -> re-plan -> speak
src/memory.js      household profile, sessions, audit log, spend cap, allergen vetoes
src/tools.js       one implementation shared by the MCP surface and the agent
src/services/      open-meteo (weather), iTunes Search (catalogue), HN Algolia (headlines),
                   Wikipedia REST (explainer card), open.er-api (household currency)
src/ui/            index.html + app.js: the simulated Alexa+ device; templates.js: ui:// resources
skills/aura-household/SKILL.md   the Agent Skill (+ references/ for progressive disclosure)
scripts/demo.mjs   headless end-to-end run    tests/verify.mjs   acceptance checks

Every tool result returns content[] (for voice-only clients), structuredContent (for data-only rendering) and _meta.ui.resourceUri (to bind the result to a ui:// template) — the three ways an MCP host can present the same answer.

Why stateless? Alexa+ owns the conversation and replays context from its own history, so a per-connection session would fight it. Household state therefore lives in data/household.json, not in the transport.

Why no LLM in the loop? The planner is a policy engine, so judges can run it offline with zero keys and still see genuine plan/observe/re-plan behaviour. src/agent.js documents the two functions (classify, replan) you swap out to drive the same tools from Bedrock or any tool-calling model — the tool surface, guardrails and memory are unchanged.

Testing instructions for judges

npm run verify prints 15/15 checks passed and exits non-zero on any regression. docs/JUDGING_MAP.md maps each judging criterion to the files and the check that evidences it.

Hackathon compliance

Third-party services

All free and key-less: Open-Meteo (weather/geocoding), iTunes Search API (catalogue), Hacker News Algolia (headlines), Wikipedia REST (explainer), open.er-api.com (currency). Artwork is generated locally as SVG (/art/:title.svg) so the demo never shows third-party posters — set AURA_ALLOW_REMOTE_ART=1 to use catalogue art instead. The household, its members and every media title in the fixtures are invented for the demo.

Feedback, licence, author

Read PRODUCT_FEEDBACK.md for what worked and what did not while building against the Alexa+ MCP toolkit docs, FRICTION_LOG.md for the seven entries with severity and workarounds, and FEATURE_REQUESTS.md for the asks ranked Critical/Important/Nice-to-have.

Apache-2.0 · Abhinav Shukla · Pune, India · October 2026