Skip to main content
Reflect supplies reflect_bash, an embedded shell for searching and editing a virtual filesystem. Agents use ordinary commands instead of a collection of specialized rule tools.

The agent’s filesystem

These paths exist inside the supplied tool, not at the root of your computer. The embedded interpreter supports file utilities, pipes, loops, and heredocs. It has no host mounts, inherited credentials, network access, external programs, or Python execution.

Retrieve relevant guidance

The native integration tells the agent where memory lives. The agent chooses what to search and read:
Reflect does not automatically insert the whole rule corpus or choose rules with a static retrieval policy. File and output limits bound the supplied tool; they do not bound the agent framework’s full conversation history.

Write a useful rule

A rule needs a title, an Applies to: line, and actionable guidance. Directories provide scope; applicability is descriptive text the agent interprets.
At the boundary, Reflect compares all working rules with the pinned accepted revision. The diff becomes one proposal. The Markdown text is normalized and versioned by content hash.
  • No change produces no_proposal.
  • Exact repeated changes and normalized duplicate guidance are detected.
  • Invalid rules or stale bases produce explicit outcomes.
  • Semantic overlaps and contradictions require reasoning and validation; exact deduplication is not a semantic memory system.

Keep memory small

The agent can merge overlapping rules, shorten guidance, move files, or remove obsolete rules using ordinary shell commands. These changes still require independent validation before they alter shared accepted guidance. The default active corpus permits 256 rules, 8 KiB per rule, and 512 KiB total. A smaller corpus can be accepted as maintenance when paired validation meets its non-inferiority checks. That verdict does not claim improved behavior.

Active notes are different from accepted rules

/context.md is a bounded scratchpad, 8 KiB by default:
Native integrations refresh a replaceable active-memory block at their supported checkpoints. Notes can carry into the same session at the same accepted revision, but are unvalidated working memory. Notes associated with candidate rule edits are not reused in a fresh ordinary view. Validation starts with fresh local memory. Reflect does not rewrite or compress the rest of the conversation. Keep native framework sessions/checkpoints for conversation history.

The durable workspace on disk

To inspect accepted rules, follow state.json → head → the matching revision’s rules/. Working proposals and notes are separate from that accepted directory. Do not edit the immutable revisions or lifecycle records to publish a rule. The identity directory is derived from endpoint, project, and API key; changing credentials changes the partition. Use a persistent local volume and a separate writable workspace for each language/deployment. Python and TypeScript have equivalent behavior, but simultaneous mixed-language writers are not supported.
The shell cannot reach authoritative storage. Other unrestricted host tools may be able to: keep that storage outside their writable environment. Historical revisions and evidence are not automatically pruned by active-rule limits. See Operations for retention and access controls.