Contextual

Local-first temporal semantic code memory engine for AI tools

PyPI License Python

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

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.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for aarjunm04 from gravatar.com aarjunm04

Credits

Author: Contextual Contributors

License

Other/Proprietary License (BUSINESS SOURCE LICENSE 1.1 )

Requires

Python <3.15, >=3.11

Provides Extra

benchmark dev test

Tags

ai code-search developer-tools embeddings local-first mcp temporal

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

contextual_engine-1.0.0.tar.gz (2.1 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

contextual_engine-1.0.0-py3-none-any.whl (879.4 kB view details)

Uploaded Python 3

File details

Details for the file contextual_engine-1.0.0.tar.gz.

File metadata

  • Download URL: contextual_engine-1.0.0.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

Hashes for contextual_engine-1.0.0.tar.gz
Algorithm Hash digest
SHA256 734433a0d795058f896e90a3ecac3faacfeae7b62615db8727172206818746fa
MD5 cc3ab6a5dbbe1d49f3e6b41e5c223b53
BLAKE2b-256 352978ce951af024d9b38d4e7207863c2f68005af65b60c71e069aec3f31f7ee

See more details on using hashes here.

Provenance

The following attestation bundles were made for contextual_engine-1.0.0.tar.gz:

Publisher: release.yml on aarjunm04/Contextual

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file contextual_engine-1.0.0-py3-none-any.whl.

File metadata

File hashes

Hashes for contextual_engine-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 22998dbbfa07a0dc7bfc6d2d5a9cec5ef298c29e7796182f28daf40c04b0f29d
MD5 2869d98dcfe50b17226a7b7704173d95
BLAKE2b-256 2a6731e73052a7fc4831c7fb37f4e0d79289240fe533ba6100c48aed2aef6f8a

See more details on using hashes here.

Provenance

The following attestation bundles were made for contextual_engine-1.0.0-py3-none-any.whl:

Publisher: release.yml on aarjunm04/Contextual

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page