Positioning & Differentiation

How ContextManager fits into the VS Code / Copilot ecosystem alongside instruction files, prompt files, and skill files.

The Four-Layer Ecosystem

There are four distinct categories of AI guidance in VS Code today. They are not competing - each one solves a different problem.

graph TB
    subgraph L1[Layer 1: Global Behavior]
        L1D[copilot-instructions.md]
    end
    subgraph L2[Layer 2: Task Workflows]
        L2D[prompt.md files]
    end
    subgraph L3[Layer 3: Agent Capabilities]
        L3D[SKILL.md files]
    end
    subgraph L4[Layer 4: Project Knowledge]
        L4D[ContextManager]
    end

    style L4 fill:#1f6feb,stroke:#388bfd,color:#fff
    style L4D fill:#1f6feb,stroke:#388bfd,color:#fff

Layers 1–3 are author-first: you write them at setup time. Layer 4 is discover-first: knowledge accumulates dynamically as you work.

What Makes ContextManager Different

Static files describe the rules. ContextManager records the reasoning.

A copilot-instructions.md might say “use the repository pattern.” ContextManager captures why your specific project uses it, which classes implement it, which ones deviate for a reason, and what the team debated before landing there.

Knowledge is generated by AI, not just consumed by it.

Every other tool is author-first: you write the file, the AI reads it. ContextManager inverts this:

  • Auto-capture and card queue — AI responses are captured and distilled into cards
  • #saveCard — save a new knowledge card on demand
  • #editCard — improve an existing card

Three kinds of persistent memory, not one.

Store What It Holds
Knowledge Cards Architecture decisions, patterns, deep explanations
Project Intelligence Conventions, tool hints, working notes

Smart injection, not “dump everything.”

  • Progressive disclosure - 3-tier card injection
  • Tiered intelligence - confirmed always, relevant matched, rest on demand
  • Staleness signals - 30+ day cards flagged for the AI
  • Usage tracking - surfaces dead cards and duplicates

Per-project scope, not global scope.

Switching projects means the AI’s entire knowledge base switches instantly.

Searchable, not just readable.

BM25 full-text search across cards, cache, sessions, conventions, hints, and notes - with camelCase tokenization, quoted phrases, prefix matching, and OR fallback.

Team knowledge, not personal notes.

Export to git-tracked Markdown for team onboarding.

Decision Guide

Scenario Right Tool
“Always use strict null checks” copilot-instructions.md
“When I ask for a test, use this structure” *.prompt.md
“Here’s how to publish this extension, step by step” SKILL.md
“Here’s what the auth flow actually does in our app” ContextManager knowledge card
“We tried EventBus and abandoned it” ContextManager convention
“Search TabStripController not tab strip” ContextManager tool hint
“Onboard a new dev without writing a doc” Export cards as git-tracked Markdown

The Progression of a Real Project

Phase 1 - Discovery. You explore with the agent. Card queue captures insights automatically. Use #saveCard or the dashboard to create cards on demand. Intelligence learns which patterns hold in practice.

Phase 2 - Building. Work proceeds normally. Auto-capture records context. Intelligence accumulates.

Phase 3 - Cumulative leverage. The AI knows the codebase - not because the model improved, but because accumulated knowledge is there from session start. The next developer lands in the same place in an hour instead of a week.

Three Personas

The Explorer

Every key discovery becomes a knowledge card automatically. No separate documentation step.

The Builder

Autonomous AI agents with accumulated intelligence. Context window resets don’t reset progress.

The Tech Lead

Accumulated knowledge is git-tracked Markdown. New hires get it on day one. Export cards as Markdown files for any newcomer.

What ContextManager Is Not

  • Not a replacement for copilot-instructions.md - global standards belong there
  • Not a prompt library - task templates belong in .prompt.md files
  • Not an agent framework - works with Copilot’s native agent mode
  • Not a documentation generator - cards are working memory for AI, with export as a bridge
  • Not a generic memory MCP server - per-project, git-integrated, dashboard-driven