Contextrie

Dynamic context curation for long-running agent work.

AI agents get worse as irrelevant context piles up. Contextrie helps you select, index, judge, and compose the right context for each task so long-running agent systems stay sharp.

Contextrie is a context-engineering toolkit for agent workflows.

Use it in two ways:

• as a library inside your own agent system with @contextrie/core and @contextrie/parsers
• as a local CLI that indexes project files and composes task-specific context into .contextrie/context.md

Status: early development; expect breaking changes.

---

Start Here

CLI quickstart

Install the published CLI and use contextrie directly.

npm install -g @contextrie/cli
contextrie --index --all --openai-api-key "$OPENAI_API_KEY" --openai-model "gpt-5.4"
contextrie --task "Summarize the files most relevant to parser source path handling."

This writes:

• .contextrie/sources.json: indexed source metadata
• .contextrie/context.md: the composed task-specific context

Use --openai-base-url as well if you are targeting an OpenAI-compatible provider.

For local development inside this repo, you can still run bun run ./cli/index.ts ....

Library quickstart

Install the packages:

npm install @contextrie/core @contextrie/parsers

Extremely brief how to:

import { openai } from "@ai-sdk/openai";
import {
  ComposerAgent,
  DocumentSource,
  IndexingAgent,
  JudgeAgent,
} from "@contextrie/core";

const model = openai("gpt-5.4");
const objective = "response";
const task = "Explain which internal docs matter most when debugging why retrieval is missing indexed metadata.";
const source = new DocumentSource(
  "indexing-architecture",
  undefined,
  "Indexed sources store generated metadata separately from source content, and shallow judgment relies on that metadata for fast relevance scoring.",
);
const indexed = await new IndexingAgent(model).add(source).run();
const judgments = await new JudgeAgent(model).from(indexed).run({
  objective,
  input: task,
});
const context = await new ComposerAgent(model)
  .from(
    Object.fromEntries(
      indexed.map((item) => [item.id, { source: item, decision: judgments[item.id] }]),
    ),
  )
  .run({
    objective,
    input: task,
  });

console.log(context);

---

Packages

• @contextrie/core: published now, TypeScript contracts and core agents
• @contextrie/parsers: published now, file parsers for .csv, .md, and .txt
• @contextrie/cli: published npm CLI for indexing local sources and composing task-specific context
• docs: documentation site in progress

---

Examples

Runnable examples are available in examples/.

Start with examples/demo/README.md for the smallest end-to-end flow:

• index a few sources
• judge them against a task
• compose the final context output

Use examples/parsers/README.md for a standalone package example that consumes @contextrie/parsers and parses local files into Contextrie sources.

---

Repo Layout

.
├─ assets/        Visuals and branding
├─ cli/           Published npm CLI package
├─ core/          TypeScript library (npm)
├─ docs/          SvelteKit documentation site
├─ examples/      Minimal examples
├─ parsers/       File parsing library (npm)
└─ readme.md      Project overview

---

Concepts

• Sources always carry underlying content
• A source without metadata is still draft
• IndexingAgent adds metadata to that source for retrieval and shallow judgment

State flow:

flowchart LR
  Source["Source (content, no metadata)"] --> IndexedSource["Source (content + metadata)"]

Loading

---

Development

Each package installs dependencies independently. Run bun install in the relevant directory, then use its commands:

Directory	Commands	Guide
core/	bun run typecheck	Core
parsers/	bun run typecheck	Parsers
cli/	bun run typecheck, bun run build	CLI
docs/	bun run dev, bun run check, bun run build	Docs

See CONTRIBUTING.md for contribution guidelines.