Contextia

Contextia proves one narrow thing well: given a workspace, a declared budget, and a small set of explicit sources, the library builds a deterministic context bundle and can write one safe journal entry when asked.

What v1 Proves

• Workspace conventions such as AGENTS.md and MEMORY.md are discovered deterministically.
• Manual sources are included in a stable order.
• drop-tail compaction omits trailing sources when the declared budget would be exceeded.
• Journal persistence only accepts allowlisted, developer-readable fields.

Canonical Flow

1. Start with createContextBundle(workspacePath).
2. Add one manual source.
3. Set budget and optional compactionPolicy: { strategy: "drop-tail" }.
4. Optionally set explicit ordering controls (kindWeights, groupRanks, sourceOverrides).
5. Build and inspect included, omitted, and orderingRationale.
6. Optionally call writeJournalEntry(...) once to persist a safe operational record.

Builder-First API

import { createContextBundle } from "contextia";

const bundle = await createContextBundle("/path/to/workspace")
  .setBudget(10_000)
  .addManualSource({
    id: "manual:brief",
    label: "Brief",
    content: "Keep deterministic ordering explicit.",
    priority: 50,
    group: "reference",
  })
  .setOrdering({
    kindWeights: { convention: 0, manual: 1 },
    groupRanks: { reference: 0, optional: 50 },
    sourceOverrides: { "manual:brief": { rank: 0 } },
  })
  .build();

Legacy Migration

buildContextBundle(options) is still available as a soft-migration wrapper. It maps legacy options to the builder internally and preserves deterministic behavior when ordering is omitted.

Legacy call:

await buildContextBundle({
  workspacePath,
  budget: 10_000,
  manualSources: [{ id: "manual:brief", label: "Brief", content: "x", priority: 50 }],
});

Builder equivalent:

await createContextBundle(workspacePath)
  .setBudget(10_000)
  .addManualSource({ id: "manual:brief", label: "Brief", content: "x", priority: 50 })
  .build();

Canonical Example

• Example file: examples/canonical-context-bundle.ts
• Run it from a workspace root that contains AGENTS.md and MEMORY.md because it uses process.cwd() as workspacePath.
• Example:
  • cd test/fixtures/workspace-basic
  • bun ../../../examples/canonical-context-bundle.ts

Public API

• createContextBundle(workspacePath)
• buildContextBundle(options)
• writeJournalEntry(options)

Run It

• bun test
• bun run typecheck
• bun run build

Reference Docs

• Runtime prompt contract
• Core terms