contextual-engine

Contextual

Local-first temporal semantic code memory engine for AI tools

What is Contextual?

Contextual transforms code repositories into queryable, time-aware knowledge structures. Unlike traditional RAG systems that treat code as static documents, Contextual maintains full temporal awareness, structural understanding, and semantic relationships across your entire codebase.

The Four-Way Wedge:

• Local-first - Embedded storage, no cloud dependency
• Bitemporal - Tracks when facts were true AND when you learned them
• Code-aware - AST parsing, not just text chunking
• Tool-agnostic - MCP integration works with any AI IDE/chat client

Features

• Hybrid Search - BM25 + vector embeddings with RRF fusion
• Temporal Queries - Time-travel through your codebase history
• Knowledge Graph - Entity-relationship triples with CHA/RTA structural resolution and recursive traversal
• Docs Write - AI-powered documentation updates with two-phase commit
• Incremental Indexing - Git-aware change detection, BLAKE3 content hashing
• Multi-Workspace MCP Daemon - One daemon serves a registry of projects; auto-configures Claude Desktop, VS Code Copilot, and Codex

Installation

# Recommended — persistent isolated environment
uv tool install contextual-engine

# Alternative
pipx install contextual-engine

Quick Start

# One-time global setup (downloads the embedding model)
contextual setup

# Initialize a project
cd /path/to/repo
contextual init .

# Index the codebase
contextual index .

# Auto-configure an AI client (writes MCP config for you)
contextual client claude    # or: vscode, codex

Search, temporal queries, and graph traversal are exposed as MCP tools, not CLI subcommands — once a client is wired up, ask it a codebase question directly. See MCP Tools for the full tool list.

MCP Integration

contextual client <name> writes this for you. To configure manually, or for a client it doesn't yet support:

{
  "mcpServers": {
    "contextual": {
      "command": "contextual",
      "args": ["mcp", "start"]
    }
  }
}

The daemon serves every workspace registered via contextual workspace add — no separate server process per project. Manage it directly with contextual mcp start|stop|restart|status|logs.

Documentation

• Architecture - System design and implementation
• Database - LanceDB schema reference
• SaaS Spec - Multi-tenancy, licensing, auth
• MCP Tools - Tool contracts and API

License

Business Source License 1.1 (BUSL-1.1) — see LICENSE for the full terms, including the Additional Use Grant and the Change Date / Change License.