cyzus/suzent

---

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.

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.

---

WHAT MAKES AN AGENT SOVEREIGN?

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

---

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.

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.

• 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:

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.

• 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, 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.

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

---

DOCUMENTATION

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.