lossless-core
Use when wiring a host to lossless-core or working on the engine itself: implement ModelHost or Reader, run a compaction, retrieval, or heal pass, or read the store directly with LcmStore.
- License 许可
- MIT
- 最近更新
- 2026-11-07
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- lossless-core
- license
- MIT
- sources
- [ "stainless-code/lossless:packages/core/src/host.ts", "stainless-code/lossless:packages/core/src/index.ts", "stainless-code/lossless:packages/core/README.md" ]
- metadata
- { "type": "core", "library": "lossless-core", "library_version": "0.1.3" }
- description
- Use when wiring a host to lossless-core or working on the engine itself: implement ModelHost or Reader, run a compaction, retrieval, or heal pass, or read the store directly with LcmStore.
03 SKILL.md 正文
Lossless core
Use it when implementing a host adapter or touching the engine. Do not use it
for adapter commands: Pi subcommands live in the pi-lossless skill,
lossless-* commands in the opencode-lossless skill.
The engine behind pi-lossless and opencode-lossless: Lossless Context
Management for a long-running agent. Every message is stored verbatim,
aged context is replaced with searchable pointers, and the original text
stays readable by id, entry, or search.
Minimal wiring
import { LcmStore, runCompaction, runHeal, runRetrieval } from "lossless-core";
import type { ModelHost, Reader } from "lossless-core";
Call shapes (full signatures in src/index.ts, port contracts in src/host.ts):
const store = new LcmStore(dbPath);
await runCompaction(store, input, llm); // input: CompactionInput (span, budgets)
await runRetrieval(store, request, reader); // request: RetrievalRequest (scope, query)
await runHeal(store, { dryRun: true }, llm); // HealInput: maxNodes, maxCalls, dryRun plan mode
The engine has no agent SDK dependency. A host supplies two ports and the
engine does the rest. Pi implements both; the OpenCode v2 adapter implements
ModelHost and runs retrieval in a host child session instead of Reader.
What it does
- Ingest. Every message lands in SQLite with its entry id, role, timestamp, and any file handle the host attached.
- Compaction. Past a swap ratio, a pass summarizes spans into leaf and condensed nodes and leaves a pointer in place. Nothing is deleted.
- Retrieval. A reader answers by calling
lcm_grep,lcm_describe, andlcm_expand, so the answer cites what was read. - Repair.
runHealre-derives a truncated summary and its ancestors from the provenance rows they still point at. - Redaction. Secret-shaped text is masked on the way to a model, never at the door, so an export or read still returns what was stored.
The two ports
src/host.ts documents both. ModelHost is what the engine calls a model
through: session(), find(), complete(), plus where notices go.
Reader is one retrieval conversation: begin() returns a Reading
whose next() appends results and returns the model reply.
| Type | Question it answers |
|---|---|
ModelHost |
Which model, and what did it answer |
Reader |
What did the reader ask for, and what did it conclude |
Boundary rule
No module under src/ imports an agent SDK, a bare specifier other than
node:* and typebox, or a file outside the engine. The boundary test
fails any violation. Import the package root only.
Common mistakes
- Importing engine source deep paths (
lossless-core/dist/...or relativesrc/...files) instead of the package root — the boundary test fails deep imports;import { LcmStore } from "lossless-core"is the only entry. - Expecting a host SDK in the bundle - the host always supplies
ModelHost(andReader, unless the host runs retrieval itself, as the OpenCode adapter does); implement the port, nevernpm installan SDK. - Assuming compaction deletes - pointers replace text in context, the verbatim rows stay queryable via the recall views.
- Redacting at write time - masking happens on the model path only; a stored row is never rewritten.
API surface
LcmStore,runCompaction,runRetrieval,runHeal— exported fromsrc/index.ts; pass and heal options live next to their runners.ModelHost,Reader,Reading(types,src/host.ts) — the two port contracts; implement these, never a host SDK.
04 同仓库更多 Skills
pi-lossless
Use when a Pi session has pi-lossless installed: search compacted history with lcm_grep, lcm_describe, or lcm_expand_query; run /lcm status, settings, backup, export, report, doctor, gc, migrate, heal, dump, or diagnose; or tune compaction thresholds.
opencode-lossless
Use when an OpenCode v2 session has opencode-lossless installed: read compacted history with lcm_grep, lcm_describe, lcm_expand, or lcm_expand_query; run /lossless-status, /lossless-report, /lossless-pass, /lossless-heal, /lossless-backup, /lossless-export, /lossless-import, /lossless-diagnose, /lossless-migrate, /lossless-gc, or /lossless-dump; or tune the swap point.