Configuration

ultrasync can be configured through environment variables, CLI flags, and local configuration files. This guide covers all available options.

Environment Variables

Client Configuration

These variables configure the ultrasync MCP client running in your coding agent.

Variable	Default	Description
`ULTRASYNC_REMOTE_SYNC`	`false`	Enable team sync
`ULTRASYNC_SYNC_URL`	-	Sync server URL
`ULTRASYNC_SYNC_TOKEN`	-	Your API token
`ULTRASYNC_TOOLS`	`search,memory`	Enabled tool categories
`ULTRASYNC_INDEX_PATH`	`.ultrasync/`	Local index location
`ULTRASYNC_LOG_LEVEL`	`info`	Logging verbosity

Tool Categories

The ULTRASYNC_TOOLS variable controls which tool categories are exposed to your MCP client:

Category	Tools Included
`search`	`search()`, `get_source()`, semantic code search
`memory`	`memory_write()`, `memory_search()`, persistent context
`sync`	Team sync, shared memories, real-time collaboration
`conventions`	`convention_discover()`, `convention_check()`
`insights`	`insights_by_type()`, `list_insights()`

Example configurations:

# Local-only mode (default)
ULTRASYNC_TOOLS="search,memory"

# Full team collaboration
ULTRASYNC_TOOLS="search,memory,sync"

# All features
ULTRASYNC_TOOLS="search,memory,sync,conventions,insights"

Log Levels

Control logging verbosity with ULTRASYNC_LOG_LEVEL:

Level	Description
`debug`	Verbose output for troubleshooting
`info`	Standard operational logging (default)
`warning`	Warnings and errors only
`error`	Errors only

Local Configuration

Index Directory

ultrasync stores its local index in .ultrasync/ by default. This directory contains:

.ultrasync/
├── index.lmdb       # Symbol and file index
├── blobs/           # Source code cache
├── memories.db      # Local memory storage
└── config.json      # Local configuration

Customize the location:

ULTRASYNC_INDEX_PATH="/custom/path/.ultrasync"

Gitignore

Add .ultrasync/ to your .gitignore - the index is machine-specific and should not be committed:

# ultrasync local index
.ultrasync/

MCP Client Configuration

Claude Code

Minimal configuration (local only):

{
  "ultrasync": {
    "type": "stdio",
    "command": "uv",
    "args": ["tool", "run", "--from", "ultrasync-mcp", "ultrasync", "mcp"]
  }
}

Full configuration (with team sync):

{
  "ultrasync": {
    "type": "stdio",
    "command": "uv",
    "args": ["tool", "run", "--from", "ultrasync-mcp", "ultrasync", "mcp"],
    "env": {
      "ULTRASYNC_REMOTE_SYNC": "true",
      "ULTRASYNC_SYNC_URL": "https://mcp.ultrasync.dev",
      "ULTRASYNC_SYNC_TOKEN": "<your-api-token>",
      "ULTRASYNC_TOOLS": "search,memory,sync",
      "ULTRASYNC_LOG_LEVEL": "info"
    }
  }
}

Codex CLI

Minimal configuration:

[mcp_servers.ultrasync]
command = "uv"
args = ["tool", "run", "--from", "ultrasync-mcp", "ultrasync", "mcp"]

Full configuration:

[mcp_servers.ultrasync]
command = "uv"
args = ["tool", "run", "--from", "ultrasync-mcp", "ultrasync", "mcp"]

[mcp_servers.ultrasync.env]
ULTRASYNC_REMOTE_SYNC = "true"
ULTRASYNC_SYNC_URL = "https://mcp.ultrasync.dev"
ULTRASYNC_SYNC_TOKEN = "<your-api-token>"
ULTRASYNC_TOOLS = "search,memory,sync"
ULTRASYNC_LOG_LEVEL = "info"

Indexing Configuration

Supported File Types

ultrasync extracts symbols (functions, classes, types) from these languages:

Language	Extensions
Python	`.py`, `.pyi`
TypeScript	`.ts`, `.tsx`
JavaScript	`.js`, `.jsx`, `.mjs`, `.cjs`
Rust	`.rs`

Other file types can be indexed for semantic search using the --extensions flag, but symbol extraction is only available for the languages above.

Exclude Patterns

By default, ultrasync excludes common non-source directories:

node_modules/
.git/
dist/, build/, out/
.next/, .nuxt/
__pycache__/, .pytest_cache/
venv/, .venv/, .env/
vendor/
coverage/

Custom exclusions via CLI:

ultrasync index --exclude "generated,tmp,fixtures"

Indexing Strategies

Full index (recommended for first run):

ultrasync index

Incremental update (faster, uses cache):

ultrasync index --incremental

Force complete re-index:

ultrasync index --force

Index specific paths:

ultrasync index src/ lib/ tests/

Team Sync Configuration

Sync Modes

Mode	Description
Local only	No sync, memories stored locally
Team sync	Shared memories visible to team members
Org sync	Cross-project memory sharing within organization

Privacy Controls

Memories are personal by default. To share with your team:

# In your coding session
memory_write_structured("Design decision: using Redis for caching")

# Later, share it
share_memory("mem:abc123")

Conflict Resolution

When syncing across team members:

Last-write-wins for simple values
Merge for memories (both versions preserved)
Server-authoritative for shared state

CLI Reference

Index Command

ultrasync index [OPTIONS] [PATHS...]

Options:
  --verbose, -v        Show detailed progress
  --force, -f          Force complete re-index
  --incremental, -i    Only index changed files
  --exclude PATTERNS   Comma-separated exclude patterns
  --help               Show help message

Query Command

ultrasync query [OPTIONS]

Options:
  --query-text TEXT    Search query
  --top-k N            Number of results (default: 5)
  --format FORMAT      Output format: json, tsv
  --help               Show help message

MCP Command

ultrasync mcp [OPTIONS]

Options:
  --help               Show help message

Starts the MCP server for integration with coding agents.

Next Steps

Installation - Setup instructions

Configuration

On this page