{"id":51096965,"url":"https://github.com/keli-wen/context-kit","last_synced_at":"2026-06-24T07:02:50.447Z","repository":{"id":354783657,"uuid":"1137285428","full_name":"keli-wen/context-kit","owner":"keli-wen","description":"A minimal toolkit for Context Engineering — Select, Compress, and   Persist context with pure functions.","archived":false,"fork":false,"pushed_at":"2026-01-20T09:28:25.000Z","size":546,"stargazers_count":44,"open_issues_count":0,"forks_count":5,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-30T03:41:29.530Z","etag":null,"topics":["agent","ai","context-engineering","educational","llm","python","toolkit"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/keli-wen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-19T07:04:31.000Z","updated_at":"2026-04-08T08:10:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/keli-wen/context-kit","commit_stats":null,"previous_names":["keli-wen/context-kit"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/keli-wen/context-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keli-wen%2Fcontext-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keli-wen%2Fcontext-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keli-wen%2Fcontext-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keli-wen%2Fcontext-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/keli-wen","download_url":"https://codeload.github.com/keli-wen/context-kit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keli-wen%2Fcontext-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34720924,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","context-engineering","educational","llm","python","toolkit"],"created_at":"2026-06-24T07:02:49.686Z","updated_at":"2026-06-24T07:02:50.434Z","avatar_url":"https://github.com/keli-wen.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# context-kit\n\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n\nEnglish | [中文](README_ZH.md)\n\n\u003e **Do the simplest thing that works.**\n\nA minimal, framework-agnostic toolkit for Context Engineering. Not another agent framework — just pure functions and a Context dataclass.\n\n**Built for learning** — understand Context Engineering concepts through readable, minimal code.\n\n## 💡 Motivation\n\n\u003e \"Most AI Agent failures are not failures of model capability, but failures of Context Engineering.\"\n\nAs LLMs become more powerful, the bottleneck shifts from model intelligence to **how we manage context**. Research on [context rot](https://research.trychroma.com/context-rot) shows that as context windows fill up, the model's ability to extract accurate information degrades — across all models.\n\n**Context Engineering** is the discipline of dynamically assembling the optimal context for each reasoning step. It's not just \"advanced prompting\" — it's treating context as a **finite resource with diminishing marginal returns**, like memory in an operating system.\n\nThe four pillars of Context Engineering are:\n\n| Pillar | Purpose | context-kit Module |\n|--------|---------|-------------------|\n| **Select** | JIT retrieval — pull information on-demand | `select` |\n| **Write** | Persist information outside the context window | `memory` |\n| **Compress** | Reduce context size while preserving signal | `Context.compress_*` |\n| **Isolate** | Distribute context across sub-agents | Framework-level |\n\ncontext-kit implements the first three pillars as pure functions, letting you compose them with any agent framework.\n\n\u003e [!TIP]\n\u003e 📚 **Deep Dive**: For a comprehensive guide on Context Engineering patterns, see [One Poem Suffices: Context Engineering](https://github.com/keli-wen/One-Poem-Suffices/blob/master/blogs/Context%20Engineering/README.md) and [One Poem Suffices: Just-in-Time Context](https://github.com/keli-wen/One-Poem-Suffices/blob/master/blogs/Just-in-Time%20Context/README.md).\n\n## 📦 Why context-kit?\n\nContext is a limited resource with diminishing returns. As context windows fill up, model performance degrades. context-kit provides the building blocks to manage context effectively:\n\n| Module | Purpose | Key Operations |\n|--------|---------|----------------|\n| **Context** | Core dataclass | `compress_by_rule`, `compress_by_model`, format conversion |\n| **Select** | JIT Context Retrieval | `list_dir`, `grep`, `read_file` |\n| **Memory** | Context Persistence | `view`, `create`, `str_replace`, `insert`, `delete` |\n| **Tools** | Agent Integration | `get_memory_tools`, `get_select_tools` |\n\n## 🚀 Installation\n\n### With uv (Recommended)\n\n```bash\ngit clone https://github.com/keli-wen/context-kit.git\ncd context-kit\nuv sync                              # Install dependencies\nuv run python examples/basic/00_minimal.py  # Run example\n```\n\n### Without uv\n\nIf you don't have [uv](https://docs.astral.sh/uv/) installed:\n\n```bash\n# Install uv (recommended)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Or use pip to build from source\ngit clone https://github.com/keli-wen/context-kit.git\ncd context-kit\npip install -e .                     # Install in editable mode\npip install -e \".[example]\"          # With example dependencies\npip install -e \".[dev]\"              # With dev dependencies\n```\n\n## ⚡ Quick Example\n\n```python\nfrom context_kit import Context, memory, select\n\n# 1. Create context from messages\nmessages = [\n    {\"role\": \"system\", \"content\": \"You are helpful.\"},\n    {\"role\": \"user\", \"content\": \"Hello\"},\n    {\"role\": \"assistant\", \"content\": \"Hi there!\"},\n]\nctx = Context.from_openai(messages)\nprint(f\"Messages: {len(ctx)}, Tokens: ~{ctx.estimate_tokens()}\")\n\n# 2. Compress by clearing old tool results (Claude Context Editing API style)\nctx = ctx.compress_by_rule(keep_tool_uses=3)\n\n# 3. Export to different formats\nopenai_msgs = ctx.to_openai()\nanthropic_msgs, system = ctx.to_anthropic()\ngoogle_contents, system = ctx.to_google()\n```\n\n## 📚 Core Concepts\n\n### Context: The Core Dataclass\n\nThe `Context` class manages conversation history with compression and format conversion:\n\n```python\nfrom context_kit import Context\n\n# Create from various formats\nctx = Context.from_openai(messages)\nctx = Context.from_anthropic(messages, system=\"You are helpful.\")\nctx = Context.from_google(contents, system=\"You are helpful.\")\n\n# Compression operations\nctx = ctx.compress_by_rule(keep_tool_uses=3)  # Clear old tool results\nctx = await ctx.compress_by_model(llm, keep_recent=3)  # LLM summarization\n\n# Export to any format\nopenai_msgs = ctx.to_openai()\nanthropic_msgs, system = ctx.to_anthropic()\n```\n\n\u003e [!NOTE]\n\u003e **Thinking/Reasoning Format Support**: The `Message` class supports thinking blocks across providers (Anthropic `type: \"thinking\"`, OpenAI/DeepSeek `reasoning_content`, Google `thought: true`). This feature is experimental — provider APIs may change. Please [file an issue](https://github.com/keli-wen/context-kit/issues) if you encounter compatibility problems.\n\n### compress_by_rule: Tool \u0026 Thinking Clearing\n\nAligned with [Claude Context Editing API](https://docs.anthropic.com/en/docs/build-with-claude/context-management). Clears old tool results and thinking blocks to reduce context size:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/context_editing_mix_strategy.png\" width=\"700\" alt=\"Context Editing Mixed Strategy\"\u003e\n\u003c/p\u003e\n\n```python\n# Clear old tool results, keep only last 3\nctx = ctx.compress_by_rule(keep_tool_uses=3)\n\n# Exclude specific tools from clearing\nctx = ctx.compress_by_rule(keep_tool_uses=3, exclude_tools=[\"read_file\"])\n\n# Clear thinking blocks too\nctx = ctx.compress_by_rule(\n    keep_tool_uses=3,\n    clear_thinking=True,\n    keep_thinking_turns=1,\n)\n\n# Archive cleared content to memory (with retrieval guidance)\nctx = ctx.compress_by_rule(\n    keep_tool_uses=3,\n    memory_path=\"./agent_data\",  # Same path as get_memory_tools()\n)\n# Placeholder: \"[Tool result cleared. Use memory_read('/memories/tool_001_grep.md') to retrieve.]\"\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e📊 Example Output\u003c/summary\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/compress_by_rule_example.png\" width=\"500\" alt=\"compress_by_rule Demo\"\u003e\n\u003c/p\u003e\n\n\u003c/details\u003e\n\n### compress_by_model: LLM Summarization\n\nUses an LLM to summarize older conversation turns:\n\n```python\nfrom context_kit.llm import from_litellm\n\nllm = from_litellm(model=\"gpt-4o-mini\")\nctx = await ctx.compress_by_model(\n    llm,\n    instruction=\"Preserve: key decisions, unresolved issues. Discard: exploratory attempts.\",\n    keep_recent=3,\n)\n```\n\n### Select: JIT Context Retrieval\n\nProgressive Disclosure pattern — start with an overview, narrow down, then load on demand:\n\n```python\nfrom context_kit import select\n\n# Step 1: Understand the map (low token cost)\nentries = select.list_dir(\"./src\", max_depth=2)\n\n# Step 2: Narrow down\nmatches = select.grep(r\"def \\w+\", \"./src\", file_pattern=\"*.py\")\n\n# Step 3: Load on demand\ncontent = select.read_file(\"./src/auth.py\", start_line=40, end_line=60)\n```\n\n### Memory: Context Persistence\n\nPersist information outside the context window ([Claude Memory Tool interface](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool)):\n\n```python\nfrom context_kit import memory\n\nmemory.init(path=\"./agent_data\")\n\n# CRUD operations\nmemory.create(\"/memories/notes.md\", \"# Analysis\\n\\nKey findings...\")\ncontent = memory.view(\"/memories/notes.md\")\nmemory.str_replace(\"/memories/notes.md\", \"old\", \"new\")\nmemory.insert(\"/memories/notes.md\", 3, \"- New item\")\nmemory.delete(\"/memories/notes.md\")\n```\n\n### Tools: Agent Integration\n\nExport tool definitions for agent frameworks:\n\n```python\nfrom context_kit import tools\n\n# Get all tools with shared memory_path\nall_tools = tools.get_all_tools(\n    memory_path=\"./agent_data\",\n    select_path=\"./src\",\n)\n\n# Or get specific tool sets\nmemory_tools = tools.get_memory_tools(memory_path=\"./agent_data\")\nselect_tools = tools.get_select_tools(select_path=\"./src\")\n```\n\n### LLM Adapters\n\nUnified interface for different LLM providers:\n\n```python\nfrom context_kit.llm import from_openai, from_anthropic, from_litellm\n\n# OpenAI\nllm = from_openai(model=\"gpt-4o-mini\")\n\n# Anthropic\nllm = from_anthropic(model=\"claude-3-haiku-20240307\")\n\n# LiteLLM (any provider)\nllm = from_litellm(model=\"gpt-4o-mini\")\n```\n\n## 🔗 Integration Example\n\n```python\nfrom camel.agents import ChatAgent\nfrom camel.toolkits import FunctionTool\nfrom context_kit import Context, tools as context_kit_tools\n\n# Setup agent with context-kit tools\nctx_tools = [FunctionTool(f) for f in context_kit_tools.get_all_tools(\n    memory_path=\"./agent_data\",\n    select_path=\"./src\",\n)]\n\nagent = ChatAgent(\n    system_message=\"You are a helpful assistant.\",\n    tools=ctx_tools,\n)\n\n# After conversation, compress context\nhistory = agent.memory.get_context()\nctx = Context.from_openai(history)\ncompressed = ctx.compress_by_rule(keep_tool_uses=3, memory_path=\"./agent_data\")\n```\n\n## 📂 Examples\n\nSee `examples/` directory:\n\n| Example | Description |\n|---------|-------------|\n| `basic/00_minimal.py` | Quick start |\n| `basic/01_select_tools.py` | JIT Context Retrieval |\n| `basic/02_memory.py` | Memory persistence |\n| `basic/03_compress_rules.py` | Tool \u0026 thinking clearing |\n| `basic/04_compress_model.py` | LLM summarization |\n| `integrations/camel/` | CAMEL framework integration |\n| `integrations/adk/` | Google ADK integration |\n\n## 🎯 Design Philosophy\n\n| Principle | Description |\n|-----------|-------------|\n| **Minimal** | Pure functions, lightweight core |\n| **Composable** | Each module independent, combine as needed |\n| **Framework-agnostic** | Works with any agent framework |\n| **Educational** | Code as documentation for Context Engineering |\n\n### Design Inspiration\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/prompt_engineering_vs_context_engineering.webp\" width=\"700\" alt=\"Prompt Engineering vs Context Engineering\"\u003e\n  \u003cbr\u003e\n  \u003cem\u003eImage source: \u003ca href=\"https://www.anthropic.com/research/building-effective-agents\"\u003eAnthropic - Building Effective Agents\u003c/a\u003e\u003c/em\u003e\n\u003c/p\u003e\n\nContext engineering treats context as structured blocks (docs, tools, memory, history) rather than a single prompt string. Inspired by Google ADK's \"[context as a compiled view](https://developers.googleblog.com/en/agent-development-kit-context-aware-multi-agent/)\" thesis:\n\n\u003e \"Context is a compiled view over a richer stateful system... context engineering stops being prompt gymnastics and starts looking like systems engineering.\"\n\ncontext-kit provides the primitives for this compilation: **Select** retrieves relevant blocks, **Memory** persists state, and **Compress** optimizes the final view.\n\n### What context-kit is NOT\n\n- Not an agent framework (use CAMEL, LangGraph, etc.)\n- Not an LLM API wrapper (use LiteLLM, OpenAI SDK, etc.)\n- Not a proxy server\n\n### Isolation Pattern\n\nFor sub-agent isolation (preventing context pollution), compose existing primitives at the framework level:\n\n```python\n# Framework layer (not context-kit)\nsub_ctx = Context.from_dict([{\"role\": \"system\", \"content\": system}])\nsub_ctx = await run_sub_agent(sub_ctx, task)\nsummary = await sub_ctx.compress_by_model(llm, keep_recent=0)\nparent_ctx = parent_ctx.add_message(\"assistant\", summary_text)\n```\n\n## 🗺️ Roadmap\n\n### Completed\n\n- [x] Context dataclass with format conversion (OpenAI, Anthropic, Google)\n- [x] compress_by_rule: Clear tool results \u0026 thinking blocks (Claude API aligned)\n- [x] compress_by_model: LLM-based summarization\n- [x] Memory module (Claude Memory Tool interface)\n- [x] Select module (list_dir, grep, read_file)\n- [x] LLM adapters (OpenAI, Anthropic, LiteLLM)\n- [x] Tools export (get_memory_tools, get_select_tools)\n- [x] Add `Context.from_dict()` convenience for thinking blocks\n- [x] Support thinking/reasoning formats: Anthropic (`type: \"thinking\"`), OpenAI/DeepSeek (`reasoning_content`), Google (`thought: true`)\n\n### Planned\n\n- [ ] Add more integration examples (LangGraph, AutoGen)\n- [ ] MCP server format export\n- [ ] Streaming support for compress_by_model\n- [ ] Semantic search with vector index for memory module (optional dependency)\n\n## 🙏 References\n\n- [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) - Anthropic\n- [Architecting Context-Aware Multi-Agent Framework](https://developers.googleblog.com/en/agent-development-kit-context-aware-multi-agent/) - Google ADK\n- [Context Rot Research](https://research.trychroma.com/context-rot) - Chroma\n- [Claude Context Management API](https://docs.anthropic.com/en/docs/build-with-claude/context-management) - Anthropic\n- [Claude Memory Tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool) - Anthropic\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeli-wen%2Fcontext-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeli-wen%2Fcontext-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeli-wen%2Fcontext-kit/lists"}