# @qmilab/lodestar-trace

> The read side — project the Lodestar event log into the epistemic chain and render a 'why did the agent do this?' report. Part of Lodestar, the trust layer for AI agents.

Latest version **0.5.0** (published 2026-07-01) · Apache-2.0 license · 42 weekly downloads

## Install

```sh
npm install @qmilab/lodestar-trace
pnpm add @qmilab/lodestar-trace
yarn add @qmilab/lodestar-trace
bun add @qmilab/lodestar-trace
```

Provides the command `lodestar-report`.

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

Negative: declining downloads.

## Facts

| | |
|---|---|
| Version | 0.5.0 |
| Published | 2026-07-01 |
| First published | 2026-05-25 |
| Weekly downloads | 42 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 252 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 3 |
| Author | QMI Lab |
| Maintainers | cybernandan |
| Keywords | ai-agents, trust, lodestar, trace, audit-trail, epistemic-chain, report |

## Links

- npm: https://www.npmjs.com/package/@qmilab/lodestar-trace
- Repository: https://github.com/qmilab/lodestar
- Homepage: https://qmilab.com/lodestar
- Issues: https://github.com/qmilab/lodestar/issues
- npm.io page: https://npm.io/package/@qmilab/lodestar-trace

## Dependencies (4)

- [zod](https://npm.io/package/zod.md) ^3.23.8
- [@qmilab/lodestar-core](https://npm.io/package/@qmilab/lodestar-core.md) 0.5.0
- [@qmilab/lodestar-event-log](https://npm.io/package/@qmilab/lodestar-event-log.md) 0.5.0
- [@qmilab/lodestar-memory-firewall](https://npm.io/package/@qmilab/lodestar-memory-firewall.md) 0.5.0

## Alternatives

- [lodash.startswith](https://npm.io/package/lodash.startswith.md) — 769.7K weekly downloads
- [@tarojs/service](https://npm.io/package/@tarojs/service.md) — 33.9K weekly downloads
- [io.extendreality.tilia.indicators.spatialtargets.unity](https://npm.io/package/io.extendreality.tilia.indicators.spatialtargets.unity.md) — 131 weekly downloads
- [@rtarojs/taro](https://npm.io/package/@rtarojs/taro.md) — 90 weekly downloads
- [node-branch-io](https://npm.io/package/node-branch-io.md) — 50 weekly downloads

## Recent versions

- 0.5.0 (latest) — 2026-07-01
- 0.4.0 — 2026-06-20
- 0.3.0 — 2026-06-12
- 0.2.0 — 2026-06-08
- 0.1.5 — 2026-05-25
- 0.1.4 — 2026-05-25
- 0.1.1 — 2026-05-25

## README

# @qmilab/lodestar-trace

The read side of the epistemic chain. Consumes an Lodestar event log and
produces a markdown trust report that explains what an agent observed,
what it came to believe, which beliefs informed which actions, what
happened, and whether anything was revised.

## CLI

```
lodestar report <session-id> [--project <id>] [--log-root <path>] [--out <file>]
```

Defaults the log root to `./.lodestar/events`. Will scan project directories
under the log root if `--project` is not supplied.

Examples:

```sh
# Render to stdout
lodestar report session-1779551238212

# Write to a file (suitable for pasting into a GitHub issue)
lodestar report session-1779551238212 --out trust.md

# Inspect a different log root
lodestar report session-1779551238212 --log-root .lodestar/events
```

The package also exposes the binary directly:

```sh
bunx lodestar-report <session-id>
```

## Library

```ts
import {
  loadSessionEvents,
  projectChain,
  renderReport,
  defaultLogRoot,
} from "@qmilab/lodestar-trace"

const { events, project_id } = await loadSessionEvents({
  logRoot: defaultLogRoot(),
  session_id: "session-1779551238212",
})
const projection = projectChain(events, { session_id: "session-1779551238212" })
const markdown = renderReport(projection)
```

## Why this is a separate package

The append-only event log is *the* source of truth in Lodestar. The trace
package treats it as such: every fact it surfaces is grounded in a
specific event. That separation is what lets `lodestar report` work even
when the agent process has exited and only the log remains.

## What it does not do

- Real-time tailing of an active session (planned for v0.2).
- Rendering to HTML or JSON (markdown only in v0).
- Exporting to LangSmith / Langfuse / Phoenix (that's `@qmilab/lodestar-otel-exporter`).
- Single-writer enforcement on the underlying event log (that's Batch 3).

---
_Source: https://npm.io/package/@qmilab/lodestar-trace · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._