Skip to main content
Glama

Iris

A self-hosted personal AI assistant that runs my life over Telegram — calendar, tasks, daily planning, memory — built as a custom MCP server and hook-plugin suite on top of the open-source OpenClaw agent harness, with Claude as the intelligence.

The design bet: an assistant you trust with write access to your life cannot be a prompt. Everything that must never go wrong — action gating, priority ranking, conflict resolution, provenance, "what day is it" — is deterministic, unit-tested code. The model supplies judgment inside an envelope that code enforces.

Why it exists

Calendar, task app, and notes are three disconnected surfaces, each claiming to be the truth. Iris inverts that: a small git-backed "brain" (mission → goals → priorities) that I own is the single source of truth, and the calendar/task apps are projection surfaces rendered from it. The assistant reads all of it, ranks the day deterministically, delivers a morning digest, and acts — creating events, moving tasks, updating memory — behind approval gates that scale with blast radius.

It has been my daily driver since June 2026.

Related MCP server: autoMate

Architecture

flowchart LR
    TG[Telegram]

    subgraph BOX["Ubuntu box — Docker, Tailscale-only, no public ports"]
        GW["OpenClaw gateway<br/>(rented: agent loop, channels, cron)"]
        subgraph OWNED["Owned core — this repo"]
            MCP["MCP server (src/)<br/>planner · brain · memory · taxonomy<br/>reconciliation · security envelope"]
            PLUG["Hook plugins (plugins/)<br/>confirm-gate · verify-gate<br/>live-state · traits · prompt-capture"]
        end
        BRAIN[("Markdown brain + memory<br/>git-backed workspace")]
    end

    TG <--> GW
    GW <-->|"tools"| MCP
    GW -.->|"before_tool_call · prompt hooks"| PLUG
    MCP <--> BRAIN
    GW <--> GCAL["Google Calendar MCP<br/>(rented, OAuth scope-narrowed)"]
    GW <--> TODO["Todoist MCP<br/>(rented, tool-allowlisted)"]
    GW <--> ANTH["Anthropic API<br/>Haiku default (live) · /model escalation"]

Own the brain, rent the surfaces. The repo builds only the differentiator — planning, memory, authority, safety. The agent loop is rented (OpenClaw), the calendar and task surfaces are rented MCP servers pinned and narrowed to least privilege (OAuth scope patch on the calendar server; tool allowlists on both). The security envelope wraps the rented servers too.

Component map

Path

Responsibility

src/planner/

rank_day — pure, LLM-free day ranking: weighted-additive score + Eisenhower quadrant + time-block-aware plan

src/reconciliation/

Authority engine: a brain-vs-live conflict is decided by the slot's type-authority prior (state→live surface, intent→brain), downgrading to flag-and-ask when the prior's loser is fresher; same-side conflicts use a recency → provenance → ask ladder. No model on the path

src/taxonomy/

Action classifier: every tool call maps to autonomous / auto+notify / confirm-first / quarantine+confirm by reversibility + blast radius

src/security-envelope/

Quarantine (untrusted-content sanitize + envelope), provenance tagging, Rule-of-Two invariant, web egress gate

src/brain/, src/memory/

Git-backed Markdown SSOT: read tools + gated write tools (propose/commit_brain_edit, memory_promote/memory_forget) — every durable write is one git revert from undone

src/traits/

Owner-tuneable personality dials (humor, verbosity, bluntness…) with a non-tuneable safety/honesty floor

src/grounding/, src/projection/

Verify-before-act helpers; calendar-as-projection write path (tagged, idempotent by record id)

plugins/confirm-gate/

before_tool_call hook → runs the taxonomy classifier → fail-closed Telegram approval via a text /approve <id> allow-once|deny command (300s timeout → deny); also hosts the web-egress gate

plugins/verify-gate/

Hard-blocks destructive calendar and Todoist writes whose target wasn't read in the same turn

plugins/live-state/

Injects fresh calendar/task state + an authoritative local Now: line every turn — time is an injected fact, never a model inference

plugins/traits/, plugins/prompt-capture/

Persona rendering into the system prompt; wire-level capture feeding the eval harness

scripts/eval/

Offline model-eval harness: wire-exact corpus, replay across providers, deterministic scorers, cross-family LLM judge

deploy/

Hardened gateway config, compose, vendored patches (pinned + hash-checked)

prs/, docs/

The development process: one research-gated PR file per change, architecture SSOT, design logs with the full decision trail

The gated write path

flowchart TD
    A["Proposed tool call"] --> V{"verify-gate:<br/>destructive write —<br/>target read this turn?"}
    V -- "no" --> B["Blocked → model told to read first"]
    V -- "yes / not destructive" --> T["taxonomy classifier<br/>(deterministic, unit-tested)"]
    T --> C{"action class"}
    C -- "autonomous /<br/>auto+notify" --> X["Execute"]
    C -- "confirm-first /<br/>quarantine+confirm" --> P["Telegram approval — /approve command<br/>fail-closed, 300s timeout → deny"]
    P -- "approve" --> X
    P -- "deny / timeout" --> D["Denied"]

Governing invariant (Rule of Two): no single operation may combine reads untrusted content + accesses sensitive data + changes external state without a mandatory human gate. In practice it's enforced as a system rather than one choke-point function: session taint escalates every same-turn write after untrusted input, and the sensitive store is read through its own gated tool. Confirm-gate additionally runs a web-egress gate — a web_fetch to a domain this turn's searches never surfaced is confirm-first (kills the classic exfil-by-URL channel). Prompt injection is unsolved; the dangerous combination stays permanently gated no matter how good the model is.

Key design decisions

Each of these had a live alternative that was researched and rejected — the full trail is in docs/*/DESIGN-log.md and the prs/ files.

  1. Deterministic gates, not prompt-based safety. System-prompt instructions like "verify before acting" were live-tested and proven insufficient — the assistant still moved real calendar events off a wrong-day inference. The fix each time was a code-level hook (verify-gate, confirm-gate) that makes the failure structurally impossible rather than discouraged. Rejected: relying on model compliance.

  2. Logic in code wherever judgment isn't required. Ranking, conflict authority, action classification, and time grounding are pure functions with unit tests. Deterministic code beats model judgment over long context, and the system stays correct even with extended thinking off. The model handles what only a model can: natural-language policy, tie-breaks, conversation. Rejected: letting the LLM rank the day and arbitrate stale-vs-fresh conflicts.

  3. Quarantine untrusted content at persistence time. Calendar invite notes and fetched web content are Unicode-stripped, wrapped in an explicit "data, not instructions" envelope, and provenance-tagged untrusted-derived before the planner ever sees them — a synchronous rewrite hook, not an async model pass — and the turn is tainted so same-turn writes escalate to gated approval. Nothing untrusted is ever durably written unguarded (anti-memory-poisoning; injection canaries live-verified quarantined). PDF attachments take a separate path: the runtime's bundled extractor inlines them inside OpenClaw's native untrusted-content framing (canary-verified live), not the owned pipeline. Rejected: dual-LLM token isolation — the runtime's persist hook is synchronous, so it's deferred, not dismissed.

  4. Model selection by measurement, not vibes. scripts/eval/ replays the assistant's own captured traffic offline against candidate models with deterministic scorers and a cross-family judge. The capture path is wire-exact (billed request body reproduced to ±0 tokens) after the naive approach — replaying reconstructed trajectories — was tested and refuted (−18.8% token fidelity). The harness's verdict set the current default (Haiku, −67% cost/turn at parity for routine traffic, with per-conversation escalation to Sonnet/Opus). It also halted a shipped decision: per-turn cross-provider routing was reverted when the live trial showed a stateful turn ships its whole session history to whichever provider serves it — the privacy carve-out unit is the session, not the turn. Rejected: benchmark-driven model choice, and the cross-provider router it initially justified.

  5. Time is an injected fact. A real incident (assistant asserted the wrong weekday, concluded the calendar UI was buggy, and moved real events) traced to a context where every ambient timestamp was UTC and no authoritative local "now" existed. The fix: a hook injects Now: <local datetime> — AUTHORITATIVE plus weekday annotations on every date, each turn, cache-neutrally. The incident class is closed structurally. Rejected: prompt rules telling the model to be careful about timezones.

Testing

294 tests across 22 files (vitest), verified passing from a clean clone. Coverage follows the "logic in code" rule — the deterministic pieces are the tested pieces:

  • ranking math, taxonomy classification, reconciliation authority, provenance parse/render, quarantine sanitization, egress-gate policy, eval-harness scorers/corpus logic

  • adversarial fixtures: prompt-injection and memory-poisoning payloads assert the gates fire and nothing durable is written from untrusted content

  • beyond unit tests, every PR in prs/ records its live binding test — the deployed behavior verified over Telegram against the real gateway before the PR closes

npm ci
npm test        # 294 tests
npm run typecheck
npm run build   # server bundle; build:plugin:* for each plugin

Running it

This is a personal, single-user system — the repo is published as a working reference, not a turnkey product. A full deployment needs an OpenClaw gateway (Docker), a Telegram bot, Google Calendar OAuth, a Todoist token, and an Anthropic API key; deploy/ contains the hardened gateway config, compose file, vendored patches, and a README with the wiring. One drift note: the committed gateway config predates the Haiku-default model switch (PR-033, applied on the live box) — it still pins Sonnet as primary. Expect to adapt paths and secrets handling to your own box.

Status — honest scope

  • In daily use since June 2026; v0.2.x. The commit history is the real changelog — each change is a research-gated PR with verification criteria.

  • The agent loop, channels, and cron are OpenClaw (third-party). This repo is the MCP server, plugins, eval harness, and deployment hardening on top.

  • Proactivity is deliberately minimal (one daily digest); the interrupt engine is designed but deferred.

  • Scanned/image-only PDFs don't reach the turn (documented gap); finance integration is designed for a sidecar-isolation pattern but not built.

  • Two vendored runtime patches (thinking-block handling, wire capture) are pinned to the current OpenClaw release and retire when upstream ships equivalents.

License

MIT

Available Tools

14 tools
commit_brain_editCommit a proposed brain edit (writes + git-commit)A

Write a previously proposed brain edit to the workspace and git-commit it (provenance-tagged). Call ONLY after the user has explicitly approved the diff from propose_brain_edit. Requires the token from that proposal.

Inputs: token (required).

healthOwned-core health checkA

Return the owned-core server's health/status. Call this to confirm the owned-core MCP server is reachable end-to-end.

Inputs: no named parameters.

memory_forgetRemove a fact from durable memory (writes + git-commit, gated)A

Remove one entry from MEMORY.md (e.g. when the user says to forget/correct a remembered fact) and git-commit the removal — the fact stays recoverable from git history (not a hard delete). This is a GATED action: it pauses and shows the targeted entry for a one-time approval before removing; just call it (no separate confirm needed). match is a distinctive substring of the entry to remove; it refuses if zero or more than one entry matches (it will not guess).

Inputs: match (required).

memory_promotePromote a fact to durable memory (writes + git-commit, gated)A

Curate a durable fact into MEMORY.md and git-commit it (provenance-tagged). This is a GATED action: it pauses and shows the fact to the user for a one-time approval before writing — you do NOT need to ask for confirmation separately first; just call it. Set sourceClass from where the fact came from — use 'untrusted-derived' for anything originating from invite/web/quarantined content (it requires confirmation). pointer is a reference back to the source (daily-log timestamp, message id, record id).

Inputs: content (required), pointer (required), sourceClass (required).

memory_sensitive_getRead the gated sensitive store (legal/medical)A

Retrieve sensitive records (e.g. legal, medical) from the gated sensitive store. These records are NOT in your normal context — they are never auto-loaded and never searched — so you MUST call this tool when the user asks about, or you need, sensitive info like medications, legal status, etc. Optional topic filters by record name (e.g. 'medical', 'legal'); omit to list all. This read is gated only when the turn contains untrusted content (then it requires approval); a normal request from the owner runs directly. Never copy sensitive content into durable memory (memory_promote) or any outbound/external action.

Inputs: topic.

project_dayDiff the daily plan against the calendar (idempotent projection)A

Compute which calendar writes make the user's calendar match the day's plan (calendar-as-projection). FIRST gather: (1) desired — the task blocks from rank_day's DailyPlan (each recordId = the Todoist task id, plus summary/start/end); (2) existing — the assistant's already-placed events from list-events, filtered to those tagged extendedProperties.private.source="assistant" (pass each event's id as eventId, its extendedProperties.private.recordId, summary, start, end). This returns {toCreate, toUpdate, stale, unchanged} (idempotent by recordId). THEN execute it: for each toCreate call create-event passing its extendedProperties verbatim (so the tag round-trips); for each toUpdate call update-event with its eventId + new fields. Do NOT delete stale events — report them to the user; their removal is confirmation-gated (PR-010). This is auto+notify: proceed without confirmation, then tell the user what changed.

Inputs: desired (required), existing (required).

propose_brain_editPropose a brain edit (no write)A

Propose new content for an owned-brain file (GOALS.md, PRIORITIES.md, or MISSION.md) drafted from the conversation. Returns a fenced diff (current→proposed) and a token. This does NOT write anything. Relay the diff to the user verbatim as a code block and get their explicit approval; only then call commit_brain_edit with the token. Provide the FULL new file content (the proposal replaces the file).

Inputs: target (required), content (required).

rank_dayRank tasks + build a daily plan (deterministic)A

Compute a priority-ranked, time-block-aware daily plan from tasks + calendar events you supply. Gather the inputs FIRST via the other tools, then pass them here: tasks from Todoist (find-tasks / find-tasks-by-date) — pass each task's raw fields incl. priority (Todoist API: 4=P1 highest … 1=P4), due, deadline, duration; events from the calendar (list-events) and optional busy intervals from get-freebusy; and now/timezone from get-current-time. This returns the DETERMINISTIC ranking + plan (weighted importance×urgency score + Eisenhower label, duration-aware placement). It does NOT apply your PRIORITIES.md/GOALS.md policy — read those (read_priorities/read_goals) and apply them yourself as a tie-breaker/override on the returned ranking before presenting the plan.

Inputs: now (required), tasks (required), events (required), timezone (required), +1 more.

read_goalsRead owned-brain goalsA

Return the full GOALS.md (long-horizon goals) from the owned brain. The planner reads this to ground priority ranking. Read-only.

Inputs: no named parameters.

read_missionRead owned-brain missionA

Return the full MISSION.md (the user's stable life-mission / statement of intent) from the owned brain. Read this when discussing or setting goals — goals ladder up to the mission. Read-only.

Inputs: no named parameters.

read_prioritiesRead owned-brain prioritiesA

Return the full PRIORITIES.md (ranking policy) from the owned brain. The planner reads this as the natural-language ranking policy. Read-only.

Inputs: no named parameters.

reconcile_and_rankReconcile durable facts against live state, then rank the day (deterministic)A

Use this INSTEAD of rank_day when a durable brain fact might override live task state — it reconciles then ranks in one deterministic pass, so nothing relies on you remembering to reconcile. Pass the same inputs as rank_day (tasks/events/busy/now/timezone) PLUS overrides: keyed brain claims (each entityKey like todoist:task:<id>, a field such as priority or due, its brain value, slotType = intent when the brain is authoritative (a deliberate override) or state when it's just a remembered value, plus the fact's at/sourceClass). Returns {plan, applied, flags}: plan is the recomputed daily plan (built FROM the reconciled values); applied lists overrides that won and changed the plan (mention them to the user); flags are genuine contradictions the code would not auto-resolve — ASK the user about each, don't guess. Unkeyed prose facts are not reconcilable here (by design) — leave them out of overrides.

Inputs: now (required), tasks (required), events (required), timezone (required), +2 more.

reset_personalityClear the runtime personality override (gated)A

Clear any temporary (session-scope) personality override and revert to the durable default dials. GATED (one-time approval). Does not change the durable defaults themselves. Call this when the owner wants to drop a temporary style change.

Inputs: no named parameters.

set_traitSet a personality dial (gated, style only)A

Adjust one of Iris's STYLE dials on a 0–100 scale: humor, verbosity, bluntness, proactivity, warmth. This is a GATED action — it pauses for the owner's one-time approval, then takes effect on the NEXT turn (no /new needed). Use scope: "durable" (default) to change the standing default, or scope: "session" for a temporary runtime override that leaves the durable default intact. Higher = more of that trait. You CANNOT dial truth, accuracy, verify-before-claim, safety, or Rule-of-Two — those are invariants, not dials, and the tool will refuse them. Call this only when the owner asks to change your style.

Inputs: level (required), trait (required), scope.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools target a distinct resource+action: the three brain reads map to three separate files, propose/commit are clearly staged, and the memory trio (promote/forget/sensitive_get) are separable. The one real overlap is rank_day vs reconcile_and_rank, which do near-identical work, but the description supplies an explicit decision rule ("use this INSTEAD of rank_day when a durable brain fact might override live task state").

    Naming Consistency4/5

    Nearly everything is snake_case verb_noun (read_goals, propose_brain_edit, memory_promote, set_trait, rank_day), so the pattern is predictable. Minor deviations: the bare noun `health`, the conjunction in `reconcile_and_rank`, and the noun-first `project_day` / `memory_sensitive_get` break the verb-first rhythm slightly.

    Tool Count5/5

    14 tools is squarely in the well-scoped band, and each one maps to a real capability: brain reads, staged brain writes, memory curation, style dials, and day planning/projection. Nothing appears redundant or vestigial.

    Completeness4/5

    The brain lifecycle is covered (three reads plus propose→commit approval flow), memory has promote/forget/sensitive-read, and planning has rank/reconcile/project. Minor gaps: no tool to list or read MEMORY.md entries explicitly (relies on auto-loading), and no getter for current style-dial values, only set/reset.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Self-hosted MCP server giving AI agents persistent memory for personalization and context across conversations.
      174 PyPI
      284
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      A personal AI assistant server that provides MCP tools for notes, files, reminders, memory, shell, browser, and 30+ SaaS integrations, enabling AI clients to access and manage your data across sessions.
      4,009
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      A self-hosted MCP server that provides any LLM with a graph-backed memory layer of your life—tasks, email, finance, contacts, calendar—plus autonomous agent offices that act on your behalf.
      153
      3
      Apache 2.0