Short records of the decisions that shape Sentient: what we decided, why, and what it costs. Read these before proposing a change to one of them.
| # | Decision | Status | Date |
|---|---|---|---|
| 0001 | Record architecture decisions | Accepted | 2026-09-12 |
| 0002 | Ship a desktop app that runs a local engine | Accepted | 2026-09-15 |
| 0003 | Keep all state in one SQLite file | Accepted | 2026-09-12 |
| 0004 | Let the user pick a model for every job | Accepted | 2026-09-12 |
| 0005 | Keep secrets in the OS keychain and never require a .env | Accepted | 2026-09-12 |
| 0006 | Define the desktop and engine contract first | Accepted | 2026-09-15 |
| 0007 | Use one agent loop for every surface | Accepted | 2026-09-15 |
| 0008 | Decide approvals by each call's effective risk | Accepted | 2026-09-15 |
| 0009 | Push memory into every turn and consolidate it nightly | Accepted | 2026-09-15 |
| 0010 | Let Sentient write its own skills, with human review (amended: skill checks, #386) | Accepted | 2026-09-12 |
| 0011 | Connect devices with a small JSON protocol over WebSockets | Accepted | 2026-09-15 |
| 0012 | Run model-written code in a sandbox that calls tools | Accepted | 2026-09-15 |
| 0013 | Prefer change feeds and scripts over model calls | Accepted | 2026-09-15 |
| 0014 | Use GitHub flow with CI that needs no secrets | Accepted | 2026-10-08 |
| 0015 | Archive v2 on a branch instead of keeping it in main | Accepted | 2026-10-08 |
| 0016 | Let people set lasting Allow, Ask or Never rules per app and tool | Accepted | 2026-10-09 |
| 0017 | Work nobody asked for can only read | Accepted | 2026-10-09 |
| 0018 | Ask before sending anything once untrusted content is in play | Accepted | 2026-10-09 |
| 0019 | Run commands on the host only when turned on, in allowed folders, with approval | Accepted | 2026-10-09 |
| 0020 | Link WhatsApp as a device with an in-process WhatsApp Web bridge | Accepted | 2026-10-09 |
| 0021 | Hold memories from untrusted sources for the user's review | Accepted | 2026-10-10 |
| 0022 | Let chats use Claude through the user's own Claude Code, off by default | Accepted | 2026-10-10 |
| 0023 | Mark outside content in prompts so the model reads it as data | Accepted | 2026-10-11 |
| 0024 | Take a second look at outgoing actions before they run | Accepted | 2026-10-13 |
| 0025 | Folders the user adds are their own content; web pages clipped into them are not | Accepted | 2026-10-14 |
| 0026 | Hold sends in an undo window and prefer the trash | Accepted | 2026-10-14 |
| 0027 | Check skills and MCP tools from outside before the model sees them | Accepted | 2026-10-15 |
| 0028 | Let a quick light command count as its own yes, and make opening the home always ask | Accepted | 2026-10-15 |
| 0029 | Treat other people in a group chat as outside content, and let the user trust a chat again | Accepted | 2026-10-15 |
| 0030 | Change the database shape through numbered migration files | Accepted | 2026-10-17 |
| 0031 | Fix where a message goes before reading what it says, and read outside documents with a tool-less reader | Accepted | 2026-10-17 |
| 0032 | Let people opt in to using their own Claude Code for everything | Accepted | 2026-10-17 |
| 0033 | Take tasks by email only from allowed real addresses, and treat the email as outside content | Accepted | 2026-10-18 |
| 0035 | Install skills from the hub into review, check them first, and pin the exact version | Accepted | 2026-10-23 |
- Copy 0000-template.md to the next number, for example
0016-short-title.md. - Fill in context, decision, consequences and alternatives. Keep it to one page.
- Add it to the table above and open a pull request. Discussion happens in review.
Records are never deleted. To change a decision, add a new record and mark the old one "Superseded by ADR NNNN".