Skip to main content

Lodestar

Lodestar is a local-first repository context tool for LLM agents. It builds a per-repo index inside /.lodestar/, returns bounded context packs, and keeps agent workflows grounded in summaries and evidence instead of large raw file dumps.

Install

pip install lodestar-context                # primary install
pip install "lodestar-context[parsers]"     # add tree-sitter parsers
pip install "lodestar-context[embeddings]"  # add sentence-transformers dense retrieval

The package ships on PyPI as lodestar-context; the import path remains lodestar. The lodestar and lodestar-mcp console scripts are available after install.

Current scope

  • repository scanning and role detection
  • per-repo SQLite index at /.lodestar/index.db
  • incremental refresh by file hash
  • repo overview generation
  • subsystem summaries
  • symbol extraction — heuristic baseline + optional tree-sitter for Python, JS, TS, Go, Rust, Java, Ruby, PHP (pip install "lodestar-context[parsers]")
  • relation graph between files and symbols
  • search, retrieve, explain, remember, pack, timeline, capture, locate-symbol primitives
  • hybrid ranking — FTS5 BM25 (porter-stemmed) + exact token matching + cosine-style overlap + role-based boost (source ×1.3, documentation ×0.7) + optional dense semantic similarity
  • symbol-aware ranking v2 — kind boosts (class/function > section), graph-proximity (results connected via relations get a bonus), and file-recency multipliers. Gate with "ranking_v2": false in /.lodestar/config.json to fall back to v1.
  • optional semantic retrieval via sentence-transformers embeddings (pip install "lodestar-context[embeddings]") — covers files, symbols, subsystems and memories
  • memory store with evidence-hash staleness detection, chunk-level evidence refs, last_validated_at freshness tracking, aggressive stale suppression, and dense memory recall
  • query result caching (retrieve and search)
  • repo-local configuration via /.lodestar/config.json
  • elapsed_ms on index, refresh, search, retrieve, pack, timeline, and explain responses
  • eval command — fixture-based precision@K benchmarking with --fixture, --top-k, per-query found_refs/missing_refs, and avg_precision
  • MCP stdio server with parse-error recovery, result.isError tool errors, -32602 invalid-param responses, and stderr protocol logging
  • CLI commands

Storage layout

Every indexed repository gets a local state directory:

/.lodestar/
  index.db
  config.json   (optional — repo-local policy overrides)
  cache/
  logs/
  state/
  version.json

Repo-local configuration

Create /.lodestar/config.json in any indexed repository to override indexing and retrieval behaviour without changing Lodestar itself.

{
  "extra_excludes": ["bootstrap/cache", "public/build"],
  "include_overrides": ["bootstrap/app.php"],
  "role_overrides": {
    "app/Models/*.php": "source",
    "config/*.php": "config"
  },
  "parser_overrides": {
    "php": false
  },
  "retrieval_defaults": {
    "budget_tokens": 2400,
    "limit": 12
  }
}

All keys are optional. Missing or malformed config silently falls back to global defaults.

Key Type Effect
extra_excludes string[] Additional directory names to skip during scanning (same semantics as built-in EXCLUDED_DIRS)
include_overrides string[] Glob patterns (relative path) that bypass all exclusion rules
role_overrides {glob: role} Override the inferred role for paths matching a glob, applied before built-in heuristics
parser_overrides {language: bool} Set false to disable symbol extraction for a language (file is still indexed, just without symbols)
retrieval_defaults {budget_tokens?, limit?} Default token budget and result limit when the caller does not specify them explicitly

CLI

lodestar index /path/to/repo
lodestar refresh /path/to/repo
lodestar overview /path/to/repo
lodestar search /path/to/repo "auth middleware"
lodestar retrieve /path/to/repo "where is auth enforced?" --budget 1800
lodestar pack /path/to/repo "where is auth enforced?" --budget 1800
lodestar explain /path/to/repo "config loading"
lodestar remember /path/to/repo "auth path" "Authentication starts in middleware." --evidence src/auth.py
lodestar timeline /path/to/repo --since last_index
lodestar capture /path/to/repo --from json --source memories.json --commit
lodestar capture /path/to/repo --from claude-jsonl --source ~/.claude/projects/<slug>/<session>.jsonl
lodestar locate-symbol /path/to/repo LodestarService.search
lodestar eval /path/to/repo
lodestar eval /path/to/repo --queries "auth middleware" "config loading" "database schema"
lodestar eval /path/to/repo --fixture /path/to/fixtures.json --top-k 10

MCP

After pip install lodestar-context, run the stdio server with:

lodestar-mcp

Example Claude Desktop config:

{
  "mcpServers": {
    "lodestar": {
      "command": "lodestar-mcp"
    }
  }
}

Development (running from source)

If you are running from this repository without installing the package, start the MCP server like this:

PYTHONPATH=src python3 -m lodestar.mcp_server

You can also use the included wrapper script:

./scripts/lodestar-mcp-stdio

Claude Desktop config file on macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

After restarting Claude Desktop, call Lodestar tools with the target repository path in repo_root, for example:

{
  "repo_root": "/path/to/your/project"
}

Supported tool names:

  • project.index
  • project.refresh
  • project.overview
  • project.search
  • project.retrieve
  • project.pack
  • project.explain
  • project.remember
  • project.timeline
  • project.capture
  • project.locate_symbol_range
  • project.find_usages

Notes

  • The baseline is intentionally standard-library-first so it can run without extra dependencies.
  • Search uses hybrid ranking: FTS5 BM25 (porter-stemmed) + exact token matching + cosine-style term overlap + role-based multipliers + optional dense semantic similarity + graph-neighbor expansion in retrieve.
  • Install pip install "lodestar-context[parsers]" to enable tree-sitter symbol extraction for Python, JS, TS, Go, Rust, Java, Ruby, and PHP. Without it, Lodestar falls back to heuristic regex parsing. Tree-sitter gives accurate ClassName.method naming and proper nested scope handling.
  • Install pip install "lodestar-context[embeddings]" to enable dense semantic retrieval. This embeds file, symbol, and subsystem summaries (and memory bodies) using all-MiniLM-L6-v2 (via sentence-transformers) and blends cosine similarity scores into every search, retrieve, and memory-recall call. Useful for natural-language queries that don't share vocabulary with identifiers in the code.
  • Evidence refs passed to remember support file:, symbol:, and chunk: prefixes for increasingly precise staleness detection. Stale memories are suppressed in retrieval unless no fresh memories match the query.
  • The MCP server logs protocol-level failures (framing errors, unknown methods) to stderr. Tool execution errors are returned as result.isError: true per the MCP spec, not as JSON-RPC error objects.

Metadata

Release files for lodestar-context 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lodestar-context 0.2.1
File Size Uploaded Provenance Actions
lodestar_context-0.2.1.tar.gz 46.4 kB With provenance Details for lodestar_context-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lodestar-context 0.2.1
File Interpreter ABI Platform Actions
lodestar_context-0.2.1-py3-none-any.whl Python 3 none any Details for lodestar_context-0.2.1-py3-none-any.whl

Total release size: 93.0 kB

Release files / lodestar_context-0.2.1.tar.gz

Download URL lodestar_context-0.2.1.tar.gz
Size 46.4 kB
Tags Source
SHA-256 checksum
How to use checksums
f902db3a6fdc5f638c46c0233d8fda203eab13ea77818aab00204e7bf202b054
BLAKE2b-256 checksum
How to use checksums
9132eaf47c3ba96761999f4d83b500c0f12cde7f62b104c123b48380c0dc59a2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 16, 2026.

Transparency log

Release files / lodestar_context-0.2.1-py3-none-any.whl

Download URL lodestar_context-0.2.1-py3-none-any.whl
Size 46.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5aaa0330b5e12293aff856fe7b8dad02797cf950a4f8e937a530abb7aa8c1ae0
BLAKE2b-256 checksum
How to use checksums
fad78fa32f462eaf07e90e1b2e8b833e056c5fa8cd822bbaa70cde7e50461d7b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 16, 2026.

Transparency log

Security for lodestar-context 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for lodestar_context-0.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page