ctxkeeper

A free, local, zero-config memory layer for GitHub Copilot. Saves your chat history per chat panel, compresses verbose prompts before they're sent, warns you before the context window fills up, and shows the AI Credits you've saved right in the status bar.

🎯 The four moments AI costs you money

Zero telemetry. Zero non-localhost network calls by default. ~178 KB minified JS bundle + ~844 KB WASM SQLite. Single universal vsix runs on Windows, macOS, and Linux.

Note on the chat path: @keeper <free text> forwards the prompt + memory context to the chat model you've already selected in Copilot — same destination as plain Copilot, no separate consent step. See SECURITY.md for the full data-flow table.

🚀 Getting started (30 seconds)

Prerequisites: VS Code 1.99 or newer and an active GitHub Copilot subscription. Building from source also needs Node.js 20 or newer.

After install, open any Copilot Chat window and type:

@keeper /help

That's it. You'll get a markdown response listing every slash command plus two clickable shortcut buttons. The status bar (bottom-right) will show ⚡ 0 saved · $0.00 — that number ticks up the first time the optimizer trims a prompt.

Persistent memory works out of the box on every platform with pure-WASM SQLite. Sessions live in your VS Code globalStorage (%APPDATA%\Code\User\globalStorage\ctxkeeper.ctxkeeper\taskmemory.db on Windows, ~/Library/Application Support/Code/User/globalStorage/ctxkeeper.ctxkeeper/ on macOS, ~/.config/Code/User/globalStorage/ctxkeeper.ctxkeeper/ on Linux) — mode 0o600 on POSIX. No native rebuilds, no platform-specific vsix.

💡 What you'll actually use

Resume a session from a fresh chat (Event 1)

@keeper /save fixing the JWT middleware bug
… work for an hour …
… restart VS Code or open a new chat …

@keeper /resume jwt

/resume <terms> ranks past sessions by FTS5 relevance and replays the most recent matching one. But you don't need the slash command — plain English works too in any new chat:

@keeper continue from last session
@keeper pick up where I left off
@keeper continue java session
@keeper continue the JWT middleware discussion we had
@keeper continue Install-ToolsInVM.ps1 session ← matches by file even if the
 name never appeared in a prompt
@keeper continue from 1 ← by session number from /sessions

When a match is found, ctxkeeper injects the prior session's turns and the list of files referenced in that session, so the model picks up exactly where you left off.

One chat panel = one session

Each time you open a new Copilot Chat panel, ctxkeeper starts a fresh session row in Task Memory. Type @keeper /sessions to see them listed with title, timestamp, status emoji, and a per-session metrics digest:

1. ✅ **fixing the JWT middleware bug** — _2026-06-01 09:20_ `6e39b655`
 _47 turns · 3 files · 2 overflows · 12 min_
2. ⚠️ **debugging the worker pool** — _2026-06-01 08:05_ `a1b2c3d4`
 _23 turns · 1 file · 1 overflow · 8 min_
3. 🚫 **untitled chat** — _2026-05-31 22:10_ `f00dbabe_
 _5 turns · 3 min_

Status legend: ✅ resolved · ⚠️ blocked · 🚫 abandoned · ❓ unfinished. The classifier runs on every /save using a local heuristic — phrases like "here's the fix" mark resolved, "still not working" marks blocked, and no follow-up for 30 min marks abandoned.

Import chats from other AI tools

If you already had a session in Claude Code or GitHub Copilot CLI and want to continue it in @keeper, just import it:

@keeper /capture-list ← see what's importable
@keeper /capture-claude <session-id> ← import a Claude Code session
@keeper /capture-copilot-cli <session-id> ← import a Copilot CLI session

After import, the session is indistinguishable from a native @keeper one — searchable via /find, resumable via @keeper continue <topic> session, file paths indexed. ctxkeeper becomes cross-AI-tool memory.

Each tool's local on-disk format gets a converter (~100 lines); Cursor, Codex, and others are easy to add in future versions.

Optimize a verbose prompt before sending (Prompt Tax)

@keeper /optimize I was wondering if you could perhaps help me figure out how to debug this race condition in my Express middleware where the requests sometimes seem to hang...

ctxkeeper shows a before / after preview with three clickable buttons: Send optimized · Edit first · Send original. Filler is stripped; code, URLs, and paths are preserved byte-for-byte. The status-bar AI Credits counter ticks up by the saved amount.

Optimization runs in four modes (default is heuristic, no LM calls):

For free-text @keeper prompts, an inline optimizer card appears automatically when the prompt exceeds 100 tokens (ctxkeeper.optimizer.autoOptimizeOverTokens). Shorter prompts pass straight through to the model.

Pin a workspace fact once, never re-explain it (Repetition Tax)

@keeper /note Auth invariants | Always lowercase emails before lookup. JWT secret in .env.local.
@keeper /pin 1

Pinned notes auto-inject into every @keeper turn (capped at 800 tokens). The model never forgets the conventions of this codebase — even after a model switch, a chat restart, or a window reload.

Get a warning before you blow the context window (Event 2)

When the chat hits 86% of the active model's window (configurable), you get:

⚠️ ctxkeeper · Critical — 91% of GPT-4o's 128k window is used.

[ Save & Start New ] [ Compress Current ] [ Dismiss ]

One click and the heavy turns get distilled into a fresh assistant message, freeing ~50K tokens. 11 popular models are pre-configured (GPT-4o, GPT-4o-mini, GPT-4.1, GPT-4-turbo, Claude 3.5 Sonnet, Claude Sonnet 4, Claude Opus 4, Claude Haiku 4, Gemini 1.5 Pro, o1, o3-mini); unknown models fall back to a conservative 32k.

Watch the AI Credits meter

⚡ 12,400 saved · $0.05

Where 1 AI Credit = 1 token of input you didn't have to send. Click the status-bar pill for a Quick Pick with:

• Session / today / week / month / lifetime breakdowns (each with token + dollar equivalent + ~time saved)
• 7-day daily sparkline (Unicode block art, zero dependencies)
• Per-category breakdown: save-flush, optimizer-heuristic, optimizer-lm-rewrite, optimizer-context-distill, capture

Note on dollar estimates: the USD figure is an approximation. It is most meaningful for premium-request, metered, or overage contexts; flat-rate Copilot users still benefit from fewer tokens sent and lower context pressure.

The dollar equivalent stays in the tooltip + Quick Pick rows so the ROI signal isn't lost; the status bar pill itself is kept clean.

🔒 Privacy & safety

• Local-only by default. Memory lives in your VS Code globalStorage directory. Zero outbound network calls without explicit consent.
• Telemetry locked off. No usage analytics ship — even anonymously — until you opt in.
• Pre-save secret scrub. Every turn written to disk passes through scrubSecrets() — AWS, GitHub PATs, Stripe, OpenAI/Anthropic/Slack tokens, JWTs, DB connection URIs, Azure AccountKeys, GCP service-account keys, ENV-style *_SECRET=…, and camelCase secretAccessKey / apiKey etc. are redacted before they touch disk.
• Editor diagnostics. Open a file with a hardcoded secret and you get a yellow squiggle + one-click Redact secret Code Action. The scanner and the scrubber use the same pattern set.
• POSIX file permissions. DB dir is 0o700, file is 0o600 — other users on a shared host (Citrix / RDP / dev containers) can't read your chats.

→ Full security audit, opt-in matrix, and audit-reproducibility commands: SECURITY.md

→ Third-party license attributions: THIRD_PARTY_NOTICES.md

⚙️ Settings worth knowing

The full ctxkeeper.* setting set is visible in VS Code's extension settings UI. The ones most people change:

📂 What gets remembered per session

Each chat panel maps to a session row in Task Memory with:

• The full turn history (user + assistant content, model id, timestamp)
• A derived title (first non-empty user prompt, truncated at 60 chars; falls back to "Untitled chat")
• The files referenced during that chat — paths you typed inline, paths in assistant responses, and #file: attachments via Copilot's chat references API
• Optional fact cards distilled from the session (heuristic by default, opt-in LM extraction)

This is why @keeper continue Install-ToolsInVM.ps1 session works even when the script name was never typed in a prompt — it's looked up via the session_files table.

📬 Feedback, issues, source

• GitHub: skfshashank/ctxkeeper — full design doc, benchmarks, roadmap
• Issues: github.com/skfshashank/ctxkeeper/issues
• Discussions: github.com/skfshashank/ctxkeeper/discussions
• License: MIT

Built for developers who want their assistant to remember, compress, and warn — without paying for cloud or losing privacy.