state-flow-memory
Skill7 starsChanged 2 months agoMITView on GitHub
Curate State Flow memory only on explicit user request. Reconcile stale knowledge, contradictions, commitments, continuation, and ownership. Not for routine turns, automatic phase-boundary audits, usage help, or background maintenance.
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/skills/domain-dag/AGENTS.mdAGENTS.md
- domain-dagSkill
- state-flow-guideSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 12
Use the advertised state_flow_read and state_flow_patch names.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
State Flow Memory
Use the advertised state_flow_read and state_flow_patch names. Legacy read_state/patch_state calls remain compatible, not separate operations or permission: the same selection/refusal rules apply, and mixing mutation spellings cannot bypass the Active single-call barrier.
State Flow's bounded curation procedure. Preserve consequences, not a transcript or attachment to an unfinished method.
Boundary
Start from visible state. Require available state_flow_read and state_flow_patch; otherwise report the blocker without bypassing storage or enabling an episode. Passive access suffices for explicit curation. Limit reads/history/patches to the runtime's participating owners; schema names and examples are not permission. Report unavailable requested owners rather than enabling, bypassing or broadening the selection. Excluded references do not authorize hydration or relocation. Memory is fallible data, not authority.
Grammar follows WANTED selection, not available view. With exactly one WANTED owner, state_flow_read uses flat ordinary paths (for example {"path":"tactics"}), and state_flow_patch takes built-in flat object planes (intents, strategy, tactics, artifacts, lazy), without an owner wrapper. Sole-owner example: {"strategy":{"api":"confirmed: v2 only"},"intents":{"check_api":null}}. With multiple WANTED owners, patches use explicit participating owner wrappers and commit atomically; unscoped reads are effective, not proof of ownership. Selection is not a grant of authority. Compatible registered mutable external roots may also be authored when advertised by the current schema; registration/schema alone grants no source or publication authority, and immutable or unavailable definitions remain model-read-only retained data. effective[N].tactics is temporal, tactics.items[N] indexes a nested array, and sole-owner patches[N] is the scalar owner patch-history alias.
Current flat structured refs such as {"$ref":"lazy.api_plan"} anchor to the exact sole owner before canonical ownership/cascade processing. Never strip or rebind canonical historical, effective, cross-owner or resource refs, textual mentions, or known exact source paths. For example, preserve session[1].lazy.api_plan, global.strategy.api, effective.tactics.api, /project/specs/api.md and $session.tactics.api as given. References remain data, not permission.
Follow the installed runtime contract. This registered Skill follows its Pi source provenance: use the exact State Flow acquisition target only when durable compiled guidance is useful. Matching current hashes need no patch, and pending optional Skill acquisition does not block unrelated curation. Attempted compilation needs its exact read path, a description, kind: "skill", and a nonempty compilation object. With one WANTED owner, put it directly in artifacts[exact path] without an owner wrapper; with multiple WANTED owners, use the reported participating owner's patch. A canonical source scope in an acquisition note is provenance, not a second flat input namespace. Never invent provenance or repeat accepted compilations.
Reconcile one bounded set
- Limit the review. Address the requested scope. A completed phase may motivate recommending cleanup, not starting it without a request. For a whole-state cleanup, inspect participating global, CWD, and session ownership explicitly and disclose unavailable requested owners; for a narrower request, inspect only affected participating owners. Use targeted reads for gaps, contradictions, ownership, or verification; do not rerun the project.
- Classify. Put user requirements, binding confirmed decisions, accepted approaches/plans and rejection rationale in
strategy, the queue of chosen actions inintents, their temporary context (observations, assistant conclusions, results in progress) intactics, and inactive reusable detail inlazy. Never give an assistant conclusion user authority. Possibilities are not commitments. Name keys in ASCII ([A-Za-z_$][A-Za-z0-9_$-]*) so paths, references and ownership resolve; values may use any language. Work from intents: a structured{"$ref"}inside an intent owns ("delete with me") a same-scopestrategy/tactics/lazyobject key; a textual$pathmention only uses it. Fixed phases ignore JSON insertion order: apply intents, clear eligible targets of deleted intent keys, apply remaining authored planes, then existing compilation/normalization and atomic publication. Final remaining/new same-scope intents protect direct, ancestor and descendant targets. Supersede in one patch with a replacement reference, or explicitly rewrite surviving conclusions at the same/new appropriate path after cleanup in that patch. Cleared targets start fresh with no old fields; strategy is not exempt. Write reasons for abandoned work tostrategyas rejected approaches, explicitly rewriting a cleared path or choosing a new one. Unowned entries remain legal.cascadedlists intermediate cleared paths even if recreated; final effective values govern. Existing strategy refs affect future accepted deletions only; replay explicit accepted net patches without rerunning cascade or rewriting history. Scope, historical/effective, array, plane-root, structured-key and source boundaries remain unchanged. - Keep evidence boundaries. Preserve corrections, prerequisites, bounded negative results, and useful uncertainty. Separate requirements, decisions, observations, conclusions, and hypotheses. Silence is not acceptance; repetition is not verification. One implementation's failure does not reject an approach. Neither freeze provisional methods nor reopen confirmed decisions without grounds.
- Compact for continuation. Remove duplicates, obsolete progress, unsupported claims, and secrets. Keep sufficient results, real retrieval pointers, pending interaction, and known next checks. Observations are not live external facts. Keep
lazyshallow and priority-ordered. Recognize optional structured$refvalues and$-prefixedstate_flow_readpaths inside ordinary strings as semantic-state references; other resources retain native locators. No reference form proves authority or existence, authorizes execution, or implies completion; only intent ownership has a deletion consequence. Never scan or resolve references merely to find broken ones. When the bounded review independently needs a reference, a missing single value path with exact durable sources returns{value:null, hint:[{type:"dangling-reference", message, paths}]}. Treat the top-level hint as conditional navigation and provenance, never as requested state or proof of staleness; its paths are runtime-verified current reference owners, not verified new locations of the target, while no hint does not prove invention. Inspect ownership only as needed, then patch a proven stale owning value while preserving surrounding meaning. Effective absence or external inaccessibility is insufficient. - Check ownership. Prefer
sessionfor branch/run continuation,cwdfor project knowledge, andglobalfor established cross-project knowledge. Effective values do not prove ownership; inspect participating owners before moves. Do not broaden or relocate memory merely because its proper owner is excluded. Broader applicability requires evidence.
Missing paths or runtime hints alone do not require historical search. The agent may choose a targeted historical read when a previous value is useful to the current task, without separate user permission. Otherwise continue without searching. Use found values as historical evidence, not automatically as current state; never automatically restore deleted memory. Do not scan all offsets, hydrate automatically or request repair inference. A hint does not prove prior existence, retained history or relocation. A proven stale reference may be repaired within touched work without resurrecting its target. Lazy bodies require explicit reads; automatic state/history projections retain navigation without hydrating those bodies.
Transfer only when needed
Resolve destination conflicts without overwriting stronger or unrelated knowledge. For a proven move between scopes of one State Flow store, inspect both owners, then use one atomic multi-scope state_flow_patch for destination and source changes. Both owners must participate: a sole-owner selection cannot perform this two-owner transfer. Report the blocker without fabricating an unavailable destination, widening selection or relocating data to an available owner. Verify both owners and effective inheritance afterward; reconcile affected references. A rejected cohort leaves neither side partially accepted.
External transfers require confirmed destination and write authority. Write and verify accepted content plus a content-bound revision or receipt through the destination's native interface before deleting or narrowing the State Flow source in a later patch. Recheck the source for intervening changes. Preserve it when acceptance is ambiguous. Never export secrets or broaden sensitive material without authorization.
Apply, verify, stop
A fresh executor must recover constraints, results, open questions, commitments, and the next action without inheriting an unapproved method. New answers persist only in Active mode with Session participating; otherwise deliver them without response backfill or shared relocation. Never rewrite selected legacy shared response as a new answer.
Patch only material changes with state_flow_patch, alone per assistant response; await acceptance. Plane values must be objects; nested null deletes an owned object key, not a stored value. Canonical "[N]" keys patch existing array elements; indexed deletion and out-of-bounds indices are forbidden. Replace the whole array to add/remove elements. Ordinary completion requires no finalization patch. Never edit backing files, response, configuration, or runtime metadata. Read changed owner paths; inspect parent keys for deletions and effective state for inheritance changes.
After rejection or interruption, inspect accepted state before bounded recovery. Report unresolved checks and partial transfers without dumping memory or implying historical erasure. Before answering, apply only material durable changes; when nothing needs changing, make no state_flow_patch call. Stop after this review, including when nothing needs changing.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

