@mcampa/claude-context-core 0.2.0 → 0.2.1

package/README.md

@@ -1,4 +1,5 @@
 # @mcampa/claude-context-core
+
 ![](../../assets/claude-context.png)
 
 The core indexing engine for Claude Context - a powerful tool for semantic search and analysis of codebases using vector embeddings and AI.
@@ -15,14 +16,18 @@ npm install @mcampa/claude-context-core
 ```
 
 ### Prepare Environment Variables
+
 #### OpenAI API key
+
 See [OpenAI Documentation](https://platform.openai.com/docs/api-reference) for more details to get your API key.
+
 ```bash
 OPENAI_API_KEY=your-openai-api-key
 ```
 
 #### Zilliz Cloud configuration
-Get a free Milvus vector database on Zilliz Cloud. 
+
+Get a free Milvus vector database on Zilliz Cloud.
 
 Claude Context needs a vector database. You can [sign up](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=2507-codecontext-readme) on Zilliz Cloud to get a free Serverless cluster.
 
@@ -40,53 +45,54 @@ If you need help creating your free vector database or finding these values, see
 ```bash
 MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint
 MILVUS_TOKEN=your-zilliz-cloud-api-key
-``` 
+```
 
 > 💡 **Tip**: For easier configuration management across different usage scenarios, consider using [global environment variables](../../docs/getting-started/environment-variables.md).
 
 ## Quick Start
 
 ```typescript
-import { 
-  Context, 
-  OpenAIEmbedding, 
-  MilvusVectorDatabase 
-} from '@mcampa/claude-context-core';
+import {
+  Context,
+  OpenAIEmbedding,
+  MilvusVectorDatabase,
+} from "@mcampa/claude-context-core";
 
 // Initialize embedding provider
 const embedding = new OpenAIEmbedding({
-  apiKey: process.env.OPENAI_API_KEY || 'your-openai-api-key',
-  model: 'text-embedding-3-small'
+  apiKey: process.env.OPENAI_API_KEY || "your-openai-api-key",
+  model: "text-embedding-3-small",
 });
 
 // Initialize vector database
 const vectorDatabase = new MilvusVectorDatabase({
-  address: process.env.MILVUS_ADDRESS || 'localhost:19530',
-  token: process.env.MILVUS_TOKEN || ''
+  address: process.env.MILVUS_ADDRESS || "localhost:19530",
+  token: process.env.MILVUS_TOKEN || "",
 });
 
 // Create context instance
 const context = new Context({
-  name: 'my-context',
+  name: "my-context",
   embedding,
-  vectorDatabase
+  vectorDatabase,
 });
 
 // Index a codebase
-const stats = await context.indexCodebase('./my-project', (progress) => {
+const stats = await context.indexCodebase("./my-project", (progress) => {
   console.log(`${progress.phase} - ${progress.percentage}%`);
 });
 
-console.log(`Indexed ${stats.indexedFiles} files with ${stats.totalChunks} chunks`);
+console.log(
+  `Indexed ${stats.indexedFiles} files with ${stats.totalChunks} chunks`
+);
 
 // Search the codebase
 const results = await context.semanticSearch(
-  './my-project',
-  'function that handles user authentication',
+  "function that handles user authentication",
   5
 );
 
-results.forEach(result => {
+results.forEach((result) => {
   console.log(`${result.relativePath}:${result.startLine}-${result.endLine}`);
   console.log(`Score: ${result.score}`);
   console.log(result.content);
@@ -125,12 +131,13 @@ results.forEach(result => {
 
 ```typescript
 interface ContextConfig {
-  embedding?: Embedding;           // Embedding provider
+  name?: string; // Context name (default: 'my-context')
+  embedding?: Embedding; // Embedding provider
   vectorDatabase?: VectorDatabase; // Vector database instance (required)
-  codeSplitter?: Splitter;        // Code splitting strategy
+  codeSplitter?: Splitter; // Code splitting strategy
   supportedExtensions?: string[]; // File extensions to index
-  ignorePatterns?: string[];      // Patterns to ignore
-  customExtensions?: string[];    // Custom extensions from MCP
+  ignorePatterns?: string[]; // Patterns to ignore
+  customExtensions?: string[]; // Custom extensions from MCP
   customIgnorePatterns?: string[]; // Custom ignore patterns from MCP
 }
 ```
@@ -140,11 +147,31 @@ interface ContextConfig {
 ```typescript
 [
   // Programming languages
-  '.ts', '.tsx', '.js', '.jsx', '.py', '.java', '.cpp', '.c', '.h', '.hpp',
-  '.cs', '.go', '.rs', '.php', '.rb', '.swift', '.kt', '.scala', '.m', '.mm',
-  // Text and markup files  
-  '.md', '.markdown', '.ipynb'
-]
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".py",
+  ".java",
+  ".cpp",
+  ".c",
+  ".h",
+  ".hpp",
+  ".cs",
+  ".go",
+  ".rs",
+  ".php",
+  ".rb",
+  ".swift",
+  ".kt",
+  ".scala",
+  ".m",
+  ".mm",
+  // Text and markup files
+  ".md",
+  ".markdown",
+  ".ipynb",
+];
 ```
 
 ### Default Ignore Patterns
@@ -165,8 +192,8 @@ interface ContextConfig {
 
 - `indexCodebase(path, progressCallback?, forceReindex?)` - Index an entire codebase
 - `reindexByChange(path, progressCallback?)` - Incrementally re-index only changed files
-- `semanticSearch(path, query, topK?, threshold?, filterExpr?)` - Search indexed code semantically
-- `hasIndex(path)` - Check if codebase is already indexed
+- `semanticSearch(query, topK?, threshold?, filterExpr?)` - Search indexed code semantically
+- `hasIndex()` - Check if index exists
 - `clearIndex(path, progressCallback?)` - Remove index for a codebase
 - `updateIgnorePatterns(patterns)` - Update ignore patterns
 - `addCustomIgnorePatterns(patterns)` - Add custom ignore patterns
@@ -179,38 +206,41 @@ interface ContextConfig {
 
 ```typescript
 interface SemanticSearchResult {
-  content: string;      // Code content
+  content: string; // Code content
   relativePath: string; // File path relative to codebase root
-  startLine: number;    // Starting line number
-  endLine: number;      // Ending line number
-  language: string;     // Programming language
-  score: number;        // Similarity score (0-1)
+  startLine: number; // Starting line number
+  endLine: number; // Ending line number
+  language: string; // Programming language
+  score: number; // Similarity score (0-1)
 }
 ```
 
-
 ## Examples
 
 ### Using VoyageAI Embeddings
 
 ```typescript
-import { Context, MilvusVectorDatabase, VoyageAIEmbedding } from '@mcampa/claude-context-core';
+import {
+  Context,
+  MilvusVectorDatabase,
+  VoyageAIEmbedding,
+} from "@mcampa/claude-context-core";
 
 // Initialize with VoyageAI embedding provider
 const embedding = new VoyageAIEmbedding({
-  apiKey: process.env.VOYAGEAI_API_KEY || 'your-voyageai-api-key',
-  model: 'voyage-code-3'
+  apiKey: process.env.VOYAGEAI_API_KEY || "your-voyageai-api-key",
+  model: "voyage-code-3",
 });
 
 const vectorDatabase = new MilvusVectorDatabase({
-  address: process.env.MILVUS_ADDRESS || 'localhost:19530',
-  token: process.env.MILVUS_TOKEN || ''
+  address: process.env.MILVUS_ADDRESS || "localhost:19530",
+  token: process.env.MILVUS_TOKEN || "",
 });
 
 const context = new Context({
-  name: 'my-context',
+  name: "my-context",
   embedding,
-  vectorDatabase
+  vectorDatabase,
 });
 ```
 
@@ -218,19 +248,35 @@ const context = new Context({
 
 ```typescript
 const context = new Context({
-  name: 'my-context',
+  name: "my-context",
   embedding,
   vectorDatabase,
-  supportedExtensions: ['.ts', '.js', '.py', '.java'],
-  ignorePatterns: [
-    'node_modules/**',
-    'dist/**',
-    '*.spec.ts',
-    '*.test.js'
-  ]
+  supportedExtensions: [".ts", ".js", ".py", ".java"],
+  ignorePatterns: ["node_modules/**", "dist/**", "*.spec.ts", "*.test.js"],
 });
 ```
 
+### Relative Path Indexing
+
+File paths are indexed relative to the `codebasePath` parameter you provide when indexing:
+
+```typescript
+// Index a codebase - paths will be relative to this directory
+await context.indexCodebase("/Users/username/projects/my-workspace");
+
+// Search returns results with relative paths
+const results = await context.semanticSearch("user authentication function");
+
+// Results show paths relative to the indexed codebase path, e.g.:
+// "packages/app/src/auth.ts" instead of full absolute path
+```
+
+This makes search results:
+
+- More readable and concise
+- Portable across different machines
+- Consistent in monorepo environments
+
 ## File Synchronization Architecture
 
 Claude Context implements an intelligent file synchronization system that efficiently tracks and processes only the files that have changed since the last indexing operation. This dramatically improves performance when working with large codebases.
@@ -242,21 +288,25 @@ Claude Context implements an intelligent file synchronization system that effici
 The file synchronization system uses a **Merkle tree-based approach** combined with SHA-256 file hashing to detect changes:
 
 #### 1. File Hashing
+
 - Each file in the codebase is hashed using SHA-256
 - File hashes are computed based on file content, not metadata
 - Hashes are stored with relative file paths for consistency across different environments
 
 #### 2. Merkle Tree Construction
+
 - All file hashes are organized into a Merkle tree structure
 - The tree provides a single root hash that represents the entire codebase state
 - Any change to any file will cause the root hash to change
 
 #### 3. Snapshot Management
+
 - File synchronization state is persisted to `~/.context/merkle/` directory
 - Each codebase gets a unique snapshot file based on its absolute path hash
 - Snapshots contain both file hashes and serialized Merkle tree data
 
 #### 4. Change Detection Process
+
 1. **Quick Check**: Compare current Merkle root hash with stored snapshot
 2. **Detailed Analysis**: If root hashes differ, perform file-by-file comparison
 3. **Change Classification**: Categorize changes into three types:
@@ -265,15 +315,16 @@ The file synchronization system uses a **Merkle tree-based approach** combined w
    - **Removed**: Files that were deleted from the codebase
 
 #### 5. Incremental Updates
+
 - Only process files that have actually changed
 - Update vector database entries only for modified chunks
 - Remove entries for deleted files
 - Add entries for new files
 
-
 ## Contributing
 
 This package is part of the Claude Context monorepo. Please see:
+
 - [Main Contributing Guide](../../CONTRIBUTING.md) - General contribution guidelines
 - [Core Package Contributing](CONTRIBUTING.md) - Specific development guide for this package
 
@@ -282,7 +333,6 @@ This package is part of the Claude Context monorepo. Please see:
 - **[@claude-context/mcp](../mcp)** - MCP server that uses this core engine
 - **[VSCode Extension](../vscode-extension)** - VSCode extension built on this core
 
-
 ## License
 
-MIT - See [LICENSE](../../LICENSE) for details
+MIT - See [LICENSE](../../LICENSE) for details