{"_id":"@dannyboy2042/claude-context-core","_rev":"3-b20b28daf809164a92a656f7b95dbfa7","name":"@dannyboy2042/claude-context-core","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@dannyboy2042/claude-context-core","version":"0.1.0","license":"MIT","_id":"@dannyboy2042/claude-context-core@0.1.0","maintainers":[{"name":"dannyboy2042","email":"danielbowne@gmail.com"}],"homepage":"https://github.com/dannyboy2042/claude-context#readme","bugs":{"url":"https://github.com/dannyboy2042/claude-context/issues"},"dist":{"shasum":"2cae16d412c40bebd5b2cd304dbb78f40ef0cd5c","tarball":"https://registry.npmjs.org/@dannyboy2042/claude-context-core/-/claude-context-core-0.1.0.tgz","fileCount":91,"integrity":"sha512-wv/O9qO+/25dOs+pSXnRcxS3PqfSjBvK2fhAJf4SSq8Mu7Bc40V2wiFgBDG00ZXJmC11TVpzF3Vl4zDGzURNFQ==","signatures":[{"sig":"MEUCIGNvQPQuxwrGN8IudsGQtRL2KqzxTaRJjkrcIzyfyX+MAiEAqR6waUiDA4RgrIpIs3uAuHA8C0VRA9QefAX+Sip9N14=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":397028},"main":"dist/index.js","_from":"file:dannyboy2042-claude-context-core-0.1.0.tgz","types":"dist/index.d.ts","scripts":{"dev":"tsc --watch","lint":"eslint src --ext .ts","build":"yarn clean && tsc --build --force","clean":"rm -rf dist","lint:fix":"eslint src --ext .ts --fix","typecheck":"tsc --noEmit"},"_npmUser":{"name":"dannyboy2042","email":"danielbowne@gmail.com"},"_resolved":"/tmp/c0b8bcdac0dd45b1316cc9f79e41d25f/dannyboy2042-claude-context-core-0.1.0.tgz","_integrity":"sha512-wv/O9qO+/25dOs+pSXnRcxS3PqfSjBvK2fhAJf4SSq8Mu7Bc40V2wiFgBDG00ZXJmC11TVpzF3Vl4zDGzURNFQ==","repository":{"url":"git+https://github.com/dannyboy2042/claude-context.git","type":"git","directory":"packages/core"},"_npmVersion":"10.8.2","description":"Core indexing engine for Claude Context","directories":{},"_nodeVersion":"20.19.4","dependencies":{"glob":"^10.0.0","ollama":"^0.5.16","openai":"^5.1.1","fs-extra":"^11.0.0","voyageai":"^0.0.4","langchain":"^0.3.27","faiss-node":"^0.5.1","typescript":"^5.0.0","tree-sitter":"^0.21.1","apache-arrow":"^17.0.0","@google/genai":"^1.9.0","tree-sitter-go":"^0.21.0","tree-sitter-cpp":"^0.22.0","@lancedb/lancedb":"^0.15.0","tree-sitter-java":"^0.21.0","tree-sitter-rust":"^0.21.0","tree-sitter-python":"^0.21.0","tree-sitter-c-sharp":"^0.21.0","tree-sitter-javascript":"^0.21.0","tree-sitter-typescript":"^0.21.0","@zilliz/milvus2-sdk-node":"^2.5.10"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.0.0","mock-fs":"^5.5.0","ts-jest":"^29.4.0","@types/jest":"^30.0.0","@types/mock-fs":"^4.13.4","@types/fs-extra":"^11.0.0"},"_npmOperationalInternal":{"tmp":"tmp/claude-context-core_0.1.0_1754929485790_0.9912335569046153","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@dannyboy2042/claude-context-core","version":"0.1.2","license":"MIT","_id":"@dannyboy2042/claude-context-core@0.1.2","maintainers":[{"name":"dannyboy2042","email":"danielbowne@gmail.com"}],"homepage":"https://github.com/dannyboy2042/claude-context#readme","bugs":{"url":"https://github.com/dannyboy2042/claude-context/issues"},"dist":{"shasum":"a631cbd2db3efaee03e8b8f8f8108cd29ce75d26","tarball":"https://registry.npmjs.org/@dannyboy2042/claude-context-core/-/claude-context-core-0.1.2.tgz","fileCount":91,"integrity":"sha512-4H4MD/m85NiqwLsA+EolS8vfh0MkYTIObQJAu1MGELwxdQKq4Lv0js45MNItWXDMrssCdjget+qmWQ3co1bZtA==","signatures":[{"sig":"MEQCIC1aalRfI3ZpstHHs9VZ4YYN3Izs4af3wEsJ240A5iDjAiAYTWs8XLsIKpcZfIUSKcwicNSjVb53ul/0oK7w6qlL4g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":397028},"main":"dist/index.js","_from":"file:dannyboy2042-claude-context-core-0.1.2.tgz","types":"dist/index.d.ts","scripts":{"dev":"tsc --watch","lint":"eslint src --ext .ts","build":"yarn clean && tsc --build --force","clean":"rm -rf dist","lint:fix":"eslint src --ext .ts --fix","typecheck":"tsc --noEmit"},"_npmUser":{"name":"dannyboy2042","email":"danielbowne@gmail.com"},"_resolved":"/tmp/609a5f0994cb567830f84119b9ea2cb8/dannyboy2042-claude-context-core-0.1.2.tgz","_integrity":"sha512-4H4MD/m85NiqwLsA+EolS8vfh0MkYTIObQJAu1MGELwxdQKq4Lv0js45MNItWXDMrssCdjget+qmWQ3co1bZtA==","repository":{"url":"git+https://github.com/dannyboy2042/claude-context.git","type":"git","directory":"packages/core"},"_npmVersion":"10.8.2","description":"Core indexing engine for Claude Context","directories":{},"_nodeVersion":"20.19.4","dependencies":{"glob":"^10.0.0","ollama":"^0.5.16","openai":"^5.1.1","fs-extra":"^11.0.0","voyageai":"^0.0.4","langchain":"^0.3.27","faiss-node":"^0.5.1","typescript":"^5.0.0","tree-sitter":"^0.21.1","apache-arrow":"^17.0.0","@google/genai":"^1.9.0","tree-sitter-go":"^0.21.0","tree-sitter-cpp":"^0.22.0","@lancedb/lancedb":"^0.15.0","tree-sitter-java":"^0.21.0","tree-sitter-rust":"^0.21.0","tree-sitter-python":"^0.21.0","tree-sitter-c-sharp":"^0.21.0","tree-sitter-javascript":"^0.21.0","tree-sitter-typescript":"^0.21.0","@zilliz/milvus2-sdk-node":"^2.5.10"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.0.0","mock-fs":"^5.5.0","ts-jest":"^29.4.0","@types/jest":"^30.0.0","@types/mock-fs":"^4.13.4","@types/fs-extra":"^11.0.0"},"_npmOperationalInternal":{"tmp":"tmp/claude-context-core_0.1.2_1754931945910_0.19112237378584962","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@dannyboy2042/claude-context-core","version":"0.2.0","description":"Core indexing engine for Claude Context","main":"dist/index.js","types":"dist/index.d.ts","dependencies":{"@google/genai":"^1.9.0","@lancedb/lancedb":"^0.15.0","@zilliz/milvus2-sdk-node":"^2.5.10","apache-arrow":"^17.0.0","faiss-node":"^0.5.1","fs-extra":"^11.0.0","glob":"^10.0.0","langchain":"^0.3.27","ollama":"^0.5.16","openai":"^5.1.1","tree-sitter":"^0.21.1","tree-sitter-cpp":"^0.22.0","tree-sitter-go":"^0.21.0","tree-sitter-java":"^0.21.0","tree-sitter-javascript":"^0.21.0","tree-sitter-python":"^0.21.0","tree-sitter-c-sharp":"^0.21.0","tree-sitter-rust":"^0.21.0","tree-sitter-typescript":"^0.21.0","typescript":"^5.0.0","voyageai":"^0.0.4"},"devDependencies":{"@types/fs-extra":"^11.0.0","@types/jest":"^30.0.0","@types/mock-fs":"^4.13.4","jest":"^30.0.0","mock-fs":"^5.5.0","ts-jest":"^29.4.0"},"repository":{"type":"git","url":"git+https://github.com/dannyboy2042/claude-context.git","directory":"packages/core"},"license":"MIT","publishConfig":{"access":"public"},"scripts":{"build":"yarn clean && tsc --build --force","dev":"tsc --watch","clean":"rm -rf dist","lint":"eslint src --ext .ts","lint:fix":"eslint src --ext .ts --fix","typecheck":"tsc --noEmit"},"_id":"@dannyboy2042/claude-context-core@0.2.0","bugs":{"url":"https://github.com/dannyboy2042/claude-context/issues"},"homepage":"https://github.com/dannyboy2042/claude-context#readme","_integrity":"sha512-n7zbpRYmb7ckSXxPujhVMBCXIqBBCC24cf/7i2vaViS6BEVjHg7fgONPDqWVnOEUiiP0TtwxCqT5LJCoOmh+tw==","_resolved":"/tmp/06d11003ad78d4727f3a3bf1247a1e0c/dannyboy2042-claude-context-core-0.2.0.tgz","_from":"file:dannyboy2042-claude-context-core-0.2.0.tgz","_nodeVersion":"20.19.4","_npmVersion":"10.8.2","dist":{"integrity":"sha512-n7zbpRYmb7ckSXxPujhVMBCXIqBBCC24cf/7i2vaViS6BEVjHg7fgONPDqWVnOEUiiP0TtwxCqT5LJCoOmh+tw==","shasum":"d45070f534d042569b23638e163ecc0ccb437e30","tarball":"https://registry.npmjs.org/@dannyboy2042/claude-context-core/-/claude-context-core-0.2.0.tgz","fileCount":91,"unpackedSize":401735,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAD0ZsMJzXgGood2KS003DQoXcb9UWE3OYLLfgrY36vsAiBW9xLw5dIFiHA5FZDXMeBfc2coPNDmW/rPDAULmAXeqA=="}]},"_npmUser":{"name":"dannyboy2042","email":"danielbowne@gmail.com"},"directories":{},"maintainers":[{"name":"dannyboy2042","email":"danielbowne@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/claude-context-core_0.2.0_1754936864283_0.6216688550995746"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-11T16:24:45.687Z","modified":"2025-08-11T18:27:44.706Z","0.1.0":"2025-08-11T16:24:46.042Z","0.1.2":"2025-08-11T17:05:46.118Z","0.2.0":"2025-08-11T18:27:44.516Z"},"bugs":{"url":"https://github.com/dannyboy2042/claude-context/issues"},"license":"MIT","homepage":"https://github.com/dannyboy2042/claude-context#readme","repository":{"type":"git","url":"git+https://github.com/dannyboy2042/claude-context.git","directory":"packages/core"},"description":"Core indexing engine for Claude Context","maintainers":[{"name":"dannyboy2042","email":"danielbowne@gmail.com"}],"readme":"# @dannyboy2042/claude-context-core\n![](../../assets/claude-context.png)\n\nThe core indexing engine for Claude Context - a powerful tool for semantic search and analysis of codebases using vector embeddings and AI.\n\n[![npm version](https://img.shields.io/npm/v/@dannyboy2042/claude-context-core.svg)](https://www.npmjs.com/package/@dannyboy2042/claude-context-core)\n[![npm downloads](https://img.shields.io/npm/dm/@dannyboy2042/claude-context-core.svg)](https://www.npmjs.com/package/@dannyboy2042/claude-context-core)\n\n> 📖 **New to Claude Context?** Check out the [main project README](../../README.md) for an overview and quick start guide.\n\n## Installation\n\n```bash\nnpm install @dannyboy2042/claude-context-core\n```\n\n### Prepare Environment Variables\n\n#### OpenAI API key\nSee [OpenAI Documentation](https://platform.openai.com/docs/api-reference) for more details to get your API key.\n```bash\nOPENAI_API_KEY=your-openai-api-key\n```\n\n#### Vector Database Configuration (Optional)\nBy default, Claude Context uses **LanceDB** for local vector storage - no setup required! All data is stored locally in `./.claude-context/lancedb/`.\n\n```bash\n# Optional: Customize LanceDB storage path\nLANCEDB_PATH=./my-custom-path\n\n# Optional: Use Zilliz Cloud instead of local LanceDB\nVECTOR_DB_TYPE=milvus\nMILVUS_ADDRESS=your-zilliz-cloud-public-endpoint\nMILVUS_TOKEN=your-zilliz-cloud-api-key\n```\n\n<details>\n<summary>Advanced: Using Zilliz Cloud for scalable deployments</summary>\n\nFor larger teams or advanced features, you can optionally use Zilliz Cloud. 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.\n\n![](../../assets/signup_and_create_cluster.jpeg)\n\nAfter creating your cluster, open your Zilliz Cloud console and copy both the **public endpoint** and your **API key**.  \n\n![Zilliz Cloud Dashboard](../../assets/zilliz_cloud_dashboard.jpeg)\n\nIf you need help creating your free vector database or finding these values, see the [Zilliz Cloud documentation](https://docs.zilliz.com/docs/create-cluster) for detailed instructions.\n</details>\n\n> 💡 **Tip**: For easier configuration management across different usage scenarios, consider using [global environment variables](../../docs/getting-started/environment-variables.md).\n\n## Quick Start\n\n```typescript\nimport { \n  Context, \n  OpenAIEmbedding, \n  LanceDBVectorDatabase \n} from '@dannyboy2042/claude-context-core';\n\n// Initialize embedding provider\nconst embedding = new OpenAIEmbedding({\n  apiKey: process.env.OPENAI_API_KEY || 'your-openai-api-key',\n  model: 'text-embedding-3-small'\n});\n\n// Initialize vector database (LanceDB - local, no setup required)\nconst vectorDatabase = new LanceDBVectorDatabase({\n  uri: process.env.LANCEDB_PATH || './.claude-context/lancedb'\n});\n\n// Create context instance\nconst context = new Context({\n  embedding,\n  vectorDatabase\n});\n\n// Index a codebase\nconst stats = await context.indexCodebase('./my-project', (progress) => {\n  console.log(`${progress.phase} - ${progress.percentage}%`);\n});\n\nconsole.log(`Indexed ${stats.indexedFiles} files with ${stats.totalChunks} chunks`);\n\n// Search the codebase\nconst results = await context.semanticSearch(\n  './my-project',\n  'function that handles user authentication',\n  5\n);\n\nresults.forEach(result => {\n  console.log(`${result.relativePath}:${result.startLine}-${result.endLine}`);\n  console.log(`Score: ${result.score}`);\n  console.log(result.content);\n});\n```\n\n## Features\n\n- **Multi-language Support**: Index TypeScript, JavaScript, Python, Java, C++, and many other programming languages\n- **Semantic Search**: Find code using natural language queries powered by AI embeddings\n- **Flexible Architecture**: Pluggable embedding providers and vector databases\n- **Smart Chunking**: Intelligent code splitting that preserves context and structure\n- **Batch Processing**: Efficient processing of large codebases with progress tracking\n- **Pattern Matching**: Built-in ignore patterns for common build artifacts and dependencies\n- **Incremental File Synchronization**: Efficient change detection using Merkle trees to only re-index modified files\n\n## Embedding Providers\n\n- **OpenAI Embeddings** (`text-embedding-3-small`, `text-embedding-3-large`)\n- **VoyageAI Embeddings** - High-quality embeddings optimized for code\n\n## Vector Database Support\n\n- **LanceDB** - Local, embedded vector database (default)\n- **Milvus/Zilliz Cloud** - High-performance vector database (optional)\n\n## Code Splitters\n\n- **AST Code Splitter** - AST-based code splitting with automatic fallback (default)\n- **LangChain Code Splitter** - Character-based code chunking\n\n## Configuration\n\n### ContextConfig\n\n```typescript\ninterface ContextConfig {\n  embedding?: Embedding;           // Embedding provider\n  vectorDatabase?: VectorDatabase; // Vector database instance (required)\n  codeSplitter?: Splitter;        // Code splitting strategy\n  supportedExtensions?: string[]; // File extensions to index\n  ignorePatterns?: string[];      // Patterns to ignore\n}\n```\n\n### Supported File Extensions (Default)\n\n```typescript\n[\n  // Programming languages\n  '.ts', '.tsx', '.js', '.jsx', '.py', '.java', '.cpp', '.c', '.h', '.hpp',\n  '.cs', '.go', '.rs', '.php', '.rb', '.swift', '.kt', '.scala', '.m', '.mm',\n  // Text and markup files  \n  '.md', '.markdown'\n]\n```\n\n### Default Ignore Patterns\n\n- `node_modules/**`, `dist/**`, `build/**`, `out/**`\n- `.git/**`, `.vscode/**`, `.idea/**`\n- `*.min.js`, `*.bundle.js`, `*.map`\n- Log files, cache directories, and temporary files\n\n## API Reference\n\n### Context\n\n#### Methods\n\n- `indexCodebase(path, progressCallback?)` - Index an entire codebase\n- `semanticSearch(path, query, topK?, threshold?)` - Search indexed code semantically\n- `hasIndex(path)` - Check if codebase is already indexed\n- `clearIndex(path, progressCallback?)` - Remove index for a codebase\n- `updateIgnorePatterns(patterns)` - Update ignore patterns\n- `updateEmbedding(embedding)` - Switch embedding provider\n- `updateVectorDatabase(vectorDB)` - Switch vector database\n\n### Search Results\n\n```typescript\ninterface SemanticSearchResult {\n  content: string;      // Code content\n  relativePath: string; // File path relative to codebase root\n  startLine: number;    // Starting line number\n  endLine: number;      // Ending line number\n  language: string;     // Programming language\n  score: number;        // Similarity score (0-1)\n  fileExtension: string; // File extension\n}\n```\n\n\n## Examples\n\n### Using VoyageAI Embeddings\n\n```typescript\nimport { Context, LanceDBVectorDatabase, VoyageAIEmbedding } from '@dannyboy2042/claude-context-core';\n\n// Initialize with VoyageAI embedding provider\nconst embedding = new VoyageAIEmbedding({\n  apiKey: process.env.VOYAGEAI_API_KEY || 'your-voyageai-api-key',\n  model: 'voyage-code-3'\n});\n\nconst vectorDatabase = new LanceDBVectorDatabase({\n  uri: './.claude-context/lancedb'\n});\n\nconst context = new Context({\n  embedding,\n  vectorDatabase\n});\n```\n\n### Custom File Filtering\n\n```typescript\nconst context = new Context({\n  embedding,\n  vectorDatabase,\n  supportedExtensions: ['.ts', '.js', '.py', '.java'],\n  ignorePatterns: [\n    'node_modules/**',\n    'dist/**',\n    '*.spec.ts',\n    '*.test.js'\n  ]\n});\n```\n\n## File Synchronization Architecture\n\nClaude 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.\n\n![File Synchronization Architecture](../../assets/file_synchronizer.png)\n\n### How It Works\n\nThe file synchronization system uses a **Merkle tree-based approach** combined with SHA-256 file hashing to detect changes:\n\n#### 1. File Hashing\n- Each file in the codebase is hashed using SHA-256\n- File hashes are computed based on file content, not metadata\n- Hashes are stored with relative file paths for consistency across different environments\n\n#### 2. Merkle Tree Construction\n- All file hashes are organized into a Merkle tree structure\n- The tree provides a single root hash that represents the entire codebase state\n- Any change to any file will cause the root hash to change\n\n#### 3. Snapshot Management\n- File synchronization state is persisted to `~/.context/merkle/` directory\n- Each codebase gets a unique snapshot file based on its absolute path hash\n- Snapshots contain both file hashes and serialized Merkle tree data\n\n#### 4. Change Detection Process\n1. **Quick Check**: Compare current Merkle root hash with stored snapshot\n2. **Detailed Analysis**: If root hashes differ, perform file-by-file comparison\n3. **Change Classification**: Categorize changes into three types:\n   - **Added**: New files that didn't exist before\n   - **Modified**: Existing files with changed content\n   - **Removed**: Files that were deleted from the codebase\n\n#### 5. Incremental Updates\n- Only process files that have actually changed\n- Update vector database entries only for modified chunks\n- Remove entries for deleted files\n- Add entries for new files\n\n\n## Contributing\n\nThis package is part of the Claude Context monorepo. Please see:\n- [Main Contributing Guide](../../CONTRIBUTING.md) - General contribution guidelines\n- [Core Package Contributing](CONTRIBUTING.md) - Specific development guide for this package\n\n## Related Packages\n\n- **[@claude-context/mcp](../mcp)** - MCP server that uses this core engine\n- **[VSCode Extension](../vscode-extension)** - VSCode extension built on this core\n\n\n## License\n\nMIT - See [LICENSE](../../LICENSE) for details\n\n---\n\n## 🙏 Thanks\n\nSpecial thanks to **Cheney Zhang** and the **Zilliz team** for creating the original Claude Context project. This fork builds upon their excellent foundation to provide a local-first vector database experience with LanceDB.","readmeFilename":"README.md"}