Connect your agent to ctxkeeper

Setup instructions and compatibility details for ctxkeeper 1.2.0.

Pi and OpenCode can use ctxkeeper with a local model server. Start the proxy, choose your model, then follow the client setup below. These instructions cover ctxkeeper 1.2.0.

Back to the compatibility overview

Save a conversation and return later

Keep both your client’s complete conversation history and ctxkeeper’s state directory. ctxkeeper saves archived turns, notes and notes history per conversation. It does not independently save every newest turn or final reply, and it cannot resume a chat from a session ID alone.

For long-term storage, choose a persistent folder you back up instead of relying on the default ~/.cache/ctxkeeper directory. For example:

ctxkeeper --recipe agent \
  --upstream http://127.0.0.1:8080 \
  --state-dir "$HOME/.local/share/ctxkeeper"

Use that same directory when restarting ctxkeeper, reopen the saved chat in your client, and resend its full history. If you use X-Ctx-Session, retain the same unique value for that conversation. Copy any existing state directory before changing its location. Keep the client’s history backups too.

There is no time-based expiry in ctxkeeper’s saved state, so the files can remain for months. Restart persistence is unit-tested; months-long retention is not a separate benchmark. The model must process the working view again if its server-side cache is gone.

Separate chats remain separate. The recall tool searches the current session’s archive. Version 1.2.0 has no global search across all chats, complete per-turn window snapshots, or one-click session restore.

What about saving the already-processed GPU state?

That is a separate model-server feature. Disk cache offloading can reuse precomputed state in compatible serving stacks, but ctxkeeper does not implement it and it has not been validated in our B70 setup. Long-term reuse would require a persistent cache index and retention policy, compatible model weights, tokenization, templates and runtime settings, and the same prompt prefix. Hybrid models also need their recurrent state.

A saved cache speeds up processing of a matching prefix; it does not let an oversized history fit the model’s active context limit. Text history remains the recoverable source if the cache is missing or incompatible.

Before connecting

First start your tool-capable model server, then run ctxkeeper using the installation commands. Use --recipe qwen for the tested Qwen/vLLM setup, or --recipe agent for other compatible models. Find the model ID with:

curl http://127.0.0.1:18200/v1/models

Replace every YOUR_MODEL_ID below with the exact ID the server returns. Merge these examples into existing configuration files. The large client history ceiling lets the agent retain old turns; ctxkeeper still sends a 32K working view. It does not ask you to allocate a ten-million-token model context.

Pi — configuration and launch command

Complete Before connecting, then add a provider in ~/.pi/agent/models.json:

{
  "providers": {
    "ctxkeeper": {
      "baseUrl": "http://127.0.0.1:18200/v1",
      "api": "openai-completions",
      "apiKey": "unused",
      "models": [{
        "id": "YOUR_MODEL_ID",
        "name": "Local model via ctxkeeper",
        "input": ["text"],
        "contextWindow": 10000000,
        "maxTokens": 4096
      }]
    }
  }
}

In ~/.pi/agent/settings.json, disable automatic compaction:

{
  "compaction": { "enabled": false }
}

pi --provider ctxkeeper --model YOUR_MODEL_ID

Avoid manual /compact during that conversation too. Tested with Pi 1.2.0; its result and the notes failure are included in the agent comparison. See Pi’s custom endpoint guide and settings reference.

OpenCode 1.x — configuration and launch command

Complete Before connecting, then add this to your project’s opencode.json. This is the 1.x configuration format, tested with 1.19.0.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ctxkeeper/YOUR_MODEL_ID",
  "small_model": "ctxkeeper/YOUR_MODEL_ID",
  "provider": {
    "ctxkeeper": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ctxkeeper",
      "options": {
        "baseURL": "http://127.0.0.1:18200/v1",
        "apiKey": "unused"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "Local model via ctxkeeper",
          "tool_call": true,
          "limit": { "context": 10000000, "output": 4096 }
        }
      }
    }
  },
  "compaction": { "auto": false, "prune": false }
}

opencode --model ctxkeeper/YOUR_MODEL_ID

Select @ai-sdk/openai-compatible so requests use Chat Completions. The OpenAI provider can use Responses, which ctxkeeper passes through without managing context. See OpenCode’s provider guide and configuration reference. Check the format before adapting this to a new major version.

OpenAI SDK and other Chat Completions clients

Use base URL http://127.0.0.1:18200/v1, model YOUR_MODEL_ID, and the placeholder API key unused if your client requires a key. Call chat.completions.create, keep the full message list, and request one reply at a time (n=1). The SDK example covers plain replies, tool calls and streaming. Streaming is accepted, but each answer arrives in one piece at the end.

For other clients, choose a custom OpenAI-compatible Chat Completions provider, set the same base URL, and disable history trimming and summarizing. Cline, Goose, mini-swe-agent and others were also tested below; the exact provider controls depend on the client version.

Codex — why a base URL is not enough yet

Current Codex custom providers use the Responses API. ctxkeeper 1.2.0 forwards that endpoint without making notes, cutting context or serving recall. Pointing Codex at port 18200 therefore does not enable these features.

A managed connection needs Responses support in ctxkeeper or a tested Responses-to-Chat-Completions adapter. Neither is included in this release. For a working local-model setup today, use the Pi or OpenCode configuration on this page. See the Codex configuration reference.

Claude Code — a protocol adapter is required

Claude Code’s custom gateway uses the Anthropic Messages format, which ctxkeeper 1.2.0 does not manage. Setting ANTHROPIC_BASE_URL to ctxkeeper alone will not add its memory features.

A possible integration would need a Messages-to-Chat-Completions adapter before ctxkeeper and an upstream gateway that authenticates with the model provider. That combination has not been tested here. Follow the Claude Code gateway compatibility guide when evaluating an adapter; tool calls, thinking and streaming must survive the conversion. The Claude web app is not a configurable Chat Completions client.

Grok and other hosted models — supply credentials upstream

Grok is a model you can use through the xAI API. Its Chat Completions endpoint uses the right protocol, but requires an API key. ctxkeeper 1.2.0 does not forward the client’s Authorization header or provide an upstream API-key setting.

The route to evaluate is Pi or OpenCode → ctxkeeper → a local gateway holding your xAI key → xAI. Configure that gateway to expose Chat Completions locally, point --upstream at it, and select its Grok model alias in the client. Keep the key in the gateway; apiKey: "unused" in the examples is only a client placeholder.

This hosted route is not tested or packaged here. A Grok website or app subscription is not the API connection described above.

Check the connection and keep conversations separate

curl http://127.0.0.1:18200/ctxkeeper/status

Check the status while using the client. Notes and cuts start once the conversation grows beyond the working budget; a short successful reply alone does not demonstrate memory management.

If your client supports custom headers, send a unique X-Ctx-Session value per conversation and keep it on every call, including after a restart. Otherwise ctxkeeper identifies conversations by their model and opening messages; identical openings can collide. If earlier messages disappear or change, it may treat the history as a new conversation.

For new instructions inside tool results, such as tickets or files, --recite-when '(?m)^TICKET \d+' repeats recorded rules after matching messages.