Context Engineering

Think of these as the five ways context engineering silently breaks.

**1. Context overload (the kitchen-sink prompt).** The field consensus: keep system prompts under ~2,000 tokens. Everything else should load on demand — exactly the pattern a skills architecture enforces. Cramming in everything the agent might need wastes most of those tokens on material that's only 10% relevant.

**2. Context poisoning.** One bad retrieved document can contaminate the agent's entire reasoning chain. The mitigations: add provenance tags to every retrieved chunk, apply freshness filters, and treat retrieved text as data — not as additional instructions.

**3. Naive RAG.** Dropping 50 unranked chunks into the context is where most RAG pipelines fail. The fix: retrieve wide (high recall), then re-rank hard to a precise top-5. Re-ranking is the dividing line between RAG that works and RAG that doesn't.

**4. Context rot in long sessions.** As conversations grow, earlier context degrades in influence. The fix: compaction triggers that summarize old turns, plus subagent offloading for bulk reads.

**5. LLM-generated context files.** The Gloaguen study found that auto-generated CLAUDE.md-style files can actually hurt performance. Write them by hand, from real institutional knowledge.

91% of engineering orgs have AI tooling — but only a small fraction govern it. The gap is context discipline.

ContextOps means treating context files the way you treat deployment config: defined once, versioned in git, reviewed before changes ship, automatically propagated to every tool format (CLAUDE.md, .mdc, copilot-instructions.md), and monitored for drift.

Here's the compounding argument: orgs that do this accumulate an organizational asset — institutional knowledge in machine-actionable form. Orgs that skip it accumulate context debt instead.

An AI OS Sprint is, in large part, paying down that context debt and installing governance so it doesn't re-accumulate.

There are four types of memory available to an agent system. Pick the simplest one that solves the problem.

**Session memory** — the active conversation plus compaction summaries. Resets when the session ends.

**Project memory** — files like CLAUDE.md, skill definitions, and reference docs. Versioned and human-curated. Persists across sessions.

**Long-term memory** — a vector store (pgvector or Pinecone) holding retrievable history: past deliverables, decisions, brand assets. Never blanket-loaded; only pulled when retrieval is triggered.

**Structured memory** — plain database tables for exact facts: budgets, targets, pointers to credentials. No semantic search needed; just a lookup.

The rule: prefer the dumbest memory type that works. Work down this list before reaching for the next.