Skip to content
Projects

cyzus/suzent has 69 GitHub stars and 11 forks. GitHot measured 0 stars in 24 hours, 0 in 7 days, and +1 in 15 days. Last checked 2026-11-17 02:36 UTC. Last push 2026-11-07.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
0
in 15 days
+1
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

SUZENT: The sovereign AI agent - own its memory, govern its actions, choose its intelligence, and keep its continuity.

AI

README.md

Original

Suzent Banner

SUZENT: THE SOVEREIGN AI AGENT

Your agent should not be an account you rent.

An open-source, local-first personal AI agent whose memory, authority, runtime, and continuity stay yours.

A memory it curates in files you own · 26 model providers and coding plans, cloud or your own hardware · actions reviewed against your rules · Regent keeps every project moving while you're away · desktop, phone, editor, and the chat apps you already use

Version Stars License Python Discord

Website • Quickstart • Docs • Discord • Contributing

The Suzent cube at the centre of an orrery. A ring of sixteen model providers turns around it, from OpenAI, ChatGPT and Claude to DeepSeek, Qwen, Kimi and GLM and models you host yourself, while its memory, permissions, phone, schedules, chat apps and folders circle closer in.

MEET SUZENT

SUZENT [soo-zuh-nt] keeps an agent's identity, memory, skills, workspace, and runtime under your control. Use GPT, Claude, Gemini, DeepSeek, Qwen, a model on your own GPU, or whatever comes next, without resetting the agent that knows you and your work.

It is not a chat window. It remembers what you told it and what it learned, tidies that memory overnight, works through goals and schedules while you're away, and asks before it does anything you haven't allowed. Its memory is plain files on your disk, its actions pass through permission modes you set, and its code runs in an isolated Docker sandbox or on the host under path restrictions you choose.

Models are replaceable. Platforms are temporary. Your agent remains.


QUICK START

SUZENT runs on Windows, macOS, and Linux.

Windows: get it from the Microsoft Store (recommended). No prerequisites; the Store keeps it up to date.

Get it from Microsoft

To install with the terminal or the desktop installer instead, follow the steps below. Git is the only prerequisite; everything else is installed for you.

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/cyzus/suzent/main/scripts/setup.sh | bash

Windows (PowerShell)

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/cyzus/suzent/main/scripts/setup.ps1 | iex"

Then start it and add a model under Settings → Providers:

suzent start

No API key? Pick Ollama and run everything on your own machine.

Installing from mainland China

Nothing to configure. Setup checks the network first: when Google is unreachable but the mainland mirrors answer, it downloads Suzent itself (from its Gitee mirror), Python, Python packages, the Playwright browser and uv from mainland mirrors. The Windows desktop installer also shows a "use mainland mirrors" switch, and updates keep whatever you chose.

If raw.githubusercontent.com does not load, fetch the same script from jsDelivr:

curl -fsSL https://cdn.jsdelivr.net/gh/cyzus/suzent@main/scripts/setup.sh | bash
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://cdn.jsdelivr.net/gh/cyzus/suzent@main/scripts/setup.ps1 | iex"

To force mirror mode on or off, set SUZENT_CHINA_MIRROR=1 or SUZENT_CHINA_MIRROR=0 before running setup. If GitHub itself is slow, set SUZENT_REPO_URL or SUZENT_RELEASE_BASE_URL to a mirror you trust.

On a mainland network, Settings → Model Providers lists DeepSeek, Qwen (DashScope), Kimi, Zhipu GLM and the other providers reachable without a VPN first, each with a link to get an API key.

The suzent CLI
suzent --version       # Print the backend version, commit, and UI version
suzent start           # Start the backend and the desktop app (in the background)
suzent serve           # Start the backend only (headless / standalone)
suzent web             # Open the web console against the backend
suzent ui              # Start the desktop app against a running backend
suzent logs -f         # Follow the log of a backgrounded process
suzent stop            # Stop the backend server and the dev frontend
suzent restart         # Stop a running backend server, then start Suzent again
suzent doctor          # Check requirements and diagnose a broken install
suzent update          # Update to the latest stable release
suzent check-update    # Report whether a newer release exists
suzent repair          # Recover an interrupted or damaged update

Run suzent --help, or suzent <command> --help, for the full flag set.

Updating
suzent update

This installs the latest stable release as one matched set: backend source, locked dependencies, and desktop app. A standalone updater performs the switch outside the active virtual environment, verifies downloaded assets, and rolls back automatically on failure. If an interrupted update needs recovery, run suzent repair.

Developers working from a source checkout can update main and its frontend dependencies together with plain suzent update; the checkout is detected automatically. The explicit equivalent is suzent update --dev.

Or re-run the install command above — it detects an existing installation and updates it to the latest stable release.


WHAT MAKES AN AGENT SOVEREIGN?

Sovereignty is not merely local execution. It is ownership of the agent's mind, authority, vessel, and continuity.

The four sovereignty pillars. I Sovereign Mind, model is not identity: memory, skills and notes are files, the model is a swappable engine. II Sovereign Authority, action within your law: Ask, Smart or Full Access, where in Smart mode a reviewer model lets an action run, asks you, or blocks it. III Sovereign Vessel, runtime in your domain: your computer, folders, laptop and phone, no vendor cloud. IV Sovereign Continuity, self over platform: memory and skills move to a new machine while keys stay local.
Question SUZENT's answer
Who owns its memory? You. Plain files on your disk are the source of truth.
Who chooses its intelligence? You. Sixteen providers built in, and any compatible endpoint you add.
Who defines what it may do? You. Permission modes, rules, and sandbox boundaries are explicit.
Where does it live? On infrastructure you control.
Can it move? Memory, skills, and configuration are portable; credentials stay local.
Can you inspect it? Tool calls, authorization decisions, files, and memory remain visible.

CHOOSE ITS INTELLIGENCE

Models are engines, not identities. Add as many providers as you like, pick a model per conversation, and switch without losing the memory, skills, or workspace that make the agent yours.

Providers
Frontier labs OpenAI (also Azure OpenAI) · ChatGPT Subscription (sign in with your ChatGPT plan, no API key) · Anthropic Claude · Google Gemini · xAI Grok
Open-weight labs DeepSeek · Qwen (DashScope) · Kimi (Moonshot) · GLM (Zhipu AI) · MiniMax · Xiaomi MiMo
Coding & token plans Kimi Code · Bailian Plan · Tencent Cloud · Volcengine Ark · StepFun · Baidu Qianfan · Huawei Cloud MaaS, plus the GLM Coding Plan and MiMo Token Plan on their cards above
Gateways & subscriptions OpenRouter (hundreds of models, one key) · OpenCode Go · ClinePass · Ollama Cloud · LiteLLM Proxy
Your own hardware Ollama · vLLM · SGLang
Anything else Add a custom provider for any OpenAI- or Anthropic-compatible endpoint, or a custom model ID on any card above.

Keys live in your operating system's keychain, never in plain-text config. Model roles let a small, cheap model handle titles, memory extraction, and permission review while your best model holds the conversation, and every role can carry backup models that take over when the first one fails.


OWN ITS MEMORY

Memory is where a sovereign agent keeps its self, so Suzent treats it as a curated knowledge base, not a chat log.

Suzent's memory pipeline. Each chat's facts are captured with the words they came from, appended to a plain file for that day, folded overnight by the organizer into one notebook page per topic with a map the agent always reads, and recalled in every chat by hybrid search over meaning, keywords, recency and importance. Lessons come from failures that were fixed; facts fade instead of being deleted; the search index rebuilds from the files.
  • It captures with evidence. Every few exchanges, facts are extracted and typed (a preference, a project detail, a lesson), each with the exact words it came from. A fact about you is kept only when you said it yourself, never when the agent guessed it.
  • It learns from what went wrong. When a command fails or you correct the agent, and the same exchanges show the fix, it saves what to do next time and where it applies. A lesson that keeps recurring for a repository is offered as a change to that repository's agent instructions.
  • It tidies overnight. An organizer reads the new daily logs and, for each fact, confirms, sharpens, supersedes, or adds it on a topic page. Contradictions become questions for you instead of guesses, and the old value is kept under a History heading.
  • It keeps a notebook. One page per topic, in a folder of plain notes the agent also researches and writes into (it opens as an Obsidian vault if you use Obsidian). A short map of those pages is loaded into every chat.
  • It recalls with hybrid search. Meaning, keywords, recency, and importance are scored together, so a fact you repeat often ranks above one you mentioned once.
  • It forgets gently. Each fact gets a review date by kind (a year for preferences, three weeks for passing context). Expired facts fade in search; nothing is deleted behind your back.

All of it is plain text files (Markdown) on your disk: open them in any editor, change them, keep them in Git. The LanceDB search index is rebuilt from those files at any time. How memory works →


GOVERN ITS ACTIONS

Autonomy never makes the agent the authority. Each conversation runs in one of three modes:

Mode What happens
Ask (default) Read-only actions run. Anything that changes files or the outside world asks you first.
Smart Clearly low-risk actions run on their own. Everything else goes to a separate reviewer model, which approves it, blocks it, or asks you.
Full Access Actions run without asking.

Your deny rules, blocked paths, and dangerous-command checks apply in every mode. An optional Docker sandbox isolates execution, and the activity timeline records what ran, what changed, and why it was authorized. Permissions & approvals →


LET IT WORK WHILE YOU'RE AWAY

You are the sovereign; Regent governs in your stead. It is the one conversation at the top of the sidebar that watches every project: tell it what you want done, and it hands the work to a session in the right project, or to a coding agent such as Codex or Claude Code, then follows up while you're gone.

You give Regent one instruction. Regent hands the work to sessions in the right projects, or to coding agents such as Codex and Claude Code, checks in on them while you are away, and brings back only what needs your decision. It reminds you when asked, the sessions it starts run in Smart mode, and it stays quiet when nothing needs you.
  • One place to look. Its board shows which chats are waiting on you, which are running, and a one-line note on where each stands.
  • It only brings you decisions. When a session finishes with nothing for you to do, Regent notes it quietly. Work that is blocked on you always notifies you.
  • It checks in on its own. Every 30 minutes it looks for stalled work and unanswered questions, and nudges things along.
  • It remembers how you like to work: what to bring to you, what to handle itself, and when not to disturb you.

Any chat can also run on a timetable ("every weekday at 9, summarize my inbox", or a reminder next Friday), and every chat turn saves a checkpoint first, so a retry restores both the conversation and the files. Extend it with portable SKILL.md packages and any MCP server you connect. Regent → · Scheduled tasks →


KEEP ITS CONTINUITY

GitHub Sync carries portable configuration, user skills, and Markdown memory through a private repository while credentials remain device-local. A provider can disappear, a model can change, and a machine can be replaced without taking the agent's continuity with it.


WHERE YOU TALK TO IT

One agent, one memory, every surface: the desktop app, the web console, a paired phone, your editor over ACP, other agents over A2A, your approved devices, and Telegram, Slack, Discord, Feishu and WeChat for allowed users only.

One agent, one memory, reachable from every surface. Messaging channels are off by default and access-controlled: a user ID must appear in allowed_users before the agent will answer it.

Surface Transport Supports Setup
Desktop app Local backend Full UI, Canvas, memory and skills browsers suzent start
Web console Local backend The same UI in your browser suzent web
Mobile app (preview) Paired with your desktop Shared conversations Guide
Your editor ACP Use Suzent as the agent in Zed and other ACP clients Guide
Other agents A2A Delegate work to other agents, or take work you grant them Guide
Telegram Bot API Text, photos, files Guide
Slack Socket Mode (Events API) Text, files Guide
Discord Gateway Text, files Guide
Feishu (Lark) WebSocket Text, files Guide
WeChat iLink Bot API Text Guide

Each conversation becomes a persistent session, so history, working memory, and extracted facts survive a restart.


DOCUMENTATION

Section What's covered
What is Suzent? What a sovereign agent is and what Suzent can do
Quickstart Install, connect a model, and start chatting
Regent The one chat that watches every project and follows up while you're away
Models & Providers All 26 providers, custom endpoints, and model roles
Memory What the agent remembers, where it lives, and how to edit it
Notebook Agent-maintained, Obsidian-compatible knowledge vault
Tools Everything the agent can do, and how to turn it on or off
Permissions & approvals How Suzent asks before it acts
Skills Install, write, and manage portable SKILL.md packages
Workspace & sandbox Folders, the Docker sandbox, and undoing a turn
Automation Scheduled tasks, heartbeats, goals, and the background service
Chat apps Telegram, Slack, Discord, Feishu, WeChat
Devices & other agents Your phone, other computers, A2A agents, and your editor
GitHub Sync Carry your agent to another computer through a private repo
Development Guide Setup, workflow, builds, architecture
Native Mobile SwiftUI/Compose developer preview, monorepo layout, and roadmap

The full index lives in docs/README.md.


TECH STACK

  • BACKEND: Python 3.12, FastAPI, pydantic-ai, litellm, SQLite.
  • FRONTEND: React, TypeScript, Tailwind, Vite, Tauri.
  • MEMORY: Markdown files as the source of truth, LanceDB hybrid (vector + full-text) index.
  • SANDBOX: Docker (optional).
  • EXTENSIBILITY: MCP, portable SKILL.md packages.

CONTRIBUTING

Contributions welcome. See CONTRIBUTING.md for the workflow, and the Development Guide for setup, production builds, and architecture.


SECURITY

Found a vulnerability? Please report it privately—see SECURITY.md. Do not open a public issue.


LICENSE

APACHE 2.0 © 2026 Yizhou Chi.

SUMMON LOCALLY. REMEMBER PRIVATELY. ANSWER TO NO FALSE GOD.