Skip to content

AGENT.md

Latest commit

 

History

History
495 lines (401 loc) · 14.5 KB

AGENT.md

File metadata and controls

495 lines (401 loc) · 14.5 KB

AI Agent Instructions for In Memoria MCP

This file provides instructions for AI agents (Claude Code, GitHub Copilot, Cursor, etc.) on how to effectively use the In Memoria MCP server for intelligent codebase navigation and analysis.

Quick Start Checklist

Every new session, follow this pattern:

  • 1. Call get_project_blueprint() to get instant context
  • 2. Check learningStatus in the blueprint response
  • 3. If recommendation === 'learning_recommended', call auto_learn_if_needed()
  • 4. Use the blueprint to understand tech stack, entry points, and key directories
  • 5. Leverage feature maps and semantic search for navigation

Tool Reference Card

🎯 Most Important Tools (Use These First)

Tool When to Use Key Feature
get_project_blueprint Every session start Instant context: tech stack, entry points, architecture, learning status
auto_learn_if_needed When learning recommended Smart learning with automatic staleness detection
predict_coding_approach Before implementing Get approach + file routing + patterns in one call
search_codebase Finding code Semantic (meaning), text (keywords), or pattern search
analyze_codebase Understanding files/dirs Token-efficient analysis with top concepts/patterns

📊 Complete Tool List (10 Core + 3 Monitoring)

Core Intelligence Tools (10)

  1. analyze_codebase - Analyze files or directories

    { path: string, includeFileContent?: boolean }

    Returns: Language, concepts (top 10), patterns (top 5), complexity

  2. search_codebase - Smart search (semantic/text/pattern)

    { query: string, type?: 'semantic'|'text'|'pattern', limit?: number }

    Returns: Scored results with context

  3. learn_codebase_intelligence - Deep learning

    { path: string, force?: boolean }

    Returns: Blueprint, concepts learned, patterns discovered

  4. get_project_blueprint - Instant project context ⭐

    { path?: string, includeFeatureMap?: boolean }

    Returns: Tech stack, entry points, key dirs, feature map, learning status

  5. get_semantic_insights - Query learned concepts

    { query?: string, conceptType?: string, limit?: number }

    Returns: Concepts, relationships, usage contexts

  6. get_pattern_recommendations - Pattern suggestions

    { problemDescription: string, currentFile?: string, includeRelatedFiles?: boolean }

    Returns: Patterns, examples, confidence, related files

  7. predict_coding_approach - Implementation guidance

    { problemDescription: string, context?: object, includeFileRouting?: boolean }

    Returns: Approach, patterns, complexity, target files

  8. get_developer_profile - Coding style and conventions

    { includeRecentActivity?: boolean, includeWorkContext?: boolean }

    Returns: Naming conventions, structural patterns, expertise

  9. contribute_insights - Record architectural decisions

    { type: string, content: object, confidence: number, sourceAgent: string }

    Returns: Success, insight ID

  10. auto_learn_if_needed - Smart auto-learning ⭐

    { path?: string, force?: boolean, skipLearning?: boolean, includeSetupSteps?: boolean }

    Returns: Action taken, intelligence status, setup steps

Monitoring Tools (3 - for debugging)

  1. get_system_status - System health check
  2. get_intelligence_metrics - Concept/pattern metrics
  3. get_performance_status - Performance diagnostics

Common Use Cases

Use Case 1: Starting Fresh in a New Codebase

// Step 1: Get the lay of the land
const blueprint = await mcp.get_project_blueprint({
  path: '.',
  includeFeatureMap: true
});

console.log('Tech Stack:', blueprint.techStack);
console.log('Entry Points:', blueprint.entryPoints);
console.log('Key Directories:', blueprint.keyDirectories);

// Step 2: Learn if needed
if (blueprint.learningStatus.recommendation !== 'ready') {
  await mcp.auto_learn_if_needed({
    path: '.',
    includeProgress: true
  });
}

// Step 3: You now have full context and intelligence!

Use Case 2: Implementing a New Feature

// Step 1: Get implementation approach with file routing
const approach = await mcp.predict_coding_approach({
  problemDescription: 'Add user password reset functionality',
  context: {
    feature: 'authentication',
    relatedFiles: ['src/auth/login.ts']
  },
  includeFileRouting: true
});

// Step 2: Get pattern recommendations for consistency
const patterns = await mcp.get_pattern_recommendations({
  problemDescription: 'Password reset with email validation',
  currentFile: approach.fileRouting.suggestedStartPoint,
  includeRelatedFiles: true
});

// Step 3: Search for similar implementations
const examples = await mcp.search_codebase({
  query: 'email validation auth',
  type: 'semantic',
  limit: 5
});

// Now you have: approach + target files + patterns + examples

Use Case 3: Understanding Existing Code

// Step 1: Analyze the mysterious directory
const analysis = await mcp.analyze_codebase({
  path: './src/services/payment'
});

// Step 2: Get semantic insights about key concepts
const insights = await mcp.get_semantic_insights({
  query: 'payment processing',
  limit: 10
});

// Step 3: Find all related code
const related = await mcp.search_codebase({
  query: 'stripe payment integration',
  type: 'semantic'
});

// Now you understand: structure + concepts + usage

Use Case 4: Code Review / Refactoring

// Step 1: Understand the coding conventions
const profile = await mcp.get_developer_profile({
  includeRecentActivity: true
});

// Step 2: Check if code follows project patterns
const patterns = await mcp.get_pattern_recommendations({
  problemDescription: 'Review API error handling consistency',
  currentFile: 'src/api/routes/users.ts',
  includeRelatedFiles: true
});

// Step 3: Find similar implementations for comparison
const similar = await mcp.search_codebase({
  query: 'try catch error middleware',
  type: 'pattern'
});

// Now you can: validate consistency + suggest improvements

🎯 Decision Tree: Which Tool to Use?

Need instant project context?
  → get_project_blueprint()

Need to learn/update intelligence?
  → auto_learn_if_needed() (smart) OR learn_codebase_intelligence() (force)

Need implementation guidance?
  → predict_coding_approach() with includeFileRouting=true

Need to find code?
  ├─ By meaning/concept? → search_codebase(type='semantic')
  ├─ By keyword? → search_codebase(type='text')
  └─ By pattern? → search_codebase(type='pattern')

Need to understand a file?
  → analyze_codebase(path='./specific/file.ts')

Need coding patterns?
  → get_pattern_recommendations() with includeRelatedFiles=true

Need to understand what codebase knows?
  → get_semantic_insights()

Need coding style/conventions?
  → get_developer_profile()

Made an architectural decision?
  → contribute_insights()

Debugging In Memoria?
  → get_system_status() / get_intelligence_metrics() / get_performance_status()

💡 Pro Tips for AI Agents

1. Always Check Learning Status First

const blueprint = await mcp.get_project_blueprint({ path: '.' });
if (blueprint.learningStatus.recommendation !== 'ready') {
  // Learning needed - call auto_learn_if_needed()
}

2. Use Feature Maps for Instant Navigation

const blueprint = await mcp.get_project_blueprint({
  path: '.',
  includeFeatureMap: true  // ← Get feature-to-file mapping
});

// Now you know which files handle which features:
// blueprint.featureMap['authentication'] = ['src/auth/login.ts', ...]

3. Combine Tools for Maximum Context

// Get everything in 3 calls:
const [blueprint, approach, patterns] = await Promise.all([
  mcp.get_project_blueprint({ path: '.', includeFeatureMap: true }),
  mcp.predict_coding_approach({ problemDescription: '...', includeFileRouting: true }),
  mcp.get_pattern_recommendations({ problemDescription: '...', includeRelatedFiles: true })
]);

// You now have: architecture + approach + files + patterns

4. Leverage Token-Efficient Responses

In Memoria automatically limits responses to avoid overwhelming the LLM:

  • File analysis: Top 10 concepts, top 5 patterns
  • Directory analysis: Top 15 concepts, top 10 patterns
  • Use get_semantic_insights if you need more concepts

5. Trust the Semantic Search

// ✅ GOOD: Semantic search understands meaning
await mcp.search_codebase({
  query: 'user authentication flow',
  type: 'semantic'
});

// ❌ BAD: Text search only matches keywords
await mcp.search_codebase({
  query: 'user authentication flow',
  type: 'text'  // Won't find conceptually related code
});

6. Record Insights for Future Sessions

// When you discover something important:
await mcp.contribute_insights({
  type: 'architectural_decision',
  content: {
    decision: 'All database queries use Prisma ORM',
    reasoning: 'Type safety and migration management',
    affectedFiles: ['src/db/', 'prisma/']
  },
  confidence: 0.95,
  sourceAgent: 'github-copilot'  // or 'claude-code', 'cursor', etc.
});

🚫 Common Mistakes to Avoid

❌ DON'T: Skip the learning check

// Bad - might work with stale/missing data
const results = await mcp.search_codebase({ query: '...' });

✅ DO: Always check and learn if needed

// Good - ensure intelligence is fresh
const blueprint = await mcp.get_project_blueprint({ path: '.' });
if (blueprint.learningStatus.recommendation !== 'ready') {
  await mcp.auto_learn_if_needed({ path: '.' });
}
const results = await mcp.search_codebase({ query: '...' });

❌ DON'T: Use text search for concepts

// Bad - won't find semantically related code
await mcp.search_codebase({ query: 'payment processing', type: 'text' });

✅ DO: Use semantic search for concepts

// Good - finds conceptually related code
await mcp.search_codebase({ query: 'payment processing', type: 'semantic' });

❌ DON'T: Ignore pattern recommendations

// Bad - implementing without checking patterns
// Just start coding...

✅ DO: Follow project patterns

// Good - check patterns first
const patterns = await mcp.get_pattern_recommendations({
  problemDescription: 'Create new API endpoint',
  includeRelatedFiles: true
});
// Now implement following the discovered patterns

❌ DON'T: Force re-learning unnecessarily

// Bad - wastes time re-learning when data is fresh
await mcp.auto_learn_if_needed({ path: '.', force: true });

✅ DO: Trust the staleness detection

// Good - only learns if needed
await mcp.auto_learn_if_needed({ path: '.', force: false });

🔄 Recommended Session Flow

// === SESSION START ===

// 1. Get instant context + learning status
const blueprint = await mcp.get_project_blueprint({
  path: '.',
  includeFeatureMap: true
});

// 2. Learn if needed (automatic staleness check)
if (blueprint.learningStatus.recommendation !== 'ready') {
  await mcp.auto_learn_if_needed({
    path: '.',
    includeProgress: false  // Set true if you want progress updates
  });
}

// 3. Understand coding style (once per session)
const profile = await mcp.get_developer_profile({
  includeRecentActivity: false,
  includeWorkContext: false
});

// === DURING WORK ===

// 4. For each task, get approach + routing
const approach = await mcp.predict_coding_approach({
  problemDescription: userRequest,
  includeFileRouting: true
});

// 5. Get patterns for consistency
const patterns = await mcp.get_pattern_recommendations({
  problemDescription: userRequest,
  currentFile: approach.fileRouting?.suggestedStartPoint,
  includeRelatedFiles: true
});

// 6. Search for relevant code as needed
const examples = await mcp.search_codebase({
  query: relevantConcept,
  type: 'semantic',
  limit: 5
});

// 7. Analyze specific files as needed
const fileAnalysis = await mcp.analyze_codebase({
  path: targetFile
});

// === SESSION END (Optional) ===

// 8. Record any insights discovered
await mcp.contribute_insights({
  type: 'architectural_decision',
  content: { /* ... */ },
  confidence: 0.9,
  sourceAgent: 'your-agent-name'
});

📊 Response Format Examples

get_project_blueprint Response

{
  "techStack": ["TypeScript", "React", "Node.js", "Express"],
  "entryPoints": {
    "web": "src/index.tsx",
    "api": "src/server.ts"
  },
  "keyDirectories": {
    "components": "src/components",
    "services": "src/services",
    "api": "src/api"
  },
  "architecture": "client-server with React SPA and Express API",
  "featureMap": {
    "authentication": ["src/auth/login.ts", "src/auth/register.ts"],
    "api": ["src/api/routes", "src/api/controllers"]
  },
  "learningStatus": {
    "hasIntelligence": true,
    "isStale": false,
    "conceptsStored": 147,
    "patternsStored": 23,
    "recommendation": "ready",
    "message": "Intelligence is ready! 147 concepts and 23 patterns available."
  }
}

predict_coding_approach Response

{
  "approach": "Create new auth middleware using existing JWT pattern",
  "suggestedPatterns": ["middleware_chain", "jwt_validation"],
  "estimatedComplexity": "medium",
  "reasoning": "Project uses JWT auth middleware in similar contexts",
  "confidence": 0.87,
  "fileRouting": {
    "intendedFeature": "authentication",
    "targetFiles": ["src/middleware/auth.ts", "src/auth/jwt.ts"],
    "workType": "enhancement",
    "suggestedStartPoint": "src/middleware/auth.ts"
  }
}

🎨 Agent-Specific Tips

For GitHub Copilot

  • Use the custom chat modes (see .vscode/copilot-chat-modes.json)
  • Reference this file in your workspace instructions
  • Always call get_project_blueprint() at the start of /explain or /new commands

For Claude Code

  • In Memoria integrates natively via MCP
  • Use the Task tool to delegate complex navigation to In Memoria
  • Combine blueprint + semantic search for exploration tasks

For Cursor

  • Add In Memoria MCP to your Cursor settings
  • Use composer mode with blueprint for context
  • Leverage semantic search in the chat panel

Remember: In Memoria provides intelligent, learned insights from the actual codebase. Trust its recommendations - they're based on real patterns, not generic suggestions.

Questions? Check the full documentation in README.md or the implementation roadmap in IMPLEMENTATION_ROADMAP.md.