contextual-engine 0.1.0

Temporal-first local code memory for AI tools via MCP

Contextual

Temporal-first local code memory for AI tools via MCP.

Contextual is a local-first, bi-temporal, code-aware semantic context engine that gives AI coding assistants persistent, accurate memory of your codebase — across tools, across time, without cloud dependencies.

The Problem

Every AI coding tool today suffers from the same fundamental flaw: context amnesia. Claude Code forgets what you discussed yesterday. Cursor re-indexes from scratch. Copilot has no memory of architectural decisions. Your AI assistant hallucinates function signatures that changed three commits ago because it has no concept of when things were true.

The result: wasted tokens, hallucinated code, repeated explanations, and lost architectural intent.

The Solution

Contextual maintains a bi-temporal knowledge graph of your codebase — tracking not just what is true, but when it became true and when you learned it was true. It exposes this knowledge through the Model Context Protocol (MCP), making it available to every AI tool in your stack simultaneously.

Developer writes code → Contextual indexes changes (tree-sitter + git blame)
                       → Builds temporal knowledge graph (SQLite bi-temporal)
                       → Embeds semantically (jina-v2-base-code + BM25)
                       → Serves context via MCP to any AI tool

Key Features

• Temporal-First Memory — Every fact carries four timestamps (valid_at, invalid_at, created_at, expired_at). Ask "what was the API signature last Tuesday?" and get the right answer.
• Tool-Agnostic via MCP — Works with Claude Desktop, Claude Code, Cursor, VS Code Copilot, Gemini CLI, Windsurf, Zed, and any MCP-compatible client. One index, every tool.
• Local-First, Private by Design — All data stays on your machine. No cloud, no telemetry, no API keys required. Runs on 8GB RAM laptops.
• Hybrid Code Search — Combines dense semantic embeddings (jina-v2-base-code) with code-aware BM25 (camelCase/snake_case splitting) via Reciprocal Rank Fusion, reranked by a cross-encoder.
• Git-Native Indexing — Incremental indexing via post-commit hooks. Blame-based temporal attribution. Force-push and rebase aware.
• 7 Languages at Launch — Python, TypeScript, JavaScript, Go, Java, Rust, C# plus config formats (JSON, YAML, TOML, Dockerfile, Markdown).

Quick Start

# Install
uvx contextual

# Index your codebase
contextual index .

# Search
contextual search "authentication middleware"

# Temporal recall
contextual recall "UserService" --as-of "2026-05-01"

# Start MCP server for your IDE
contextual serve --stdio

IDE Integration

Run contextual setup <ide> to auto-configure any supported IDE, or configure manually:

Claude Desktop / Cursor / Windsurf

{
  "mcpServers": {
    "contextual": {
      "command": "uvx",
      "args": ["contextual", "serve", "--stdio"]
    }
  }
}

VS Code Copilot

{
  "mcp.servers": {
    "contextual": {
      "type": "stdio",
      "command": "uvx",
      "args": ["contextual", "serve", "--stdio"]
    }
  }
}

Claude Code

claude mcp add contextual -- uvx contextual serve --stdio

Gemini CLI

{
  "mcpServers": {
    "contextual": {
      "command": "uvx",
      "args": ["contextual", "serve", "--stdio"]
    }
  }
}

MCP Tools

Tool	Description
index	Index a codebase at a given path
search	Hybrid semantic + keyword code search
recall	Temporal recall — what did we know about X at time T?
capture_decision	Record an architectural decision
freshness	Check how stale the current index is
status	System health and statistics
forget	Invalidate a fact (never deletes — marks as expired)
timeline	Full temporal history of any entity

Requirements

• Python 3.12+
• macOS, Linux, or Windows
• 8GB RAM minimum (16GB recommended)
• Git repository (full history recommended)

Documentation

• Architecture — System design and data flow
• Technical Specification — Complete implementation reference
• Roadmap — 30-day build plan
• ADRs — Architectural Decision Records
• Delegation Playbook — AI team task guide

License

Business Source License 1.1 — Change License: Apache 2.0, Change Date: 4 years from each release.

Acknowledgements

Built with FastMCP, LanceDB, tree-sitter, pygit2, fastembed, and tantivy-py. Temporal model inspired by Graphiti/Zep and Snodgrass's bi-temporal formalism.