@ashlr/core-efficiency

Token-efficiency primitives for AI coding agents — genome RAG, multi-tier context compression, provider-aware budgeting, and prompt-caching helpers.

Extracted from ashlrcode and shared by the ashlrcode CLI and the ashlr-plugin for Claude Code.

Platform support: macOS / Linux / Windows on Bun >= 1.0 and Node >= 20.

Modules

| Subpath | LOC | Purpose | |---------|-----|---------| | /genome | ~2,342 | Self-evolving project specs via RAG + scribe protocol. Manifest CRUD, TF-IDF/Ollama retrieval, fitness-based strategy evolution, mutation audit trail. | | /compression | ~470 | 3-tier context compression: autoCompact (LLM summarize old turns), snipCompact (truncate tool results > 2 KB), contextCollapse (drop short/dup). PromptPriority enum. | | /budget | ~50 | Provider-aware prompt budgeting. getProviderContextLimit, systemPromptBudget. | | /tokens | ~50 | Token estimation: estimateTokensFromString, estimateTokensFromMessages. | | /anthropic | ~200 | Anthropic SDK helpers: withGenome, cacheBreakpoints, ashlrMcpConfig. | | /session-log | ~150 | Structured session event log (tool calls, costs, savings). | | /local | ~120 | Context-window manager for small-context local models. | | /types | ~60 | Shared types: Message, ContentBlock, LLMSummarizer, StreamEvent. |

Install

# Bun (primary runtime)
bun add @ashlr/core-efficiency

# npm / pnpm / yarn
npm install @ashlr/core-efficiency

For local development against a checkout:

bun add file:../ashlr-core-efficiency

The package ships TypeScript source in src/. Bun runs it directly. For Node.js, compile first with bun run build (outputs to dist/).

Quickstart

compression

import {
  autoCompact,
  snipCompact,
  contextCollapse,
  PromptPriority,
} from "@ashlr/core-efficiency/compression";

// Truncate any tool result that exceeds 2 KB (head + tail elided middle).
const trimmed = snipCompact(messages, { maxBytes: 2048 });

// Drop short or duplicate messages to reduce prompt size.
const collapsed = contextCollapse(messages);

// LLM-summarize old turns when approaching the context limit.
const compacted = await autoCompact(messages, summarizer, {
  targetTokens: 50_000,
  priority: PromptPriority.High,
});

budget

import {
  getProviderContextLimit,
  systemPromptBudget,
} from "@ashlr/core-efficiency/budget";

const limit = getProviderContextLimit("anthropic");     // 200_000
const budget = systemPromptBudget("anthropic", 0.05, 50_000);  // 5% floor, 50K cap

tokens

import {
  estimateTokensFromString,
  estimateTokensFromMessages,
} from "@ashlr/core-efficiency/tokens";

const n = estimateTokensFromString("Hello, world!");
const total = estimateTokensFromMessages(messages);  // walks ContentBlock[] incl. tool results

genome

import {
  retrieveSectionsV2,
  injectGenomeContext,
  genomeExists,
} from "@ashlr/core-efficiency/genome";

if (await genomeExists(process.cwd())) {
  const sections = await retrieveSectionsV2("architecture overview", process.cwd(), {
    maxTokens: 2000,
  });
  const system = injectGenomeContext(baseSystem, sections);
}

anthropic

import Anthropic from "@anthropic-ai/sdk";
import { withGenome, cacheBreakpoints } from "@ashlr/core-efficiency/anthropic";

const client = new Anthropic();
const system = await withGenome("You are a senior engineer.", process.cwd());

const req = cacheBreakpoints({
  system,
  messages: [
    { role: "user", content: projectContext, cache: true },
    { role: "user", content: "What does login.ts do?" },
  ],
});

await client.messages.create({ ...req, model: "claude-sonnet-4-6", max_tokens: 1024 });

For stdio MCP tools via the Agent SDK:

import { query } from "@anthropic-ai/claude-agent-sdk";
import { ashlrMcpConfigRecord } from "@ashlr/core-efficiency/anthropic";

const mcpServers = ashlrMcpConfigRecord({ plugins: ["efficiency"] });
for await (const msg of query({ prompt: "...", options: { mcpServers } })) {
  // ...
}

See examples/anthropic-sdk/ for runnable scenarios.

session-log

import { SessionLog } from "@ashlr/core-efficiency/session-log";

const log = new SessionLog();
log.record({ type: "tool_call", tool: "ashlr__read", inputTokens: 120 });
console.log(log.summary());

local

import { LocalContextManager } from "@ashlr/core-efficiency/local";

const mgr = new LocalContextManager({ contextWindow: 4096 });
const messages = mgr.fit(allMessages);  // drops oldest turns to stay within window

Root barrel export (all subpaths re-exported):

import {
  autoCompact,
  getProviderContextLimit,
  retrieveSectionsV2,
  estimateTokensFromString,
} from "@ashlr/core-efficiency";

Compatibility

| Runtime | macOS | Linux | Windows | |---------|-------|-------|---------| | Bun >= 1.0 | Yes | Yes | Yes | | Node >= 20 | Yes (compile first) | Yes (compile first) | Yes (compile first) |

Path separators are normalized internally; no Unix-only assumptions.

Development

bun install
bun test          # ~17 unit tests (budget + tokens)
bun run typecheck
bun run build     # emit dist/ for Node consumers

Integration tests live in the ashlrcode repo where 700+ tests run against real-world consumers.

Design notes

• LLMSummarizer interface: autoCompact and genome scribe depend on a minimal { stream(ProviderRequest): AsyncGenerator<StreamEvent> } contract, not a concrete router. Consumers inject their own provider.
• PromptPriority enum: 12 named slots (Core=0 through Undercover=95). Numeric values are stable — raw-int callers continue to work across versions.
• estimateTokens: previously duplicated in three places. Now one implementation, two entry points: FromString and FromMessages (walks ContentBlock[] including tool_use/tool_result).
• Source-first exports: main and exports point to src/. Bun resolves .ts imports directly. For Node.js, run bun run build and consume from dist/. A module field mirrors main for bundlers that inspect it.

Versioning

Follows semver. Breaking changes (removed exports, changed interfaces) go to major versions. Additive exports and bug fixes are minor/patch.

License

MIT — see LICENSE.