Quickstart — Romance Companion (恋爱陪伴样板)

Build a working AI-companion app — persistent memory, relationship progression, streaming chat — in about 10 minutes. This is the flagship sample: the same architecture the Pouchy demo app runs on.

What you get: a project seeded with two polished companion presets (苏黎 · girlfriend, 沈屿 · boyfriend), a Node backend that exchanges your secret key for per-user session tokens, and a browser client on the companion SDK. Every end user automatically gets their own instance — own memory, own relationship arc — with zero per-user setup.

1. Create the project

Dashboard → 新建项目 → template 恋爱陪伴 → create. The project arrives with both agents already published. (Or in one API call:)

curl -X POST https://pouchy.ai/v1/projects \
  -H "Authorization: Bearer <FIREBASE_ID_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My companion app", "template": "romance", "createKey": true }'
# → { project, agents: [苏黎, 沈屿], secretKey: { key: "pchy_sk_…" } }  # key shown ONCE

Grab an agent id from the response (or the dashboard agent header), and the secret key. Use a pchy_sk_test_… key while developing — test users never count toward your plan's MAU.

2. Mint session tokens on YOUR backend

The secret key never ships to a browser. Your server swaps (agent, your own user id) for a short-lived session token; first-seen user ids are auto-provisioned:

// server.js — Express
import express from 'express';
const app = express().use(express.json());

app.post('/api/companion-session', async (req, res) => {
  const r = await fetch('https://pouchy.ai/v1/sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.POUCHY_SECRET_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      agent: process.env.POUCHY_AGENT_ID,        // 苏黎 or 沈屿
      external_user_id: req.auth.userId,         // YOUR user id — any stable string
      expires_in: 3600
    })
  });
  res.status(r.status).json(await r.json());     // { session_token, expires_in, instance }
});

app.listen(3000);

3. Connect the client

<script type="module">
  import { createCompanion } from '@pouchy_ai/companion-sdk';

  const { session_token } = await (await fetch('/api/companion-session', { method: 'POST' })).json();

  const companion = createCompanion({ baseUrl: 'https://pouchy.ai', token: session_token });
  await companion.connect();
  companion.onMessage((text) => appendBubble('her', text));   // streamed reply
  companion.start();

  await companion.sendText('晚上好呀，今天加班到现在……');
</script>

That's the whole loop. Re-mint a token whenever one expires (≤24 h) — the instance and its memory persist across sessions, so 苏黎 remembers last week's conversation.

4. What makes it a companion, not a chatbot

  • Memory is automatic — facts the user shares are captured after each turn and recalled in later sessions. Nothing to build.
  • Relationship progression — the persona warms up over time (the seeded prompts encode the arc; tune it in the dashboard's 人格 tab — edits bump templateRev and roll out on each user's next session).
  • Voice — await companion.connectCall() upgrades to live voice.
  • Moderation — suspend / GDPR-erase any end user from the dashboard's 终端用户 page; suspended users are refused at the next mint.

5. Ship it

Publish state, key rotation, MAU usage and per-user fair-use live in the dashboard. The free tier includes 10 monthly active end users forever — upgrade when your app grows past that.

Full API surface: companion-api-reference.md · SDK events: companion-sdk-protocol.md