context-engineering

🧠 Context Engineering is an open-source toolkit to visualize, test, and optimize how LLMs process context windows. Includes a Streamlit app, RAG simulation, educational docs, and Docker supportβ€”perfect for prompt engineers, researchers, and AI developers.

https://github.com/oxbshw/context-engineering

Science Score: 44.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • βœ“
    CITATION.cff file
    Found CITATION.cff file
  • βœ“
    codemeta.json file
    Found codemeta.json file
  • βœ“
    .zenodo.json file
    Found .zenodo.json file
  • β—‹
    DOI references
  • β—‹
    Academic publication links
  • β—‹
    Academic email domains
  • β—‹
    Institutional organization owner
  • β—‹
    JOSS paper metadata
  • β—‹
    Scientific vocabulary similarity
    Low similarity (9.1%) to scientific vocabulary
Last synced: 9 months ago · JSON representation ·

Repository

🧠 Context Engineering is an open-source toolkit to visualize, test, and optimize how LLMs process context windows. Includes a Streamlit app, RAG simulation, educational docs, and Docker supportβ€”perfect for prompt engineers, researchers, and AI developers.

Basic Info
  • Host: GitHub
  • Owner: oxbshw
  • License: mit
  • Language: Python
  • Default Branch: main
  • Size: 0 Bytes
Statistics
  • Stars: 0
  • Watchers: 0
  • Forks: 0
  • Open Issues: 0
  • Releases: 0
Created 11 months ago · Last pushed 11 months ago
Metadata Files
Readme License Citation

README.md

Context Engineering Toolkit

Introduction

Welcome to the Context Engineering Toolkit! This open-source project provides a comprehensive suite of tools for developing advanced conversational AI systems through layered context management. Whether you're a prompt engineer, AI researcher, or developer, this toolkit offers visualizations, simulations, and practical implementations to help you understand and optimize how language models process context.

Key Features

  • Layered Context Management: Implement context engineering principles across multiple layers (atomic, molecular, cellular, organ, field, and meta-recursive)
  • Context Field Operations: Manage continuous semantic operations with attractors, resonance, and emergence
  • Protocol Shells: Execute structured field operations for co-emergence, resonance scaffolding, memory management, and self-repair
  • Self-Improvement Capabilities: Demonstrate meta-recursive improvement through continuous learning and adaptation
  • Visualization Tools: Include tools for visualizing context fields, attractor dynamics, and field operations
  • Educational Resources: Provide documentation and examples to help understand context engineering concepts

Architecture

Context Field Architecture: β”œβ”€β”€ Core Layer: Basic conversation handling β”œβ”€β”€ Protocol Layer: Field operations and resonance β”œβ”€β”€ Memory Layer: Persistent attractor dynamics β”œβ”€β”€ Meta Layer: Self-reflection and improvement └── Integration: Unified field orchestration

Project Diagram

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Project Ecosystem β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ chatbot_ │◄──►│ protocol_ │◄──►│ context_ β”‚ β”‚ β”‚ β”‚ core.py β”‚ β”‚ shells.py β”‚ β”‚ field.py β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β–Ό β–Ό β–Ό β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ conversationβ”‚ β”‚ meta_ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ examples.py β”‚ β”‚ recursive_ β”‚ β”‚ utils.py β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ demo.py β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ docs/ β”‚ β”‚ notebooks/ β”‚ β”‚ assets/ β”‚ β”‚ β”‚ β”‚ tutorials β”‚ β”‚ examples β”‚ β”‚ diagrams β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Getting Started

Prerequisites

  • Python 3.8+
  • Required packages: numpy, matplotlib, scipy

Installation

bash git clone https://github.com/oxbshw/context-engineering.git cd context-engineering pip install -r requirements.txt

Usage

Basic Conversation

```python from chatbot_core import ToyContextChatbot

Initialize the chatbot

chatbot = ToyContextChatbot()

Start a conversation

response = chatbot.chat("Hello, how are you?") print(response)

Show field state

chatbot.showfieldstate() ```

Demonstrate Field Operations

```python

Execute protocol shells

attractorresults = chatbot.field.protocols["attractorcoemerge"].execute(chatbot.field) resonanceresults = chatbot.field.protocols["field_resonance"].execute(chatbot.field)

Show field coherence

print(f"Field coherence: {resonanceresults['fieldcoherence']:.2f}") ```

Meta-Recursive Improvement

```python

Perform self-improvement

improvementinfo = chatbot.metaimprove() print(f"Improvement strategy: {improvementinfo.get('laststrategy', 'Unknown')}") ```

Demonstration Examples

The repository includes several demonstration examples showcasing different aspects of context engineering:

  1. Basic Conversation: Simple prompt-response interactions (atomic layer)
  2. Context Retention: Remembering previous topics across exchanges (cellular layer)
  3. Field Operations: Attractor formation and resonance (field layer)
  4. Self-Repair: Handling inconsistencies and restoring field integrity (field layer)
  5. Meta-Recursive: Self-observation and continuous improvement (meta-recursive layer)

Documentation

For detailed documentation and tutorials, refer to the documentation directory. You'll find:

  • Conceptual Overviews: Deep dives into context engineering theory
  • API Documentation: Full reference for all classes and methods
  • Tutorials: Step-by-step guides for various applications
  • Examples: Complete code examples for different use cases

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

We welcome contributions from the community! Please see our contributing guidelines for details on how to get involved.

Citation

If you use this toolkit in your research, please cite it using the following BibTeX entry:

bibtex @misc{context_engineering_toolkit, author = {Your Name}, title = {Context Engineering Toolkit}, year = {2023}, publisher = {GitHub}, journal = {GitHub repository}, howpublished = {\url{https://github.com/oxbshw/context-engineering}}, }

Thank you for your interest in the Context Engineering Toolkit! We hope this resource helps you explore and develop advanced conversational AI systems.

Owner

  • Name: Sayed Allam
  • Login: oxbshw
  • Kind: user

Citation (CITATIONS.md)

# CITATIONS

This document provides conceptual anchors, research bridges, foundational references, and academic reserch that guide the Context-Engineering repository. These references support our approach to context as a continuous field with emergent properties, symbolic mechanisms, and cognitive tools.

## Core Conceptual Anchors

### [1. Emergent Symbolic Mechanisms in LLMs](https://openreview.net/forum?id=y1SnRPDWx4)

**Source:** Yang, Y., Campbell, D., Huang, K., Wang, M., Cohen, J., & Webb, T. (2025). "Emergent Symbolic Mechanisms Support Abstract Reasoning in Large Language Models." *Proceedings of the 42nd International Conference on Machine Learning*.

**Key Concepts:**
- **Three-Stage Symbolic Architecture**: LLMs implement reasoning through an emergent three-stage process:
  1. **Symbol Abstraction**: Heads in early layers convert input tokens to abstract variables based on relations between tokens
  2. **Symbolic Induction**: Heads in intermediate layers perform sequence induction over abstract variables
  3. **Retrieval**: Heads in later layers predict next tokens by retrieving values associated with predicted abstract variables

**Connections to Context-Engineering:**
- Directly supports our `08_neural_fields_foundations.md` and `12_symbolic_mechanisms.md` foundations
- Provides mechanistic understanding for `30_examples/09_emergence_lab/` implementations
- Validates our approach to treating context as continuous fields with emergent properties

**Socratic Questions:**
- How can we design context structures that explicitly leverage these three stages?
- Can we create tools to detect and measure the emergence of symbolic processing?
- How might we enhance retrieval mechanisms through better field-based context design?

---

### [2. Cognitive Tools for Language Models](https://www.arxiv.org/pdf/2506.12115)

**Source:** Brown Ebouky, Andrea Bartezzaghi, Mattia Rigotti (2025). "Eliciting Reasoning in Language Models with Cognitive Tools." arXiv preprint arXiv:2506.12115v1.

**Key Concepts:**
- **Cognitive Tools Framework**: Modular, predetermined cognitive operations executed sequentially
- **Tool-Based Approach**: Implements specific reasoning operations as tools the LLM can call
- **Key Cognitive Operations**:
  - **Recall Related**: Retrieving relevant knowledge to guide reasoning
  - **Examine Answer**: Self-reflection on reasoning and answers
  - **Backtracking**: Exploring alternative reasoning paths when blocked

**Connections to Context-Engineering:**
- Direct implementation in our `cognitive-tools/` directory
- Supports our approach in `05_cognitive_tools.md` foundations
- Provides framework for `20_templates/prompt_program_template.py`
- Enriches implementation of `30_examples/02_multi_agent_orchestrator/`

**Socratic Questions:**
- How can cognitive tools interact with field-based context representations?
- Can we build hybrid systems that combine cognitive tools with neural field approaches?
- How might we measure the impact of cognitive tools on context efficiency and effectiveness?

---

### 3. Neural Field Theory & Symbolic Residue

**Source:** Context Engineering Contributors (2024). "Neural Fields for Context Engineering" and emergent research across cited papers.

**Key Concepts:**
- **Context as Field**: Treating context as continuous semantic landscape rather than discrete tokens
- **Resonance Patterns**: How information patterns interact and reinforce each other
- **Attractor Dynamics**: Stable patterns that organize the field and guide information flow
- **Symbolic Residue**: Fragments of meaning that persist and influence the field

**Connections to Context-Engineering:**
- Core theoretical foundation for `08_neural_fields_foundations.md` through `11_emergence_and_attractor_dynamics.md`
- Implementation in `60_protocols/shells/` and `70_agents/` directories
- Measurement tools in `20_templates/resonance_measurement.py` and related templates

**Socratic Questions:**
- How can we better measure and visualize field dynamics in context systems?
- What are the most effective metrics for detecting emergence and resonance?
- How can boundary operations be optimized for different types of context?

---

## Parallel Research Bridges

### Symbol Processing & Abstract Reasoning

| Research Finding | Context-Engineering Implementation |
|-----------------|-----------------------------------|
| Symbol abstraction heads identify relationships between tokens | `12_symbolic_mechanisms.md`, `20_templates/symbolic_residue_tracker.py` |
| Symbolic induction heads perform sequence induction over abstract variables | `09_persistence_and_resonance.md`, `10_field_orchestration.md` |
| Retrieval heads predict tokens by retrieving values from abstract variables | `04_rag_recipes.ipynb`, `30_examples/04_rag_minimal/` |
| Invariance: Consistent representations despite variable instantiations | `40_reference/symbolic_residue_types.md` |
| Indirection: Variables referring to content stored elsewhere | `60_protocols/shells/recursive.memory.attractor.shell` |

### Cognitive Operations & Tools

| Research Finding | Context-Engineering Implementation |
|-----------------|-----------------------------------|
| Structured reasoning operations improve problem-solving | `cognitive-tools/cognitive-templates/reasoning.md` |
| Recall related knowledge guides reasoning | `cognitive-tools/cognitive-programs/basic-programs.md` |
| Examining answers through self-reflection improves accuracy | `cognitive-tools/cognitive-templates/verification.md` |
| Backtracking prevents getting stuck in unproductive paths | `cognitive-tools/cognitive-programs/advanced-programs.md` |
| Tool-based approach provides modular reasoning capabilities | `cognitive-tools/integration/` directory |

### Neural Field Dynamics

| Research Finding | Context-Engineering Implementation |
|-----------------|-----------------------------------|
| Context as continuous semantic landscape | `08_neural_fields_foundations.md` |
| Resonance between information patterns creates coherence | `09_persistence_and_resonance.md`, `20_templates/resonance_measurement.py` |
| Attractor dynamics organize field and guide information flow | `11_emergence_and_attractor_dynamics.md`, `70_agents/03_attractor_modulator/` |
| Boundary dynamics control information flow and field evolution | `40_reference/boundary_operations.md`, `70_agents/04_boundary_adapter/` |
| Symbolic residue enables subtle influences and pattern continuity | `20_templates/symbolic_residue_tracker.py`, `70_agents/01_residue_scanner/` |

---

## Visual Conceptual Bridges

### Emergent Symbolic Architecture

```
                        ks    Output
                        ↑
                        A
Retrieval              ↑ 
Heads           A   B   A
                ↑   ↑   ↑
                        
Symbolic        A   B   A   A   B   A   A   B
Induction       ↑   ↑   ↑   ↑   ↑   ↑   ↑   ↑
Heads                   
                        
Symbol     A       B       A       A       B       A       A       B
Abstraction ↑       ↑       ↑       ↑       ↑       ↑       ↑       ↑
Heads    iac     ilege    iac    ptest     yi     ptest    ks      ixe   Input
```
*Figure adapted from Yang et al. (2025)*

This three-stage architecture demonstrates how:
1. Symbol abstraction heads convert tokens to abstract variables based on relations
2. Symbolic induction heads perform pattern recognition over these variables
3. Retrieval heads produce outputs based on the predicted abstract variable

### Cognitive Tools Framework

```
                                        Tool Execution
                                           LLM
LLM                                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”   give answer              β”‚         β”‚
β”‚         β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Ί answer      β”‚         β”‚
question ──         β”‚                  β”‚         β”‚
          β”‚         β”‚  tool calling    β”‚         β”‚
          β”‚         β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Ίβ”Œβ”€β”΄β”€β”       β”‚
          β”‚    β”Œβ”€β”€β”€β”€β”˜                β”‚   β”‚       β”‚
          β”‚    β”‚                     β”‚   β”‚       β”‚
          β””β”€β”€β”€β”€β”˜                     β””β”€β”€β”€β”˜       β”‚
        Cognitive                   cognitive    β”‚
         Tools                       tools       β”‚
         Prompt                                  β”‚
                                    inputs ─────►└─────────► output
                                                 
                                                 
                                               Tool
                                              Prompt
```
*Figure adapted from Ebouky et al. (2025)*

This framework shows how:
1. LLMs can leverage cognitive tools through a structured prompting mechanism
2. Tools encapsulate specific reasoning operations executed by the LLM itself
3. The approach enables modular, sequential execution of cognitive operations

### Neural Field and Attractor Dynamics

```
                         Field Boundary
                     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                     β”‚                   β”‚
                     β”‚    β”Œβ”€β”€β”€β”€β”€β”        β”‚
                     β”‚    β”‚     β”‚        β”‚
                     β”‚    β”‚  A  β”‚        β”‚
                     β”‚    β”‚     β”‚        β”‚
                     β”‚    β””β”€β”€β”€β”€β”€β”˜        β”‚
                     β”‚        ↑          β”‚
                     β”‚        β”‚          β”‚
                     β”‚        β”‚          β”‚
  Information ───────┼───► β”Œβ”€β”€β”€β”€β”€β”       β”‚
     Input           β”‚     β”‚     β”‚       β”‚
                     β”‚     β”‚  B  β”‚       β”‚
                     β”‚     β”‚     β”‚       β”‚
                     β”‚     β””β”€β”€β”€β”€β”€β”˜       β”‚
                     β”‚                   β”‚
                     β”‚                   β”‚
                     β”‚                   β”‚
                     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                      Information Field with
                         Attractors
```

This conceptual visualization shows:
1. Context as a continuous field with permeable boundaries
2. Attractors (A, B) that organize information and influence surrounding patterns
3. Information flow guided by attractor dynamics and field properties

---

## Implementation & Measurement Bridges

### Symbolic Mechanism Detection

To detect and leverage symbolic mechanisms in context engineering:

1. **Symbol Abstraction Analysis**:
   ```python
   def detect_symbol_abstraction(context, model):
       # Analyze attention patterns in early layers
       attention_patterns = extract_attention_patterns(model, context, layers='early')
       # Detect relational patterns between tokens
       relation_matrices = compute_relation_matrices(attention_patterns)
       # Identify potential abstract variables
       abstract_variables = extract_abstract_variables(relation_matrices)
       return abstract_variables
   ```

2. **Symbolic Induction Measurement**:
   ```python
   def measure_symbolic_induction(context, model):
       # Extract intermediate layer representations
       intermediate_reps = extract_representations(model, context, layers='middle')
       # Analyze pattern recognition over abstract variables
       pattern_scores = analyze_sequential_patterns(intermediate_reps)
       # Quantify induction strength
       induction_strength = compute_induction_strength(pattern_scores)
       return induction_strength
   ```

3. **Retrieval Mechanism Evaluation**:
   ```python
   def evaluate_retrieval_mechanisms(context, model):
       # Extract late layer representations
       late_reps = extract_representations(model, context, layers='late')
       # Analyze retrieval patterns
       retrieval_patterns = analyze_retrieval_patterns(late_reps)
       # Measure retrieval accuracy
       retrieval_accuracy = compute_retrieval_accuracy(retrieval_patterns)
       return retrieval_accuracy
   ```

### Resonance and Field Metrics

```python
def measure_field_resonance(context):
    # Extract semantic patterns
    patterns = extract_semantic_patterns(context)
    # Compute pattern similarity matrix
    similarity_matrix = compute_pattern_similarity(patterns)
    # Identify resonant patterns
    resonant_patterns = identify_resonant_patterns(similarity_matrix)
    # Calculate overall resonance score
    resonance_score = calculate_resonance_score(resonant_patterns)
    return resonance_score
```

```python
def detect_emergence(context_history):
    # Track field state over time
    field_states = extract_field_states(context_history)
    # Identify novel patterns
    novel_patterns = identify_novel_patterns(field_states)
    # Measure pattern stability and influence
    stability = measure_pattern_stability(novel_patterns, field_states)
    influence = measure_pattern_influence(novel_patterns, field_states)
    # Calculate emergence score
    emergence_score = calculate_emergence_score(novel_patterns, stability, influence)
    return emergence_score
```

---

## Future Research Directions

Based on the research reviewed, several promising research directions emerge:

1. **Hybrid Symbolic-Neural Approaches**:
   - Develop context engineering techniques that explicitly leverage emergent symbolic mechanisms
   - Create tools to measure and enhance symbolic processing in LLMs
   - Build hybrid systems combining neural field approaches with explicit symbolic operations

2. **Advanced Field Dynamics**:
   - Explore more sophisticated boundary operations for context fields
   - Develop better metrics for measuring resonance, persistence, and emergence
   - Create visualization tools for field dynamics and attractor formation

3. **Cognitive Tool Integration**:
   - Integrate cognitive tools with field-based context representations
   - Develop adaptive systems that select appropriate cognitive tools based on field state
   - Create evaluation frameworks for measuring the impact of cognitive tools on reasoning

4. **Symbolic Residue Engineering**:
   - Develop techniques for detecting and leveraging symbolic residue
   - Create systems for tracking residue integration and influence
   - Build tools for measuring residue persistence and impact

5. **Meta-Learning and Self-Reflection**:
   - Explore how self-reflection can enhance context management
   - Develop systems that learn to optimize their own context structures
   - Create frameworks for measuring and enhancing meta-cognitive abilities

---

## Citation Format

```bibtex
@inproceedings{yang2025emergent,
  title={Emergent Symbolic Mechanisms Support Abstract Reasoning in Large Language Models},
  author={Yang, Yukang and Campbell, Declan and Huang, Kaixuan and Wang, Mengdi and Cohen, Jonathan and Webb, Taylor},
  booktitle={Proceedings of the 42nd International Conference on Machine Learning},
  year={2025}
}

@article{ebouky2025eliciting,
  title={Eliciting Reasoning in Language Models with Cognitive Tools},
  author={Ebouky, Brown and Bartezzaghi, Andrea and Rigotti, Mattia},
  journal={arXiv preprint arXiv:2506.12115v1},
  year={2025}
}

@misc{contextengineering2024,
  title={Context-Engineering: From Atoms to Neural Fields},
  author={Context Engineering Contributors},
  year={2024},
  howpublished={\url{https://github.com/context-engineering/context-engineering}}
}
```

GitHub Events

Total
  • Watch event: 16
  • Push event: 30
  • Fork event: 1
  • Create event: 6
Last Year
  • Watch event: 16
  • Push event: 30
  • Fork event: 1
  • Create event: 6

Dependencies

docker/Dockerfile docker
docker/docker-compose.yml docker
requirements.txt pypi
  • flake8 *
  • jupyter *
  • llama-index *
  • pytest *
  • pyyaml *
  • requests *
  • streamlit *
  • transformers *