Metadata-Version: 2.5
Name: contextual-engine
Version: 1.0.3
Summary: Temporal-first local code memory for AI tools via MCP
Project-URL: Homepage, https://contextuallabs.dev
Project-URL: Documentation, https://contextuallabs.dev/docs
Project-URL: Repository, https://github.com/Contextual-Laboratories/Contextual-Labs/issues
Project-URL: Changelog, https://contextuallabs.dev/changelog
Author: Contextual Contributors
License: PROPRIETARY SOFTWARE LICENSE
        
        ---
        
        Copyright (c) 2026 Aarjun Mahule. All Rights Reserved.
        
        Product: CONTEXTUAL
        Licensor: Aarjun Mahule
        Contact: aarjun.mahule23@gmail.com
        
        ---
        
        1. No Rights Granted By Default
        
        This software and its accompanying source code (the "Software") are the
        proprietary and confidential property of the Licensor. All rights, title,
        and interest in and to the Software — including all copyright, trade
        secret, and other intellectual property rights — are and remain the
        exclusive property of the Licensor.
        
        No right, license, or permission is granted to any person to use, copy,
        modify, merge, publish, distribute, sublicense, reverse-engineer, or
        create derivative works of the Software, in whole or in part, except as
        expressly authorized in writing by the Licensor or under the terms of a
        separate, active Commercial License Agreement / Terms of Service between
        the Licensor and the user (available at the Licensor's website).
        
        2. Authorized Use
        
        Use of the Software — including via a paid subscription, a commercial
        license agreement, or any officially distributed build or package — is
        governed exclusively by the Commercial License Agreement / Terms of
        Service accompanying that use, not by this file. Where those terms grant
        usage rights, they control; this file grants none on its own.
        
        3. No Open-Source Obligation
        
        This is not an open-source license. The Software is not, and will not
        become, licensed under any open-source or source-available license at
        any future date. There is no change date, no automatic relicensing, and
        no conversion to a permissive or copyleft license.
        
        4. Trademarks
        
        This License does not grant any rights to use the Licensor's trademarks,
        service marks, trade names, or logos, except as required for reasonable
        and customary use in accurately describing the origin of the Software.
        
        5. Disclaimer of Warranty
        
        TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE SOFTWARE IS PROVIDED
        ON AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND
        CONDITIONS, EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION)
        WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
        NON-INFRINGEMENT, AND TITLE.
        
        6. Limitation of Liability
        
        TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL
        THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
        WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
        OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
        DEALINGS IN THE SOFTWARE.
        
        7. Termination
        
        Any use of the Software outside the scope expressly authorized under
        an active Commercial License Agreement / Terms of Service is unlicensed
        and automatically unauthorized; the Licensor reserves all rights and
        remedies available at law and in equity in response to such use.
        
        8. Governing Law
        
        This License shall be governed by and construed in accordance with the
        laws of the Republic of India, without regard to conflict of law
        principles.
        
        ---
License-File: LICENSE
Keywords: ai,code-search,developer-tools,embeddings,local-first,mcp,temporal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Text Processing :: Indexing
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.11
Requires-Dist: blake3>=0.4.1
Requires-Dist: datasketch<2,>=1.6.4
Requires-Dist: dulwich>=0.21
Requires-Dist: fastembed>=0.4.2
Requires-Dist: fastmcp<4,>=3.2
Requires-Dist: gcf-python>=2.2.0
Requires-Dist: httpx[http2]>=0.27.0
Requires-Dist: huggingface-hub>=0.23
Requires-Dist: lancedb<0.31,>=0.26
Requires-Dist: licensing>=0.54
Requires-Dist: numpy>=1.26
Requires-Dist: opentelemetry-api>=1.24.0
Requires-Dist: opentelemetry-sdk>=1.24.0
Requires-Dist: pathspec>=0.10
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyarrow>=14.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyobjc-framework-localauthentication>=10.0; sys_platform == 'darwin'
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: setproctitle>=1.3.0
Requires-Dist: simsimd<6,>=3.9
Requires-Dist: sqlglot>=20.0
Requires-Dist: starlette>=0.37
Requires-Dist: structlog>=25.4
Requires-Dist: tenacity>=8.0
Requires-Dist: tiktoken>=0.5
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tree-sitter-language-pack==1.9.0
Requires-Dist: typer<1.0,>=0.9
Requires-Dist: uvicorn>=0.27
Requires-Dist: watchdog>=4.0
Requires-Dist: winsdk>=1.0.0b1; sys_platform == 'win32'
Provides-Extra: benchmark
Requires-Dist: coir-eval; extra == 'benchmark'
Requires-Dist: ranx>=0.3; extra == 'benchmark'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: cyclonedx-bom>=7.3.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pip-licenses>=5.5.5; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: otlp
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.24.0; extra == 'otlp'
Provides-Extra: test
Requires-Dist: anyio[trio]>=4.3.0; extra == 'test'
Requires-Dist: freezegun>=1.5.0; extra == 'test'
Requires-Dist: hypothesis>=6.100.0; extra == 'test'
Requires-Dist: polyfactory>=2.16.0; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'test'
Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
Requires-Dist: pytest-timeout>=2.3.0; extra == 'test'
Requires-Dist: pytest-xdist>=3.5.0; extra == 'test'
Requires-Dist: pytest>=8.3.0; extra == 'test'
Requires-Dist: pyyaml>=6.0; extra == 'test'
Requires-Dist: respx>=0.21.0; extra == 'test'
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.Contextual-Laboratories/contextual -->
# Contextual

**Local-first temporal semantic code memory engine for AI tools**

[![PyPI](https://img.shields.io/pypi/v/contextual-engine)](https://pypi.org/project/contextual-engine/)
[![License](https://img.shields.io/badge/license-Proprietary-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)

## 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

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

# Alternative
pipx install contextual-engine
```

## Quick Start

```bash
# 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](docs/MCP_TOOLS.md) 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:

```json
{
  "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](docs/ARCHITECTURE.md) - System design and implementation
- [Database](docs/DATABASE.md) - LanceDB schema reference
- [MCP Tools](docs/MCP_TOOLS.md) - Tool contracts and API

## License

Proprietary — All Rights Reserved. See [LICENSE](LICENSE) for the full terms.
Contextual is closed-source and is not, and will not become, open source.
Commercial use is governed by the Commercial License Agreement / Terms of
Service accompanying a paid subscription, not by this file alone.
