ctx-engine

A cross-project architectural knowledge system for developers. Captures and connects knowledge about your codebases so you can understand impact across projects.

Why ctx-engine?

You ask:

"How can we incorporate role sending from the CMS into this project?"

Without ctx-engine:

"I'd need to explore the CMS codebase first. Can you point me to it?"

With ctx-engine:

"The CMS uses RoleService to emit role changes via Redis pub/sub. Your project already has a Redis connection in lib/cache.ts - you can subscribe to the roles:updated channel and sync with your local UserPermissions model.

But this violates the standard auth pattern used by your organization. You may want to go through the authentication service instead."

Cross-project context. Organizational standards. No discovery needed.

Quick Start

# Install globally
npm install -g ctx-engine

# Initialize and auto-configure Claude Code
ctx-engine init
ctx-engine setup-mcp

# Scan for projects
ctx-engine projects scan ~/Work

# Restart Claude Code - you're ready!

Or use without installing:

npx ctx-engine init
npx ctx-engine setup-mcp

Updating

# If installed globally
npm update -g ctx-engine

# Then restart Claude Code to load the new version

If using npx, the MCP server updates automatically when you restart Claude Code (npx checks for new versions periodically). To force the latest version immediately:

npx ctx-engine@latest mcp

How It Works

1. Index your projects - Context Engine scans your codebases to detect frameworks, auth patterns, databases, and external services
2. Capture knowledge organically - As you work, the agent stores architectural insights via MCP tools
3. Query across projects - Search concepts, check impact, find connections between projects

CLI Commands

# Setup
ctx-engine init                          # Initialize ~/.context-engine/
ctx-engine setup-mcp                     # Auto-configure Claude Code/Desktop
ctx-engine setup-mcp --force             # Overwrite existing MCP config

# Projects
ctx-engine projects scan <directory>     # Scan for git repos
ctx-engine projects add <path>           # Add single project
ctx-engine projects list                 # List all projects
ctx-engine projects reindex [name]       # Re-scan projects
ctx-engine projects remove <name>        # Remove a project

# Concepts
ctx-engine concepts search <query>       # Search concepts
ctx-engine concepts list                 # List all concepts
ctx-engine concepts show <name>          # Show concept details

# Impact analysis
ctx-engine impact <concept>              # Show affected projects

# Config
ctx-engine config get [key]              # Show config
ctx-engine config set <key> <value>      # Set config value

# MCP Server (used by Claude Code internally)
ctx-engine mcp                           # Start MCP server via stdio

MCP Tools

When connected via MCP, these tools are available.

Note: The agent may not automatically check context-engine for architecture questions. You can prompt it with: "Check context-engine for any relevant knowledge" or "Search concepts for auth patterns"

Concept Tools

• store_concept - Store architectural knowledge (proactively called during work)
• search_concepts - Search for relevant concepts
• get_concept - Get full concept with linked concepts
• list_concepts - List all concepts
• update_concept - Update existing concept
• delete_concept - Remove outdated concept
• link_concepts - Create relationship between concepts

Project Tools

• list_projects - Show indexed projects
• get_project_context - Full project details
• find_project_connections - How projects relate

Impact Tools

• get_impact - What's affected if concept changes
• get_shared_concepts - Common concepts between projects

Example Workflow

Month 1 - Normal development:

Session 1 (api-gateway):
User: "Help me debug this JWT validation issue"
Agent: [investigates, discovers auth flow touches user-service]
       [stores concept: "jwt-auth-flow" linking api-gateway, user-service]
       → Fixes bug, knowledge captured automatically

Month 6 - Comprehensive knowledge exists:

User: "I'm thinking of changing our auth approach"
Agent: [calls get_impact("jwt-auth-flow")]
       → "This would affect 4 projects. Here's what would need to change..."

Configuration

Settings stored in ~/.context-engine/config.json:

| Key | Values | Description | |-----|--------|-------------| | searchProvider | minisearch, embeddings | Search backend (default: minisearch) | | captureMode | notify, silent, ask | How agent reports stored concepts | | ollamaUrl | URL | Local Ollama for embeddings | | embeddingProvider | ollama, openai, anthropic | Embedding service | | embeddingApiKey | string | API key for embedding provider |

Storage

Data stored in ~/.context-engine/:

~/.context-engine/
├── config.json              # Settings
├── concepts/
│   ├── index.json           # Concept metadata
│   └── *.md                 # Concept content
├── links.json               # Concept relationships
├── projects/
│   └── index.json           # Project registry
└── cache/
    └── search-index.json    # MiniSearch index

Cross-Tool Compatibility

Works with any MCP-compatible client:

• Claude Code, Claude Desktop
• Cursor, VS Code (Continue), Windsurf, Cline, Zed
• JetBrains IDEs (via plugins)

Knowledge captured in one tool is available in all others.

Development

# Clone and install
git clone https://github.com/laspencer91/ctx-engine
cd ctx-engine
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm run test

# Run CLI locally
node dist/index.js

# Run MCP server locally
node dist/mcp.js

Contributing

1. Create a changeset for your changes:

   npx changeset

2. Submit a PR - CI will run tests on Mac, Linux, and Windows

License

MIT