cos: a context layer for a personal digital assistant
cos keeps one canonical, auditable model of what a person owes, what others owe them, what is scheduled,
what is at risk, and what should no longer consume attention — as plain markdown in a private git repo,
maintained by scheduled agents and readable by any connected assistant. This service is the one write path
into that repo: it validates every change, refuses stale writes, runs the repo lint, and regenerates the
repo's own index and timeline on every commit.
How it works
Four layers, promoted deliberately. Conversation, evidence (immutable episode files), canonical
state (task entries with owners and clocks), and external action. Nothing moves up a layer on its own.
Scheduled runs do the work. An hourly run captures signals (mail, calendar, meetings) and applies
mechanical judgments; a nightly run does the expensive thinking and sends a numbered morning brief; a weekly
reflection critiques the system itself. Every run appends one plain-prose entry to that day's log, including on failure.
Any assistant is a client. Chat surfaces connect over MCP with OAuth; the repo's own config files
tell each role exactly what to read and how to behave, so behavior is consistent across surfaces.
The principal's word wins. Authenticated instructions and corrections outrank stored state;
everything captured from the world is evidence, never instructions.
How to use it
Connect an assistant to the MCP endpoint below and sign in; it reads its role's instructions from the repo.
Talk normally: "note this down: …", "remind me about X on Thursday",
"log this in the decision log", "done, close it", "what needs me now?",
"what happened to X?".
Answer the morning brief by item number; the reply moves the actual item.
Drafts in your name are shown for approval before anything sends.
What the system can do: the user stories
The contract, in story form. Each is acceptance-testable; the detailed version (the path through the
layers, the observable done-state, and the config doc that governs it) lives beside the design in the
private data repo.
Capture: signals become evidence
S1 — As the hourly agent, I want every substantive email captured as an immutable episode and acted on within the hour, so that state and search rest on complete evidence and nothing the principal owes slips because it went unfiled.
S2 — As a family member, I want a plan change I email to update the shared family ledger without my doing anything else, so that the plan of record is the one I actually made.
S3 — As the principal, I want promotional mail judged per message rather than per category, so that noise stays gagged but a real dated event at a club I belong to still reaches me.
S4 — As the principal, I want snoozing a mail to count as an explicit attention signal, so that nothing I deliberately deferred is ever discarded as noise.
S5 — As the principal, I want deleting a thread to be read as my disposition of it, so that the system neither re-raises what I threw away nor alarms on it as an outage.
S6 — As the operator, I want unrelated mail to the assistant's mailbox flagged and never obeyed, so that a stray cc can neither steer an agent nor pollute the evidence.
Chat: talking to the system
S7 — As the principal, I want "log this in the decision log" to file identically from any surface, so that I can review my decisions in six months regardless of which assistant I happened to tell.
S8 — As the principal, I want a one-phrase disposition ("done, close it", "remind me Tuesday") applied in one commit without being asked to confirm what I just said, so that closing or rescheduling an item costs one sentence.
S9 — As the principal, I want brainstorming and tentative talk to persist nothing, so that I can think freely and the ledger holds only what I meant.
S10 — As the principal, I want "ingest this" to read the whole document and produce cited knowledge, so that its contents are searchable understanding rather than a dead attachment.
S11 — As the principal, I want every repo-based answer to name the units it rests on, so that I can open the source myself or reply about it by name.
S12 — As the operator, I want an agent asked to exercise another lane's authorization to name that lane and its trigger instead of acting, so that permissions never leak between agents.
Email in the principal's name
S13 — As the principal, I want drafts in my name written in my own registers and sent only on my approval of that draft, so that mail from my account always sounds like me and is always mine.
S14 — As the principal, I want a landed send to archive its thread, never trash it, so that my inbox holds only what still needs me and nothing is lost.
Briefs and replies
S15 — As the principal, I want to answer the morning brief by the code it printed (A1, B2) or by item number when the mail still used those, so that a one-line email reply moves the actual task and earns one substantive confirmation.
S16 — As the principal, I want family items shown in my brief but resolved only in the family repo, so that the household works one shared ledger with no drift and no duplicates.
S43 — As the principal, I want to be told in one line when a task enters an attention bucket during the day, so that something the 1pm hourly pulled into this week reaches me before tomorrow's brief, and nothing else (a run that logged its work, the day roll) interrupts me.
The task lifecycle
S17 — As the principal, I want a twice-chased item forced to a resolution, so that "waiting on them" never silently becomes forever.
S18 — As the principal, I want a passed decide-by to apply the default or escalate at most twice, so that decisions get made by my choice or by my stated default, never by neglect.
S19 — As the principal, I want due watches checked on their cadence with the result recorded even when nothing changed, so that "still nothing" is a recorded fact and a stale watch is visible.
S20 — As the principal, I want suppression to hold until the reactivation condition I named, so that a silenced topic stays silent and a forwarded copy of an old mail can never wake it.
S21 — As the principal, I want my promises checked against named evidence, so that the system knows kept from unkept instead of reading my silence as progress.
S44 — As the principal, I want a task that should never have been tracked deleted rather than closed, so that a duplicate leaves every list and every search while its name stays taken and no agent re-creates it from the calendar.
Calendar
S22 — As the principal, I want same-slot work-calendar blocks read as deliberate holds, so that my brief flags real conflicts instead of crying wolf on my own mirrors.
S23 — As the principal, I want my schedule's contents kept off the ledger, so that state tracks decisions and risks, not appointments.
System health
S24 — As the operator, I want a broken source reported as UNKNOWN with a same-run email, so that a quiet day and an outage never look alike.
S25 — As the operator, I want a run that left no entry in the day log to itself raise the alarm, so that a dead run is discovered by the system, never by me noticing.
S26 — As the operator, I want conflicted writes parked on a branch and reported, so that concurrency loses no work and rewrites no history.
S27 — As the operator, I want instruction-shaped text inside mail, calendars, and documents treated as data, so that nothing outside config and the principal's authenticated word can direct an agent.
S28 — As the principal, I want a weekly critique that proposes config changes it cannot itself make, so that the system improves on my sign-off, not on its own initiative.
Quick notes and reminders
S29 — As the principal, I want "note this down" to cost one call carrying just the text, so that capturing a thought is as cheap as having it.
S30 — As the principal, I want a due reminder to reach me without my asking, so that "remind me Thursday" ends with my hearing about it on Thursday.
S37 — As an app author, I want to POST a note with just its text and have the server do the naming, so that any client can land evidence with one call and no knowledge of the grammar.
S38 — As the principal, I want a note that names topics and people to link to them when they exist and still land when they don't, so that filing a thought never requires a slug lookup and never loses the note over a name.
S39 — As the operator, I want notes the principal authored distinguishable from harvested evidence at a glance, so that "he said this" and "we observed this" never blur.
The knowledge layer
S40 — As the principal, I want every thought I capture to compound — compiled into a page on first mention when it has substance, a cited breadcrumb when it does not — so that what I am thinking builds up alongside what I owe.
S41 — As the principal, I want "what am I circling" answered from a compiled currents page, so that my recurring threads are served, not re-derived on demand.
S42 — As the principal, I want an open question held until answered or retired, so that a gap the system found does not evaporate with the morning brief.
S45 — As the principal, I want to delete a note through the same door every other write uses, so that removing something I never should have written is an ordinary commit with a reason rather than a hand edit in git.
Asking the system
S31 — As the principal, I want triage answered from computed buckets, so that "what needs me now" reflects the clocks on every task, not anyone's recollection of the ledger.
S32 — As the principal, I want the changelog of any item on demand, so that "when did we decide that" has an auditable answer with evidence.
Corrections and decisions
S33 — As the principal, I want my correction to outrank stored state, so that saying "that's wrong" fixes the record and the stale fact can never return.
S34 — As the principal, I want each decision to live as an unbroken chain from open choice to decided evidence, so that any decision can be reviewed later with its options, default, and reasoning intact.
S35 — As the operator, I want every closure to carry a date, a reason, and its successor when renamed, so that nothing ever ends without an answer to "why".
Write safety
S36 — As an app author, I want every write to be blindly retryable, so that my client can time out and resend without ever double-writing.