AILv1

What it is

When a long session moves to a new model or a fresh context window, a plain summary tends to lose the parts that matter most: which approaches already failed and why, which names keep recurring, and what the code actually looks like. AILv1 (Agent Intermediate Language, version 1) keeps those in tagged lines:

• @MEM defines short $N pointers for names that recur.
• @CTX and @ARCH hold context, topology and data flow.
• @LOG records a rejected approach, the reason, and what replaced it.
• @SIG lists code signatures with the state they mutate.
• @NEXT lists open tasks.

!AILv1
@MEM $1=recipe_api $2=MinIO $3=Celery_Redis
@ARCH $1[FastAPI|Postgres] := upload->$2:originals->$3:make_thumbnails->$2:thumbs
@LOG !FastAPI_BackgroundTasks(lost_40_jobs_on_redeploy) -> ^$3_acks_late
@SIG worker.py|make_thumbnails(photo_id:int,key:str)->list[str]|mutates(storage.put_object_bytes)
@NEXT ?per_user_upload_rate_limit

The tool is a single Python script that needs only the standard library. It includes:

• an encoder that redacts secrets by default before it does anything else;
• a decoder that only parses, resolves pointers in one pass, and caps input and output size;
• a signature extractor built on Python's ast module;
• a CLI, an MCP server, and an Agent Skill (SKILL.md).

Redaction covers common API tokens and keys, private key blocks, password= and "api_key": "…" style credentials, email addresses, and IPv4 and IPv6 addresses. It is pattern-based and has limits, which SECURITY.md lists.

Use it in your own project

AILv1 ships as one folder, skills/ail-context-compressor, which holds the SKILL.md file and the Python script. You can load it as an Agent Skill, run it as an MCP server, or both.

No install: the README has a prompt-only encoder you can paste into any AI chat.

1. Download the release

From the latest release, download both files into the same folder: ail-context-compressor-v1.0.1.zip and ail-context-compressor-v1.0.1.zip.sha256. The zip holds one folder, ail-context-compressor/, with SKILL.md, scripts/ail_mcp.py, mcp.example.json, the README, SECURITY.md and LICENSE.

Check the zip before you unpack it:

sha256sum -c ail-context-compressor-v1.0.1.zip.sha256       # Linux
shasum -a 256 -c ail-context-compressor-v1.0.1.zip.sha256   # macOS

It should print ail-context-compressor-v1.0.1.zip: OK. If it does not, delete the zip and download it again.

2. Unzip it into your project

Unzip into your project's skills folder. For Claude Code that is .claude/skills/, which puts the skill at .claude/skills/ail-context-compressor/:

cd /path/to/your-project
mkdir -p .claude/skills
unzip /path/to/ail-context-compressor-v1.0.1.zip -d .claude/skills

To make the skill available in every project rather than one, unzip into ~/.claude/skills instead. Other agents that read SKILL.md files have their own skills folder; unzip into it.

If you prefer to work from source, clone the repository and copy the folder yourself:

git clone https://github.com/jiludkumar-therealone/ail-context-compressor.git
mkdir -p .claude/skills
cp -r ail-context-compressor/skills/ail-context-compressor .claude/skills/

3. Add the MCP server

Install the mcp package (1.x or 2.x) with pip install mcp, then add the server to your client's MCP configuration. For a single project this is usually a file in the project, such as .mcp.json for Claude Code or .cursor/mcp.json for Cursor. Start from mcp.example.json and point the path at the copy you made in step 2:

{
  "mcpServers": {
    "ail-context-compressor": {
      "command": "python3",
      "args": ["/path/to/your-project/.claude/skills/ail-context-compressor/scripts/ail_mcp.py", "mcp"]
    }
  }
}

The same block is in mcp.example.json in the zip and in claude_desktop_config.example.json in the repository. The server exposes four tools: ail_compress_text, ail_extract_code_sigs, ail_hydrate_state, and ail_save_checkpoint. The checkpoint tool writes a new <name>.ail file in the server's working directory only. It takes no directory argument, never overwrites a file, and never follows symlinks.

From the command line

The script needs only the Python standard library (3.10 or later):

S=skills/ail-context-compressor/scripts/ail_mcp.py
python3 $S pack -f notes.md > session.ail   # prose or chat log to snapshot
python3 $S sig -f app.py                    # @SIG lines only
python3 $S unpack -f session.ail            # back to readable text

Running pip install . from a checkout installs the same script as the ail-mcp command. Install tiktoken if you want exact token counts.

Benchmarks

Token counts use tiktoken's cl100k_base encoding (tiktoken 0.14.0). Every input is in the repository's benchmarks/inputs/ folder and is invented sample text.

How to read these numbers:

• On Python source, the encoder keeps only signatures and mutations, so the saving is large. Function bodies are dropped. The result is a map of the code, not a copy of it.
• On prose, the automatic encoder is close to lossless and saves little, because it only replaces long names that repeat. The large saving on a conversation comes from a hand-written snapshot, which is a summary and drops detail.
• On a short paragraph, AILv1 can cost more tokens than the original. Pointers and section tags pay off only when names repeat.

To reproduce the table from a checkout:

pip install tiktoken
python3 benchmarks/run.py

A test in the repository fails if the README table drifts from what this script measures.

Source and license

• Source code, issues and full documentation: github.com/jiludkumar-therealone/ail-context-compressor
• Security policy and redaction scope: SECURITY.md
• Origin and design rationale: Why AIL exists
• License: MIT