KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#codex #developer-tools #typescript #ai-agents #claude-code #python #mcp #react #cli #macos #ai-agent #deepseek-harness

Yours-A-more-thoughtful-AI-companion

★ 103 Open GitHub ↗

An AI companion that grows with you, supporting OpenClaw/Hermes. A better HER.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Yours

AI companion product · first phase of Everlasting 
 <a href="./READMEcn.md">中文说明</a>
 ·
 <a href="#architecture">Architecture</a>
 ·
 <a href="#quick-start">Quick start</a>
 ·
 <a href="#frameworks--memory">Frameworks &amp; memory</a>
 ·
 <a href="#acknowledgments--open-source">Acknowledgments</a>

---

## Everlasting and Yours

**Everlasting** explores digital persistence in an AI-native world: video, image, voice, and memory so companions can feel present, keep a personality, and grow over time.

**Yours** is the first shipping product in that line — a chat companion with an in-page Live2D pet, optional agent runtimes (OpenClaw / Hermes), and a three-layer memory OS.

| Today | Coming later |
|-------|----------------|
| **Bella** is the only product-available persona | Other cast on the banner (Hikari / Aria / Noa) are architectural placeholders |
| Local login required; Settings shell with Companion / Agent / Appearance (6 UI languages + spoken voice profile) | Google OAuth (UI stub only) |
| Page pet + TTS lip-sync | System desktop pet shell |

The banner art is an **original cast illustration**, not Live2D Haru and not AIRI character assets. The stage pet currently uses the **Live2D official Haru sample** as a temporary model (see Acknowledgments).

---

## Architecture

Yours is a monorepo: **React + Vite** frontend, **Node** backend, **PostgreSQL** (+ **pgvector** for companion memory), and optional **external** OpenClaw / Hermes executors.

Conversation is **not** one flat LLM call. It is three stages:

1. **Intent** — classify the turn (chat vs task vs media…)  
2. **Execution** — light sync completion, or agent runtime (OpenClaw / Hermes)  
3. **Persona** — rewrite into Bella’s voice using fixed SOUL + memory context

### Big picture

```mermaid
flowchart TB
  subgraph client [Browser]
    UI[Yours_UI_and_Live2D_pet]
  end

subgraph yours [Yours_backend]
    Chat["POST_/api/assistant/chat"]
    Intent[Intent_router]
    Branch{Light_or_runtime}
    Sync[Direct_LLM]
    Runtime[AgentRuntimeRouter]
    OC[OpenClawAdapter]
    HM[HermesAdapter]
    Outer[Outer_persona_LLM]
    MemOS[Memory_OS_L1_L2_L3]
    Chat --> Intent --> Branch
    Branch -->|chat_only| Sync --> Outer
    Branch -->|tools_files_media| Runtime
    Runtime --> OC
    Runtime --> HM
    OC --> Outer
    HM --> Outer
    MemOS -.-> Intent
    MemOS -.-> Outer
  end

subgraph data [Data]
    PG[(Postgres_pgvector)]
    GB[gbrain_CLI]
  end

subgraph ext [External_not_vendored]
    GW[OpenClaw_Gateway]
    HC[Hermes_CLI]
  end

UI --> Chat
 Outer --> UI
 Chat --> PG
 MemOS --> PG
 MemOS --> GB
 GB --> PG
 OC <--> GW
 HM <--> HC
```

### Layers in words

| Layer | What it does | Where |
|-------|----------------|-------|
| Intent | Decides chat vs runtime; hybrid LLM + rules | `bellaIntentClassifier.ts` |
| Execution | Sync LLM **or** OpenClaw / Hermes by registered framework | `AgentRuntimeRouter`, adapters |
| Persona | Final user-visible Bella reply; never dumps raw tool logs | `bellaComposer.ts`, `bellaPersona.ts`, `docs/templates/Bella-SOUL.md` |
| Memory OS | L1 session in Postgres; L2/L3 + digest via gbrain, keyed by **CompanionBond** | `MEMORY_OS_V1.md` |
| Pet | Shared Live2D engine; model URL from companion registry | `COMPANION_PET_DESIGN.md` |

**Important gate:** agent adapters run only when `ASSISTANT_CHAT_PROVIDER=openclaw` (or legacy `clawra`). If the provider stays `openai` / similar, the stored framework is unused and chat stays on the direct LLM path. Details: [`docs/FRAMEWORKS_AND_MEMORY_USAGE.md`](docs/FRAMEWORKS_AND_MEMORY_USAGE.md).

### Account vs companion instance

```mermaid
flowchart LR
  Account[Human_account] --> BondA[Bella_bond_work]
  Account --> BondB[Bella_bond_life]
  BondA --> MemA[Memory_namespace_A]
  BondB --> MemB[Memory_namespace_B]
  BondA --> Tmpl[Template_bella_SOUL_Live2D]
  BondB --> Tmpl
```

One login can own many **Bella** instances (different names, isolated memory). Persona SOUL is template-fixed — users do not edit it. Spec: [`docs/COMPANION_ACCOUNT_IDENTITY_DESIGN.md`](docs/COMPANION_ACCOUNT_IDENTITY_DESIGN.md).

### Chat request path

```text
message + bondId
  → auth required
  → load L1 (+ L2/L3 packet if memory on)
  → intent
  → sync reply  OR  OpenClaw/Hermes job
  → outer persona
  → reply (+ media / downloads / jobId)
  → async memory write / harvest
```

Framework is chosen **once at registration** (`openclaw` | `hermes`). Settings show it read-only. Ops may override with `POST /api/auth/ops/set-framework` when `BELLA_ALLOW_FRAMEWORK_OVERRIDE=1` (no migrate).

Deeper notes: [`docs/ARCHITECTURE_AND_REFACTOR.md`](docs/ARCHITECTURE_AND_REFACTOR.md).

---

## Quick start

**Need:** Node.js + npm, Docker, Git.

**This section is Tier A only** — chat + L1 + pet. It does **not** install OpenClaw, Hermes, or gbrain.

```bash
# 1) deps
cd backend && npm install && cd ../frontend && npm install

# 2) env
cp backend/.env.example backend/.env
# set POSTGRES_PASSWORD=… (DATABASE_URL optional — auto-built from POSTGRES_*)

# 3) database
cd .. && npm run docker:db
cd backend && npm run prisma:deploy && npx prisma generate

# 4) run (two terminals)
cd backend && npm run dev          # http://localhost:3001/health
cd frontend && npm run dev         # http://localhost:5173 → /bella
```

1. Register the first account (empty user table allows register; later use `BELLA_ALLOW_REGISTER=1`).  
2. Pick **OpenClaw** or **Hermes** at sign-up (stored; may not execute until Tier C).  
3. Set an LLM API key in `backend/.env` for your `ASSISTANT_CHAT_PROVIDER` (default `openai` → `OPENAI_API_KEY`).

| Tier | What you get | Follow |
|------|--------------|--------|
| **A** Minimal chat (this section) | Postgres, Prisma, LLM key, `/bella`, L1 | below + [`docs/LOCAL_SETUP.md`](docs/LOCAL_SETUP.md) |
| **B** Long-term memory | + gbrain CLI + init same DB → L2/L3 + `/bella/memory` | [`docs/COMPANION_AUTH_GBRAIN.md`](docs/COMPANION_AUTH_GBRAIN.md) |
| **C** Agent executor | + `ASSISTANT_CHAT_PROVIDER=openclaw` + OpenClaw gateway **or** Hermes CLI | [`docs/FRAMEWORKS_AND_MEMORY_USAGE.md`](docs/FRAMEWORKS_AND_MEMORY_USAGE.md), [`docs/OPENCLAW_SETUP.md`](docs/OPENCLAW_SETUP.md) |

Coding agents: use the checklist **[`docs/CODING_AGENT_SETUP.md`](docs/CODING_AGENT_SETUP.md)**.  
Self-check: `npm run doctor` (postgres / llm_key / gbrain / gateway / hermes / soul).  
Memory migration (spec only): [`docs/MEMORY_BUNDLE_SPEC.md`](docs/MEMORY_BUNDLE_SPEC.md).

WSL one-click helper: `scripts/dev-start.bat` (still run Prisma yourself).

**Production build** (repo root): `npm run build`.

---

## Frameworks & memory

| Piece | Status | How to use |
|-------|--------|------------|
| **OpenClaw** | Ready when gateway + env set | `ASSISTANT_CHAT_PROVIDER=openclaw`, `OPENCLAW_GATEWAY_*`, register OpenClaw |
| **Hermes** | Partial (thin CLI adapter) | Same provider gate + `HERMES_*`; register Hermes; smoke via `npm run test:hermes-smoke` |
| **L1 memory** | Ready | Postgres sessions/turns |
| **L2 / L3 / digest** | Ready if gbrain on | CLI + init; Settings → Companion toggles; edit `/bella/memory` |

```mermaid
flowchart LR
  Turn[Chat_turn] --> L1[L1_Postgres]
  Turn --> L2[L2_gbrain_prefs]
  Turn --> L3[L3_gbrain_episodes]
  L1 --> Packet[Context_packet]
  L2 --> Packet
  L3 --> Packet
  Packet --> Persona[Outer_persona]
```

Full operator guide (env, gates, limits): **[`docs/FRAMEWORKS_AND_MEMORY_USAGE.md`](docs/FRAMEWORKS_AND_MEMORY_USAGE.md)**.  
UI / spoken voice / TTS locales: **[`docs/UI_I18N_AND_VOICE_LOCALES.md`](docs/UI_I18N_AND_VOICE_LOCALES.md)**.  
Contracts: [`docs/MEMORY_OS_V1.md`](docs/MEMORY_OS_V1.md).

---

## Documentation

| Start here | |
|------------|--|
| [`docs/LOCAL_SETUP.md`](docs/LOCAL_SETUP.md) | Minimal local run |
| [`docs/CODING_AGENT_SETUP.md`](docs/CODING_AGENT_SETUP.md) | Agent-friendly Tier A/B/C checklist |
| [`docs/MEMORY_BUNDLE_SPEC.md`](docs/MEMORY_BUNDLE_SPEC.md) | Memory Bundle export/import spec (not implemented) |
| [`docs/UI_I18N_AND_VOICE_LOCALES.md`](docs/UI_I18N_AND_VOICE_LOCALES.md) | Six UI locales, voice profiles, providers inventory |
| [`docs/UI_UX_DESIGN_SYSTEM.md`](docs/UI_UX_DESIGN_SYSTEM.md) | Visual design tokens, CSS layers, component recipes |
| [`docs/FRAMEWORKS_AND_MEMORY_USAGE.md`](docs/FRAMEWORKS_AND_MEMORY_USAGE.md) | OpenClaw / Hermes / memory how-to |
| [`docs/COMPANION_AUTH_GBRAIN.md`](docs/COMPANION_AUTH_GBRAIN.md) | Auth + Postgres + gbrain ops |
| [`docs/COMPANION_ACCOUNT_IDENTITY_DESIGN.md`](docs/COMPANION_ACCOUNT_IDENTITY_DESIGN.md) | Account / bonds / settings spec |
| [`docs/COMPANION_PET_DESIGN.md`](docs/COMPANION_PET_DESIGN.md) | Live2D pet spec |
| [`docs/MEMORY_OS_V1.md`](docs/MEMORY_OS_V1.md) | L1/L2/L3 contracts |
| [`docs/OPENCLAW_SETUP.md`](docs/OPENCLAW_SETUP.md) | Gateway wiring |
| [`docs/OPENCLAW_SKILLS_SETUP.md`](docs/OPENCLAW_SKILLS_SETUP.md) | Skills index |

<details>
<summary>More docs (architecture, deploy, per-skill guides)</summary>

### Architecture & product

| Document | Contents |
|----------|----------|
| [`docs/ARCHITECTURE_AND_REFACTOR.md`](docs/ARCHITECTURE_AND_REFACTOR.md) | Stack map and refactor notes |
| [`docs/OPENCLAW_DECISION_FLOW.md`](docs/OPENCLAW_DECISION_FLOW.md) | OpenClaw decision / SOUL notes |
| [`docs/BELLA_CAPABILITIES_AND_SKILLS.md`](docs/BELLA_CAPABILITIES_AND_SKILLS.md) | Capabilities overview |
| [`docs/COMPANION_IMPL_WAVE1.md`](docs/COMPANION_IMPL_WAVE1.md) | Spec compliance matrix |
| [`docs/HARVEST_MAPPING.md`](docs/HARVEST_MAPPING.md) | Framework MEMORY → layers |
| [`docs/ENVIRONMENT_SETUP.md`](docs/ENVIRONMENT_SETUP.md) | Env conventions |
| [`NODE_AND_LOCALHOST.md`](NODE_AND_LOCALHOST.md) | Localhost troubleshooting |
| [`docs/WSL_MIGRATION.md`](docs/WSL_MIGRATION.md) | WSL notes |
| [`docs/GITHUB_RELEASE_CHECKLIST.md`](docs/GITHUB_RELEASE_CHECKLIST.md) | Release checklist |

### OpenClaw extras

| Document | Contents |
|----------|----------|
| [`docs/OPENCLAW_CHINA_WORLD_MODE.md`](docs/OPENCLAW_CHINA_WORLD_MODE.md) | China vs world mode |
| [`docs/SKILL_CONVENTION_CHINA_WORLD.md`](docs/SKILL_CONVENTION_CHINA_WORLD.md) | Skill authoring by region |
| [`docs/OPENCLAW_PYTHON_VENV_UNIFIED.md`](docs/OPENCLAW_PYTHON_VENV_UNIFIED.md) | Shared Python venv |
| [`docs/OPENCLAW_SANDBOX_UPGRADE.md`](docs/OPENCLAW_SANDBOX_UPGRADE.md) | Sandbox upgrade |
| [`docs/OPENCLAW_WEB_FETCH_SSRF_AND_DNS.md`](docs/OPENCLAW_WEB_FETCH_SSRF_AND_DNS.md) | SSRF / DNS |
| [`docs/WEATHER_SKILL_DIAGNOSTIC.md`](docs/WEATHER_SKILL_DIAGNOSTIC.md) | Weather skill debug |
| [`docs/HERMES_SMOKE_TEST.md`](docs/HERMES_SMOKE_TEST.md) | Hermes CLI smoke |

### Per-skill setup

See index [`docs/OPENCLAW_SKILLS_SETUP.md`](docs/OPENCLAW_SKILLS_SETUP.md). Individual guides: `docs/OPENCLAW_SKILL_*_SETUP.md` (pdf, docx, pptx, xlsx, canvas-design, frontend-design, media-image, media-video, web-to-markdown, markitdown*, taobao / china e-commerce price skills).

### Deploy & providers

| Document | Contents |
|----------|----------|
| [`docs/HANDS_ON_GUIDE.md`](docs/HANDS_ON_GUIDE.md) | MiniMax + OpenClaw hands-on |
| [`docs/BELLA_MINIMAX_SETUP.md`](docs/BELLA_MINIMAX_SETUP.md) | MiniMax |
| [`docs/DEPLOY_AWS.md`](docs/DEPLOY_AWS.md) | AWS EC2 / systemd |
| [`docs/AWS_APP_RUNNER_DEPLOY_BELLA.md`](docs/AWS_APP_RUNNER_DEPLOY_BELLA.md) | App Runner |
| [`deploy/PUBLIC_DEPLOY.md`](deploy/PUBLIC_DEPLOY.md) | Public topology |
| [`docs/STAR_OFFICE_DEPLOY_AND_INTEGRATION.md`](docs/STAR_OFFICE_DEPLOY_AND_INTEGRATION.md) | Star Office submodule |
| [`docs/OPTIONAL_SUBMODULES.md`](docs/OPTIONAL_SUBMODULES.md) | Optional submodule pattern |

</details>

### Contributor entry points

- `backend/src/routes/assistant.ts` — chat orchestration, jobs, SSE  
- `backend/src/services/bellaIntentClassifier.ts` — intent  
- `backend/src/services/agent/AgentRuntimeRouter.ts` — OpenClaw / Hermes  
- `backend/src/services/bellaComposer.ts` / `bellaPersona.ts` — persona  
- `frontend/src/companions/registry.ts` — companion templates  
- `frontend/src/components/agent/CompanionSettingsModal.tsx` — Settings UI

Smoke: `npm run test:skill-resolver-smoke`, `test:file-download-smoke`, `test:phase9-smoke:json` (CI: `.github/workflows/phase9-smoke.yml`).

---

## Acknowledgments & open source

Yours builds on, integrates with, or is inspired by the following. **Licenses and terms of each upstream apply**; this list is attribution, not a claim of ownership.

| Project / asset | Role in Yours | Notes |
|-----------------|---------------|--------|
| **[OpenClaw](https://github.com/openclaw)** (ecosystem / gateway) | Optional agent executor & skills | Not vendored; configure via env. See `docs/OPENCLAW_*.md` |
| **Hermes** (external runtime) | Optional thin CLI executor | Not vendored; see `docs/HERMES_SMOKE_TEST.md` |
| **gbrain** | Long-term companion memory CLI | Same Postgres as Yours when enabled |
| **PostgreSQL** + **pgvector** | Primary DB / vectors | Compose uses a pgvector-capable image |
| **React**, **Vite**, **Prisma**, **Express** | App stack | See `package.json` files |
| **PixiJS** + **[pixi-live2d-display](https://github.com/guansss/pixi-live2d-display)** + Live2D Cubism | In-page pet rendering | |
| **Live2D Haru (official Free Material sample)** | Temporary pet model under `frontend/public/live2d/haru/` | © Live2D Inc.; follow Free Material / Sample Data terms. Not a Yours original character. Details: `frontend/public/live2d/README.md` |
| **[moeru-ai/airi](https://github.com/moeru-ai/airi)** and related demos | **Inspiration** for companion UX / realtime voice ideas | Code may be MIT; **art/models are separate**. We do **not** ship unauthorized AIRI demo characters |
| **unspeech** (optional TTS sidecar) | High-quality TTS → lip-sync | AGPL: keep as out-of-process sidecar only |
| OpenClaw **skills** (pdf/docx/pptx/xlsx, markitdown, media, etc.) | Document & media tooling | Per-skill setup docs; respect each skill’s upstream license |

Banner illustration in this README is an **original AI-assisted cast poster** for Yours marketing/docs (Bella / Hikari / Aria / Noa concepts). It is unrelated to Live2D Haru and unrelated to AIRI character assets.

If you are an upstream author and want a wording change, open an issue or PR.

---

## License & contributing

Follow the repository root license file (if present) and contributing conventions in `coding-standard.md`. Do not commit secrets or personal absolute paths in docs or examples.

Yours-A-more-thoughtful-AI-companion

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README