context-engine · diff

v1.0.0 to v1.1.0

25 added, 376 removed. Audit A to A.

---

name: context-engine

description: >

Context management engine for AI coding agents. Use when building agent memory systems,

optimizing context windows, allocating token budgets, designing RAG pipelines for code, or

managing persistent multi-session agent state.

license: MIT + Commons Clause

metadata:

- version: 1.0.0

+ version: 1.1.0

author: borghei

category: engineering

domain: ai-agents

tier: POWERFUL

- updated: 2026-03-09

+ updated: 2026-06-17

frameworks: context-window-optimization, memory-architecture, knowledge-graphs

---

# Context Engine - AI Agent Context Management

- **Tier:** POWERFUL

- **Category:** Engineering

- **Tags:** context management, AI agents, memory systems, RAG, token optimization, knowledge graphs

- ## Overview

Context Engine provides production-grade patterns for managing what AI agents know, remember, and retrieve. It covers the full lifecycle: ingestion of project knowledge, optimal packing of context windows, persistent memory across sessions, and retrieval-augmented generation for large codebases. The difference between a useful agent and a hallucinating one is context management.

## Core Capabilities

- ### 1. Context Window Architecture

- Every AI agent operates within a finite context window. Mismanaging it is the #1 cause of degraded agent performance.

- #### Token Budget Allocation Framework

- |---------|----------|---------|----------|

- #### Context Packing Strategies

- **Greedy Relevance Packing**

- ```

- 1. Score all candidate context by relevance to current task

- 2. Sort by score descending

- 3. Pack until budget exhausted

- 4. Always reserve output buffer

- ```

- - Pros: Simple, fast, works well for focused tasks

- - Cons: Misses cross-cutting context, no diversity

- **Tiered Loading**

- ```

- Tier 0 (always loaded): System prompt, project rules, active file

- Tier 1 (task-specific): Related files, type definitions, tests

- Tier 2 (on-demand): Documentation, examples, history

- Tier 3 (retrieved): Search results, RAG chunks

- ```

- - Pros: Predictable, debuggable, respects fixed costs

- - Cons: Requires upfront tier classification

- **Adaptive Compression**

- ```

- 1. Load full context for first pass

- 2. Identify low-signal sections (boilerplate, repetitive code)

- 3. Summarize or truncate low-signal sections

- 4. Re-pack with compressed context

- 5. Preserve high-signal sections verbatim

- ```

- - Pros: Maximizes information density

- - Cons: Risk of losing important details in compression

- ### 2. Memory Architecture

- #### Three-Layer Memory Model

- ```

- ┌─────────────────────────────────────────────────┐

- │ Layer 1: Working Memory (Context Window) │

- │ Scope: Current conversation/task │

- │ Lifetime: Single session │

- │ Storage: In-context tokens │

- │ Update: Every turn │

- ├─────────────────────────────────────────────────┤

- │ Layer 2: Session Memory (Persistent Store) │

- │ Scope: Project-level learnings │

- │ Lifetime: Across sessions │

- │ Storage: MEMORY.md, .claude/rules/, CLAUDE.md │

- │ Update: End of session or on discovery │

- ├─────────────────────────────────────────────────┤

- │ Layer 3: Knowledge Base (Indexed Corpus) │

- │ Scope: Full codebase + documentation │

- │ Lifetime: Persistent, versioned │

- │ Storage: Vector store, graph DB, file index │

- │ Update: On commit / scheduled reindex │

- └─────────────────────────────────────────────────┘

- ```

- #### Memory Promotion Protocol

- Knowledge flows upward through layers based on recurrence and value:

- | Signal | Action | Example |

- |--------|--------|---------|

- | Pattern seen 1x | Working memory only | "This file uses tabs" |

- | Pattern seen 2-3x | Candidate for session memory | "Project uses pnpm everywhere" |

- | Pattern confirmed across sessions | Promote to CLAUDE.md/rules | "Always use pnpm, never npm" |

- | Pattern is domain knowledge | Add to knowledge base | "Auth flow uses JWT + refresh tokens" |

- #### Staleness Detection

- Context has a shelf life. Stale context causes hallucinations.

- ```

- Freshness Score = f(last_verified, change_frequency, confidence)

- Fresh (< 7 days, file unchanged): Use directly

- Aging (7-30 days, file changed): Re-verify before using

- Stale (> 30 days): Flag, re-retrieve, or discard

- Unknown (never verified): Treat as low-confidence

- ```

- ### 3. Retrieval Strategies for Code

- #### File-Level Retrieval

- Best for: navigating to the right file when the agent knows what it needs.

- ```

- Query: "authentication middleware"

- Strategy:

- 1. Filename pattern match: *auth*, *middleware*

- 2. Import graph: files that import auth modules

- 3. Symbol search: exported functions matching auth*

- 4. Content search: files containing auth-related patterns

- 5. Rank by: recency of edit + import centrality + name match

- ```

- #### Chunk-Level Retrieval (RAG for Code)

- Best for: finding specific implementations within large files.

- **Chunking Strategy for Source Code:**

- - Chunk by function/class boundaries (never mid-function)

- - Include the function signature + docstring + body as one chunk

- - Attach metadata: file path, language, exports, imports

- - Overlap: include 2 lines above/below for context

- - Max chunk size: 200 lines (larger functions get sub-chunked by logical block)

- **Embedding Considerations:**

- - Code-specific embeddings (CodeBERT, StarCoder embeddings) outperform general text embeddings by 15-30% on code retrieval tasks

- - Hybrid search (keyword + semantic) outperforms either alone

- - Index function signatures separately for fast symbol lookup

- #### Dependency-Aware Retrieval

- When retrieving a function, also retrieve:

- 1. Its type definitions (interfaces, types it uses)

- 2. Its direct dependencies (imported functions it calls)

- 3. Its tests (to understand expected behavior)

- 4. Its callers (to understand usage context)

- This "context neighborhood" approach prevents the agent from seeing a function in isolation.

- ### 4. Knowledge Graph Construction

- #### Codebase Graph Schema

- ```

- Nodes:

- - File (path, language, size, last_modified)

- - Function (name, signature, docstring, complexity)

- - Class (name, methods, properties, inheritance)

- - Module (name, exports, dependencies)

- - Test (name, covers, assertions)

- - Config (type, values, affects)

- Edges:

- - IMPORTS (File → File)

- - CALLS (Function → Function)

- - IMPLEMENTS (Class → Interface)

- - TESTS (Test → Function)

- - CONFIGURES (Config → Module)

- - DEPENDS_ON (Module → Module)

- ```

- #### Graph Queries for Context

- | Agent Question | Graph Query | Context Retrieved |

- |---------------|-------------|-------------------|

- | "How does auth work?" | Subgraph around auth module, 2 hops | Auth files + dependencies + tests |

- | "What breaks if I change X?" | Reverse dependency traversal from X | All callers + their tests |

- | "What's the API surface?" | All exported functions from API modules | Route handlers + types + middleware |

- | "How is this tested?" | TEST edges from target function | Test files + fixtures + mocks |

- ### 5. Context Window Optimization Patterns

- #### Pattern: Sliding Window with Anchors

- For long conversations, maintain fixed "anchor" messages while sliding recent history.

- ```

- [System Prompt] ← Fixed anchor (never evicted)

- [Task Definition] ← Fixed anchor

- [Key Decision #1] ← Pinned (user marked as important)

- [Key Decision #2] ← Pinned

- ...

- [Turn N-4] ← Sliding window starts here

- [Turn N-3]

- [Turn N-2]

- [Turn N-1]

- [Current Turn]

- [Output Buffer] ← Reserved

- ```

- #### Pattern: Progressive Summarization

- When conversation exceeds budget:

- 1. Summarize oldest turns into a "conversation summary" block

- 2. Keep the summary as a single anchor message

- 3. Update summary every N turns

- 4. Always keep: first system message, task definition, last 5 turns

- #### Pattern: Selective Tool Result Caching

- Tool outputs (file reads, search results, command output) consume the most tokens.

- ```

- Strategy:

- - Cache tool results keyed by (tool, args, file_hash)

- - On re-request: serve from cache (0 new tokens)

- - On file change: invalidate cache for that file

- - Always truncate: command output > 200 lines → first 50 + last 50

- - Never cache: error output (always show in full)

- ```

- ### 6. Multi-Agent Context Sharing

- When multiple agents collaborate, context synchronization becomes critical.

- #### Shared Context Bus

- ```

- ┌──────────┐ ┌──────────────────┐ ┌──────────┐

- │ Agent A │────▶│ Shared Context │◀────│ Agent B │

- │ (Planner) │ │ - Task state │ │ (Coder) │

- └──────────┘ │ - Decisions log │ └──────────┘

- │ - File changes │

- ┌──────────┐ │ - Constraints │ ┌──────────┐

- │ Agent C │────▶│ - Artifacts │◀────│ Agent D │

- │ (Reviewer)│ └──────────────────┘ │ (Tester) │

- └──────────┘ └──────────┘

- ```

- #### Context Handoff Protocol

- When Agent A passes work to Agent B:

- 1. **State Summary**: What was done, decisions made, current state

- 2. **Relevant Artifacts**: Files created/modified, with paths

- 3. **Constraints**: What must not be changed, invariants

- 4. **Open Questions**: Unresolved decisions that need Agent B's input

- 5. **Next Steps**: Explicit instructions for what Agent B should do

- Anti-pattern: Passing the entire conversation history. Always summarize.

- ## Workflows

- ### Workflow 1: Bootstrap Agent Context for a New Codebase

- ```

- Step 1: Index the codebase

- - Build file tree with metadata (language, size, last modified)

- - Extract all exports, imports, and dependency edges

- - Identify entry points (main files, route handlers, CLI commands)

- Step 2: Construct initial knowledge graph

- - Map module dependencies

- - Identify architectural layers (API, service, data, config)

- - Detect frameworks and conventions (naming, structure, patterns)

- Step 3: Generate project summary

- - One paragraph: what this project does

- - Architecture diagram (text-based)

- - Key directories and their roles

- - Critical files (config, entry points, shared types)

- Step 4: Configure context tiers

- - Tier 0: Project summary, CLAUDE.md, active file

- - Tier 1: Related files within same module

- - Tier 2: Cross-module dependencies

- - Tier 3: Documentation and examples

- ```

- ### Workflow 2: Optimize Context for a Specific Task

- ```

- Step 1: Parse task requirements

- - Extract entities (files, functions, features mentioned)

- - Identify task type (bug fix, feature, refactor, review)

- Step 2: Retrieve relevant context

- - File-level: files matching entities

- - Dependency-level: imports/exports of matched files

- - Test-level: tests covering matched code

- - History-level: recent changes to matched files

- Step 3: Budget allocation

- - Calculate total tokens available

- - Allocate per tier (see Token Budget Framework)

- - Pack context with greedy relevance

- Step 4: Verify coverage

- - Check: all mentioned files included?

- - Check: type definitions for used types included?

- - Check: test examples for expected behavior included?

- - If gaps: retrieve missing context from lower tiers

- ```

- ### Workflow 3: Session Memory Management

- ```

- Step 1: During session - capture learnings

- - New patterns discovered: log to working memory

- - Corrections received: mark as high-confidence learning

- - Errors encountered: log with resolution

- Step 2: End of session - evaluate learnings

- - Which learnings are project-specific vs session-specific?

- - Which patterns recurred during this session?

- - Which corrections should become rules?

- Step 3: Promote valuable learnings

- - Recurring patterns → CLAUDE.md or .claude/rules/

- - Project conventions → project documentation

- - Error resolutions → knowledge base

- Step 4: Prune stale memory

- - Remove learnings about deleted files

- - Update learnings contradicted by new information

- - Archive session-specific context

- ```

- ## Anti-Patterns

- | Anti-Pattern | Problem | Better Approach |

- |-------------|---------|-----------------|

- | Dumping entire files into context | Wastes tokens on irrelevant code | Retrieve specific functions/sections |

- | No output buffer reservation | Agent output gets truncated | Always reserve 10-15% for output |

- | Static context loading | Same context regardless of task | Dynamic retrieval based on task type |

- | No staleness tracking | Using outdated information | Timestamp and verify before using |

- | Full conversation replay | Older turns crowd out relevant code | Sliding window with summarization |

- | Ignoring import graph | Missing type definitions, broken understanding | Always include direct dependencies |

+ - **Context window architecture** — token budget allocation plus greedy, tiered, and adaptive-compression packing strategies.

+ - **Memory architecture** — three-layer model (working / session / knowledge base), promotion protocol, and staleness detection.

+ - **Code retrieval** — file-level, chunk-level (RAG), and dependency-aware retrieval with code chunking and embedding guidance.

+ - **Knowledge graph construction** — codebase graph schema (nodes + edges) and graph queries that resolve agent questions.

+ - **Window optimization patterns** — sliding window with anchors, progressive summarization, selective tool-result caching.

+ - **Multi-agent context sharing** — shared context bus and a five-element handoff protocol.

- ## Evaluation Metrics

+ ## When to Use

- | Metric | Description | Target |

- |--------|-------------|--------|

- | Context Relevance | % of loaded context actually used in response | > 70% |

- | Retrieval Precision | % of retrieved items that are relevant | > 80% |

- | Token Utilization | % of context budget used productively | > 85% |

- | Staleness Rate | % of context items that are outdated | < 5% |

- | Cache Hit Rate | % of tool results served from cache | > 40% |

- | Handoff Completeness | % of required context passed between agents | 100% |

+ - Bootstrapping agent context for a new codebase (index → graph → summary → tiers).

+ - Optimizing context for a specific task (bug fix, feature, refactor, review).

+ - Capturing, promoting, and pruning session memory across sessions.

+ - Designing a RAG pipeline for code retrieval.

+ - Coordinating context across multiple collaborating agents.

- ## Integration Points

+ ## Tools

- | Skill | Integration |

- |-------|-------------|

- | **rag-architect** | Use RAG Architect for vector store design; Context Engine for retrieval strategy |

- | **agent-designer** | Agent Designer defines agent roles; Context Engine manages what each agent knows |

- | **self-improving-agent** | Self-Improving Agent promotes learnings; Context Engine decides when/how to load them |

- | **observability-designer** | Monitor context utilization metrics alongside agent performance |

+ | Tool | Purpose | Command |

+ |------|---------|---------|

+ | `context_analyzer.py` | Analyze files/prompts for token usage, relevance, and optimization suggestions | `python scripts/context_analyzer.py src/ --budget 128000 --json` |

+ | `context_pruner.py` | Prune low-relevance content, redundancy, and verbose patterns from context | `python scripts/context_pruner.py src/main.py --aggressive --json` |

+ | `memory_indexer.py` | Index and search a memory/knowledge base with TF-IDF relevance scoring | `python scripts/memory_indexer.py docs/ --query 'auth middleware' --top 5` |

## References

- - `references/context-window-strategies.md` - Detailed packing algorithms and benchmarks

- - `references/code-retrieval-patterns.md` - RAG for code: chunking, embedding, and ranking strategies

- - `references/memory-architecture-guide.md` - Multi-layer memory system design patterns

- ## Troubleshooting

- | Problem | Cause | Solution |

- |---------|-------|----------|

- | Agent responses ignore relevant files | Context retrieval missing import graph traversal | Enable dependency-aware retrieval; always include direct imports and type definitions alongside target files |

- | Output truncated mid-response | No output buffer reserved in token budget | Reserve 10-15% of context window for generation; reduce Tier 2/3 content first |

- | Stale context causing hallucinations | Memory layer not tracking file modification timestamps | Implement staleness detection with freshness scores; invalidate cache entries when source files change |

- | RAG retrieval returns irrelevant chunks | Chunking splits functions mid-body or ignores code structure | Switch to AST-aware chunking at function/class boundaries; attach file path and export metadata to each chunk |

- | Context window exceeded on large tasks | Greedy packing loads too many full files | Use adaptive compression: summarize boilerplate, load only signatures for low-priority files, keep high-signal code verbatim |

- | Multi-agent handoff loses critical state | Raw conversation history passed instead of structured summary | Follow the Context Handoff Protocol: pass state summary, artifacts, constraints, open questions, and next steps |

- | Knowledge graph queries return empty results | Graph not rebuilt after major refactors or branch switches | Schedule reindexing on commit hooks or branch checkout; validate node counts after rebuild |

- ## Success Criteria

+ Load the reference that matches the task — keep this file lean and pull detail on demand:

- - **Context Relevance above 70%**: At least 70% of tokens loaded into the context window are directly referenced or used in the agent's response.

- - **Retrieval Precision above 80%**: More than 80% of retrieved code chunks or files are relevant to the current task, measured by human evaluation or downstream task success.

- - **Token Utilization above 85%**: Productive token usage (system instructions + task-relevant code + active conversation) exceeds 85% of the allocated budget, with less than 15% wasted on redundant or low-signal content.

- - **Staleness Rate below 5%**: Fewer than 5% of context items are outdated (file changed since last retrieval without re-verification), validated by comparing loaded content hashes against current file state.

- - **Cache Hit Rate above 40%**: At least 40% of repeated tool invocations (file reads, searches) are served from cache, reducing redundant token consumption and latency.

- - **Handoff Completeness at 100%**: Every multi-agent context handoff includes all five protocol elements (state summary, artifacts, constraints, open questions, next steps) with zero information gaps.

- - **Session Memory Promotion Accuracy above 90%**: Learnings promoted to persistent memory (CLAUDE.md, rules files) are validated as still accurate within 30 days, with fewer than 10% requiring correction or rollback.

+ - **[references/context-window-strategies.md](references/context-window-strategies.md)** — budget allocation, packing strategies, and window-optimization patterns. Read when planning budgets or optimizing a long conversation.

+ - **[references/memory-architecture-guide.md](references/memory-architecture-guide.md)** — three-layer memory model, promotion protocol, staleness detection, shared context bus + handoff protocol. Read when designing persistent memory or coordinating agents.

+ - **[references/code-retrieval-patterns.md](references/code-retrieval-patterns.md)** — file/chunk/dependency-aware retrieval, chunking/embedding guidance, knowledge-graph schema and queries. Read when building RAG for code.

+ - **[references/workflows-and-quality.md](references/workflows-and-quality.md)** — the three workflows, anti-patterns, evaluation metrics, troubleshooting, and success criteria. Read before running a workflow and before shipping.

## Scope & Limitations

**This skill covers:**

- Context window token budget planning, allocation strategies, and packing algorithms for AI coding agents.

- Multi-layer memory architecture design (working memory, session memory, knowledge base) with promotion and staleness protocols.

- Code-specific retrieval strategies including file-level, chunk-level, and dependency-aware retrieval for RAG pipelines.

- Knowledge graph construction from codebases and graph-based context queries for agent workflows.

**This skill does NOT cover:**

- Vector store infrastructure setup, embedding model selection, or database deployment — see **rag-architect** for vector store design and embedding strategies.

- Agent role definition, personality design, or multi-agent orchestration logic — see **agent-designer** for agent architecture and **agent-workflow-designer** for orchestration patterns.

- Runtime observability, metrics dashboards, or alerting for agent systems — see **observability-designer** for monitoring and instrumentation.

- Prompt engineering techniques, chain-of-thought design, or instruction tuning — see **prompt-engineer-toolkit** for prompt construction patterns.

## Integration Points

| Skill | Integration | Data Flow |

|-------|-------------|-----------|

| **rag-architect** | Context Engine defines retrieval strategies; RAG Architect implements the vector store and embedding pipeline | Retrieval queries flow from Context Engine to RAG Architect's indexed store; ranked results flow back as context chunks |

| **agent-designer** | Agent Designer defines agent roles and capabilities; Context Engine manages per-agent context budgets and memory layers | Agent specifications define context requirements; Context Engine returns tailored context windows per agent role |

| **self-improving-agent** | Self-Improving Agent identifies recurring patterns and corrections; Context Engine decides when to promote learnings to persistent memory | Candidate learnings flow from Self-Improving Agent; promotion decisions and memory updates flow back through Context Engine's staleness and promotion protocols |

| **observability-designer** | Observability Designer instruments context utilization metrics (relevance, staleness, cache hits); Context Engine exposes metric endpoints | Raw metric events flow from Context Engine; Observability Designer aggregates into dashboards and alerts |

| **agent-workflow-designer** | Agent Workflow Designer defines multi-agent handoff sequences; Context Engine implements the shared context bus and handoff protocol | Workflow definitions specify which agents share context; Context Engine manages the context bus, serialization, and handoff payloads |

| **codebase-onboarding** | Codebase Onboarding generates project summaries and architecture maps; Context Engine consumes these as Tier 0 bootstrap context | Onboarding artifacts (project summary, directory map, entry points) feed into Context Engine's initial knowledge graph and context tiers |