TIER v1.0.0 — Tiered Information for Efficient Retrieval

A 4-layer context format, codebase graph indexer, and zero-dependency MCP server that cuts AI agent token usage by 86%–97%.

Quickstart · See it in action · Benchmarks · Architecture · Format spec

TIER keeps AI agents from loading whole repositories and documents into context. It gives every document an always-loadable L0 index, one-line L1 abstracts, L2 signatures and dependency edges, and surgical L3 source-line slices. A hybrid retriever, incremental repository map, reverse-dependency impact graph, and write-back memory keep context small and current.

The core is 100% Python standard library — no runtime dependencies, no API calls, no telemetry. Optional extras add terminal styling and the official MCP SDK adapter.

30-Second Quickstart

From a checkout:

python3 -m pip install .          # or: python3 -m pip install -e .
# isolated CLI: uv tool install .  /  pipx install .

Then run the two commands that configure and verify everything:

tier install      # interactive wizard: Claude Code, Claude Desktop, Cursor, VS Code, Windsurf
tier doctor       # environment, configs, repo.tier, lint, and sync checks

tier install writes safe .bak backups, preserves other MCP servers, and is idempotent. Use --clients, --yes, --dry-run, or --uninstall for scripts and CI. tier setup is an alias.

Related MCP server: parecode

See It in Action

$ tier from-repo . -o repo.tier
wrote repo.tier

$ tier index repo.tier | head -4
tier repository map - 24 source files; languages: javascript 1, python 23; entrypoints: ...
! Read the repo.tier module map before opening source files; fetch only the listed line ranges.
! Use tier_get with follow=true to pull a module and its direct local dependencies.
! Use tier_slice for exact L3 source slices instead of reading whole files.

$ tier find repo.tier "parse TIER document" -k 1
@src-tier-parser.py  46.75  src/tier/parser.py (python module); symbols: wrap_untrusted, parse, nodes, ...

$ tier slice repo.tier src/tier/parser.py parse
@src-tier-parser.py#parse [L43-L111]
    def parse(text: str) -> Doc:
        doc = Doc()
        ...

$ tier impact repo.tier src/tier/parser.py
Impact target: @src-tier-parser.py
Direct dependents: @src-tier-__init__.py, @src-tier-cli.py, @src-tier-converter.py, ...
Dependencies: @src-tier-models.py

Measured on this repository: 49,725 raw src/tier tokens → 695-token L0 → 1,460-token L0 + one-hop. The complete five-step workflow costs 4,441 tokens (−91.1%) while retrieving 3/3 exact slices and 10/10 dependents.

Core Capabilities

Verified Benchmarks

All numbers below are from benchmarks/BENCH.txt, produced by benchmarks/bench.py with the o200k_base tokenizer. TIER measures tokens and retrieval identifiers, not LLM answer accuracy.

The checked-in self-index repo.tier maps 24 source files in 11,034 tokens with an 893-token L0 (8%). Reproduce the full suite:

./benchmarks/fetch_corpus.sh     # optional: Tracks D and I corpus
python3 benchmarks/bench.py      # writes benchmarks/BENCH.txt

tier install / tier setup detects and configures:

tier install                                      # interactive
tier install --clients claude-code,cursor --yes   # scripted
tier install --clients all --dry-run              # preview diffs only
tier install --uninstall --clients all            # remove TIER entries only
tier install --no-repo --no-hook --instructions none

Every existing JSON config is backed up to <file>.bak before an atomic merge. Existing servers, hooks, and keys are preserved. The installer prefers an absolute tier-mcp executable, falling back to the absolute current interpreter with -m tier.mcp, so GUI hosts do not depend on shell PATH.

The default pip install tier runtime is stdlib-only, with dependencies = [].

pip install "tier[ui]"    # rich terminal rendering for installer/doctor
pip install "tier[mcp]"   # official mcp v2 SDK adapter
pip install "tier[all]"   # both

• [ui] adds rich styling. Without it, the installer and doctor use ANSI colors and box drawing with a clean non-TTY fallback.

• [mcp] adds the official mcp>=2.0 SDK and the tier-mcp-sdk command / python -m tier.mcp.sdk_server module. It wraps all 11 tools with MCP v2 MCPServer (v1 FastMCP fallback), supports mcp dev for MCP Inspector, and serves Streamable HTTP:

tier-mcp-sdk /path/to/docs
python3 -m tier.mcp.sdk_server /path/to/docs --transport streamable-http --host 127.0.0.1 --port 8000
mcp dev src/tier/mcp/sdk_server.py

Without the extra, tier-mcp-sdk prints the exact pip install "tier[mcp]" command and exits cleanly. The default tier-mcp / python -m tier.mcp server remains the zero-dependency stdlib JSON-RPC implementation.

CLI

MCP tools

tier_list, tier_index, tier_find, tier_get, tier_slice, tier_impact, tier_sync, tier_lint, tier_ingest, tier_repo, tier_remember.

Start the default server with tier-mcp /path/to/root or python3 -m tier.mcp /path/to/root. All paths are confined to the configured root; live repository edits auto-sync before reads.

Privacy, Zero Telemetry & Contributing

TIER runs entirely on your machine. There are no telemetry, analytics, API keys, or network calls in the core runtime. The MCP server is path-sandboxed, repository scans reject symlinks escaping the root, and memory writes are validated before an atomic replace. The optional [mcp] Streamable HTTP transport is the only network listener, and only when you explicitly start it.

• Format and safety rules: SPEC.md

• Module boundaries, layer flow, and contributor guide: ARCHITECTURE.md

• Examples: examples/

• Full benchmark output: benchmarks/BENCH.txt

python3 -m unittest discover -s tests -q     # 88 tests
tier doctor .                                # 10 checks: 0 failed, 0 warnings
python3 benchmarks/bench.py                  # Tracks A-I; writes benchmarks/BENCH.txt
tier from-repo . -o repo.tier                # refresh the checked-in self-index
tier lint repo.tier && tier lint SPEC.tier

Limits. Only token counts, retrieval identifiers, and exact-slice coverage are measured — not LLM answer accuracy. Claude's tokenizer is not public; counts use OpenAI o200k (or a character estimate when Node is unavailable). JS/TS/Go/Rust symbol extraction is heuristic, not a full parser. A --max-tokens budget below the saved artifact-path cost is best-effort.

License

MIT © 2026 000jd. See LICENSE.