Your life, in context.
A self-hosted personal AI assistant with durable context, realtime voice, and human-approved actions.
Quick start · Features · Architecture · Sandbox
Fictional sandbox data only · watch the higher-quality WebM
Argus is an experiment in a different kind of assistant: a continuously deployed personal system that carries useful context across conversations, separates different areas of life into focused domains, and asks before changing durable state.
It combines a self-hosted web interface, realtime voice and text conversations, inspectable Markdown prompts, SQLite-backed tools, and explicit Accept / Reject workflows for consequential actions.
Note
Argus is an early-stage personal project. Interfaces and storage schemas are still evolving.
| Capability | What it means |
|---|---|
| Voice + text | Move between typed chat and realtime voice within one conversation. |
| Domain modes | Focus context and tools for Life, Tasks, News, and Worldbuilding. |
| Durable context | Store structured state in SQLite instead of hiding it inside prompts. |
| Human-approved actions | Review proposed journal entries, plans, and canon changes before they are written. |
| Inspectable prompts | Runtime behavior lives in plain Markdown under prompts/. |
| Evaluation loops | Exercise intent routing, planning behavior, provider lookup, and tool effects with repeatable scripts. |
| Continuous deployment | Run Argus as a persistent web application behind Nginx and systemd, with automated deployment through GitHub Actions. |
Argus uses one conversation shell, but each domain narrows the context, tools, and durable state available to the assistant.
A planning and reflection system rather than a generic to-do list.
- Natural-language check-ins become realistic calendar blocks.
- Monthly reviews define the goals that are actually active now.
- Preferences, requirements, routines, people, experiments, and constraints live in structured local storage.
- Journal Wrap Up extracts factual entries from a conversation for review.
- Plans can be marked completed, partial, skipped, or moved, feeding progress and replanning.
- Google Calendar sync is available when configured.
A project-aware Kanban board shared by the interface and the assistant.
- Projects and tasks are stored locally in SQLite.
- Work moves through Backlog, Doing, Review, and Done.
- Task detail, priority, description, project filters, and comments stay available as structured context.
- The focused Tasks chat can reason over the current board instead of relying on pasted lists.
A monitored-topic system designed to reduce noise rather than create another feed.
- Define watches with matching terms, context terms, exclusions, polling policy, and alert policy.
- Track RSS/Atom source health and the watches attached to each source.
- Separate important alerts from daily-digest material.
- Generate a concise morning brief from the signals that passed the configured filters.
A provenance-aware canon graph for long-running fictional worlds.
- Explore characters, places, factions, artifacts, events, and their links as a force graph.
- Store detailed facets separately from short node summaries.
- Search canon and inspect neighbouring concepts before answering consistency questions.
- Wrap Up proposes lore changes for review; brainstorming does not silently become canon.
- Evidence links preserve where accepted details came from.
Text and realtime voice share the same chat history. Domain focus can change inside a conversation, tool calls remain visible, and consequential writes can be presented as explicit Accept / Reject proposals.
- Private, self-hosted state. Runtime databases, chats, and logs remain on infrastructure you control.
- Propose before writing. The assistant can prepare changes, but the user remains the authority.
- Structured memory over giant prompts. Domains retrieve only the state needed for the current interaction.
- One conversation, focused contexts. Domain modes narrow the active tools without fragmenting the product.
- Simple, inspectable technology. Static HTML/CSS/JS, Node's built-in test runner, Markdown prompts, and SQLite.
flowchart LR
U[Browser] -->|text · audio · approvals| W[Express + Socket.IO]
W --> R[Conversation runtime]
R --> P[Prompt registry]
R --> M[Model providers]
R --> D{Domain registry}
D --> L[Life]
D --> T[Tasks]
D --> N[News]
D --> B[Worldbuilding]
L & T & N & B --> S[(Local SQLite stores)]
D --> A[Action proposals]
A -->|Accept / Reject| U
The active application lives in app/:
app/
├── backend/ Express, Socket.IO, tools, and domain stores
├── frontend/ Static UI and realtime audio worklet
├── scripts/ Sandbox, simulations, and evaluations
└── data/ Ignored runtime databases and logs
prompts/ Live, inspectable Markdown prompts
archive/ Historical adapters and retired experiments
- Node.js 20+
- npm
- A Gemini API key for model and realtime voice features
git clone https://github.com/kungfusaini/argus.git
cd argus
npm --prefix app ci
cp env.example .envAdd the credentials you want to use to .env, then run:
npm --prefix app startOpen http://localhost:5174.
npm --prefix app run check
npm --prefix app testArgus includes an isolated sandbox with fictional worldbuilding data, generic tasks, and non-personal Life records. It never touches the normal runtime databases.
Seed it and verify the tool layer without model calls:
npm --prefix app run sandbox -- --mockRun the interactive model-backed sandbox:
npm --prefix app run sandboxUseful commands include:
/domain life|worldbuilding|tasks|news
/send <message>
/command <id>
/accept
/reject
/tools
/counts
See app/README.md for the full workflow.
Argus began as a collection of Telegram agents, prompt workers, and small personal integrations. Those experiments established the core ideas—domain-specific context, durable tools, and an assistant that could do more than chat—but the system became fragmented.
The repository then moved toward an app-first architecture: one web interface, one conversation runtime, explicit domain boundaries, local stores, and reviewable actions. Older adapters remain in archive/ where they help explain that evolution without defining the current product.
- Runtime data, credentials, transcripts, and generated artifacts are ignored by Git.
- The committed environment file contains names only—never credential values.
- The sandbox uses generic seeded data designed for demos and evaluation.
- Public history is scanned for secrets before release.
Do not expose a personal Argus deployment directly to the internet without authentication, TLS, backups, and appropriate network controls.
Argus is currently shaped around a personal workflow, but focused issues and pull requests are welcome. Please avoid committing real conversations, personal records, credentials, or generated runtime databases.
MIT © Sumeet Saini