PEEK caches reusable orientation knowledge about long and recurring external contexts (e.g., document corpora and code repositories) that LLM agents operate on, representing this knowledge as a context map. Inspired by computer-system caches and database indexes, PEEK treats the context map as a small, prompt-resident cache of a much larger external context. This helps the agent understand, navigate, and act on that context more efficiently and reliably.

PEEK manages the map through a modular cache policy. It is agent- and model-agnostic, as well as unsupervised: it makes no assumptions about the agent’s architecture or scaffolding, and works with both open- and closed-source LMs, including most frontier models. PEEK uses inference-time signals (without requiring ground-truth labels) and returns an updated map that can be prepended to the next call.

pip install peek-ai            # core (tiktoken only)
pip install peek-ai[openai]    # + OpenAI / OpenAI-compatible endpoints
pip install peek-ai[anthropic] # + Anthropic
pip install peek-ai[gemini]    # + Google Gemini
pip install peek-ai[all]       # all of the above

A minimal loop around your own agent looks like this:

from peek import CachePolicy
from peek.llm.openai_client import OpenAIClient

client = OpenAIClient(model="gpt-5-mini-2025-08-07")
policy = CachePolicy(client=client, token_budget=1024, evolve_steps=10)

for question in stream_of_questions:
    system_prompt = f"{base_instructions}\n\nContext Map:\n{policy.current_map_text}"
    trajectory = my_agent.run(system_prompt, question, long_external_context)
    policy.update(trajectory=trajectory, question=question)

policy.save("maps/my-corpus.peek.json")

Any object satisfying peek.LMClient works as the Distiller/Cartographer backbone — implement completion(messages) and last_usage() and you can plug in vLLM, Together, Ollama, or a local stub. Three reference clients ship with the package:

• PEEK paper — arXiv:2605.19932
• Blog post — Give Your Agent an Orientation Cache

We welcome contributions! A simple path to contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m "Add amazing feature")
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Paper Authors: See the arXiv paper for author contact information.
• Interest and Feedback: Please fill out the form.
• Issues: Please open an issue on GitHub.

If you use PEEK in your research, please cite:

@misc{gu2026peekcontextmaporientation,
      title={PEEK: Context Map as an Orientation Cache for Long-Context LLM Agents}, 
      author={Zhuohan Gu and Qizheng Zhang and Omar Khattab and Samuel Madden},
      year={2026},
      eprint={2605.19932},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2605.19932}, 
}