# PatrickSys/codebase-context [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/PatrickSys/codebase-context  
**GitHub Stars:** 67  
**npm Downloads (last month):** 560  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/patricksys-codebase-context

## Description
Local MCP server that shows AI agents which patterns your team actually uses, what files a change will affect, and when there is not enough context to trust an edit. 30+ languages, fully local.

## Tools
Capabilities this server exposes over MCP:

- **search_codebase** — Hybrid search + decision card when `intent="edit"
- **get_team_patterns** — Pattern frequencies, golden files, conflict detection
- **get_symbol_references** — Concrete references to a symbol (count + snippets)
- **remember** — Record a convention, decision, gotcha, or failure
- **get_memory** — Query team memory with confidence decay scoring
- **get_codebase_metadata** — Project structure, frameworks, dependencies
- **get_style_guide** — Style guide rules for the current project
- **detect_circular_dependencies** — Import cycles between files
- **refresh_index** — Full or incremental re-index + git memory extraction
- **get_indexing_status** — Progress and stats for the current index

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "codebase-context": {
    "command": "npx",
    "args": ["-y","codebase-context"]
  }
}
```

## Documentation

## What PatrickSys/codebase-context does

PatrickSys/codebase-context helps coding agents understand an existing repository before they search, modify, or review code. It indexes project files locally and exposes repository context through MCP, including ranked search results, representative team patterns, style rules, project metadata, symbol references, and recorded engineering decisions.

The server is aimed at local coding workflows and supports more than 30 languages. Its search can return a compact set of relevant files and symbols rather than an unstructured repository dump. When called with an edit intent, `search_codebase` also returns a decision card that helps the agent judge whether it has enough context to proceed.

## How it works

The first run downloads a local model and builds an index. Codebase Context combines keyword matching, semantic embeddings, and result ranking to find code by both exact terms and meaning. A client can pass an absolute `project` path to select the repository; after a successful selection, that project becomes the default for later calls in the same server process.

The MCP connection uses stdio by default, so the client starts the process when needed. One process can route requests to multiple repositories when each call identifies its project. Some clients may provide workspace roots, but explicit project selection is the documented way to avoid ambiguous repository choices.

The repository can also be queried from the terminal with commands for reindexing, producing a map, searching, and viewing patterns. `refresh_index` supports full or incremental indexing and can extract memory from Git history.

## Setup and configuration

Node.js 22 or newer is required. The published npm package can be launched with `npx -y codebase-context`. Claude Code and Codex CLI provide direct MCP add commands; Gemini CLI has its own add command as well. Cursor, VS Code with GitHub Copilot, and Windsurf use their respective MCP configuration files. Codex Desktop can use a project-level `.codex/config.toml` entry with a 120-second startup timeout.

After adding the server, start a new agent session in the target project. A useful first request supplies the repository's absolute path, asks Codebase Context to find a feature, and tells the agent to wait for indexing before opening relevant source files. A fixed default folder can be appended to the npm command as an absolute path.

## Tools and capabilities

- `search_codebase` performs hybrid search and can produce an edit-oriented decision card.
- `get_team_patterns` reports pattern frequencies, representative files, and conflicts.
- `get_symbol_references` returns concrete references, counts, and snippets for a symbol.
- `remember` records conventions, decisions, gotchas, or failures for the project.
- `get_memory` retrieves stored project knowledge using confidence-decay scoring.
- `get_codebase_metadata` describes project structure, frameworks, and dependencies.
- `get_style_guide` returns style rules detected for the current project.
- `detect_circular_dependencies` finds import cycles between files.
- `refresh_index` rebuilds or incrementally updates the index and extracts Git memory.
- `get_indexing_status` reports indexing progress and statistics.

## Limitations and notes

The default local provider keeps code and indexes on the machine, and does not require Docker, a GPU, or an API key. Cloud embedding providers are optional; selecting one sends code chunks to that provider. The AI client may separately send search results or file contents to its configured model provider.

Generated index files should be ignored by Git. Teams can choose to commit `.codebase-context/memory.json` when they want to share recorded project memory. Open issues include an Intel Mac indexing crash, custom OpenAI endpoint support, and Ollama support. The published benchmark reports 25.7% expected-file recovery versus 27.1% for jCodeMunch in a fixed retrieval comparison; it does not measure coding quality or establish an overall winner.

_Full upstream README: https://allmcps.com/mcp/patricksys-codebase-context/readme_