Skip to main content

​
What It Does

Every workspace has one Observer: a hidden recorder that logs each top-level command and its file ops as timestamp-ordered events. It owns no mount and has no endpoint of its own, features like command history are just views over its events. Nested evals ($(...), eval, source, xargs) run without recording, so only real top-level commands land.

​
Storage backends

The Observer holds a storage-agnostic ObserverStore. RAM is the default; swap it to persist events across daemon restarts. The store is chosen at construction; there is no runtime API to change it. 
from mirage import Workspace, MountMode
from mirage.resource.ram import RAMResource
from mirage.observe.disk_store import DiskObserverStore
from mirage.observe.redis_store import RedisObserverStore

# RAM (default), nothing to configure
ws = Workspace({"/data": RAMResource()}, mode=MountMode.WRITE)

# Persist to disk
ws = Workspace({"/data": RAMResource()}, mode=MountMode.WRITE,
               observe=DiskObserverStore("/var/mirage/history"))

# Persist to Redis
ws = Workspace({"/data": RAMResource()}, mode=MountMode.WRITE,
               observe=RedisObserverStore("redis://localhost:6379/0"))

​
Supported: command history

The Observer powers a GNU-bash-compatible history, exposed two ways over the same events:
SurfaceScopeNotes
history builtincalling sessionGNU flags -c -d -a -n -r -w -s -p and a count arg
/.bash_history mountall sessionsread-only, GNU histfile format (#<epoch> then the command)
Because /.bash_history is a real read-only mount, the ordinary file commands work on it directly: 
history 5
tail -n 6 /.bash_history
grep cat /.bash_history
The format is GNU bash (#<epoch>), not zsh (: <ts>:<dur>;<cmd>).

​
Snapshots

History is part of the workspace state: the Observer’s command, clear, and delete events are captured into a snapshot and restored on load, so a restored workspace replays with the same history. The /.bash_history view mount itself is not stored, it is a live projection rebuilt from the events.