ContextAtlas

ContextAtlas

Stable, reusable, and observable code context infrastructure for AI agents

Hybrid Retrieval · Project Memory · MCP Server · Retrieval Observability

=20" />

简体中文 · Docs · First Use · Deployment · CLI · MCP

ContextAtlas is an open-source context infrastructure for AI coding agents — providing hybrid code retrieval, project memory, and retrieval observability as a CLI, MCP server, or embeddable library. It combines tree-sitter semantic chunking, LanceDB vector search, SQLite FTS5 full-text search, and token-aware context packing to deliver structured, high-quality code context to tools like Claude Code, Codex, and custom agent workflows.

Updates

• 2026-04-15: added git hook auto-maintenance with --quick health check (260x speedup), stale index cleanup CLI, and three-layer hook protection (debounce + quick mode + daily throttle).
• 2026-04-14: extracted 11 Memory MCP tools' business logic to application layer, completing three-layer architecture separation (CLI / MCP adapter → application → domain), and fixed all 31 TypeScript compilation errors.
• 2026-04-10: codebase-retrieval now includes the lightweight direct graph summary by default, with MCP metadata, tests, and changelog docs updated in sync.
• 2026-04-09: added churn / cost-aware index planning, moved long-term memory into dedicated tables + FTS5, and finished default-path hardening, threshold configuration, ops alert threshold alignment, and doc sync.
• 2026-04-08: added the embedding gateway, local caching and multi-upstream routing, plus Hugging Face integration and MCP context lifecycle tools.
• 2026-04-07: improved the indexing pipeline with lighter planning, snapshot copy reduction, queue observability, fallback hardening, and repeatable benchmarks.
• 2026-04-06: tightened the default user path, memory governance, and operational visibility to make first use, feedback loops, and health checks clearer.

Contents

• [Why ContextAtlas](#why-contextatlas)
• [Where it fits](#where-it-fits)
• [Core Capabilities](#core-capabilities)
• [Tech Stack](#tech-stack)
• [Installation](#installation)
• [Configuration](#configuration)
• [Quick Start](#quick-start)
• [Integration Modes](#integration-modes)
• [Architecture Overview](#architecture-overview)
• [Documentation](#documentation-map)
• [Friendly Links](#friendly-links)
• [License](#license)

ContextAtlas is not just a code search tool. It addresses a more practical engineering problem:

• can an agent find the right code faster in a large repository?
• can repository understanding be persisted instead of rediscovered every session?
• can retrieval, indexing, and memory quality be observed and improved over time?

If you are building Claude Code workflows, MCP clients, or custom agent systems, ContextAtlas provides a context infrastructure layer: retrieval, memory, context packing, and observability.

Why ContextAtlas

In real projects, agent failures are often not caused by a weak model. They come from weak context systems:

• the relevant code is not found
• the returned code is too fragmented and lacks surrounding context
• the same module has to be re-understood again and again
• indexes become stale, retrieval quality degrades, and token budgets get exhausted without clear signals

ContextAtlas turns this into a composable set of capabilities:

• Find: hybrid retrieval narrows down the relevant implementation
• Expand: graph expansion and token packing turn hits into usable local context
• Store: project memory, long-term memory, and a cross-project hub preserve knowledge
• Observe: health checks, telemetry, usage analysis, and alerts make the system diagnosable

Where it fits

• As a repository retrieval backend for coding agents
• As an MCP server for external clients that need code retrieval and memory tools
• As a local CLI / skill backend for scripts, CI, and workflow automation
• As a cross-project knowledge layer for reusable module knowledge and decision history

Core capabilities

| Capability | Description | |------|------| | Hybrid Retrieval | Vector recall + FTS lexical recall + RRF fusion + rerank | | Context Expansion | Local context expansion based on neighbors, breadcrumbs, and imports | | Token-aware Packing | Keeps the highest-value context inside a limited token budget | | Project Memory | Feature Memory, Decision Record, and Project Profile | | Long-term Memory | Rules, preferences, and external references that cannot be derived reliably from code | | Cross-project Hub | Reuse module memories, dependency chains, and relations across repositories | | Async Indexing | SQLite queue + daemon consumer + atomic snapshot switch | | Observability | Retrieval monitor, usage report, index health, memory health, and alert evaluation |

ContextAtlas decides what context to provide, not how the task should be executed. It does not handle agent reasoning, workflow orchestration, or business API actions.

Tech stack

• TypeScript / Node.js 20+
• Tree-sitter for semantic chunking
• SQLite + FTS5 for metadata, retrieval, queues, and memory hub storage
• LanceDB for vector storage
• Model Context Protocol SDK for MCP integration

Installation

npm install -g @codefromkarl/context-atlas

Product identity mapping:

• Repository: ContextAtlas
• npm package: @codefromkarl/context-atlas
• CLI command: contextatlas

Available commands:

• contextatlas
• cw (short alias)

The docs use contextatlas as the primary command name. cw remains as a compatibility alias.

Configuration

Initialize the config directory and example environment file first:

contextatlas init
# Choose your integration mode:
contextatlas setup:local --mode cli-skill   # Terminal + skill integration
# OR
contextatlas setup:local --mode mcp         # MCP client integration

Default config file location:

~/.contextatlas/.env

Minimum required configuration:

EMBEDDINGS_API_KEY=
EMBEDDINGS_BASE_URL=
EMBEDDINGS_MODEL=

RERANK_API_KEY=
RERANK_BASE_URL=
RERANK_MODEL=

Index update planning also supports these optional knobs:

INDEX_UPDATE_CHURN_THRESHOLD=0.35
INDEX_UPDATE_COST_RATIO_THRESHOLD=0.65
INDEX_UPDATE_MIN_FILES=8
INDEX_UPDATE_MIN_CHANGED_FILES=5

• INDEX_UPDATE_CHURN_THRESHOLD: when the changed-file ratio crosses this value, index:plan / index:update will favor full
• INDEX_UPDATE_COST_RATIO_THRESHOLD: triggers full when the estimated incremental cost is close to a full rebuild
• INDEX_UPDATE_MIN_FILES / INDEX_UPDATE_MIN_CHANGED_FILES: require both repo size and change size to clear a minimum bar before escalation is allowed

> init writes an editable example .env, including default SiliconFlow endpoints and recommended model settings. > setup:local --mode writes only the configuration files for the selected mode. See [First use guide](./docs/guides/first-use.md) for mode selection guidance. > After setup, run contextatlas health:full to verify index, memory, graph, contract, and MCP process health.

Quick start

If you are onboarding for the first time, start with the [First use guide](./docs/guides/first-use.md).

1) Confirm the default entry flow

contextatlas start /path/to/repo

2) Initialize and fill in API settings

contextatlas init
# edit ~/.contextatlas/.env

3) Index a repository

contextatlas index /path/to/repo

4) Run local retrieval

contextatlas search \
  --repo-path /path/to/repo \
  --information-request "How is the authentication flow implemented?"

5) Start the daemon (recommended)

contextatlas daemon start

6) Expose it as an MCP server

contextatlas mcp

> If you want MCP client integration, run contextatlas setup:local --mode mcp first.

Integration modes

1. As a local CLI / skill backend

Set up with contextatlas setup:local --mode cli-skill.

Useful for:

• custom agent skills
• shell workflows and CI scripts
• local debugging and retrieval analysis

Example:

# retrieval
contextatlas search --repo-path /path/to/repo --information-request "Where is the payment retry policy implemented?"

# project memory
contextatlas memory:find "search"
contextatlas decision:list

# health
contextatlas health:full

2. As an MCP server

Set up with contextatlas setup:local --mode mcp.

Use contextatlas setup:local --mode mcp --toolset retrieval-only when the client should only see read-only retrieval, graph, contract, and memory-reader tools.

Useful for:

• desktop clients that support MCP
• agent systems that need standard tool-based access to ContextAtlas capabilities

Claude Desktop configuration example:

{
  "mcpServers": {
    "contextatlas": {
      "command": "contextatlas",
      "args": ["mcp"]
    }
  }
}

ContextAtlas MCP tools cover:

• code retrieval
• project memory
• long-term memory
• cross-project hub operations
• auto-recording and memory suggestion flows

Architecture overview

Indexing:  Crawler / Scanner → Chunking → Indexing → Vector / SQLite Storage
Retrieval: Vector + FTS Recall → RRF → Rerank → Graph Expansion → Context Packing
Memory:    Project Memory / Long-term Memory / Hub → CLI / MCP Tools

ContextAtlas focuses on what context to provide, not how the task should be executed. For a fuller architecture explanation, see [repository positioning](./docs/architecture/repository-positioning.md) and [engineering positioning](./docs/architecture/harness-engineering.md).

Documentation map

| Document | Purpose | |------|------| | [2026-04-15 update summary](./docs/changelog/2026-04-15.md) | Quick health check, stale index cleanup, and git hook auto-maintenance | | [Docs index](./docs/README.md) | Unified entry for stable docs, plans, changelog, and archived delivery material | | [2026-04-10 update summary](./docs/changelog/2026-04-10.md) | Default-on graph context for codebase retrieval plus MCP/docs sync | | [First use guide](./docs/guides/first-use.md) | Fast onboarding path for the default contextatlas loop | | [2026-04-06 update summary](./docs/changelog/2026-04-06.md) | Summary of the new main path, memory governance, operations, release gate, and team metrics | | [2026-04-07 update summary](./docs/changelog/2026-04-07.md) | Summary of the seven indexing phases covering lightweight planning, snapshot copy reduction, health repair, observability, fallback hardening, storage trimming, and benchmarks | | [2026-04-09 update summary](./docs/changelog/2026-04-09.md) | Summary of index planning thresholds, long-term memory table split, and delivery sync | | [Deployment guide](./docs/guides/deployment.md) | Installation, deployment patterns, MCP integration, operations | | [CLI reference](./docs/reference/cli.md) | CLI commands, categories, and examples | | [MCP reference](./docs/reference/mcp.md) | MCP tools, parameters, and calling patterns | | [Project memory guide](./docs/project/project-memory.md) | Feature Memory, Decision Record, and Catalog routing | | [Latest delivery bundle](./docs/archive/deliveries/2026-04-09-index-and-memory/delivery-bundle.md) | Bundled handoff package for the latest verified delivery | | [Repository positioning](./docs/architecture/repository-positioning.md) | Repository role, design thinking, and system boundaries | | [Engineering positioning](./docs/architecture/harness-engineering.md) | Where ContextAtlas fits in harness engineering | | [Product roadmap](./docs/product/roadmap.md) | Future versions and product direction |

Contributing

Ways to improve ContextAtlas:

• open issues for bugs or documentation gaps
• submit PRs for retrieval, memory, monitoring, or documentation improvements
• contribute real-world usage patterns, deployment notes, and benchmark data
• improve README, CLI docs, and MCP examples

Before submitting code, it helps to:

1. run pnpm build and make sure the repo still builds
2. keep command examples, README, and docs aligned with the implementation
3. update functionality, documentation, and operational notes together when possible

Development

pnpm build
pnpm build:release
pnpm dev
node dist/index.js

Friendly links

https://linux.do/

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: codefromkarl
• Source: codefromkarl/ContextAtlas
• License: MIT
• Homepage: https://github.com/codefromkarl/ContextAtlas/tree/main/docs

Install and usage instructions live in the source repository linked above.