yous 0.1.0

You(s) – a personal wiki-first AI agent

You(s)

A personal CLI agent that learns who you are — and gets smarter every day.

You(s) is a wiki-first AI agent that lives in your terminal. It reads your Obsidian vault before it does anything else, learns your writing style, your code preferences, your active projects, and your thinking patterns — and uses that context to produce work that actually sounds like you.

Unlike a generic chatbot, You(s) knows your vault. It never re-derives what it already knows, never silently overwrites your files, and never makes a move without your approval.

---

What You(s) Can Do

You talk to it in plain English. It figures out what to do.

"search my wiki for LoRA"
"write a 3-page project proposal for my agent"
"debug this error in main.py"
"break down my goal of building the ingest pipeline into tasks"
"what do people on Reddit say about ChromaDB vs Pinecone?"
"deploy my project to the VPS"
"buy 100 TSLA paper"
"find flights from KL to London in mid-June, 2 pax"
"what's the regime on BTC right now?"
"put this data in a Google Sheet"

No commands to memorise for getting work done. If the intent is ambiguous, You(s) asks exactly one clarifying question — with multiple-choice options — before doing anything.

---

Feature Overview

Wiki — The Core

You(s) treats your Obsidian vault as its primary brain. Every response draws from your wiki before falling back to model reasoning or the internet.

• Semantic search via ChromaDB
• Read, create, and update wiki pages with diff preview and approval gate
• 4-stage ingest pipeline for PDFs and raw sources
• Skill page auto-creation after hard problems (so solutions are never re-derived)
• Persistent vault map — You(s) never loses track of file locations between sessions

Coding

• Generate, refactor, and debug code in your preferred language and style
• Style and library preferences extracted from your wiki automatically
• Critique gate reviews output before delivery

Writing

• Produce Word documents (.docx) or Google Docs from natural language
• Tone and structure pulled from your wiki preferences
• Draft → outline approval → full document → critique → export

Planning

• Break any high-level goal into concrete, prioritised tasks
• Context-aware: reads your hot.md and active projects first
• Plans saved to /wiki/plans/ and updatable with natural language mid-session

Research

• Web search, official docs, GitHub issues, Reddit discussions
• Results synthesised into a coherent answer
• Prompted to save findings back into your wiki

Trading Mode (paper only in v1.1)

Auto-detected from intent — no command needed.

• Regime detection, watchlist scans, trade-check against risk rules
• Journal: log entries, close trades, view P&L, run backtests
• Paper execution via MooMoo (Futu OpenD required)
• Risk rules enforced: 2% max risk, 2:1 min R:R, 2 max open positions
• Live trading locked behind a config flag; every live order requires Telegram confirmation before it executes

Google Drive, Sheets, and Excel

• Create, read, and edit Google Sheets or local .xlsx files
• Read and write files inside your Google Drive workspace
• Single OAuth grant covers Drive, Sheets, and Docs
• Default scope: /My Drive/You(s) Workspace/ — full Drive access is opt-in

Trip Planning

Auto-detected from intent — no command needed.

• Flight search via Amadeus; results link to Trip.com, Google Flights, and Skyscanner
• Hotel comparison across Booking.com, Agoda, and Trip.com
• Day-by-day itinerary generation with POIs and weather context
• Booking tracking saved to your vault
• Google Sheets or Google Docs export on request
• VPS trip reminders: 48h, 24h, and day-of alerts via Telegram (if VPS is configured)

DevOps

• VPS deployment via SSH, Dockerfile generation, Docker build and run
• GitHub Actions and GitLab CI config generation
• CI/CD pipeline status via GitHub API

Frontend

• React, Vue, or framework of your preference (read from wiki)
• Figma MCP integration for visual output alongside code (optional, connect via /mcps)

Observability

• Full activity log at ~/.yous/logs/YYYY-MM-DD.log
• Token usage and API cost breakdown per session
• Alerts for errors and high token usage

---

Vault Safety

You(s) never silently writes to your vault. Every file write goes through a guarded pipeline:

1. Vault map lookup — path is always resolved from the persistent ~/.yous/vault_map.json, never re-derived
2. Name collision check — if a file with that name exists elsewhere, You(s) stops and asks
3. Content similarity check — if similar content already exists (Chroma similarity > 0.85), You(s) asks before creating a duplicate
4. Folder confirmation — if the target folder is new, You(s) confirms before creating it
5. Diff preview — every write shows a unified diff in the terminal before anything is applied
6. Approval gate — [y/n/e] — apply, cancel, or open in your editor
7. .bak file — created before every overwrite, no exceptions

In /mode auto, the diff is still shown but the write proceeds automatically after a 2-second pause so you can Ctrl+C.

---

Memory and Personalisation

Style Learning

At session start, You(s) scans your wiki and builds a style profile:

• Preferred coding language and libraries
• Explanation depth and tone derived from how you write
• Active projects and current priorities from hot.md
• Opinions and decisions from origin: self-written pages — never contradicted

Life Profile Onboarding (requires VPS)

You(s) asks you one question per day via Telegram, drawn from a 1,500-question life profile spanning your history, values, cognitive style, and personality. Answers are written to your vault locally and build into:

• /wiki/identity/life-profile.md — a continuously updated personal knowledge base
• Your style profile JSON — tone, depth, active topics
• The "About Me" block in hot.md — loaded every session

No duplicate questions, ever. Skipped questions are archived and replaced. The daily question fires from the VPS at your configured time — your local machine does not need to be on.

---

VPS Backend — 24/7 Autonomous Core (optional)

You(s) works fully offline. The VPS backend adds the ability to run scheduled work — market scans, daily questions, Telegram alerts — without your local machine being on.

Architecture

┌─────────────────────────────────────────┐
│         VPS — You(s) Cloud Core         │
│  (runs 24/7)                            │
│                                         │
│  • Job Scheduler (APScheduler)          │
│  • Telegram Bot (send & receive)        │
│  • OpenTrader market scans              │
│  • MCP-Trading signal engine            │
│  • Job Queue (Redis or SQLite)          │
│  • Auth / API gateway                   │
└────────────────┬────────────────────────┘
                 │  HTTPS + mutual TLS
                 │  Jobs ↓     Results ↑
┌────────────────┴────────────────────────┐
│       Local Device — You(s) Client      │
│  (runs when machine is on)              │
│                                         │
│  • Full vault access (local only)       │
│  • Executes jobs received from VPS      │
│  • Sends back result summaries only     │
│  • Raw vault content never leaves       │
└─────────────────────────────────────────┘

The VPS dispatches instructions. Your local client executes them against your vault. Only summaries and confirmations are returned — raw file content never leaves your device.

Security

• mTLS — both sides authenticate; connections cannot be impersonated
• API key — hashed with bcrypt server-side; rotates with immediate invalidation via /config server rotate-key
• Ed25519 device keypair — mandatory for all VPS connections; private key never leaves your device; every job result is signed and verified before the VPS accepts it
• No vault exposure — the VPS never sees raw file content, wiki page text, or local filesystem paths

Connect to a VPS

yous config server connect --host https://your-vps-ip --key YOUR_API_KEY

VPS Setup

git clone https://github.com/yous-ai/yous-server
cd yous-server
uv sync
cp config.example.yaml config.yaml
# Edit config.yaml: Telegram token, user API keys, scheduler settings
uv run yous-server start

Recommended spec: 8 GB RAM / 4 vCPU / 75 GB NVMe. A Caddy reverse proxy handles TLS. The server runs as a systemd service or Docker container.

---

Install

Python 3.11+ is required. Choose whichever install method suits you.

# Recommended for developers
pipx install yous

# macOS
brew install yous-ai/tap/yous

# Windows
scoop install yous

# uv users
uv tool install yous

After any method, open any terminal and type:

yous

First-Run Setup

On first launch, a setup wizard walks you through configuration in about 2 minutes:

Welcome to You(s) v1.1

? Where is your Obsidian vault?  ~/vault
? Which LLM provider?            DeepSeek
? Enter your DeepSeek API key:   ••••••••
? Connect Google Drive?          Yes  ← opens browser for OAuth
? Enable Telegram alerts?        Yes
? Telegram Bot Token:            ••••••••
? Telegram Chat ID:              ••••••••

Setup complete. Type 'yous' anytime to start.

Shell Completion

yous --install-completion

---

Slash Commands

Slash commands are for controlling You(s) itself. Everything else is natural language.

Command	Description
/help	Show all slash commands and agent capabilities
/new	Start a new session (clears session memory, wiki is preserved)
/sessions	List all past sessions with timestamps and summaries
/session <id>	Resume or inspect a past session
/agents	List available agent personas / switch between them
/skills	List all skill pages in /wiki/skills/
/mcps	List currently connected MCP servers
/mode ask	Ask before every action (default)
/mode auto	Act and log — still shows diffs before writes
/logs	Show recent activity log
/logs sync	Force all pending log writes immediately
/cost	Show API cost breakdown for this session
/audit	Run vault linting — orphan pages, broken links, path reconciliation
/style	Show your current style profile derived from the wiki
/config	Open config file for editing
/config env	Show the environment/app cache as a table
/config env clear	Wipe the env cache and re-discover on next use
/config drive full-access	Enable full Google Drive access beyond the default workspace folder
/config server connect	Connect local client to a VPS backend
/config server rotate-key	Rotate VPS API key (old key invalidated immediately)

---

Configuration

Key config paths:

Path	Purpose
~/.yous/config.yaml	Main configuration
~/.yous/.env	API keys and secrets
~/.yous/vault_map.json	Persistent vault file index
~/.yous/env_cache.json	Cached environment paths (OpenD, etc.)
~/.yous/credentials/google_token.json	Google OAuth token
~/.yous/credentials/device_key.pem	Ed25519 private key (chmod 600)
~/.yous/onboarding/	Life profile question state
~/.yous/logs/	Activity logs

Key config options:

logs:
  auto_update: true           # set false to disable automatic log writes
  write_on_significant: true
  write_on_session_end: true

writes:
  diff_preview: true          # set false to skip diff display (power users only)
  auto_apply_delay_seconds: 2 # pause in auto mode before applying

trading:
  allow_real_execution: false # must be true to place live orders
  default_trd_env: SIMULATE
  confirmation_timeout_seconds: 60

env_cache:
  stale_after_days: 7

---

Tech Stack

Layer	Tool
Language	Python 3.11+
LLM — fast tasks	DeepSeek V4 Flash
LLM — reasoning	DeepSeek V4 Pro
LLM — high-stakes decisions	DeepSeek V4 Pro + thinking mode
Semantic search	ChromaDB
CLI	rich + prompt_toolkit
Word docs	python-docx
Spreadsheets	Google Sheets API + openpyxl
Google integration	google-api-python-client
Session storage	SQLite
Trading	OpenTrader + MCP-Trading + MooMoo (Futu OpenD)
Flights	Amadeus API
Places / geocoding	Google Places API
Weather	OpenMeteo
SSH / DevOps	paramiko + Docker SDK
Logging	Python logging + structured JSON

---

Provenance and Quality Control

• All agent-generated content is tagged origin: agent-compiled
• All user-written content is tagged origin: self-written
• You(s) cannot overwrite origin: self-written pages without explicit confirmation
• Every wiki write creates a .bak before overwriting
• The critique gate (DeepSeek Pro self-review) runs on all outputs before delivery
• Conflicts are flagged in the change plan — never silently resolved
• Schema linting available via /audit

---

Version

v1.1 — Current
v1.0 — Foundation release

You(s) is a personal project, actively developed.