Skip to main content

mindslice-flow

Mount, settle and bake MindSlice memory stage by stage.

A flow is a list of stages, each with its own set of slices. While a stage is played, only its slices are mounted, and its director cards (cards with load = "always") are the agent's standing instructions. When the user ends the stage, the agent tidies what the stage left in @overlay, and mindslice-flow next bakes it into one cumulative state slice (@story by default, a new version per stage) and mounts the next stage. The first use is a multi-act tabletop / interactive story.

The flow is a small state machine on top of the mindslice command. It starts no agent and calls no model: the player plays in their own harness, and the agent runs next for them when they ask.

Python 3.12+, standard library only. Needs mindslice 0.1.6 or newer on PATH.

A flow definition

my-script/
├── flow.toml
└── slices/
    ├── world.slice/      # mounted in every stage
    ├── act1.slice/       # its load = "always" cards are the director cards of act 1
    └── act2.slice/
name = "迷雾庄园"
state = "story"                      # alias of the cumulative state slice (default "story")
mount = ["slices/world.slice"]       # mounted in every stage, relative to flow.toml

[[stage]]
id = "act1"
title = "第一幕:抵达"
mount = ["slices/act1.slice"]        # this stage's own slices

[[stage]]
id = "act2"
title = "第二幕:晚宴"
mount = ["slices/act2.slice"]

A slice mounts under the alias of its slice.toml, else under its directory name without .slice; either must be letters, digits, _, . or -, so a directory with another name (世界.slice) needs an alias. flow.toml is read again by every command, so later stages can be edited during a run. examples/manor is a complete three-act flow.

Commands

Command Does
mindslice-flow check FLOW_DIR check the definition; warn about stages without a director card
mindslice-flow init FLOW_DIR [-o WORKSPACE] create a workspace for one run and enter the first stage
mindslice-flow status stages, mounts, overlay cards left to settle, changes waiting for review
mindslice-flow next [--to STAGE] settle the current stage and enter the next one (or STAGE)

The workspace is found like mindslice finds it: -w, else $MINDSLICE_WORKSPACE, else the nearest directory with mounts.toml. Each run gets its own workspace; the flow owns its mount table.

next refuses while changes wait for review (decide on them with mindslice review, apply or discard), bakes every @overlay card into the state slice, mounts exactly the next stage's slices plus @overlay, the state slice and @flow, and rewrites the @flow cards. It writes its state last, so running it again after an interruption finishes the same switch. After the last stage it marks the flow finished; next --to STAGE plays a stage again. To undo a stage's bake, use mindslice rollback @story --yes and then next --to.

Playing

  1. mindslice-flow init examples/manor -o manor.run
  2. Point your harness's MindSlice at the workspace (for the Claude Code plugin, set its workspace option; otherwise MINDSLICE_WORKSPACE, or the MCP server mindslice -w manor.run mcp).
  3. Start a session. The standing memory holds the director card and the flow's stage card (@flow/stage). When the stage's end condition is met, the agent says so; you can keep exploring.
  4. Ask the agent to end the stage. It follows @flow/settlement: tidies the overlay, writes the stage summary summaries/<stage-id>, shows you the result, and runs mindslice-flow next once you agree.
  5. Start a new session for the next stage (or let the agent call manifest again to continue).

The stage cards are rendered from mindslice_flow/cards/ and carry the workspace's absolute path, so the agent never has to guess it.

Not in this version

  • Turning a script document into slices, director cards and flow.toml.
  • Branch conditions, automatic stage ends, or driving harness sessions.
  • Hiding future stages: their files stay on disk, they are only not mounted or searched.

Development

python -m unittest discover -s tests -t . -v

The functional tests run the example flow with the real mindslice command and no model. CI runs them on Linux, Windows and macOS against both the newest mindslice on PyPI and the oldest supported one (MINIMUM in mindslice_flow/engine.py), on every push and weekly.

License

Apache-2.0

Metadata

Release files for mindslice-flow 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mindslice-flow 0.1.0
File Size Uploaded Provenance Actions
mindslice_flow-0.1.0.tar.gz 24.0 kB With provenance Details for mindslice_flow-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mindslice-flow 0.1.0
File Interpreter ABI Platform Actions
mindslice_flow-0.1.0-py3-none-any.whl Python 3 none any Details for mindslice_flow-0.1.0-py3-none-any.whl

Total release size: 44.2 kB

Release files / mindslice_flow-0.1.0.tar.gz

Download URL mindslice_flow-0.1.0.tar.gz
Size 24.0 kB
Tags Source
SHA-256 checksum
How to use checksums
8fd19d09da4954ed975fbf98f9dd5c1d30ad013265b1890b5bd2e7df375403dc
BLAKE2b-256 checksum
How to use checksums
61822dd3a015d9a221a692c96b58a2418cd4ad5861920d0a93befe75c8881d6a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / mindslice_flow-0.1.0-py3-none-any.whl

Download URL mindslice_flow-0.1.0-py3-none-any.whl
Size 20.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b992f6f8a1a3ab687a5104da834fd1edcea72b23a2b3f91a6af15dc610b50712
BLAKE2b-256 checksum
How to use checksums
39a78391d64498f2402190d649872590320bc8e3012ea7c632ec30f4bd5414bd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for mindslice-flow 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mindslice_flow-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page