docs: research open loops and personal execution boundaries

2026-09-28 22:37:51 +09:00
parent b0458c4b91
commit 970553bd8f
2 changed files with 318 additions and 0 deletions
@@ -0,0 +1,202 @@
 # gbrain open loops and personal execution support
 Research, 2026-09-28. Source inspection at gbrain revision
 `e78f1c38b947b053f3a46881340f74f316be855a`; upstream tests were read, not executed.
 Application behavior below is proposed, not implemented. This supplements
 [external Codex publishing](agent-publishing-design.md).
 ## What gbrain implements
 ### Scope: ingestion is broader than the open-loop engine
 gbrain as a whole is not Gmail-only. Its implemented ingestion paths include:
 - Google: Gmail, Calendar and Contacts.
 - GitHub: issues, pull requests, comments, reviews and associated metadata.
 - ChatGPT and Claude account history through live session-cookie connectors.
 - Imported agent transcripts, including Codex, Claude Code, OpenClaw and Hermes,
  plus consumer conversation exports.
 - Markdown repositories and files, inbox-folder capture, CLI/MCP page writes,
  and the HTTP ingest endpoint.
 See [data ingestion](https://github.com/garrytan/gbrain/blob/e78f1c38b947b053f3a46881340f74f316be855a/docs/guides/data-ingestion.md),
 [GitHub source](https://github.com/garrytan/gbrain/blob/e78f1c38b947b053f3a46881340f74f316be855a/docs/guides/github-source.md),
 and the [live connector registry](https://github.com/garrytan/gbrain/blob/e78f1c38b947b053f3a46881340f74f316be855a/src/core/connectors/registry.ts).
 Custom ingestion extensions and agent-side service access are separate from
 native synchronization. Documentation mentions Slack, iMessage and other
 messaging services through external agent gateways; this does not establish
 built-in history sync or open-loop detection for each service. No native Beeper
 source was identified. The automatic open-loop detection path inspected below
 is specifically wired to Google email threads, not every ingested page.
 ### Detection
 Collection itself is implemented code, not an LLM asked to copy every item.
 `gbrain sync --source <id>` dispatches to native Google/GitHub synchronization;
 `gbrain connectors sync chatgpt` fetches conversation history and passes it to
 the transcript importer. Agents can invoke these commands, but a scheduler can
 invoke them directly without an interactive agent. Semantic extraction and
 optional embeddings are separate model-using stages.
 The [email recipe](https://github.com/garrytan/gbrain/blob/e78f1c38b947b053f3a46881340f74f316be855a/recipes/email-to-brain.md)
 explicitly says that earlier versions asked agents to build a collector script,
 while current versions ship that logic in the native connector. The illustrative
 `scripts/email-collector/email-collector.mjs` path in the deterministic-collectors
 guide is not a shipped script at this revision. Agent-authored memory and custom
 external integrations remain distinct ingestion paths; not every integration
 mentioned in a recipe is a built-in connector.
 The engine operates on Google/Gmail threads. It is not a ready-made Beeper
 integration. It distinguishes five kinds of unfinished interaction:
 | Kind                  | Detection                                                                                                            |
 | --------------------- | -------------------------------------------------------------------------------------------------------------------- |
 | Unanswered inbound    | Last substantive message is from someone else, owner is in To, at least 24 hours old                                 |
 | Unanswered outbound   | Last substantive message is from owner, external To recipient exists, body contains ASCII `?`, at least 72 hours old |
 | Commitment owed by me | LLM extracts an unresolved promise by the owner                                                                      |
 | Commitment owed to me | LLM extracts an unresolved promise by someone else                                                                   |
 | Decision pending      | LLM extracts an explicit unresolved choice or question                                                               |
 The [detector](https://github.com/garrytan/gbrain/blob/e78f1c38b947b053f3a46881340f74f316be855a/src/core/google/loop-detect.ts)
 filters machine senders, calendar system messages, self-only threads, muted
 senders/threads, and inbound list mail or CC-only delivery. Outbound attribution
 uses the first external To recipient. Evidence includes the last message ID and
 up to 200 characters of its body.
 These rules are useful candidate detection, not proof that a response is owed.
 Inbound messages need not contain a request. Outbound requests without `?`,
 including full-width Japanese `？`, can be missed. In group chat, a third party's
 message is not evidence that the intended recipient answered.
 The [LLM extractor](https://github.com/garrytan/gbrain/blob/e78f1c38b947b053f3a46881340f74f316be855a/src/core/google/loops-extract.ts)
 processes eligible threads whose newest message is within 30 days. It sends the
 newest 12,000 characters, requesting structured direction, counterparty, promise,
 due date and quotation. Spam/trash and machine-only conversations are excluded;
 owner participation can override bulk-mail exclusions. Updates remain eligible
 because they may contain invoices or contracts.
 Important implementation limits:
 - A malformed item rejects the whole parsed response before writes. This does
  not make the subsequent facts, loops and graph writes one atomic transaction.
 - A quotation is checked against the supplied text after whitespace
  normalization. A mismatch removes the quotation **but retains the loop**.
 - Commitment confidence is a fixed `0.85`; decision confidence is `0.8`.
  Neither is a calibrated probability or a model-generated confidence estimate.
 - LLM evidence references a page; it does not require a specific message ID.
 - Date-only deadlines are stored at `23:59:59Z`, not the user's local end of day.
 - Deduplication hashes thread, direction and generated text. A paraphrase can
  produce a second loop for the same real-world promise.
 ## Resolution and persistence
 The [store](https://github.com/garrytan/gbrain/blob/e78f1c38b947b053f3a46881340f74f316be855a/src/core/loops/loops-store.ts)
 keeps `open`, `done`, `dropped` and `stale`, with closure history.
 - A change in whose turn it is automatically closes the appropriate
  deterministic unanswered loop. Muting or a same-side reminder does not.
 - Reply-driven closure applies only to `deterministic_thread` loops.
 - LLM extraction upserts candidates. It does **not** reconcile previously
  stored promises that disappear from a later extraction. Asking the model to
  omit fulfilled promises is insufficient to close those records.
 - Users can mark a loop done or dropped. Reprocessing the same observed activity
  does not resurrect it; genuinely newer activity can reopen it.
 - LLM loops become stale after a deadline is over 14 days past **and** activity
  is over 14 days old, or after 90 days without activity. Stale is not fulfilled.
 - Dedicated snooze/defer operations are absent. Mutes prevent future detection;
  they do not close existing loops.
 For example, “I will send the document Friday” and “Thanks!” can settle the
 reply exchange while leaving the document promise open. Completion needs its
 own evidence or the user's decision.
 ## Scheduling, freshness and ranking
 The detector runs when
 [Google source processing](https://github.com/garrytan/gbrain/blob/e78f1c38b947b053f3a46881340f74f316be855a/src/core/google/google-source.ts)
 loads a thread. Delta sync processes threads changed in Gmail history. No
 dedicated elapsed-time reevaluation was found in that path: a thread skipped
 inside the grace period may not be reconsidered merely because 24/72 hours pass,
 until a full sync or another touch. This is a code-based inference, not a
 reproduced runtime failure.
 Extraction jobs use source, page slug and newest-message timestamp as their key.
 Pending work has a 500-job ceiling per source. Overflow is logged, but a durable
 backlog of excluded candidates is not maintained; another thread change may be
 needed to enqueue them. Successful source sync therefore does not imply complete
 or current inference results.
 The [waiting operations](https://github.com/garrytan/gbrain/blob/e78f1c38b947b053f3a46881340f74f316be855a/src/core/ops/loops.ts)
 group loops by person, defaulting to three groups. Ranking combines loop count,
 deadline proximity, age and backlinks to the person's page. It is not a
 personal-capacity or action-readiness model. Retrieval considers up to 500
 recent loops before ranking and reports truncation.
 The [CLI](https://github.com/garrytan/gbrain/blob/e78f1c38b947b053f3a46881340f74f316be855a/src/commands/loops.ts)
 normally refuses a waiting report if all Google sources are over 24 hours stale.
 One fresh source permits display, so per-source freshness still matters. Remote
 operations omit quotations, deep links and entity context that trusted-local
 calls may expose.
 ## Proposed application flow
 Keep life as CRM truth and external Codex as the reasoning and filesystem writer.
 The app accepts structured proposals and records user decisions and execution.
 1. Beeper supplies conversation events. External scheduled Codex runs also
   reconsider items whose review time has arrived, even without a new message.
 2. Codex distinguishes a request, an accepted promise, an unanswered exchange
   and a decision. A request must not automatically become an accepted obligation.
 3. Publish candidates with stable identities, source message references,
   observations, direction, counterparty and any real deadline. Avoid using
   generated prose as the only identity.
 4. Home selects a small set of actionable activities alongside routines and
   measurements. Open loops are candidate context, not automatically today's list.
 5. Replies open conversation and draft review; document promises open the actual
   next action. Weight entries and routines retain their own execution controls.
 6. Keep waiting items available outside the active list. A review date can bring
   a follow-up back without pretending the other person's work is the user's task.
 7. Record done, not needed, defer and corrections separately. Codex consumes
   these decisions and maintains life. New messages alone should not override
   an explicit rejection of the same obligation.
 Track source observation and inference completion separately. An old successful
 report can remain visible with its timestamp; incomplete coverage must not be
 presented as certainty that nothing remains. Old promises should enter review,
 not silently count as resolved.
 ## ADHD-oriented design hypothesis
 The intended benefit is to externalize remembering, choosing, starting and
 resuming work. These are product hypotheses for personal use, not evidence that
 this application treats ADHD or that all people with ADHD need the same UI.
 [NICE guidance](https://www.nice.org.uk/guidance/ng87/chapter/recommendations)
 describes individually chosen environmental modifications, reducing distraction,
 shorter periods of focus with breaks, and written support for verbal requests.
 [NIMH guidance](https://www.nimh.nih.gov/health/publications/attention-deficit-hyperactivity-disorder-what-you-need-to-know)
 includes routines, written reminders and breaking large tasks into manageable
 steps. These support the general direction, not a specific dashboard layout.
 Design hypotheses to evaluate:
 - Show a few concrete next actions with the material needed to start. Three is
  a possible initial display limit, not a clinically established number.
 - Store the broader context out of the user's working memory while keeping it
  retrievable. Do not turn every detected message into another decision to triage.
 - Support restarting after an interruption: what was last done, what remains,
  and a small next step. A missed day must not require clearing a wall of debt.
 - Keep flexible routines while preserving genuine external deadlines. Hiding
  real deadlines is different from avoiding a rigid minute-by-minute schedule.
 - Let ordinary actions use direct controls; natural language is an additional
  route, not a requirement to formulate a prompt before every action.
 - Use restrained reminders and easy correction. False positives and repeated
  resurfacing are additional work, even when recall improves.
 - Review routine fit and effort as well as completion. Useful questions include
  whether important promises were missed, whether suggestions were wrong, and
  whether the app made starting or resuming easier. Avoid optimizing a completion
  percentage at the cost of meaningful work or rest.
 An initial trial can combine one routine, one genuine promise and one waiting
 item, then review the actual friction before expanding automatic capture.
@@ -0,0 +1,116 @@
 # Rensheng, gbrain and the personal workspace
 Research and recommendation, 2026-09-28. No integration was installed or tested.
 gbrain inspection: `e78f1c38b947b053f3a46881340f74f316be855a`.
 Rensheng inspection: `c06c4e3f290800752a0c252c84fbca0eed61e45d`.
 ## Finding
 There is substantial overlap. Memory, CRM, daily briefs, natural-language task
 management and agent tools are not unique to this workspace. Its remaining
 product hypothesis is a low-friction daily execution interface: turn personal
 context into a few actionable choices, execute through appropriate controls,
 retain actual outcomes, and improve routines from experience.
 This hypothesis has not been demonstrated by the current mock. Home, Messages
 and Journal still use in-memory prototype state; Beeper sending and life
 integration are not connected. Research has real persisted decks and Codex chat.
 See [current status](../README.md) and [execution prototype](execution-support.md).
 ## Honest comparison
 | Concern                   | gbrain                                                                               | Rensheng / life                                                                    | This workspace                                                     |
 | ------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
 | Collection                | Native Google/GitHub sync, chat-history connectors, imports and extension points     | External agents and existing source tools; shared raw store remains planned        | Real research connectors; communication integration proposed       |
 | Durable personal context  | Pages, sourced facts, corrections, withdrawal, retrieval and graph                   | Small source-linked Markdown views, explicit user decisions and domain conventions | Should consume context, not own another CRM                        |
 | Daily brief               | Agent briefing skills                                                                | Briefs generated by external agents                                                | State-derived prose prototype; externally published brief proposed |
 | Tasks                     | Agent skill for add, complete, defer and remove in a structured task page            | Procedures and context; execution tools retain occurrences                         | Direct routine/task controls, currently prototype                  |
 | Execution by content type | No equivalent unified routine/measurement/reply screen identified in inspected UI    | Separate OpenBrief implements attention handoff and return anchors                 | Content-specific execution controls are the intended focus         |
 | Routine learning          | No equivalent occurrence-based routine review identified in inspected implementation | Stores chosen procedures and meaningful review conclusions                         | Durable events and statistics proposed, not implemented            |
 gbrain's [daily-task-manager skill](https://github.com/garrytan/gbrain/blob/e78f1c38b947b053f3a46881340f74f316be855a/skills/daily-task-manager/SKILL.md)
 defines stable task IDs, priority, completion archives and deferral. Its
 [briefing skill](https://github.com/garrytan/gbrain/blob/e78f1c38b947b053f3a46881340f74f316be855a/skills/briefing/SKILL.md)
 already addresses daily assistance. These are agent workflows, not evidence of
 a unified execution app, but they are genuine alternatives for a user satisfied
 with chat and linked source applications.
 Rensheng is not uniquely local or agent-independent: gbrain also emphasizes
 portable, sourced memory across agents. Rensheng's useful distinction here is
 the deliberately small, directly readable context model and its operational
 conventions. It does not ship a replacement for gbrain's complete ingestion and
 retrieval infrastructure. See [Rensheng's comparison](https://github.com/yutakobayashidev/rensheng/blob/c06c4e3f290800752a0c252c84fbca0eed61e45d/COMPARISON.md).
 ## The nearer overlap: OpenBrief
 The Rensheng repository also contains an implemented
 [OpenBrief](https://github.com/yutakobayashidev/rensheng/blob/c06c4e3f290800752a0c252c84fbca0eed61e45d/docs/openbrief.md)
 daemon, desktop app and mobile companion. It handles observations, bounded
 briefs, agent proposals, confirmed decisions and return anchors. Thus resumption
 support should not be described as absent from the existing Rensheng repository.
 Before integrating that feature, choose one owner for its decisions and return
 anchors. If OpenBrief remains active, this workspace should reference its
 records rather than independently maintain conflicting copies. Reusing its
 runtime is not automatically required: its ACP ownership and desktop collection
 solve a narrower problem than this app's external-Codex publishing contract.
 Actual compatibility needs a separate implementation check.
 ## Recommended division
 - **Original systems:** messages, calendar events and source evidence.
 - **life:** relationship context, explicit preferences, accepted goals and routine
  definitions. External Codex maintains these files. Compiled claims remain
  traceable to original evidence and user corrections.
 - **External Codex:** interpretation, candidate selection, reply drafts and
  periodic review. No new app-owned reasoning engine is required.
 - **Workspace:** published suggestions, user choices, activity occurrences,
  measurements and execution events, plus the controls to act on them.
 - **gbrain, optional:** collection or retrieval infrastructure if a measured
  source-coverage or search problem justifies operating it. Do not introduce a
  second authoritative profile, task list and routine definition by default.
 Durable context and execution events have different owners. Copy meaningful
 outcomes into life through Codex; do not continuously reconcile two independently
 editable task databases. If gbrain indexes life later, treat the indexed copy as
 a projection and first verify its source-write behavior. This is an integration
 proposal, not a tested read-only mode or a promise that whole-brain deployment
 can be reduced to a dependency-free collector.
 ## Options and decision criteria
 1. **Rensheng + Codex + existing apps:** lowest custom application upkeep. Prefer
   this if a daily brief and source links already lead to action reliably.
 2. **Rensheng + this workspace + Codex:** recommended experiment for the stated
   need for routines, measurements and communication in one daily view. The
   execution interface and recorded outcomes must earn their maintenance cost.
 3. **Add gbrain underneath:** consider when collection, retrieval or cross-agent
   memory becomes an observed bottleneck. Its connectors do not supply a native
   Beeper integration or automatically replace external-Codex reasoning.
 4. **gbrain + existing chat/source apps:** reasonable if generic memory, Gmail
   waiting reports and conversational task management satisfy the actual need.
   In that case, much of this workspace need not be built.
 ## Smallest useful experiment
 Run a suggested one-to-two-week trial with one real life routine, one measurement
 and a small set of real Beeper follow-ups. This duration is a practical starting
 point, not a clinical protocol. Persist records before adding more mock screens.
 Publish a short brief and actionable items through the proposed
 [Codex interface](agent-publishing-design.md). Support direct execution, deferral
 and correction. Keep reply completion distinct from fulfillment of a promise.
 Retain events across reloads. Use observed results in one Codex-led review and
 save only adopted routine changes to life.
 Compare with the simpler baseline: Codex writes a daily brief to life and the
 user acts through existing apps. Assess actual usefulness: easier starts and
 returns, important commitments missed, false positives, correction effort,
 and whether the workspace is opened without prompting. Completion rate can
 support review but must preserve planned denominators, missing coverage and
 routine-version changes. No specific UI is claimed to treat ADHD.
 If the interface does not reduce friction, simplify to the baseline rather than
 defend the project through feature count. Defer generic vector search, knowledge
 graphs, a new agent framework, broad connector coverage and additional dashboard
 expansion until this execution loop proves useful.