nomos

<p align="center">
  <img src="images/project-nomos-header.png" alt="Project Nomos" width="100%" />
</p>

<p align="center">
  <strong>An autonomous AI agent that remembers everything, works everywhere, and never stops learning</strong><br/>
  Deploy to Slack, Discord, Telegram, WhatsApp — with persistent memory, multi-agent teams, and a web dashboard. All TypeScript, fully open source.
</p>

<p align="center">
  <a href="#get-running-in-2-minutes">Quick Start</a> &middot;
  <a href="#what-you-get">Features</a> &middot;
  <a href="#advanced-agent-capabilities">Advanced</a> &middot;
  <a href="#daemon-mode">Daemon</a> &middot;
  <a href="#channel-integrations">Channels</a> &middot;
  <a href="#skills-system">Skills</a> &middot;
  <a href="#contributing">Contributing</a>
</p>

<p align="center">
  <a href="https://github.com/project-nomos/nomos/releases"><img src="https://img.shields.io/github/v/release/project-nomos/nomos" alt="Release" /></a>
  <a href="https://github.com/project-nomos/nomos/actions/workflows/ci.yml"><img src="https://github.com/project-nomos/nomos/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="https://github.com/project-nomos/nomos/actions/workflows/docker.yml"><img src="https://github.com/project-nomos/nomos/actions/workflows/docker.yml/badge.svg" alt="Docker" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
  <img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="Node >= 22" />
  <img src="https://img.shields.io/badge/TypeScript-strict-blue.svg" alt="TypeScript Strict" />
  <img src="https://img.shields.io/badge/Claude_Agent_SDK-powered-6B4FBB?logo=anthropic" alt="Claude Agent SDK" />
  <img src="https://img.shields.io/badge/AI-agent_teams-ff6f00" alt="Agent Teams" />
  <img src="https://img.shields.io/badge/RAG-vector_memory-00b4d8" alt="Vector Memory" />
  <img src="https://img.shields.io/badge/skills-35+-10b981" alt="35+ Skills" />
  <img src="https://img.shields.io/badge/MCP-compatible-10b981?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgZmlsbD0id2hpdGUiIHZpZXdCb3g9IjAgMCAxNiAxNiI+PGNpcmNsZSBjeD0iOCIgY3k9IjgiIHI9IjMiLz48L3N2Zz4=" alt="MCP Compatible" />
  <img src="https://img.shields.io/badge/pnpm-10.23+-yellow.svg" alt="pnpm" />
  <a href="https://github.com/project-nomos/nomos/pkgs/container/nomos"><img src="https://img.shields.io/badge/GHCR-container-blue?logo=docker" alt="Docker Image" /></a>
  <a href="https://github.com/project-nomos/nomos/stargazers"><img src="https://img.shields.io/github/stars/project-nomos/nomos?style=flat" alt="Stars" /></a>
</p>

---

## What is Nomos?

Most AI assistants forget you the moment a conversation ends. Nomos doesn't.

Nomos is an autonomous AI agent platform that **remembers every interaction**, connects to your tools and channels, and gets smarter over time. It runs as a persistent background daemon — always on, always learning — reachable from Slack, Discord, Telegram, WhatsApp, the terminal, or any gRPC/WebSocket client.

It comes with **persistent vector memory** across sessions and channels, **multi-agent team orchestration** for complex tasks, **smart model routing** to optimize cost and quality, **27 bundled skills**, a **web management dashboard**, and built-in **image and video generation**.

> **What powers Nomos?** Under the hood, Nomos is built on Anthropic's [Claude Agent SDK](https://docs.anthropic.com/en/docs/claude-code/sdk) — inheriting the full agent loop, built-in tools, streaming, and compaction. Nomos adds the infrastructure layer on top: memory, channels, teams, scheduling, and a management UI.

---

## Get Running in 2 Minutes

```bash
# Homebrew (recommended)
brew tap project-nomos/nomos https://github.com/project-nomos/nomos
brew install project-nomos/nomos/nomos

# Then just:
nomos chat
```

That's it. A browser-based setup wizard handles the rest — database connection, API provider, assistant personality, and channel integrations. Everything is saved encrypted in PostgreSQL. Configuration is stored in `~/.nomos/.env` and works from any directory.

<details>
<summary><strong>Other installation methods</strong></summary>

### npm (GitHub Packages)

```bash
npm install -g @project-nomos/nomos --registry=https://npm.pkg.github.com
```

### Docker Compose (includes database)

```bash
git clone https://github.com/project-nomos/nomos.git
cd nomos
cp .env.example .env
# Edit .env with your ANTHROPIC_API_KEY (or OPENROUTER_API_KEY)
docker compose up -d
```

The agent is accessible via gRPC on port 8766 and WebSocket on port 8765.

### Docker (standalone)

```bash
docker run -d --name nomos \
  -e DATABASE_URL=postgresql://nomos:nomos@host.docker.internal:5432/nomos \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -p 8766:8766 -p 8765:8765 \
  ghcr.io/project-nomos/nomos:latest
```

### From source

```bash
git clone https://github.com/project-nomos/nomos.git
cd nomos
pnpm install
pnpm build
pnpm link --global
nomos chat
```

</details>

### Prerequisites

- **Node.js** >= 22
- **PostgreSQL** with the [pgvector](https://github.com/pgvector/pgvector) extension
- **One of**: Anthropic API key, Google Cloud credentials (Vertex AI), [OpenRouter](https://openrouter.ai) API key, or a local [Ollama](https://ollama.com) instance
- **Google Cloud credentials** for embeddings (optional — falls back to full-text search when unavailable)

---

## What You Get

|                           | Feature                                                                            | What it does                                                                                |
| ------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| :brain:                   | [**Memory That Persists**](#memory-that-persists-across-sessions-and-channels)     | Every conversation auto-indexed into pgvector. Recall anything from any session or channel. |
| :speech_balloon:          | [**6 Channel Integrations**](#deploy-to-6-platforms-in-minutes)                    | Slack, Discord, Telegram, WhatsApp, iMessage — thin adapters, one agent runtime.            |
| :busts_in_silhouette:     | [**Multi-Agent Teams**](#multi-agent-teams--parallelize-complex-work)              | Coordinator + parallel workers. Hand off complex tasks, get synthesized results.            |
| :zap:                     | [**Smart Model Routing**](#smart-model-routing--cut-costs-without-cutting-quality) | Route by complexity across any provider — cloud, local, or hybrid. Cut costs automatically. |
| :globe_with_meridians:    | [**Multiple API Providers**](#multiple-api-providers)                              | 5 providers supported: direct API, Vertex AI, OpenRouter, Ollama, or custom.                |
| :art:                     | [**Image & Video Gen**](#image--video-generation--built-in-not-bolted-on)          | Gemini image + Veo video generation, conversational — just ask.                             |
| :desktop_computer:        | [**Web Dashboard**](#web-based-management-dashboard)                               | Next.js 16 settings UI with setup wizard. No YAML editing.                                  |
| :jigsaw:                  | [**27 Bundled Skills**](#extend-without-forking)                                   | Three-tier loading: bundled, personal, project. Create your own in minutes.                 |
| :lock:                    | [**Secrets Encrypted at Rest**](#secrets-encrypted-at-rest)                        | AES-256-GCM for all API keys and tokens. Auto-key on first run.                             |
| :brain:                   | [**Adaptive Memory**](#adaptive-memory--user-model)                                | Extracts facts, preferences, corrections. Builds a persistent user model.                   |
| 

[truncated…]