somora_agent｜本地优先的多智能体团队与共享记忆服务器

access：来源确认 · curl -fsSL https://somora.ai/install.sh | bash

project_type：来源确认 · A small server you run on your machine that hosts your agents.

<p align="center">
  <img src="docs/images/somora-hero.png" alt="somora.ai — Build your own AI team. Local-first agents that never forget." />
</p>

# somora 🐨

> **Your AI team. Shared memory. Your choice of models.**
>
> Run personal AI agents on your own machine, switch between Claude, ChatGPT,
> Grok and local models in the middle of a conversation, and let the agents
> turn what they learn into a shared long-term wiki while they sleep.
> Run. Rest. Dream.

<p align="center">
  <a href="https://somora.ai"><img src="https://img.shields.io/badge/Website-2ea44f?style=for-the-badge&logo=googlechrome&logoColor=white" alt="Website: somora.ai" /></a>
  <a href="https://docs.somora.ai"><img src="https://img.shields.io/badge/Docs-0a7ea4?style=for-the-badge&logo=readthedocs&logoColor=white" alt="Documentation: docs.somora.ai" /></a>
  <a href="https://www.npmjs.com/package/somora"><img src="https://img.shields.io/npm/v/somora?style=for-the-badge&logo=npm&label=npm&color=cb3837" alt="npm: somora" /></a>
  <a href="https://somora.ai/discord"><img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord" /></a>
  <a href="https://x.com/somora_ai"><img src="https://img.shields.io/badge/@somora__ai-000000?style=for-the-badge&logo=x&logoColor=white" alt="X: @somora_ai" /></a>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
  <a href="#what-works-where"><img src="https://img.shields.io/badge/status-active%20dev-green.svg" alt="Status: active development" /></a>
  <a href="#requirements"><img src="https://img.shields.io/badge/node-%E2%89%A522.22-brightgreen.svg" alt="Node 22.22 or newer" /></a>
</p>

## Install

```bash
curl -fsSL https://somora.ai/install.sh | bash
```

Linux or macOS, as a normal user. Brings everything that is missing
(Node.js included), registers the background service and walks you through
models, your first agent, memory and HTTPS — details under
[Quickstart](#quickstart). Update later: `somora update`.

| | |
|---|---|
| **One line** (recommended) | `curl -fsSL https://somora.ai/install.sh \| bash` |
| **npm** — you already have Node ≥22.22.2 | [docs/setup.md → Install by hand](docs/setup.md#install-by-hand) (npm 12 needs one extra flag) |
| **From source** — you want to work on somora itself | [docs/setup.md → Develop from a checkout](docs/setup.md#develop-from-a-checkout) |

## See it

<a href="docs/images/somora-web-dark-2026-10-12.png"><img src="docs/images/somora-web-dark-2026-10-12.png" alt="somora web client, dark theme: browser desktop with agent windows, two tmux terminals, the agent's browser, a builder plan and the taskbar" /></a>

<a href="docs/images/somora-web-light-2026-10-12.png"><img src="docs/images/somora-web-light-2026-10-12.png" alt="somora web client, light theme: the same desktop" /></a>

<table>
  <tr>
    <td width="66%" valign="top">
      <a href="docs/images/somora-tui-2026-10-12.png"><img src="docs/images/somora-tui-2026-10-12.png" alt="somora TUI: the terminal client with its status line" /></a>
    </td>
    <td width="34%" valign="top">
      <a href="docs/images/somora-mobile-2026-10-12.png"><img src="docs/images/somora-mobile-2026-10-12.png" alt="somora mobile app: avatar row at the top, an agent's reply, attachment, microphone and send at the bottom" /></a>
    </td>
  </tr>
</table>

Browser desktop in dark and light, terminal, and installable phone app — all talking to the
same local server, the same agents, the same memory.

## Why somora

- **A personal agent team.** Configure as many agents as you want, each
  with its own character, private memory, model preferences, and tool
  permissions. A `team.yaml` tells every agent who reports to whom. Agents
  delegate to each other: one spawns a sub-agent for a task, another asks a
  colleague a question mid-turn, and an answer that arrives after the turn
  ended still reaches the one who asked.
- **Knowledge that compounds.** Agents notice facts while you chat, keep
  them privately, and a background dream cycle promotes stable knowledge
  into a shared Obsidian wiki — with your approval where it matters. What
  one agent learns today, another can use next week.
- **Any model, one conversation.** Flip between Claude (your Claude
  subscription), ChatGPT (your ChatGPT subscription), Grok, or any
  OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, OpenRouter) with a
  slash command. History and tools carry over; the same tool registry
  feeds all four engines.
- **Yours.** Config, agent memory, sessions and attachments live in
  `~/.somora/`; the shared wiki lives in your Obsidian vault; workspace
  files and generated media in your configured workspace. Which models and
  which external services your agents talk to is your configuration, not a
  default.

## What is somora?

A small server you run on your machine that hosts your agents. You chat
with them from the terminal, the browser, or your phone; they remember
things across sessions; they use the same typed tools — memory, files
(numbered reads, tolerant patches, filtered search), web, shell, tmux,
attachments, sub-agents — regardless of which LLM you point them at.
Everything an agent is asked to do — a question from you, a question
from another agent, a sub-agent, a scheduled trigger, a voice
call — goes through one queue per session that you can see and take back
from in every client.

## Two kinds of agents

Every agent is one of two kinds, chosen when it is created and never
changed. Most of your agents are **chat agents**. A **builder** is the
one you give a repository to.

| | Chat agent | Builder |
|---|---|---|
| **What it is for** | Talking, thinking, remembering, orchestrating: the assistant you ask, the analyst, the coordinator | Building software in a repository: plan, edit, run, test, report |
| **Its prompt** | Its persona (`AGENTS.md`, `SOUL.md`, `USER.md`), your team, the wiki map, memory recall | Harness rules, an environment block, the repository's own `AGENTS.md`/`CLAUDE.md`; no persona, no memory recall |
| **Tools** | The whole programme, gated per agent | A short coding set: files, shell, task list, questions, helpers, colleagues, search |
| **Turns** | A few rounds; on an OpenAI-compatible model the loop stops at 30 tool calls (the CLI engines run their own loop) | Hours; hundreds of rounds, compaction mid-turn, a task list you watch |
| **Memory** | Notices facts, dreams them into notes and the wiki | Reads memory, never writes it; does not dream |
| **Works in** | Its workspace | The pinned project's folder, and folders an order allows besides it |
| **Window** | Chat | Chat plus a task panel, in the web client and on the phone: mode, plan → Go, tasks, acceptance list, questions, running time |
| **Made how** | `somora setup agent`, or a folder with an `AGENTS.md` and an `agent.yaml` | A folder whose `agent.yaml` says `kind: builder` — fixed for life |

You can talk to a builder directly — describe the project, let it plan,
press Go — or let a chat agent hand it the order in one call and be
woken with the report. The hand-over procedure ships as a skill. Details
in [docs/builder.md](docs/builder.md); chat agents in
[docs/agents.md](docs/agents.md).

On top of chat and memory, each optional and off until configured:

- **Skills** — Markdown how-tos an agent can activate, with declared
  binaries and secrets that somora checks and injects
  ([docs/skills.md](docs/skills.md)).
- **Media generation** — point somora at an image or video endpoint and
  both you and your agents can make pictures and film; results land in
  your workspace and in one gallery ([docs/imagegen.md](docs/imagegen.md),
  [docs/videogen.md](docs/videogen.md)).
- **Shared browser** — a real Chromium per agent that the agent drives and
  you can watch and take over in the web client: sign in, pass a 2FA
  prompt, hand back, and the agent continues in the same tab
  ([docs/browser.md](docs/browser.md)).
- **Talking to an agent** — a standing, interruptible voice call in the
  web client or on the phone: a realtime model does the talking, the agent does the
  knowing, and a long answer is read out when it lands
  ([docs/realtime-voice.md](docs/realtime-voice.md)). Separate from
  dictation and spoken replies ([docs/voice.md](docs/voice.md)).
- **Projects** — bind a session to a real-world thing via a manifest of
  pointers the agent sees in its prompt ([docs/projects.md](docs/projects.md)).
- **Sentinel** — triggers that wake an agent on a schedule (`at` /
  `every` / `daily` / `weekly` / `cron`) or when a small check script sees
  something happen; a decision model can judge what the script fetched,
  such as "a new mail that needs an answer today"
  ([docs/sentinel.md](docs/sentinel.md)).
- **External agents** — bring an OpenClaw or Hermes agent into somora:
  you chat with it in its own window, and your agents hand it work over
  A2A, images and files included. Other systems reach your agents the
  same way, and an editor talks to them through `somora acp`
  ([docs/external-agents.md](docs/external-agents.md),
  [docs/a2a.md](docs/a2a.md), [docs/acp.md](docs/acp.md)).
- **External MCP servers** — one config entry, all engines see the tools,
  gateable per agent ([docs/mcp.md](docs/mcp.md)).
- **Language servers** — with one installed, every file a builder
  writes comes back with the compiler's errors for that file, so it
  fixes them in the same step ([docs/lsp.md](docs/lsp.md)).
- **Steering** — type into a running turn instead of behind it: the
  model reads your message at its next step and changes course. Works on
  every engine ([docs/api.md → Steering](docs/api.md#steering)).
- **Decision models** — agents ask a System One decision model (such as
  a self-hosted Clef) typed yes/no, choice and score questions about text
  or images, and get probabilities back. Scripts and other programs ask
  through `POST /decisions/evaluate` ([docs/decisions.md](docs/decisions.md)).

## Requirements

Hard:

- **Node ≥22.22.2** — the memory database uses `better-sqlite3` with `sqlite-vec`, both prebuilt. On an
  older Node every `somora` command stops with the upgrade steps.
- **macOS, or Linux with glibc ≥2.34** — Debian 12, Ubuntu 22.04, RHEL 9,
  Fedora 35 or newer. The memory database ships prebuilt for these.
- **About 1.6 GB of disk** on Linux, 1.4 GB on macOS, mostly the
  bundled Codex, Claude and Grok engines.
- **A current browser** for the web and mobile clients: Chrome or Edge
  111, Firefox 114, Safari 16.4 (iOS and iPadOS 16.4) or newer.
- **tmux** — for the `tmux` tool (long-lived terminal sessions for agents)
  and the web tmux app.
- **At least one LLM backend:** a Claude subscription (engine
  `claude-cli` — Claude Code is bundled, `somora claude login`); a ChatGPT
  subscription (engine `codex-cli` — Codex is bundled, `somora codex login`); a SuperGrok or
  Premium subscription (engine `grok-cli` — the Grok CLI is bundled, `somora grok login`); or any OpenAI-compatible HTTP
  server (Ollama, LM Studio, vLLM, oMLX, OpenRouter, …).

Optional: an **Obsidian vault** for the shared wiki and read-only vault
recall; **Tailscale** for HTTPS to the web and mobile clients
(`tailscale cert`, needed for HTTP/2 and the microphone, screen-share and
clipboard APIs); **ripgrep** for `file_search`; **Chromium or Chrome** for
the shared browser.

somora makes one request of its own: once a day it asks somora.ai
whether a newer version exists (version, OS, Node version and CPU in the
User-Agent, nothing else; somora.ai counts installations from its
server log). `DO_NOT_TRACK=1` or `updateCheck.enabled: false` switches it
off — [docs/setup.md → The daily update check](docs/setup.md#the-daily-update-check).

[docs/setup.md](docs/setup.md) is the full install walkthrough,
[docs/models.md](docs/models.md) lists the models known to run with somora
and their tested config blocks.

## Quickstart

```bash
curl -fsSL https://somora.ai/install.sh | bash
```

One line, as a normal user (not root), on Linux or macOS. The installer
checks for tmux, ripgrep, git and a compiler and installs what is missing
(it asks before using admin rights), brings Node.js if yours is missing or
too old, installs somora from npm, registers the background service, and
then starts the **setup assistant**:

```text
somora setup
  1  Models        connect a Claude, ChatGPT or Grok subscription, or your own model server
  2  Web search    a Brave Search API key, so agents can search the web
  3  First agent   name, language, model and a backup model
  4  Memory        REM, Deep and Lucid — and where the shared wiki lives
  5  Team          who is who, once there is more than one agent
  6  Access        HTTPS through Tailscale, so phone and laptop can reach it
  7  Start + test  starts the service and sends your agent a real message
```

Every step first looks at what is already there, so `somora setup` is safe
to run again — as a whole or one step (`somora setup access`). Update
later with `somora update`.

Already have Node ≥22.22.2 and the tools from [Requirements](#requirements)?
Then follow [Install by hand](docs/setup.md#install-by-hand): one npm
command, then `somora setup`.

### Already using a coding agent? Let it set up somora.

If you already run Claude Code, Codex CLI or another AI agent with
terminal access to your machine, hand it the setup. It reads the docs,
does the install and configuration below, and gets you a complete
instance — model providers, agents, a team, memory, skills, resources —
not just a running server. Copy this into your agent:

```text
Set up somora for me from the official repository:
https://github.com/thenaxon/somora_agent

Read the current README, then docs/setup.md, docs/models.md,
docs/agents.md, docs/team.md, docs/resources.md and docs/skills.md.
Inspect my environment, then install somora with the installer from the
README (`curl -fsSL https://somora.ai/install.sh | bash -s -- --no-setup`)
and configure it yourself instead of the interactive `somora setup`.

Aim for a complete, useful setup, not just a running server:
- Help me choose model providers and connect the CLI logins or API
  access I already have. Use the documented model configurations
  (engine, reasoning mapping, context window, capabilities, sampling,
  fallback) from docs/models.md — don't guess model IDs.
- Set up my agents and a coherent team with clear roles and
  delegation rules (docs/agents.md, docs/team.md), including one
  builder agent for coding work if I have a repository to work in
  (docs/builder.md).
- Configure the features that fit me: memory and the dream phases,
  skills, projects, scheduled tasks (sentinel), the shared browser, and
  image, video or voice generation where I have a backend for it. Explain
  optional features and what they need rather than silently skipping them.
- Connect the machines and services I want as resources
  (docs/resources.md).
- Ask concise questions for missing preferences, credentials or
  decisions.
- Verify: the server is healthy, a chat turn answers on the
  configured model, tools run, and every integration you set up
  works. Summarise what works and what still needs my input.

Preserve unrelated services and configuration. Ask before making
disruptive changes. Never invent model IDs, credentials, resources or
configuration options that the docs don't describe.
```

### By hand

```bash
# 1. Prereqs (see docs/setup.md for details per OS)
sudo apt install tmux ripgrep git build-essential python3   # Debian/Ubuntu
# brew install tmux ripgrep git                             # macOS (plus Xcode command line tools)

# 2. Install somora (npm older than 11.16: leave out the --allow-scripts line)
ONNXRUNTIME_NODE_INSTALL=skip npm install -g somora \
  --allow-scripts=cpu-features,esbuild,fsevents,node-pty,onnxruntime-node,protobufjs,somora,ssh2

# 3. Log in to at least one LLM backend (pick one or more)
somora claude login                         # Claude subscription; Claude Code is bundled
somora codex login                        # ChatGPT subscription; Codex is bundled
somora grok login                         # SuperGrok or Premium subscription; the Grok CLI is bundled
# local models: run Ollama / LM Studio / oMLX and add the endpoint to
# ~/.somora/config.yaml after step 4

# 4. First-run setup + start
somora init                    # creates ~/.somora/ and registers the background service
somora server start            # starts it (and from then on at boot / login); the default agent is created on first start
somora tui                     # chat in the terminal
somora key link                # sign the web client in (link + QR code for the phone)
```

Once you have more than one agent, `somora team init --principal "<your
name>"` writes `~/.somora/team.yaml` so every agent knows who is who — or
arrange it in the **team** tile of the web client
([docs/team.md](docs/team.md)). The web client, providers and Tailscale
HTTPS are in [docs/setup.md](docs/setup.md); hacking on somora itself in
its [contributor section](docs/setup.md#develop-from-a-checkout).

## What works where

Every engine gets the same feature set:

| Capability | claude-cli | codex-cli | grok-cli | openai-compatible |
|---|:-:|:-:|:-:|:-:|
| Chat (streaming) | ✓ | ✓ | ✓ | ✓ |
| Memory auto-injection | ✓ | ✓ | ✓ | ✓ |
| Memory tools (read + write) | ✓ via MCP | ✓ dynamic tools | ✓ via MCP | ✓ in-process |
| Wiki layer (shared) | ✓ | ✓ | ✓ | ✓ |
| Three-phase dreams | ✓ | ✓ | ✓ | ✓ |
| Tool surface | ✓ via MCP | ✓ dynamic tools | ✓ via MCP | ✓ in-process |
| Skills (markdown how-tos) | ✓ | ✓ | ✓ | ✓ |
| Multimodal attachments (image, PDF) | ✓ native | ✓ image native, PDF rasterized | ✓ image native, PDF rasterized | ✓ image; PDF native or rasterized per provider |
| Image + video generation¹ | ✓ via MCP | ✓ dynamic tools | ✓ via MCP | ✓ in-process |
| Sub-agents, agent-to-agent questions, follow-ups | ✓ | ✓ | ✓ | ✓ |
| SSH-resource exec | ✓ | ✓ | ✓ | ✓ |

¹ Off until an `imageGen` / `videoGen` block exists in `config.yaml`.

## Architecture at a glance

```
   you (terminal · browser · phone)   another agent   a voice call   a timer
                    │                       │              │            │
        TUI / Web / Mobile PWA           agent_ask     realtime      sentinel
                    │                       │              │            │
                    └──── HTTP + SSE · WebSocket ──────────┴────────────┘
                                          ▼
   somora-server
   │
   ├─ Turn dispatch — one entry for every turn, whoever started it
   │    one queue per session, first come first served · Stop reaches every turn
   │    work ledger: what runs, what waits, what is arriving · wakes when
   │    late results land · follow-ups to whoever asked · visible in every client
   │
   ├─ Engines           claude-cli · codex-cli · grok-cli · openai-compatible
   │    one tool registry for all four (in-process · MCP child · Codex dynamic tools)
   │
   ├─ Tools             memory · dream · wiki · file · exec + tmux · web · agents
   │                    skills · sentinel · browser · image · video · media · projects
   │                    + external MCP servers — every tool gateable per agent
   │
   ├─ Memory            ~/.somora/agents/<name>/memory/*.md   per agent, private
   │  Wiki              <obsidian-vault>/<wiki-subfolder>/    shared, long-term
   │  Vault             the rest of the vault                 read-only context
   │                    hybrid retrieval (SQLite + sqlite-vec + FTS5), one index per source
   │
   ├─ Dream system      REM  session → memory   ·   Deep  memory → wiki   ·   Lucid  wiki review
   │
   ├─ Sentinel          ~/.somora/sentinel/triggers.json — time and check-script fires as agent turns
   │
   ├─ Optional          realtime voice call · Chromium per agent · image + video generation
   │
   └─ Storage           sessions as JSONL · attachments content-addressed · config.yaml
                        all under ~/.somora/
```

## Clients

Three first-party clients, all hitting the same local server:

| Client | Launch | What you get |
|---|---|---|
| **TUI** | `somora tui` | Terminal multi-agent chat with full keyboard control, the session's queue (`/queue`), memory and tool detail toggles. |
| **Web** | `https://<host>.<tailnet>.ts.net:18737/web/` | A browser desktop: one window per agent, drag-and-drop attachments and screenshots, tmux app and shell terminal, Wiki Explorer with link graph, Media gallery, Sessions browser, the agent's Chromium window, server log, an inbox for updates and things that need you, a light or dark theme plus the bundled Ocean theme, or themes of your own (colours and wallpaper, [docs/web.md#themes](docs/web.md#themes)), Abilities matrix (which tools and skills each agent may use), Team and Agent windows, a queue badge per session (what runs, what waits, what is arriving — take back or stop from there), dictation and spoken replies, and a voice window for a live call. HTTPS recommended (needed from other devices and for the microphone); sign in once with the server's key (`somora key link`). [docs/web.md](docs/web.md) |
| **Mobile (PWA)** | `…:18737/mobile/`, then "Add to Home Screen" | The phone app: avatar row to switch agent, a sheet in the header to switch session and model or restore an archived session, the same queue sheet with steering, the thinking level per session, a tools switch that shows a turn's tool calls, a builder's panel (mode, phase, Go, task and acceptance lists), voice input and spoken replies, a live voice call with an agent, photo/PDF attachments via the native picker. Signs in once by scanning the QR code from `somora key link`. [docs/mobile.md](docs/mobile.md) |

Anything else can talk to the server the same way the clients do, with
the server's key in an `Authorization: Bearer` header:
[docs/api.md](docs/api.md) is the HTTP + SSE + WebSocket reference.

## Documentation

Start at [docs/index.md](docs/index.md): what somora is, which page to read
for which goal, and every concept in one sentence. The same pages, rendered
and searchable: [docs.somora.ai](https://docs.somora.ai).

- **Get running:** [setup](docs/setup.md) · [models](docs/models.md) · [agents](docs/agents.md) · [team](docs/team.md) · [security](docs/security.md)
- **Memory and knowledge:** [memory](docs/memory.md) · [wiki](docs/wiki.md) · [dream phases](docs/dream-phases.md) · [compaction](docs/compaction.md) · [cache strategy](docs/cache-strategy.md)
- **What agents can do:** [tools](docs/tools.md) · [builders](docs/builder.md) · [language servers](docs/lsp.md) · [files](docs/files.md) · [tmux](docs/tmux.md) · [resources](docs/resources.md) · [skills](docs/skills.md) · [MCP servers](docs/mcp.md) · [projects](docs/projects.md) · [sentinel](docs/sentinel.md) · [browser](docs/browser.md) · [image generation](docs/imagegen.md) · [video generation](docs/videogen.md) · [decision models](docs/decisions.md) · [image handling](docs/image-handling.md) · [external agents](docs/external-agents.md) · [A2A](docs/a2a.md)
- **Clients and API:** [web](docs/web.md) · [mobile](docs/mobile.md) · [TUI display](docs/display.md) · [voice](docs/voice.md) · [realtime voice](docs/realtime-voice.md) · [editors (ACP)](docs/acp.md) · [API](docs/api.md)
- **Models in detail:** [thinking](docs/thinking.md) · [sampling](docs/sampling.md)

## Contributing

Contributions are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) says how to
report bugs, propose ideas and send pull requests. Security problems are
reported privately: [SECURITY.md](.github/SECURITY.md). What changed in
each version is in the
[release notes](https://github.com/thenaxon/somora_agent/releases).

## License

[MIT](LICENSE).

---

🐨 *somora — patient, slow, with very good memory.*

Node ≥22.22.2；macOS 或 glibc ≥2.34 的 Linux；约 1.4–1.6 GB 磁盘；tmux（tmux 工具所需）；现代浏览器；至少一个 LLM 后端：Claude 订阅、ChatGPT 订阅、SuperGrok/Premium 订阅，或 OpenAI 兼容服务（Ollama、LM Studio、vLLM、oMLX、OpenRouter 等）；可选 Brave Search API Key、Obsidian vault、Tailscale（HTTPS）、ripgrep、Chromium/Chrome。模型与第三方服务费用、是否提供商业模块与托管服务待核验；Windows 支持未声明；国内网络可用性待核验。