Keep context work proportional.

Measure the bottleneck first

Determine whether the delay is a first index build, a provider request, a large read, an embedding operation or a slow external command. These need different fixes.

lean-ctx status
lean-ctx doctor
lean-ctx index status

Warm-cache behavior is not representative of a fresh project. Record both when assessing responsiveness.

Limit the project surface

Respect ignore rules and exclude generated dependencies, build artifacts and unrelated repositories. A correct project root reduces indexing work and irrelevant candidates at the same time.

The schema’s graph_index_max_files default is 15000. A value of zero means unlimited, not “disabled.” Choose a bound appropriate to the repository.

Tune one resource at a time

Review max_index_threads, bm25_max_cache_mb, max_disk_mb and the memory lifecycle settings. max_ram_percent is a soft runtime control; it is not a hard OS-enforced cap.

Embedding models, dimensions and first-use downloads have their own cost. Check the actual embedding backend and provisioning state rather than assuming that semantic search always uses the same path.

Bound long-running processes

Two kinds of LeanCTX process can stay alive for days: the stdio MCP server that each agent host starts, and the shared background daemon that builds indexes for every session on the machine (lean-ctx daemon status). Each has its own memory target besides max_ram_percent, and the lower of the two applies.

Setting	Environment override	Applies to	Default
mcp_max_rss_mb	LEAN_CTX_MCP_MAX_RSS_MB	each stdio MCP server	512 MB
daemon_max_rss_mb	LEAN_CTX_DAEMON_MAX_RSS_MB	the background daemon	2048 MB

0 keeps only the percentage target. Above its target, a process evicts caches and resident indexes and returns the freed memory to the operating system; everything reloads on demand. A target close to what a large repository needs while it is being indexed makes builds stop early under memory pressure. Lower daemon_max_rss_mb in steps, and confirm with lean-ctx index status that builds still complete.

The daemon keeps search indexes in memory for at most eight project roots, so many repositories or worktrees do not add up. lean-ctx daemon restart returns everything it holds at once.

On macOS, compare against the “Memory” column in Activity Monitor (physical footprint). That is the figure the guardian measures; resident size leaves out compressed memory.

Avoid unnecessary background work

Autonomy, preload, consolidation and experimental learning settings are distinct. Enable only the behavior you need and compare before/after resource usage under a representative task.

Do not stop the user’s installed daemon merely to compile or inspect source.

Verify useful results

A faster scan that misses relevant files is not an improvement. After tuning, repeat a known search, a focused read and a recovery operation. Inspect both latency and output completeness.

See configuration for actual field names and captured defaults.

Sources & versions4 references · Reviewed 17 Sept 2026

• mod.rsrust/src/core/config/schema/mod.rsReviewed checkout
• 14-performance-tuning.mddocs/reference/14-performance-tuning.mdReviewed checkout
• memory_guard.rsrust/src/core/memory_guard.rsReviewed checkout
• search_index.rsrust/src/core/search_index.rsReviewed checkout

Core checkout

0ce2207ee4

Reviewed runtime

3.10.2

SDK release

1.1.0

Separate baselines for source, CLI/configuration and SDK contracts. Review does not certify every platform or integration.

Versions & compatibility