memory_write
Persist conversation details as structured memories with scopes, categories, and optional grounding checks against the codebase to prevent stale claims.
Instructions
Create a new memory. Call PROACTIVELY when something durable enters the conversation — aggressive writing is safe; the guardrails below catch bad writes. Trigger→category mapping: the server instructions block.
Parameters:
content: the memory body.scopes: non-empty list. Avoid the catch-all 'general'; prefer narrow tags liketools,infrastructure,projects:<name>,learning-style.category(default 'fact'): one offact,user-inference,ambient.fact: project / infra / reference / tooling. Commits immediately (unlessrequire_write_confirmation).user-inference: claims ABOUT THE USER. Always returns {status:'pending', pending_id} regardless of config — ask the user in plain language, then memory_write_confirm or memory_write_cancel. Misattribution sticks; user gets the veto.ambient: atmospheric context that shapes replies without being cited. Commits like fact but excluded from dead-weight curation; long bodies (>500 words) attach a non-blockingambient_body_longwarning.
confidence('low' / 'medium' / 'high'),source('explicit-statement' / 'inferred').claims(optional): claims the body makes about this repo —path,path::symbol,path::NAME=literal. Checked against the worktree NOW (false ⇒ refused); drift then watches the claimed bindings, not whole files. Declare when citing code.groundedness_check=True+source_transcript: optional gate. Sentences with <30% token overlap to the transcript return {status:'ungrounded', claims:[…]}. Override viaacknowledge_ungrounded=Truewhen you have grounding sources outside the transcript (file reads, tool results). Off by default; opt in for a paper trail.
Return statuses:
committed— write succeeded; payload carries the new id andrelatedmedium-overlap matches.duplicate— content dedup fired; the matched memory is credited a corroboration (corroboration_recorded: true, once per session) — recurrence is evidence; thehintcarries the remedy.transient_warning/credential_warning/previously_removed/scope_mismatch— gate rejects. Each returns what matched and ahintcarrying the remedy and itsacknowledge_*/force=Trueoverride.user_claim_warning— the body reads as a claim ABOUT THE USER butcategoryisn'tuser-inference. Re-issue as that (the user gets the veto) or passacknowledge_user_claim=Trueif the subject is someone else.pending—category='user-inference'orrequire_write_confirmation.pending_reasondistinguishes.ungrounded— groundedness gate fired.
A committed or memory_write_confirm response may inline a one-shot per-session curation_hint block when dead_weight + drifted + cold_endorsement_memories pressure crosses the configured threshold. Shape: {pressure, threshold, counts: {dead_weight, drifted, cold_endorsement_memories}, message}. Passive notification — call memory_health for full buckets, memory_remove / memory_verify to resolve.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | ||
| claims | No | ||
| scopes | Yes | ||
| source | No | explicit-statement | |
| content | Yes | ||
| category | No | fact | |
| confidence | No | medium | |
| source_transcript | No | ||
| groundedness_check | No | ||
| acknowledge_transient | No | ||
| acknowledge_credential | No | ||
| acknowledge_ungrounded | No | ||
| acknowledge_user_claim | No | ||
| acknowledge_scope_mismatch | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||