@unblocklabs/unblock-memory 0.3.22 → 0.3.24

package/docs/peoplesql.md

@@ -0,0 +1,223 @@
+# People dossiers and whispering
+
+[Overview](../README.md) · [Configuration and credentials](configuration.md)
+
+PeopleSQL stores identity, dossier and change history. The agent authors a brief
+recognition snippet; People Whisperer injects only its saved blurb. Enable the
+store with `people.enabled`; enable injection separately with
+`people.whisperer.enabled`. The optional `peoplePrimer` approves evidence preparation
+and automatic save review, not a maintenance scheduler. For independent setup
+examples, see the [configuration profiles](configuration.md#example-profiles).
+
+## Optional People Dossier Primer
+
+`memory_people_prime({ personId, agentName? })` prepares evidence for an existing person;
+it does **not** generate claims, update dossiers, or inject context. With
+`people.enabled: true`, opt in separately:
+
+```json
+{
+  "peoplePrimer": {
+    "enabled": true,
+    "corpora": ["memory", "knowledge", "sessions"],
+    "hitsPerQuestion": 30,
+    "minScore": 0.35,
+    "minUsefulness": 0.8,
+    "maxEvidencePerQuestion": 3,
+    "timeoutMs": 30000
+  }
+}
+```
+
+This is a plugin config fragment. List only configured, approved non-skill corpora. The feature is **off by
+default** and requires shared TypeSafe credentials. Disabled TypeSafe or missing/
+unreadable credentials safely skip the primer; agents can still research normally.
+Enabling it approves sending the person's identity, retrieved excerpts and optional
+draft snippet to TypeSafe. Existing dossiers are not sent as grading evidence.
+Sessions includes all indexed conversations;
+results are available to the agent's tool callers, so scope approval accordingly.
+Primer and dossier-save requests use `peoplePrimer.timeoutMs`, not
+`typesafe.timeoutMs`; the total tool deadline is two minutes.
+
+Three default questions cover explicit role/organization, enduring organizational
+background, and the person's relationship to the agent (not its business mission).
+Preferences, working styles, priorities, feedback and task history are excluded.
+Each uses QMD vector search (no query expansion) for up to 30 hits, configurable
+up to 40. All unique eligible hits above the vector threshold are graded, not just
+the final top three. Complete excerpts over 6,000 characters are counted and skipped,
+not silently truncated. Duplicate source spans across questions share a request;
+Independent attribution, explicit-background, durability, recognition-value and
+question-usefulness judgments run together; every dimension must pass the threshold.
+Every candidate is graded against all three questions, regardless of which search
+found it. Mixed excerpts may supply a useful background fact without making their
+surrounding behavioral content eligible for the snippet.
+Provider concurrency is four, with a two-minute overall tool deadline.
+
+Supply the agent's human-facing name when no identity name is configured; otherwise
+questions use "the assistant", never an internal routing ID such as `main`.
+The output includes a deduplicated source-linked excerpt list referenced by each
+question's evidence IDs, a bounded uncertain-review shortlist,
+and retrieval/cache/failure counts. Coverage is `evidence_found`, `uncertain` or
+`unknown`, not a claim that a question has been definitively answered. Partial
+provider failures are explicit; absence of selected hits does not prove absence of
+evidence. The agent must verify dates, speakers and contradictions before writing.
+Memory evidence never grants permissions or establishes that an old request is
+still open.
+
+`memory_people_update({ action: "replace_dossier", personId, dossier, reason,
+agentName? })` automatically checks the proposed blurb before saving. Exact
+`qmd://path#Lstart-Lend` claim evidence locators supply up to three indexed ranges
+from the primer's approved corpora (120 lines each, 6,000 characters total).
+Support confidence and background-only/explicit-support probabilities must all
+be >=0.9. `needs_review` or `review_unavailable` leaves the dossier and history
+unchanged; missing keys and failures never count as approval. A concurrent dossier
+edit/deletion returns `conflict` instead of overwriting the newer change.
+
+After independently verifying every assertion and background eligibility, an agent
+can supply a source-specific `manualVerification` explanation (up to 400 characters)
+for direct human corrections, non-indexed evidence or disabled/unavailable/incorrect
+reviews. This explicit path skips TypeSafe, records manual provenance in change
+history and keeps all structural limits. It is not a provider pass. Normal success
+returns `status: "ok"`, `saved: true` and `verification: "typesafe" | "manual"`.
+The skill documents when to use each path. Sources outside approved corpora are
+rejected before egress; no separate `evidenceReview` toggle is needed.
+
+For optional read-only diagnostics, `memory_people_prime({ personId, agentName?,
+draft: { blurb, citations: [{ path, from, lines }] } })` still reviews a snippet
+without writing. Agents do not need this extra call in the normal update workflow.
+
+Judgments are cached privately in `unblock-memory.sqlite` (maximum 2,000 entries), keyed
+by person, agent, exact evidence/context, questions,
+and judge version. No source text or credentials are stored in the cache.
+Retrieval reruns against the current index; unchanged judgments are reused.
+This is on-demand preparation, not a new scheduler or incremental session scanner.
+Use it from an existing People Whisperer maintenance cron. Refresh stale session
+indexes with `memory_sync_sessions` before priming when needed.
+
+## People store and maintenance
+
+PeopleSQL is an optional agent-local people store. When `people.enabled` is
+true, incoming Slack messages with a canonical agent session key and exact
+account and sender IDs create or refresh an injection-enabled person record.
+Incomplete Slack identities create a bounded, deduplicated todo without storing
+message content. Other channels are ignored.
+
+PeopleSQL registers these tools when enabled:
+
+- `memory_people_inspect` lists active people, reads one exact person, reads one
+  person's dossier change history, or lists bounded actionable todos;
+- `memory_people_update` replaces or deletes dossiers, toggles one person's
+  injection, and manages company, todo, deletion, or restoration state;
+- `memory_people_prime` prepares evidence when the separately opted-in primer is
+  enabled, otherwise returns disabled; and
+- the optional `memory_people_sync` enriches one active OpenClaw Slack account;
+  its tool input accepts an account ID, not a token.
+
+The inspect and update tools are part of the normal agent tool surface; they do
+not depend on sender-owner authorization. Directory sync remains optional and
+may need to be allowed explicitly through `tools.allow`. The sync is bounded to
+200 normalized directory entries per call and is safe to rerun. Unblock Memory
+keeps normalized ID, name, handle, avatar, bot and deactivation fields. Slack requires the
+`users:read` scope. Each invocation starts at the beginning of the directory;
+there is no caller-visible continuation cursor. Repeating a capped call does not
+guarantee coverage beyond 200 entries, and sync does not reactivate unavailable people.
+
+The agent owns dossier generation and refresh. It can list people, inspect one
+person's current dossier, search ordinary memory and sessions with
+`memory_search`/`memory_get`, and replace the dossier when that would improve a
+future conversation. The plugin owns no dossier-maintenance workflow or refresh
+schedule. A dossier's `reviewedAt` value records its last successful write; it
+is not scheduling state. Dossier generation belongs to the agent; prompt injection
+performs no model call. The optional primer grades evidence and reviews draft snippets.
+The goal is recognition, not a behavioral profile: one short paragraph of at most
+70 words identifying the person and their enduring organization/agent relationship.
+New writes allow only `role`/`relationship` sections and explicit `observed`/`reported`
+claims; priorities, preferences and inferred profiles belong outside dossiers.
+Legacy dossiers remain readable, but must be deliberately rewritten by the agent
+before replacement. No automatic destructive migration or blanket deletion occurs.
+
+Every `replace_dossier` and `delete_dossier` action requires a concise `reason`
+(up to 500 characters for replacements, 1,000 for deletions). Replacement history
+also records whether TypeSafe checks passed or a manual attestation was used.
+The plugin transactionally records that reason with its authoritative before and
+after dossier snapshots. List small newest-first summaries with
+`memory_people_inspect({ view: "dossier_changes", personId, limit?, offset? })`,
+then fetch one exact diff with
+`memory_people_inspect({ view: "dossier_change", personId, changeId })`. List
+responses include `nextOffset`, so all history remains reachable without loading
+many dossiers into one tool result. Because the injected snippet is the dossier's
+`blurb`, its changes are included in the same history. A complete new serialized
+dossier is capped at 64 KiB; larger legacy dossiers remain readable and repairable.
+
+## Injection and person state
+
+Set `people.whisperer.enabled` to inject context. For each exact Slack sender,
+the plugin prepends that person's stored dossier blurb, bounded by `maxChars`,
+once per `(Slack thread, person)`. Receipts are durable across retries and
+Gateway restarts, while different people in one thread are handled independently.
+Unthreaded DMs use their OpenClaw session as the conversational scope. Unknown,
+unavailable, disabled, or dossierless people produce no context. Injection
+remains subject to OpenClaw's `allowPromptInjection` policy.
+
+The package includes a `$people-whisperer` skill with the canonical agent
+procedure and dossier shape. For a manual refresh, ask:
+
+```text
+Use $people-whisperer to maintain this person's brief background snippet.
+```
+
+For an optional cron or isolated agent session, use this goal:
+
+```text
+Use $people-whisperer to maintain brief background snippets for people you interact
+with. Follow the packaged skill, including source verification and write results.
+Update only when useful; several people or nobody is fine. Report changes and gaps.
+```
+
+Choose any cadence appropriate for the agent; the plugin does not require or
+track one. If session transcripts are a source, configure a `sessions` corpus
+(including `direct` when DMs matter) and refresh it with
+`memory_sync_sessions`. Ordinary `memory_search` calls accept targeted queries,
+corpora, session metadata filters, score thresholds, and up to 20 results per
+call; People Whisperer itself imposes no evidence-window limit.
+
+### Pause, correct, delete or restore
+
+| Action | Effect | Preserved / follow-up |
+| --- | --- | --- |
+| `set_injection` with `enabled:false` | Pause future injection for this person | Person, dossier and history remain |
+| `replace_dossier` | Save a verified full replacement | Prior snapshot/reason remain in history; existing thread receipts are not reset |
+| `delete_dossier` | Remove the current dossier | Person and transactional before/after history remain; no new blurb injection |
+| `soft_delete_person` | Mark unavailable and turn injection off | Identity/dossier/history remain; creates a review todo |
+| `restore_person` | Mark active again | Injection stays **off**; inspect and explicitly re-enable if appropriate |
+| `set_injection` with `enabled:true` | Enable the person-level injection gate | Still needs global whispering, host permissions, a dossier and an unserved thread |
+
+Slack deactivation marks the **whole linked person** unavailable and disables
+injection, even when other identities are linked. Directory sync skips unavailable
+people rather than automatically restoring them.
+
+Tool inputs for a deliberate pause and later restore/re-enable, using an actual ID:
+
+```json
+{ "action": "set_injection", "personId": "PERSON_ID", "enabled": false }
+```
+
+```json
+{ "action": "restore_person", "personId": "PERSON_ID" }
+```
+
+`restore_person` is for an unavailable person, not a paused active person. After
+inspection, use `set_injection` with `enabled:true` for either one when wanted.
+None of these operations erases raw memory or dossier history.
+
+`memory_people_inspect`'s `injectionEligible` and `contribution` are a
+**record-level preview**, not proof that a hook will inject: they do not account
+for the global whisperer switch, host permissions or an existing thread receipt.
+Changing a dossier or restarting the Gateway does not re-inject it in an already
+served thread. A same-run retry replays its saved contribution; a different thread
+can receive the current blurb. Do not delete receipts as routine troubleshooting.
+
+For agent research/write steps and the dossier schema, use the packaged
+[People Whisperer skill](../skills/people-whisperer/SKILL.md). If the agent has a
+skill allowlist, include `people-whisperer`. General [search and session filtering](retrieval.md)
+are shared memory features, not people-specific controls.

package/docs/response-audit.md

@@ -0,0 +1,217 @@
+# Response quality and sentiment
+
+[Overview](../README.md) · [Configuration and credentials](configuration.md)
+
+`responseAudit` evaluates bounded human-agent exchanges in the background. It is
+separate from chunk-quality auditing and never changes memories or prompts. It
+creates private response-review tasks, not memory-curation tasks.
+Its primary purpose is tracking delivery quality over time: visible fulfillment,
+deliverable fit, clear underdelivery and its observable reason. Memory gaps are only
+an optional diagnostic lead, not a proxy for performance.
+
+This reads the host transcript database directly: it does not require a `sessions`
+corpus, People Primer, whisperers or clustering. Configure [shared TypeSafe
+credentials](configuration.md#shared-typesafe-credentials) separately. Begin with
+the dry-run command below before requesting inference.
+Only approved Slack sender IDs with trusted `senderKind: human` or owner metadata
+qualify (older Slack records use unknown senderKind even for known owners).
+Explicit bots, unverified identities, internal messages, other senders and thread changes form
+hard boundaries. Synthetic delivery mirrors and gateway-injected answers are excluded.
+Assistant progress messages are grouped with the terminal answer.
+Recognized Slack envelopes are stripped even inside `upstreamUserText`; embedded
+history is not treated as current human text. Ambiguous envelopes are excluded.
+Removed history marks the context as limited; ordinary Markdown/JSON is preserved.
+Human feedback closes when the next assistant turn starts. Still-open feedback,
+no-response exchanges, incomplete/failed turns and oversized inputs are not graded.
+
+Place this fragment under `plugins.entries.unblock-memory.config`. The optional
+`memoryCorpora` names must already exist as file corpora; use `[]` to omit memory
+investigation while still tracking response quality and sentiment.
+
+```json
+{
+  "responseAudit": {
+    "enabled": true,
+    "sentimentEnabled": true,
+    "senderIds": ["YOUR_SLACK_USER_ID"],
+    "chatTypes": ["direct"],
+    "historyMessages": 6,
+    "lookbackDays": 30,
+    "maxEpisodes": 20,
+    "intervalMinutes": 60,
+    "memoryCorpora": ["memory", "knowledge"]
+  }
+}
+```
+
+This is explicit approval to send those exchanges to TypeSafe. Sender IDs apply
+across the agent's Slack accounts; use only identities approved in all such accounts.
+`memoryCorpora` is optional and separately approves configured **file** corpora for
+memory-gap investigation. Leave it empty to send no indexed memory evidence.
+`typesafe.enabled: false` or missing credentials prevents evaluation. An interval
+of zero means manual-only. Defaults are disabled, no approved senders, direct chats,
+6 preceding visible messages, 30 days, 20 episodes per run and a 60-minute interval.
+`sentimentEnabled` defaults to **true within that opt-in audit**; it does not bypass
+approved senders or TypeSafe credentials. Set it false to omit polarity, annoyance,
+frustration and intensity questions while retaining quality/repair judgments.
+`intervalMinutes` controls their shared cadence; no second sentiment timer is needed.
+For example, `720` means every 12 hours; `0` means manual-only. `maxEpisodes`
+defaults to 20 per run (maximum 100), so one scheduled run may not clear a backlog.
+The Gateway checks a durable per-agent due time on startup and every minute (no
+agent-turn cron or separate launchd job). First enablement waits one interval;
+restarts preserve the due time and an overdue schedule gets one bounded catch-up,
+not one run per missed interval. Each attempt advances the due time before work,
+including missing-key skips, failures or interrupted runs, to prevent retry storms.
+Changing the interval recalculates the due time from the last scheduled attempt
+(or initial enablement). The Gateway must be running; manual audits do not change
+the automatic schedule. Missing/unreadable credentials skip all quality and sentiment
+inference without failing Gateway startup or normal memory functionality.
+Changing the interval does not invalidate cached results. Changing the sentiment
+toggle selects a separate reporting cohort, so older missing sentiment is not
+treated as neutral; unchanged quality/feedback stages are reused across the toggle.
+
+Operator commands (not agent tools):
+
+```sh
+openclaw memory-responses audit --agent main --dry-run
+openclaw memory-responses audit --agent main
+openclaw memory-responses report --agent main
+openclaw memory-responses report --agent main --episode EPISODE_ID
+openclaw memory-responses report --agent main --sender SLACK_USER_ID --account ACCOUNT_SCOPE --bucket day --since 2026-09-01 --until 2026-10-01
+openclaw memory-responses report --agent main --person PERSON_ID
+openclaw memory-responses tasks --agent main
+openclaw memory-responses review --agent main --id TASK_ID --status deferred --reviewer human --note "Review the linked exchanges before changing preferences"
+openclaw memory-responses annotate --agent main --date 2026-09-18 --kind prompt --note "Known prompt revision deployed"
+openclaw memory-responses retry-failed --agent main
+```
+
+Reports group by scoped human identity as well as task/model/time. Names are not
+identity keys. Existing active people-store links are resolved read-only at assessment
+time; missing links do not prevent analysis. Unknown account scopes stay isolated
+per session. No new identity fields are sent to TypeSafe. Date ranges are UTC with
+an inclusive start and exclusive end. `periodStart` identifies a day/week bucket;
+legacy `week`/`fromWeek`/`toWeek` fields remain aliases. `--task-type` and `--model`
+further narrow comparisons. Human-specific scores are not rankings of the humans:
+task difficulty, feedback habits and selection bias remain important.
+
+Session checkpoints hash bounded active source bytes; unchanged sessions skip
+extraction and all inference. Changed sessions are re-extracted within the existing
+budget, then stage hashes reuse unchanged quality, feedback, sentiment and later
+evidence judgments. Only hashes/counts are checkpointed, never a transcript copy.
+A persisted cursor rotates through discovery and tracked-session reconciliation;
+`deferredByLimit` includes known backlog and a lower-bound marker for unvisited
+sessions. `stages` exposes pending/failed/succeeded counts and exhausted retries
+for the cohort/date range, before person filters. `retry-failed` only resets failed
+work; successful stages remain cached. Source freshness is checked before activation.
+
+Review tasks distinguish `delivery_quality` shortfalls from `human_experience`
+complaints. The latter requires at least 0.8 probability mass at intensity levels
+2/3, at least 0.8 combined mass across agent-related/mixed targets, and annoyance
+or frustration yes-probability of at least 0.8. It uses grouped probabilities, not
+an expected-intensity cutoff or certainty about one precise target. These are
+review leads, not proof the agent was at fault. Status can be `pending`, `resolved`,
+`dismissed` or `deferred`, with a required review note.
+Stable task keys include exchange, scoped human and issue
+family. Decisions survive rescoring; stale source evidence and superseded findings
+are labeled separately. Review status/provenance never changes the raw judgments.
+Tasks and change annotations are operator-only and stay out of memory/whisperer
+prompts. `--reviewer` records human/agent provenance, not authentication or a new
+permission grant. Task lists disclose their 1,000-item cap. There are no automatic
+dossier updates: review the evidence and approve any concrete preference separately.
+Old cohorts remain stored; the first staged-cohort run does not silently import
+unverified older rubric judgments. Audit-history retention is not automatic.
+
+Separate original-answer and feedback passes prevent human feedback from influencing the original
+fulfillment/deliverable-fit grade. The feedback pass distinguishes acceptance,
+correction, continuation, unrelated replies, expressed sentiment, repeated constraints
+and avoidable rework. Current-index memory investigation runs only for a strong
+memory-gap signal: lexical retrieval selects up to three whole short documents from
+approved collections. This is an investigation lead, **not proof of historical
+availability, factual truth, or agent fault**. Tool-call counts do not establish what
+the model saw or whether it should have searched. Unseen artifacts are unassessable.
+
+Deliverable kind/format/scope has its own assessability gate, independent of whether
+execution or external facts can be verified. Feedback attribution distinguishes the
+current answer, earlier behavior, delivery, missing proactive action, external events,
+new work and mixed/unclear targets. A reported forgotten instruction does not prove
+searchable memory existed. A third, separate request examines the original exchange,
+human feedback and available next assistant block for specific reported shortfalls,
+acknowledgment, explicit factual corrections, delivery failures and regressions. These are
+retrospective signals, not independently verified facts and never inputs to the
+original grade. Clean text preceding a synthetic error/delivery notice can be assessed
+as **partial** evidence; the notice itself is excluded and no successful completion
+is inferred. Later evidence is capped at six messages/12K characters; incomplete,
+unsafe or oversized blocks stay explicitly pending/unavailable/oversized. New later
+evidence changes the input hash; only changed assessment stages are re-evaluated,
+within normal audit budgets. Successful stages survive failures in later stages.
+When the next block is unavailable, the third pass uses only the original exchange
+and feedback; it cannot infer a missing delivery from missing later evidence.
+
+Code combines narrow, confident evidence into an **observed outcome**, preserving
+its basis and reason. A concrete original-answer shortfall or later admission takes
+precedence over praise. Broad reported failures are used only when they do not
+depend on a newly introduced requirement. Accurate explanations of earlier mistakes,
+ordinary follow-ups, necessary clarification and unseen work are not automatically
+failures. Sentiment and earlier-workflow complaints remain separate review signals.
+Sentiment includes independent annoyance and frustration yes-probabilities (both
+can apply), plus an expressed-dissatisfaction intensity score from 0 to 3. Intensity
+means no expressed displeasure / restrained displeasure / pointed complaint /
+explicit rejection or loss of trust. It is **not confidence or failure severity**.
+External frustration, brevity and factual corrections alone do not establish
+annoyance or frustration; mixed praise and complaints can still carry both signals.
+Daily/weekly reports show dissatisfaction, annoyance and frustration rates, intensity
+means, unknown counts and their own assessment denominators. Unassessed results
+are never counted as neutral. Sentiment deltas require 20 samples in both periods
+and matching assessment coverage; they remain descriptive, not causal evidence.
+Outcome, evidence basis and failure reasons remain distinct: a correction does not
+automatically mean `incorrect_claim`. Confident reason judgments and direct
+delivery/regression admissions supply reasons; otherwise `reasonStatus` is
+`uncertain`. `reasonDetails` retain each label's source and strength, distinguishing
+Choice confidence from Noul yes-probability. Multiple supported reasons can coexist.
+`reportVersion` identifies composition/reporting semantics independently of the
+judge rubric, allowing cached judgments to be re-reported without re-inference.
+
+Results live in operator-only tables in the agent's private
+`unblock-memory/unblock-memory.sqlite`, outside the memory index. These tables
+are not searched or injected into agent prompts. They store judgments and source event references/hashes, not copies
+of conversations. Identical successful inputs are cached; source rewrites invalidate
+in-scope results on the next scan. Reports partition by fixed judge/rubric/context
+configuration, scoped human, UTC day/week, task type and agent model. They expose eligible/assessed
+counts, excluded cases, confidence-qualified score means with per-dimension denominators, rework rates with Wilson
+intervals, and evidence IDs. Small groups (<20) are marked explicitly. Confidence
+thresholds are provisional, not calibrated guarantees. Human-reviewed evaluation
+data is still needed before drawing performance conclusions.
+Reports include dated clear-underdelivery examples and reason counts. Descriptive
+score deltas compare successive available UTC buckets within the same human, task type,
+agent model and rubric/configuration, with at least 20 confident scores per dimension
+in each period and unchanged scored coverage; changed coverage withholds the score
+delta. Outcome trends show acknowledgment, reported-shortfall and unknown rates
+against **all evaluated exchanges**, with at least 20 evaluated exchanges per period.
+Read the three rates together: fewer acknowledgments can mean more unknowns, not
+more failures. Every delta includes before/after values, sample counts, denominator
+and coverage-change flags. Unknown task types/models cannot produce deltas. These
+are not statistical change-point detections or proof of causality; model/version
+changes remain visible as separate groups rather than silently mixing cohorts.
+The legacy `observedSuccessRate` group field remains acknowledgment / known outcomes
+for compatibility, but is not used for trends. Unknowns are never successes.
+Coverage changes and threshold variability can move rates; acknowledgment is not
+factual verification. Week buckets
+may be partial, and several exchanges in one session are not independent. Wilson
+intervals are descriptive, not calibrated confidence about overall agent ability.
+
+Each run selects at most 100 recent sessions for inference, each at most 2,000 active events/2M
+characters; episodes must fit 24K characters and six feedback messages without
+truncating the answer. Coverage counts describe the scanned sessions; only episodes
+within `lookbackDays` are judged. Caps, failures and no-feedback cases remain visible.
+Saved sessions in the report window are also reconciled independently of that
+selection, so removing an entire active branch retires its scores. Oversized saved
+sessions defer reconciliation rather than being treated as deleted; the report
+exposes `reconciledSessions` and `reconciliationDeferred`. All reconciliation shares
+the run deadline. Freshness checks compare the assessed episode, not unrelated
+later session activity. Actual snapshot races do not exhaust provider retries.
+The whole run has a two-minute deadline, at most three provider attempts per input (ten-minute
+backoff), and a cross-process lease. Scheduling never starts inference on the agent
+turn path or boots a QMD manager. No model downloads or source re-indexing occur.
+The report is observational: different task mixes, selective human replies and judge
+changes can produce apparent trends. It does not automatically declare regressions,
+rewrite prompts, or treat silence as success.