About the States category

Artifacts States
,
1

Evolving system-wide artifacts that preserve shared identity, user models, operational conditions, plans, memory, and other maintained context used across BIThub agents and systems.

States

Artifacts > States

States are evolving contextual artifacts maintained for the wider system.

They represent information that may change as BIThub develops, operates, learns, or encounters new conditions.

States are not merely templates. They may be initialized from templates, but their maintained contents become shared operational artifacts that connected agents can ingest and use.

What Belongs Here

  • USER.md

  • SELF.md

  • STATE.md

  • PLAN.md

  • MEMORY.md

  • SNAPSHOT.md

  • HEARTBEAT.md

  • system-wide TOOLS.md

  • current system conditions

  • shared user models

  • ideal user avatars

  • system identity

  • active priorities

  • maintained plans

  • accumulated operational knowledge

  • generated system snapshots

  • other evolving contextual artifacts used across the system

System-Wide Scope

States currently describe BIThub and its shared operating environment.

They are not individual user profiles, private agent memories, or per-project state files.

Examples:

  • USER.md may define ideal user avatars, common user needs, interaction assumptions, and base logic applied across users.

  • SELF.md may define the shared identity, role, boundaries, and operating model of the system.

  • STATE.md may describe current system conditions, active initiatives, known limitations, and operational readiness.

  • PLAN.md may represent current system priorities and intended work.

  • MEMORY.md may preserve durable system-wide knowledge.

  • TOOLS.md may describe tools and capabilities broadly available across connected agents.

  • SNAPSHOT.md may capture the condition of the wider system at a particular point in time.

Individualized States may be introduced later if the system develops the required scope controls, permissions, update procedures, and privacy protections.

States and Indexes

States preserve evolving system-wide context.

Indexes provide complete or authoritative catalogues of available entities, resources, artifacts, models, agents, tools, or relationships.

Examples:

  • shared user models and user logic belong in USER.md under States

  • a catalogue of registered users would belong under Indexes

  • system identity belongs in SELF.md under States

  • a catalogue of available agents belongs under Indexes

  • current available capabilities may be represented in TOOLS.md under States

  • the complete tools registry belongs under Indexes

  • current system priorities belong in PLAN.md under States

  • a catalogue of available workflows belongs under Indexes

States explain the system as it currently understands and operates itself.

Indexes enumerate what exists.

Lifecycle

States may be:

  • initialized

  • generated

  • updated

  • reviewed

  • merged

  • superseded

  • restored from snapshots

Changes should preserve source history, scope, and provenance.

Some States may be updated manually. Others may be maintained through guarded workflows, agent proposals, scheduled processes, or generated system observations.

Use by Connected Agents

Connected agents may ingest relevant States as shared system context.

Agents should:

  • identify the current valid version

  • distinguish maintained State from its template

  • use only the States relevant to the task

  • preserve the intended scope and meaning

  • avoid treating examples as current facts

  • submit proposed changes through the available update process

  • preserve provenance when combining or transforming State

  • avoid independently creating conflicting system-wide versions

No single State should be treated as universally authoritative outside its defined purpose.

Relationship to Templates

A template defines the expected structure of a State.

A maintained State contains the current system-wide information expressed through that structure.

For example:

  • the USER.md template defines what shared user information may be represented

  • the maintained USER.md contains the current user avatars, assumptions, needs, and base rules used by the system

Templates may be reused across systems, while maintained States remain specific to the system they describe.

Navigate