Skip to content

ctxkeeper 1.0.0

Latest
Latest

Choose a tag to compare

View all tags
@steveseguin steveseguin released this 15 Oct 01:51
ctxkeeper-v1.0.0
29feb5d

ctxkeeper lets an AI agent keep working on one long task after its conversation has grown far past what the model can read at once, without forgetting what it was told.

It is a small proxy between your agent (or chat app) and any OpenAI-compatible model server: vLLM, llama.cpp, SGLang and others. Your agent keeps sending its whole history; the model is shown a short, current view of it: the opening instructions, notes it keeps up to date (standing rules, current facts, open questions) and the newest turns. Everything older is archived word for word on disk and the model gets a recall tool to search it. Python 3.10 or newer, standard library only, public domain.

Install (pick one)

R=https://github.com/steveseguin/b70-optimization-lab/releases/download/ctxkeeper-v1.0.0
pip install $R/ctxkeeper-1.0.0-py3-none-any.whl          # gives the `ctxkeeper` command
docker build -t ctxkeeper $R/ctxkeeper-1.0.0.tar.gz        # image from the 80 KB source archive
curl -LO $R/ctxkeeper.py && curl -LO $R/notesdelta.py     # or just the two files

Run

ctxkeeper --upstream http://127.0.0.1:8000 --recipe agent   # your server, without /v1

Point your agent at http://127.0.0.1:18200/v1. To see it work: curl -LO $R/long_chat.py && python3 long_chat.py.

Measured

Qwen3.8-27B FP8 on two Intel Arc Pro B70 cards, 32K-token view:

Test With ctxkeeper Without it
Fix 40 real bugs one ticket at a time, following three house rules, then 7 questions about the earliest fixes 40/40 fixed, 40/40 following every rule, 7/7, in 16 min Latest 32K only: 22-35 of 40 following the rules, 0/7
The same task through a separate agent program 40/40/7 in 33 min, 2.9M prompt tokens Whole history in a 262K window: same score, 55 min, 29.9M
228 questions over a million-token history 226/228 in 50 min 200K window: 166/228, 228 min
2M tokens with planted traps 351/382, 0 of 12 traps taken no window holds it

Release test (campaign 19)

Installed the way a user installs it and run as the README says (records: data/2026-10-14-context-campaign19/):

Check Result
The code-repair task through a separate agent program, --recipe qwen and nothing else 40/40 fixed, 40/40 following every rule, 7/7, 31 min
long_chat.py through the Docker image, 300K tokens (more than the server's own 262K window) 4/4, 4 min
The README's OpenAI SDK snippet plain reply, tool call and streaming
Another model and server: Gemma 4 26B (Q8) on llama.cpp, --recipe agent --budget 15360, 100K tokens 4/4, 4.5 min (one smoke-test run)

Files

File What it is SHA-256
ctxkeeper-1.0.0-py3-none-any.whl pip package 5d79c44f3e160e52466d311bc6793c5979e5bd9d7e46fcc49f47c9d21083aa45
ctxkeeper-1.0.0.tar.gz source archive: Docker build context, pip source, tests, demo, README 998fb0b983c9b56c14bcf01427d4f40ec3993026019d12b78e87b7cc6d7152e8
ctxkeeper.py the proxy 2db699ca21f2160ff6e121749b5f2c30c5408062012c687d15e7875e7159ffaf
notesdelta.py the notes checks it imports a80002585a8f628e9d4fce0ed389d84130b40d8b459b280fb97a14204cf30d0f
long_chat.py the demo 1b0e9b2e3d060a0e3e62f7a0205fb9172ead907fd5bd1a1fe57deab86cc21c69

SHA256SUMS holds the same list.

More

Limits: measured with one model family on one machine; the notes are written by the model and can be wrong (the originals stay searchable); no authentication and plain-text state, listening on 127.0.0.1 by default.

Assets 8
Loading