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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file contextual_engine-0.11.1.tar.gz.
File metadata
- Download URL: contextual_engine-0.11.1.tar.gz
- Upload date:
- Size: 2.1 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
181886d305f6f7f190a9fa75aa0b08aa9b51aefa3ec7fb9ea34e4134aa1c2444
|
|
| MD5 |
6f0f786bafe0798e7b353230a650a860
|
|
| BLAKE2b-256 |
e822281ceaca4ab225565912e9f22560a64ea8334f7efd7bb242994c4958e1ea
|
Provenance
The following attestation bundles were made for contextual_engine-0.11.1.tar.gz:
Publisher:
release.yml on aarjunm04/Contextual
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
contextual_engine-0.11.1.tar.gz -
Subject digest:
181886d305f6f7f190a9fa75aa0b08aa9b51aefa3ec7fb9ea34e4134aa1c2444 - Sigstore transparency entry: 2612445025
- Sigstore integration time:
-
Permalink:
aarjunm04/Contextual@bf0e9a3c2a42fa468927ed9073edd7fdd21c7a39 -
Branch / Tag:
refs/tags/t-0.11.1 - Owner: https://github.com/aarjunm04
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@bf0e9a3c2a42fa468927ed9073edd7fdd21c7a39 -
Trigger Event:
push
-
Statement type:
File details
Details for the file contextual_engine-0.11.1-py3-none-any.whl.
File metadata
- Download URL: contextual_engine-0.11.1-py3-none-any.whl
- Upload date:
- Size: 878.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
43a8a0d2e29695daa8f3079bc2a5cdc83d86614fe421015c9364e41ddd88f821
|
|
| MD5 |
ced5b8871eeab7a3bc882edf53f02323
|
|
| BLAKE2b-256 |
b7d8b2648ce8619c0bc2f0b75dbfcbcb5ae352bcb038abb433a1ed3b7fde74e3
|
Provenance
The following attestation bundles were made for contextual_engine-0.11.1-py3-none-any.whl:
Publisher:
release.yml on aarjunm04/Contextual
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
contextual_engine-0.11.1-py3-none-any.whl -
Subject digest:
43a8a0d2e29695daa8f3079bc2a5cdc83d86614fe421015c9364e41ddd88f821 - Sigstore transparency entry: 2612445085
- Sigstore integration time:
-
Permalink:
aarjunm04/Contextual@bf0e9a3c2a42fa468927ed9073edd7fdd21c7a39 -
Branch / Tag:
refs/tags/t-0.11.1 - Owner: https://github.com/aarjunm04
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@bf0e9a3c2a42fa468927ed9073edd7fdd21c7a39 -
Trigger Event:
push
-
Statement type:
