Teya

A personal AI assistant that grows with your business.

It remembers your clients, tracks your tasks, monitors your metrics, and gets smarter the more you use it. When something needs your attention, it reaches out.

It's yours to shape: Give it a name, a personality, specialized skills, and a team of sub-agents. Talk to it from the terminal, Telegram, or any channel -- same memory everywhere.

It runs on your terms: Use cloud models for power, or run fully offline with local LLMs. Your data never leaves your machine unless you want it to. Sandboxed tools, permission engine, credential isolation.

---

Personality and intelligence

Area	Summary
Memory engine	Remembers what matters. Knowledge graph stores entities, facts, and relations extracted from every conversation. Hybrid search (semantic + keyword) finds relevant context instantly.
Session intelligence	Learns from every interaction. Background process summarizes sessions, extracts topics, and builds a structured understanding of your preferences, projects, and patterns over time.
Identity layer	Defines who the assistant is. Behavior lives in SOUL.md. Operating instructions, workflows, and checklists in AGENTS.md. Each sub-agent has its own personality and expertise.
Autonomous scheduling	Works while you sleep. Standalone daemon executes tasks on cron -- competitor monitoring, report generation, data collection. Retries on failure, catches up on missed windows, full execution history.
Sub-agent delegation	The right agent for the right job. Create specialized agents (@researcher, @analyst, @writer) and mention them directly. Tasks route to the agent with the right skills and context.

Infrastructure and security

Area	Summary
Privacy	Your data stays yours. Sandboxed workspace -- the agent writes to its own directory, not yours. Run fully offline with Ollama. Zero external calls when you need it.
Permission engine	Defaults to safe. Allow-all, ask-before-acting, rule-based, or deny-all modes. DLP guard blocks data exfiltration. Credentials never reach the model.
Skills	Add capabilities through plugins. Manifest-driven skills with tools and prompt sections. Install from GitHub, URL, local directory, or Teya's bundled verified catalog. Sandboxed execution.
Channels	One assistant, everywhere. CLI with image paste and @mentions. Telegram bot. Same memory, same personality, same skills across all channels.
Any LLM	Swap models without changing anything. OpenRouter (100+ models), Ollama (local), or mix them with multi-model routing. Automatic fallback chains.
Observability	See everything the agent does. OTEL-compatible tracing to console, JSON files, or Jaeger/Tempo/Datadog. Every LLM call, tool execution, and delegation tracked with cost and latency.

---

Getting started

CLI

git clone https://github.com/esporykhin/teya.git
cd teya
pnpm install && pnpm -r build

cd packages/cli && npm link && cd ../..

teya    # interactive setup on first run

Fully local (no cloud, no API keys)

ollama serve
teya --provider ollama --model qwen3:8b

Cloud (100+ models)

teya --provider openrouter --api-key YOUR_KEY

Telegram Bot

teya --transport telegram --telegram-token BOT_TOKEN

Telegram Userbot (MTProto)

Connect your real Telegram account -- Teya reads and writes messages as you, no bot needed.

# First time: interactive login (phone + code + optional 2FA)
teya telegram login

# Run
teya --transport telegram-userbot

Requires api_id and api_hash from my.telegram.org/apps. By default responds only in Saved Messages. Use --telegram-allowed-chats to whitelist chats or --telegram-trigger "!t " to invoke via prefix in any chat.

See transport-telegram/README.md for full setup guide.

Scheduler

teya scheduler start      # background daemon
teya scheduler install    # auto-start on boot (macOS)
teya scheduler status     # active tasks, execution history

---

Sub-agents

Create specialized agents in ~/.teya/agents/:

~/.teya/agents/researcher/
  SOUL.md       # "You are a web research specialist..."
  AGENTS.md     # workflows, checklists, operating instructions
  config.json   # {"description": "...", "provider": {"type": "ollama", "model": "qwen3:32b"}}

Mention them in conversation: @researcher find the top 5 competitors in this space

The main agent sees all sub-agents and delegates automatically when the task matches.

---

Skills

Teya supports two skill sources:

• Installed skills in ~/.teya/skills/
• Bundled verified skills in packages/skills/verified/

Verified skills are the curated built-in option. They do not block installing external skills from GitHub, URL, or a local folder.

Verified skills live in the repository as regular Claude-style skill folders:

packages/skills/verified/
  digest/
    SKILL.md
    tables.md
    templates/
      digest-outline.md
  market-research/
    SKILL.md
  sales-pipeline/
    SKILL.md
    tables.md
    templates/
      pipeline-review.md
  personal-stylist/
    SKILL.md
    templates/
      wardrobe-plan.md
  nutrition-coach/
    SKILL.md
    tables.md
    templates/
      nutrition-plan.md

Each skill is a full folder, not a single markdown file. It can ship prompt instructions, templates, scripts, helper docs, and assets in one installable unit.

Recommended frontmatter for a verified skill:

---
name: digest
description: Build recurring digests from structured sources.
category: content
audience: both
domains: ["content", "research", "operations"]
triggers: ["digest", "newsletter"]
tags: ["content", "sources", "tables"]
inputs: ["goal", "sources", "audience"]
outputs: ["source registry", "digest"]
order: 10
---

Recommended taxonomy for a larger catalog:

• Keep one folder per skill. A skill can include SKILL.md, scripts/, templates/, assets/, and helper docs.
• Use audience for business / personal / both.
• Use category as a compact library bucket like content, research, finance, style, health.
• Use domains for stable topical grouping like marketing, operations, wellbeing, career, sales.
• Use tags for looser discovery terms and UI search, not as the primary taxonomy.

List the curated catalog:

teya skill verified

Install a verified skill:

teya skill add verified:market-research

Current verified catalog:

Skill	Audience	Category	What it does
digest	both	content	Builds recurring or one-off digests from structured sources and keeps the source registry in Teya tables.
market-research	business	research	Analyzes markets, competitors, pricing, and demand signals before a product or growth decision.
sales-pipeline	business	sales	Creates and maintains a lightweight sales pipeline in Teya tables, including next actions and review cadence.
personal-stylist	personal	style	Turns goals, wardrobe constraints, and context into a practical style direction and outfit plan.
nutrition-coach	personal	health	Builds a sustainable nutrition routine and, when useful, keeps goals and check-ins in Teya tables.

Catalog shape:

• business: tools like research, sales, operations, finance, content workflows.
• personal: tools like style, nutrition, wellbeing, routines, learning.
• both: reusable workflows that work for either side, like digest.

---

Architecture

14 modular packages -- swap any part:

Package	What it does
core	Agent loop, types, system prompt, security
providers	OpenRouter, Ollama, routing, fallback chains
tools	Built-in tools, MCP client, sandboxed workspace
memory	Knowledge graph, sessions, assets, intelligence
scheduler	Task store, cron engine, daemon, multi-agent dispatch
orchestrator	Sub-agent registry, delegation, isolated execution
skills	Skill loader, trigger matching, installer
tracing	OTEL spans, console/JSON/OTLP exporters
eval	E2E test runner, side-effect scoring
transport-cli	Terminal UI, image paste, @mentions
transport-telegram	Telegram bot + userbot (MTProto)
context	Context window management, condensation
data	YAML schema to SQLite CRUD
cli	Entry point, config, subcommands

---

Development

pnpm -r build                          # build all
pnpm test                              # tests
teya eval run evals/core-tools.yaml    # e2e evals against live LLM

TDD workflow: write eval first, then implement until all checks pass.

---

License

MIT -- use it however you want, commercially or personally.

Built by Evgeny Sporykhin.