Get started with the SDK.
Install the Purgr core package via npm to begin integrating context compression into your AI pipeline.
npm install purgr
Integrate in minutes.
Initialize the Purgr engine and compress your conversation history before sending it to your LLM provider.
const purgr = new Purgr({ activeWindow: 8, anchorCount: 3, scorerMode: 'auto' })
// Compress before your LLM call
const result = purgr.compress(conversationHistory)
// Pass compressed messages to your LLM
const response = await openai.chat.completions.create({
model: 'gpt-4o',
messages: result.messages
})
// Receipt is in result.signedReceipt
// Human-readable receipt box:
console.log(purgr.receipt(result.stats))
Architected for trust.
Purgr uses a multi-phase approach to ensure your most critical context is preserved while eliminating noise.
Active Window Protection.
The most recent N messages are never compressed and always pass through unchanged. Default: 8 messages.
Phase 1 — Momentum Scoring.
Every message receives a momentum score based on topical activity. Messages that decay are compressed.
Phase 2 — Koopman DMD.
Models conversation as a dynamical system, identifying structural topics that persist across changes.
Cryptographic Receipts.
Ed25519-signed receipts with Merkle roots over all decisions. Verifiable locally at purgr.dev/verify.
CLA Liveness Scoring.
NCD/LZ hash containment identifies logically necessary messages that momentum and DMD would incorrectly compress. Rescued messages are signed in the receipt. Pro feature — enableLiveness: true.
Fact Fidelity Scoring.
Post-compression deterministic verification. Every receipt shows how many critical facts (currency values, dates, identifiers, regulatory citations) survived. Signed in the Ed25519 receipt.
Purgr Recall.
Runs the full intelligence pipeline on both a source document and an AI response independently. Compares what was identified as important in the source against what survived in the response. Classifies every fact as Present, Modified, or Absent. Produces a signed Recall Receipt suitable for compliance documentation. Any value discrepancy — regardless of magnitude — is flagged for analyst review.
Comprehensive control.
The Purgr SDK provides low-level methods for granular control over the compression engine and receipt generation.
Primary method for compressing conversation history.
| Parameter | Type | Req | Description |
|---|---|---|---|
| messages | Message[] | Yes | Array of role/content objects |
| options.query | string | No | Binds receipt to this prompt |
| options.response | string | No | Commits response to receipt |
query: "What was the approved budget?",
response: "The approved budget is $2.4M"
})
Optimized for long-form documents (PDFs, transcripts, reports).
| Parameter | Type | Default | Description |
|---|---|---|---|
| text | string | req | Raw document text |
| config.profile | string | 'balanced' | 'conservative' | 'aggressive' |
For RAG pipelines. Deduplicates and filters retrieved chunks.
| Parameter | Type | Default | Description |
|---|---|---|---|
| chunks | CorpusChunk[] | req | Retrieved chunks with metadata |
| options.budget | number | 8000 | Maximum output tokens |
Standalone stateless function. No Purgr instance required. Proves which specific numbers, dates, and identifiers in an LLM response exist in the source document.
| Parameter | Type | Req | Description |
|---|---|---|---|
| documentText | string | Yes | Source document |
| llmResponse | string | Yes | AI response to verify |
| options.query | string | No | Optional query for receipt binding |
| options.privateKey | string | No | If provided, signs the result |
| options.publicKey | string | No | Required when privateKey provided |
{ groundingScore, groundedFacts, derivedFacts, ungroundedFacts, signedReceipt? }Three categories: Grounded — fact present verbatim in document. Derived — mathematically computable from adjacent document facts. Ungrounded ⚠ — not traceable, verify manually.
Honest scope: proves token presence, not relational accuracy.
const result = verifyDocument(contractText, llmAnalysis)
console.log(`Grounding: ${Math.round(result.groundingScore * 100)}%`)
console.log('Grounded:', result.groundedFacts)
console.log('⚠ Ungrounded:', result.ungroundedFacts)
Static method. Detects and parses any conversation export format into a standard messages array.
openai-api — JSON with messages array · chatgpt-export — JSON with mapping object · claude-web-export — Claude.ai export format · human-assistant — Human:/Assistant: format · chatgpt-text — User:/ChatGPT: format · prose-transcript — Any continuous prose, podcasts, interviews, raw chat logs
Returns: { messages, format, confidence } | null
if (parsed) {
console.log(`Format: ${parsed.format} (${parsed.confidence} confidence)`)
const result = purgr.compress(parsed.messages)
}
Generates a Merkle proof for a single compression decision. Allows proving one message outcome without revealing the full session.
Returns: { messageId, leafHash, proof, root } | null
The proof can be verified by any third party using verifyMerkleProof() without access to the full receipt.
const proof = purgr.proveDecision('msg-42')
// Third party verification — no full session required
import { verifyMerkleProof } from 'purgr'
const valid = verifyMerkleProof(proof.leafHash, proof.proof, proof.root)
// root should match receipt.payload.merkleRoot
Standalone async function. No Purgr instance required. Runs the full Purgr intelligence pipeline on both the source document and the AI response with zero compression — maximum preservation — to use the pipeline's intelligent fact identification. Compares what was identified as important in the source against what is present in the response. Produces a signed Recall Receipt. The compliance-grade artifact.
| Parameter | Type | Req | Description |
|---|---|---|---|
| documentText | string | Yes | Source document — contract, filing, report |
| aiResponse | string | Yes | The AI response to verify against the source |
| options.query | string | No | The prompt sent to AI — hashed and bound to receipt |
| options.chunkStrategy | string | No | 'auto' (default), 'paragraph', 'sentence', 'fixed' |
| options.chunkSize | number | No | Chunk size when chunkStrategy is 'fixed' |
| options.signer | object | No | { privateKey, publicKey } — uses persistent key if omitted |
{ receipt, warnings, error?, latencyMs }Receipt contains:
factsPresent, factsAbsent, factsModified, recallScore, documentPipeline, responsePipeline, merkleRoot, signature, publicKeyThree verdict categories: Present — fact found in response with identical value. Modified ⚠ — fact found but value differs — ANY discrepancy flagged regardless of magnitude. Absent ✗ — fact in source not found in response.
Important note: Modified verdict flags ANY numeric discrepancy — $47,382 vs $47,000 is modified. The analyst determines significance. Purgr does not make materiality judgments.
Pipeline info documented in receipt: which scorer phase ran (1 or 2), whether co-occurrence activated, whether liveness ran, whether fallback to regex occurred, chunk count and strategy used.
const result = await recall(contractText, aiAnalysis, {
query: "Summarize key financial obligations"
})
if (result.error) {
console.error(result.error)
} else {
console.log(`Recall Score: ${Math.round(result.receipt.recallScore * 100)}%`)
console.log('Modified facts requiring review:', result.receipt.factsModified)
console.log('Absent facts:', result.receipt.factsAbsent)
if (result.warnings.length > 0) console.warn(result.warnings)
}
Tune for performance.
Adjust constructor options to balance between aggressive token reduction and context preservation.
| Option | Type | Default | Description |
|---|---|---|---|
| activeWindow | number | 8 | Messages protected from compression |
| anchorCount | number | 3 | Max anchor summaries injected |
| scorerMode | string | 'auto' | 'momentum', 'dmd', or 'auto' |
| enableLiveness | boolean | false | CLA liveness scoring — rescues logically necessary messages. Pro feature. |
| enableCoOccurrence | boolean | false | Co-occurrence semantic similarity. Activates after 50 messages. Pro feature. |
| coOccurrenceWindow | number | 10 | Context window size for co-occurrence pairs |
| protectedLeadMessages | number | 5 | Oldest N messages permanently protected |
| factFidelityMaxTokens | number | 500000 | Token limit for fact fidelity pass. Set 0 to disable. |
Transparent boundaries.
Purgr is highly effective but has known limitations regarding semantic paraphrase and fact protection signals.
Semantic NIAH.
Pure semantic paraphrase NIAH scores 0% without an embedding model for conceptual fallback.
Topic Resurrection.
DMD may compress early topics before resurrection signals arrive if turns exceed 100+.
General Detail.
Fact protection triggers on high-specificity signals (currency, dates). Casual details are not protected.
Relational Accuracy.
Recall and verifyDocument() prove specific facts were present — dollar amounts, dates, identifiers. They do not verify relational accuracy. "Entity A wired $50K to Entity B" and "Entity B wired $50K to Entity A" both contain the same facts and both score as present. SVO triple extraction for relational grounding is on the roadmap.
Custom Fact Patterns.
The fact identification engine recognizes standard compliance fact types — currency, dates, percentages, regulatory citations, FAR/DFARS clauses, CLIN numbers. Custom fact patterns per engagement — CAGE codes, contract-specific identifiers, domain-specific terms — are on the roadmap for the compliance enterprise build.
Works with your stack.
Purgr is provider-agnostic. Use these patterns to integrate with OpenAI, Anthropic, or local models.
import OpenAI from 'openai'
const purgr = new Purgr({ activeWindow: 8 })
const openai = new OpenAI()
const result = purgr.compress(conversationHistory)
const response = await openai.chat.completions.create({
model: 'gpt-4o',
messages: result.messages
})
Command line power.
The Purgr CLI provides tools for proxying LLM traffic and managing local receipts.
| Command | Description |
|---|---|
| purgr proxy | Start the local compression proxy |
| purgr setup claude-desktop | Configure Claude Desktop integration |
| purgr mcp | Start MCP server |
| purgr receipts | View today's receipt log |
| purgr recall --document [file] --response [file] | Generate a Recall Receipt comparing document against AI response |
| purgr recall --document [file] --response [file] --query "text" | Recall with query binding |
| purgr receipts --verify [receipt.json] | Verify a saved receipt |
Verifiable context.
Every compression produces an Ed25519-signed receipt forming a tamper-evident chain.
| Field | Description |
|---|---|
| payload.inputHash | SHA-256 of uncompressed input |
| payload.merkleRoot | Merkle root over all decisions |
| signature | Ed25519 signature over payload |
| payload.decisionsCommitted | Count of individual decisions committed to Merkle tree |
| payload.receiptChainLength | Number of prior receipts linked in session chain |
| payload.factFidelityScore | Fraction of critical facts preserved (0.0–1.0) |
| payload.factFidelityPreserved | Count of facts preserved |
| payload.factFidelityTotal | Total facts detected |
| payload.livenessRescued | Messages rescued from compression by CLA liveness |
| payload.coOccurrenceActive | Whether co-occurrence matrix was active |
Recall Receipt — additional fields
| Field | Description |
|---|---|
| payload.receiptType | 'recall' — identifies this as a Recall Receipt |
| payload.documentHash | SHA-256 of exact source document text |
| payload.responseHash | SHA-256 of exact AI response text |
| payload.recallScore | Fraction of source facts present in response (0.0–1.0) |
| payload.factsPresentCount | Count of facts found in response with identical value |
| payload.factsAbsentCount | Count of source facts not found in response |
| payload.factsModifiedCount | Count of facts found but with any value discrepancy |
| payload.documentPipeline | Pipeline info — scorer phase, co-occurrence, liveness, fallback status |
| payload.responsePipeline | Same for response side |
| payload.merkleRoot | Binary Merkle tree root over all fact verdicts sorted by raw value |
| payload.keyMode | 'persistent' — engagement key / 'ephemeral' — session key only |
Portable session state.
A .purgr file is a portable session snapshot carrying compressed messages and signed receipts.
Basic Portability.
✓ Compressed messages
✓ Signed cryptographic receipt
– No DMD memory
– No encryption
Full Continuity.
✓ Everything in Free
✓ Full Purgr State (DMD memory)
✓ AES-256 Encryption
purgr export --passport --output session.purgr
# Pro: encrypted export
purgr export --passport --encrypt --passphrase "yourpass"
Common questions.
Everything you need to know about Purgr's performance and streaming support.