Cortex MCP Server

Portfolio memory for AI agents.
Transforms your real project history into structured context that any AI assistant can query in real time.

⚠️ Status: Active MVP — functional and tested, but under active development. Feedback and contributions are welcome.

Table of Contents

• What It Is
• How It Works — The Three Layers
• Third-Party Repositories
• Quick Start
• Daily Workflow
• CLI
• What It Exposes via MCP
• Knowledge Store
• Architecture
• Tech Stack
• Development
• Positioning
• Usage Examples
• Context Overhead
• Roadmap
• References
• Support
• License

What It Is

Cortex MCP is a local server that implements the Model Context Protocol (MCP) — the open standard that lets AI assistants safely access external data.

It reads synthesized knowledge about your projects (a lightweight adjacency knowledge graph mapping relations between apps, technologies, and domains; patterns; observations; developer profile) and exposes it as tools, resources, and prompts consumable by any MCP-compatible agent.

The Problem

When you open Claude, Copilot, or Cursor in a project, the agent does not know:

• What other projects you have and how they connect
• Which stack you prefer and why
• Which patterns you use repeatedly
• Which components could be reused
• Your real experience with each technology

Every session starts from scratch — amnesiac pair programming.

The Solution

Cortex gives AI agents the same long-term memory you have as a developer. It accumulates knowledge across repositories and makes it instantly accessible in every session.

"AI is your mirror — it reveals who you are faster. If you are incompetent, it will produce bad things faster. If you are competent, it will produce good things faster." — Akita

Cortex works like the "CLAUDE.md" of your entire portfolio — not of one project, but of your whole career.

Complete Privacy

100% local, no cloud, no telemetry. Your data never leaves your machine.

How It Works — The Three Layers

Read this section before using. Most users only use Layer 1 and find the system "shallow". The real value is in Layers 2 and 3.

Cortex does not learn passively. It is a structured knowledge repository — the more you feed it, the more useful it becomes. The right mental model: a portfolio wiki that AI agents query in real time.

Layer 1 — Automatic Scanner (~20% of value)

cortex-mcp scan automatically detects:

• Technology stack (language, frameworks, databases, CI, Docker)
• Commit frequency and contributor history
• Recurring patterns across repositories
• Initial operator profile

Important limitation: the scanner only sees what is in the code and git history. It does not know why you chose a technology, what problems you encountered, or what you learned. A project with 1 commit (shallow clone) generates a very poor profile.

Layer 2 — Curation via MCP Tools (~60% of value)

The real power of Cortex is fed by you during work sessions:

⚠️ The real challenge: Layer 2 is where 60% of the value lives, but it requires actively remembering to call start_session, track_decision, and end_session every day.

Most developers will not sustain this habit without intentional effort. The gap between "installed" and "actually useful" is real — Cortex is only as good as the discipline you bring to curation.

The roadmap item "Dynamic prompts based on session history" points toward closing this gap, but it has not shipped yet. In the meantime: set up reminders, or make these calls part of your team's Definition of Done.

Layer 3 — Operator Profile (~20% of value)

The file knowledge/operator-profile.yaml is the developer's personal context. It is generated automatically by the scanner but requires manual curation to have real substance. Edit it directly:

identity:
  name: Your Name
  role: Your Role
  domain: Your areas of expertise
  github: https://github.com/your-username

Third-Party Repositories

You can add third-party repositories (public or private) as sources for analysis and comparison.

• Cortex incorporates these signals into your local context (stack, patterns, conventions, relations).
• This makes suggestions more contextualized, not "smarter" by magic.
• Use with judgment: respect licenses, confidentiality, and the separation between your own portfolio and external references.
• To avoid confusion, name external sources explicitly (e.g., --name ref-repo-name).

Quick Start

Prerequisites

• Node.js 20+
• Git

Install and Build

git clone https://github.com/BUGG1N/cortex-mcp.git cortex-mcp
cd cortex-mcp
npm install
npm run build

Generate Knowledge

# 1. Initialize the knowledge directory
npx cortex-mcp init

# 2. Add repositories (local, public GitHub, or private with token)
npx cortex-mcp add ./my-project
npx cortex-mcp add https://github.com/user/public-repo
npx cortex-mcp add https://github.com/user/private-repo --token ghp_xxx

# 3. Scan everything → generates knowledge files automatically
npx cortex-mcp scan

# 4. Start the MCP server
npx cortex-mcp

Security: the token is only used to authenticate Git operations and is not written into the remote URL of the cloned repository.

⚠️ Repositories cloned from a URL arrive with a shallow history. This causes the scanner to report 1 commit and degrades the quality of the generated profile. To fix:

cd repos/repo-name && git fetch --unshallow
cd ../.. && npx cortex-mcp scan

Configure Your Profile (recommended)

After the first scan, edit knowledge/operator-profile.yaml to add real context:

identity:
  name: Your Real Name
  role: Your Role (e.g. Founder CTO, Senior Engineer)
  domain: Your domains (e.g. fintech, IoT, healthcare)
  github: https://github.com/your-username

Without this, the profile defaults to name: Developer with expertise inferred only by commit volume.

Enrich With Real Context (where the value is)

The scanner generates a starting point. Useful knowledge comes from curation — via MCP tools with the agent connected:

# Examples of prompts that feed Cortex automatically:
"Record that I chose FastAPI over Flask because I needed native async"
"Add an observation to project-x that the accuracy bottleneck is dataset size, not architecture"
"Start a work session on project-y focused on Sprint 0"

As the agent executes these actions, Cortex persists the knowledge in YAML/JSONL files and makes it available in all future sessions.

Connect to Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "cortex": {
      "command": "node",
      "args": ["/absolute/path/to/cortex-mcp/dist/cli.js"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "cortex": {
      "command": "node",
      "args": ["C:\\dev\\cortex-mcp\\dist\\cli.js"]
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "cortex": {
      "command": "node",
      "args": ["/home/user/cortex-mcp/dist/cli.js"]
    }
  }
}

Restart Claude Desktop. You will see "cortex" available with tools and resources.

Connect to VS Code (GitHub Copilot)

Option 1 — Workspace only

In .vscode/mcp.json at the Cortex project root:

{
  "servers": {
    "cortex": {
      "command": "node",
      "args": ["<path>/dist/cli.js"]
    }
  }
}

Option 2 — Global (recommended for portfolios)

To use Cortex in any VS Code window (e.g., open another project and still have access to the full knowledge base), create the global MCP config file:

File location:

• Windows: %APPDATA%\Code\User\mcp.json
• macOS: ~/Library/Application Support/Code/User/mcp.json
• Linux: ~/.config/Code/User/mcp.json

{
  "servers": {
    "cortex": {
      "command": "node",
      "args": ["<path>/dist/cli.js"],
      "type": "stdio",
      "env": {
        "CORTEX_ROOT": "<path>"
      }
    }
  }
}

⚠️ CORTEX_ROOT is required in the global configuration. Without it, Cortex tries to find the root from the current working directory (cwd). When VS Code opens another project, the cwd is that project — and Cortex cannot find the knowledge/ folder, returning empty results. CORTEX_ROOT resolves this by explicitly pointing to the directory where data is stored.

Replace <path> with the absolute path to the Cortex root (e.g., C:\\dev\\CORTEX on Windows, /home/user/cortex on Linux).

Daily Workflow

Cortex is most useful when integrated into the natural development rhythm, not only used during initial setup.

Starting work on a project

[in the agent chat, Agent mode]
"Start a session on project X focused on [goal]"

start_session automatically injects: project stack, previous observations, relevant patterns, last recorded decisions, and operator context.

During work

"Record that I found an N+1 query problem in the /observations endpoint"
"Add the decision to use Alembic instead of manual migrations, reason: traceability"
"Note that the current model accuracy is below the target threshold — the bottleneck is dataset size, not architecture"

When finishing

"End the session with summary: [what was done], decisions: [list], next steps: [list]"

Returning after days

"What do you know about project X?" → the agent queries Cortex and summarizes current state
"What were the last decisions on project Y?" → returns curated decisions log
"What is my pattern for Python APIs?" → returns from the knowledge store

Periodic maintenance (weekly/biweekly)

# Update GitHub sources
npx cortex-mcp sync

# Re-scan after stack changes
npx cortex-mcp scan

# Diagnostics if something seems wrong
npx cortex-mcp doctor

CLI

cortex-mcp [command] [options]

Commands:
  init                    Initialize knowledge directory with empty files
  add <source>            Add a repository source (local path or GitHub URL)
  scan                    Scan all sources and update the knowledge base
  sync                    Update GitHub sources (pull latest)
  sources                 List all configured sources
  remove <name>           Remove a source
  serve                   Start the MCP server (default if no command given)
  doctor                  Diagnose the environment and knowledge files

Adding sources:
  cortex-mcp add ./local/path                  Local directory
  cortex-mcp add https://github.com/u/repo     Public GitHub repo (auto-clones)
  cortex-mcp add https://github.com/u/repo --token ghp_xxx   Private repo
  cortex-mcp add <source> --name my-name       Custom name
  cortex-mcp add <source> --branch develop     Specific branch

Options:
  --root <path>   Root directory (auto-detected from cwd)
  --no-watch      Disable file watching for hot-reload
  --help, -h      Show help
  --version, -v   Show version

Environment variables:

• CORTEX_ROOT — overrides root directory
• CORTEX_KNOWLEDGE_PATH — overrides knowledge files path
• GITHUB_TOKEN — GitHub token for private repositories (alternative to --token)

What It Exposes via MCP

Tools

Read tools are used automatically by the agent when answering questions. Curation tools are how knowledge is accumulated — each call persists something to YAML/JSONL files.

Reading and Querying

Curation and Knowledge Accumulation (use actively — this is where the real value is)

Resources

Prompts

Knowledge Store

Cortex reads these files from the knowledge/ directory. Each file has an origin and an expected utility level:

observations.jsonl is the most important file and the only one that is never populated automatically. A portfolio without observations only has detected stack — no memory of why things were done that way.

operator-profile.yaml is generated with name: Developer and expertise inferred by commit volume. For real substance, edit it manually adding name, domain, and personal context.

Example Data

The examples/knowledge/ directory contains a complete example portfolio with 4 apps, 14 technologies, 24 relations, 6 patterns, and 7 observations. Use it as a reference to understand the file structure or as a starting point for your own portfolio.

Architecture

cortex-mcp/
├── src/
│   ├── cli.ts                  # CLI entry point (init, add, scan, sync, serve)
│   ├── config.ts               # Config resolution (flags → yaml → env → defaults)
│   ├── index.ts                # Public API exports
│   ├── server.ts               # MCP server (stdio transport)
│   ├── types.ts                # Core TypeScript types
│   ├── engine/
│   │   ├── knowledge-engine.ts # Orchestrator — load, index, query
│   │   ├── yaml-parser.ts      # YAML/JSONL parsers
│   │   ├── search-index.ts     # MiniSearch full-text index
│   │   ├── graph-traversal.ts  # BFS/DFS graph queries
│   │   ├── file-reader.ts      # Repository file reader
│   │   └── file-watcher.ts     # Hot-reload via Chokidar
│   ├── mcp/
│   │   ├── tools/              # MCP tools
│   │   ├── resources/          # MCP resources
│   │   └── prompts/            # MCP prompts
│   ├── scanner/
│   │   ├── index.ts            # Scanner orchestrator
│   │   └── detectors/          # Stack auto-detection
│   │       ├── package-json.ts # Node.js / TypeScript
│   │       ├── python.ts       # Python (pip, poetry, pipenv)
│   │       ├── java.ts         # Java (Maven, Gradle)
│   │       ├── dotnet.ts       # .NET / C#
│   │       ├── go.ts           # Go (go.mod)
│   │       ├── rust.ts         # Rust (Cargo.toml)
│   │       ├── infra.ts        # Terraform, Kubernetes, Helm
│   │       ├── docker.ts       # Docker / containerization
│   │       ├── ci.ts           # CI/CD (GitHub Actions, GitLab, Jenkins)
│   │       └── git.ts          # Git metadata (commits, contributors)
│   ├── sources/
│   │   └── index.ts            # Source manager (local, GitHub)
│   └── writer/
│       └── index.ts            # Knowledge writer (YAML/JSONL persistence)
├── test/                       # 35 test files, 90 tests
├── package.json
├── tsconfig.json
└── tsup.config.ts

Design Principles

1. Zero heavy dependencies — No database, no Docker, no cloud. Reads local files, serves via stdio.
2. Synthesized knowledge, not raw code — The agent receives patterns, relations, and decisions — not 10k lines of code.
3. Generalizable — Works with any collection of repositories, not tied to a specific portfolio.
4. Fast — All data loaded in-memory at startup. Typical response < 100ms.
5. Privacy-first — All data stays on your machine. Nothing is sent externally.

Tech Stack

Development

Commands

npm install          # Install dependencies
npm run build        # Compile with tsup
npm run typecheck    # TypeScript check (zero errors expected)
npm run test         # Run tests
npm run dev          # Watch mode

Full contribution guide: CONTRIBUTING.md

Project Rules

• TypeScript strict — zero any, no @ts-ignore, no @ts-expect-error
• 100% in-memory data after startup — no external database
• MCP transport: stdio (JSON-RPC)
• Tool results capped at MAX_ITEMS=10 to avoid context overflow
• Hot-reload via file watcher (chokidar, debounce 500ms)
• Tests with Vitest — coverage focused on critical paths, error paths, and resilience

Code Conventions

Contribution Checklist

• Tests written and passing
• npm run build without errors
• npm run typecheck zero errors
• npm test all pass
• Code follows project conventions
• No any, no @ts-ignore

Positioning

This table compares features, not maturity. Cortex is an individual MVP-stage project; the other tools have teams, communities, and larger production histories.

Cortex combines multi-repo scanning + local technology graph + developer profile + delivery via local MCP.

Usage Examples

Building a New Project

Without Cortex:

You: "I need to build a real-time chat app"
Claude: "You can use Socket.IO with Express..."
(Generic advice, no context about your experience)

With Cortex:

You: "I need to build a real-time chat app"
Claude: "I can see in your portfolio that you have experience with Socket.IO
in 'collab-tool' and 'gaming-platform'. You prefer NestJS for structured APIs.
I can reuse your auth middleware from 'user-service'
and the Redis session pattern from 'marketplace-backend'."

Decisions With Context

Question: "GraphQL or REST for this project?"

Answer with Cortex: "Looking at your history: you used GraphQL in 2 of 12 projects, both complex dashboards with many data relations. For simple CRUD APIs, you consistently chose REST + Express. This project looks like CRUD, so REST aligns with your proven patterns."

Framework Analysis (NestJS)

Complete example of knowledge extraction from NestJS in examples/nestjs-analysis.md — demonstrating automatic detection of 18 technologies, enterprise patterns, and integration strategies.

Context Overhead

"Will loading all this knowledge eat up my context window?"

No — and here is the proof.

Token budget per session

Token counts measured on real start_session responses serialised as JSON-RPC. Your figures will be slightly lower if your knowledge base is sparse, or higher if you have dense operator-profile notes.

As a percentage of the context window

Return on investment

For ≈ 2 % of your context window you get injected into every session:

• Full technology stack of the active project
• Last recorded architectural decisions with rationale
• Accumulated patterns across all your repositories
• Pitfalls and observations logged over time
• Your complete operator profile (domain, preferences, conventions)

Compare that to a typical codebase dump with Repomix (50,000–300,000 tokens — 25–150 % of a 200k window). Cortex gives you the knowledge layer — the distilled "why" and "how" — at a fraction of the cost of pasting raw source files.

The ratio: ~1–2 % of context window → portfolio-wide memory. That is a return of 50–100× on context invested.

Roadmap

• Multi-stack scanner (10 languages/platforms)
• 29 MCP tools + resources + prompts
• Runtime validation with Zod in all handlers
• 90 tests in 35 files (happy paths + error paths + resilience + concurrency + CLI e2e + MCP contract + stdio integration)
• CLI doctor for first-use diagnostics
• GitHub Actions CI (Node 20 + 22)
• Example data directory (examples/knowledge/)
• Semantic search with embeddings (currently lexical + synonym expansion)
• Plugin ecosystem for custom detectors
• Local web dashboard to visualize the knowledge graph
• Dynamic prompts based on session history
• npm publication (npx cortex-mcp init)

References

Support

If Cortex saves you time, consider buying me a coffee ☕

Crypto

Tip: Use a wallet created specifically for donations — never your main or trading wallet. For Ethereum you can register a human-readable ENS name (e.g. yourname.eth) so the address is easy to share and verify.

PIX (Brazil)

Chave PIX: 4978dd10-e12d-42e8-8a32-257ad00594e3

You can also support the project by:

• ⭐ Starring the repository
• 🐛 Reporting bugs or requesting features via Issues
• 🔀 Opening a pull request

License

MIT