code-memory 0.1.0__py3-none-any.whl

.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run linting
+        run: uv run ruff check .
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --tb=short
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        run: uv publish --token ${{ secrets.PYPI_TOKEN }}

.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Required for PyPI trusted publishing
+      contents: read
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          
+      # uv python install ensures the required python version is available
+      - name: Set up Python
+        run: uv python install
+        
+      - name: Build package
+        run: uv build
+        
+      - name: Publish to PyPI
+        run: uv publish

.gitignore

@@ -0,0 +1,40 @@
+# ── Python ─────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# ── Virtual environments ──────────────────────────────────────────────
+.venv/
+venv/
+ENV/
+
+# ── SQLite databases ─────────────────────────────────────────────────
+*.db
+*.db-shm
+*.db-wal
+*.db-journal
+*.sqlite
+*.sqlite3
+
+# ── IDE ───────────────────────────────────────────────────────────────
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# ── OS ────────────────────────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+
+# ── Testing / Coverage ───────────────────────────────────────────────
+.pytest_cache/
+.coverage
+htmlcov/
+
+# ── uv lock (keep in repo) ───────────────────────────────────────────
+# uv.lock is committed intentionally

.python-version

@@ -0,0 +1 @@
+3.13

CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-02-22
+
+### Added
+- Initial release
+- `search_code` tool with hybrid retrieval (BM25 + vector + RRF fusion)
+  - Find symbol definitions with semantic search
+  - Find cross-references to symbols
+  - Get file structure (all symbols in a file)
+- `search_docs` tool for documentation search
+  - Index markdown files and READMEs
+  - Extract docstrings from code symbols
+  - Hybrid search over documentation chunks
+- `search_history` tool for Git history search
+  - Search commit messages
+  - Get file history with rename tracking
+  - Run git blame with line range support
+  - Get detailed commit information
+- `index_codebase` tool for code and documentation indexing
+  - Multi-language AST parsing with tree-sitter
+  - Supports Python, JavaScript/TypeScript, Java, Kotlin, Go, Rust, C/C++, Ruby
+  - Incremental indexing (skips unchanged files)
+  - Generates embeddings for semantic search
+- Production hardening
+  - Structured error handling with custom exceptions
+  - Input validation with clear error messages
+  - Configurable logging via `CODE_MEMORY_LOG_LEVEL` environment variable
+  - CI/CD with GitHub Actions
+  - Test suite with pytest
+
+### Dependencies
+- mcp[cli] - Model Context Protocol server
+- sqlite-vec - Vector search extension for SQLite
+- sentence-transformers - Local embedding model (all-MiniLM-L6-v2)
+- tree-sitter + language packages - Multi-language AST parsing
+- gitpython - Git operations
+- markdown-it-py - Markdown parsing

CONTRIBUTING.md

@@ -0,0 +1,133 @@
+# Contributing to code-memory
+
+Thank you for your interest in contributing to code-memory! This document provides guidelines and instructions for contributing.
+
+## Development Setup
+
+### Prerequisites
+
+- Python >= 3.13
+- [uv](https://docs.astral.sh/uv/) package manager
+
+### Clone and Install
+
+```bash
+# Clone the repository
+git clone https://github.com/kapillamba4/code-memory.git
+cd code-memory
+
+# Install dependencies (including dev dependencies)
+uv sync --all-extras
+```
+
+### Run the Server
+
+```bash
+# Run the MCP server
+uv run mcp run server.py
+
+# Run with MCP Inspector for debugging
+uv run mcp dev server.py
+```
+
+## Development Workflow
+
+### Running Tests
+
+```bash
+# Run all tests
+uv run pytest tests/ -v
+
+# Run with coverage
+uv run pytest tests/ -v --cov --cov-report=term-missing
+```
+
+### Linting and Formatting
+
+```bash
+# Run ruff linter
+uv run ruff check .
+
+# Run ruff formatter
+uv run ruff format .
+
+# Run type checking
+uv run mypy .
+```
+
+### Building
+
+```bash
+# Build the package
+uv build
+```
+
+## Code Style
+
+- Follow [PEP 8](https://peps.python.org/pep-0008/) conventions
+- Maximum line length is 100 characters
+- Use type hints for function parameters and return types
+- Write docstrings for public functions and classes
+
+## Project Structure
+
+```
+code-memory/
+├── server.py          # MCP server entry point
+├── db.py              # SQLite database layer
+├── parser.py          # Tree-sitter code parser
+├── doc_parser.py      # Markdown documentation parser
+├── queries.py         # Hybrid retrieval query layer
+├── git_search.py      # Git history search module
+├── errors.py          # Custom exception hierarchy
+├── validation.py      # Input validation functions
+├── logging_config.py  # Structured logging configuration
+├── tests/             # Test suite
+├── prompts/           # Milestone prompt files
+└── pyproject.toml     # Project configuration
+```
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests and linting (`uv run pytest && uv run ruff check .`)
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+### PR Guidelines
+
+- Include a clear description of the changes
+- Reference any related issues
+- Ensure all tests pass
+- Add tests for new functionality
+- Update documentation if needed
+
+## Adding New Features
+
+### Adding a New Tool
+
+1. Add the tool function in `server.py` with the `@mcp.tool()` decorator
+2. Add input validation using functions from `validation.py`
+3. Wrap the implementation in error handling
+4. Add logging using `ToolLogger`
+5. Write tests in `tests/test_tools.py`
+
+### Adding a New Language Parser
+
+1. Add the tree-sitter language package to `pyproject.toml`
+2. Update the language registry in `parser.py`
+3. Add node-type mappings for the new language
+4. Write tests for the new language
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CODE_MEMORY_LOG_LEVEL` | Logging verbosity (DEBUG, INFO, WARNING, ERROR) | INFO |
+
+## License
+
+By contributing to code-memory, you agree that your contributions will be licensed under the MIT License.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kapil Lamba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS 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.

Makefile

@@ -0,0 +1,33 @@
+.PHONY: run dev inspect lint format test clean help
+
+# ── Server ─────────────────────────────────────────────────────────────
+run: ## Run the MCP server (stdio transport)
+	uv run mcp run server.py
+
+dev: ## Run with MCP Inspector for interactive debugging
+	uv run mcp dev server.py
+
+# ── Code Quality ───────────────────────────────────────────────────────
+lint: ## Run ruff linter
+	uv run ruff check .
+
+format: ## Auto-format with ruff
+	uv run ruff format .
+
+# ── Testing ────────────────────────────────────────────────────────────
+test: ## Run test suite
+	uv run pytest -v
+
+# ── Housekeeping ───────────────────────────────────────────────────────
+clean: ## Remove caches and build artifacts
+	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
+	rm -rf dist/ build/
+
+# ── Help ───────────────────────────────────────────────────────────────
+help: ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'
+
+.DEFAULT_GOAL := help

PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: code-memory
+Version: 0.1.0
+Summary: A deterministic, high-precision code intelligence MCP server
+Project-URL: Homepage, https://github.com/kapillamba4/code-memory
+Project-URL: Documentation, https://github.com/kapillamba4/code-memory#readme
+Project-URL: Repository, https://github.com/kapillamba4/code-memory.git
+Project-URL: Issues, https://github.com/kapillamba4/code-memory/issues
+Author-email: Kapil Lambert <kapillamba4@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Requires-Dist: gitpython>=3.1.46
+Requires-Dist: markdown-it-py>=4.0.0
+Requires-Dist: mcp[cli]>=1.26.0
+Requires-Dist: sentence-transformers>=5.2.3
+Requires-Dist: sqlite-vec>=0.1.6
+Requires-Dist: tree-sitter-c>=0.24.1
+Requires-Dist: tree-sitter-cpp>=0.23.4
+Requires-Dist: tree-sitter-go>=0.25.0
+Requires-Dist: tree-sitter-java>=0.23.5
+Requires-Dist: tree-sitter-javascript>=0.25.0
+Requires-Dist: tree-sitter-kotlin>=1.1.0
+Requires-Dist: tree-sitter-python>=0.25.0
+Requires-Dist: tree-sitter-ruby>=0.23.1
+Requires-Dist: tree-sitter-rust>=0.24.0
+Requires-Dist: tree-sitter-typescript>=0.23.2
+Requires-Dist: tree-sitter>=0.25.2
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# code-memory
+
+A deterministic, high-precision **code intelligence layer** exposed as a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server.
+
+`code-memory` gives your AI coding assistant structured access to your codebase through three focused pathways — eliminating context-window bloat and vague "search everything" queries.
+
+## Architecture: Progressive Disclosure
+
+Instead of a single monolithic search, `code-memory` routes queries through **three purpose-built tools**:
+
+| Question Type | Tool | Data Source |
+|---|---|---|
+| **"Where / What / How?"** — find definitions, references, structure, semantic search | `search_code` | BM25 + Dense Vector (SQLite vec) |
+| **"Architecture / Patterns"** — understand architecture, explain workflows | `search_docs` | Semantic / Fuzzy |
+| **"Who / Why?"** — debug regressions, understand intent | `search_history` | Git + BM25 + Dense Vector (SQLite vec) |
+| **"Setup / Prepare"** — index parsing & embedding generation | `index_codebase` | AST Parser + `sentence-transformers` |
+
+This forces the LLM to pick the *right retrieval strategy* before any data is fetched.
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+# Install with pip
+pip install code-memory
+
+# Or with uvx (for MCP hosts)
+uvx code-memory
+```
+
+### From Source
+
+```bash
+# Clone the repo
+git clone https://github.com/kapillamba4/code-memory.git
+cd code-memory
+
+# Install dependencies
+uv sync
+
+# Run the MCP server (stdio transport)
+uv run mcp run server.py
+```
+
+## Quickstart
+
+### Prerequisites
+
+- Python ≥ 3.13
+- [`uv`](https://docs.astral.sh/uv/) package manager (recommended) or pip
+
+### Install & Run
+
+```bash
+# Install from PyPI
+pip install code-memory
+
+# Or run directly with uvx
+uvx code-memory
+```
+
+### Development
+
+```bash
+# Run with the MCP Inspector for interactive debugging
+uv run mcp dev server.py
+
+# Run tests
+uv run pytest tests/ -v
+
+# Lint and format
+uv run ruff check .
+uv run ruff format .
+
+# Build package
+uv build
+```
+
+## Configure Your MCP Host
+
+### Gemini CLI / Gemini Code Assist
+
+Add to your MCP settings (e.g. `~/.gemini/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "code-memory": {
+      "command": "uvx",
+      "args": ["code-memory"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "code-memory": {
+      "command": "uvx",
+      "args": ["code-memory"]
+    }
+  }
+}
+```
+
+### VS Code (Copilot / Continue)
+
+Add to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "code-memory": {
+      "command": "uvx",
+      "args": ["code-memory"]
+    }
+  }
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CODE_MEMORY_LOG_LEVEL` | Logging verbosity (DEBUG, INFO, WARNING, ERROR) | INFO |
+
+Example:
+```bash
+CODE_MEMORY_LOG_LEVEL=DEBUG uvx code-memory
+```
+
+## Tools
+
+### `index_codebase`
+
+Indexes or re-indexes source files and documentation in the given directory. Run this before using `search_code` or `search_docs` to ensure the database is up to date. Uses tree-sitter for language-agnostic structural extraction and generates dense vector embeddings using `sentence-transformers` (runs locally, in-process) for semantic search.
+
+```
+index_codebase(directory=".")
+```
+
+### `search_code`
+
+Perform semantic search and find structural code definitions, locate where functions/classes are defined, or map out dependency references (call graphs). Uses hybrid retrieval (BM25 + vector embeddings) to find exact matches and semantic similarities.
+
+```
+search_code(query="parse python files", search_type="definition")
+search_code(query="how do we establish the database connection", search_type="references")
+search_code(query="src/auth/", search_type="file_structure")
+```
+
+### `search_docs`
+
+Understand the codebase conceptually — how things work, architectural patterns, SOPs. Searches markdown documentation, READMEs, and docstrings extracted from code.
+
+```
+search_docs(query="how does the authentication flow work?")
+search_docs(query="installation instructions", top_k=5)
+```
+
+### `search_history`
+
+Debug regressions and understand developer intent through Git history.
+
+```
+search_history(query="fix login timeout", search_type="commits")
+search_history(query="src/auth/login.py", search_type="file_history", target_file="src/auth/login.py")
+search_history(query="server.py", search_type="blame", target_file="server.py", line_start=1, line_end=20)
+```
+
+## Project Structure
+
+```
+code-memory/
+├── server.py          # MCP server entry point (FastMCP)
+├── db.py              # SQLite database layer with sqlite-vec
+├── parser.py          # Tree-sitter-based code parser
+├── doc_parser.py      # Markdown documentation parser
+├── queries.py         # Hybrid retrieval query layer
+├── git_search.py      # Git history search module
+├── errors.py          # Custom exception hierarchy
+├── validation.py      # Input validation functions
+├── logging_config.py  # Structured logging configuration
+├── tests/             # Test suite
+├── pyproject.toml     # Project metadata & dependencies
+└── prompts/           # Milestone prompt engineering files
+```
+
+## Troubleshooting
+
+### "Git repository not found" error
+
+Make sure you're running `search_history` from within a git repository. The tool searches upward from the current directory to find `.git`.
+
+### Empty search results
+
+Run `index_codebase(directory=".")` first to index your code and documentation. The index is stored locally in `code_memory.db`.
+
+### Slow indexing
+
+Indexing generates embeddings using a local sentence-transformers model. The first run downloads the model (~90MB). Subsequent runs are faster.
+
+### Embedding model errors
+
+Ensure you have enough disk space and memory. The `all-MiniLM-L6-v2` model requires ~500MB RAM when loaded.
+
+## Roadmap
+
+- [x] **Milestone 1** — Project scaffolding & MCP protocol wiring
+- [x] **Milestone 2** — Implement `search_code` with AST parsing + SQLite + `sqlite-vec`
+- [x] **Milestone 3** — Implement `search_history` with Git integration
+- [x] **Milestone 4** — Implement `search_docs` with semantic search
+- [x] **Milestone 5** — Production hardening & packaging
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+## License
+
+MIT