Documentation

What is SessionGraph?

SessionGraph is a local HTTPS proxy that sits transparently between your AI coding tool and the upstream AI API (Anthropic, OpenAI, etc.). It intercepts every request, compresses the context window by removing redundant or already-resolved content, and then forwards the slimmer payload to the provider. On average, users see an 84% reduction in tokens sent per request.

Beyond compression, SessionGraph extracts a structured session graph from your conversation — a compact JSON snapshot of the project decisions made, files touched, errors resolved, and patterns established during the session. When you start a new session the next day, SessionGraph injects that graph into the system prompt, giving the AI an instant, accurate picture of where you left off — without you re-explaining anything.

Everything runs on your machine. Your code, API keys, and conversation content never leave your device. The proxy only forwards the compressed messages to the AI provider you were already using.

Installation

System Requirements

• macOS 12 Monterey or later (Apple Silicon and Intel)
• Windows 10 / 11 (x64)
• Linux: Ubuntu 20.04+ or any distro with glibc 2.31+
• 4 GB RAM minimum, 8 GB recommended
• 100 MB free disk space

Download & Install

1. Go to sessiongraph.dev/download and download the installer for your platform.
2. Run the installer. On macOS you may need to right-click → Open to bypass Gatekeeper on first launch.
3. SessionGraph will start automatically and appear in your system tray / menu bar.
4. On first launch, SessionGraph generates a local CA certificate at ~/.sessiongraph/ca.crt and installs it into the system trust store.

Verifying SessionGraph is Running

Open a browser or run the following command to hit the health-check endpoint:

curl http://127.0.0.1:4200/health

A healthy response looks like:

{"status":"ok","proxy":"running","version":"0.1.0"}

Configuration

SessionGraph is configured by setting two environment variables that point your AI tool at the local proxy, plus one variable that makes Node.js trust the local CA certificate used for HTTPS interception.

Environment Variables

export HTTPS_PROXY=http://127.0.0.1:4200
export HTTP_PROXY=http://127.0.0.1:4200
export NODE_EXTRA_CA_CERTS="$HOME/.sessiongraph/ca.crt"

Add these to your shell profile (~/.zshrc, ~/.bashrc, or ~/.profile). For Windows, set them as System Environment Variables in the Control Panel or use the PowerShell equivalent:

$env:HTTPS_PROXY = "http://127.0.0.1:4200"
$env:HTTP_PROXY  = "http://127.0.0.1:4200"
$env:NODE_EXTRA_CA_CERTS = "$env:USERPROFILE\.sessiongraph\ca.crt"

One-Click Profile Installer

SessionGraph includes a one-click CLI profile installer in the desktop app. Open the dashboard, click Configure CLI, and SessionGraph will automatically append the correct variables to your shell profile and reload the shell. No manual editing required.

How the CA Certificate Works

Modern AI APIs use HTTPS, which means traffic is encrypted end-to-end. To intercept and inspect the request bodies, SessionGraph performs MITM (man-in-the-middle) TLS interception. It generates a unique, per-device root CA certificate the first time it runs and registers it with your operating system's trust store. When your tool makes an HTTPS request to api.anthropic.com or api.openai.com, SessionGraph presents a dynamically generated leaf certificate signed by the local CA, terminates the TLS connection, reads and compresses the request body, then establishes a fresh TLS connection to the real upstream server.

The CA certificate lives at:

~/.sessiongraph/ca.crt

Node.js-based tools (Claude Code, Aider, Codex CLI) require NODE_EXTRA_CA_CERTS to trust this cert. Python-based tools typically use the system trust store, which is automatically updated during install. Java or Go-based tools may require additional steps; consult your tool's proxy documentation.

Supported Tools

SessionGraph works with any tool that respects the standard HTTP_PROXY / HTTPS_PROXY environment variables. The following tools are tested and fully supported:

Any other tool that sends requests to api.anthropic.com or api.openai.com and honours HTTPS_PROXY will work automatically. Tools with hard-coded direct connections (no proxy support) are not compatible.

How Compression Works

Every request to an AI API contains a messages array — the full conversation history. As sessions grow, this array can span tens of thousands of tokens, most of which contain information the model has already reasoned about: file contents it has already read, errors it has already fixed, decisions it has already made.

The Compression Pipeline

1. Intercept. The proxy captures the full JSON request body before it reaches the network.
2. Analyse. The messages array is passed to a local LLM-based summariser that identifies redundant context: file contents the model has already digested, repeated tool results, resolved error traces, and verbose back-and-forth that is now settled.
3. Compress. Redundant messages are replaced with dense summaries or removed entirely. Recent messages (the active working context) are always preserved verbatim.
4. Forward. The compressed payload is sent to the upstream AI provider. The provider sees a valid, well-formed request — just with a much smaller token count.
5. Preserve. The original, uncompressed messages are stored locally in SQLite. They are never discarded, which is what enables full session graph extraction and restoration.

The compressor is tuned to be conservative: it will never compress a message that is still relevant to the current task. If in doubt, it preserves. The 84% figure is an average across real-world sessions; individual savings depend on session length and content.

Session Graphs

At the end of a session (or on demand via the dashboard), SessionGraph extracts a session graph — a structured JSON representation of what happened during your coding session.

What a Session Graph Contains

• Files touched (created, modified, deleted)
• Architectural decisions made and the rationale captured
• Errors encountered and how they were resolved
• Patterns and conventions the AI was instructed to follow
• Open questions and known technical debt noted during the session
• Token and cost statistics for the session

Session Restoration

When you start a new AI session, SessionGraph detects the active project (by working directory) and injects the most recent session graph into the system prompt before your first message is sent. The AI receives a compact, structured briefing on the project state — what was built, what was decided, what still needs to be done — without requiring you to type a word.

Restoration is automatic when the proxy is running. You can also disable it per-project in the dashboard if you want a clean-slate session.

Viewing Session Graphs

Open the SessionGraph desktop dashboard and navigate to the Sessions tab. Select any session to see an interactive D3.js graph visualisation of the session nodes and relationships. Click any node to inspect its content. You can export a graph as JSON or copy it to the clipboard.

Free Tier Limits

Context compression is always unlimited on all plans — there are no caps on how much you save.

Session graph saves are limited to 3 per calendar month on the Free tier. When you reach the limit, you can still use compression; you just cannot save new session snapshots until the next month or until you upgrade.

Upgrade to Pro for unlimited session saves, priority support, and early access to new features. See pricing →

Troubleshooting

Privacy

SessionGraph is designed with a strong privacy-by-default stance.

• Your API keys never leave your machine. The proxy forwards your API key only to the upstream AI provider you configured — the same provider you were already sending it to directly.
• Your code stays local. Source files, conversation content, and session graphs are stored only in the local SQLite database at ~/.sessiongraph/sessions.db.
• No telemetry without consent. The desktop app sends no analytics by default. Aggregate, anonymous usage stats (tokens saved, session count) are sent to the web dashboard only if you are signed in to a SessionGraph account.
• Outbound connections. The only outbound connections made by the proxy are (1) the forwarded request to your AI provider, and (2) if you have a paid license, a periodic license validation ping to our server containing only your license key hash — no conversation content.

See the full Privacy Policy for complete details.

FAQ