dotscope 1.6.2

Agents see files. You see architecture. dotscope gives agents the architecture.

Dotscope: The Physics Engine for AI Coding Agents

AI agents operate blind. They process code as flat text, fundamentally unaware of the structural gravity and blast radius of the files they intend to modify. They hallucinate architectural boundaries, break implicit contracts, and fail silently because they simply do not possess the mathematical context of your repository.

Dotscope is a structural compiler that force-feeds physical topology into their reasoning loop. Supported natively via the Model Context Protocol (MCP) on Cursor, Windsurf, and Claude Desktop, Dotscope guarantees that agents stop hallucinating state and start adhering to the strict architectural boundaries of your application.

---

The Magic: Frictionless UX

You do not need to teach your AI a new paradigm. The AI simply searches the codebase exactly as it normally does.

However, under the hood, Dotscope's Semantic Interceptor hijacks the query. It intercepts the natural language request and instantly enriches the return payload with the precise structural reality of the targets. The agent reads the code, and mathematically understands the blast radius simultaneously.

Because Dotscope operates an Immortal Matrix—a standalone background double-buffered architecture—the graph is never stale. Saving a file natively updates the dependency mapping behind the scenes instantly.

---

The Proof: Unfakeable Rigor

Dotscope isn't a wrapper; it is an optimized topological execution plane engineered to map planetary-scale structures.

The Titan Metric Benchmark:

• Sustained Load: 100,000 files, 50,000 commits evaluated.
• Execution Time: ~32 seconds initial ingestion.
• Memory Ceiling: Bounded strictly to 208MB RAM.

The system natively absorbs IDE "save-spam" and completely eliminates memory-tearing across agents seamlessly via Read-Copy-Update epoch locks.

---

Quick Start (3-Step Installation)

It is brain-dead simple to bind Dotscope to your repository locally.

# 1. Install the core toolkit
pip install dotscope

# 2. Bind your repository and implicitly launch the tracking plane
dotscope init

# 3. Connect to your Agent
# Dotscope automatically generates the `.cursorrules` or `.windsurfrules` constraints required to orient the AI.

---

The Flex: Under the Hood

For the Systems Engineers: Dotscope borrows its architectural fundamentals straight from High-Frequency Trading (HFT) infrastructure.

Instead of forcing your AI to ping slower Python GIL-bound scripts or bloated Language Servers that take 30 seconds to cold-start, Dotscope relies on a standalone local Rust Daemon performing continuous AST ingestion in the background.

1. The Write-Plane: A compiled dotscope_daemon.exe uses notify to debounce IDE file-write spikes into a Token Bucket, safely calculating zero-latency $O(V + E)$ dependency subgraphs gracefully.
2. The Read-Plane: We leverage standard C-aligned memory mapping (memmap2) to deploy double-buffered matrices (topology_A.bin / topology_B.bin). The Python MCP read-plane structurally casts these zero-copy bounds into memory in exactly 0 CPU cycles.
3. Multi-Version Concurrency Control (MVCC): Your AI reads from an immortal control.mmap atomic semaphore. If the agent queries the repo while a massive file modification is resolving, a local Unix-style blocking socket catches the Python process and formally halts the AI's thread natively until the matrix mathematically resolves. Zero hallucinogenic state is explicitly enforced at the OS level.

---

Scaling to the Swarm (Coming Soon)

Local .mmap daemons are built for isolated IDEs. But when you deploy autonomous agents at planetary scale, the physics must scale with them.

Dotscope Pro: The Genesis Matrix

Open-source Dotscope calculates the physical layout of your local codebase in realtime. Dotscope Pro is the global intelligence vector. By connecting to the Pro WebSocket, your agents don't have to compile graphs from scratch; they instantly stream pre-compiled structural fingerprints from over 10,000 top-tier open-source architectural hubs. Your agent doesn't just know how you construct code, it mathematically recognizes how the planet constructs it natively across boundaries.

Dotswarm: Fleet Telemetry & Swarm Locks

What happens when you deploy 50 autonomous agents against a single enterprise monorepo infrastructure? They clobber each other's execution states. Dotswarm lifts our zero-latency local MVCC synchronization primitives directly into a distributed backend. It formally enforces Swarm Locks across distributed memory pools, guaranteeing massive AI fleets can orchestrate cross-repository execution simultaneously without triggering catastrophic merge collisions.