contextgo 0.15.0

Local-First Context & Memory Runtime for Multi-Agent AI Coding Teams
Unified cross-agent memory, sub-second hybrid retrieval, native Model Context Protocol (MCP), and zero-knowledge encrypted multi-machine sync.

Architecture • Why ContextGO? • Quick Start • Native MCP • Supported Agents • Hybrid Engine • CLI Reference • Encrypted Sync • Smart Recall • 简体中文

Overview & Architecture

Modern AI software development rarely relies on a single tool. In any non-trivial engineering workflow, engineers fluidly switch between multiple AI coding assistants: DeepSeek Agent (dsh) for autonomous agentic refactoring, Claude Code for terminal-based project reasoning, Cursor or Windsurf for inline code completions, and Antigravity / Gemini for orchestrated subagent tasks.

However, each AI assistant functions within a siloed, ephemeral memory sandbox. When a developer changes tools, reboots a terminal session, or switches between laptops:

• Historical context evaporates: Past code explorations, architecture discussions, and verified root causes disappear.
• Agents repeat known failures: The next assistant attempts the exact same dead-end fix that another tool already disproved an hour ago.
• Friction and context switching compound: Engineers waste substantial time manually copying logs, transcripts, and decisions across disparate tools.

ContextGO solves this by providing a unified, local-first shared intelligence runtime for your AI coding assistants. It runs silently on your machine, auto-discovers and indexes sessions from 15+ AI coding environments, exposes a native Model Context Protocol (MCP) stdio server for live tool calling, and delivers sub-second hybrid lexical/vector recall with zero data exfiltration.

ContextGO 4-Tier Architecture: Multi-Agent Adapters, Local SQLite Engine, Interfaces & Native MCP Server, and Encrypted Multi-Device Sync.

Why ContextGO?

Quick Start

1. Installation

Install ContextGO globally using pipx to keep your Python environment clean and isolated:

# Standard installation with lexical hybrid recall & core engine
pipx install "contextgo[vector]"

# Or include zero-knowledge encrypted multi-machine sync
pipx install "contextgo[sync,vector]"

2. Shell Integration

Add instant shell aliases (cg for quick recall, cgs for full-text search, cgse for semantic recall):

eval "$(contextgo shell-init)"

Add that single line to your ~/.zshrc, ~/.bashrc, or configuration profile.

3. Verify Health & Auto-Detected Adapters

# Check runtime health, active databases, and vector status
contextgo health

# Inspect all detected AI coding tools and session counts on your machine
contextgo sources

4. Search & Recall Context Instantly

# Fast hybrid recall (automatically routes to keyword search or session ID lookup)
cg "how did we resolve the MT5 wine socket timeout?"

# Full-text lexical search across all indexed AI session histories
cgs "AdGuard Home DNS" --limit 5

# Memory-first semantic recall prioritizing durable architecture decisions
cgse "sync engine encryption and sharding architecture" --limit 3

# Save an authoritative technical conclusion or verified bug root cause
contextgo save --title "Bug: MT5 socket hang" --content "Resolved by tuning SO_RCVTIMEO to 15s." --tags "mt5,network"

Native MCP Server Support (v0.14.1)

ContextGO v0.14.1 introduces official Model Context Protocol (MCP) support. By running contextgo mcp, ContextGO acts as a standard JSON-RPC 2.0 stdio server, exposing native Function Calling tools directly to DeepSeek Agent (dsh), Claude Code, Cursor, Windsurf, Zed, and any MCP-compliant environment.

Exposed MCP Tools

Configuration Examples

1. Claude Desktop & Claude Code

Add to your claude_desktop_config.json or ~/.claude/mcp.json:

{
  "mcpServers": {
    "contextgo": {
      "command": "contextgo",
      "args": ["mcp"]
    }
  }
}

2. Cursor IDE

Add to .cursor/mcp.json or Global Cursor Settings:

{
  "mcpServers": {
    "contextgo": {
      "command": "contextgo",
      "args": ["mcp"]
    }
  }
}

3. Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "contextgo": {
      "command": "contextgo",
      "args": ["mcp"]
    }
  }
}

4. DeepSeek Agent (dsh)

Include in your .dsh/config.json or launch with stdio pipe:

{
  "tools": [
    {
      "type": "mcp",
      "command": "contextgo",
      "args": ["mcp"]
    }
  ]
}

Supported AI Agents & IDEs

ContextGO automatically discovers, streams, and harmonizes sessions from 15+ development tools on your machine without requiring manual configuration or altering agent binaries:

Hybrid Retrieval Engine

ContextGO delivers sub-second search precision across hundreds of thousands of conversational turns through a multi-stage, privacy-first retrieval pipeline:

1. SQLite FTS5 Lexical Indexing: Tokenizes source events into a local inverted index with Porter stemming and BM25 ranking.
2. Dense Vector Embeddings (Optional): Employs lightweight, CPU-efficient Model2Vec 256-dimensional embeddings for semantic affinity without needing GPU infrastructure.
3. Reciprocal Rank Fusion (RRF): Merges lexical keyword hits and dense vector semantic candidates using mathematical RRF scoring ($RRF = \sum \frac{1}{k + r}$).
4. Dynamic Time-Decay Prioritization: Exponentially boosts recent, highly relevant decisions while preserving historical milestones.
5. Noise Marker Filtering: Automatically identifies and suppresses boilerplate system prompts, repetitive error stack traces, and low-SNR agent artifacts.

CLI Command Reference

usage: contextgo [-h] [--version] <command> ...

Zero-Knowledge Multi-Device Sync

ContextGO provides secure, cross-machine synchronization backed by any private GitHub repository:

# 1. Initialize sync on your primary workstation (e.g. Windows 11)
contextgo sync init --repo your-org/my-contextgo-sync --device-id workstation-win11

# 2. Push encrypted shards to your private repository
contextgo sync push

# 3. Pull and merge on your laptop (e.g. macOS)
pipx install "contextgo[sync,vector]"
contextgo sync init --repo your-org/my-contextgo-sync --device-id macbook-m4
contextgo sync pull

Security Guarantees

• Client-Side AES-256-GCM: Every session observation is compressed and encrypted on your local machine before upload. The remote repository only ever receives encrypted ciphertext.
• Scrypt Key Derivation: Encryption keys are derived locally using scrypt with a unique per-repository salt. Your passphrase is never transmitted or stored remotely.
• Conflict-Free Device Shards: Each machine commits exclusively to its own encrypted partition (shards/<device-id>.enc.json), eliminating Git merge conflicts across platforms.
• Pre-Sync Credential Sanitization: API keys, bearer tokens, private keys, and local home directory paths are automatically detected and redacted prior to encryption.

Smart Context-First (SCF) Policy

AI agents perform significantly better when instructed to check prior project context before writing code. Running contextgo setup injects the canonical Smart Context-First (SCF) policy into active agent instruction files (GEMINI.md, CLAUDE.md, .cursorrules, copilot-instructions.md, etc.):

contextgo setup

Proactive Recall Guidelines for AI Agents

Native Background Daemon & Web Viewer

Run ContextGO as a native, lightweight background service for automatic, non-invasive session indexing:

# Control the background service
contextgo daemon start
contextgo daemon status
contextgo daemon stop

# Install the native OS service unit
contextgo daemon install

Zero-Dependency Local Web Viewer

Launch the built-in dashboard to visually explore sessions, search memories, and inspect agent timelines:

contextgo serve --port 37677

Open http://127.0.0.1:37677 in your browser. The viewer runs entirely locally with zero external network requests.

Security & Privacy Commitment

• 100% Local Execution: ContextGO stores all databases, indexes, and logs locally under ~/.contextgo.
• Zero Silent Telemetry: No analytics, telemetry pings, tracking tokens, or user data are ever sent over the network.
• Zero Mandatory Third-Party Dependencies: The core CLI, SQLite engine, MCP server, and Web viewer rely solely on the Python standard library.
• Safe for Proprietary & Air-Gapped Codebases: Completely safe to use in enterprise, financial, and confidential software environments.

Development & Release Gates

ContextGO enforces rigorous release quality standards with 86%+ test coverage and full lint/security validation:

# Clone repository
git clone https://github.com/dunova/ContextGO.git
cd ContextGO

# Sync development dependencies using uv
uv sync --extra dev --extra sync --extra vector

# Run code style, type check, and security audits
uv run ruff check src/contextgo tests
uv run ruff format --check src/contextgo tests
uv run mypy src/contextgo --ignore-missing-imports
uv run bandit -r src/contextgo -c pyproject.toml --quiet

# Execute full test suite & sandbox smoke gate
uv run pytest
uv run contextgo smoke --sandbox

Community & Star Support

If ContextGO saves you time and keeps your AI coding agents in sync, please consider starring the repository! Every star helps support open, local-first developer tooling.

• 🐛 Found a bug or need a new adapter? Open an issue on the GitHub Issue Tracker.
• 💡 Have a feature idea or discussion? Join the GitHub Discussions.
• 🤝 Want to contribute? Read our Contributing Guide.

License

ContextGO is licensed under the AGPL-3.0-only license.

Copyright © 2025-2026 Dunova.