Sessionlore is a plugin for writing source-linked engineering dev logs in the coding agent's first-person voice. Codex, Claude Code, or OpenCode supplies the model: the host agent reads evidence, plans, writes, and reviews. The packaged local tools import sessions, search evidence, check citation IDs, and export Markdown and HTML. This workflow needs no separate writing-model API key.
Codex rollouts, Claude Code transcripts, and OpenCode JSON exports feed the same evidence store. Existing API-backed narrative experiments remain available for research; they are separate from the plugin and retain their original prompts.
Requires Node.js 22.15 or newer. The plugin includes its runtime and needs no workspace dependency install. This is an early release; see the tested versions and limits.
For Codex:
codex plugin marketplace add LabLambWorks/sessionlore
codex plugin add sessionlore@sessionlore-localFor Claude Code, run these inside a session:
/plugin marketplace add LabLambWorks/sessionlore
/plugin install sessionlore@sessionlore-local
Restart the host session and ask:
Use Sessionlore to write this project's dev log from your perspective.
Claude Code also provides /sessionlore:devlog.
For OpenCode V1, clone this repository and add the absolute file URL of
plugins/sessionlore/opencode.mjs to the plugin array in opencode.json.
Restart and run /sessionlore. See the plugin guide for the
complete configuration, supported transcript formats, and V2 status.
The agent writes as itself: “I traced the failure to the parser,” while attributing the developer's decisions to the developer. It checks claims against captured sources and exports a local draft with citations. Review the result before sharing; source excerpts can contain private information.
Use Node.js 22.23.1 and pnpm 10.33.2. The repository pins both versions. With nvm and Corepack installed:
git clone https://github.com/LabLambWorks/sessionlore.git
cd sessionlore
nvm use
corepack enable
pnpm install --frozen-lockfile
pnpm check
pnpm plugin:buildThe build produces a standalone plugin at dist/plugins/sessionlore. The
repository also includes a ready-to-install copy at plugins/sessionlore.
After changing the runtime, run pnpm plugin:prepare-release to update that copy.
CI checks that it matches a fresh build.
For Claude Code, test the plugin directly:
claude --plugin-dir ./dist/plugins/sessionloreTo exercise the local tools without invoking any model:
pnpm host prepare --host claude --input fixtures/claude/v1/session.jsonl \
--out .sessionlore/host-demo
pnpm host read --run .sessionlore/host-demoThe host writes draft.json, reviews the source records, then passes the reviewed
draft to validate and export. The skill describes the complete workflow.
A successful citation check confirms that references exist; it does not prove
that every sentence is true.
pnpm demo writes a source timeline to .sessionlore/demo/timeline.md.
pnpm demo:approaches runs all six pipelines on synthetic sessions and artifacts.
It prints a new directory under .sessionlore/experiments-demo/ containing
comparison.md and a narrative.md for each approach. Both demos run locally
without an API key. The approach demo uses deterministic excerpts and heuristics;
use a real model to compare writing quality.
Select a project as the main input:
pnpm cli projects
pnpm cli capture --project peekatrack --out .sessionlore/cases/peekatrack-new
pnpm setup:history
pnpm cli compare --project peekatrack --provider kimi-code \
--out .sessionlore/peekatrack-fullProject discovery collects its sessions, resume files, and Git worktrees. Recorded
file changes and validation results remain in the captured evidence. New run
and compare jobs use conversation content as their primary model input:
user messages, assistant replies, clarification questions, and recorded answers.
Execution commands, bulk tool results, thoughts, and injected instructions stay
in the local archive. Explicitly supplied artifacts remain available. Project
selection no longer automatically adds copies of tool results as artifacts.
Use --evidence-view execution only for an intentional raw-trace experiment.
Put
KIMI_CODE_API_KEY in the ignored root .env. DeepSeek remains available with
--provider deepseek and DEEPSEEK_API_KEY. The full-history comparison rejects
time windows, uses token budgets, and resumes cached work in the same output
directory. See the full-history guide for the four methods
and the prepared PeekaTrack case. Python 3 is needed for the tokenizer setup.
To recover every requested enhancement and refinement as a searchable list, use the request inventory. It reads requests and recorded answers in bounded Kimi batches, preserves source links and stated reasons, and tracks every input record. It does not write a devlog or infer implementation status.
Prepare a compact conversation view from an existing full-project capture, without making any API calls:
pnpm cli prepare-conversation .sessionlore/peekatrack-full-deepseek-v1 \
--out .sessionlore/peekatrack-conversation-v1conversation.json contains the messages with source IDs. preflight.json
reports their size and local token estimates. Raw evidence remains in the source
capture for targeted verification. See the input policy.
Generate a complete devlog from the captured project with Kimi Code:
pnpm build
node --env-file=.env scripts/write-conversation.mjs \
--source .sessionlore/peekatrack-full-deepseek-v1 \
--out .sessionlore/peekatrack-kimi-full-narrative-v1This path reads the full conversation, writes the complete project narrative,
then performs one review and revision using the conversation and bounded original
execution records retrieved from the draft's claims. It makes at most two
generation calls, with no automatic retries or output repairs. The output includes
narrative.html, narrative.md, the unchanged draft.md, source links, exact
requests and responses, and measured usage. Completed calls are cached for resumption.
The same-model review is not independent proof of correctness.
That two-pass path is separate from the four long-history approaches. To compare all four on the same frozen cleaned PeekaTrack conversation with Kimi Code:
pnpm build
node scripts/compare-cleaned-kimi.mjsThis runs summary hierarchy, hybrid retrieval, hierarchy plus retrieval, and
recursive reading through the same first-person writer and batched source review.
Open .sessionlore/peekatrack-kimi-four-cleaned-v1/comparison.html for all four full
outputs side by side. Original drafts, review corrections, citations and measured
usage remain available. The runner checks Kimi quota and uses one generation at
a time; exact completed requests are reused on resume.
node scripts/render-cleaned-comparison.mjs rebuilds the reader locally without
loading an API key or making a model request.
The evidence diagnostic compares extraction from selected original messages with retrieval from the full project on both models. The Kimi-only retrieval comparison tests request-to-result retrieval and source-derived checks for missing details against the current pipeline, using the same full-history capture and source budget.
For a model-backed comparison:
# Set OPENAI_API_KEY in your shell. Use a model available to your account that
# supports Chat Completions and structured JSON output.
export SESSIONLORE_MODEL='your-model-id'
pnpm cli run fixtures/experiments/v1/sessions \
--provider openai-compatible \
--approach all \
--artifacts fixtures/experiments/v1/artifacts.json \
--out .sessionlore/comparisonSelect one with --approach direct, hierarchical, pivot, workstream,
retrieval, or artifact. Letters A through F and comma-separated selections
also work. See the experiment guide for real session inputs,
Git artifacts, local model endpoints, limits, and review instructions.
| Path | Package | Responsibility |
|---|---|---|
apps/cli |
@sessionlore/cli |
CLI arguments and local commands |
packages/contracts |
@sessionlore/contracts |
Runtime schemas and TypeScript types for evidence and later narrative stages |
packages/adapter-codex |
@sessionlore/adapter-codex |
File discovery, JSONL/Zstandard decoding, Codex normalization |
packages/adapter-transcripts |
@sessionlore/adapter-transcripts |
Claude JSONL and OpenCode export normalization |
packages/host-tools |
@sessionlore/host-tools |
Local tools for the host-agent workflow; no model transport |
plugins/sessionlore |
— | Shared agent-POV skill, Codex/Claude manifests, OpenCode integration |
packages/evidence-store |
@sessionlore/evidence-store |
Immutable raw bytes and versioned snapshots |
packages/core |
@sessionlore/core |
Ingestion, deduplication within a run, timeline rendering, replay |
packages/experiments |
@sessionlore/experiments |
Narrative experiments, full-history methods, model transport, retrieval, writing, and verification |
fixtures/codex/v1 |
— | Synthetic regression inputs |
fixtures/experiments/v1 |
— | Synthetic mixed-task sessions and engineering artifacts |
docs |
— | Original build brief, revision report, architecture image, and implementation notes |
Internal dependencies use workspace:*. TypeScript project references build the
packages in dependency order. The plugin build bundles its runtime dependencies.
Nothing is published by the build; a public release still needs a licensing and
distribution decision.
# Build all packages.
pnpm build
# Build the standalone plugin, or inspect its model-free command interface.
pnpm plugin:build
pnpm host --help
# Rebuild packages when source files change.
pnpm dev
# Ingest an explicit file or recursively scan a directory.
pnpm cli ingest /path/to/rollout.jsonl --out .sessionlore/local
pnpm cli ingest /path/to/sessions --out .sessionlore/local
# Verify a captured snapshot using a source ID from report.json.
pnpm cli replay <source-sha256> --out .sessionlore/local
# Run formatting checks, type checks, and tests.
pnpm check
pnpm format
# Exercise all six pipelines without API access.
pnpm demo:approachespnpm cli builds before running. After a build, you can also run
node apps/cli/dist/index.js --help. To build one package and its dependencies,
run pnpm --filter @sessionlore/core build.
- Reads
.jsonland.jsonl.zstfiles only from the path you provide. - Retains every physical record, including unknown records and malformed tails.
- Records raw hashes, source metadata, line numbers, and decompressed byte ranges.
- Recognizes human turns from supported
event_msg.user_messagerecords. A completed desktopUserMessageis also recognized. Arole=userresponse item alone is not treated as a human turn. Explicit subagent input remains distinct from human input. - Reads completed
FileChangeandCommandExecutionrecords as structured evidence, and flags explicit message mirrors to avoid duplicate story inputs. - Records explicit fork, subagent, and attachment metadata as distinct lineage relationships. It does not infer or merge thread families.
- Keeps complete event IDs stable when a source is appended to. Repeated ingestion of unchanged bytes creates no new snapshot. Plain and compressed copies share event IDs, while each raw snapshot remains available.
- Renders source-file and line order, preserving timestamp conflicts as warnings.
- Replays captured bytes without requiring the original input file.
Each run replaces the local timeline and report with the supplied input set. Prior
snapshots remain stored; the timeline is not a cumulative database query. Capture
and normalization stream large files, with limits of 2 GiB per raw or decoded
source and 256 MiB per physical JSONL record. Media remains in raw evidence; the
writer receives text projections. Symlinks are not followed. The scanner skips
.git, node_modules, .sessionlore, and the selected output directory.
.sessionlore/local/
raw/<source-sha256>
snapshots/<source-sha256>/codex-0.3.0.json
report.json
timeline.md
Raw evidence and local previews can contain secrets. They are not redacted or
ready for publication. Ingestion, replay, and the demo provider make no network
calls. Model-backed runs send selected source content to the configured API
endpoint and save prompts and responses locally. The tool does not execute
transcript content. It creates data files with mode 0600 on POSIX systems.
.sessionlore/ is ignored by Git. Keep custom output locations out of version
control as well.
The contracts require evidence references and distinguish observed, inferred,
and unknown fields. Schema validation does not prove a claim is supported by its
source. Experiments validate source IDs and use a model to review atomic claims
against original excerpts. This reviewer can miss errors. The long-history
comparison keeps source-supported review corrections and withholds paragraphs
that the reviewer cannot repair. Other experiment paths retain their original
filtering policy. Complete drafts and verdicts remain available. Redaction and
publishing are not implemented.
The design research records the initial implementation order and evidence boundaries. See monorepo notes for package dependencies and the remaining phases.
The fixtures are synthetic. They do not establish compatibility with a particular installed host version. Native plugin loading checks are documented separately in the plugin guide. Broader live-version fixtures, a Grok adapter, lifecycle capture, calibrated continuation inference, dedicated short-form generation, and publishing remain future work.
See CONTRIBUTING.md for development and release checks, and SECURITY.md for private vulnerability reports.
Sessionlore is licensed under MIT. The bundled plugin includes third-party notices.