feat(muse): index Muse Code sessions as a first-class source

CHANGELOG.md

@@ -81,6 +81,23 @@ Notable changes to the native `ai-hist` CLI are documented here.
 
 ### Added
 
+- Muse Code (Meta's `muse` CLI) is a first-class source, `muse`. Sessions are
+  read from `$XDG_DATA_HOME/muse/sessions/YYYY/MM/DD/<id>/session.jsonl`
+  (`~/.local/share/muse/sessions` by default) by discovery, `sync`,
+  targeted hydration and live capture: typed prompts become `history` rows at
+  the microsecond time Muse recorded them, and each session gets its prose,
+  readable thinking, tool calls and results (status from Muse's own
+  `tool_batch.effect.terminal` outcome, and a non-zero `bash` exit code),
+  `write_file` / `edit_file` edits, per-model-step token usage (normalized as
+  `per-request`), models, CLI version and lifecycle markers (`turn_end`,
+  `session_start`, `session_resumed`, `session_end`, `model_switch`,
+  `encrypted_reasoning`). Subagent and reminder logs
+  (`subagent/<id>/session.jsonl`, at any depth) are indexed under the child's
+  own session id and linked to their parent as `delegated` children, typed
+  from the parent's `task_stream_linked` record; they are not catalogued as
+  sessions and their objectives are not history rows. A Muse hydration
+  reports `full`. `ai-hist resume` prints `muse resume <id>`, and the sync
+  service forwards `XDG_DATA_HOME`.
 - Read every OpenCode channel database. OpenCode keeps one SQLite store per
   release channel — `opencode.db` for `latest`/`beta`, and
   `opencode-stable.db`, `opencode-nightly.db`, ... beside it — and only
@@ -406,6 +423,9 @@ Notable changes to the native `ai-hist` CLI are documented here.
 
 ### Rust API
 
+- `Source::Muse` and `ProviderRoots::muse` (the Muse Code sessions directory;
+  `from_env` honours `XDG_DATA_HOME`). Both types are `#[non_exhaustive]`, so
+  this is additive.
 - `ProviderRoots` gains `opencode_db_pinned: bool`. `from_env` sets it when
   `OPENCODE_DB` is set; `from_home` leaves it `false`, so every OpenCode channel
   database beside `opencode_db` is read. Set it to read `opencode_db` alone.

README.md

@@ -2,7 +2,7 @@
 
 **Search, resume, and hand off every coding-agent session — across every harness on your machine.**
 
-Local memory for **Claude Code**, **Codex**, **Cursor**, **Grok**, **OpenCode**, and [**Agent Relay**](https://github.com/AgentWorkforce/relay). Your agent sessions are indexed into one local SQLite database. Search them all at once, jump back into a session with its harness's native resume command, and hand a compact context pack to another agent — or to a teammate's agent — to continue the work.
+Local memory for **Claude Code**, **Codex**, **Cursor**, **Grok**, **Muse Code**, **OpenCode**, and [**Agent Relay**](https://github.com/AgentWorkforce/relay). Your agent sessions are indexed into one local SQLite database. Search them all at once, jump back into a session with its harness's native resume command, and hand a compact context pack to another agent — or to a teammate's agent — to continue the work.
 
 ```sh
 ai-hist search "auth rewrite"
@@ -31,7 +31,7 @@ ai-hist search "the thing i was working on"
 
 The bare `ai-hist` command bootstraps a searchable database on first use: it discovers your most recent local sessions and indexes their evidence, then tells you what it found. It leaves an already-populated database alone. Run `ai-hist sync` any time you want a full re-ingest rather than the bounded first-run pass.
 
-RelayHistory follows each harness's configured state directory. Set `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, or `GROK_HOME` to relocate Claude Code, Codex, or Grok data; unset or empty values fall back to `~/.claude`, `~/.codex`, and `~/.grok`. OpenCode uses `OPENCODE_DB`, defaulting to `~/.local/share/opencode/opencode.db`.
+RelayHistory follows each harness's configured state directory. Set `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, or `GROK_HOME` to relocate Claude Code, Codex, or Grok data; unset or empty values fall back to `~/.claude`, `~/.codex`, and `~/.grok`. Muse Code sessions are read from `$XDG_DATA_HOME/muse/sessions` (`~/.local/share/muse/sessions` when `XDG_DATA_HOME` is unset). OpenCode uses `OPENCODE_DB`, defaulting to `~/.local/share/opencode/opencode.db`.
 
 Node.js 20 or 22 is required. `npm install` pulls a prebuilt native addon for macOS (arm64, x64), Linux glibc ≥ 2.28 and musl (arm64, x64), and Windows x64 — no Rust toolchain, compiler, or separate binary download. The glibc floor covers Debian 12, Ubuntu 22.04, Amazon Linux 2023, and RHEL/Alma 9; releases are smoke-tested on `node:22-bookworm-slim` and `ubuntu:22.04`.
 
@@ -52,9 +52,9 @@ ai-hist recent 20                                    # the last N prompts, newes
 ai-hist stats                                        # how much history is indexed, by source and project
 ```
 
-`<harness>` is the session's source — `claude`, `codex`, `cursor`, `grok`, `opencode`, or `relay` — and is required alongside the ID, because session IDs collide across providers. `ai-hist sessions list` prints both.
+`<harness>` is the session's source — `claude`, `codex`, `cursor`, `grok`, `muse`, `opencode`, or `relay` — and is required alongside the ID, because session IDs collide across providers. `ai-hist sessions list` prints both.
 
-`ai-hist resume` prints a native resume command for Claude Code, Codex, Cursor, and Grok sessions. OpenCode and Agent Relay sessions are searchable and packable, but have no native resume command to print, so use `ai-hist pack` to carry that context forward instead.
+`ai-hist resume` prints a native resume command for Claude Code, Codex, Cursor, Grok, and Muse Code sessions. OpenCode and Agent Relay sessions are searchable and packable, but have no native resume command to print, so use `ai-hist pack` to carry that context forward instead.
 
 OpenCode is read from whichever of its two stores the machine has: the SQLite
 `opencode.db` that current releases write (`OPENCODE_DB`), or the older JSON
@@ -114,7 +114,7 @@ Team uploads come from the [Agent Relay desktop app](https://agentrelay.com), no
 
 ## Why `ai-hist`
 
-- **Every harness, one search.** Claude Code, Codex, Cursor, Grok, OpenCode, Agent Relay — indexed side-by-side. No per-harness silo.
+- **Every harness, one search.** Claude Code, Codex, Cursor, Grok, Muse Code, OpenCode, Agent Relay — indexed side-by-side. No per-harness silo.
 - **Provider-aware evidence.** Prompts, tool calls, and edits are preserved as raw evidence, not summarized away — as much of it as each harness actually exposes. Hydration reports `full`, `partial`, or `shallow_only` per session, so you can tell thin coverage from a thing that never happened. Where a harness records less than the others, the gap is named. Cursor transcripts carry the assistant's prose and every tool call, but no tool output, model id, token usage or timestamp field — those are reported as unavailable, and a turn whose injected `<timestamp>` tag cannot be read is stamped from the file mtime with `CURSOR_TIMESTAMP_FROM_MTIME`. Older Grok builds log no per-turn billing tokens, so their only token fact is a context-window proxy, and hydration says so; newer builds' per-turn `usage` breakdown is recorded beside it, never added to it. The per-field detail is in [the session catalog](docs/session-catalog.md).
 - **Local by default.** SQLite on your machine. Export requires an explicit selection; remote acquisition requires an installed source plugin.
 - **Handoff-native.** `pack` and `resume` are first-class commands, not afterthoughts.

crates/ai-hist-cli/src/lib.rs

@@ -417,7 +417,7 @@ enum SessionsAction {
     /// content blocks, agent lifecycle events. Same `(ts_ms IS NULL, ts_ms,
     /// id)` keyset as tool calls and file edits; undated markers page last.
     Markers {
-        /// Coding-agent source (claude, codex, cursor, grok, relay, opencode).
+        /// Coding-agent source (claude, codex, cursor, grok, muse, relay, opencode).
         source: String,
         /// Native session identifier within that source.
         session_id: String,
@@ -441,7 +441,7 @@ enum SessionsAction {
     /// and cost is never computed: `reported_cost_usd` appears only when the
     /// source data carried one.
     Usage {
-        /// Coding-agent source (claude, codex, cursor, grok, relay, opencode).
+        /// Coding-agent source (claude, codex, cursor, grok, muse, relay, opencode).
         source: String,
         /// Native session identifier within that source.
         session_id: String,
@@ -479,7 +479,7 @@ enum SessionsAction {
 enum LearnAction {
     /// Distill local session history into decision/finding/reflection events.
     Distill {
-        /// Only distill sessions from this source (claude, codex, cursor, grok, relay, opencode).
+        /// Only distill sessions from this source (claude, codex, cursor, grok, muse, relay, opencode).
         #[arg(long)]
         source: Option<String>,
         /// Distill one session id.
@@ -2901,11 +2901,13 @@ fn service_command_args(spec: &ServiceSpec, args: &[String]) -> Vec<String> {
     command
 }
 
-const PROVIDER_ENV_VARS: [&str; 4] = [
+const PROVIDER_ENV_VARS: [&str; 5] = [
     "CLAUDE_CONFIG_DIR",
     "CODEX_HOME",
     "GROK_HOME",
     "OPENCODE_DB",
+    // Muse Code keeps its sessions under `$XDG_DATA_HOME/muse/sessions`.
+    "XDG_DATA_HOME",
 ];
 
 fn scheduler_environment_value(name: &str, value: std::ffi::OsString) -> Result<Option<String>> {

crates/ai-hist-napi/src/lib.rs

@@ -1736,7 +1736,9 @@ pub async fn hydrate_session(options: HydrateSessionOptions) -> napi::Result<Hyd
     })
 }
 
-const CATALOG_SOURCES: &[&str] = &["claude", "codex", "cursor", "grok", "relay", "opencode"];
+const CATALOG_SOURCES: &[&str] = &[
+    "claude", "codex", "cursor", "grok", "relay", "opencode", "muse",
+];
 
 /// Reject an unusable identity before opening anything, so a typo is an
 /// argument error rather than an empty result that looks like real data.

crates/ai-hist/public-api.txt

@@ -175,6 +175,7 @@ pub ai_hist::Source::Claude
 pub ai_hist::Source::Codex
 pub ai_hist::Source::Cursor
 pub ai_hist::Source::Grok
+pub ai_hist::Source::Muse
 pub ai_hist::Source::OpenCode
 pub ai_hist::Source::Relay
 pub ai_hist::Source::Trajectory
@@ -459,6 +460,7 @@ pub ai_hist::ProviderRoots::claude: std::path::PathBuf
 pub ai_hist::ProviderRoots::codex: std::path::PathBuf
 pub ai_hist::ProviderRoots::grok: std::path::PathBuf
 pub ai_hist::ProviderRoots::home: std::path::PathBuf
+pub ai_hist::ProviderRoots::muse: std::path::PathBuf
 pub ai_hist::ProviderRoots::opencode_db: std::path::PathBuf
 pub ai_hist::ProviderRoots::opencode_db_pinned: bool
 pub ai_hist::ProviderRoots::opencode_storage_dir: std::path::PathBuf

crates/ai-hist/src/discover.rs

@@ -312,6 +312,8 @@ pub struct DiscoveryEnv<'a> {
     pub codex_home: PathBuf,
     /// Grok state root.
     pub grok_home: PathBuf,
+    /// Muse Code session logs.
+    pub muse_sessions: PathBuf,
     /// Path to the opencode database.
     pub opencode_db: PathBuf,
     /// Whether `opencode_db` is the only OpenCode database to read, rather
@@ -341,6 +343,7 @@ impl<'a> DiscoveryEnv<'a> {
             claude_config_dir: roots.claude,
             codex_home: roots.codex,
             grok_home: roots.grok,
+            muse_sessions: roots.muse,
             opencode_db: roots.opencode_db,
             opencode_db_pinned: roots.opencode_db_pinned,
             opencode_storage_dir: roots.opencode_storage_dir,
@@ -369,9 +372,11 @@ impl<'a> DiscoveryEnv<'a> {
             .parent()
             .map(|parent| parent.join("storage"))
             .unwrap_or_else(|| home.join(".local/share/opencode/storage"));
+        let muse = crate::paths::default_muse_sessions_dir(&home);
         Self::with_provider_roots(
             conn,
             crate::ProviderRoots {
+                muse,
                 home,
                 claude: claude_config_dir,
                 codex: codex_home,
@@ -409,6 +414,7 @@ impl<'a> DiscoveryEnv<'a> {
             claude_config_dir: &self.claude_config_dir,
             codex_home: &self.codex_home,
             grok_home: &self.grok_home,
+            muse_sessions: &self.muse_sessions,
             opencode_db: &self.opencode_db,
             opencode_db_pinned: self.opencode_db_pinned,
             opencode_storage_dir: &self.opencode_storage_dir,
@@ -451,6 +457,8 @@ pub struct ScanEnv<'a> {
     pub codex_home: &'a Path,
     /// Grok state root.
     pub grok_home: &'a Path,
+    /// Muse Code session logs.
+    pub muse_sessions: &'a Path,
     /// Path to the opencode database.
     pub opencode_db: &'a Path,
     /// Whether `opencode_db` is the only OpenCode database to read.
@@ -500,6 +508,8 @@ pub struct ProviderRoots<'a> {
     pub codex: &'a Path,
     /// Grok state root.
     pub grok: &'a Path,
+    /// Muse Code session logs.
+    pub muse: &'a Path,
     /// Path to the opencode database.
     pub opencode_db: &'a Path,
 }
@@ -1009,6 +1019,7 @@ pub fn shallow_providers() -> Vec<Box<dyn ShallowSessionProvider>> {
         Box::new(CodexProvider),
         Box::new(CursorProvider),
         Box::new(GrokProvider),
+        Box::new(MuseProvider),
         Box::new(OpencodeProvider::default()),
         Box::new(RelayProvider),
     ]
@@ -2063,6 +2074,141 @@ fn grok_update_bounds(
     Ok((first, last))
 }
 
+// ---------------------------------------------------------------------------
+// muse
+// ---------------------------------------------------------------------------
+
+/// Muse Code: one append-only `session.jsonl` per session under
+/// `muse/sessions/YYYY/MM/DD/<session-id>/`. Subagent and reminder children
+/// write their own transcripts under `subagent/` beside the parent; those are
+/// not sessions of their own and are never enumerated.
+struct MuseProvider;
+
+impl ShallowSessionProvider for MuseProvider {
+    fn acquire(
+        &self,
+        _home: &Path,
+        _observation: &crate::observations::SessionObservation,
+    ) -> Result<crate::sources::AcquiredEvidence> {
+        Ok(crate::sources::AcquiredEvidence::LocalFiles)
+    }
+    fn source(&self) -> &'static str {
+        "muse"
+    }
+    /// The transcript parser writes prompts, events, tool calls, file edits
+    /// and `delegated` edges to the subagent logs beside the session: every
+    /// kind a full session is made of.
+    fn evidence_kinds(&self) -> &'static [EvidenceKind] {
+        FULL_SESSION_KINDS
+    }
+
+    fn watch_roots(&self, roots: &ProviderRoots<'_>) -> Vec<WatchRoot> {
+        vec![WatchRoot::tree(roots.muse.to_path_buf())]
+    }
+
+    fn enumerate(
+        &self,
+        env: &DiscoveryEnv<'_>,
+        _requested_limit: Option<usize>,
+    ) -> Result<Vec<Candidate>> {
+        file_candidates(
+            "muse",
+            crate::collect_muse_transcripts(&env.muse_sessions)?,
+            crate::file_stamp_and_modified,
+        )
+    }
+
+    /// Enumeration is top-level transcripts only, but a subagent log is
+    /// evidence too: sync stamps it, and a background subagent keeps writing
+    /// after its parent has stopped. Left out of the fold, a tick whose only
+    /// change was a child log would sit behind an unchanged fingerprint and
+    /// never reach the sweep that reads it.
+    fn fingerprint_inputs(&self, env: &DiscoveryEnv<'_>) -> Result<Vec<Candidate>> {
+        let mut files = Vec::new();
+        for transcript in crate::collect_muse_transcripts(&env.muse_sessions)? {
+            match crate::muse_session_files(&transcript) {
+                Ok(tree) => files.extend(tree),
+                Err(error) if error.is::<crate::CaptureCancelled>() => return Err(error),
+                // One session's child log that cannot be statted must not fail
+                // the whole fold. Its transcript still counts; the sweep reads
+                // that session, fails it alone, and — having left a source
+                // unread — does not cache this fingerprint, so it is retried.
+                Err(_) => files.push(transcript),
+            }
+        }
+        file_candidates("muse", files, crate::file_stamp_and_modified)
+    }
+
+    fn read_shallow(
+        &self,
+        scan: &ScanEnv<'_>,
+        _catalog: Option<&Connection>,
+        candidate: &Candidate,
+    ) -> Result<Option<ShallowSession>> {
+        use crate::ingest::muse;
+        let path = PathBuf::from(&candidate.locator);
+        // A subagent's log is never a session of its own, however the
+        // candidate arrived — enumeration skips them, a watch hit or a
+        // by-path read need not.
+        if muse::is_subagent_log(&path) {
+            return Ok(None);
+        }
+        let bounded = read_bounded_jsonl(scan, &path)?;
+        // A permission frame can precede the metadata record, so the header
+        // is looked for rather than assumed to be the first line.
+        let Some(metadata) = bounded
+            .head_records()
+            .filter_map(parse_record)
+            .find_map(|record| muse::parse_metadata(&record))
+        else {
+            return Ok(None);
+        };
+        let own_stream = |record: &Value| {
+            record.pointer("/stream/id").and_then(Value::as_str)
+                == Some(metadata.session_id.as_str())
+        };
+        let mut models = Vec::new();
+        push_unique(&mut models, metadata.model_id.as_deref());
+        let mut first_prompt = None;
+        for record in bounded.head_records().filter_map(parse_record) {
+            if !own_stream(&record) {
+                continue;
+            }
+            match muse::parse_event(&record) {
+                Some(muse::MuseEvent::Prompt { text }) if first_prompt.is_none() => {
+                    first_prompt = Some(excerpt(&text));
+                }
+                Some(muse::MuseEvent::ModelCompleted { model, .. }) => {
+                    push_unique(&mut models, model.as_deref());
+                }
+                _ => {}
+            }
+            if first_prompt.is_some() && models.len() > 1 {
+                break;
+            }
+        }
+        let last_activity_ms = bounded
+            .tail_records_rev()
+            .filter_map(parse_record)
+            .filter(own_stream)
+            .find_map(|record| muse::recorded_ms(&record));
+        Ok(Some(ShallowSession {
+            source: "muse".into(),
+            session_id: metadata.session_id,
+            cwd: metadata.workspace_root,
+            first_activity_ms: metadata.recorded_ms,
+            last_activity_ms: last_activity_ms
+                .or(metadata.recorded_ms)
+                .or_else(|| crate::file_modified_ms(&path)),
+            first_prompt,
+            models,
+            agent_version: metadata.cli_version,
+            raw_path: Some(candidate.locator.clone()),
+            ..Default::default()
+        }))
+    }
+}
+
 // ---------------------------------------------------------------------------
 // opencode
 // ---------------------------------------------------------------------------
@@ -3458,6 +3604,7 @@ pub(crate) fn provider_watch_roots(source: &str, roots: &crate::ProviderRoots) -
             claude: &roots.claude,
             codex: &roots.codex,
             grok: &roots.grok,
+            muse: &roots.muse,
             opencode_db: &roots.opencode_db,
         },
     )