Span

Persistent codebase understanding for coding agents.

Span is a local MCP server that keeps what your agent learned about your repository tied to the code it came from, and marks it stale when the supporting evidence changes.

Quick start · How it works · Docs

The problem

Coding agents either trust documentation and memory that may no longer match the repository, or they re-read the same source, tests, contracts, and configuration every session and reconstruct the same understanding.

Nothing normally fails when a note becomes wrong. The file still looks valid, the agent still reads it, and the next session starts from the same uncertainty.

Span gives the agent a third option: established understanding, stored with the evidence that supports it, and an explicit answer about whether that support is still current.

See it

This is a real exchange from the current build, against a two-file fixture. The client is a scripted MCP client, not a model; it shows the wire and freshness behaviour, not model judgement. Raw records: current MCP acceptance evidence.

> explain src/alpha.py
Pending cont-1  CQ-01
  "VALUE = 1"

> submit_interpretation cont-1
PURPOSE  alpha computes the value
  CURRENT

> explain src/alpha.py
PURPOSE  alpha computes the value
  CURRENT

# edit src/alpha.py

> status src/alpha.py
PURPOSE  alpha computes the value
  STALE
  evidence changed
  scope: src/alpha.py

> refresh src/alpha.py
Pending cont-6  CQ-01
  "VALUE = 1 # touched"

> submit_interpretation cont-6
PURPOSE  alpha computes the value
  CURRENT
predecessor  STALE

The first call suspends with a bounded task. The submission establishes the purpose, and the next explain reads it back as current. After the file changes, status reports the purpose as stale, with the changed file and the scope to re-check. Refresh re-examines that one scope; the new result becomes current while the predecessor stays recorded as stale.

Stale means the supporting evidence changed. It does not mean Span has proved the old conclusion false.

The edit did not invalidate the whole repository, and it did not leave the old conclusion looking current. Span does not remove the first investigation; it keeps that work from being discarded when the session ends.

How it works

Like tests give code a feedback loop, Span gives codebase understanding one.

1. Establish. The agent investigates a bounded area. Span keeps the conclusion together with the evidence and authority it used.
2. Reuse. Later agents get the established understanding while its support is still current.
3. Invalidate narrowly. When supporting evidence changes, only the understanding that depended on it becomes STALE.
4. Re-check. The agent investigates the affected scope and submits a new result. Unaffected understanding stays current; the predecessor remains as history.

Quick start

Span currently requires Linux (the verified installation path), Python 3.12 or newer, and Node.js with npm.

pipx install span-mcp        # or: pip install span-mcp
span-install --repo /path/to/your/repo

span-install creates Span's runtime environment, provisions the managed structural indexer, deploys the Agent Skills, and registers supported hosts. Restart or reload your coding agent after installation.

Verify the installation:

span-install --verify-only

To work from a source checkout instead — when contributing, or when pinning to a commit — clone the repository and run the installer from its root:

git clone https://github.com/pontivus-com/span.git
cd span
python3 scripts/install-span.py --repo /path/to/your/repo

Installation establishes operational readiness, not repository understanding. For the manual Codex command and the OpenCode entry, see install and connect.

Works with

Span runs locally over stdio. It does not call an LLM, choose a model, or store provider credentials. Its state lives in a data directory outside the repositories it analyzes.

Why it is different

Documentation records an answer. Agent memory remembers. Search finds evidence. Span maintains the interpretation layer between them: the conclusion, its evidence, its authority, its dependencies, and its freshness.

The detailed comparison, including the difference between validation and scoped doubt, is in scope and boundaries.

What it is not

• Not a documentation generator.
• Not general agent memory, validated or otherwise.
• Not code search or a structural graph.
• Not an LLM service: it never invokes a model or stores provider credentials.
• Not autonomous: it does not edit code, run tests, or make stale understanding current by itself.

See scope and boundaries for the full list.

Status

Span is beta. Linux is the currently verified installation path; macOS and Windows paths are reserved but not verified. The public operation surface is eleven MCP operations; see the MCP reference. Recorded acceptance runs are in acceptance evidence.

If Span is useful to you, a star helps other developers find it. Feedback and issues are welcome.

Documentation

• Repository overview
• Install and connect
• Using Span
• MCP reference
• Freshness and refresh
• Evidence, authority, trust
• Scope, boundaries, and differentiation
• FAQ
• Architecture
• Full documentation index
• Glossary
• Changelog

Contributing

See the contributing guide. Changes should preserve the central contract: established understanding remains reusable only while its required supporting evidence remains current. Security reports are handled through SECURITY.md. Support expectations are described in SUPPORT.md.

Registry

Official MCP Registry entry: io.github.pontivus-com/span

mcp-name: io.github.pontivus-com/span

License

Span is licensed under the Apache License 2.0 (Apache-2.0). See LICENSE.

In one sentence

Span gives coding agents codebase understanding that cannot go stale silently: reuse what is still current, and re-check only what changed.