ctx-saver is a self-hosted MCP server for AI coding agents. It keeps large command output out of the chat context by storing the full text locally and returning a compact summary instead.
No cloud. No telemetry. No account. Local SQLite only.
A self-hosted MCP server (Go) that reduces AI context window usage by sandboxing large tool outputs and returning compact summaries instead of raw text.
星數
3
工具
—
可用率
—
The Problem
AI agents often need to inspect big outputs:
go test -race -v ./...
docker logs, journalctl, kubectl get pods -A
git log --all, git diff, grep -r, find
large JSON files, API responses, Jira exports, build logs
Sending all of that text into the model burns context fast. ctx-saver gives the agent the useful summary first, then lets it search or retrieve details only when needed.
How It Works
flowchart LR
A[AI agent] -->|calls MCP tool| B[ctx-saver]
B --> C{Output size}
C -->|small| D[Return output directly]
C -->|large| E[Store full output in local SQLite]
E --> F[Return compact summary + output_id]
F --> G[Search with ctx_search]
F --> H[Retrieve exact lines with ctx_get_full]
The main idea is simple: keep noisy output searchable, but do not spend the whole context window on it.
Quick Start
1. Install
Requires Go 1.26+.
go install github.com/ChonlakanSutthimatmongkhol/ctx-saver/cmd/ctx-saver@latest
Make sure your Go binary directory is in PATH:
export PATH="$PATH:$(go env GOPATH)/bin"
Or build from source:
git clone https://github.com/ChonlakanSutthimatmongkhol/ctx-saver.git
cd ctx-saver
make install
2. Connect Your AI Client
Claude Code
ctx-saver init claude
Codex CLI
ctx-saver init codex
ctx-saver init agents-md
Restart Codex CLI after installing hooks.
VS Code Copilot
ctx-saver setup copilot
ctx-saver doctor
The combined setup installs project MCP configuration and instructions plus
personal hooks ($COPILOT_HOME/hooks or ~/.copilot/hooks). Use
ctx-saver setup copilot --repo-hooks only when hooks should apply to every
collaborator. See
Copilot Enterprise Setup for
company/enterprise setup notes.
Daily Usage
Most users only need these tools:
Tool
Use it for
ctx_session_init
Start a session with project rules, recent activity, cached outputs, cached reference files (cached_files), and saved decisions. Pass task="..." to resume task-scoped handoffs.
ctx_execute
Run shell, Python, Go, or Node commands while storing large output safely.
ctx_read_file
Read large files without flooding the model context.
ctx_search
Search stored outputs using full-text search.
ctx_get_full
Retrieve a full output or exact line range when needed.
ctx_note
Save/list durable decisions, or use action="handoff" with task="..." to resume work across sessions.
Typical agent flow:
sequenceDiagram
participant User
participant Agent
participant Saver as ctx-saver
participant DB as Local SQLite
User->>Agent: "Run tests and inspect failures"
Agent->>Saver: ctx_execute("go test -race -v ./...")
Saver->>DB: Store full test output
Saver-->>Agent: Summary + output_id
Agent->>Saver: ctx_search("FAIL", output_id)
Saver-->>Agent: Relevant failing lines
Agent-->>User: Short diagnosis, not 800 lines of logs
What You Get Back
Large outputs return a compact summary instead of raw text:
ctx_stats counts raw and returned tokens locally with the o200k_base
tokenizer. No API call or API key is required. Legacy rows created before
v0.13.0 are reported as untokenized_outputs and excluded from exact savings.
Outputs larger than 2 MiB are stored immediately and tokenized in the
background; they may appear temporarily in untokenized_outputs. Scalar metric
fields remain present at zero when the selected scope has no matching data.
Command
Raw
Summary
Saving
go test -race -v ./...
39 KB
115 B
99.7%
git log --oneline -500
8.7 KB
155 B
98.2%
Jira JSON export
88 KB
320 B
99.6%
app.log with 2,000 lines
177 KB
1.5 KB
99.2%
git diff HEAD~5
22 KB
750 B
96.6%
Overall benchmark snapshot: 391 KB raw output reduced to 6.1 KB of summaries, about 98.4% smaller.
Run the benchmark locally:
scripts/benchmark.sh
Context-Window Health
ctx_stats measures context-window health, not tool-usage frequency.
missed_large_outputs is the primary signal: it counts above-threshold output
that passed through annotated native Shell/Read tools. Git write commands and
native reads of files edited in the same session are sanctioned and do not
lower adherence. adherence_score remains as an informational compatibility
metric.
Key Features
Smart Summaries
ctx_execute detects common output formats and summarizes them with structure:
Note hits come back in decision_matches with a snippet and a full_text_via
call that returns the whole note. Search finds notes; ctx_note reads them, so
a long handoff never floods a search response.
Compare Repeated Runs
After rerunning the same test or build command, compare only what changed:
The result is a unified diff with three context lines and add/remove counts.
Large diffs are truncated to a bounded head/tail view.
Managed Storage
Bodies larger than 4 KiB are compressed with zstd. FTS rows remain plaintext,
so search behavior is unchanged and compression savings apply only to the
full_output portion of the database. Set storage.max_db_size_mb to enable
LRU eviction; 0 keeps the database unlimited. Recent outputs and decisions
are preserved.
Freshness Checks
Retrieval tools include a freshness field so the agent knows whether cached data is still safe to use.
Level
Age
Agent behavior
fresh
under 1 hour
use as-is
aging
1-24 hours
use as-is, mention age when relevant
stale
1-7 days
warn and offer refresh
critical
over 7 days
ask before using for decisions
Secret Redaction
Command and file output is scrubbed of well-known secret patterns before it is
summarised, returned to the model, or written to SQLite. Matches are replaced with
[REDACTED:<rule>] and the rule names are reported in stats.redacted_rules.
Default rules cover private key blocks, AWS access keys, GitHub/GitLab/Slack tokens,
JWTs, Bearer tokens, and generic key=value secrets (e.g. password=…, api_key: …).
Redaction is on by default. You can add patterns or turn it off via the redaction
config block. SourceHash for file caching is still computed from the on-disk file, so
cache invalidation is unaffected.
Redaction applies to new output only — rows stored before upgrading are not
retroactively scrubbed. Use ctx_purge to clear them if needed.
Session Handoff
One feature usually spans several sessions. ctx_note action handoff records the
state a later session needs to resume, scoped to a task name:
{ "action": "handoff", "task": "health-score-detail",
"text": "Parser is green. Next: wire the UI and cover the empty state." }
The next session calls ctx_session_init(task="health-score-detail") and gets that
handoff back. A handoff gets a 6000-character budget, three times what an ordinary
note gets, because it summarises a whole session rather than one decision.
Every session writes a new handoff. Nothing is overwritten, so no detail is lost,
and the response still stays small: ctx_session_init injects the newest handoff for
the task in full and collapses older ones to a stub marked superseded. Anything
shortened carries truncated, full_chars, and full_text_via naming the call that
returns the rest.
If you have forgotten the task name, call ctx_session_init with no task. Its
other_tasks field lists every task holding handoffs, with a count and the age
of the newest, so an empty recent_decisions is never a dead end.
To read a shortened entry, run the call in its full_text_via field verbatim:
A decision_id lookup returns that one note whole. It ignores every other filter and
is exempt from the response budget, so it never comes back truncated.
Budgets count Unicode characters, not bytes, so Thai and Japanese notes get the same
room as English ones. All of them are configurable; see Configuration below.
Cached Reference Files
ctx_session_init returns a cached_files list of previously read files with a short
SHA, freshness, and a changed_on_disk flag (the file is re-hashed at init). The agent
can reuse those via ctx_search / ctx_get_full from turn 1 instead of re-reading; when
changed_on_disk=true, it re-reads with ctx_read_file first.
Hooks
Host
MCP
Hooks
Session restoration
Claude Code
Yes
Yes
SessionStart context injection
Codex CLI
Yes
Yes
Instructions + stored events
GitHub Copilot
Yes
Yes
Instructions call ctx_session_init
Hook
What it does
PreToolUse
Blocks dangerous commands and routes likely-large outputs through ctx_execute.
PostToolUse
Records tool-call summaries for session restoration.
SessionStart
Injects context on supported hosts; Copilot records the event but ignores hook output.
Configuration
Default config:
~/.config/ctx-saver/config.yaml
Project override:
.ctx-saver.yaml
Small example:
sandbox:
timeout_seconds: 60
storage:
data_dir: ~/.local/share/ctx-saver
retention_days: 14
max_output_size_mb: 50
max_db_size_mb: 0 # 0 = unlimited; evict old outputs above this cap
summary:
head_lines: 20
tail_lines: 5
auto_index_threshold_bytes: 32768
smart_format: true
hooks:
session_history_limit: 10
view_deny_threshold_bytes: 131072 # 0 disables Copilot reference-read denial
notes: # ctx_note budgets, in characters (not bytes)
max_note_chars: 2000 # one "save"
max_handoff_chars: 6000 # one "handoff" — a whole session's state
list_budget_chars: 30000 # combined text from one "list" response
session_init_budget_chars: 12000 # combined decisions at session start
session_init_note_chars: 600 # one ordinary note at session start
superseded_handoff_chars: 240 # a replaced handoff; 0 hides its text
redaction:
enabled: true # scrub secrets before storage (default: true)
extra_patterns: # optional user-defined rules, merged after defaults
- name: internal_ticket
regex: 'INT-[0-9]{6}'
The notes write caps bound what one call may store. The read budgets bound what one
response may cost, which is what keeps a feature spanning many sessions from eating the
context window ctx-saver exists to protect. Omitted keys keep their defaults, and a
config whose handoff cap is smaller than its note cap is rejected at startup.
Freshness presets are in configs/freshness-examples, whose
default.yaml mirrors every compiled-in default.
Project Knowledge
After a few sessions, ctx-saver can generate .ctx-saver/project-knowledge.md so future AI sessions start with useful project memory:
most-read files
most-run commands
common command sequences
high-importance decisions grouped by task
session patterns
ctx-saver knowledge refresh
ctx-saver knowledge show
ctx-saver knowledge reset
Security
SQLite database permissions are 0600
command deny list is checked before execution
binary output with null bytes is rejected
paths are cleaned with filepath.Abs and filepath.Clean
command strings in logs are truncated to reduce secret exposure
secrets are redacted from output before storage (see Secret Redaction)
When using multiple AI hosts (Claude Code + Copilot + Codex) in the same
environment, you may see tool names like:
mcp__ctx-saver__ctx_execute
mcp__plugin__claude_ctx-saver__ctx_execute
This is expected behavior. Each host registers ctx-saver under its own
namespace. Both names point to the same server and the same database —
no data conflict or duplication occurs. The AI host calls the correct
namespace automatically.
ctx_session_init not called automatically
VS Code Copilot may require ToolSearch before calling deferred MCP tools,
which can cause ctx_session_init to be unavailable in the first turn. Copilot
Enterprise tools are expected to be pre-registered; if ctx_session_init is not
visible there, state the limitation and use the manual fallback from the project
instructions.
Fix: Add this line to your instruction file (CLAUDE.md / AGENTS.md /
copilot-instructions.md):
Your first tool call in every new session must be ctx_session_init.
If VS Code Copilot has not loaded ctx tools yet, run:
tool_search("ctx_session_init ctx_execute ctx_read_file ctx_stats ctx_note")
When Copilot cannot find ctx_stats, run ctx-saver doctor. If the local
stdio smoke check passes, reload VS Code, restart ctx-saver under
MCP: List Servers, open a new chat, and call the tool_search fallback.
Design Notes
ctx-saver intentionally uses local subprocesses and SQLite instead of remote services. The threat model is context pollution from huge outputs, not running untrusted software. The goal is to make AI coding sessions more focused, searchable, and recoverable while staying simple enough to audit.
C
Ctx Saver
ChonlakanSutthimatmongkhol·3 顆星·
A self-hosted MCP server (Go) that reduces AI context window usage by sandboxing large tool outputs and returning compact summaries instead of raw text.
上次檢查時間:2026-11-05。 A self-hosted MCP server (Go) that reduces AI context window usage by sandboxing large tool outputs and returning compact summaries instead of raw text.