GitHub - sliamh11/Deus: A token-efficient open-source AI assistant that remembers, adapts, and improves — secured, self-hosted, and entirely yours.

5 min read Original article ↗

Deus - Open-source personal AI assistant

License: MIT Node Platform

A personal AI that understands you - not just recalls things you've said. It learns what you care about, how you think, and what you'll actually find useful. The longer you use it, the more it feels like it gets you. Everything runs on your computer. Your data stays yours.

What it does

  1. Understands you - It doesn't just store memories - it breaks conversations into facts, indexes by meaning, and builds a model of what you care about. Ask about something from three weeks ago and it recalls the details, even if you don't remember what you called it. (95% recall on the LongMemEval benchmark.)

  2. Adapts to how you think - Scores its own responses, generates self-critiques, and rewrites its system prompt based on what worked. Tone, judgment, the kind of suggestions it surfaces - all of it improves at the personality level.

  3. Picks up where you left off - Context carries over between sessions. Start a project Monday, come back Thursday, and it knows where you left off.

  4. Lives where you already are - WhatsApp, Telegram, Slack, Discord, Gmail. Add only the ones you need. Your memory follows you across all of them.

  5. Private by default - Runs on your machine in isolated containers. No cloud sync, no tracking, no data leaving your computer.

  6. Works on your code too - Run deus in any project directory for a coding assistant that already knows your preferences and past work.

And more
  • Voice - Send a voice message and it transcribes and responds. Runs locally on Apple Silicon.
  • Vision - Send a photo or screenshot and it sees and responds to it.
  • Calendar - Reads and manages your Google Calendar. Ask what's coming up, or tell it to book something.
  • Scheduled tasks - Daily summaries, weekly recaps, reminders - set it and forget it.
  • Web & video - Summarize YouTube videos, fetch web pages, or research a topic, all from a chat message.

Quick Start

What you need

  • macOS (Apple Silicon recommended), Linux, or Windows
  • Claude Code or Codex CLI installed and authenticated
  • Docker Desktop (handles WSL 2 on Windows automatically)
  • Node.js 20+, Python 3.11+
  • A Gemini API key (free tier is enough)
  • Ollama for local embeddings and scoring (not an agent backend) - /setup pulls the right models automatically based on your hardware

Install

git clone https://github.com/sliamh11/Deus.git
cd Deus
claude            # or: codex

Then inside the CLI:

Setup installs dependencies, builds the container, and walks you through configuration. At the end it offers a Personality Kickstarter - choose a behavioral bundle (developer, student, universal) or pick individual behaviors, and optionally give it example conversations so it's useful from day one.

Connect a channel

A fresh install has zero channels. Add only what you need:

/add-whatsapp           # Scan QR code to connect WhatsApp
/add-telegram           # Paste bot token to connect Telegram

See AGENTS.md for all available skills.

Start talking

@Deus what's on my calendar tomorrow?
@Deus summarize the YouTube video at <url>
@Deus remind me every Monday morning what I worked on last week

Switching from another AI? Paste this into your current AI (ChatGPT, Gemini, etc.) and send the output to Deus in your first conversation:

I'm switching to a new AI assistant called Deus. Generate a structured summary
about me that I can give it so it knows me from day one. Include:

1. About me - name, role, location, languages
2. What I use AI for - main topics and tasks
3. Communication style - how I like responses
4. Preferences - things I've corrected you on
5. Key context - ongoing projects, goals, background

Be specific and factual. Skip anything generic. Format as plain text.

CLI

Command What it does
deus Launch in the current directory (project mode if outside ~/deus)
deus home Launch in home mode regardless of current directory
deus codex Use OpenAI/Codex backend for this session
deus auth Rebuild and restart background services
deus gcal Google Calendar token management (status, auth, ping)
deus listen Record from mic, transcribe locally, copy to clipboard
deus tui Full-screen terminal UI for chat, wardens, services, and channels

For direct Codex CLI sessions outside the deus launcher, register Deus memory recall as an MCP tool through the repo launcher:

codex mcp add deus-memory -- /path/to/deus/scripts/deus-memory-mcp

To mirror the repo's Warden gates in direct Codex CLI sessions, install the local Codex hooks:

python3 scripts/codex_warden_hooks.py install --dry-run
python3 scripts/codex_warden_hooks.py install
python3 scripts/codex_warden_hooks.py check

Comparison

Deus OpenClaw NemoClaw Hermes Agent Plain Claude
Memory Understands you - indexes facts by meaning, recalls in context Markdown files Via OpenClaw Full-text search + preference profiling Conversation only
Learning Adapts at the personality level - tone, judgment, suggestions No No Auto-creates & refines skills No
Channels 5 (WhatsApp, Telegram, Slack, Discord, Gmail) 10+ Via OpenClaw 15+ (WhatsApp, Telegram, Signal, Matrix...) None
Isolation Container per conversation Opt-in Docker Landlock + seccomp Per-session None
LLM support Claude default, OpenAI opt-in Any provider Any (via OpenClaw) Any (10+ providers) Claude only
Setup ~5 min ~15 min ~20 min ~10 min N/A
Repo size ~13 MB ~592 MB ~22 MB ~147 MB N/A

Deus goes deep on understanding you and adapting over time. Hermes goes wide on channels and LLM flexibility. See docs/benchmarks.md for detailed numbers.

Docs

Topic
How it works Architecture
Memory system Architecture - Memory
Self-improvement loop Architecture - Evolution
Security model Security
Benchmarks & token costs Benchmarks
Environment variables Environment
Using different AI backends Multi-backend
Backend quality benchmark Claude vs Codex parity report
Development setup Development
Contributing Contributing
Known limitations Limitations

Contributing

PRs welcome. Every change goes through a pull request - no direct pushes to main. See CONTRIBUTING.md for the full guide.

Support

Built and maintained solo - no company, no funding. If Deus is useful to you, sponsoring helps keep it going.

GitHub Sponsors Ko-fi

Acknowledgments

Built on NanoClaw - thanks to the NanoClaw team for the foundation.

License

MIT