# Miseledger > MiseLedger is a local-first evidence ledger for AI work history: SQLite FTS search, Markdown export, StationTrail and SourceHarvest imports, and Brigade-ready evidence bundles. - **Type:** MCP server - **Install:** `agentstack add mcp-escoffier-labs-miseledger` - **Verified:** Pending review - **Seller:** [escoffier-labs](https://agentstack.voostack.com/s/escoffier-labs) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [escoffier-labs](https://github.com/escoffier-labs) - **Source:** https://github.com/escoffier-labs/miseledger - **Website:** https://brigade.tools/miseledger ## Install ```sh agentstack add mcp-escoffier-labs-miseledger ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About MiseLedger Your agent history is scattered. MiseLedger makes it searchable evidence. Local SQLite evidence graph for AI work: crawl sessions and notes, import adapter.v1 records, search with FTS5, export Brigade-ready bundles. Untrusted evidence, not instructions. No network required. Website · Install · Quickstart · Brigade hub ## Install ```bash # install pinned release 0.5.0 (Linux/macOS) MISELEDGER_VERSION=v0.5.0 curl -fsSLO https://raw.githubusercontent.com/escoffier-labs/miseledger/v0.5.0/install.sh cat install.sh # review before running MISELEDGER_VERSION="$MISELEDGER_VERSION" sh install.sh miseledger init miseledger crawl sessions miseledger search "cookie rotation" miseledger evidence --json ``` Review `install.sh` before running it. The installer downloads release binaries and verifies their sha256 checksums against the release `checksums.txt`. To verify GitHub artifact provenance for a downloaded release asset, run `gh attestation verify --repo escoffier-labs/miseledger`. Or from source: ```bash git clone https://github.com/escoffier-labs/miseledger.git cd miseledger && go build -o bin/miseledger ./cmd/miseledger ``` ## What it does | | Job | What you get | |---|---|---| | **Crawl** | Sessions, files, git, chat exports | Built-in crawlers + external exporters into adapter.v1 | | **Store** | One local ledger | SQLite with FTS5, deduped collections and items | | **Search** | Find what you already figured out | Full-text search across sources with provenance | | **Export** | Hand evidence to Brigade | Bundles marked untrusted for run briefs and receipts | Memory is for decisions. MiseLedger is for proof of what actually happened. Local only. ## Build ```bash go build -o bin/miseledger ./cmd/miseledger go build -o bin/sessionfind ./cmd/sessionfind ``` You can also run commands with: ```bash go run ./cmd/miseledger --help ``` First archive: ```bash miseledger init miseledger crawl sessions --json miseledger crawl chatgpt-export ~/Downloads/chatgpt-export.zip --json miseledger crawl claude-export ~/Downloads/claude-export.zip --json miseledger crawl docs ./notes --json miseledger crawl repo . --json miseledger sessions search "release audit" --source codex --json miseledger search "auth timeout" --json miseledger evidence "auth timeout" --markdown ``` Convenience alternative, mutable `HEAD` installer: ```bash curl -fsSL https://raw.githubusercontent.com/escoffier-labs/miseledger/HEAD/install.sh | sh ``` For a first archive and agent integration path, see [docs/QUICKSTART.md](docs/QUICKSTART.md). For MCP client configuration, see [docs/MCP.md](docs/MCP.md). For roadmap and cookbook material, see [docs/ROADMAP.md](docs/ROADMAP.md), [docs/EXAMPLES.md](docs/EXAMPLES.md), [docs/QUERY_COOKBOOK.md](docs/QUERY_COOKBOOK.md), [docs/STATIONTRAIL_PARITY.md](docs/STATIONTRAIL_PARITY.md), [docs/LIVE_DRY_RUN_CHECKLIST.md](docs/LIVE_DRY_RUN_CHECKLIST.md), and [docs/INSTALL_SMOKE.md](docs/INSTALL_SMOKE.md). ## How It Works The generated evidence plate above is rebuilt from docs/assets/workflows/evidence.json. MiseLedger follows one ingest path: 1. Receive `miseledger.adapter.v1` JSONL from a file, stdin, a built-in crawler, a native compatibility adapter, or an external crawler binary. 2. Parse and validate each adapter record. 3. Store normalized sources, collections, items, actors, artifacts, raw refs, tags, imports, warnings, and scan manifests in SQLite. 4. Deduplicate repeat records and preserve raw payload references for audit. 5. Maintain FTS5 search indexes and shallow relations. 6. Serve search, show, explain, export, HTTP, MCP, and evidence-bundle workflows from the local archive. ## Stack Map ```mermaid flowchart TB MISELEDGER["MiseLedgerarchive, search, evidence layer"] SQLITE["SQLite archivenormalized records, FTS, relations, raw refs"] MISELEDGER -->|owns| SQLITE subgraph AGENTS [" agent-session crawlers "] SESSIONS["miseledger crawl sessionsCodex, Claude, OpenClaw, OpenCode, Hermes, Cursor, Grok"] COMPAT["Native importssource-specific compatibility commands"] end subgraph LOCAL [" local artifact crawlers "] ARTIFACTS["miseledger crawl docs/filesMarkdown, text, logs, HTML"] GITLOG["miseledger crawl gitlogrepository history"] GENERIC["Generic adapter recordsnormalized source exports"] end subgraph CRAWLERS [" external crawler binaries "] DISCRAWL["discrawl"] GITCRAWL["gitcrawl"] GRAINCRAWL["graincrawl"] NOTCRAWL["notcrawl"] SLACRAWL["slacrawl"] MAILCRAWL["mailcrawl"] TELECRAWL["telecrawl"] end SESSIONS & COMPAT == adapter JSONL ==> MISELEDGER ARTIFACTS & GITLOG & GENERIC == adapter JSONL ==> MISELEDGER DISCRAWL & GITCRAWL & GRAINCRAWL & NOTCRAWL & SLACRAWL & MAILCRAWL & TELECRAWL == adapter JSONL ==> MISELEDGER subgraph READERS [" reader workflows "] CLI["miseledger CLIsearch, show, explain, export"] EVIDENCE["Evidence bundlesBrigade-ready context"] MCP["Agent readersHTTP loopback, stdio MCP"] OPS["Archive operationsdoctor, stats, compact"] end SQLITE --> CLI SQLITE --> EVIDENCE SQLITE --> MCP SQLITE --> OPS classDef core fill:#2563eb,stroke:#1d4ed8,color:#fff; classDef archive fill:#fff7ed,stroke:#ea580c,color:#7c2d12; classDef source fill:#eff6ff,stroke:#2563eb,color:#1e3a8a; classDef crawler fill:#ecfdf5,stroke:#059669,color:#064e3b; classDef reader fill:#f1f5f9,stroke:#94a3b8,color:#334155; class MISELEDGER core; class SQLITE archive; class SESSIONS,COMPAT,ARTIFACTS,GITLOG,GENERIC source; class DISCRAWL,GITCRAWL,GRAINCRAWL,NOTCRAWL,SLACRAWL,MAILCRAWL,TELECRAWL crawler; class CLI,EVIDENCE,MCP,OPS reader; ``` MiseLedger owns local agent-session crawling, local artifact crawling, archive ingest, SQLite, FTS, relations, scan manifests, reader APIs, and evidence bundles. External crawler tools keep their native sync and query behavior. Six wrappers consume source-owned adapter JSONL. The Telegram wrapper converts Telecrawl's public JSON message output into the same adapter contract. ## Runtime Paths MiseLedger uses XDG paths when present: - config: `~/.config/miseledger/config.toml` - data: `~/.local/share/miseledger/miseledger.db` - cache: `~/.cache/miseledger/` Directories and files created by the CLI use private permissions. ## Smoke Test ```bash miseledger init miseledger import adapter testdata/adapters/discrawl.fixture.jsonl miseledger import adapter testdata/adapters/agent-session.fixture.jsonl --source codex miseledger adapter codex testdata/harnesses/codex-session.fixture.jsonl --out - miseledger adapter hermes testdata/harnesses/session_hermes-demo.fixture.json --out - miseledger adapter opencode testdata/harnesses/opencode-export.fixture.json --out - miseledger import codex testdata/harnesses/codex-session.fixture.jsonl --json miseledger import openclaw testdata/harnesses/openclaw-session.fixture.jsonl --json miseledger import claude testdata/harnesses/claude-project.fixture.jsonl --json miseledger import hermes testdata/harnesses/session_hermes-demo.fixture.json --json miseledger import opencode testdata/harnesses/opencode-export.fixture.json --json miseledger status --json miseledger scans list --json miseledger sources discover --json miseledger search "adapter contract" --json miseledger evidence "adapter contract" --json miseledger evidence show --json miseledger explain "adapter contract" --json miseledger show --json miseledger export markdown --out /tmp/miseledger-md miseledger relations backfill --json miseledger stats --json miseledger compact --json miseledger prune imports --before 2026-01-01 --dry-run --json miseledger sql "select count(*) as items from items" --json miseledger doctor --json miseledger doctor --mcp --json miseledger doctor --archive --json ``` Re-running the same imports is idempotent and does not increase item counts. ## Native Session Adapters Native adapter generators convert local session JSON and JSONL into `miseledger.adapter.v1` records: ```bash miseledger adapter codex ~/.codex/sessions --out codex.adapter.jsonl --limit 100 miseledger adapter openclaw ~/.openclaw/agents --out openclaw.adapter.jsonl --since 2026-06-01 miseledger adapter claude ~/.claude/projects --out claude.adapter.jsonl --limit 100 miseledger adapter hermes ~/.hermes/sessions --out hermes.adapter.jsonl --limit 100 miseledger adapter opencode ~/.local/share/opencode --out opencode.adapter.jsonl --limit 100 miseledger adapter cursor ~/.config/Cursor/User --out cursor.adapter.jsonl miseledger adapter grok ~/.grok/sessions --out grok.adapter.jsonl ``` Native import commands stream generated adapter records into the same adapter ingest path: ```bash miseledger import codex ~/.codex/sessions --json miseledger import openclaw ~/.openclaw/agents --json miseledger import claude ~/.claude/projects --json miseledger import hermes ~/.hermes/sessions --json miseledger import opencode ~/.local/share/opencode --json miseledger import cursor ~/.config/Cursor/User --json miseledger import grok ~/.grok/sessions --json miseledger import codex testdata/harnesses/malformed-unknown.fixture.jsonl --dry-run --json miseledger import discovered --json miseledger watch once --json miseledger watch once --if-changed --json ``` For the normal user-facing archive-crawler lane, prefer: ```bash miseledger crawl sessions --json ``` That imports discovered local session roots through the same idempotent archive path. ## Provider Exports MiseLedger can also import official AI chat exports directly from a `.zip`, a directory containing `conversations.json`, or the JSON file itself: ```bash miseledger crawl chatgpt-export ~/Downloads/chatgpt-export.zip --json miseledger crawl claude-export ~/Downloads/claude-export.zip --json miseledger import chatgpt-export conversations.json --json miseledger import claude-export conversations.json --json ``` These imports normalize provider conversations into local `conversation` collections with `message` items tagged as `ai-chat`. ## Cursor MiseLedger imports current Cursor conversation search data from its user-data root (`$XDG_CONFIG_HOME/Cursor/User` or `~/.config/Cursor/User` on Linux, `~/Library/Application Support/Cursor/User` on macOS, and `%APPDATA%/Cursor/User` on Windows): ```bash miseledger crawl cursor --json # defaults to the standard Cursor root miseledger crawl cursor ~/.config/Cursor/User --json miseledger import cursor ~/.config/Cursor/User --json ``` The current reader opens `globalStorage/conversation-search.db` in read-only mode and indexes conversation titles and FTS bodies as agent sessions. When a WAL exists, its metadata is used for change tracking while raw references stay on the main database. The older Cursor Agent `prompt_history.json`, chat `meta.json`, and store-only session layout remains supported for explicit legacy roots. Binary legacy `store.db` message bodies are not decoded. ## Grok Sessions Grok sessions are discovered under `~/.grok/sessions`. MiseLedger reads each session's `summary.json` and `chat_history.jsonl` without importing unrelated files: ```bash miseledger crawl sessions --json miseledger import grok ~/.grok/sessions --json miseledger sessions search "crawler review" --source grok --json ``` ## Session Locator For harness-style "find the session I was working in" workflows, use the session-level commands: ```bash miseledger sessions list --source codex --json miseledger sessions list --project miseledger --model gpt-5 --json miseledger sessions search "release audit" --project miseledger --model gpt-5 --json miseledger sessions search "auth timeout" --source claude --model claude-sonnet --json sessionfind list --source codex --json sessionfind "release audit" --source codex --json ``` `--project` matches normalized `project`, `workspace`, `workspace_dir`, or `cwd` metadata with the same exact-or-contains behavior as general search. `--model` applies the same matching behavior to normalized model metadata. Both filters operate across the session collection, so the matching project and model may be recorded on different events in that session. The JSON `workspace` field prefers `workspace`, then `workspace_dir`, then `cwd`; an unmatched `project` value is omitted when a workspace-like value satisfied an active project filter. Session JSON also includes model, harness, and source name when provided; unavailable fields are omitted. `sessions search` groups matching item hits by session/conversation collection and returns the locator and match context needed to inspect or resume the local harness session. The scanners accept a file or directory, walk relevant source files recursively, skip obvious backups and sidecars, preserve raw refs, and warn rather than crash on malformed or unknown events. Hermes native support covers `session_*.json` snapshots and trajectory JSONL under `~/.hermes/sessions`; Hermes `state.db` is not parsed directly. OpenCode native support reads sanitized `opencode export` JSON files under `~/.local/share/opencode` by default. Cursor is the one native source that also reads a known SQLite search database. ## Built-In Crawlers `miseledger crawl sessions` imports discovered local agent-session roots through the same adapter ingest path: ```bash miseledger sources discover --json miseledger crawl sessions --dry-run --json miseledger crawl sessions --json miseledger crawl cursor --json ``` Native compatibility imports remain available when you want to point at one source explicitly: ```bash miseledger import codex ~/.codex/sessions --json miseledger import claude ~/.claude/projects --json miseledger import openclaw ~/.openclaw/agents --json miseledger import opencode ~/.local/share/opencode --json miseledger import hermes ~/.hermes/sessions --json miseledger import grok ~/.grok/sessions --json ``` Local artifact crawls add defaults for common archive sources: ```bash miseledger crawl docs ./notes --json miseledger crawl files ./logs --glob "*.md,*.txt,*.log" --json miseledger crawl gitlog . --json miseledger crawl json export.json --records-path records --json miseledger crawl jsonl export.jsonl --source notes --collection notes:local --json miseledger crawl adapter export.adapter.jsonl --source export --json ``` External crawler binaries can be called through domain wrappers when installed on `PATH`, or through adapter JSONL files they produced earlier: ```bash miseledger crawl discord --limit 100 --json miseledger crawl github --repo escoffier-labs/miseledger --json miseledger crawl github --repo escoffier-labs/miseledger --numbers 34,35 --limit 2 --json miseledger crawl slack --workspace T123 --json miseledger crawl granola --json miseledger crawl notion --json miseledger crawl gmail --account me@example.com --query "subject:miseledger" --json miseledger crawl telegram --chat "MiseLedger" --json miseledger import adapter discrawl.adapter.jsonl --json ``` Archived StationTrail and SourceHarvest exports are still ordinary `miseledger.adapter.v1` JSONL, so already-generated files can be imported with `miseledger import adapter`. Discord, Slack, Granola, Notion, and Gmail call each crawler's adapter exporter. GitHub calls current Gitcrawl's `sync` and `threads --json` commands, then converts those thread rows locally. Telegram calls `telecrawl --json messages`; MiseLedger converts the returned message array locally and maps `--since` to Telecrawl's `--after` flag. Gmail remains explicit about account selection. Gog may have configured accounts, but MiseLedger requires `--account` so a crawl cannot silently pick a mailbox. Use `--metadata-only`, a narrow `--query`, and `--dry-run` first; `scripts/smoke_gmail_metadata.sh` does exactly that with the first configured Gog account and does not import mail. Scheduled crawls use the same comman … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [escoffier-labs](https://github.com/escoffier-labs) - **Source:** [escoffier-labs/miseledger](https://github.com/escoffier-labs/miseledger) - **License:** MIT - **Homepage:** https://brigade.tools/miseledger Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-escoffier-labs-miseledger - Seller: https://agentstack.voostack.com/s/escoffier-labs - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.