Local Semantic Code Search for Claude Code and AI Agents

The Problem with grep

I've been writing code for over twenty years. Last month I spent forty-five minutes searching for a function I wrote myself three weeks earlier.

Forty-five minutes. For code I wrote.

The function was called silentTokenRefresh. Of course it was. I'd typed "token" into grep. Got 847 results. None of them were the actual token handler. I'd scrolled right past it twice before giving up and asking a colleague who remembered the name.

I started timing these searches. Three hours hunting for "the thing that validates webhook signatures." Two hours finding where we actually persist user preferences. An entire afternoon tracing why a settings change wasn't propagating—turned out there were four different settings services, and I was looking at the wrong three.

grep doesn't care about my memory. It doesn't know that when I search for "auth" I probably mean the token refresh flow, not the 200 files that happen to contain the word "authentication" in a comment.

I was tired of feeling stupid in codebases I wrote myself.

The Numbers

The Architecture: Not Just Another Search Tool

claudemem builds a semantic graph of your codebase. Not a text index. Not a fuzzy matcher. An actual understanding of what calls what and why.

The indexer parses every file into an AST. Functions, classes, methods, calls—all of it becomes nodes in a graph. Then it runs PageRank. The same algorithm Google used to find important web pages, but pointed at your code.

This matters more than it sounds. When you search, results come back ranked by architectural importance. The core authentication handler ranks higher than the seventeen wrapper functions that call it. You find the heart of your system in seconds, not hours.

Semantic search sits on top. When I search "refresh tokens silently," it doesn't just pattern-match those words. It understands token operations, refresh patterns, silent execution. It finds silentTokenRefresh even though my query didn't match the exact name.

The caller/callee analysis closed the loop. Before touching any function, I see exactly what depends on it. Last month this caught a disaster—I was about to "clean up" a function that looked unused. claudemem showed nine callers. Nine were dead code we'd been maintaining for two years. The tenth was the payment processor.

We'd been maintaining code nobody called for two years. And we almost deleted code that would have broken payments.

This isn't a research project. It's the architecture I needed to stop wasting hours every week. Everything stays local in .claudemem/ in your project. Nothing goes to a server. Ever.

It changed how we work.

Embedding Model Benchmarks: We Tested Everything

Which embedding model is best for code search? We didn't guess. We measured.

Run claudemem benchmark to test models on your actual codebase. Here's what we found on real code search tasks:

LLM Summarizer Benchmarks: Which Model Describes Code Best?

claudemem generates natural language descriptions of code chunks. These descriptions power semantic search. Better descriptions = better search results.

We benchmarked 18 LLM models across 6 different evaluation methods:

Evaluation Methods

• Judge (Pointwise): LLM rates each description's quality 0-10
• Judge (Pairwise): LLM picks better description in head-to-head comparisons
• Contrastive Discrimination: Can the description identify its source code among alternatives?
• Retrieval: Does using the description improve search accuracy?
• Downstream Tasks: Does the description help with actual coding tasks?
• Self-Evaluation: Model rates its own outputs (calibration check)

Symbol Graph: Beyond Search

Search is table stakes. The real power is the symbol graph.

claudemem tracks every reference between symbols. It computes PageRank scores based on how central each function/class is to your codebase. This enables:

Dead Code Detection

claudemem dead-code

Finds symbols with zero callers + low PageRank + not exported. Great for cleaning up unused code.

Test Coverage Gaps

claudemem test-gaps

Finds high-PageRank symbols not called by any test file. Prioritize what to test next.

Change Impact Analysis

claudemem impact FileTracker

Shows all transitive callers, grouped by file. Understand the blast radius before refactoring.

Symbol Navigation

claudemem symbol handleAuth     # find definition
claudemem callers handleAuth   # what calls this?
claudemem callees handleAuth   # what does this call?
claudemem context handleAuth   # all of the above

Self-Learning System (Experimental)

This is where it gets interesting.

Traditional ML validation assumes millions of samples and explicit labels. Our context is different: 50-500 sessions per project, no user ratings, data stays local.

claudemem's self-learning system uses implicit feedback signals:

The strongest signal: Code Survival Rate

code_survival_rate = lines_kept / lines_written_by_agent

If the user keeps the agent's code in their git commit, the agent did well. If they rewrite everything, it failed.

What Gets Generated

• Skills: Automatable sequences become slash commands
• Subagents: Error clusters become specialized agents
• Prompt Optimizations: Correction patterns become prompt additions

Safety Validation

Changes are tested against a Red Team before deployment:

• Red Team: Attacks with edge cases, malformed data, injections
• Blue Team: Defends with validation, sanitization, limits
• Safety Score: > 0.90 = Deploy, < 0.70 = Reject

Using with Claude Code

Run claudemem as an MCP server:

claudemem --mcp

Then Claude Code can use these tools:

• search_code - semantic search (auto-indexes changes)
• index_codebase - manual full reindex
• get_status - check what's indexed
• clear_index - start fresh

Detective Agents

Install the code-analysis plugin for pre-built agents that use claudemem:

• developer-detective: Trace implementations, find usages
• architect-detective: Analyze architecture, find patterns
• tester-detective: Find test gaps, coverage analysis
• debugger-detective: Trace errors, find bug sources

Documentation Indexing

claudemem can automatically fetch and index documentation for your dependencies. Search across both your code AND the frameworks you use.

Sources (in priority order):

• Context7: 6000+ libraries, versioned API docs (free API key)
• llms.txt: Official AI-optimized docs (Vue, Nuxt, Langchain, etc.)
• DevDocs: Offline documentation for 100+ languages

claudemem docs fetch              # fetch docs for all detected dependencies
claudemem docs fetch react vue    # fetch specific libraries
claudemem docs status             # show indexed docs

How We Compare

When This Matters to You

You need claudemem if:

• grep isn't cutting it: You're searching for concepts, not exact strings
• You value privacy: Code never leaves your machine. Ever.
• You want to benchmark: Test embedding models on YOUR codebase
• You need code analysis: Dead code detection, test gaps, change impact
• You use Claude Code: MCP integration gives Claude semantic search superpowers
• You're cost-conscious: Free for local models, ~$0.01/1M tokens for cloud

Quick Start

# Install
npm install -g claude-codemem

# Setup
claudemem init

# Index your project
claudemem index

# Search
claudemem search "authentication flow"
claudemem search "where do we validate user input"

That's it. Changed some files? Just search again - it auto-reindexes modified files before searching.

Talk to Us

We built claudemem because we needed it. We're using it daily. We're improving it constantly.

If you hit issues. If you have ideas. If you want to contribute. The door's open.

What code search problem are you trying to solve?