2 Usage
Run mindstream-new (default: C-c , n) to start a session.
Write!
Save the file at your regular cadence after making a few changes to it. If you pull up a Magit window, you’ll notice that there is a distinct commit recorded in the underlying Git repo for your session each time that you saved the file. You can also create new files at the same path, and changes to any of them would also be similarly tracked.
You may notice that there is only one template available to use for your first session. This is because Mindstream creates a simple text template in ~/.emacs.d/mindstream/templates/ if it doesn’t find any there. You may want to add more templates that are relevant for you. Let’s see how to do that.
2.1 Adding New Session Templates
Mindstream doesn’t include any templates out of the box, so you’ll probably want to create some for standard sessions you are likely to need, for instance, for programming in your favorite language (perhaps Racket?), or just freewriting some text for your next great novel, following in the keystrokes of Emacs octopuses like Neal Stephenson.
To add a new template, visit mindstream-template-path (default: "~/.emacs.d/mindstream/templates/") in your file manager of choice (e.g. Emacs’s dired, or just a command line), and create a folder there with the name of your template (e.g. racket). The folder should contain an ordinary file (or multiple files) with the appropriate extension (e.g. .rkt – it could be anything at all that you typically use Emacs to edit). This template will now be available as an option in mindstream-new.
2.2 Saving Sessions
You can also save scratch sessions that you’d like to keep by using mindstream-save-session (default binding: C-c , C-s). This simply clones the session’s Git repo to a more permanent and familiar path that you indicate (as opposed to the anonymous session path which is assumed to be ephemeral and defaults to ~/mindstream/anon), thus preserving the entire session history, allowing it to be navigated and even resumed at any time in the future.
2.3 Entering Sessions Even More Quickly
mindstream-enter-anonymous-session (default: C-c , b) will take you immediately to an anonymous session for the current major mode, without asking you any questions. If an anonymous session already exists, it will take you there rather than create a new one. In creating a new session, it will use the first template it finds that is recognizable to your current major mode.
If you’ve got more than one template for a particular major mode, you may want to indicate which one is preferred rather than leave it to chance or accidents of alphabetical order. You can do this by associating each major mode with the name of the preferred template. For example:
:custom ... (mindstream-preferred-template '(racket-mode "racket"))
This customization is only relevant when using mindstream-enter-anonymous-session, as you would select the template yourself when using mindstream-new.
See Design to learn more about anonymous sessions.
2.4 Archiving Sessions
Anonymous sessions at mindstream-path are considered active, that is, they are sessions you are currently in the middle of. Anonymous sessions that have served their purpose, and which you do not save as named sessions, are archived instead, which simply moves them to mindstream-archive-path. These sessions will retain their filing under folders named for their creation date, under folders named for the template from which the session was begun.
anon-or-archive-path/ python/ 2024-09-02/ b6c86878fd8bcddfef3c7b4781f8a3b6694e72b7 ... text/ 2024-09-08/ 2b31e1f7e58ab273709bad1bf47888fb523c49af b914a595b8d2ad567d4e14ab128570207742ce06 ... ...
This path will accumulate hundreds, or thousands, of sessions over time. They are always there and conveniently filed if you need to refer to them, and can serve as a detailed log of your thoughts and work over time. See Choosing an Archive Path for some further considerations regarding the archive.
Sessions are archived either automatically, depending on your customization of session persistence and uniqueness, or manually by you on demand.
You can manually archive a session using mindstream-archive (default binding: C-c , a).
2.5 Live Mode!
Live mode configures Mindstream to automatically take some action that you indicate whenever there is a pause (by default, 1.5 seconds) in typing. Typically, this is used in programming settings to trigger evaluation of the buffer in an accompanying runtime environment.
Live mode is configured by associating each major mode with a desired action to take for sessions in that mode.
For example, use the following config to evaluate your buffer "live" while in Racket Mode:
:custom ... (mindstream-live-action '(racket-mode racket-run))
You can "go live" in any Mindstream session with M-x mindstream-go-live (default: C-c , C-l). If no live action is configured for the major mode, it will simply use the default action of saving the buffer.
Currently, live mode is only supported for individual buffers rather than for the session as a whole, so you would need to "go live" in each session buffer individually.
Go offline with M-x mindstream-go-offline (default: C-c , C-o).
2.6 Mindstream Anywhere
If you have an existing, ordinary file or directory that you were working on at some point, and if you want to continue working on it in a mindstream session, that’s easy enough to do. Simply follow these steps:
Create a new folder (give it a representative name, as you would any Mindstream session) and move the file(s) into it.
At the command line in that folder, run git init.
Open the file in Emacs in the usual way and M-x mindstream-begin-session.
Mindstream sessions are just ordinary Git repositories. If you wanted to, you could use Mindstream in any Git repo simply by M-x mindstream-begin-session after opening a file in the repo, but this isn’t a well-supported use case for the moment (e.g. it would result in a lot of commits, and you would most likely want to manually squash them). For now, if you are interested in mindstreaming an existing repo, try out this workflow by Noboru Ota.
2.7 Explore
Try M-x mindstream- ... to see all the available interactive commands. These are also included as keybindings in a minor mode, mindstream-mode, which allows you to enter a Mindstream session from anywhere, and contains useful commands for active sessions like saving the session, "going live," and so on.
Mindstream commands are bound by default under the prefix C-c , .... You can view all Mindstream commands by using Emacs’s C-h introspection with this prefix, as in C-c , C-h.