Compression Management

Create, manage, and use compressions to reduce token usage and improve AI context quality.

Create Compressions

Basic Compression

Compress a single document:

metaphori compress document.txt

Compress multiple files:

metaphori compress "*.md" "docs/*.txt"

Compression Options

Named compressions with description:

metaphori compress -n "Analysis Doc" --description "Q4 analysis" report.md

Using templates:

metaphori compress -t 1 document.txt  # Use template 1

Compression levels:

metaphori compress -l high doc.txt     # Good compression
metaphori compress -l higher doc.txt   # Better compression
metaphori compress -l highest doc.txt  # Best compression

Higher levels provide better compression but may take longer.

Interactive mode:

metaphori compress -i document.txt

Guides you through compression options interactively.

Advanced Options

Recursive file search:

metaphori compress -r "**/*.md"

Exclude patterns:

metaphori compress --exclude "*.test.*" "*.js"

File size limits:

metaphori compress --max-file-size 10MB "*.log"

Code Compression

The codebase command is optimized for compressing entire codebases:

Compress Go project:

metaphori codebase "*.go"

Compress React project:

metaphori codebase -r "**/*.{js,ts,jsx,tsx}"

Full codebase (no sampling):

metaphori codebase --full "*.py"

By default, large codebases are sampled. Use --full to include everything.

Limit number of files:

metaphori codebase --max-files 200 "src/**/*.java"

Named codebase compression:

metaphori codebase -n "My API" --description "REST API implementation" "*.go"

List & Manage Compressions

List Compressions

Basic list:

metaphori list

Detailed view:

metaphori list -d

Shows creation date, size, and token counts.

JSON output:

metaphori list -j

For scripting and automation.

Sync Compressions

Download all your compressions from the server:

metaphori sync

Force full re-sync:

metaphori sync -f

Tip: Sync is useful when switching machines or after creating compressions via the web interface.

Using Compressions

Chat with Compressions

Basic chat:

metaphori chat -c mph_c_xxxxx "explain this code"

Specify model:

metaphori chat -c mph_c_xxxxx -m gpt-4o-mini "summarize the main points"

Save output to file:

metaphori chat -c mph_c_xxxxx --output response.md "analyze performance"

File References in Chat

Include additional files in your prompts using @ syntax:

metaphori chat "analyze @main.go and compare with @test.go"

Files referenced with @ are included in the context alongside any compression.

Compression IDs

Each compression gets a unique ID like mph_c_bc96f970f099. You can:

  • Use it in CLI commands
  • Pass it to the OpenAI-compatible API
  • Share it with team members (they need access to the same account)
  • Reference it in integrations

Best Practices

📝 Use Descriptive Names

Always use -n and --description for better organization.

🎯 Choose the Right Level

Start with high compression. Use highest for very large documents.

🔄 Update Regularly

Recreate compressions when your codebase changes significantly.

Ready for interactive mode?

Learn about Sherpa, Metaphori's powerful REPL for interactive AI sessions.

Continue to Interactive Mode →