claudemem Development Guide

You are an expert claudemem developer. claudemem is a local semantic code search tool that combines AST parsing, embeddings, symbol graphs, and code analysis.

Architecture Overview

claudemem combines:

Core Module Structure

```

src/

├── core/

│ ├── analysis/ # Code analysis (dead-code, test-gaps, impact)

│ │ ├── analyzer.ts # CodeAnalyzer class

│ │ └── test-detector.ts # Language-aware test file detection

│ ├── graph/ # Symbol graph with PageRank

│ ├── enrichment/ # LLM-based code summaries

│ ├── indexer/ # Code indexing pipeline

│ ├── search/ # Hybrid search (vector + BM25)

│ └── watcher/ # File system watcher

├── git/ # Git hook integration

│ └── hook-manager.ts # Post-commit hook management

├── cli.ts # Main CLI entry point

├── mcp-server.ts # MCP server for Claude Code

├── ai-instructions.ts # Role-based AI agent prompts

└── ai-skill.ts # Skill documents for embedding

```

Development Instructions

When Adding New Commands

Follow these steps exactly:

1. **Add command case** in `cli.ts` switch statement

2. **Create handler function** following existing patterns in the file

3. **Update help text** in the `printHelp()` function

4. **Update README.md** CLI reference section with the new command

5. **Update AI files** - add command to `ai-instructions.ts` and `ai-skill.ts` for AI agent awareness

When Implementing Code Analysis Features

Use the standard code analyzer pattern:

```typescript

import { createCodeAnalyzer } from "./core/analysis/index.js";

const analyzer = await createCodeAnalyzer(projectPath);

const results = analyzer.findDeadCode({ maxPageRank: 0.001 });

```

When Working with Test Detection

Test file detection is language-specific. Check `src/core/analysis/test-detector.ts` for patterns:

Add new language patterns to `test-detector.ts` if needed.

Key Commands (v0.3.0)

Symbol Graph Commands

Code Analysis Commands

Developer Experience Commands

Testing and Building

Run these commands during development:

```bash

Run tests

bun test

Type check

bun run typecheck

Build for distribution

bun run build

```

AI Integration Files

ai-instructions.ts

Contains role-based prompts for different agent personas:

ai-skill.ts

Contains multiple skill document variants:

Update these when adding new commands or analysis capabilities.

Critical Development Rules

1. **Always use `--nologo --raw`** flags when outputting machine-parseable data

2. **PageRank > 0.05** indicates high-importance symbols - use this threshold in analysis features

3. **Test file detection** is language-specific - always check/update `test-detector.ts`

4. **Impact analysis** uses BFS with depth limiting to prevent infinite loops in circular dependencies

5. **Watch mode** uses native `fs.watch` - no external dependencies like chokidar

6. **Publishing** happens via CI/CD - use automated releases, not manual npm publish

Common Implementation Patterns

When implementing new analysis features:

When adding new search capabilities:

Publishing and Releases

The project uses CI/CD for automated releases. Do not manually publish to npm. Follow the automated release workflow configured in the repository.