0xtotem/peek-dspy

peek-dspy is a Python library that ports a research technique called PEEK into the DSPy AI programming framework. PEEK stands for a self-updating context map, which is a block of text that lives inside an AI agent's prompt and gets smarter over time. Instead of starting fresh on every question, the agent carries a growing summary of structural knowledge about whatever it is working on, such as a codebase or a document collection. The core idea is that when you ask an AI agent many questions about the same external context, a lot of repeated orientation work gets redone on each call. PEEK separates that orientation work from question-specific reasoning, saves the useful parts, and trims what is no longer needed. This makes repeated interactions more efficient because the agent does not have to re-learn the structure of the thing it is looking at each time. Under the hood, three components handle the map updates after each call. A Distiller figures out which parts of the agent's reasoning were about understanding the context versus answering the specific question. A Cartographer then produces structured edits to the map, adding new facts, removing stale ones, or replacing outdated sections. An Evictor keeps the map within a token budget by dropping sections judged to be low-value. To use it, you wrap any existing DSPy module with the PEEK wrapper, set a token budget and an optional freeze point, and then run your questions through it as usual. The map accumulates automatically. You can inspect the current map at any time through a provided property on the policy object. Setup requires Python with Poetry, and an Anthropic API key since the examples use a Claude model. The library is a direct port of the upstream PEEK implementation described in an academic paper linked in the README.