Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

fix(memory): review chats that read mail and count misses the product recorded (#549)

Rufusfbcf3d2d4ad7
diff --git a/packages/core/openexecutive/architecture/architecture-facts.yaml b/packages/core/openexecutive/architecture/architecture-facts.yaml
index be696e85..c2873352 100644
--- a/packages/core/openexecutive/architecture/architecture-facts.yaml
+++ b/packages/core/openexecutive/architecture/architecture-facts.yaml
@@ -5089,8 +5089,15 @@ chat:
Conversation review (memory/chat_review.py). The post-turn block keeps a
verified speaker's turn (principal on a people_tools-verified surface, or
a rostered teammate on their own web chat, Slack or Discord; never an
- email, unattended run, private-to-principal turn, mailbox turn or an
- attachment) in chat_review_turns: own words, reply, tools run. One
+ email, unattended run, private-to-principal turn or an attachment) in
+ chat_review_turns: own words, reply, tools run. A turn that touched the
+ speaker's mailbox, and every turn of a mail-private conversation, is kept
+ too, for their own review only: tools kept by name with only a failure
+ marker (no result text, the results are other people's mail), no
+ remember_fact in its fix loop, its lessons never shared, the Reflection
+ screen shows it to its owner alone (_session_access), and the review and
+ replay passes over it write every audit row as that person's own
+ (chat_review_turns.mail, mail_private_turns, rows_for_person). One
chat_review __internal__ action per conversation fires 30 minutes after
the last turn (pushed back while the chat goes on) and runs one small
tool loop per person (CHAT_REVIEW_MODEL, default ROUTING_MODEL; 5 rounds,
@@ -5109,10 +5116,12 @@ chat:
forced grade_turns call (actor chat_review_grade): fine, miss (kind
company = a fact or preference it lacked, product = something it could
not do) or unclear, with what the person wanted instead and a 4+ word
- quote that must appear in that or a later turn, else the grade is unclear.
+ quote that must appear in that or a later turn, or a signal other than a
+ thumbs up on the turn, else the grade is unclear.
The grader reads the signals the product recorded about each turn:
thumbs up/down and the note (chat_messages.feedback, joined by the saved
- reply's first 120 characters), stopped replies, a rewind
+ reply's first 120 characters, or typed or said as the whole next message
+ in a chat app, which has no buttons), stopped replies, a rewind
(session_rewound audit row after the turn), a claim-check nudge
(claim_check audit row by turn_id) and failed tool calls. Grades land on
chat_review_turns (verdict, kind, wanted, signals, graded_at, message_id)
@@ -5130,7 +5139,7 @@ chat:
working-style deny-list plus the lessons' own (information-moving
verbs, everyone/everything words) without the about-the-writing
requirement, re-checked on every render. Stored in chat_review_lessons
- (shared = learned in a channel or group thread); chat_review_lesson_uses
+ (shared = learned in a channel or group thread that never read mail); chat_review_lesson_uses
records which turn id, and whose, saw which lesson. Reaches a turn by keyword match (two shared content words
between lesson+quote and the message; no vector index): the Executive's
turn as a <lessons> user-turn block (build_lessons_block, counted as
diff --git a/packages/core/openexecutive/architecture/prebuilt/lifecycle.json b/packages/core/openexecutive/architecture/prebuilt/lifecycle.json
index 9d49399a..da1a7ea8 100644
--- a/packages/core/openexecutive/architecture/prebuilt/lifecycle.json
+++ b/packages/core/openexecutive/architecture/prebuilt/lifecycle.json
@@ -1,7 +1,7 @@
{
"section_id": "lifecycle",
"title": "Request Lifecycle",
- "markdown": "A single chat message makes a full round-trip through the API, the orchestrator's tool-use loop, a parallel specialist fan-out, and synthesis — all streamed back as server-sent events.\n\n### Steps\n\n1. **Arrival** — the client mints a `client_turn_id` and posts to `POST /chat` (`openexecutive.api.routes.chat`). The turn carries a `<current_speaker>` hint resolved from the caller's `person_id` (followed by that person's `<working_style>` rules when they have any — see the attunement section — and a `<lessons>` block when a lesson the conversation review learned from a miss matches the message, `memory/lessons.py`; see the memory section), plus a `<briefing>` digest of current open alerts (built in parallel with RAG/episodic/peer-memory fetches) so the Executive can discuss any item shown on the `/today` briefing page. A turn arriving from a chat adapter instead of the web app also carries a `<channel>` block naming the surface and stating which approvals can be completed there; on Slack the `<briefing>` digest is gated to the principal's DMs. All three ride in the **user turn**, never a cached system block, as does a `<drive_memory>` block naming the Drive files this conversation already found or opened and the Drive searches that matched nothing (see the memory section). A `<pending_followups>` block lists, for a verified speaker, the follow-ups they scheduled that haven't gone out (up to 10, from `correction_tools.pending_followups_block`, the same ownership rule as `list_followups`), and asks the Executive to cancel one with `cancel_followup` when the message shows it is already done or no longer needed, and say so in a line. The server registers a stop switch under that id *before* the context fetch, so a Stop pressed during those first seconds halts the turn before any model call is made.\n2. **Tool-use loop** — the `Executive` calls Claude. For a cross-domain question the assistant turn emits multiple `consult_specialist` tool-use blocks at once. The call carries the conversation so far (`Session.get_recent_history`: 20 to 30 turns, its start moving in steps of 10) with a 1h cache marker on the previous reply, so each message reads the earlier conversation from the prompt cache and writes only what is new (see Caching); on the OpenRouter path the translator keeps that marker on the reply's text. The history is re-read from the stored transcript at the start of every web turn, so a chat continued in a chat app and then reopened on the web or phone includes the turns the app added.\n The person can keep typing while it works. A message sent then (`POST /chat/add`) joins the running turn: the loop adds it after the next round's tool results, so the answer follows it, and it is saved as its own message before the reply. One that arrives while the final answer is being written becomes the next turn instead. A conversation runs one turn at a time.\n3. **Parallel fan-out** — `openexecutive.orchestrator.router.route_parallel` dispatches those calls concurrently, bounded by `MAX_PARALLEL_SPECIALISTS`; calls past the cap get a skip tool_result. A specialist that raises (a timeout, an overloaded model) or returns no text no longer fails the batch: its tool_result says it is unavailable and tells the Executive not to invent its view, the others' results stand, and the turn goes on. It does not count as consulted, so it takes no committee seat and no department memory records the turn, and its documents are left out of the answer's sources. On the web chat the reply need not mention the gap, because the app shows it under the answer; on every other channel the tool_result asks the Executive to say in one sentence that part of the analysis is missing. A knowledge retrieval that fails likewise leaves that specialist without context rather than failing the turn.\n4. **Per-specialist RAG** — each specialist runs its own domain-filtered ChromaDB query, then reasons over the retrieved chunks and returns analysis as a tool_result. Its user turn also carries a `<company_stage>` tag from the session's company profile, so stage-sensitive advice (venture benchmarks vs. cash-first for a bootstrapped company) does not depend on the Executive remembering to mention it. Once the batch is done, the documents each answering specialist's retrieval returned are named, in call order, into the turn's `TurnSources` (`orchestrator/answer_sources.py`), which the web chat route owns and which also holds its own search's documents. Synced Google Drive files are recorded as `drive` sources with their Drive link, and the web chat lists them under **Google Drive**.\n5. **Synthesis** — the Executive feeds the tool_results back to Claude and streams one coherent reply. Every tool round — not just a specialist one — emits an `activity` event naming what is running, immediately followed by a `thinking` keepalive. The label names the *activity*, never the internal agent: \"Putting time on the calendar…\", \"Looking up people…\", or, for a connected (MCP) tool, plain words for what it does (\"Searching Drive…\"), from the same table (`orchestrator/tool_labels.py`) that names the finished chip (\"Searched Drive\"). The raw `server__tool` name never reaches the user. Under the reply, repeats of the same action collapse into one chip with a count, and tapping it lists what each run looked at. A round that really does fan out collapses to the generic \"Consulting specialists…\" — the one voice holds even in the progress line. The keepalive carries no tool information of its own; it used to drive a hardcoded \"Consulting specialists…\" string, so an MCP or calendar round misreported itself as a fan-out.\n **Do what it says.** Before the turn ends, its last reply is checked against the tool calls the turn made (`orchestrator/claim_check.py`). A reply with no word that can claim a change (\"done\", \"removed\", \"I'll remind you\"…) ends the turn as before. Otherwise one small forced-tool call on `ROUTING_MODEL` reads the person's message, the reply and each call with the start of its result, and reports a claim of a change no call made (or put up for approval). The claim must appear word for word in the reply, or it is ignored. The loop then gets one more round with a note in the user turn (never a cached block): make the change with the right tool, or say plainly it isn't done. Once a turn; a failed check lets the reply through. On the web chat the extra round streams after the first reply, separated by a blank line; chat apps send the whole reply at once. `CLAIM_CHECK_ENABLED` turns it off.\n **A chat several people are in.** When its owner shared a web chat (`session_shares`), every turn in it is labelled: the history is re-read with each person's message starting `[Name]: `, the current message too, and a note naming everyone in the chat rides in the user turn (`channel_context_block`, never a cached block). The Executive answers whoever wrote the latest message. Such a session is no private conversation (`Session.shared_chat`): Act as me is off there (`delegation.settings.private_conversation`), open loops are not listed as on a private surface, no one's mail is read there, the principal's included (`teammate_mail._reader_id`), what the Executive remembers about the speaker (peer memory) is not fetched, the alert digest leaves out the principal's private cards and roster requests (`briefing.context.render_and_trust`), and the principal-only tools are withheld whoever speaks (`content_trust.principal_only_withheld`), because the others write into what the principal's turn reads. A message that starts like a label (`[Alex]: …`) loses it before its sender's own goes in front. Peer memory still records each person's own words. Turns stay one at a time under the conversation's lock; the route publishes each one to the chat's live stream (`api.chat_live`) as it runs, so everyone else in the chat watches it happen. A chat of one publishes nothing.\n6. **Optional committee review** — when enabled, `Executive.stream_chat_with_committee()` runs a silent draft, parallel reviewer critiques, then a streamed revision pass.\n7. **Side effects** — after the reply, every rostered speaker's turn (not only the principal's) schedules a fire-and-forget **open-loop pass** (Attunement) beside the episodic extraction: a keyword prefilter, then one forced-tool call that may open or close loops, every item quote-gated against the speaker's own words. A verified speaker's turn is also kept for the **conversation review** (`memory.chat_review`, see Memory), which reads it once the chat has been quiet 30 minutes and fixes what the replies left undone, from the speaker's own quoted words. The user message is persisted with `sender_person_id` — the resolved speaker, never the principal fallback a Discord / Telegram session uses for ownership — and the session records the speaker for the turn (`Session.caller_person_id`), which `close_open_loop` reads. A DM sent while proactive work is tagged (`attunement.outcomes.tag_proactive` — scheduler dispatch, reflection, research, alert review) also opens an outcome-ledger row at `_record_outbound_context`; a user's own turn is never tagged. A tagged DM is also subject to the recipient's own notification settings: in their quiet hours, or when they chose *In my briefs*, the send handler stores it (`outbound_guard.check_hold`, `people.held_messages`) and returns `{\"status\": \"held\"}` instead of sending (see Org). Any side-effecting tool call surfaces an `action_taken` chip, which unlike the ephemeral `activity` label is persisted with the assistant message; once the reply is over — also when it was stopped or timed out — the web chat route sends one `sources` event: the documents and web pages the turn looked at (its own search, each specialist that answered, web search results, and the pages the reply cites, which are always kept) and the areas (\"finance\", never a specialist) it had to go without. The web chat shows it under the reply, and it is persisted with the assistant message as `chat_messages.sources`; other channels don't collect it. The stream closes with a `done` event — preceded by a `stopped` event when the user halted the turn, in which case the partial reply is still persisted and flagged so it reads as cut short rather than complete, and is mirrored into the live in-memory session so the next turn's prompt matches what was saved. The stream still ends with `done` event. While nothing else is going out — a slow tool call, a long specialist round — the route sends an SSE comment (`: keepalive`) every `CHAT_STREAM_KEEPALIVE_S` (15 s by default, 0 for none) so a browser or proxy does not drop the connection as idle; the step it waits on keeps running across it, and the whole-turn deadline is unchanged. Every call through the MCP gateway (Gmail, Calendar, Drive, Outlook, OneDrive, tool search) has its own ceiling, `MCP_TOOL_TIMEOUT_S` (120 s): past it the model gets an error saying the tool did not answer and may still have run, so it checks before calling again, and no outbound linkage is recorded for a send that timed out. One side-effecting tool is gated server-side rather than by its description: `ack_alert` will only accept an `alert_id` from the live alert board the server itself derived this turn — the whole live set, not only the rows the `<briefing>` digest printed, since `/today` renders more cards than the digest lists and every one of them is Discuss-able — and it fails closed, so an id it cannot even parse is refused rather than waved through to the handler's own parse. That check runs on **every** session. It used to run only on turns that arrived from a chat channel, keyed on `origin_channel`, which the browser never sets — so the web, the surface the principal actually uses, was unchecked and the model could ack any id, including one quoted out of an alert body by the briefing page's Discuss handoff. What that buys is bounded and worth stating plainly: an id that is invented, closed, snoozed or expired is refused, including one quoted out of an attacker-written alert body; the model being argued into acking the wrong *live* card is not prevented. The one way to widen that set is `find_alerts`, for an item the principal names that has left the live board (already opened, snoozed, older than the board): a keyword search over alerts of every status whose own results — never an id the model supplies — join the trusted set. It runs only in a turn where `render_and_trust` showed the principal their own board (`Session.principal_board_shown`: the verified principal, and on a channel only in their DM), never merely because the session has a set — every `Session` starts with an empty one, and that empty set is how a Google Chat turn, someone else's DM or an unattended pass refuses every ack — and not on the principal's turn in a shared Slack or Discord thread either, where others read the reply and write into what the model reads. It trusts only rows still open (`unread`, `read`), never a roster-request card, and at most 25 ids per turn across calls, and refuses a query with no word of three or more letters. It also moves the admitted limit outward: a model argued into the wrong search can now reach up to 25 open alerts that are off the board, not only live ones. The board is recorded on the turn's `Session`, and the route binds that session for the **whole** SSE body (`schedule_tools.set_session`, alongside `set_turn`) rather than letting `stream_chat` bind it from inside its own generator. `_sse_body` drives the executive with `asyncio.wait_for(stream.__anext__())`, which runs each step in a fresh Task holding a *copy* of the context, so a binding made inside the generator is discarded with the step that made it: step one sees the session and every later step sees `None`. The tool-call loop runs on those later steps, so the whole guard read an empty set and refused every ack on the web — on live, open cards — until the binding moved out to the route. Anything reading `current_session` mid-turn has the same requirement, and two of them needed more than the binding to behave. `schedule_followup`'s seen-`channel_ref` anti-spam gate refuses a send to an address the session has not seen; with no session it skipped itself, so a web turn could schedule to **any** address, and with an empty one it refused even the principal's own. The route now seeds the caller's own addresses onto the session, so on web the gate means what it means on every other surface. Reply linkage (`_record_outbound_context`, read back by `inbound_hydration` to quote the originating conversation into the turn handling a recipient's reply) is the other: it was never reachable on web, and rather than switch that on for the principal's broadest surface as a side effect it is held back, keyed on an explicit `Session.from_web_chat` flag. Not on an empty `origin_channel` — alert review, the CLI and the unattended workflows all leave it empty while legitimately recording linkage, as does the email poller under its own `email` tag. `scheduled_actions` rows also take their `session_id` from the session. A session that was shown no board has an empty trusted set and can ack nothing, so the unattended passes (the nightly reflection, the research synthesis) are refused by default — they also still withhold the tool outright, which is belt-and-braces rather than the only thing stopping them. After the stream closes, the turn is also handed to the episodic memory extractor (`memory.episodic.schedule_extraction`, fire-and-forget) — on every turn where the principal said anything at all, and only the principal: a turn naming an `origin_channel` must resolve to a person marked `is_principal`, because the quote validator downstream cannot tell whose words it is checking. Both this path and the committee path call the same `should_extract` predicate, and it applies no length floor: the gate used to sum in the assistant's reply, which let a verbose answer drag a trivial turn in and discarded the short, decisive instructions that are the whole point of extracting. A user-side floor would fare no better — \"Do B.\" and \"Done\" are one character apart. See **Memory** for what that cost on a live tenant. None of this runs for a **replay** of a graded turn (`Session.replay`, `memory/replay.py`): the loop answers its acting tools with \"done\" and records them on the session, offers no script, job or server load, and skips every post-turn pass, so the nightly replay of the misses changes nothing and reaches nobody. On a team member's turn (`department_gate.speaker`) it also refuses an alert that is not routed to them (`routed_to_person_id`), so they clear only their own items; the principal clears anything on the board. `create_alert` on such a turn ignores the `source`, `external_id` and `from_address` it was given: the alert gets the source `team_member`, a fresh id and `raised_by` (their name), so it can't pose as mail or a watch, coalesce into one, or pre-claim the id a real alert will arrive with.\n8. **Tool failures** — a handler that raises instead of returning its JSON error is isolated: both tool gathers run with `return_exceptions=True`, the model gets an error `tool_result` naming only the exception's TYPE — a message can carry a filesystem path, a validation error echoing the input, or a third-party HTTP body, and anything in model context can be quoted back to the user, so the full repr stays in the log and the audit row — and the failure is audited with `ok=false`. Only `CancelledError` is re-raised, so turn-timeout and client-disconnect handling still work. Before this one crashing tool aborted the whole turn, which reached the user as an unexplained apology with no audit row (#136).\n\nWeb search, when invoked on the Anthropic path, executes inside the Anthropic API itself (`web_search_20250305`) and returns within the same generation; for any model routed via OpenRouter the same tool becomes OpenRouter's `openrouter:web_search` server tool, which also runs inside the generation with the same search cap and domain lists.\n\nThe install's workspace mode (solo or team, see Org) is read fresh at the start of each turn by `memory.workspace_settings.pin_turn_workspace_mode(session)` and pinned on the session for that turn only (`Session.turn_workspace_mode`): the persona, the org block, the tool list and every tool handler in the turn then agree, and a switch made mid-turn applies from the next turn. A session can instead carry an explicit override, `Session.workspace_mode` (`None` by default), which wins over both — so a caller that runs many conversations concurrently on one Executive, such as evals, can pick the mode per session rather than flipping the install-wide setting. Everything reads it through `effective_workspace_mode(session)` (override, then the turn's pin, then the setting). The principal's role is pinned the same way (`pin_turn_principal_role(session, mode)` → `Session.turn_principal_role`: in solo the `Session.principal_role` override, else the workspace settings read fresh; in team an empty role). The org block renders it, each specialist batch gets it as a `<principal_role>` user-turn tag, and a workflow the turn starts reads the same pin through `effective_principal_role` (override, then the pin, then the setting), so a role edited mid-turn applies from the next turn; a team turn sends none.\n\nAct as me is pinned beside them: `delegation.settings.pin_turn_delegation(session, speaker_text)` records on `Session.turn_delegation` whether the speaker has it on, whether `ghostwrite_email` is offered this turn (the principal, or a team member once the owner lets them, on a verified surface, in a conversation private to them, attended), and the speaker's own words. The pin is also held in a context variable for the turn's task, so two turns running at once on one session each read their own. The tool list, the tool handler and the turn's audit privacy all read that one pin, so a switch flipped mid-turn applies from the next turn. Once the tool touches the speaker's mailbox, the conversation is the speaker's alone (`session_store.mark_mail_private`, the principal included when it isn't theirs), the rest of the turn's audit rows are private (a team member's theirs alone) and the turn teaches no memory: no extraction, open-loop, working-style or Honcho pass runs on it. Later turns of that conversation stay private the same way; the pin also records whether the reading turn is still in the history the model is shown (`mail_in_view`, from `sessions.mail_read_at` against `session.history_window_start`), and links, scripts, workflows and posts to everyone stay withheld only while it is.",
+ "markdown": "A single chat message makes a full round-trip through the API, the orchestrator's tool-use loop, a parallel specialist fan-out, and synthesis — all streamed back as server-sent events.\n\n### Steps\n\n1. **Arrival** — the client mints a `client_turn_id` and posts to `POST /chat` (`openexecutive.api.routes.chat`). The turn carries a `<current_speaker>` hint resolved from the caller's `person_id` (followed by that person's `<working_style>` rules when they have any — see the attunement section — and a `<lessons>` block when a lesson the conversation review learned from a miss matches the message, `memory/lessons.py`; see the memory section), plus a `<briefing>` digest of current open alerts (built in parallel with RAG/episodic/peer-memory fetches) so the Executive can discuss any item shown on the `/today` briefing page. A turn arriving from a chat adapter instead of the web app also carries a `<channel>` block naming the surface and stating which approvals can be completed there; on Slack the `<briefing>` digest is gated to the principal's DMs. All three ride in the **user turn**, never a cached system block, as does a `<drive_memory>` block naming the Drive files this conversation already found or opened and the Drive searches that matched nothing (see the memory section). A `<pending_followups>` block lists, for a verified speaker, the follow-ups they scheduled that haven't gone out (up to 10, from `correction_tools.pending_followups_block`, the same ownership rule as `list_followups`), and asks the Executive to cancel one with `cancel_followup` when the message shows it is already done or no longer needed, and say so in a line. The server registers a stop switch under that id *before* the context fetch, so a Stop pressed during those first seconds halts the turn before any model call is made.\n2. **Tool-use loop** — the `Executive` calls Claude. For a cross-domain question the assistant turn emits multiple `consult_specialist` tool-use blocks at once. The call carries the conversation so far (`Session.get_recent_history`: 20 to 30 turns, its start moving in steps of 10) with a 1h cache marker on the previous reply, so each message reads the earlier conversation from the prompt cache and writes only what is new (see Caching); on the OpenRouter path the translator keeps that marker on the reply's text. The history is re-read from the stored transcript at the start of every web turn, so a chat continued in a chat app and then reopened on the web or phone includes the turns the app added.\n The person can keep typing while it works. A message sent then (`POST /chat/add`) joins the running turn: the loop adds it after the next round's tool results, so the answer follows it, and it is saved as its own message before the reply. One that arrives while the final answer is being written becomes the next turn instead. A conversation runs one turn at a time.\n3. **Parallel fan-out** — `openexecutive.orchestrator.router.route_parallel` dispatches those calls concurrently, bounded by `MAX_PARALLEL_SPECIALISTS`; calls past the cap get a skip tool_result. A specialist that raises (a timeout, an overloaded model) or returns no text no longer fails the batch: its tool_result says it is unavailable and tells the Executive not to invent its view, the others' results stand, and the turn goes on. It does not count as consulted, so it takes no committee seat and no department memory records the turn, and its documents are left out of the answer's sources. On the web chat the reply need not mention the gap, because the app shows it under the answer; on every other channel the tool_result asks the Executive to say in one sentence that part of the analysis is missing. A knowledge retrieval that fails likewise leaves that specialist without context rather than failing the turn.\n4. **Per-specialist RAG** — each specialist runs its own domain-filtered ChromaDB query, then reasons over the retrieved chunks and returns analysis as a tool_result. Its user turn also carries a `<company_stage>` tag from the session's company profile, so stage-sensitive advice (venture benchmarks vs. cash-first for a bootstrapped company) does not depend on the Executive remembering to mention it. Once the batch is done, the documents each answering specialist's retrieval returned are named, in call order, into the turn's `TurnSources` (`orchestrator/answer_sources.py`), which the web chat route owns and which also holds its own search's documents. Synced Google Drive files are recorded as `drive` sources with their Drive link, and the web chat lists them under **Google Drive**.\n5. **Synthesis** — the Executive feeds the tool_results back to Claude and streams one coherent reply. Every tool round — not just a specialist one — emits an `activity` event naming what is running, immediately followed by a `thinking` keepalive. The label names the *activity*, never the internal agent: \"Putting time on the calendar…\", \"Looking up people…\", or, for a connected (MCP) tool, plain words for what it does (\"Searching Drive…\"), from the same table (`orchestrator/tool_labels.py`) that names the finished chip (\"Searched Drive\"). The raw `server__tool` name never reaches the user. Under the reply, repeats of the same action collapse into one chip with a count, and tapping it lists what each run looked at. A round that really does fan out collapses to the generic \"Consulting specialists…\" — the one voice holds even in the progress line. The keepalive carries no tool information of its own; it used to drive a hardcoded \"Consulting specialists…\" string, so an MCP or calendar round misreported itself as a fan-out.\n **Do what it says.** Before the turn ends, its last reply is checked against the tool calls the turn made (`orchestrator/claim_check.py`). A reply with no word that can claim a change (\"done\", \"removed\", \"I'll remind you\"…) ends the turn as before. Otherwise one small forced-tool call on `ROUTING_MODEL` reads the person's message, the reply and each call with the start of its result, and reports a claim of a change no call made (or put up for approval). The claim must appear word for word in the reply, or it is ignored. The loop then gets one more round with a note in the user turn (never a cached block): make the change with the right tool, or say plainly it isn't done. Once a turn; a failed check lets the reply through. On the web chat the extra round streams after the first reply, separated by a blank line; chat apps send the whole reply at once. `CLAIM_CHECK_ENABLED` turns it off.\n **A chat several people are in.** When its owner shared a web chat (`session_shares`), every turn in it is labelled: the history is re-read with each person's message starting `[Name]: `, the current message too, and a note naming everyone in the chat rides in the user turn (`channel_context_block`, never a cached block). The Executive answers whoever wrote the latest message. Such a session is no private conversation (`Session.shared_chat`): Act as me is off there (`delegation.settings.private_conversation`), open loops are not listed as on a private surface, no one's mail is read there, the principal's included (`teammate_mail._reader_id`), what the Executive remembers about the speaker (peer memory) is not fetched, the alert digest leaves out the principal's private cards and roster requests (`briefing.context.render_and_trust`), and the principal-only tools are withheld whoever speaks (`content_trust.principal_only_withheld`), because the others write into what the principal's turn reads. A message that starts like a label (`[Alex]: …`) loses it before its sender's own goes in front. Peer memory still records each person's own words. Turns stay one at a time under the conversation's lock; the route publishes each one to the chat's live stream (`api.chat_live`) as it runs, so everyone else in the chat watches it happen. A chat of one publishes nothing.\n6. **Optional committee review** — when enabled, `Executive.stream_chat_with_committee()` runs a silent draft, parallel reviewer critiques, then a streamed revision pass.\n7. **Side effects** — after the reply, every rostered speaker's turn (not only the principal's) schedules a fire-and-forget **open-loop pass** (Attunement) beside the episodic extraction: a keyword prefilter, then one forced-tool call that may open or close loops, every item quote-gated against the speaker's own words. A verified speaker's turn is also kept for the **conversation review** (`memory.chat_review`, see Memory), which reads it once the chat has been quiet 30 minutes and fixes what the replies left undone, from the speaker's own quoted words. A turn that touched their mailbox, which teaches no other memory, is kept too, for their own review only (`record_turn(mail=...)`: tools by name, no results), with the words they typed rather than the blanked text the other passes get. A replay turn is never kept. The user message is persisted with `sender_person_id` — the resolved speaker, never the principal fallback a Discord / Telegram session uses for ownership — and the session records the speaker for the turn (`Session.caller_person_id`), which `close_open_loop` reads. A DM sent while proactive work is tagged (`attunement.outcomes.tag_proactive` — scheduler dispatch, reflection, research, alert review) also opens an outcome-ledger row at `_record_outbound_context`; a user's own turn is never tagged. A tagged DM is also subject to the recipient's own notification settings: in their quiet hours, or when they chose *In my briefs*, the send handler stores it (`outbound_guard.check_hold`, `people.held_messages`) and returns `{\"status\": \"held\"}` instead of sending (see Org). Any side-effecting tool call surfaces an `action_taken` chip, which unlike the ephemeral `activity` label is persisted with the assistant message; once the reply is over — also when it was stopped or timed out — the web chat route sends one `sources` event: the documents and web pages the turn looked at (its own search, each specialist that answered, web search results, and the pages the reply cites, which are always kept) and the areas (\"finance\", never a specialist) it had to go without. The web chat shows it under the reply, and it is persisted with the assistant message as `chat_messages.sources`; other channels don't collect it. The stream closes with a `done` event — preceded by a `stopped` event when the user halted the turn, in which case the partial reply is still persisted and flagged so it reads as cut short rather than complete, and is mirrored into the live in-memory session so the next turn's prompt matches what was saved. The stream still ends with `done` event. While nothing else is going out — a slow tool call, a long specialist round — the route sends an SSE comment (`: keepalive`) every `CHAT_STREAM_KEEPALIVE_S` (15 s by default, 0 for none) so a browser or proxy does not drop the connection as idle; the step it waits on keeps running across it, and the whole-turn deadline is unchanged. Every call through the MCP gateway (Gmail, Calendar, Drive, Outlook, OneDrive, tool search) has its own ceiling, `MCP_TOOL_TIMEOUT_S` (120 s): past it the model gets an error saying the tool did not answer and may still have run, so it checks before calling again, and no outbound linkage is recorded for a send that timed out. One side-effecting tool is gated server-side rather than by its description: `ack_alert` will only accept an `alert_id` from the live alert board the server itself derived this turn — the whole live set, not only the rows the `<briefing>` digest printed, since `/today` renders more cards than the digest lists and every one of them is Discuss-able — and it fails closed, so an id it cannot even parse is refused rather than waved through to the handler's own parse. That check runs on **every** session. It used to run only on turns that arrived from a chat channel, keyed on `origin_channel`, which the browser never sets — so the web, the surface the principal actually uses, was unchecked and the model could ack any id, including one quoted out of an alert body by the briefing page's Discuss handoff. What that buys is bounded and worth stating plainly: an id that is invented, closed, snoozed or expired is refused, including one quoted out of an attacker-written alert body; the model being argued into acking the wrong *live* card is not prevented. The one way to widen that set is `find_alerts`, for an item the principal names that has left the live board (already opened, snoozed, older than the board): a keyword search over alerts of every status whose own results — never an id the model supplies — join the trusted set. It runs only in a turn where `render_and_trust` showed the principal their own board (`Session.principal_board_shown`: the verified principal, and on a channel only in their DM), never merely because the session has a set — every `Session` starts with an empty one, and that empty set is how a Google Chat turn, someone else's DM or an unattended pass refuses every ack — and not on the principal's turn in a shared Slack or Discord thread either, where others read the reply and write into what the model reads. It trusts only rows still open (`unread`, `read`), never a roster-request card, and at most 25 ids per turn across calls, and refuses a query with no word of three or more letters. It also moves the admitted limit outward: a model argued into the wrong search can now reach up to 25 open alerts that are off the board, not only live ones. The board is recorded on the turn's `Session`, and the route binds that session for the **whole** SSE body (`schedule_tools.set_session`, alongside `set_turn`) rather than letting `stream_chat` bind it from inside its own generator. `_sse_body` drives the executive with `asyncio.wait_for(stream.__anext__())`, which runs each step in a fresh Task holding a *copy* of the context, so a binding made inside the generator is discarded with the step that made it: step one sees the session and every later step sees `None`. The tool-call loop runs on those later steps, so the whole guard read an empty set and refused every ack on the web — on live, open cards — until the binding moved out to the route. Anything reading `current_session` mid-turn has the same requirement, and two of them needed more than the binding to behave. `schedule_followup`'s seen-`channel_ref` anti-spam gate refuses a send to an address the session has not seen; with no session it skipped itself, so a web turn could schedule to **any** address, and with an empty one it refused even the principal's own. The route now seeds the caller's own addresses onto the session, so on web the gate means what it means on every other surface. Reply linkage (`_record_outbound_context`, read back by `inbound_hydration` to quote the originating conversation into the turn handling a recipient's reply) is the other: it was never reachable on web, and rather than switch that on for the principal's broadest surface as a side effect it is held back, keyed on an explicit `Session.from_web_chat` flag. Not on an empty `origin_channel` — alert review, the CLI and the unattended workflows all leave it empty while legitimately recording linkage, as does the email poller under its own `email` tag. `scheduled_actions` rows also take their `session_id` from the session. A session that was shown no board has an empty trusted set and can ack nothing, so the unattended passes (the nightly reflection, the research synthesis) are refused by default — they also still withhold the tool outright, which is belt-and-braces rather than the only thing stopping them. After the stream closes, the turn is also handed to the episodic memory extractor (`memory.episodic.schedule_extraction`, fire-and-forget) — on every turn where the principal said anything at all, and only the principal: a turn naming an `origin_channel` must resolve to a person marked `is_principal`, because the quote validator downstream cannot tell whose words it is checking. Both this path and the committee path call the same `should_extract` predicate, and it applies no length floor: the gate used to sum in the assistant's reply, which let a verbose answer drag a trivial turn in and discarded the short, decisive instructions that are the whole point of extracting. A user-side floor would fare no better — \"Do B.\" and \"Done\" are one character apart. See **Memory** for what that cost on a live tenant. None of this runs for a **replay** of a graded turn (`Session.replay`, `memory/replay.py`): the loop answers its acting tools with \"done\" and records them on the session, offers no script, job or server load, and skips every post-turn pass, so the nightly replay of the misses changes nothing and reaches nobody. On a team member's turn (`department_gate.speaker`) it also refuses an alert that is not routed to them (`routed_to_person_id`), so they clear only their own items; the principal clears anything on the board. `create_alert` on such a turn ignores the `source`, `external_id` and `from_address` it was given: the alert gets the source `team_member`, a fresh id and `raised_by` (their name), so it can't pose as mail or a watch, coalesce into one, or pre-claim the id a real alert will arrive with.\n8. **Tool failures** — a handler that raises instead of returning its JSON error is isolated: both tool gathers run with `return_exceptions=True`, the model gets an error `tool_result` naming only the exception's TYPE — a message can carry a filesystem path, a validation error echoing the input, or a third-party HTTP body, and anything in model context can be quoted back to the user, so the full repr stays in the log and the audit row — and the failure is audited with `ok=false`. Only `CancelledError` is re-raised, so turn-timeout and client-disconnect handling still work. Before this one crashing tool aborted the whole turn, which reached the user as an unexplained apology with no audit row (#136).\n\nWeb search, when invoked on the Anthropic path, executes inside the Anthropic API itself (`web_search_20250305`) and returns within the same generation; for any model routed via OpenRouter the same tool becomes OpenRouter's `openrouter:web_search` server tool, which also runs inside the generation with the same search cap and domain lists.\n\nThe install's workspace mode (solo or team, see Org) is read fresh at the start of each turn by `memory.workspace_settings.pin_turn_workspace_mode(session)` and pinned on the session for that turn only (`Session.turn_workspace_mode`): the persona, the org block, the tool list and every tool handler in the turn then agree, and a switch made mid-turn applies from the next turn. A session can instead carry an explicit override, `Session.workspace_mode` (`None` by default), which wins over both — so a caller that runs many conversations concurrently on one Executive, such as evals, can pick the mode per session rather than flipping the install-wide setting. Everything reads it through `effective_workspace_mode(session)` (override, then the turn's pin, then the setting). The principal's role is pinned the same way (`pin_turn_principal_role(session, mode)` → `Session.turn_principal_role`: in solo the `Session.principal_role` override, else the workspace settings read fresh; in team an empty role). The org block renders it, each specialist batch gets it as a `<principal_role>` user-turn tag, and a workflow the turn starts reads the same pin through `effective_principal_role` (override, then the pin, then the setting), so a role edited mid-turn applies from the next turn; a team turn sends none.\n\nAct as me is pinned beside them: `delegation.settings.pin_turn_delegation(session, speaker_text)` records on `Session.turn_delegation` whether the speaker has it on, whether `ghostwrite_email` is offered this turn (the principal, or a team member once the owner lets them, on a verified surface, in a conversation private to them, attended), and the speaker's own words. The pin is also held in a context variable for the turn's task, so two turns running at once on one session each read their own. The tool list, the tool handler and the turn's audit privacy all read that one pin, so a switch flipped mid-turn applies from the next turn. Once the tool touches the speaker's mailbox, the conversation is the speaker's alone (`session_store.mark_mail_private`, the principal included when it isn't theirs), the rest of the turn's audit rows are private (a team member's theirs alone) and the turn teaches no memory: no extraction, open-loop, working-style or Honcho pass runs on it. Later turns of that conversation stay private the same way; the pin also records whether the reading turn is still in the history the model is shown (`mail_in_view`, from `sessions.mail_read_at` against `session.history_window_start`), and links, scripts, workflows and posts to everyone stay withheld only while it is.",
"mermaid": "sequenceDiagram\n participant C as Client\n participant API as FastAPI /chat\n participant E as Executive\n participant CL as Claude\n participant S as Specialists\n participant KB as ChromaDB\n C->>API: POST /chat message\n API->>E: start turn\n E->>CL: messages (tool-use loop)\n CL-->>E: consult_specialist calls\n E->>S: route_parallel fan-out\n S->>KB: domain-filtered RAG\n KB-->>S: chunks\n S-->>E: analysis tool_results\n E->>CL: synthesize\n CL-->>E: streamed reply\n E-->>API: SSE chunks then done\n API-->>C: streamed response",
- "generated_at": "2026-10-18T19:51:21Z"
+ "generated_at": "2026-10-19T09:30:00Z"
}
diff --git a/packages/core/openexecutive/architecture/prebuilt/memory.json b/packages/core/openexecutive/architecture/prebuilt/memory.json
index 1798d51c..76dd5bf6 100644
--- a/packages/core/openexecutive/architecture/prebuilt/memory.json
+++ b/packages/core/openexecutive/architecture/prebuilt/memory.json
@@ -1,7 +1,7 @@
{
"section_id": "memory",
"title": "Memory System",
- "markdown": "The Executive's durable memory is an episodic SQLite store at `./episodic_memory.db`, managed by `openexecutive.memory.episodic`. It holds four tables:\n\n- `decisions` — choices made, with `domain`, `summary`, `rationale`, `outcome`, and `tags`. `outcome` is filled in when the principal says how a decision turned out — the `record_decision_outcome` chat tool (principal on a verified surface only) or the Memories page. The weekly review reads this table twice: the week's decisions (`decisions_since`) and up to three older than 30 days with no outcome yet (`decisions_awaiting_outcome`), which it asks about.\n- `initiatives` — tracked efforts with a `status` and `summary` (idempotent upserts).\n- `advice_given` — query/advice pairs per domain.\n- `scheduled_actions` — a dispatch queue, treated separately from recall memory. `cancel_scheduled_action` guards its UPDATE on `status = 'pending'`, so a cancel never overwrites a row the scheduler claimed a moment earlier.\n\n### What gets extracted, and when\n\n`episodic.extract_and_store` runs after a turn and asks a utility-fast model for decisions, initiatives and advice. Every candidate must carry a `user_commitment_quote` that appears verbatim in the principal's own message (`_is_valid_user_commitment`) — the turn's speaker text (`memory_text` when the entry point supplies one, else the prompt), so a quoted Executive email or a briefing card's body inside the prompt cannot satisfy it — the model has repeatedly tried to log the Executive's *recommendations* as the user's commitments, and that quote is the hard gate against it.\n\nA turn reaches the extractor if `should_extract(speaker_text, session=...)` is true, which means only that the principal said something on a surface that proved it was them — there is deliberately **no length floor**. There used to be one, on the combined user+assistant length, and on a live tenant it selected almost exactly the wrong turns: 9 of 16 exchanges were blocked, and the 9 held every instruction the principal gave, while the 7 admitted were long analytical exchanges with no commitment in them. The extractor ran 13 times and stored nothing.\n\nMoving that floor to the user's side would relocate the bug, not fix it. The canonical executive decision is a long analysis answered with \"Approve option B.\" (17 chars) or \"Do B.\" (5), and any floor high enough to skip \"Done\" (4) also skips those — \"Do B.\" and \"Done\" differ by one character and mean opposite things. Length cannot separate a decision from an acknowledgement; the verbatim-quote check can, so `_is_valid_user_commitment` is the gate that decides. The price is one utility-fast call on turns that propose nothing.\n\nThat quote check is only meaningful when `user_message` holds the **principal's** words, and on a chat channel it does not — `Executive.chat()` is reached from Slack, Discord, Telegram, Google Chat and the email poller. A teammate's line would be written to `decisions` with no speaker attached, indistinguishable from the principal's own; an inbound email body is text the sender chose, so a self-quote is free. Removing the length floor is what makes this bite — short channel traffic used to fall under it incidentally — so `should_extract` asks the untrusted-content policy (`orchestrator.content_trust.principal_speaking`) whether the principal is speaking. It names the principal's surfaces rather than inferring them: the web chat (signed in as the principal — or, on an install with no principal on the People page yet, a request that carried no sign-in; a signed-in email on nobody's entry, such as an archived teammate still allowed to sign in, is not the principal), the CLI (`Session.from_cli`), the principal's own Slack or Discord or a private Telegram chat with a valid webhook secret (`people_tools.is_principal_on_verified_surface`), and email from the principal's primary address that Gmail's own `Authentication-Results` marks `dmarc=pass` (`Session.email_authenticated`). Everything else fails closed: a teammate (on the web too), an unrostered sender, the principal's address on mail Gmail did not authenticate, Google Chat, the MCP server (its caller names themselves), unattended runs, and an unreadable roster. The rule used to be \"no `origin_channel` means the principal's own surface\", and the email poller left `origin_channel` empty, so every stranger's email ran through the extractor with its body — headers, quoted chain and all — as the principal's words, and whatever it stored rendered on every later turn. The poller now tags its sessions `origin_channel=\"email\"`, and the gate no longer reads an empty channel as trust.\n\nThe extractor also reads only the words **outside** every `<untrusted_content>` block (`schedule_extraction` runs `content_trust.strip_untrusted` first): an attached document's text is inlined in that block, so a sentence the principal did not type can never be quoted back as their commitment, and a turn that is nothing but an attachment is not extracted at all.\n\nEach pass writes a `memory_extraction` audit row — in a `finally`, so a pass that crashed is recorded too, with the exception type as its `failure` reason: how many items the model proposed, how many were stored, a `malformed` count so a pass where the model returned only garbage does not read as one that found nothing, and a `{kind, reason}` record per drop — `bad_quote` and `missing_field` for an item the model proposed, `not_a_list`, `item_not_a_dict` and `payload_not_a_dict` for a shape that was never a usable item. Every proposed item is either stored or dropped, so `proposed == stored + item drops` is the arithmetic that says whether anything was lost silently. The tool payload is not schema-checked anywhere, so a malformed shape is counted as a drop rather than raised — it used to abort the whole pass, discarding the other two kinds with it and suppressing the row, which read exactly like \"extraction never ran\". Without it, \"the model found nothing\" and \"the model found things and every one was rejected\" are indistinguishable from outside the database — which is why the failure above survived undetected and took a SQLite session on the tenant to find. A `proposed>0, stored=0` streak is the signal to watch.\n\nThe validator rejects a paraphrase, and the model paraphrases: on one install two of three real commitments were lost that way, the quote beginning \"SVN's engagement covers only …\" where the person had typed something else. So a `bad_quote` drop earns exactly one corrective call. The model is shown the rejected items and the quotes it gave, told to copy the span character-for-character (typos and casing included) or return empty arrays, and the tool is forced where the provider supports tool choice. Every retry item is validated first; a still-invalid one adds no second drop and is counted `still_invalid`. A valid item is then classified in order: its label matches a pending drop record → a recovery, stored and the record released; else its quote (terminal punctuation ignored) already supports a stored item of that kind → a re-send, ignored and counted `repeated`, so a model that re-sends everything cannot double-count `stored`; else a new proposal, stored and counted — a reworded label cannot be told from a different item, and crediting it would erase the very `bad_quote` census the row exists to show, so its original drop stands. Recovery is checked before re-send because two commitments can rest on one sentence. Malformed shapes at any level — a kind that is not a list, an item or payload that is not a dict, a response with no tool call — are counted `malformed`, so a retry that returned garbage does not read like one that obediently returned nothing. The row's `retry` block (`rejected`, `recovered`, `repeated`, `still_invalid`, `malformed`, `failure`) is always present, zeros when nothing was rejected; `rejected` is set from the complete drop list when the row is written, so neither a store failure before the retry nor a cancellation during it can zero it. The arithmetic above still holds after the retry. An exception on the retry is recorded as the retry's own `failure` and leaves the first pass's results untouched; the cost is one utility-model call, only on turns that dropped something. `memory_extraction` is a declared event type, so the audit page's filter can select it.\n\n### Standing facts (corrections that persist everywhere)\n\nA fifth table, `facts` (`openexecutive.memory.facts`, created on first write), holds facts and corrections the principal stated and asked to keep — \"Maple House is 48 units, not 52\". Before it, a chat correction's only durable home was Honcho peer memory: optional, best-effort (its prefetch times out or errors under load), re-injected only into that person's later chat turns, and never read by the briefs, the scheduled runs or the alert review. The episodic extractor cannot hold one either: it stores only decisions backed by a commitment quote, and a fact is not a commitment.\n\n- **Written from chat, by the principal or an attributed teammate.** `remember_fact` stores one (subject, statement, optional wrong value) and `forget_fact` retires one. The principal on a verified surface may do both. A teammate on the People list (a `team` row, not archived, not a contact) on a verified surface (the web app signed in, their own Slack or Discord; `fact_tools._teammate_speaker`) may call `remember_fact` only; email, Google Chat and unrostered senders are refused. Both tools are withheld from every unattended run and every turn private to the principal. Every call, `forget_fact` included (retiring a fact changes what later prompts treat as true just as writing one does), also needs `source_quote`: at least two words and eight characters, found in what the speaker typed this turn (`delegation.settings.own_words` over the pinned `TurnDelegation.speaker_text`). The `<outbound_reply_context>` backstory a Slack or Discord reply is hydrated with is stripped first, and a message with an attachment is refused outright. The quote alone only proves the principal asked, so everything `remember_fact` stores and renders (the statement, the subject shown as `[fact N] subject:`, and a previous value shown as `(corrects: …)`) is tied to their words too. An omitted previous value falls back to the replaced fact's own statement. Every figure must be a number they wrote, compared at its magnitude: `$180k` matches `180,000`, but `180m` never lets `$180k` through. Every name must also appear in what they typed: a capitalised word, or any word holding a non-ASCII letter, other than the statement's very first word (a statement is one fact, so splitting a document's names into one-word sentences exempts nothing). So must every month, weekday or quarter. A name the model writes in lower case is not caught: the gate narrows what a real quote can carry in; it does not prove a paraphrase. A real quote therefore cannot carry a document's figure, name or date in with it (\"Cedar Court's lease expires in March\" after \"remember what the lease doc says\"), while a paraphrase of what they said still passes. So the model cannot store its own inference, a document's figure or text quoted back at the principal as something they said. Every audit row the tools write, and the chat loop's `skill:` dispatch row for them (whose input quotes the principal verbatim), is private to the principal (`executive._private_tool_row`). Those rows tie a fact to the principal's session and turn, which `GET /memories/facts` hides from teammates, and a teammate can read any non-private audit row. The handlers run in a worker thread (`asyncio.to_thread`, which carries the turn's context), and the chat and committee paths, the alert review, the morning brief's synthesis and the end-of-day, weekly-review and reflection workflows read the block the same way, so SQLite, the profile file and its lock never block the event loop the SSE streams share. The principal's own email may ask too: the change is checked the same way, then held until they confirm it by replying to a one-time token sent to their own address (see Integrations → Standing facts by email).\n- **Provenance and attribution.** Each row keeps the quote, the channel (`web` or the adapter), `session_id`, `turn_id`, the recording person and the time, plus `recorded_by_role` (`principal` or `teammate`) and, for a teammate, `recorded_by_name` as the People list had it. Rows written before these columns existed read as the principal's (`_migrate` adds the columns on the first write; the read-only render tolerates a DB that has none).\n- **One active fact per subject.** A new row supersedes any active row with the same folded subject key, or the id named in `replaces_fact_id`, in one transaction. The old row stays as `superseded` (with `superseded_by`), and the new one is stored as a `correction` carrying what it replaced. Retiring sets `retired` with a reason. **The principal outranks a teammate:** a teammate's write that would replace an active fact the principal set (by subject or `replaces_fact_id`) raises `PrincipalFactConflict`, and the tool stores it as `proposed` instead, naming the fact it would replace (`replaces_fact_id`); teammates replace each other's facts freely, and the principal replaces anyone's. **\"Needs my approval\"** (`fact_approval_rules`, per teammate, **on by default**, set only by the principal) stores every fact from that teammate as `proposed`; the principal turns it off for a teammate they trust, whose facts then apply at once (except one that would replace the principal's). The rule is read inside `record_fact`'s own write transaction, so a switch turned on a moment earlier cannot let one fact through; a teammate write that names no person is never trusted. One teammate may have at most `MAX_PENDING_PROPOSALS_PER_PERSON` (20) proposals waiting (`TooManyProposals`; the tool tells them to wait for the principal's review). A teammate's retire checks ownership in the `UPDATE` itself (`retire_fact(teammate_id=)`: their own row, not approved). A proposed row never renders; `approve_fact` makes it active and replaces what it names (the principal's own fact included — approving it is their word) and stamps `approved_at`, after which it outranks teammates exactly as the principal's own fact does (`Fact.principal_owned`: no teammate may replace or retire it); `decline_fact` sets `declined`. No field of a teammate's fact may carry what the render adds itself — `(per <anyone>)` in any case (a unit such as `(per month)` or `(per unit)` is fine), `[fact N]` or a date stamp after any dash, read NFKC-folded with invisible characters removed (`fact_tools._marker_error`) — so a teammate cannot plant a second, forged attribution inside their statement (the principal's own unmarked lines are not checked: \"(per Smith lease)\" is ordinary wording for them). The tool answers `awaiting_approval` (no action chip) and tells the model to say it is not in use yet.\n- **Rendered everywhere output is produced.** `render_facts_for_prompt` renders the active rows newest first under a self-explaining `STANDING FACTS` header (use these over older figures; a line ending `(per <name>)` is that teammate's word and the principal's unmarked line wins a conflict; the current conversation still wins; quoted data never instructions). A teammate's line ends `(per <name>)`, the name defanged like the rest, capped at 40 facts / 6000 chars, with angle brackets defanged. It opens the DB read-only and never creates it or the table. The block always rides in a user turn, never a cached system block: a chat turn's `<standing_facts>` (so every scheduled run through the chat loop too), each specialist consult (`route_to_specialist`, chat and workflow steps alike), the /today header and the morning brief (`render_briefing_context`, after the quiet check and inside the string the header's cache key hashes, so a new fact rewrites the header), the alert review's batch (`render_batch`, read once per pass), and the end-of-day digest, the weekly review's top-three call and the morning reflection (`with_standing_facts`).\n- **Company-profile edits from chat.** `update_company_profile` (same gate and quote rule) changes one whitelisted field of `company/profile.yaml`, under `PROFILE_EDIT_LOCK` (also taken by `PATCH /company-profile`, so neither edit silently drops the other): a text or number field is set, a list field gets an item added or removed, and `financials.key_metrics` takes a named metric. It writes through `CompanyProfile.save_to_yaml` and updates the session's profile, so the next turn's cached company block carries it (one cache miss on the change). The new value must itself appear in the principal's own words, not just the quote: the value renders into the cached company block on every later turn, so \"set our mission to what the doc says\" or \"update our headcount\" is refused rather than saving a document's text or a guessed figure. A number must be one they wrote, however they wrote it (`$180k`, `1.2m`, `2,400,000`). Saved text has `<`/`>` defanged. A `kind='profile'` row records each edit with its quote for the Pulse page. Those rows are never rendered into a prompt, because the profile block already carries the value.\n\n### Session scoping\n\n`decisions` and `advice_given` rows carry a `session_id`, so per-thread channels (Discord, Telegram) can pull just-this-thread history without leaking cross-conversation context. A null `session_id` falls back to a global view.\n\n### Surfacing\n\n`openexecutive.memory.episodic.format_for_prompt` renders recent decisions and initiatives into a compact `<past_decisions>` block injected into the user turn — alongside `<retrieved_context>` and peer memory — never into a cached system block. Each decision names where it was recorded when that was a channel — `- 2026-09-01 [finance] (via email): …`, from the prefix of its `session_id` (`email:`, `slack:`, `discord:`, `telegram:`, `google_chat:`); a web or CLI decision has no tag. Rows extracted from mail before the untrusted-content policy, when any sender's body could be stored, therefore read as mail rather than as the principal's own word.\n\nScoped to a session, decisions and advice cover every conversation of a chat app's stream (`memory.conversation_ids.family_clause`): a Telegram chat or a DM is cut into conversations after two quiet hours or a /new (`memory.conversations`), and what an earlier conversation decided still renders in the next.\n\nThe chat route also injects a `<briefing>` block into the same user turn: a compact digest of the current open (unread) alerts, built by `openexecutive.briefing.context.format_open_alerts_for_prompt` (company-wide, `status=\"unread\"`, mirroring `/today`). This is what lets the Executive discuss a briefing item the principal clicked or named on `/today` (e.g. \"Gulf Coast Port Cyberattack\"). It is resolved in parallel with the other context fetches, omitted when there are no open alerts, and never placed in a cached system block.\n\nOn the Pulse page the Memory section shows the three lists as Decisions, Initiatives and Advice tabs, then a **Corrections** tab (`GET /memories/facts`: active standing facts and profile edits with their quote, channel and — for a teammate's — their name; proposals first under \"Waiting for your approval\" with **Approve** / **Decline** for the principal; the replaced, retired and declined history folded away; **Retire** on any fact for the principal and on their own not-yet-approved one for a teammate; and, for the principal, a per-teammate \"needs my approval\" switch), and a **History** tab for the person's own Always in the loop notes (see below). The header's Memories tile counts the three lists. What peer memory has learned about the signed-in person is theirs alone, so it is not on Pulse: it is on **Settings → About you** (see the peer memory section).\n\nThe same user turn carries a `<drive_memory>` block when the conversation has touched Google Drive (`openexecutive.memory.drive_reads`). Drive is reached only as live Google Workspace calls inside a turn and history keeps only prose, so without it a file found one turn was gone the next. `MCPGateway.call_tool` hands each `search_drive_files` and `get_drive_file_content` result to `record_drive_result`, which keeps, per session, every file found or opened (file id, name, type, link, and for an opened file its first 600 characters) and every search that matched nothing, with its query. `format_drive_memory` lists the 20 most recent files, so \"the file you found earlier\" resolves to a file id the Executive reopens rather than searching again, and the queries that found nothing (dropped once the same query later finds something). Rows are keyed on the session *and* the speaker, and shown only to that speaker in that session, because one session can span several people (an email thread, a Slack or Discord thread). Nothing is recorded or shown without a bound `current_session` and a rostered speaker, on a turn private to the principal, or on one that touched the speaker's own mailbox (Act as me). workspace-mcp writes file names into its output unescaped, so a name containing a newline can forge a result line. Only a Drive-shaped file id, type and `docs`/`drive.google.com` link are therefore kept; any other line is dropped, and the name is always quoted as the file's own content, not instructions. Each speaker keeps at most 100 files and 100 searches per session, older rows are pruned on write, and `session_store.delete_session` drops them all.\n\nThe scheduler reads one more thing from the transcript: when a follow-up back to the person who set it fires, `session_store.own_messages_since` gives it that person's own messages since it was set (their words only, across their conversations, capped), so a follow-up whose reason was already settled in chat stands down instead of sending (see the scheduler section).\n\nA conversation can also become its owner's alone. When Act as me first reads the speaker's own mailbox in it, `session_store.mark_mail_private` sets `sessions.mail_private` (creating the row with its owner when a channel adapter hasn't written it yet), and from then on only the session's owner may open, continue or delete it — the principal included, when it is a team member's (`chat._session_access`). It is never cleared. Beside it `sessions.mail_read_at` keeps how many history messages the conversation held before the last turn that read the mail (`session_store.mail_read_at`; NULL on rows marked before the column): Act as me's hold on links and scripts in later turns lasts only while that turn is still in the history window (see Act as me). \n\nThe chat list has owner controls on the same row: `sessions.pinned_at` (pinned chats list first) and `sessions.title_locked` (set by `rename_session`, after which `update_session_title`, the automatic title, leaves the name alone). Chats are also grouped by topic for their owner (`memory/chat_topics.py`): a `chat_topics(id, owner_person_id, name, kept, pinned_at, created_at)` row per topic, unique per owner and name (any case), and `sessions.topic_id` with `sessions.topic_source` (NULL = not looked at, `auto` = chosen by the model, `owner` = filed by the owner and never refiled). The one utility-fast call that titles a new chat (`utils/chat_topics.name_chat`, from the web chat and the chat-app conversations) also picks its topic, reusing one of the owner's 60 most recent topic names or making a new one. Only when the owner alone has written in the chat: a channel or group conversation, a shared chat, or one where someone else wrote first is titled without the owner's topic names in the prompt (another writer could steer the title into repeating them) and is filed later by the backfill, whose answer only the owner sees. Each call is bounded by the utility-fast timeout (60 s for a backfill batch). Only a turn that makes a new topic costs a second short call, over the topic names alone, which merges it into an existing topic that means the same unless the owner has `kept` it (renamed, pinned, merged into or filed a chat under it). Chats from before, or whose naming failed, are filed from their titles in batches of 80 the first time the owner opens the Topic view (`backfill`; a failure waits 10 minutes). Topics left with no chat are dropped when listed. Related topics share an `area` (`chat_topics.area`, `area_kept`): one property, deal or client, shown as one heading over them. The same second call that checks a new topic also names the area it shares with related ones, and after the backfill one call over the names gives areas to topics not yet looked at (once the owner has three); an area counts only when two topics share it. An area the owner renamed or ungrouped is left as they made it. A `session_shares(session_id, person_id, shared_by_person_id, created_at)` row adds one team member to someone's chat (`list_shared_with_person`, `set_shares`, `leave_share`): they read and write in it with its owner, each of their messages saved with their own `sender_person_id`; a `mail_private` chat is never shared or opened that way, and deleting the chat drops its shares. `last_turn_sender` says who wrote the last turn, which is how redo stays with the person who asked. The chat list's preview puts `You:` only before the caller's own words. `rewind_last_turn` deletes a web chat's last turn (the last reply and the user messages after the reply before it) so it can be asked again; the next turn's history is re-read from these rows, so nothing else needs clearing. A search that matched nothing also gains a note in its tool result: say the exact query and that it found nothing, never that the file does not exist. This is a first step: Drive is still not indexed into the company collection.\n\n### System of record\n\nSQL is the system of record; the peer-memory service is a recall layer mirrored from it, not a replacement. When `store_decision` / `store_initiative` / `store_advice` insert a row whose `department` is non-empty and not `\"general\"`, the row is mirrored as a kind-tagged note into that department's peer via `append_department_note`. The mirror fires only after a successful INSERT, is fire-and-forget, and never rolls back the SQL row on peer-memory failure. `scheduled_actions` is never mirrored — it is a queue, not memory.\n\nThe episodic extractor still learns only from the principal's own words. Commitments and asks from everyone else on the roster are tracked as **open loops** (see Attunement) — `scheduled_actions` rows with `kind='open_loop'`, opened and closed by a separate quote-gated pass after each attributed turn. That pass depends on `chat_messages.sender_person_id`, which records who actually wrote each persisted user message. An open loop counts toward `list_awaiting_replies_by_person` only once it is due, and `list_scheduled_actions(exclude_internal=True)` filters `__internal__` rows in SQL so readers that want real sends are not starved by them. `mark_outbound_context_consumed` also resolves the Attunement outcome row for that DM as `replied` — a matched reply is the clearest sign proactive outreach landed — and a real change to an existing initiative (`store_initiative` / `update_initiative`, new status or summary) marks the updater's own check-in nudges `acted` — an update with no known updater, such as `PATCH /memories/initiatives/{id}`, credits nobody.\n\n### Workspace settings\n\nThe same database holds one row of settings that are not memory: `workspace_settings` (`openexecutive.memory.workspace_settings`) — the install's mode (`team` by default, or `solo` for one person using Open Executive just for themselves), the user's IANA time zone, the principal's role (`PrincipalRole`: `role_kind`, `role_title`, `reports_to`, `remit`, `measured_on`, all nullable; only solo mode reads it), and the company's own email domains (`company_domains`, a JSON list, or NULL to derive them from the principal's primary address — `people.identity` matches a teammate by local part on them; `validate_company_domains` lowercases, dedupes and sorts, allows at most 10 plain DNS names and refuses a free-mail provider's, and a stored value that no longer validates reads as NULL). It is a table of its own rather than a company-profile field because onboarding rebuilds the profile from scratch. Every read is fresh and read-only (a missing file or table reads as the defaults; a table from before the role or `company_domains` columns reads them as unset and is migrated additively by the next init or write). A read error (a locked database, say) also reads as the defaults, so `get_workspace` then says team; `read_stored_mode` is the strict read of the mode alone — None when the row cannot be read or holds no valid mode — for the scheduler's weekly-review check, which must not take a failed read for team. A session may carry an explicit `workspace_mode` override; otherwise the mode is read fresh at the start of each turn and pinned on the session for that turn only (`Session.turn_workspace_mode`, via `pin_turn_workspace_mode`), so every tool handler in the turn sees the mode its persona and tools were built in. `effective_workspace_mode` reads override, then the pin, then the setting; `effective_principal_role` reads a session's `principal_role` override, then the role pinned for the turn (`Session.turn_principal_role`, via `pin_turn_principal_role`), then the stored role. See Org for what solo changes and Scheduler for the time zone.\n\n### Act as me\n\n`initialize_db` also creates Act as me's per-person tables (`delegation.schema.ensure_schema`): `delegation_settings`, `delegation_voice` and `delegation_voice_history`. They hold a setting and a writing profile rather than memory, and nothing in them is mirrored to peer memory. A turn that touched the speaker's own mailbox teaches no memory: the episodic, open-loop and working-style passes are skipped along with the Honcho peer and department syncs, since its reply quotes a draft built from other people's mail. See **Act as Me (Delegation)**.\n\n### Always in the loop (notes of what you said)\n\nA person can keep private, dated notes of what they said, in chat with the Executive and in email replies it drafted for them: what they promised, agreed, declined, answered, asked for or shared. The switch is per person (\"Keep track of what happens\", `history_person_settings.reply_notes`, off by default, one switch for every channel). Any team member on the People list may turn it on (`history.can_keep_notes`: kind `team`, not archived, the principal included); Act as me isn't needed, though notes from email replies only come through it.\n\n- **Where notes come from: chat.** After each chat turn, on both the single-voice and the committee path, the Executive's post-turn block calls `memory.history_chat.schedule_chat_notes` next to the open-loop and style passes, except on a turn that touched the speaker's mailbox. It reads only what the speaker typed this turn (`delegation.settings.own_words`: no backstory an adapter added, nothing when a file came with it), never the reply and never anyone else's message: every channel calls the Executive with the one speaker's message, and what other people say to each other is never read. It runs only for a speaker the turn verified (`history_chat.verified_speaker`): the turn's `caller_person_id` is them, nobody started it by email or runs it unattended or for them, and the surface proved who they are (the web chat signed in or a local install, the principal or a team member on their own Slack or Discord, a private Telegram chat behind a valid webhook secret, or a channel whose adapter verified the sender itself and set `Session.speaker_verified`). A shared Slack or Discord thread counts: the notes stay private and are read back only where nobody else can see them. A message under 40 characters is skipped, and each person gets at most 40 passes a day, counted in `history_chat_passes` so the cap holds across workers and restarts. The pass uses a constant `CHAT_PROMPT` (requests to the assistant, questions and small talk are not notes), the same `record_notes` tool and the same `check_note` gate with the message as both body and allowed words; the note's channel is the inbound channel or `web`, its conversation the session id, and it names no counterpart.\n- **Where notes come from: email.** After `delegation.reply_send` sends a reply, it starts `memory.history_notes.note_sent_reply` in the background. The note-taker reads only the words the person sent (`email_poller.sender_new_text` strips quoted mail) and the recipients' names, cut to four words of name characters (`history_notes.short_name`): never the mail being answered, nor the subject, which others in the thread write too, so nothing another person wrote can become a note. One forced `record_notes` call with a constant prompt and no other tools returns at most three notes. Code then drops any note that says more than they did: the `quote` must appear word for word in what they sent, every figure in the summary must be in the quote, every name or date word must be in what they sent or the recipients' names, at least half its other content words must be theirs, the summary carries no link or address, and a `due_date` is kept only for something promised or agreed. Notes record events, never instructions, and carry `trust = high` because they rest on the person's own words.\n- **Whose they are.** Every note is private to its person (`visibility = private`). Nobody else reads it, the principal included; there is no shared note.\n- **How long they last.** The company default is 90 days (`history_settings.retention_days`, the principal's choice of 30, 90, 365 or until forgotten). A person may only choose a shorter time; shortening the company time clamps everyone's choice and re-dates live notes. A pinned note never expires; unpinning restarts its clock, and a later retention change counts from there. Reads skip expired notes and the scheduler's alert sweep deletes them (`history.sweep_expired`).\n- **What a person controls.** Through `/memories/history` they read, search, pin, correct and forget their own notes. On the Pulse page this is the **History** tab, last in the Memory section and shown only to someone with notes to see (signed in and on the People list): each note shows its kind, who it was with, the date, the person's own words, any due date and when it will be forgotten, and its menu holds **Correct** (a side panel; \"Use the original\" clears a correction), **Pin**, **Don't remember this** and **Forget**. \"Don't remember this\" forgets every note from that conversation and adds it to `history_excluded`, so it is never noted again. Settings → **Memory** holds the switch (\"Keep track of what happens\") and a shorter time for their own notes, and the company time, which the principal changes and everyone else reads. A chat note shows the channel alone (\"Slack\", \"Web chat\").\n- **Recall.** `recall_history` (`orchestrator.history_tools`) is offered only on a turn where the speaker may read their notes: verified as above, a team member who may keep notes, in a conversation private to them (`history_chat.private_chat`: the web chat, a Slack or Discord DM, a Telegram chat, or one its adapter marked `Session.private_chat`), with their switch on. Before any note is read the turn is set `touched_mail`, for the principal too, so its rows are private to the speaker, it teaches no memory and the mail lockdown holds from that round on. The conversation is also marked theirs alone (`session_store.mark_mail_private`), so every later turn in it is private the same way (the lockdown is that turn's alone) and, for a team member, the principal can't open it; recall refuses if that can't be stored. Notes come back in a `<history_notes>` block as history to cite: the date, the person's own words first, then how they were noted. With `due: true` it lists only notes with a due date, from a week overdue to two weeks ahead, soonest first (\"what's due today?\").\n- **In the owner's briefs.** The morning brief adds a FROM YOUR NOTES — DUE SOON block (`memory.history_brief.due_soon_block`: what the owner promised, agreed or asked of someone, from a week overdue to a week ahead, in the workspace's local dates) and the end-of-day digest a FROM YOUR NOTES — TODAY block (`noted_today_block`: what they promised, agreed, asked or declined since the last digest, then what is due tomorrow). Both only on the scheduler's delivery to the owner alone (`morning_brief.PRINCIPAL_DELIVERY`), never a run started from chat, whose tool result lands in the turn's shared audit row and peer memory; only when the owner may keep notes and has the switch on (`history_brief.owner_keeping_notes`), and only the owner's own notes. A run that used any is marked `private_to_principal`, so the shared run history keeps `PRIVATE_RUN_ARTIFACT` instead of its text, and the note ids with their state (overdue, today, soon) enter the brief's fingerprint, so one falling due un-suppresses an unchanged brief. Teammates get no brief, so their notes reach them only through recall and reminders.\n- **In Act as me drafts.** The ghostwriter gets a `<writer_noted>` block (`memory.history_drafts.notes_for_draft`): the writer's own notes from earlier Act as me replies that every recipient of the new draft was on, with their switch on. It keeps the draft consistent with them and turns a contradiction into an open question on the card; it never adds anything from them (see Act as me).\n- **Due-today reminders.** `memory.history_reminders.maybe_remind`, called from the scheduler tick every 15 minutes between 09:00 and 18:00 local time, sends each person with the switch on one message on a day something they promised or agreed to by email (`source = approved_reply`) falls due. Chat promises are left to open loops, which the nudge engine already chases. The message says only how many things are due, never what or to whom, and the channel senders' audit rows for it are private to the person (`audit.context.rows_for_person`; the owner's `private_rows`), which also keeps the send off the shared activity rail (`_record_send_to_activity` skips a send whose rows are private). The person asks \"what's due today?\" in a private conversation and `recall_history` answers. It goes to their own Slack or Discord DM, a private Telegram chat (`delivery_order` skips a negative group id, for the owner's briefs too) or their own email (`scheduler.runner.deliver_to_person`), never a shared channel. `history_reminders` holds one row per person per day, claimed before sending and never released, so two workers never both send and a half-failed send is never repeated; a failed one waits for the next due day.\n- **Not peer memory.** Notes never reach Honcho, episodic extraction, standing facts or another person's turn. The tables (`history_notes`, `history_settings`, `history_person_settings`, `history_excluded`, `history_chat_passes`, `history_reminders`, created by `history_schema.ensure_schema` from `initialize_db`) swap with a client slot and are cleared by a factory reset.\n\n### Conversation review (fixing what replies left undone)\n\n`memory.chat_review` looks back over a chat once it has been quiet `CHAT_REVIEW_QUIET_MINUTES` (30) and fixes what the replies left undone: \"I sent it\" answered with \"noted\" and the draft still waiting, \"drop that reminder\" answered with \"sure\" and the reminder still set. The claim check (`orchestrator.claim_check`, see Lifecycle) catches a false claim in the same turn; this catches the rest.\n\n- **Never from another AI app.** `history_chat.verified_speaker` refuses every turn from Open Executive's MCP server (`Session.from_mcp_client`), even one allowed to act that counts as a verified surface for its tools, so neither History notes nor the conversation review take that app's text as the person's own words.\n- **What is recorded.** On both the single-voice and the committee path the post-turn block calls `record_turn` with the speaker's own words (`delegation.settings.own_words`), the reply and the tools the turn ran (`_stream_agent_loop(calls_out=)`). Only a verified speaker's turn is kept: the principal on a surface `people_tools` verifies, or a rostered teammate on their own signed-in web chat, Slack or Discord. A channel whose adapter set `Session.speaker_verified` counts as a verified surface here too; an email, an unattended run, a turn private to the principal, one that touched the speaker's mailbox and a message with an attachment are never kept. Rows live in `chat_review_turns` for 7 days, a turn graded a miss (below) for `MISS_KEEP_DAYS` (90); each row also keeps the audit `turn_id` of the turn, so the claim check's row can be joined back to it.\n- **When.** Each kept turn makes sure one `chat_review` `__internal__` action is waiting for the conversation (`channel_ref` = session id), due 30 minutes on. The runner marks it done and calls `run_scheduled`, which schedules a fresh one if a newer turn arrived meanwhile, else reviews the oldest unreviewed turns (at most 20, the rest in a review right after) and marks exactly those reviewed, so a chat is read in parts and never twice. `CHAT_REVIEW_MAX_PER_DAY` (10) caps each person's passes a day (`chat_review_days`), so one person's chats can't use up another's.\n- **The pass.** One small tool loop per person on `CHAT_REVIEW_MODEL` (default `ROUTING_MODEL`), at most 5 rounds and 8 changes, in its own task with a session rebuilt from the recorded surface and caller and a delegation pin holding their words, so each tool runs through the chat tool's own handler and checks: `list_open_loops` / `close_open_loop`, `remember_fact`, `list_followups` / `cancel_followup` / `move_followup`, `leave_out_of_brief`, plus `learn_reply_style` (a working-style rule), `learn_writing_style` (a habit or avoid line in their Act as me voice profile, only for someone who may use it) and `raise_in_brief` (one line for the next brief). Every change carries `source_quote` of at least four of the person's own words (`fact_tools._quote_error`), and the thing it changes (the loop's or follow-up's text, the fact, the brief item or line) must share two words with what they wrote (its only one, for a one-word target) A chat draft's state is left to the brief's own check of the mailbox's Drafts. The replies are shown as `<untrusted_content>` (they quote mail and documents) and tool results not at all, only the tools' names. `leave_out_of_brief` and `raise_in_brief` are the principal's only; dropping a fact and changing a goal are left to chat. It never sends, books, deletes or grants permission to act, and nothing it does is said in chat. One `chat_review` audit row per pass lists the changes.\n- **Grading (looking back at how it went).** Before the fix loop, the same pass grades each turn it reads with one forced-tool call (`grade_turns`) on the review model. The grader sees what the fix loop sees plus one SIGNALS line per turn, joined from where the product already records them (`turn_signals`): a 👍/👎 and its note on the saved reply (`chat_messages`, matched to the recorded reply by its first 120 characters, which also gives the Reflection screen the reply's `message_id`), a reply the person stopped (`stopped`), a turn they took back to ask again (a `session_rewound` audit row after a turn whose reply is no longer in the chat), a claim the reply made that no tool backed (a `claim_check` audit row with the turn's `turn_id`), and a tool whose recorded result reads as an error. Per turn it records `fine`, `miss` or `unclear`; for a miss, `wanted` (what the person wanted instead, one or two sentences) backed by a `quote` of at least four of their own words from that turn or the ones after it, code-checked (`accept_grades`) or the turn is `unclear` and `wanted` dropped, plus the `kind`: `company` (a term, a fact, a preference, which specialist to ask, doing a thing rather than promising it would have fixed it) or `product` (a tool failed or was refused, a capability it lacks). A turn the model skipped is `unclear`. Grades go on the row (`verdict`, `kind`, `wanted`, `signals`, `graded_at`, `message_id`), and each person's weekly count of graded turns and misses on `chat_review_weeks`, so the rate outlives the 7-day rows. Grading changes nothing in the workspace and never blocks the fixes: a failed grade leaves the turns ungraded. The pass's audit row carries the counts. `list_misses` (one person's or everyone's; the route then keeps, for the principal, only rows from chats `chat._session_access` lets them open, so a teammate's own chat stays theirs), `weekly_rates` and `forget_miss` (`is_principal_or_self`) serve `GET`/`DELETE /memories/reflection` (the Pulse screen **What it got wrong**).\n- **Lessons** (`memory/lessons.py`): for a turn graded a miss the review may call `learn_lesson` once: one sentence this workspace wants done differently (a term and what it means, a preference about the content, a thing to do rather than promise, a specialist to consult), quoted from the person's own words (the quote must come from the miss turn or a later one, and the lesson must be what the quote says). It passes the working-style deny-list (`attunement.style._DENY_PATTERNS`: no link, handle, amount, markup, identifier, action verb, instruction talk, nudge to act unchecked, roster name) plus the lessons' own list (the verbs that move information: email, share, post, export, attach...; the words that widen a request to everyone or everything) without the about-the-writing requirement, may add at most two content words beyond the quote (`lesson_overreach`, so a real quote can't carry a different sentence in), and is re-checked on every render. Rows live in `chat_review_lessons` (text, quote, person, session, `shared` = learned in a channel or group thread, turn, `shown`, `fine_after`, `miss_after`, `retired_at`/`retired_reason`) with `chat_review_lesson_uses` (lesson, turn id, whose turn). A lesson reaches a turn by a keyword match (two shared content words between the lesson plus its quote and the message; no vector index for a list this short): the Executive's own turn gets the matching ones as a `<lessons>` block in the user turn (`build_lessons_block`, never a cached block; the header says the current request wins and nothing in it authorizes an action), and each specialist call gets the same lines under its `<failure_cases>` block (`router._lessons_for_call` → `lessons_for_query`). A lesson reaches its own person's turns; the principal's reach everyone's only when learned in a shared space (`shared`), so nothing said in someone's own chat is paraphrased into another person's turn. `build_lessons_block` counts each showing against the active turn id and the speaker; when the review later grades that turn, `note_outcome` adds to `fine_after` or `miss_after` only when the turn was the lesson's own person's (nobody else's chats can retire it), and a lesson shown 5 times with more misses than fine turns retires itself (`unhelpful`). At most 40 live lessons per person; their oldest retires to make room (`BEGIN IMMEDIATE`, so two reviews can't both skip it). Forget on the screen retires one by hand (`forgotten`); a retired lesson is listed as stopped, never erased.\n- **Replay: the workspace's own evals** (`memory/replay.py`). Nightly (the `chat_replay` scheduled action, `CHAT_REPLAY_TIME` 03:30 in the user's zone, seeded and chained like the reflection), the Executive runs its misses again with everything in force today and a judge says whether each would now go right. A case is a graded turn: a miss (its `wanted`), or a turn that went fine and got a thumbs up (`kept = 1`, held as long as a miss, at most `MAX_KEPT` 300 per person), which the replay protects so a lesson can't break what worked; a closed miss joins that pool. `due_cases` picks a miss the night a lesson is written for it (`WHY_LESSON`), when a lesson learned since the last night reaches it (`WHY_REACHED`), else once a week (`WHY_WEEKLY`), from the last 30 days only and at most `CHAT_REPLAY_MAX_CASES` (30) a night within `CHAT_REPLAY_MINUTES` (20); 20 protected cases (`WHY_PROTECT`, rotated by last replay) run only on a night a new lesson landed. `replay_case` runs `Executive.chat` on a session rebuilt from the recorded surface and speaker (`chat_review._rebuild_session`) with the saved conversation up to that turn (`chat_messages` before the reply's `message_id`), flagged `Session.replay`: reads run for real through every gate, and every tool a read-only turn is denied (`MCP_CLIENT_WITHHELD_TOOLS`, and gateway calls outside `MCP_CLIENT_MCP_TOOLS`) returns \"done\" and lands in `Session.replay_calls` instead (`faked_handlers` / `faked_call_tool`, wrapped outermost in the agent loop); scripts, Python jobs, `load_mcp_server`, Act as me's tools, `recall_history` and extension tools are not offered at all; nothing a replay does is kept (no extraction, open loops, style, notes, review or Honcho mirror, and `build_lessons_block(count=False)` counts no showing). The judge (`CHAT_REPLAY_JUDGE_MODEL`, else `EVAL_JUDGE_MODEL`, else Sonnet; `evals.judges.judge_message`) reads the original date, the person's words and the conversation before, what they wanted (or the reply they liked), today's reply and the recorded actions, and answers `{passed, time_bound, notes}`, intent and action rather than figures; an unreadable answer is a fail. The gate (`_settle`): a miss that passes is `closed` with `closed_at`; a time-bound one becomes `evidence` and is not replayed again; a lesson for a miss that still fails on `LESSON_FAILS` (2) judged replays after it was learned retires (`replay`); a protected case that fails reopens a closed miss and counts a strike against each new lesson of the same person that reached it (a teammate's turn never retires the principal's shared lessons), which retires at `PROTECT_FAILS` (2) such strikes, so one judged turn, or one message written to fail the judge, is not enough. A case that didn't run (an error, the `CASE_SECONDS` timeout) is recorded with `ran = 0` and settles nothing. The judge's input is scrubbed like outside content (`content_trust._scrub`) with the prompt's own tag names renamed inside it. Every replay is a `chat_review_replays` row (the reply and recorded calls; dropped with its turn when a miss or chat is forgotten or purged, `chat_review._prune_replays`) and a `chat_review` audit row (actor `chat_replay`); each night a `chat_review_replay_runs` row, written before the first case (so a second runner sees nothing new) and filled in after, which is also what \"new since the last night\" means. The nightly Executive carries the scheduler's MCP gateway, so the reads a miss needs run as they did. The Reflection screen's number, \"of the N things that went wrong in the last 30 days, M would go right today\" (`summary_for`, over the misses the caller sees), and each miss's last replay come from these columns on `chat_review_turns` (`replay_state`, `replayed_at`, `closed_at`, `replay_count`, `replay_notes`). Off with `CHAT_REPLAY_ENABLED=false` or when the review itself is off.\n\n## Decision ledger\n\n`openexecutive.memory.decision_ledger` keeps one `decision_instances` row per gated action — a meeting the Executive proposes to book, an Act as me reply card — with how it was resolved, so each class has a reliability record. Every status change is a compare-and-set. A tap with an outside effect (sending an email) claims the row first (`claim_for_execution`, proposed → executing), so of two taps only one acts, and finishes it as `approved_unchanged`, `approved_with_edit` or `failed`, or hands it back (`release_claim`). A row whose class acted on its own with nobody tapping — `gate_mode` `auto_execute`, as Act as me's **Handle it for me** replies are — finishes as `executed` instead, with no resolver, so a reliability read never counts it as an approval. A send whose result is unclear stays `executing` for a reconciler and is never retried. A row still waiting can have its payload changed only by compare-and-set (`update_open_payload`, on `proposed` and, when given, on the payload as it was read): that is how an Act as me reply card takes the person's edit, or records the draft made for it at Send.",
+ "markdown": "The Executive's durable memory is an episodic SQLite store at `./episodic_memory.db`, managed by `openexecutive.memory.episodic`. It holds four tables:\n\n- `decisions` — choices made, with `domain`, `summary`, `rationale`, `outcome`, and `tags`. `outcome` is filled in when the principal says how a decision turned out — the `record_decision_outcome` chat tool (principal on a verified surface only) or the Memories page. The weekly review reads this table twice: the week's decisions (`decisions_since`) and up to three older than 30 days with no outcome yet (`decisions_awaiting_outcome`), which it asks about.\n- `initiatives` — tracked efforts with a `status` and `summary` (idempotent upserts).\n- `advice_given` — query/advice pairs per domain.\n- `scheduled_actions` — a dispatch queue, treated separately from recall memory. `cancel_scheduled_action` guards its UPDATE on `status = 'pending'`, so a cancel never overwrites a row the scheduler claimed a moment earlier.\n\n### What gets extracted, and when\n\n`episodic.extract_and_store` runs after a turn and asks a utility-fast model for decisions, initiatives and advice. Every candidate must carry a `user_commitment_quote` that appears verbatim in the principal's own message (`_is_valid_user_commitment`) — the turn's speaker text (`memory_text` when the entry point supplies one, else the prompt), so a quoted Executive email or a briefing card's body inside the prompt cannot satisfy it — the model has repeatedly tried to log the Executive's *recommendations* as the user's commitments, and that quote is the hard gate against it.\n\nA turn reaches the extractor if `should_extract(speaker_text, session=...)` is true, which means only that the principal said something on a surface that proved it was them — there is deliberately **no length floor**. There used to be one, on the combined user+assistant length, and on a live tenant it selected almost exactly the wrong turns: 9 of 16 exchanges were blocked, and the 9 held every instruction the principal gave, while the 7 admitted were long analytical exchanges with no commitment in them. The extractor ran 13 times and stored nothing.\n\nMoving that floor to the user's side would relocate the bug, not fix it. The canonical executive decision is a long analysis answered with \"Approve option B.\" (17 chars) or \"Do B.\" (5), and any floor high enough to skip \"Done\" (4) also skips those — \"Do B.\" and \"Done\" differ by one character and mean opposite things. Length cannot separate a decision from an acknowledgement; the verbatim-quote check can, so `_is_valid_user_commitment` is the gate that decides. The price is one utility-fast call on turns that propose nothing.\n\nThat quote check is only meaningful when `user_message` holds the **principal's** words, and on a chat channel it does not — `Executive.chat()` is reached from Slack, Discord, Telegram, Google Chat and the email poller. A teammate's line would be written to `decisions` with no speaker attached, indistinguishable from the principal's own; an inbound email body is text the sender chose, so a self-quote is free. Removing the length floor is what makes this bite — short channel traffic used to fall under it incidentally — so `should_extract` asks the untrusted-content policy (`orchestrator.content_trust.principal_speaking`) whether the principal is speaking. It names the principal's surfaces rather than inferring them: the web chat (signed in as the principal — or, on an install with no principal on the People page yet, a request that carried no sign-in; a signed-in email on nobody's entry, such as an archived teammate still allowed to sign in, is not the principal), the CLI (`Session.from_cli`), the principal's own Slack or Discord or a private Telegram chat with a valid webhook secret (`people_tools.is_principal_on_verified_surface`), and email from the principal's primary address that Gmail's own `Authentication-Results` marks `dmarc=pass` (`Session.email_authenticated`). Everything else fails closed: a teammate (on the web too), an unrostered sender, the principal's address on mail Gmail did not authenticate, Google Chat, the MCP server (its caller names themselves), unattended runs, and an unreadable roster. The rule used to be \"no `origin_channel` means the principal's own surface\", and the email poller left `origin_channel` empty, so every stranger's email ran through the extractor with its body — headers, quoted chain and all — as the principal's words, and whatever it stored rendered on every later turn. The poller now tags its sessions `origin_channel=\"email\"`, and the gate no longer reads an empty channel as trust.\n\nThe extractor also reads only the words **outside** every `<untrusted_content>` block (`schedule_extraction` runs `content_trust.strip_untrusted` first): an attached document's text is inlined in that block, so a sentence the principal did not type can never be quoted back as their commitment, and a turn that is nothing but an attachment is not extracted at all.\n\nEach pass writes a `memory_extraction` audit row — in a `finally`, so a pass that crashed is recorded too, with the exception type as its `failure` reason: how many items the model proposed, how many were stored, a `malformed` count so a pass where the model returned only garbage does not read as one that found nothing, and a `{kind, reason}` record per drop — `bad_quote` and `missing_field` for an item the model proposed, `not_a_list`, `item_not_a_dict` and `payload_not_a_dict` for a shape that was never a usable item. Every proposed item is either stored or dropped, so `proposed == stored + item drops` is the arithmetic that says whether anything was lost silently. The tool payload is not schema-checked anywhere, so a malformed shape is counted as a drop rather than raised — it used to abort the whole pass, discarding the other two kinds with it and suppressing the row, which read exactly like \"extraction never ran\". Without it, \"the model found nothing\" and \"the model found things and every one was rejected\" are indistinguishable from outside the database — which is why the failure above survived undetected and took a SQLite session on the tenant to find. A `proposed>0, stored=0` streak is the signal to watch.\n\nThe validator rejects a paraphrase, and the model paraphrases: on one install two of three real commitments were lost that way, the quote beginning \"SVN's engagement covers only …\" where the person had typed something else. So a `bad_quote` drop earns exactly one corrective call. The model is shown the rejected items and the quotes it gave, told to copy the span character-for-character (typos and casing included) or return empty arrays, and the tool is forced where the provider supports tool choice. Every retry item is validated first; a still-invalid one adds no second drop and is counted `still_invalid`. A valid item is then classified in order: its label matches a pending drop record → a recovery, stored and the record released; else its quote (terminal punctuation ignored) already supports a stored item of that kind → a re-send, ignored and counted `repeated`, so a model that re-sends everything cannot double-count `stored`; else a new proposal, stored and counted — a reworded label cannot be told from a different item, and crediting it would erase the very `bad_quote` census the row exists to show, so its original drop stands. Recovery is checked before re-send because two commitments can rest on one sentence. Malformed shapes at any level — a kind that is not a list, an item or payload that is not a dict, a response with no tool call — are counted `malformed`, so a retry that returned garbage does not read like one that obediently returned nothing. The row's `retry` block (`rejected`, `recovered`, `repeated`, `still_invalid`, `malformed`, `failure`) is always present, zeros when nothing was rejected; `rejected` is set from the complete drop list when the row is written, so neither a store failure before the retry nor a cancellation during it can zero it. The arithmetic above still holds after the retry. An exception on the retry is recorded as the retry's own `failure` and leaves the first pass's results untouched; the cost is one utility-model call, only on turns that dropped something. `memory_extraction` is a declared event type, so the audit page's filter can select it.\n\n### Standing facts (corrections that persist everywhere)\n\nA fifth table, `facts` (`openexecutive.memory.facts`, created on first write), holds facts and corrections the principal stated and asked to keep — \"Maple House is 48 units, not 52\". Before it, a chat correction's only durable home was Honcho peer memory: optional, best-effort (its prefetch times out or errors under load), re-injected only into that person's later chat turns, and never read by the briefs, the scheduled runs or the alert review. The episodic extractor cannot hold one either: it stores only decisions backed by a commitment quote, and a fact is not a commitment.\n\n- **Written from chat, by the principal or an attributed teammate.** `remember_fact` stores one (subject, statement, optional wrong value) and `forget_fact` retires one. The principal on a verified surface may do both. A teammate on the People list (a `team` row, not archived, not a contact) on a verified surface (the web app signed in, their own Slack or Discord; `fact_tools._teammate_speaker`) may call `remember_fact` only; email, Google Chat and unrostered senders are refused. Both tools are withheld from every unattended run and every turn private to the principal. Every call, `forget_fact` included (retiring a fact changes what later prompts treat as true just as writing one does), also needs `source_quote`: at least two words and eight characters, found in what the speaker typed this turn (`delegation.settings.own_words` over the pinned `TurnDelegation.speaker_text`). The `<outbound_reply_context>` backstory a Slack or Discord reply is hydrated with is stripped first, and a message with an attachment is refused outright. The quote alone only proves the principal asked, so everything `remember_fact` stores and renders (the statement, the subject shown as `[fact N] subject:`, and a previous value shown as `(corrects: …)`) is tied to their words too. An omitted previous value falls back to the replaced fact's own statement. Every figure must be a number they wrote, compared at its magnitude: `$180k` matches `180,000`, but `180m` never lets `$180k` through. Every name must also appear in what they typed: a capitalised word, or any word holding a non-ASCII letter, other than the statement's very first word (a statement is one fact, so splitting a document's names into one-word sentences exempts nothing). So must every month, weekday or quarter. A name the model writes in lower case is not caught: the gate narrows what a real quote can carry in; it does not prove a paraphrase. A real quote therefore cannot carry a document's figure, name or date in with it (\"Cedar Court's lease expires in March\" after \"remember what the lease doc says\"), while a paraphrase of what they said still passes. So the model cannot store its own inference, a document's figure or text quoted back at the principal as something they said. Every audit row the tools write, and the chat loop's `skill:` dispatch row for them (whose input quotes the principal verbatim), is private to the principal (`executive._private_tool_row`). Those rows tie a fact to the principal's session and turn, which `GET /memories/facts` hides from teammates, and a teammate can read any non-private audit row. The handlers run in a worker thread (`asyncio.to_thread`, which carries the turn's context), and the chat and committee paths, the alert review, the morning brief's synthesis and the end-of-day, weekly-review and reflection workflows read the block the same way, so SQLite, the profile file and its lock never block the event loop the SSE streams share. The principal's own email may ask too: the change is checked the same way, then held until they confirm it by replying to a one-time token sent to their own address (see Integrations → Standing facts by email).\n- **Provenance and attribution.** Each row keeps the quote, the channel (`web` or the adapter), `session_id`, `turn_id`, the recording person and the time, plus `recorded_by_role` (`principal` or `teammate`) and, for a teammate, `recorded_by_name` as the People list had it. Rows written before these columns existed read as the principal's (`_migrate` adds the columns on the first write; the read-only render tolerates a DB that has none).\n- **One active fact per subject.** A new row supersedes any active row with the same folded subject key, or the id named in `replaces_fact_id`, in one transaction. The old row stays as `superseded` (with `superseded_by`), and the new one is stored as a `correction` carrying what it replaced. Retiring sets `retired` with a reason. **The principal outranks a teammate:** a teammate's write that would replace an active fact the principal set (by subject or `replaces_fact_id`) raises `PrincipalFactConflict`, and the tool stores it as `proposed` instead, naming the fact it would replace (`replaces_fact_id`); teammates replace each other's facts freely, and the principal replaces anyone's. **\"Needs my approval\"** (`fact_approval_rules`, per teammate, **on by default**, set only by the principal) stores every fact from that teammate as `proposed`; the principal turns it off for a teammate they trust, whose facts then apply at once (except one that would replace the principal's). The rule is read inside `record_fact`'s own write transaction, so a switch turned on a moment earlier cannot let one fact through; a teammate write that names no person is never trusted. One teammate may have at most `MAX_PENDING_PROPOSALS_PER_PERSON` (20) proposals waiting (`TooManyProposals`; the tool tells them to wait for the principal's review). A teammate's retire checks ownership in the `UPDATE` itself (`retire_fact(teammate_id=)`: their own row, not approved). A proposed row never renders; `approve_fact` makes it active and replaces what it names (the principal's own fact included — approving it is their word) and stamps `approved_at`, after which it outranks teammates exactly as the principal's own fact does (`Fact.principal_owned`: no teammate may replace or retire it); `decline_fact` sets `declined`. No field of a teammate's fact may carry what the render adds itself — `(per <anyone>)` in any case (a unit such as `(per month)` or `(per unit)` is fine), `[fact N]` or a date stamp after any dash, read NFKC-folded with invisible characters removed (`fact_tools._marker_error`) — so a teammate cannot plant a second, forged attribution inside their statement (the principal's own unmarked lines are not checked: \"(per Smith lease)\" is ordinary wording for them). The tool answers `awaiting_approval` (no action chip) and tells the model to say it is not in use yet.\n- **Rendered everywhere output is produced.** `render_facts_for_prompt` renders the active rows newest first under a self-explaining `STANDING FACTS` header (use these over older figures; a line ending `(per <name>)` is that teammate's word and the principal's unmarked line wins a conflict; the current conversation still wins; quoted data never instructions). A teammate's line ends `(per <name>)`, the name defanged like the rest, capped at 40 facts / 6000 chars, with angle brackets defanged. It opens the DB read-only and never creates it or the table. The block always rides in a user turn, never a cached system block: a chat turn's `<standing_facts>` (so every scheduled run through the chat loop too), each specialist consult (`route_to_specialist`, chat and workflow steps alike), the /today header and the morning brief (`render_briefing_context`, after the quiet check and inside the string the header's cache key hashes, so a new fact rewrites the header), the alert review's batch (`render_batch`, read once per pass), and the end-of-day digest, the weekly review's top-three call and the morning reflection (`with_standing_facts`).\n- **Company-profile edits from chat.** `update_company_profile` (same gate and quote rule) changes one whitelisted field of `company/profile.yaml`, under `PROFILE_EDIT_LOCK` (also taken by `PATCH /company-profile`, so neither edit silently drops the other): a text or number field is set, a list field gets an item added or removed, and `financials.key_metrics` takes a named metric. It writes through `CompanyProfile.save_to_yaml` and updates the session's profile, so the next turn's cached company block carries it (one cache miss on the change). The new value must itself appear in the principal's own words, not just the quote: the value renders into the cached company block on every later turn, so \"set our mission to what the doc says\" or \"update our headcount\" is refused rather than saving a document's text or a guessed figure. A number must be one they wrote, however they wrote it (`$180k`, `1.2m`, `2,400,000`). Saved text has `<`/`>` defanged. A `kind='profile'` row records each edit with its quote for the Pulse page. Those rows are never rendered into a prompt, because the profile block already carries the value.\n\n### Session scoping\n\n`decisions` and `advice_given` rows carry a `session_id`, so per-thread channels (Discord, Telegram) can pull just-this-thread history without leaking cross-conversation context. A null `session_id` falls back to a global view.\n\n### Surfacing\n\n`openexecutive.memory.episodic.format_for_prompt` renders recent decisions and initiatives into a compact `<past_decisions>` block injected into the user turn — alongside `<retrieved_context>` and peer memory — never into a cached system block. Each decision names where it was recorded when that was a channel — `- 2026-09-01 [finance] (via email): …`, from the prefix of its `session_id` (`email:`, `slack:`, `discord:`, `telegram:`, `google_chat:`); a web or CLI decision has no tag. Rows extracted from mail before the untrusted-content policy, when any sender's body could be stored, therefore read as mail rather than as the principal's own word.\n\nScoped to a session, decisions and advice cover every conversation of a chat app's stream (`memory.conversation_ids.family_clause`): a Telegram chat or a DM is cut into conversations after two quiet hours or a /new (`memory.conversations`), and what an earlier conversation decided still renders in the next.\n\nThe chat route also injects a `<briefing>` block into the same user turn: a compact digest of the current open (unread) alerts, built by `openexecutive.briefing.context.format_open_alerts_for_prompt` (company-wide, `status=\"unread\"`, mirroring `/today`). This is what lets the Executive discuss a briefing item the principal clicked or named on `/today` (e.g. \"Gulf Coast Port Cyberattack\"). It is resolved in parallel with the other context fetches, omitted when there are no open alerts, and never placed in a cached system block.\n\nOn the Pulse page the Memory section shows the three lists as Decisions, Initiatives and Advice tabs, then a **Corrections** tab (`GET /memories/facts`: active standing facts and profile edits with their quote, channel and — for a teammate's — their name; proposals first under \"Waiting for your approval\" with **Approve** / **Decline** for the principal; the replaced, retired and declined history folded away; **Retire** on any fact for the principal and on their own not-yet-approved one for a teammate; and, for the principal, a per-teammate \"needs my approval\" switch), and a **History** tab for the person's own Always in the loop notes (see below). The header's Memories tile counts the three lists. What peer memory has learned about the signed-in person is theirs alone, so it is not on Pulse: it is on **Settings → About you** (see the peer memory section).\n\nThe same user turn carries a `<drive_memory>` block when the conversation has touched Google Drive (`openexecutive.memory.drive_reads`). Drive is reached only as live Google Workspace calls inside a turn and history keeps only prose, so without it a file found one turn was gone the next. `MCPGateway.call_tool` hands each `search_drive_files` and `get_drive_file_content` result to `record_drive_result`, which keeps, per session, every file found or opened (file id, name, type, link, and for an opened file its first 600 characters) and every search that matched nothing, with its query. `format_drive_memory` lists the 20 most recent files, so \"the file you found earlier\" resolves to a file id the Executive reopens rather than searching again, and the queries that found nothing (dropped once the same query later finds something). Rows are keyed on the session *and* the speaker, and shown only to that speaker in that session, because one session can span several people (an email thread, a Slack or Discord thread). Nothing is recorded or shown without a bound `current_session` and a rostered speaker, on a turn private to the principal, or on one that touched the speaker's own mailbox (Act as me). workspace-mcp writes file names into its output unescaped, so a name containing a newline can forge a result line. Only a Drive-shaped file id, type and `docs`/`drive.google.com` link are therefore kept; any other line is dropped, and the name is always quoted as the file's own content, not instructions. Each speaker keeps at most 100 files and 100 searches per session, older rows are pruned on write, and `session_store.delete_session` drops them all.\n\nThe scheduler reads one more thing from the transcript: when a follow-up back to the person who set it fires, `session_store.own_messages_since` gives it that person's own messages since it was set (their words only, across their conversations, capped), so a follow-up whose reason was already settled in chat stands down instead of sending (see the scheduler section).\n\nA conversation can also become its owner's alone. When Act as me first reads the speaker's own mailbox in it, `session_store.mark_mail_private` sets `sessions.mail_private` (creating the row with its owner when a channel adapter hasn't written it yet), and from then on only the session's owner may open, continue or delete it — the principal included, when it is a team member's (`chat._session_access`). It is never cleared. Beside it `sessions.mail_read_at` keeps how many history messages the conversation held before the last turn that read the mail (`session_store.mail_read_at`; NULL on rows marked before the column): Act as me's hold on links and scripts in later turns lasts only while that turn is still in the history window (see Act as me). \n\nThe chat list has owner controls on the same row: `sessions.pinned_at` (pinned chats list first) and `sessions.title_locked` (set by `rename_session`, after which `update_session_title`, the automatic title, leaves the name alone). Chats are also grouped by topic for their owner (`memory/chat_topics.py`): a `chat_topics(id, owner_person_id, name, kept, pinned_at, created_at)` row per topic, unique per owner and name (any case), and `sessions.topic_id` with `sessions.topic_source` (NULL = not looked at, `auto` = chosen by the model, `owner` = filed by the owner and never refiled). The one utility-fast call that titles a new chat (`utils/chat_topics.name_chat`, from the web chat and the chat-app conversations) also picks its topic, reusing one of the owner's 60 most recent topic names or making a new one. Only when the owner alone has written in the chat: a channel or group conversation, a shared chat, or one where someone else wrote first is titled without the owner's topic names in the prompt (another writer could steer the title into repeating them) and is filed later by the backfill, whose answer only the owner sees. Each call is bounded by the utility-fast timeout (60 s for a backfill batch). Only a turn that makes a new topic costs a second short call, over the topic names alone, which merges it into an existing topic that means the same unless the owner has `kept` it (renamed, pinned, merged into or filed a chat under it). Chats from before, or whose naming failed, are filed from their titles in batches of 80 the first time the owner opens the Topic view (`backfill`; a failure waits 10 minutes). Topics left with no chat are dropped when listed. Related topics share an `area` (`chat_topics.area`, `area_kept`): one property, deal or client, shown as one heading over them. The same second call that checks a new topic also names the area it shares with related ones, and after the backfill one call over the names gives areas to topics not yet looked at (once the owner has three); an area counts only when two topics share it. An area the owner renamed or ungrouped is left as they made it. A `session_shares(session_id, person_id, shared_by_person_id, created_at)` row adds one team member to someone's chat (`list_shared_with_person`, `set_shares`, `leave_share`): they read and write in it with its owner, each of their messages saved with their own `sender_person_id`; a `mail_private` chat is never shared or opened that way, and deleting the chat drops its shares. `last_turn_sender` says who wrote the last turn, which is how redo stays with the person who asked. The chat list's preview puts `You:` only before the caller's own words. `rewind_last_turn` deletes a web chat's last turn (the last reply and the user messages after the reply before it) so it can be asked again; the next turn's history is re-read from these rows, so nothing else needs clearing. A search that matched nothing also gains a note in its tool result: say the exact query and that it found nothing, never that the file does not exist. This is a first step: Drive is still not indexed into the company collection.\n\n### System of record\n\nSQL is the system of record; the peer-memory service is a recall layer mirrored from it, not a replacement. When `store_decision` / `store_initiative` / `store_advice` insert a row whose `department` is non-empty and not `\"general\"`, the row is mirrored as a kind-tagged note into that department's peer via `append_department_note`. The mirror fires only after a successful INSERT, is fire-and-forget, and never rolls back the SQL row on peer-memory failure. `scheduled_actions` is never mirrored — it is a queue, not memory.\n\nThe episodic extractor still learns only from the principal's own words. Commitments and asks from everyone else on the roster are tracked as **open loops** (see Attunement) — `scheduled_actions` rows with `kind='open_loop'`, opened and closed by a separate quote-gated pass after each attributed turn. That pass depends on `chat_messages.sender_person_id`, which records who actually wrote each persisted user message. An open loop counts toward `list_awaiting_replies_by_person` only once it is due, and `list_scheduled_actions(exclude_internal=True)` filters `__internal__` rows in SQL so readers that want real sends are not starved by them. `mark_outbound_context_consumed` also resolves the Attunement outcome row for that DM as `replied` — a matched reply is the clearest sign proactive outreach landed — and a real change to an existing initiative (`store_initiative` / `update_initiative`, new status or summary) marks the updater's own check-in nudges `acted` — an update with no known updater, such as `PATCH /memories/initiatives/{id}`, credits nobody.\n\n### Workspace settings\n\nThe same database holds one row of settings that are not memory: `workspace_settings` (`openexecutive.memory.workspace_settings`) — the install's mode (`team` by default, or `solo` for one person using Open Executive just for themselves), the user's IANA time zone, the principal's role (`PrincipalRole`: `role_kind`, `role_title`, `reports_to`, `remit`, `measured_on`, all nullable; only solo mode reads it), and the company's own email domains (`company_domains`, a JSON list, or NULL to derive them from the principal's primary address — `people.identity` matches a teammate by local part on them; `validate_company_domains` lowercases, dedupes and sorts, allows at most 10 plain DNS names and refuses a free-mail provider's, and a stored value that no longer validates reads as NULL). It is a table of its own rather than a company-profile field because onboarding rebuilds the profile from scratch. Every read is fresh and read-only (a missing file or table reads as the defaults; a table from before the role or `company_domains` columns reads them as unset and is migrated additively by the next init or write). A read error (a locked database, say) also reads as the defaults, so `get_workspace` then says team; `read_stored_mode` is the strict read of the mode alone — None when the row cannot be read or holds no valid mode — for the scheduler's weekly-review check, which must not take a failed read for team. A session may carry an explicit `workspace_mode` override; otherwise the mode is read fresh at the start of each turn and pinned on the session for that turn only (`Session.turn_workspace_mode`, via `pin_turn_workspace_mode`), so every tool handler in the turn sees the mode its persona and tools were built in. `effective_workspace_mode` reads override, then the pin, then the setting; `effective_principal_role` reads a session's `principal_role` override, then the role pinned for the turn (`Session.turn_principal_role`, via `pin_turn_principal_role`), then the stored role. See Org for what solo changes and Scheduler for the time zone.\n\n### Act as me\n\n`initialize_db` also creates Act as me's per-person tables (`delegation.schema.ensure_schema`): `delegation_settings`, `delegation_voice` and `delegation_voice_history`. They hold a setting and a writing profile rather than memory, and nothing in them is mirrored to peer memory. A turn that touched the speaker's own mailbox teaches no memory: the episodic, open-loop and working-style passes are skipped along with the Honcho peer and department syncs, since its reply quotes a draft built from other people's mail. See **Act as Me (Delegation)**.\n\n### Always in the loop (notes of what you said)\n\nA person can keep private, dated notes of what they said, in chat with the Executive and in email replies it drafted for them: what they promised, agreed, declined, answered, asked for or shared. The switch is per person (\"Keep track of what happens\", `history_person_settings.reply_notes`, off by default, one switch for every channel). Any team member on the People list may turn it on (`history.can_keep_notes`: kind `team`, not archived, the principal included); Act as me isn't needed, though notes from email replies only come through it.\n\n- **Where notes come from: chat.** After each chat turn, on both the single-voice and the committee path, the Executive's post-turn block calls `memory.history_chat.schedule_chat_notes` next to the open-loop and style passes, except on a turn that touched the speaker's mailbox. It reads only what the speaker typed this turn (`delegation.settings.own_words`: no backstory an adapter added, nothing when a file came with it), never the reply and never anyone else's message: every channel calls the Executive with the one speaker's message, and what other people say to each other is never read. It runs only for a speaker the turn verified (`history_chat.verified_speaker`): the turn's `caller_person_id` is them, nobody started it by email or runs it unattended or for them, and the surface proved who they are (the web chat signed in or a local install, the principal or a team member on their own Slack or Discord, a private Telegram chat behind a valid webhook secret, or a channel whose adapter verified the sender itself and set `Session.speaker_verified`). A shared Slack or Discord thread counts: the notes stay private and are read back only where nobody else can see them. A message under 40 characters is skipped, and each person gets at most 40 passes a day, counted in `history_chat_passes` so the cap holds across workers and restarts. The pass uses a constant `CHAT_PROMPT` (requests to the assistant, questions and small talk are not notes), the same `record_notes` tool and the same `check_note` gate with the message as both body and allowed words; the note's channel is the inbound channel or `web`, its conversation the session id, and it names no counterpart.\n- **Where notes come from: email.** After `delegation.reply_send` sends a reply, it starts `memory.history_notes.note_sent_reply` in the background. The note-taker reads only the words the person sent (`email_poller.sender_new_text` strips quoted mail) and the recipients' names, cut to four words of name characters (`history_notes.short_name`): never the mail being answered, nor the subject, which others in the thread write too, so nothing another person wrote can become a note. One forced `record_notes` call with a constant prompt and no other tools returns at most three notes. Code then drops any note that says more than they did: the `quote` must appear word for word in what they sent, every figure in the summary must be in the quote, every name or date word must be in what they sent or the recipients' names, at least half its other content words must be theirs, the summary carries no link or address, and a `due_date` is kept only for something promised or agreed. Notes record events, never instructions, and carry `trust = high` because they rest on the person's own words.\n- **Whose they are.** Every note is private to its person (`visibility = private`). Nobody else reads it, the principal included; there is no shared note.\n- **How long they last.** The company default is 90 days (`history_settings.retention_days`, the principal's choice of 30, 90, 365 or until forgotten). A person may only choose a shorter time; shortening the company time clamps everyone's choice and re-dates live notes. A pinned note never expires; unpinning restarts its clock, and a later retention change counts from there. Reads skip expired notes and the scheduler's alert sweep deletes them (`history.sweep_expired`).\n- **What a person controls.** Through `/memories/history` they read, search, pin, correct and forget their own notes. On the Pulse page this is the **History** tab, last in the Memory section and shown only to someone with notes to see (signed in and on the People list): each note shows its kind, who it was with, the date, the person's own words, any due date and when it will be forgotten, and its menu holds **Correct** (a side panel; \"Use the original\" clears a correction), **Pin**, **Don't remember this** and **Forget**. \"Don't remember this\" forgets every note from that conversation and adds it to `history_excluded`, so it is never noted again. Settings → **Memory** holds the switch (\"Keep track of what happens\") and a shorter time for their own notes, and the company time, which the principal changes and everyone else reads. A chat note shows the channel alone (\"Slack\", \"Web chat\").\n- **Recall.** `recall_history` (`orchestrator.history_tools`) is offered only on a turn where the speaker may read their notes: verified as above, a team member who may keep notes, in a conversation private to them (`history_chat.private_chat`: the web chat, a Slack or Discord DM, a Telegram chat, or one its adapter marked `Session.private_chat`), with their switch on. Before any note is read the turn is set `touched_mail`, for the principal too, so its rows are private to the speaker, it teaches no memory and the mail lockdown holds from that round on. The conversation is also marked theirs alone (`session_store.mark_mail_private`), so every later turn in it is private the same way (the lockdown is that turn's alone) and, for a team member, the principal can't open it; recall refuses if that can't be stored. Notes come back in a `<history_notes>` block as history to cite: the date, the person's own words first, then how they were noted. With `due: true` it lists only notes with a due date, from a week overdue to two weeks ahead, soonest first (\"what's due today?\").\n- **In the owner's briefs.** The morning brief adds a FROM YOUR NOTES — DUE SOON block (`memory.history_brief.due_soon_block`: what the owner promised, agreed or asked of someone, from a week overdue to a week ahead, in the workspace's local dates) and the end-of-day digest a FROM YOUR NOTES — TODAY block (`noted_today_block`: what they promised, agreed, asked or declined since the last digest, then what is due tomorrow). Both only on the scheduler's delivery to the owner alone (`morning_brief.PRINCIPAL_DELIVERY`), never a run started from chat, whose tool result lands in the turn's shared audit row and peer memory; only when the owner may keep notes and has the switch on (`history_brief.owner_keeping_notes`), and only the owner's own notes. A run that used any is marked `private_to_principal`, so the shared run history keeps `PRIVATE_RUN_ARTIFACT` instead of its text, and the note ids with their state (overdue, today, soon) enter the brief's fingerprint, so one falling due un-suppresses an unchanged brief. Teammates get no brief, so their notes reach them only through recall and reminders.\n- **In Act as me drafts.** The ghostwriter gets a `<writer_noted>` block (`memory.history_drafts.notes_for_draft`): the writer's own notes from earlier Act as me replies that every recipient of the new draft was on, with their switch on. It keeps the draft consistent with them and turns a contradiction into an open question on the card; it never adds anything from them (see Act as me).\n- **Due-today reminders.** `memory.history_reminders.maybe_remind`, called from the scheduler tick every 15 minutes between 09:00 and 18:00 local time, sends each person with the switch on one message on a day something they promised or agreed to by email (`source = approved_reply`) falls due. Chat promises are left to open loops, which the nudge engine already chases. The message says only how many things are due, never what or to whom, and the channel senders' audit rows for it are private to the person (`audit.context.rows_for_person`; the owner's `private_rows`), which also keeps the send off the shared activity rail (`_record_send_to_activity` skips a send whose rows are private). The person asks \"what's due today?\" in a private conversation and `recall_history` answers. It goes to their own Slack or Discord DM, a private Telegram chat (`delivery_order` skips a negative group id, for the owner's briefs too) or their own email (`scheduler.runner.deliver_to_person`), never a shared channel. `history_reminders` holds one row per person per day, claimed before sending and never released, so two workers never both send and a half-failed send is never repeated; a failed one waits for the next due day.\n- **Not peer memory.** Notes never reach Honcho, episodic extraction, standing facts or another person's turn. The tables (`history_notes`, `history_settings`, `history_person_settings`, `history_excluded`, `history_chat_passes`, `history_reminders`, created by `history_schema.ensure_schema` from `initialize_db`) swap with a client slot and are cleared by a factory reset.\n\n### Conversation review (fixing what replies left undone)\n\n`memory.chat_review` looks back over a chat once it has been quiet `CHAT_REVIEW_QUIET_MINUTES` (30) and fixes what the replies left undone: \"I sent it\" answered with \"noted\" and the draft still waiting, \"drop that reminder\" answered with \"sure\" and the reminder still set. The claim check (`orchestrator.claim_check`, see Lifecycle) catches a false claim in the same turn; this catches the rest.\n\n- **Never from another AI app.** `history_chat.verified_speaker` refuses every turn from Open Executive's MCP server (`Session.from_mcp_client`), even one allowed to act that counts as a verified surface for its tools, so neither History notes nor the conversation review take that app's text as the person's own words.\n- **What is recorded.** On both the single-voice and the committee path the post-turn block calls `record_turn` with the speaker's own words (`delegation.settings.own_words`), the reply and the tools the turn ran (`_stream_agent_loop(calls_out=)`). Only a verified speaker's turn is kept: the principal on a surface `people_tools` verifies, or a rostered teammate on their own signed-in web chat, Slack or Discord. A channel whose adapter set `Session.speaker_verified` counts as a verified surface here too; an email, an unattended run, a turn private to the principal and a message with an attachment are never kept. A turn that touched the speaker's mailbox, and every turn of a conversation that once did (`sessions.mail_private`), is kept for their own review only: its tools are kept by name with only a failure marker, never their output (other people's mail), its fix loop is not offered `remember_fact`, a lesson from it is never shared, the Reflection screen shows it to its owner alone (`chat._session_access`), and every audit row the review and the nightly replay write about it is that person's own (`chat_review_turns.mail`, `mail_private_turns`, `audit.context.rows_for_person`), since a judge's notes quote the chat. Rows live in `chat_review_turns` for 7 days, a turn graded a miss (below) for `MISS_KEEP_DAYS` (90); each row also keeps the audit `turn_id` of the turn, so the claim check's row can be joined back to it.\n- **When.** Each kept turn makes sure one `chat_review` `__internal__` action is waiting for the conversation (`channel_ref` = session id), due 30 minutes on. The runner marks it done and calls `run_scheduled`, which schedules a fresh one if a newer turn arrived meanwhile, else reviews the oldest unreviewed turns (at most 20, the rest in a review right after) and marks exactly those reviewed, so a chat is read in parts and never twice. `CHAT_REVIEW_MAX_PER_DAY` (10) caps each person's passes a day (`chat_review_days`), so one person's chats can't use up another's.\n- **The pass.** One small tool loop per person on `CHAT_REVIEW_MODEL` (default `ROUTING_MODEL`), at most 5 rounds and 8 changes, in its own task with a session rebuilt from the recorded surface and caller and a delegation pin holding their words, so each tool runs through the chat tool's own handler and checks: `list_open_loops` / `close_open_loop`, `remember_fact`, `list_followups` / `cancel_followup` / `move_followup`, `leave_out_of_brief`, plus `learn_reply_style` (a working-style rule), `learn_writing_style` (a habit or avoid line in their Act as me voice profile, only for someone who may use it) and `raise_in_brief` (one line for the next brief). Every change carries `source_quote` of at least four of the person's own words (`fact_tools._quote_error`), and the thing it changes (the loop's or follow-up's text, the fact, the brief item or line) must share two words with what they wrote (its only one, for a one-word target) A chat draft's state is left to the brief's own check of the mailbox's Drafts. The replies are shown as `<untrusted_content>` (they quote mail and documents) and tool results not at all, only the tools' names. `leave_out_of_brief` and `raise_in_brief` are the principal's only; dropping a fact and changing a goal are left to chat. It never sends, books, deletes or grants permission to act, and nothing it does is said in chat. One `chat_review` audit row per pass lists the changes.\n- **Grading (looking back at how it went).** Before the fix loop, the same pass grades each turn it reads with one forced-tool call (`grade_turns`) on the review model. The grader sees what the fix loop sees plus one SIGNALS line per turn, joined from where the product already records them (`turn_signals`): a 👍/👎 and its note on the saved reply (`chat_messages`, matched to the recorded reply by its first 120 characters, which also gives the Reflection screen the reply's `message_id`), or a thumbs up or down typed or said as the whole next message (a chat app has no buttons), a reply the person stopped (`stopped`), a turn they took back to ask again (a `session_rewound` audit row after a turn whose reply is no longer in the chat), a claim the reply made that no tool backed (a `claim_check` audit row with the turn's `turn_id`), and a tool whose recorded result reads as an error. Per turn it records `fine`, `miss` or `unclear`; for a miss, `wanted` (what the person wanted instead, one or two sentences) backed by a `quote` of at least four of their own words from that turn or the ones after it, or by a signal on the turn other than a 👍 (a miss the product recorded needs no words from them), code-checked (`accept_grades`) or the turn is `unclear` and `wanted` dropped, plus the `kind`: `company` (a term, a fact, a preference, which specialist to ask, doing a thing rather than promising it would have fixed it) or `product` (a tool failed or was refused, a capability it lacks). A turn the model skipped is `unclear`. Grades go on the row (`verdict`, `kind`, `wanted`, `signals`, `graded_at`, `message_id`), and each person's weekly count of graded turns and misses on `chat_review_weeks`, so the rate outlives the 7-day rows. Grading changes nothing in the workspace and never blocks the fixes: a failed grade leaves the turns ungraded. The pass's audit row carries the counts. `list_misses` (one person's or everyone's; the route then keeps, for the principal, only rows from chats `chat._session_access` lets them open, so a teammate's own chat stays theirs), `weekly_rates` and `forget_miss` (`is_principal_or_self`) serve `GET`/`DELETE /memories/reflection` (the Pulse screen **What it got wrong**).\n- **Lessons** (`memory/lessons.py`): for a turn graded a miss the review may call `learn_lesson` once: one sentence this workspace wants done differently (a term and what it means, a preference about the content, a thing to do rather than promise, a specialist to consult), quoted from the person's own words (the quote must come from the miss turn or a later one, and the lesson must be what the quote says). It passes the working-style deny-list (`attunement.style._DENY_PATTERNS`: no link, handle, amount, markup, identifier, action verb, instruction talk, nudge to act unchecked, roster name) plus the lessons' own list (the verbs that move information: email, share, post, export, attach...; the words that widen a request to everyone or everything) without the about-the-writing requirement, may add at most two content words beyond the quote (`lesson_overreach`, so a real quote can't carry a different sentence in), and is re-checked on every render. Rows live in `chat_review_lessons` (text, quote, person, session, `shared` = learned in a channel or group thread, turn, `shown`, `fine_after`, `miss_after`, `retired_at`/`retired_reason`) with `chat_review_lesson_uses` (lesson, turn id, whose turn). A lesson reaches a turn by a keyword match (two shared content words between the lesson plus its quote and the message; no vector index for a list this short): the Executive's own turn gets the matching ones as a `<lessons>` block in the user turn (`build_lessons_block`, never a cached block; the header says the current request wins and nothing in it authorizes an action), and each specialist call gets the same lines under its `<failure_cases>` block (`router._lessons_for_call` → `lessons_for_query`). A lesson reaches its own person's turns; the principal's reach everyone's only when learned in a shared space (`shared`), so nothing said in someone's own chat is paraphrased into another person's turn. `build_lessons_block` counts each showing against the active turn id and the speaker; when the review later grades that turn, `note_outcome` adds to `fine_after` or `miss_after` only when the turn was the lesson's own person's (nobody else's chats can retire it), and a lesson shown 5 times with more misses than fine turns retires itself (`unhelpful`). At most 40 live lessons per person; their oldest retires to make room (`BEGIN IMMEDIATE`, so two reviews can't both skip it). Forget on the screen retires one by hand (`forgotten`); a retired lesson is listed as stopped, never erased.\n- **Replay: the workspace's own evals** (`memory/replay.py`). Nightly (the `chat_replay` scheduled action, `CHAT_REPLAY_TIME` 03:30 in the user's zone, seeded and chained like the reflection), the Executive runs its misses again with everything in force today and a judge says whether each would now go right. A case is a graded turn: a miss (its `wanted`), or a turn that went fine and got a thumbs up (`kept = 1`, held as long as a miss, at most `MAX_KEPT` 300 per person), which the replay protects so a lesson can't break what worked; a closed miss joins that pool. `due_cases` picks a miss the night a lesson is written for it (`WHY_LESSON`), when a lesson learned since the last night reaches it (`WHY_REACHED`), else once a week (`WHY_WEEKLY`), from the last 30 days only and at most `CHAT_REPLAY_MAX_CASES` (30) a night within `CHAT_REPLAY_MINUTES` (20); 20 protected cases (`WHY_PROTECT`, rotated by last replay) run only on a night a new lesson landed. `replay_case` runs `Executive.chat` on a session rebuilt from the recorded surface and speaker (`chat_review._rebuild_session`) with the saved conversation up to that turn (`chat_messages` before the reply's `message_id`), flagged `Session.replay`: reads run for real through every gate, and every tool a read-only turn is denied (`MCP_CLIENT_WITHHELD_TOOLS`, and gateway calls outside `MCP_CLIENT_MCP_TOOLS`) returns \"done\" and lands in `Session.replay_calls` instead (`faked_handlers` / `faked_call_tool`, wrapped outermost in the agent loop); scripts, Python jobs, `load_mcp_server`, Act as me's tools, `recall_history` and extension tools are not offered at all; nothing a replay does is kept (no extraction, open loops, style, notes, review or Honcho mirror, and `build_lessons_block(count=False)` counts no showing). The judge (`CHAT_REPLAY_JUDGE_MODEL`, else `EVAL_JUDGE_MODEL`, else Sonnet; `evals.judges.judge_message`) reads the original date, the person's words and the conversation before, what they wanted (or the reply they liked), today's reply and the recorded actions, and answers `{passed, time_bound, notes}`, intent and action rather than figures; an unreadable answer is a fail. The gate (`_settle`): a miss that passes is `closed` with `closed_at`; a time-bound one becomes `evidence` and is not replayed again; a lesson for a miss that still fails on `LESSON_FAILS` (2) judged replays after it was learned retires (`replay`); a protected case that fails reopens a closed miss and counts a strike against each new lesson of the same person that reached it (a teammate's turn never retires the principal's shared lessons), which retires at `PROTECT_FAILS` (2) such strikes, so one judged turn, or one message written to fail the judge, is not enough. A case that didn't run (an error, the `CASE_SECONDS` timeout) is recorded with `ran = 0` and settles nothing. The judge's input is scrubbed like outside content (`content_trust._scrub`) with the prompt's own tag names renamed inside it. Every replay is a `chat_review_replays` row (the reply and recorded calls; dropped with its turn when a miss or chat is forgotten or purged, `chat_review._prune_replays`) and a `chat_review` audit row (actor `chat_replay`); each night a `chat_review_replay_runs` row, written before the first case (so a second runner sees nothing new) and filled in after, which is also what \"new since the last night\" means. The nightly Executive carries the scheduler's MCP gateway, so the reads a miss needs run as they did. The Reflection screen's number, \"of the N things that went wrong in the last 30 days, M would go right today\" (`summary_for`, over the misses the caller sees), and each miss's last replay come from these columns on `chat_review_turns` (`replay_state`, `replayed_at`, `closed_at`, `replay_count`, `replay_notes`). Off with `CHAT_REPLAY_ENABLED=false` or when the review itself is off.\n\n## Decision ledger\n\n`openexecutive.memory.decision_ledger` keeps one `decision_instances` row per gated action — a meeting the Executive proposes to book, an Act as me reply card — with how it was resolved, so each class has a reliability record. Every status change is a compare-and-set. A tap with an outside effect (sending an email) claims the row first (`claim_for_execution`, proposed → executing), so of two taps only one acts, and finishes it as `approved_unchanged`, `approved_with_edit` or `failed`, or hands it back (`release_claim`). A row whose class acted on its own with nobody tapping — `gate_mode` `auto_execute`, as Act as me's **Handle it for me** replies are — finishes as `executed` instead, with no resolver, so a reliability read never counts it as an approval. A send whose result is unclear stays `executing` for a reconciler and is never retried. A row still waiting can have its payload changed only by compare-and-set (`update_open_payload`, on `proposed` and, when given, on the payload as it was read): that is how an Act as me reply card takes the person's edit, or records the draft made for it at Send.",
"mermaid": "flowchart TD\n Store[\"store_decision / store_initiative / store_advice\"]\n DB[\"episodic_memory.db<br/>decisions / initiatives<br/>advice_given / scheduled_actions\"]\n Fmt[\"format_for_prompt\"]\n Turn[\"User turn<br/>past_decisions block\"]\n Mirror[\"append_department_note\"]\n Peer[\"Department peer<br/>(Honcho)\"]\n Store --> DB\n DB --> Fmt\n Fmt --> Turn\n Store -->|\"dept set & not general\"| Mirror\n Mirror -->|\"fire-and-forget\"| Peer\n Tool[\"remember_fact / update_company_profile<br/>(principal, verified, quoted)\"]\n Facts[\"facts table<br/>active / superseded / retired\"]\n Every[\"STANDING FACTS block<br/>chat, specialists, briefs,<br/>alert review, workflows\"]\n Tool --> Facts\n Facts -->|\"render_facts_for_prompt\"| Every\n class Store entry\n class DB storage\n class Fmt compute\n class Turn hot\n class Peer external\n\n class Tool entry\n class Facts storage\n class Every hot",
- "generated_at": "2026-10-18T19:51:21Z"
+ "generated_at": "2026-10-19T09:30:00Z"
}
diff --git a/packages/core/openexecutive/architecture/prebuilt/schemas.json b/packages/core/openexecutive/architecture/prebuilt/schemas.json
index 24435778..398ae487 100644
--- a/packages/core/openexecutive/architecture/prebuilt/schemas.json
+++ b/packages/core/openexecutive/architecture/prebuilt/schemas.json
@@ -1,7 +1,7 @@
{
"section_id": "schemas",
"title": "Data Schemas",
- "markdown": "The shapes below are the load-bearing data structures: episodic SQLite tables (in `episodic_memory.db`) and the Pydantic models for departments and people.\n\n### Episodic tables\n\n| Table | Key columns |\n|---|---|\n| `decisions` | `id`, `timestamp`, `domain`, `summary`, `rationale`, `outcome`, `tags`, `department`, `session_id` |\n| `initiatives` | `id`, `title`, `status`, `created_at`, `updated_at`, `summary`, `department` |\n| `advice_given` | `id`, `timestamp`, `domain`, `query_summary`, `advice_summary`, `department`, `session_id` |\n| `facts` | `id`, `kind` (fact / correction / profile), `subject`, `subject_key`, `statement`, `previous_statement`, `source_quote`, `source_channel`, `session_id`, `turn_id`, `recorded_by_person_id`, `created_at`, `status` (active / superseded / retired), `superseded_by`, `retired_at`, `retired_reason` |\n| `scheduled_actions` | `id`, `created_at`, `run_at`, `channel`, `channel_ref`, `intent_text`, `status`, `attempts`, `kind`, `department`, `assigned_to_person_id`, `awaiting_response_since`, `scope_key`, `required_scope`, `created_by_person_id` |\n| `outbound_context` | `id`, `created_at`, `channel`, `channel_ref`, `recipient_person_id`, `outbound_text`, `originating_session_id`, `outbound_message_id`, `consumed_at`, `status` |\n| `history_reminders` | (`person_id`, `day`) PK, `sent_at` — the days a person was reminded of notes due (`memory.history_reminders`), older days pruned on write |\n| `session_drive_files` | (`session_id`, `person_id`, `file_id`) PK, `name`, `mime_type`, `link`, `summary` (first 600 chars of an opened file), `opened`, `found_by` (the search query), `first_seen_at`, `last_seen_at` — Drive files a conversation found or opened (`memory.drive_reads`) |\n| `session_drive_searches` | `id`, `session_id`, `person_id`, `query`, `result_count`, `searched_at` — every Drive search a conversation ran |\n| `saved_tools` | `name` (PK), `description`, `enabled`, `current_version`, `workflow_version` (the version workflows may run, NULL until the owner turns it on; never set for a Python tool), `kind` (`script` for `run_script`, `python` for a kept `run_python_job`; added with default `script`), `created_at`, `updated_at` — scripts and Python jobs the Executive saved to run again (`workflows.saved_tools`) |\n| `saved_tool_versions` | (`name`, `version`) PK, `description`, `script`, `tools` (JSON: the tools the script called when saved), `origin` (`chat` or `workflow:<name>/<step>`), `created_at` |\n| `saved_tool_runs` | `id`, `name`, `version`, `ok`, `calls`, `duration_ms`, `origin`, `at` — the newest 200 runs per tool |\n| `chat_messages` | `id`, `session_id`, `role`, `content`, `created_at`, `action_chips`, `stopped`, `sender_person_id`, `feedback`, `feedback_note`, `feedback_by_person_id`, `sources` (JSON `{sources: [{kind, title, url}], unavailable: [area]}` — what an assistant reply looked at and which areas it left out; NULL on older rows) |\n| `attunement_usage` | `day` (PK, UTC date), `calls` — the per-day ceiling on open-loop extraction model calls |\n| `attunement_profiles` | `person_id` (PK), `rules` (JSON: up to 8 `{text, basis, evidence}`; basis `feedback`, `stated`, `edited` or `conversation`), `locked`, `updated_at`, `updated_by`, `last_pass_at`, `pass_day`, `passes_today`, `last_message_id` — per-person working style plus pass pacing |\n| `chat_review_turns` | `id`, `session_id`, `person_id`, `surface` (JSON: the verified surface flags), `message` (the speaker's own words), `reply`, `calls` (JSON: tools run, results cut short), `created_at`, `reviewed_at` — a verified speaker's chat turns for the conversation review, kept 7 days |\n| `chat_review_days` | `day` (PK, UTC date), `runs` — the per-day ceiling on conversation reviews |\n| `brief_requests` | `id`, `kind` (`leave_out` / `raise`), `text`, `source_quote`, `person_id`, `session_id`, `created_at`, `expires_at`, `removed_at` — what the principal asked of their brief in chat |\n| `attunement_profile_history` | `id`, `person_id`, `created_at`, `rules`, `locked`, `updated_by` — every change to a working style |\n| `proactive_outcomes` | `id`, `created_at`, `person_id`, `source`, `ref`, `channel`, `channel_ref`, `outbound_context_id`, `outcome` (`replied` / `acted` / `ignored` / `void`, NULL while open), `resolved_at` — one row per proactive DM (Attunement outcome ledger) |\n| `delegation_settings` | `person_id` (PK), `enabled` (default 0), `updated_at`, `updated_by` — Act as me, per person; no row means off |\n| `history_notes` | `id`, `person_id`, `visibility` (`private`), `source` (`approved_reply`), `channel` (`email`), `conversation_key` (a hash of the channel and thread, never the thread id), `counterpart`, `subject`, `kind` (`promised` / `agreed` / `declined` / `answered` / `asked` / `shared`), `summary`, `quote` (the person's own words), `due_date`, `trust`, `occurred_at`, `created_at`, `expires_at` (NULL: until forgotten), `pinned`, `correction`, `corrected_at`, `kept_from` (when the retention clock started: NULL means `occurred_at`; an unpin restarts it) — Always in the loop, one row per note |\n| `history_settings` | `id` (1), `retention_days` (NULL: until forgotten; no row means 90), `updated_at`, `updated_by` — the company retention |\n| `history_person_settings` | `person_id` (PK), `reply_notes` (default 0), `retention_days` (NULL: the company's), `updated_at`, `updated_by` |\n| `history_excluded` | `person_id`, `conversation_key` (PK together), `created_at` — conversations a person asked not to remember |\n| `history_chat_passes` | `person_id`, `day` (PK together, UTC `YYYY-MM-DD`), `passes` — note passes run on a person's chat messages that day, against the daily cap; older days pruned on write |\n| `delegation_voice` | `person_id` (PK), `profile` (JSON: `greetings` per audience, `sign_off`, `signature`, `length`, `formality`, up to 8 `habits`, up to 6 `avoid`, up to 3 `exemplars`), `locked`, `learned_at`, `sample_count`, `updated_at`, `updated_by` — \"How I write\" |\n| `delegation_voice_history` | `id`, `person_id`, `created_at`, `profile`, `locked`, `updated_by` — every change to a writing profile |\n| `delegation_drafts` | `id`, `person_id`, `source` (`chat` \\| `inbox`), `thread_id`, `draft_id`, `message_id`, `sent_message_id`, `created_at`, `gone_at` (a chat draft found missing from their mailbox: sent or deleted there) — one row of ids per draft Act as me saved in someone's Gmail (no address, subject or text): the daily limit counts it, and \"How I write\" skips a chat draft's thread and a sent draft's message |\n| `delegation_inbox_watch` | `person_id` (PK), `enabled`, `watch_since` (reset on every off→on), `last_poll_at`, `status`, `backoff_until`, `failures`, `mailbox_drafts` (also save each reply in their Drafts; default 0, the reply lives on its card alone), `updated_at`, `updated_by` — **Draft replies to my inbox**, per person; no row means off |\n| `delegation_inbox_messages` | `id`, `person_id`, `message_id`, `thread_id`, `received_at`, `sender_key` (a hash of the address, never the address), `relation`, `outcome` (`processing`, `retry` — left for a later scan, `skipped`, `not_needed`, `deferred`, `failed`, `drafted`, `sent`, `dismissed`, `closed`, `expired`), `reason`, `classified`, `attempts`, `draft_id`, `decision_id`, `flags` (JSON), `created_at`, `updated_at`; `UNIQUE(person_id, message_id)` — the inbox watcher's cursor: what happened to each message it looked at |\n| `delegation_handle_it` | `person_id` (PK), `enabled`, `mode` (`careful`, `balanced` or `bold`), `levels` (the per-kind setting `mode` replaced, kept for older rows), `updated_at`, `updated_by` — **Handle it for me**, per person; no row means off. A `training` mode from before per-setting training moves to `balanced` with Replies and Follow-ups in training |\n| `delegation_training` | `person_id`, `setting` (`replies`, `follow_ups`, `actions` or `drafts`), `enabled`, `updated_at`, `updated_by`; primary key `(person_id, setting)` — Act as me settings in training, per person; no row means not in training |\n| `delegation_disclosure` | `person_id` (PK), `handle_it`, `approved_sends` (each NULL = as the install's `AI_DISCLOSURE_HANDLE_IT` / `AI_DISCLOSURE_APPROVED_SENDS`), `updated_at`, `updated_by` — the AI line on replies sent as that person; no row means the install's defaults |\n| `delegation_handled` | `id`, `person_id`, `thread_id`, `decision_id`, `sent_message_id`, `sent_at`; index on `(person_id, sent_at)` — one row per reply or follow-up Handle it for me sent on its own, read for its one-per-thread-a-day and daily limits |\n\n| `dynamic_workflows` | `name` (PK), `definition` (JSON of `DynamicWorkflowDef`), `is_active`, `created_at`, `updated_at`, `owner_person_id` (creator; set on insert only, kept out of the definition JSON) |\n| `workflow_approved_targets` | (`workflow_name`, `value`) PK, `key`, `approved_at`, `run_id` — targets a workflow's tool steps may write to without asking again; cleared when the workflow is deleted |\n| `executive_control` | `id` (PK, always 1), `paused`, `paused_at`, `paused_by`, `reason`, `updated_at` — the operator pause switch (`scheduler.pause`); operator-level, so client-slot switches carry it across |\n| `app_migrations` | `name` (PK), `applied_at` — one-shot data migrations (sweeps that must run exactly once per DB); schema DDL stays idempotent and is not recorded here |\n\n`department` and `session_id` are additive columns (default `''`); `session_id` scopes per-thread recall. `scheduled_actions.status` ∈ pending / running / done / failed / cancelled, and `scheduled_actions.kind` includes `dynamic_workflow` (a cadence-fired user-created workflow run) and `open_loop` (an Attunement open loop: `assigned_to_person_id` is the owner, `awaiting_response_since` the due time — cleared when the loop closes — and `scope_key` `loop:{owner}:{hash}`, unique among open loops via the partial index `idx_scheduled_open_loop_scope`). `chat_messages.sender_person_id` is the resolved rostered sender of a user message (never the session owner's principal fallback; NULL on legacy rows and for unrostered senders); `feedback` is `up` / `down` on an assistant reply. `dynamic_workflows` stores user-created (dynamic) workflow definitions interpreted by the generic `DynamicWorkflow` engine; the JSON `definition` holds free-text input fields and an ordered step list (specialist / approval_gate / synthesis) plus an optional cadence.\n\n### Legacy tables (talent / staff onboarding)\n\nThe talent (executive-search) and staff-onboarding features were removed. Their tables —\n`engagements`, `candidates`, `offers`, `onboarding_templates`, `onboarding_plans`,\n`onboarding_tasks` — are **not dropped**: no code creates, reads or writes them any more,\nbut rows survive on upgraded installs. `clients.slots` still wipes them when a blank client\nslot is activated (existence-guarded, a no-op on fresh installs) so a slot can never inherit\na previous client's candidate data.\n\n### Department / Goal / ChecklistItem\n\n| Model | Fields |\n|---|---|\n| `DepartmentConfig` | `slug`, `title`, `specialist_key`, `charter`, `authority_level`, `head_person_id`, `head_persona_slug`, `cadences`, `slack_channel_id`, `discord_channel_id`, `telegram_chat_id` |\n| `Goal` | `id`, `department_slug`, `period_type`, `period_value`, `key_result`, `target`, `current`, `status`, `created_at`, `updated_at`, `last_reviewed_at` |\n| `DepartmentState` | `config`, `goals`, `headcount`, `budget_usd`, `member_person_ids`, `updated_at` |\n\n`authority_level` ∈ `auto_execute` / `propose_only` / `escalate`; `Goal.status` ∈ `on_track` / `at_risk` / `off_track`.\n\n### Person\n\n| Field group | Fields |\n|---|---|\n| Identity | `id`, `full_name`, `role`, `is_principal`, `kind`, `department_slugs` |\n| Contact | `email`, `email_aliases`, `slack_user_id`, `telegram_chat_id`, `discord_user_id`, `preferred_channel`, `last_channel` / `last_channel_at` (the chat app they last talked in, and when) |\n| Routing | `availability`, `authority_scope`, `response_sla_hours`, `on_leave_until`, `reports_to_person_id` |\n| Lifecycle | `archived`, `created_at`, `updated_at` |\n\nExactly one `Person` should have `is_principal=True` — the fallback approver when no delegated person matches.\n\n`kind` is `team` (the default) or `contact` — someone outside the team, such as a client or contractor. It is an additive column, `kind TEXT NOT NULL DEFAULT 'team'`, added by the same `PRAGMA table_info`-guarded migration as `discord_user_id`, so every existing row is a team member. The principal is always `team`: the store refuses to write a principal contact (`PrincipalContactError`), and `initialize_db` repairs a hand-edited one on boot. A stored value the code does not know reads as `contact`. Every roster read in `people.store` and `people.registry` returns team members only unless it passes `include_contacts=True` (see Org).\n\n`email` is the one address a person signs in with; `email_aliases` (read from the `person_emails` table, up to 10) are other addresses they write from — they match inbound mail and may be emailed, but never sign in (see Org).\n\n### People-side tables\n\nThese live next to `people` (created by `people.store.initialize_db`, which also runs `people.roster_requests.initialize_tables`):\n\n| Table | Key columns |\n|---|---|\n| `person_emails` | `id`, `person_id` (FK → `people`, `ON DELETE CASCADE`), `email`, `email_norm` (trimmed + lowercased, **UNIQUE** across the roster), `source` (`manual` / `chat_tool` / `roster_request`), `roster_request_id`, `created_at` — a person's aliases; deleted when they are archived |\n| `roster_requests` | `id`, `channel` (`email` / `slack` / `discord` / `telegram`), `channel_ref` (the address or chat id), `display_name` (sanitised, unverified), `profile_email`, `on_company_domain`, `suggested_kind`, `suggested_person_id`, `status` (`pending` / `resolving` / `approved` / `linked` / `declined` / `expired` / `superseded`), `resolved_person_id`, `resolved_kind`, `resolved_via` (`web` / `slack` / `discord` / `telegram` / `email` / `people_page`), `resolved_at`, `token_hash` (the email answer token, hashed; cleared on resolve), `confirm_message_id`, `notified_at`, `notified_channel`, `ack_sent_at`, `alert_id`, `message_count`, `first_seen_at`, `last_seen_at`, `expires_at` — one pending row per `(channel, channel_ref)` (partial unique index) |\n| `roster_request_messages` | `id`, `request_id` (FK, cascade), `external_id` (unique per request, so a redelivery is held once), `payload_json` (what the adapter needs to replay it), `preview`, `received_at`, `replay_status` (`held` / `replaying` / `replayed` / `dropped` / `failed` / `unavailable`), `replayed_at` — at most 10 per request; `payload_json` and `preview` are blanked once a message is replayed or dropped |\n| `roster_ack_log` | `id`, `channel`, `channel_ref`, `sent_at` — one row per acknowledgement sent to a new sender, for the per-sender window and the daily cap |\n\n**Take the lead tables** (`orchestrator.take_the_lead`, created on first use, per company in `clients.slots` and `reset_all_state`): `take_the_lead` (`scope` PK: `executive` or `person:<id>`, `enabled`, `training` (added in place on older databases), `updated_at`, `updated_by`; each kind's Ask first is a `decision_class_state` row for `take_the_lead_action:<kind>`); `take_the_lead_rules` (`id`, `scope`: `company` or `person:<id>`, `kind` person|domain|words|amount, `value`, `created_by`, `created_at`); `take_the_lead_log` (`id`, `at`, `scope`, `source` reflection|research|scheduled, `tool`, `summary`, `status` done|waiting|approved|declined|failed, `why`, `decision_id`). A held action is a `decision_instances` row of class `take_the_lead_action` whose payload carries the tool, its input, whether it is an MCP tool, the gate kind or rule, the reason and the summary. `take_the_lead_allowed` (`id`, `key` unique: `<feature>|<action>|<who>`, `label`, `feature`, `example` (JSON of the edited fields, or empty), `uses`, `last_used_at`, `created_by`, `created_at`, `decision_id`, `removed_at`: set by Remove, so only approvals after it count toward a new suggestion, `person_id`: whose it is for a feature that learns per person, Act as me's `act_as_me|person:<id>|<reply|follow_up|message|invite|style>|<who>`, NULL for Take the lead; added in place on older databases): what it may do on its own in training, at most `ALLOWED_MAX` (200) per feature and person.\n\n**`telegram_chats`** (episodic DB, `integrations/telegram_chats.py`) — the Telegram chats the bot has seen, because Telegram cannot list them: `chat_id` (primary key), `chat_type` (`private`, `group` or `supergroup`), `title` (a group's title or a person's name), `username`, `first_seen_at`, `last_seen_at`. The webhook upserts a row per update only when `TELEGRAM_WEBHOOK_SECRET` checked out, drops a group that moved to a supergroup id or that removed the bot, and keeps the 500 most recently seen. Private chats are people picker options and groups are room options (`GET /chat-directory/*`). Reads never create it. A blank client slot wipes it.\n",
+ "markdown": "The shapes below are the load-bearing data structures: episodic SQLite tables (in `episodic_memory.db`) and the Pydantic models for departments and people.\n\n### Episodic tables\n\n| Table | Key columns |\n|---|---|\n| `decisions` | `id`, `timestamp`, `domain`, `summary`, `rationale`, `outcome`, `tags`, `department`, `session_id` |\n| `initiatives` | `id`, `title`, `status`, `created_at`, `updated_at`, `summary`, `department` |\n| `advice_given` | `id`, `timestamp`, `domain`, `query_summary`, `advice_summary`, `department`, `session_id` |\n| `facts` | `id`, `kind` (fact / correction / profile), `subject`, `subject_key`, `statement`, `previous_statement`, `source_quote`, `source_channel`, `session_id`, `turn_id`, `recorded_by_person_id`, `created_at`, `status` (active / superseded / retired), `superseded_by`, `retired_at`, `retired_reason` |\n| `scheduled_actions` | `id`, `created_at`, `run_at`, `channel`, `channel_ref`, `intent_text`, `status`, `attempts`, `kind`, `department`, `assigned_to_person_id`, `awaiting_response_since`, `scope_key`, `required_scope`, `created_by_person_id` |\n| `outbound_context` | `id`, `created_at`, `channel`, `channel_ref`, `recipient_person_id`, `outbound_text`, `originating_session_id`, `outbound_message_id`, `consumed_at`, `status` |\n| `history_reminders` | (`person_id`, `day`) PK, `sent_at` — the days a person was reminded of notes due (`memory.history_reminders`), older days pruned on write |\n| `session_drive_files` | (`session_id`, `person_id`, `file_id`) PK, `name`, `mime_type`, `link`, `summary` (first 600 chars of an opened file), `opened`, `found_by` (the search query), `first_seen_at`, `last_seen_at` — Drive files a conversation found or opened (`memory.drive_reads`) |\n| `session_drive_searches` | `id`, `session_id`, `person_id`, `query`, `result_count`, `searched_at` — every Drive search a conversation ran |\n| `saved_tools` | `name` (PK), `description`, `enabled`, `current_version`, `workflow_version` (the version workflows may run, NULL until the owner turns it on; never set for a Python tool), `kind` (`script` for `run_script`, `python` for a kept `run_python_job`; added with default `script`), `created_at`, `updated_at` — scripts and Python jobs the Executive saved to run again (`workflows.saved_tools`) |\n| `saved_tool_versions` | (`name`, `version`) PK, `description`, `script`, `tools` (JSON: the tools the script called when saved), `origin` (`chat` or `workflow:<name>/<step>`), `created_at` |\n| `saved_tool_runs` | `id`, `name`, `version`, `ok`, `calls`, `duration_ms`, `origin`, `at` — the newest 200 runs per tool |\n| `chat_messages` | `id`, `session_id`, `role`, `content`, `created_at`, `action_chips`, `stopped`, `sender_person_id`, `feedback`, `feedback_note`, `feedback_by_person_id`, `sources` (JSON `{sources: [{kind, title, url}], unavailable: [area]}` — what an assistant reply looked at and which areas it left out; NULL on older rows) |\n| `attunement_usage` | `day` (PK, UTC date), `calls` — the per-day ceiling on open-loop extraction model calls |\n| `attunement_profiles` | `person_id` (PK), `rules` (JSON: up to 8 `{text, basis, evidence}`; basis `feedback`, `stated`, `edited` or `conversation`), `locked`, `updated_at`, `updated_by`, `last_pass_at`, `pass_day`, `passes_today`, `last_message_id` — per-person working style plus pass pacing |\n| `chat_review_turns` | `id`, `session_id`, `person_id`, `surface` (JSON: the verified surface flags), `message` (the speaker's own words), `reply`, `calls` (JSON: tools run, results cut short), `created_at`, `reviewed_at`, `mail` (1 when the turn read mail or its chat once did: tool results not kept, rows the person's own) — a verified speaker's chat turns for the conversation review, kept 7 days |\n| `chat_review_days` | `day` (PK, UTC date), `runs` — the per-day ceiling on conversation reviews |\n| `brief_requests` | `id`, `kind` (`leave_out` / `raise`), `text`, `source_quote`, `person_id`, `session_id`, `created_at`, `expires_at`, `removed_at` — what the principal asked of their brief in chat |\n| `attunement_profile_history` | `id`, `person_id`, `created_at`, `rules`, `locked`, `updated_by` — every change to a working style |\n| `proactive_outcomes` | `id`, `created_at`, `person_id`, `source`, `ref`, `channel`, `channel_ref`, `outbound_context_id`, `outcome` (`replied` / `acted` / `ignored` / `void`, NULL while open), `resolved_at` — one row per proactive DM (Attunement outcome ledger) |\n| `delegation_settings` | `person_id` (PK), `enabled` (default 0), `updated_at`, `updated_by` — Act as me, per person; no row means off |\n| `history_notes` | `id`, `person_id`, `visibility` (`private`), `source` (`approved_reply`), `channel` (`email`), `conversation_key` (a hash of the channel and thread, never the thread id), `counterpart`, `subject`, `kind` (`promised` / `agreed` / `declined` / `answered` / `asked` / `shared`), `summary`, `quote` (the person's own words), `due_date`, `trust`, `occurred_at`, `created_at`, `expires_at` (NULL: until forgotten), `pinned`, `correction`, `corrected_at`, `kept_from` (when the retention clock started: NULL means `occurred_at`; an unpin restarts it) — Always in the loop, one row per note |\n| `history_settings` | `id` (1), `retention_days` (NULL: until forgotten; no row means 90), `updated_at`, `updated_by` — the company retention |\n| `history_person_settings` | `person_id` (PK), `reply_notes` (default 0), `retention_days` (NULL: the company's), `updated_at`, `updated_by` |\n| `history_excluded` | `person_id`, `conversation_key` (PK together), `created_at` — conversations a person asked not to remember |\n| `history_chat_passes` | `person_id`, `day` (PK together, UTC `YYYY-MM-DD`), `passes` — note passes run on a person's chat messages that day, against the daily cap; older days pruned on write |\n| `delegation_voice` | `person_id` (PK), `profile` (JSON: `greetings` per audience, `sign_off`, `signature`, `length`, `formality`, up to 8 `habits`, up to 6 `avoid`, up to 3 `exemplars`), `locked`, `learned_at`, `sample_count`, `updated_at`, `updated_by` — \"How I write\" |\n| `delegation_voice_history` | `id`, `person_id`, `created_at`, `profile`, `locked`, `updated_by` — every change to a writing profile |\n| `delegation_drafts` | `id`, `person_id`, `source` (`chat` \\| `inbox`), `thread_id`, `draft_id`, `message_id`, `sent_message_id`, `created_at`, `gone_at` (a chat draft found missing from their mailbox: sent or deleted there) — one row of ids per draft Act as me saved in someone's Gmail (no address, subject or text): the daily limit counts it, and \"How I write\" skips a chat draft's thread and a sent draft's message |\n| `delegation_inbox_watch` | `person_id` (PK), `enabled`, `watch_since` (reset on every off→on), `last_poll_at`, `status`, `backoff_until`, `failures`, `mailbox_drafts` (also save each reply in their Drafts; default 0, the reply lives on its card alone), `updated_at`, `updated_by` — **Draft replies to my inbox**, per person; no row means off |\n| `delegation_inbox_messages` | `id`, `person_id`, `message_id`, `thread_id`, `received_at`, `sender_key` (a hash of the address, never the address), `relation`, `outcome` (`processing`, `retry` — left for a later scan, `skipped`, `not_needed`, `deferred`, `failed`, `drafted`, `sent`, `dismissed`, `closed`, `expired`), `reason`, `classified`, `attempts`, `draft_id`, `decision_id`, `flags` (JSON), `created_at`, `updated_at`; `UNIQUE(person_id, message_id)` — the inbox watcher's cursor: what happened to each message it looked at |\n| `delegation_handle_it` | `person_id` (PK), `enabled`, `mode` (`careful`, `balanced` or `bold`), `levels` (the per-kind setting `mode` replaced, kept for older rows), `updated_at`, `updated_by` — **Handle it for me**, per person; no row means off. A `training` mode from before per-setting training moves to `balanced` with Replies and Follow-ups in training |\n| `delegation_training` | `person_id`, `setting` (`replies`, `follow_ups`, `actions` or `drafts`), `enabled`, `updated_at`, `updated_by`; primary key `(person_id, setting)` — Act as me settings in training, per person; no row means not in training |\n| `delegation_disclosure` | `person_id` (PK), `handle_it`, `approved_sends` (each NULL = as the install's `AI_DISCLOSURE_HANDLE_IT` / `AI_DISCLOSURE_APPROVED_SENDS`), `updated_at`, `updated_by` — the AI line on replies sent as that person; no row means the install's defaults |\n| `delegation_handled` | `id`, `person_id`, `thread_id`, `decision_id`, `sent_message_id`, `sent_at`; index on `(person_id, sent_at)` — one row per reply or follow-up Handle it for me sent on its own, read for its one-per-thread-a-day and daily limits |\n\n| `dynamic_workflows` | `name` (PK), `definition` (JSON of `DynamicWorkflowDef`), `is_active`, `created_at`, `updated_at`, `owner_person_id` (creator; set on insert only, kept out of the definition JSON) |\n| `workflow_approved_targets` | (`workflow_name`, `value`) PK, `key`, `approved_at`, `run_id` — targets a workflow's tool steps may write to without asking again; cleared when the workflow is deleted |\n| `executive_control` | `id` (PK, always 1), `paused`, `paused_at`, `paused_by`, `reason`, `updated_at` — the operator pause switch (`scheduler.pause`); operator-level, so client-slot switches carry it across |\n| `app_migrations` | `name` (PK), `applied_at` — one-shot data migrations (sweeps that must run exactly once per DB); schema DDL stays idempotent and is not recorded here |\n\n`department` and `session_id` are additive columns (default `''`); `session_id` scopes per-thread recall. `scheduled_actions.status` ∈ pending / running / done / failed / cancelled, and `scheduled_actions.kind` includes `dynamic_workflow` (a cadence-fired user-created workflow run) and `open_loop` (an Attunement open loop: `assigned_to_person_id` is the owner, `awaiting_response_since` the due time — cleared when the loop closes — and `scope_key` `loop:{owner}:{hash}`, unique among open loops via the partial index `idx_scheduled_open_loop_scope`). `chat_messages.sender_person_id` is the resolved rostered sender of a user message (never the session owner's principal fallback; NULL on legacy rows and for unrostered senders); `feedback` is `up` / `down` on an assistant reply. `dynamic_workflows` stores user-created (dynamic) workflow definitions interpreted by the generic `DynamicWorkflow` engine; the JSON `definition` holds free-text input fields and an ordered step list (specialist / approval_gate / synthesis) plus an optional cadence.\n\n### Legacy tables (talent / staff onboarding)\n\nThe talent (executive-search) and staff-onboarding features were removed. Their tables —\n`engagements`, `candidates`, `offers`, `onboarding_templates`, `onboarding_plans`,\n`onboarding_tasks` — are **not dropped**: no code creates, reads or writes them any more,\nbut rows survive on upgraded installs. `clients.slots` still wipes them when a blank client\nslot is activated (existence-guarded, a no-op on fresh installs) so a slot can never inherit\na previous client's candidate data.\n\n### Department / Goal / ChecklistItem\n\n| Model | Fields |\n|---|---|\n| `DepartmentConfig` | `slug`, `title`, `specialist_key`, `charter`, `authority_level`, `head_person_id`, `head_persona_slug`, `cadences`, `slack_channel_id`, `discord_channel_id`, `telegram_chat_id` |\n| `Goal` | `id`, `department_slug`, `period_type`, `period_value`, `key_result`, `target`, `current`, `status`, `created_at`, `updated_at`, `last_reviewed_at` |\n| `DepartmentState` | `config`, `goals`, `headcount`, `budget_usd`, `member_person_ids`, `updated_at` |\n\n`authority_level` ∈ `auto_execute` / `propose_only` / `escalate`; `Goal.status` ∈ `on_track` / `at_risk` / `off_track`.\n\n### Person\n\n| Field group | Fields |\n|---|---|\n| Identity | `id`, `full_name`, `role`, `is_principal`, `kind`, `department_slugs` |\n| Contact | `email`, `email_aliases`, `slack_user_id`, `telegram_chat_id`, `discord_user_id`, `preferred_channel`, `last_channel` / `last_channel_at` (the chat app they last talked in, and when) |\n| Routing | `availability`, `authority_scope`, `response_sla_hours`, `on_leave_until`, `reports_to_person_id` |\n| Lifecycle | `archived`, `created_at`, `updated_at` |\n\nExactly one `Person` should have `is_principal=True` — the fallback approver when no delegated person matches.\n\n`kind` is `team` (the default) or `contact` — someone outside the team, such as a client or contractor. It is an additive column, `kind TEXT NOT NULL DEFAULT 'team'`, added by the same `PRAGMA table_info`-guarded migration as `discord_user_id`, so every existing row is a team member. The principal is always `team`: the store refuses to write a principal contact (`PrincipalContactError`), and `initialize_db` repairs a hand-edited one on boot. A stored value the code does not know reads as `contact`. Every roster read in `people.store` and `people.registry` returns team members only unless it passes `include_contacts=True` (see Org).\n\n`email` is the one address a person signs in with; `email_aliases` (read from the `person_emails` table, up to 10) are other addresses they write from — they match inbound mail and may be emailed, but never sign in (see Org).\n\n### People-side tables\n\nThese live next to `people` (created by `people.store.initialize_db`, which also runs `people.roster_requests.initialize_tables`):\n\n| Table | Key columns |\n|---|---|\n| `person_emails` | `id`, `person_id` (FK → `people`, `ON DELETE CASCADE`), `email`, `email_norm` (trimmed + lowercased, **UNIQUE** across the roster), `source` (`manual` / `chat_tool` / `roster_request`), `roster_request_id`, `created_at` — a person's aliases; deleted when they are archived |\n| `roster_requests` | `id`, `channel` (`email` / `slack` / `discord` / `telegram`), `channel_ref` (the address or chat id), `display_name` (sanitised, unverified), `profile_email`, `on_company_domain`, `suggested_kind`, `suggested_person_id`, `status` (`pending` / `resolving` / `approved` / `linked` / `declined` / `expired` / `superseded`), `resolved_person_id`, `resolved_kind`, `resolved_via` (`web` / `slack` / `discord` / `telegram` / `email` / `people_page`), `resolved_at`, `token_hash` (the email answer token, hashed; cleared on resolve), `confirm_message_id`, `notified_at`, `notified_channel`, `ack_sent_at`, `alert_id`, `message_count`, `first_seen_at`, `last_seen_at`, `expires_at` — one pending row per `(channel, channel_ref)` (partial unique index) |\n| `roster_request_messages` | `id`, `request_id` (FK, cascade), `external_id` (unique per request, so a redelivery is held once), `payload_json` (what the adapter needs to replay it), `preview`, `received_at`, `replay_status` (`held` / `replaying` / `replayed` / `dropped` / `failed` / `unavailable`), `replayed_at` — at most 10 per request; `payload_json` and `preview` are blanked once a message is replayed or dropped |\n| `roster_ack_log` | `id`, `channel`, `channel_ref`, `sent_at` — one row per acknowledgement sent to a new sender, for the per-sender window and the daily cap |\n\n**Take the lead tables** (`orchestrator.take_the_lead`, created on first use, per company in `clients.slots` and `reset_all_state`): `take_the_lead` (`scope` PK: `executive` or `person:<id>`, `enabled`, `training` (added in place on older databases), `updated_at`, `updated_by`; each kind's Ask first is a `decision_class_state` row for `take_the_lead_action:<kind>`); `take_the_lead_rules` (`id`, `scope`: `company` or `person:<id>`, `kind` person|domain|words|amount, `value`, `created_by`, `created_at`); `take_the_lead_log` (`id`, `at`, `scope`, `source` reflection|research|scheduled, `tool`, `summary`, `status` done|waiting|approved|declined|failed, `why`, `decision_id`). A held action is a `decision_instances` row of class `take_the_lead_action` whose payload carries the tool, its input, whether it is an MCP tool, the gate kind or rule, the reason and the summary. `take_the_lead_allowed` (`id`, `key` unique: `<feature>|<action>|<who>`, `label`, `feature`, `example` (JSON of the edited fields, or empty), `uses`, `last_used_at`, `created_by`, `created_at`, `decision_id`, `removed_at`: set by Remove, so only approvals after it count toward a new suggestion, `person_id`: whose it is for a feature that learns per person, Act as me's `act_as_me|person:<id>|<reply|follow_up|message|invite|style>|<who>`, NULL for Take the lead; added in place on older databases): what it may do on its own in training, at most `ALLOWED_MAX` (200) per feature and person.\n\n**`telegram_chats`** (episodic DB, `integrations/telegram_chats.py`) — the Telegram chats the bot has seen, because Telegram cannot list them: `chat_id` (primary key), `chat_type` (`private`, `group` or `supergroup`), `title` (a group's title or a person's name), `username`, `first_seen_at`, `last_seen_at`. The webhook upserts a row per update only when `TELEGRAM_WEBHOOK_SECRET` checked out, drops a group that moved to a supergroup id or that removed the bot, and keeps the 500 most recently seen. Private chats are people picker options and groups are room options (`GET /chat-directory/*`). Reads never create it. A blank client slot wipes it.\n",
"mermaid": null,
- "generated_at": "2026-10-18T18:00:00+00:00"
+ "generated_at": "2026-10-19T09:30:00Z"
}
diff --git a/packages/core/openexecutive/memory/chat_review.py b/packages/core/openexecutive/memory/chat_review.py
index 58ea41e1..50576339 100644
--- a/packages/core/openexecutive/memory/chat_review.py
+++ b/packages/core/openexecutive/memory/chat_review.py
@@ -10,8 +10,11 @@ kept.
that confirms it is them, or a rostered teammate on their own signed-in web
chat, Slack or Discord) is recorded here: their own words, the reply, and the
tools the turn ran. Nothing else is: an email, an unattended run, a turn
-private to the principal, one that touched their own mailbox, or a message
-with an attachment. In team mode that covers the principal and every teammate.
+private to the principal, or a message with an attachment. In team mode that
+covers the principal and every teammate. A chat that read the person's own
+mailbox (Act as me) is kept for their own review only: its misses and lessons
+are shown to them alone, it keeps no fact, and its tools are kept by name
+with no result text (``record_turn``'s ``mail``).
**When.** ``CHAT_REVIEW_QUIET_MINUTES`` (30) after the last recorded turn of a
conversation, through a ``chat_review`` scheduled action. Only the turns not
@@ -36,13 +39,15 @@ permission to act. What it can't fix goes into the next brief as one line
**Grading (looking back at how it went).** Before the fix loop, the same
pass grades each turn it reads, from the person's own words, the reply and
-the signals the product recorded: a 👍 or 👎 on the reply (``chat_messages``),
+the signals the product recorded: a 👍 or 👎 on the reply (``chat_messages``,
+or typed as the next message in a chat app),
a reply they stopped, a turn they took back to ask again
(``session_rewound``), a claim the reply made that no tool backed
(``claim_check``), a tool that failed. One forced-tool call on the review
model says, per turn, ``fine``, ``miss`` or ``unclear``; for a miss, what
the person wanted instead, backed by a quote of four of their own words from
-that turn or the next ones (code-checked, or the turn is ``unclear``), and
+that turn or the next ones or by a signal other than a 👍 (code-checked, or
+the turn is ``unclear``), and
whether the miss was about this company (a term, a fact, a preference, a
specialist) or the product (a tool that failed, a capability it lacks).
Misses are kept ``MISS_KEEP_DAYS`` (90) instead of 7, and each person's weekly
@@ -169,6 +174,8 @@ def _connect(db_path: Path | None) -> sqlite3.Connection:
("closed_at", "TEXT"),
("replay_count", "INTEGER NOT NULL DEFAULT 0"),
("replay_notes", "TEXT"),
+ # The turn read mail, or its chat once did: its person's alone.
+ ("mail", "INTEGER NOT NULL DEFAULT 0"),
):
if col not in present:
try:
@@ -237,11 +244,15 @@ def _verified_person(session: Any, person_id: int | None) -> Any:
return person if teammate is not None and teammate.id == person.id else None
-def _calls_json(calls: list[tuple[str, str]]) -> str:
- return json.dumps([
- {"tool": name, "result": " ".join(str(result).split())[:CALL_RESULT_MAX]}
- for name, result in calls[:CALLS_MAX]
- ])
+def _calls_json(calls: list[tuple[str, str]], *, private: bool = False) -> str:
+ """The turn's tools and the start of each result. ``private`` (a chat
+ that read mail) keeps only whether a tool failed, never its output."""
+ def result(text: str) -> str:
+ if private:
+ return "error" if _FAILED_RE.search(str(text)) else ""
+ return " ".join(str(text).split())[:CALL_RESULT_MAX]
+
+ return json.dumps([{"tool": name, "result": result(text)} for name, text in calls[:CALLS_MAX]])
def record_turn(
@@ -251,12 +262,21 @@ def record_turn(
session: Any,
person_id: int | None,
calls: list[tuple[str, str]] | None = None,
+ mail: bool = False,
now: datetime | None = None,
db_path: Path | None = None,
) -> int | None:
"""Keep this turn for the review and schedule one for the conversation.
Returns the row id, or None when the turn isn't one to review. Never
- raises."""
+ raises.
+
+ ``mail``: the turn read or drafted in the speaker's own mailbox. Such a
+ turn, and every turn of a conversation that once did
+ (``session_store.mark_mail_private``), is kept for that person's own
+ review only: the Reflection screen shows it to them alone (the chat
+ routes' rule), a lesson from it never reaches anyone else, the review
+ keeps no fact from it, and its tools are kept by name, with no result
+ text, since the results are other people's mail."""
try:
if not enabled() or not reply.strip():
return None
@@ -268,10 +288,7 @@ def record_turn(
person = _verified_person(session, person_id)
if person is None or person.id is None:
return None
- if _mail_private(session.session_id, db_path):
- # A conversation that read its owner's own mail stays theirs
- # alone: nothing from it is kept for the review.
- return None
+ private = mail or _mail_private(session.session_id, db_path)
current = now or _now()
surface = {f: getattr(session, f, None) for f in _SURFACE_FIELDS}
from openexecutive.audit.context import get_active_turn_id
@@ -280,10 +297,11 @@ def record_turn(
try:
cur = conn.execute(
f"INSERT INTO {TURNS_TABLE} (session_id, person_id, surface, message, reply, " # noqa: S608
- "calls, created_at, turn_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+ "calls, created_at, turn_id, mail) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
(session.session_id, int(person.id), json.dumps(surface),
words.strip()[:MESSAGE_MAX], reply.strip()[:REPLY_MAX],
- _calls_json(calls or []), current.isoformat(), get_active_turn_id()),
+ _calls_json(calls or [], private=private), current.isoformat(), get_active_turn_id(),
+ 1 if private else 0),
)
# A miss is kept longer than a turn that went fine, so the
# Reflection screen can show what went wrong this quarter; so is
@@ -351,6 +369,16 @@ def _mail_private(session_id: str, db_path: Path | None) -> bool:
return True
+def mail_private_turns(turns: list[sqlite3.Row], *, db_path: Path | None = None) -> bool:
+ """Whether these turns are their person's alone: one read mail when it
+ was kept (``mail``), or their chat has read mail since. Then everything
+ the review and the replay write about them (audit rows included) is
+ that person's own (``audit.context.rows_for_person``)."""
+ if any(int(r["mail"] or 0) for r in turns):
+ return True
+ return any(_mail_private(str(sid), db_path) for sid in {str(r["session_id"]) for r in turns})
+
+
def forget_session(session_id: str, *, db_path: Path | None = None) -> None:
"""Drop everything kept from one chat (``session_store.delete_session``
calls this): the turns, their grades and the misses. The weekly counts
@@ -662,6 +690,15 @@ def _chat_tools() -> tuple[dict[str, dict[str, Any]], dict[str, Callable[[dict[s
return {d["name"]: d for d in defs}, handlers
+def _own_rows(active: bool, person_id: int) -> Any:
+ """``rows_for_person`` when ``active``, else nothing."""
+ import contextlib
+
+ from openexecutive.audit.context import rows_for_person
+
+ return rows_for_person(person_id) if active else contextlib.nullcontext()
+
+
def _with_quote(tool: dict[str, Any]) -> dict[str, Any]:
"""``tool`` with a required ``source_quote`` (kept when it has one)."""
schema = dict(tool.get("input_schema") or {"type": "object", "properties": {}})
@@ -734,7 +771,8 @@ async def _review_person(
surface = json.loads(turns[-1]["surface"] or "{}")
session = _rebuild_session(session_id, person, surface if isinstance(surface, dict) else {})
words = "\n\n".join(str(r["message"]) for r in turns)
- with set_turn(session_id=session_id, turn_id=f"chat-review-{turns[-1]['id']}"):
+ mail = mail_private_turns(turns, db_path=db_path)
+ with set_turn(session_id=session_id, turn_id=f"chat-review-{turns[-1]['id']}"), _own_rows(mail, person_id):
from openexecutive.orchestrator.schedule_tools import set_session
with set_session(session):
@@ -748,15 +786,15 @@ async def _review_person(
graded = await _grade_turns(session_id, person, turns, db_path=db_path)
missed = {i for i, row in enumerate(turns, 1) if graded.get(int(row["id"])) == "miss"}
done = await asyncio.wait_for(
- _run_loop(session, person, turns, words, misses=missed, db_path=db_path),
+ _run_loop(session, person, turns, words, misses=missed, mail=mail, db_path=db_path),
timeout=_TIMEOUT_S,
)
- misses = sum(1 for v in graded.values() if v == "miss")
- _audit(session_id,
- f"conversation review for person {person_id}: {len(done)} change(s), "
- f"{misses} miss(es) in {len(graded)} graded turn(s)",
- {"op": "chat_review", "person_id": person_id, "turns": len(turns),
- "changes": done, "graded": len(graded), "misses": misses})
+ misses = sum(1 for v in graded.values() if v == "miss")
+ _audit(session_id,
+ f"conversation review for person {person_id}: {len(done)} change(s), "
+ f"{misses} miss(es) in {len(graded)} graded turn(s)",
+ {"op": "chat_review", "person_id": person_id, "turns": len(turns),
+ "changes": done, "graded": len(graded), "misses": misses})
except Exception as exc:
logger.exception("chat_review: pass failed")
_audit(session_id, f"FAILED({type(exc).__name__}) conversation review",
@@ -787,7 +825,8 @@ was asked.
For a miss, say what the person wanted instead in one or two sentences \
(wanted), and copy as quote at least four of their exact words, from the THEM \
-lines of that turn or the next ones, that show it. Then the kind: company when \
+lines of that turn or the next ones, that show it (a miss a SIGNAL shows needs \
+no quote when they said nothing about it). Then the kind: company when \
something only this workspace knows would have fixed it (a term they use, a \
fact, a preference, which specialist to ask, doing a thing rather than \
promising it); product when the assistant could not have done it with what it \
@@ -938,10 +977,41 @@ def turn_signals(
if row["turn_id"] and str(row["turn_id"]) in nudged:
lines.append("the reply claimed a change no tool made")
lines.extend(f"tool {name} failed" for name in _failed_calls(row))
+ # A chat app has no 👍/👎 on the reply: the person types it as their
+ # next message instead.
+ typed = _typed_thumb(str(turns[i + 1]["message"])) if i + 1 < len(turns) else None
+ if typed == "down" and not any(line.startswith("thumbs down") for line in lines):
+ lines.append("thumbs down")
+ elif typed == "up" and THUMBS_UP not in lines:
+ lines.append(THUMBS_UP)
signals[int(row["id"])] = lines
return signals, message_ids
+_THUMB_RE = re.compile(r"^(?:thumbs?[ -]?(up|down)|(👍|👎)(?:[\U0001F3FB-\U0001F3FF])?)$", re.IGNORECASE)
+_VOICE_PREFIX = "[Voice note, transcribed]"
+
+
+def _typed_thumb(message: str) -> str | None:
+ """``"up"`` or ``"down"`` when the whole message is a thumbs up or down,
+ typed or said ("Thumbs down.", "👎"), else None."""
+ text = message.strip()
+ if text.startswith(_VOICE_PREFIX):
+ text = text[len(_VOICE_PREFIX):]
+ text = " ".join(text.strip(" \t\n.!").split())
+ m = _THUMB_RE.match(text)
+ if m is None:
+ return None
+ word = (m.group(1) or "").lower()
+ return "up" if word == "up" or m.group(2) == "👍" else "down"
+
+
+def _backed_by_signal(lines: list[str]) -> bool:
+ """Whether the product itself recorded that the turn fell short: any
+ signal but a thumbs up."""
+ return any(line != THUMBS_UP for line in lines)
+
+
def _render_signals(turns: list[sqlite3.Row], signals: dict[int, list[str]]) -> str:
parts: list[str] = []
for i, row in enumerate(turns, 1):
@@ -951,13 +1021,18 @@ def _render_signals(turns: list[sqlite3.Row], signals: dict[int, list[str]]) ->
def accept_grades(
- payload: dict[str, Any], turns: list[sqlite3.Row]
+ payload: dict[str, Any],
+ turns: list[sqlite3.Row],
+ signals: dict[int, list[str]] | None = None,
) -> dict[int, tuple[str, str, str]]:
"""The grades the model gave, by row id, as ``(verdict, kind, wanted)``,
after the code checks: one grade per shown turn, a known verdict, and a
miss backed by a quote of four or more of the person's own words from
- that turn or the ones after it (else the turn is ``unclear`` and
- ``wanted`` is dropped). A turn the model skipped is ``unclear``."""
+ that turn or the ones after it, or by a signal the product recorded on
+ the turn (``signals``: a thumbs down, a stopped or taken-back reply, a
+ claim no tool made, a failed tool), else the turn is ``unclear`` and
+ ``wanted`` is dropped. A miss always needs ``wanted``. A turn the model
+ skipped is ``unclear``."""
from openexecutive.memory.episodic import _normalize_for_quote_match
grades: dict[int, tuple[str, str, str]] = {}
@@ -979,7 +1054,9 @@ def accept_grades(
if verdict == "miss":
quote = _normalize_for_quote_match(str(g.get("quote") or ""))
wanted = " ".join(str(g.get("wanted") or "").split())[:WANTED_MAX]
- if not wanted or len(quote.split()) < _QUOTE_MIN_WORDS or quote not in words_from[i]:
+ quoted = len(quote.split()) >= _QUOTE_MIN_WORDS and quote in words_from[i]
+ backed = quoted or _backed_by_signal((signals or {}).get(int(row["id"])) or [])
+ if not wanted or not backed:
verdict, wanted = "unclear", ""
else:
kind = str(g.get("kind") or "company")
@@ -1076,7 +1153,7 @@ async def _grade_turns(
if getattr(block, "type", "") == "tool_use" and getattr(block, "name", "") == GRADE_TOOL["name"]:
payload = block.input if isinstance(block.input, dict) else {}
break
- grades = accept_grades(payload, turns)
+ grades = accept_grades(payload, turns, signals)
_store_grades(grades, turns, signals, message_ids, db_path=db_path)
return {rid: v for rid, (v, _k, _w) in grades.items()}
except Exception:
@@ -1205,14 +1282,19 @@ def forget_miss(row_id: int, *, caller_person_id: int | None, db_path: Path | No
def _tools_for(
- person: Any, *, misses: bool = False
+ person: Any, *, misses: bool = False, mail: bool = False
) -> tuple[list[dict[str, Any]], dict[str, Callable[[dict[str, Any]], Awaitable[str]]]]:
+ """The review's tools for ``person``. ``mail``: the chat read their
+ mailbox, so no fact is kept from it (facts are read on everyone's
+ turns, and its replies quote other people's mail)."""
from openexecutive.delegation.settings import can_delegate
by_name, chat_handlers = _chat_tools()
names = sorted(by_name)
if not person.is_principal:
names = [n for n in names if n not in _PRINCIPAL_ONLY]
+ if mail:
+ names = [n for n in names if n != "remember_fact"]
tools = [by_name[n] if n in _READ_TOOLS else _with_quote(by_name[n]) for n in names]
handlers = {n: chat_handlers[n] for n in names}
tools.append(LEARN_REPLY_STYLE_TOOL)
@@ -1232,6 +1314,7 @@ async def _run_loop(
words: str,
*,
misses: set[int] | None = None,
+ mail: bool = False,
db_path: Path | None = None,
) -> list[str]:
"""The tool loop; the names of the changes that went through. ``misses``
@@ -1244,7 +1327,7 @@ async def _run_loop(
settings = _settings()
model = settings.chat_review_model or settings.routing_model
misses = misses or set()
- tools, handlers = _tools_for(person, misses=bool(misses))
+ tools, handlers = _tools_for(person, misses=bool(misses), mail=mail)
offered = {t["name"] for t in tools}
facts = _standing_facts() if person.is_principal else ""
intro = (
@@ -1401,6 +1484,7 @@ async def _apply(
lesson, reason = await asyncio.to_thread(
lessons.add_lesson, int(person.id), str(tool_input.get("lesson") or ""),
quote=quote, session_id=str(session.session_id), turn_row_id=row_id, db_path=db_path,
+ private=mail_private_turns(list(turns or []), db_path=db_path),
)
return json.dumps({"status": "kept", "lesson": lesson["text"]} if lesson else {"status": "refused", "detail": reason})
if name == "learn_reply_style":
diff --git a/packages/core/openexecutive/memory/lessons.py b/packages/core/openexecutive/memory/lessons.py
index dc662458..b54ec211 100644
--- a/packages/core/openexecutive/memory/lessons.py
+++ b/packages/core/openexecutive/memory/lessons.py
@@ -24,7 +24,8 @@ principal's lessons learned in a shared space (a channel or group thread,
where everyone read the chat) reach every speaker's turns; one learned in
the principal's own chat stays with the principal, as a teammate's stays
with the teammate, so nothing said in someone's own chat is paraphrased
-into another person's turn. The Reflection screen lists each person their
+into another person's turn. A chat that read its owner's mail is theirs
+alone even in a shared space, so its lessons stay theirs too. The Reflection screen lists each person their
own and the principal the ones from chats they may open.
**What it may say.** The lesson must be the quote's own point: beyond the
@@ -180,13 +181,19 @@ def _normalize(text: str) -> str:
return _normalize(text)
-def _shared_space(session_id: str) -> bool:
+def _shared_space(session_id: str, db_path: Path | None = None) -> bool:
"""Whether the chat was a channel or group thread everyone there read
- (``api.routes.chat._shared_space``). Fails closed: not shared."""
+ (``api.routes.chat._shared_space``) and never read its owner's mail
+ (``session_store.mark_mail_private``: then it is theirs alone, wherever
+ it happened). Fails closed: not shared."""
try:
from openexecutive.api.routes.chat import _shared_space
+ from openexecutive.memory.episodic import _resolve_db_path
+ from openexecutive.memory.session_store import session_mail_private
- return bool(_shared_space(str(session_id)))
+ if not _shared_space(str(session_id)):
+ return False
+ return not session_mail_private(str(session_id), db_path=_resolve_db_path(db_path))
except Exception:
return False
@@ -204,9 +211,11 @@ def add_lesson(
session_id: str,
turn_row_id: int | None,
db_path: Path | None = None,
+ private: bool = False,
) -> tuple[dict[str, Any] | None, str | None]:
"""Keep one lesson; ``(lesson, None)`` when stored, ``(None, reason)``
when not. The caller has checked ``quote`` against the person's words.
+ ``private``: learned from a chat that read mail, so never shared.
A duplicate of a live lesson is refused; past ``MAX_ACTIVE`` live
lessons the oldest retires to make room."""
clean = _normalize(text)
@@ -214,7 +223,7 @@ def add_lesson(
if rejection:
return None, rejection
now = _now().isoformat()
- shared = _shared_space(session_id)
+ shared = not private and _shared_space(session_id, db_path)
conn = _connect(db_path)
try:
# One writer at a time: two reviews landing together must not both
diff --git a/packages/core/openexecutive/memory/replay.py b/packages/core/openexecutive/memory/replay.py
index 07774f93..a2e51551 100644
--- a/packages/core/openexecutive/memory/replay.py
+++ b/packages/core/openexecutive/memory/replay.py
@@ -405,6 +405,17 @@ async def replay_case(
person = get_person(int(row["person_id"]))
if person is None or person.id is None or person.archived:
return None
+ # A chat that read mail is its person's alone: so is every audit row the
+ # replay writes about it (the judge's notes quote the chat).
+ with chat_review._own_rows(chat_review.mail_private_turns([row], db_path=db_path), int(person.id)):
+ return await _replay_case(row, why, person, executive=executive, now=now,
+ new_lessons=new_lessons, db_path=db_path)
+
+
+async def _replay_case(
+ row: sqlite3.Row, why: str, person: Any, *, executive: Any, now: datetime,
+ new_lessons: list[dict[str, Any]], db_path: Path | None,
+) -> dict[str, Any]:
protect = why == WHY_PROTECT
reached = [lesson["id"] for lesson in lessons.lessons_for(int(person.id), str(row["message"]), db_path=db_path)]
try:
diff --git a/packages/core/openexecutive/orchestrator/executive.py b/packages/core/openexecutive/orchestrator/executive.py
index 41f4e7e0..33cd1099 100644
--- a/packages/core/openexecutive/orchestrator/executive.py
+++ b/packages/core/openexecutive/orchestrator/executive.py
@@ -1504,7 +1504,8 @@ class Executive:
# has none to learn from: its reply quotes a draft built from other
# people's mail, so should_extract refuses the empty text and every
# other pass below is skipped outright.
- speaker_text = "" if touched_mail else with_added(_speaker_text(memory_text, user_message), inbox)
+ own_text = with_added(_speaker_text(memory_text, user_message), inbox)
+ speaker_text = "" if touched_mail else own_text
# A replay of a graded turn (memory.replay) is kept nowhere: no open
# loops, style, review or mirror of it (should_extract and
# schedule_chat_notes refuse a replay session themselves).
@@ -1562,12 +1563,13 @@ class Executive:
# Kept for the conversation review once the chat goes quiet
# (memory.chat_review): a verified speaker's own words, the reply
- # and the tools the turn ran.
+ # and the tools the turn ran. A turn that touched their mailbox is
+ # kept too, for their own review only (record_turn's ``mail``).
from openexecutive.memory.chat_review import record_turn
- if kept:
- record_turn(speaker_text, full_response, session=session,
- person_id=person_id, calls=turn_calls)
+ if not chat_replay.is_replay(session):
+ record_turn(own_text, full_response, session=session,
+ person_id=person_id, calls=turn_calls, mail=touched_mail)
# Mirror the completed exchange into Honcho so its server-side
# extraction can update the peer card. Fire-and-forget; the
@@ -2057,7 +2059,8 @@ class Executive:
# The speaker's own words, for extraction, open loops and peer
# memory alike — none for a turn that touched their mailbox; see
# stream_chat.
- speaker_text = "" if touched_mail else with_added(_speaker_text(memory_text, user_message), inbox)
+ own_text = with_added(_speaker_text(memory_text, user_message), inbox)
+ speaker_text = "" if touched_mail else own_text
# private_rows: see stream_chat — the scheduled passes copy it.
# A replay (memory.replay) is kept nowhere — see stream_chat.
kept = not touched_mail and not chat_replay.is_replay(session)
@@ -2090,9 +2093,9 @@ class Executive:
# Conversation review — see stream_chat.
from openexecutive.memory.chat_review import record_turn
- if kept:
- record_turn(speaker_text, final_response, session=session,
- person_id=person_id, calls=turn_calls)
+ if not chat_replay.is_replay(session):
+ record_turn(own_text, final_response, session=session,
+ person_id=person_id, calls=turn_calls, mail=touched_mail)
# Mirror the completed exchange into Honcho (see stream_chat for
# rationale, and for why a turn private to the principal — or one
diff --git a/packages/core/openexecutive/orchestrator/teammate_mail.py b/packages/core/openexecutive/orchestrator/teammate_mail.py
index 1477526c..49f19dd5 100644
--- a/packages/core/openexecutive/orchestrator/teammate_mail.py
+++ b/packages/core/openexecutive/orchestrator/teammate_mail.py
@@ -579,12 +579,16 @@ def _keep_private(session: Any, sides: _Sides) -> None:
if sides.reader_id is None or sides.reader_is_principal or not session_id:
return
from openexecutive.delegation.settings import history_len
+ from openexecutive.memory.replay import is_replay
from openexecutive.memory.session_store import mark_mail_private
- try:
- mark_mail_private(str(session_id), sides.reader_id, history_len=history_len(session))
- except Exception:
- logger.exception("teammate_mail: couldn't mark the conversation private")
+ # A replay (memory.replay) keeps no conversation: marking one would leave
+ # an empty chat in the teammate's list.
+ if not is_replay(session):
+ try:
+ mark_mail_private(str(session_id), sides.reader_id, history_len=history_len(session))
+ except Exception:
+ logger.exception("teammate_mail: couldn't mark the conversation private")
# The rest of this turn's rows, its answer included, are theirs too.
from openexecutive.delegation.settings import turn_delegation
diff --git a/packages/core/tests/unit/test_chat_review.py b/packages/core/tests/unit/test_chat_review.py
index d78185c3..561a4397 100644
--- a/packages/core/tests/unit/test_chat_review.py
+++ b/packages/core/tests/unit/test_chat_review.py
@@ -579,13 +579,80 @@ def test_a_deleted_chat_takes_its_turns_with_it(db: Path, roster: SimpleNamespac
assert _turns(db) == []
-def test_a_chat_that_read_its_owners_mail_is_not_kept(db: Path, roster: SimpleNamespace) -> None:
+def test_a_chat_that_read_its_owners_mail_is_kept_without_the_mail(db: Path, roster: SimpleNamespace) -> None:
+ """A chat that read the owner's mail is reviewed, but its tools are kept
+ by name only: their results are other people's mail."""
from openexecutive.memory.session_store import create_session, mark_mail_private
create_session("s-1", "Mail", NOW.isoformat(), roster.principal.id, db_path=db)
mark_mail_private("s-1", roster.principal.id, db_path=db)
- assert _record(roster.principal, text=ASK, reply="Your inbox has two from Dana.") is None
- assert _turns(db) == []
+ calls = [("search_gmail", "From Dana: the counter is 5k over"), ("create_alert", '{"error": "off"}')]
+ assert cr.record_turn(ASK, "Dana came up 5k.", session=_web(roster.principal.id),
+ person_id=roster.principal.id, calls=calls, now=NOW) is not None
+ # The turn that read the mail itself, before the chat is marked.
+ assert cr.record_turn(AGAIN, "Two from Dana.", session=_web(roster.principal.id, session_id="s-2"),
+ person_id=roster.principal.id, calls=calls, mail=True, now=NOW) is not None
+ for row in _turns(db):
+ assert json.loads(row["calls"]) == [{"tool": "search_gmail", "result": ""},
+ {"tool": "create_alert", "result": "error"}]
+ assert cr._failed_calls(row) == ["create_alert"]
+
+
+def test_the_review_of_a_chat_that_read_mail_writes_only_its_persons_rows(
+ db: Path, roster: SimpleNamespace, provider: _Provider
+) -> None:
+ from openexecutive.memory.session_store import create_session
+
+ create_session("s-1", "Offer", NOW.isoformat(), roster.teammate.id, db_path=db)
+ cr.record_turn(ASK, "Dana came up 5k.", session=_web(roster.teammate.id), person_id=roster.teammate.id,
+ calls=[], mail=True, now=NOW)
+ provider.grades = [{"turn": 1, "verdict": "fine"}]
+ _review(db)
+ [row] = _turns(db)
+ assert row["mail"] == 1
+ events = audit_logger.get_audit_logger().query(event_type="chat_review", all_owners=True)
+ review = [e for e in events if "conversation review for person" in e.summary]
+ assert review and all(e.private and e.private_to_person == roster.teammate.id for e in review)
+
+
+def test_a_chat_that_read_mail_keeps_no_fact(roster: SimpleNamespace) -> None:
+ names = {t["name"] for t in cr._tools_for(roster.principal, mail=True)[0]}
+ assert "remember_fact" not in names and "close_open_loop" in names
+ assert "remember_fact" in {t["name"] for t in cr._tools_for(roster.principal)[0]}
+
+
+def test_a_miss_the_product_recorded_needs_no_quote(db: Path, roster: SimpleNamespace,
+ provider: _Provider) -> None:
+ from openexecutive.audit import log_event
+ from openexecutive.audit.context import set_turn
+
+ with set_turn(session_id="s-1", turn_id="turn-1"):
+ _record(roster.principal, text=ASK, reply="I've cancelled it.")
+ log_event("claim_check", "Reply claimed a change no tool made", session_id="s-1", turn_id="turn-1",
+ actor="executive")
+ _record(roster.principal, text=AGAIN, reply="Done.", at=NOW + timedelta(minutes=1))
+ provider.grades = [
+ {"turn": 1, "verdict": "miss", "kind": "company", "wanted": "The alert actually cancelled."},
+ {"turn": 2, "verdict": "miss", "wanted": "Something else."},
+ ]
+ _review(db)
+ first, second = _turns(db)
+ assert first["verdict"] == "miss" and first["wanted"] == "The alert actually cancelled."
+ assert second["verdict"] == "unclear" # no signal and no quote
+
+
+def test_a_typed_thumbs_down_counts_as_one(db: Path, roster: SimpleNamespace, provider: _Provider) -> None:
+ _record(roster.principal, text=ASK, reply="I'll keep an eye on it.", at=NOW)
+ _record(roster.principal, text="Thumbs down.", reply="Sorry about that.", at=NOW + timedelta(minutes=1))
+ _record(roster.principal, text="[Voice note, transcribed]\n👍", reply="Glad it helped.",
+ at=NOW + timedelta(minutes=2))
+ _record(roster.principal, text="thumbs down on the weather", reply="Noted.", at=NOW + timedelta(minutes=3))
+ provider.grades = [{"turn": i, "verdict": "fine"} for i in range(1, 5)]
+ _review(db)
+ content = _grade_content(provider)
+ assert "[1] SIGNALS: thumbs down" in content
+ assert "[2] SIGNALS: thumbs up" in content
+ assert "[3] SIGNALS: none" in content
def test_a_miss_outlives_the_week_and_a_fine_turn_does_not(db: Path, roster: SimpleNamespace,
diff --git a/packages/core/tests/unit/test_lessons.py b/packages/core/tests/unit/test_lessons.py
index 4f142816..43db18af 100644
--- a/packages/core/tests/unit/test_lessons.py
+++ b/packages/core/tests/unit/test_lessons.py
@@ -142,6 +142,23 @@ def test_a_lesson_from_someones_own_chat_stays_with_them(roster: SimpleNamespace
assert "board deck" in olivia and "reorg" in olivia and "price list" not in olivia
+def test_a_lesson_from_a_shared_chat_that_read_mail_stays_with_its_owner(
+ roster: SimpleNamespace, db: Path
+) -> None:
+ """A channel thread that read its owner's mail is theirs alone, so a
+ lesson learned there reaches no one else's turns."""
+ from openexecutive.memory.session_store import create_session, mark_mail_private
+
+ session_id = "slack:channel:C7:ts2"
+ create_session(session_id, "Offers", "2026-10-14T09:00:00+00:00", roster.principal.id, db_path=db)
+ mark_mail_private(session_id, roster.principal.id, db_path=db)
+ lesson, _ = lessons.add_lesson(roster.principal.id, "The board deck means the Q4 board workflow.",
+ quote="the board deck is the Q4 board workflow",
+ session_id=session_id, turn_row_id=None)
+ assert lesson is not None and lesson["shared"] is False
+ assert "board deck" not in lessons.build_lessons_block(roster.teammate.id, "send me the board deck")
+
+
def test_the_specialists_get_the_same_lines_under_their_failure_cases(roster: SimpleNamespace) -> None:
_add(roster.principal.id, "The board deck means the Q4 board workflow.")
section = lessons.lessons_for_query(roster.principal.id, "update the board deck")
diff --git a/packages/core/tests/unit/test_replay.py b/packages/core/tests/unit/test_replay.py
index f8a2df7e..ac333094 100644
--- a/packages/core/tests/unit/test_replay.py
+++ b/packages/core/tests/unit/test_replay.py
@@ -298,6 +298,25 @@ def test_a_miss_that_now_passes_is_closed_with_the_date(roster: SimpleNamespace)
assert replay.summary_for(cr.list_misses(person_id=None), NOW)["would_pass"] == 1
+def test_a_replay_of_a_chat_that_read_mail_writes_only_its_persons_rows(
+ db: Path, roster: SimpleNamespace
+) -> None:
+ """The judge's notes quote the chat: on a chat that read mail, every
+ audit row the replay writes is its person's alone."""
+ from openexecutive.memory.session_store import create_session, mark_mail_private
+
+ create_session("s-mail", "Offer", NOW.isoformat(), roster.teammate.id, db_path=db)
+ mark_mail_private("s-mail", roster.teammate.id, db_path=db)
+ miss = _turn(roster.teammate.id, session_id="s-mail")
+ plain = _turn(roster.teammate.id, session_id="s-1")
+ _run(miss, replay.WHY_WEEKLY, passed=True, new_lessons=[])
+ _run(plain, replay.WHY_WEEKLY, passed=True, new_lessons=[])
+ rows = audit_logger.get_audit_logger().query(event_type="chat_review", all_owners=True)
+ mail_rows = [r for r in rows if r.session_id == "s-mail"]
+ assert mail_rows and all(r.private and r.private_to_person == roster.teammate.id for r in mail_rows)
+ assert all(r.private_to_person is None for r in rows if r.session_id == "s-1")
+
+
def test_a_lesson_whose_miss_still_fails_twice_retires(roster: SimpleNamespace) -> None:
miss = _turn(roster.principal.id)
lesson_id = _lesson(roster.principal.id, miss)