In-Memoria

# GitHub Copilot Instructions for In Memoria

This repository includes **In Memoria**, an intelligent MCP (Model Context Protocol) server that provides codebase intelligence through semantic analysis, pattern recognition, and smart navigation.

## ⚠️ CRITICAL: Path Parameter Usage

**ALWAYS provide absolute paths to In-Memoria tools. NEVER rely on default values.**

### Why This Matters

In MCP server context, `process.cwd()` is unpredictable and may point to the wrong directory (like `/home/user` instead of your project). Always specify the path explicitly to avoid analyzing the wrong codebase or creating databases in unexpected locations.

```typescript
// ❌ WRONG - May use incorrect directory
await use_mcp_tool('in-memoria', 'get_project_blueprint', {
  includeFeatureMap: true
});

// ✅ CORRECT - Always specify path explicitly
await use_mcp_tool('in-memoria', 'get_project_blueprint', {
  path: '/absolute/path/to/project',  // Use workspace root
  includeFeatureMap: true
});
```

### Getting the Project Path

- In VS Code: Use `${workspaceFolder}` or workspace root API
- Ensure it's an **absolute path** (starts with `/` on Unix, `C:\` on Windows)
- Be **consistent** across all tool calls in a session
- Verify the path exists before calling tools

### Path Convention for All Tools

Every tool that accepts a `path` parameter should receive:
- **Absolute paths** to the project root directory
- **Same path** throughout the entire session
- **No relative paths** like `.` or `./src` (resolve them first)

---

## Core Capabilities

In Memoria learns from codebases and provides:
- **Instant project context** - Tech stack, entry points, key directories, architecture overview
- **Semantic search** - Find code by meaning, not just keywords
- **Pattern recognition** - Discover coding patterns and best practices
- **Smart file routing** - Navigate to relevant files from vague requests
- **Coding approach predictions** - Get implementation suggestions based on learned patterns

## How to Use In Memoria MCP Tools

### 🚀 Quick Start Pattern

**ALWAYS start new sessions with:**
```typescript
// IMPORTANT: Get the absolute project path first
const projectPath = '/absolute/path/to/project'; // or ${workspaceFolder}

// 1. Get instant project blueprint
const blueprint = await use_mcp_tool('in-memoria', 'get_project_blueprint', {
  path: projectPath,  // Always provide path!
  includeFeatureMap: true
});

// Check if learning is needed
if (blueprint.learningStatus.recommendation === 'learning_recommended') {
  // 2. Auto-learn from codebase if needed
  await use_mcp_tool('in-memoria', 'auto_learn_if_needed', {
    path: projectPath,  // Same path throughout session
    includeProgress: true
  });
}
```

This eliminates cold-start exploration and gives you instant context.

### 📊 The 10 Core Tools (Use These Frequently)

#### 1. **analyze_codebase** - Comprehensive Analysis
Use for: Understanding files or directories
```typescript
const projectPath = '/absolute/path/to/project';

// Analyze a specific file
await use_mcp_tool('in-memoria', 'analyze_codebase', {
  path: `${projectPath}/src/components/Header.tsx`
});

// Analyze entire directory
await use_mcp_tool('in-memoria', 'analyze_codebase', {
  path: `${projectPath}/src`
});
```
Returns: Languages, frameworks, complexity, top concepts, top patterns (token-efficient)

#### 2. **search_codebase** - Smart Search
Use for: Finding code by meaning, text, or patterns
```typescript
// Semantic search (finds by meaning)
await use_mcp_tool('in-memoria', 'search_codebase', {
  query: 'authentication logic',
  type: 'semantic',
  limit: 10
});

// Text search (fast keyword matching)
await use_mcp_tool('in-memoria', 'search_codebase', {
  query: 'fetchUserData',
  type: 'text'
});
```

#### 3. **get_project_blueprint** - Instant Context
Use for: Cold-start elimination, understanding project structure
```typescript
await use_mcp_tool('in-memoria', 'get_project_blueprint', {
  path: '/absolute/path/to/project',  // ALWAYS provide path
  includeFeatureMap: true
});
```
Returns: Tech stack, entry points, key directories, feature-to-file mapping, **learning status**

#### 4. **predict_coding_approach** - Implementation Guidance
Use for: Getting suggestions before writing code
```typescript
await use_mcp_tool('in-memoria', 'predict_coding_approach', {
  problemDescription: 'Add user profile editing feature',
  context: { currentFile: 'src/pages/profile.tsx' },
  includeFileRouting: true
});
```
Returns: Recommended approach, patterns, complexity estimate, target files

#### 5. **get_pattern_recommendations** - Pattern Suggestions
Use for: Maintaining consistency with existing code
```typescript
await use_mcp_tool('in-memoria', 'get_pattern_recommendations', {
  problemDescription: 'Create new API endpoint for user search',
  currentFile: 'src/api/routes/users.ts',
  includeRelatedFiles: true
});
```
Returns: Patterns to follow, examples, confidence scores, related files

#### 6. **get_semantic_insights** - Explore Concepts
Use for: Understanding what the codebase knows
```typescript
await use_mcp_tool('in-memoria', 'get_semantic_insights', {
  query: 'authentication',
  limit: 10
});
```
Returns: Related concepts, usage contexts, relationships

#### 7. **learn_codebase_intelligence** - Deep Learning
Use for: Initial learning or re-learning after major changes
```typescript
await use_mcp_tool('in-memoria', 'learn_codebase_intelligence', {
  path: '.',
  force: false  // Set true to force re-learning
});
```
Returns: Concepts learned, patterns discovered, blueprint data

#### 8. **auto_learn_if_needed** - Smart Automation
Use for: Automatic learning with setup verification
```typescript
await use_mcp_tool('in-memoria', 'auto_learn_if_needed', {
  path: '.',
  force: false,
  includeProgress: true,
  skipLearning: false,      // Set true for quick setup without learning
  includeSetupSteps: true   // Get detailed setup verification
});
```
Returns: Action taken, status, intelligence metrics

#### 9. **get_developer_profile** - Understand Coding Style
Use for: Learning project conventions and preferences
```typescript
await use_mcp_tool('in-memoria', 'get_developer_profile', {
  includeRecentActivity: true,
  includeWorkContext: true
});
```
Returns: Naming conventions, structural patterns, testing approach, expertise areas

#### 10. **contribute_insights** - Record Learnings
Use for: Teaching In Memoria about the codebase

**⚠️ IMPORTANT:** The `content` field is REQUIRED and must contain the actual insight data.

```typescript
// ✅ CORRECT - content field with insight details
await use_mcp_tool('in-memoria', 'contribute_insights', {
  type: 'best_practice',
  content: {  // REQUIRED FIELD
    practice: 'Use React Query for all API calls',
    reasoning: 'Provides better caching and error handling',
    affectedFiles: ['src/hooks/', 'src/api/']
  },
  confidence: 0.95,
  sourceAgent: 'github-copilot',
  sessionUpdate: {  // OPTIONAL
    feature: 'API integration',
    files: ['src/api/users.ts']
  }
});

// ❌ WRONG - missing content field
await use_mcp_tool('in-memoria', 'contribute_insights', {
  type: 'best_practice',
  confidence: 0.9,
  sourceAgent: 'github-copilot'
  // ERROR: content is required!
});
```

### 🔍 Monitoring Tools (Debug/System)

Use these for debugging and system health:
- `get_system_status` - Database status, learning state
- `get_intelligence_metrics` - Concept/pattern counts, quality scores
- `get_performance_status` - Vector DB health, query performance
- `health_check` - Verify setup and configuration (checks paths, database, API keys)

**Example: Run health check**
```typescript
// Diagnose setup issues
const health = await use_mcp_tool('in-memoria', 'health_check', {
  path: '/absolute/path/to/project'
});

// Check status: 'healthy', 'warning', or 'error'
console.log(health.status);       // Overall status
console.log(health.summary);      // Human-readable summary
console.log(health.checks);       // Detailed check results
```

## 🎯 Usage Patterns

### Pattern 1: Starting a New Feature
```typescript
// 1. Get project context
const blueprint = await use_mcp_tool('in-memoria', 'get_project_blueprint', { path: '.' });

// 2. Find similar features
const similar = await use_mcp_tool('in-memoria', 'search_codebase', {
  query: 'user profile features',
  type: 'semantic'
});

// 3. Get implementation approach
const approach = await use_mcp_tool('in-memoria', 'predict_coding_approach', {
  problemDescription: 'Add profile photo upload',
  includeFileRouting: true
});

// 4. Get pattern recommendations
const patterns = await use_mcp_tool('in-memoria', 'get_pattern_recommendations', {
  problemDescription: 'Profile photo upload with validation',
  currentFile: approach.fileRouting.suggestedStartPoint
});

// Now you have: context, similar code, approach, patterns, target files
```

### Pattern 2: Understanding Unfamiliar Code
```typescript
// 1. Analyze the file/directory
const analysis = await use_mcp_tool('in-memoria', 'analyze_codebase', {
  path: './src/auth'
});

// 2. Get semantic insights about key concepts
const insights = await use_mcp_tool('in-memoria', 'get_semantic_insights', {
  query: 'authentication flow'
});

// 3. Search for usage examples
const examples = await use_mcp_tool('in-memoria', 'search_codebase', {
  query: 'auth.login',
  type: 'text'
});
```

### Pattern 3: Debugging/Code Review
```typescript
// 1. Get developer profile to understand conventions
const profile = await use_mcp_tool('in-memoria', 'get_developer_profile', {});

// 2. Check if current code follows patterns
const patterns = await use_mcp_tool('in-memoria', 'get_pattern_recommendations', {
  problemDescription: 'Review error handling in API routes',
  currentFile: 'src/api/routes/users.ts'
});

// 3. Find similar implementations for comparison
const similar = await use_mcp_tool('in-memoria', 'search_codebase', {
  query: 'error handling middleware',
  type: 'pattern'
});
```

## 🚫 What NOT to Do

❌ **Don't guess file paths** - Use `get_project_blueprint` to discover structure
❌ **Don't skip learning checks** - Always call `auto_learn_if_needed` at session start
❌ **Don't use text search for concepts** - Use `semantic` search for meaning-based queries
❌ **Don't ignore pattern recommendations** - They reflect actual codebase conventions
❌ **Don't re-learn unnecessarily** - Check `blueprint.learningStatus` before forcing re-learning

## 💡 Pro Tips

1. **Token Efficiency**: `analyze_codebase` automatically limits concepts/patterns to top 10-15 to avoid overwhelming responses
2. **Feature Mapping**: Use `includeFeatureMap: true` in `get_project_blueprint` to get instant feature-to-file routing
3. **Smart Routing**: Set `includeFileRouting: true` in `predict_coding_approach` to get target files automatically
4. **Related Files**: Set `includeRelatedFiles: true` in `get_pattern_recommendations` to discover similar implementations
5. **Work Context**: Set `includeWorkContext: true` in `get_developer_profile` to see session history and recent decisions

## 🔄 Typical Session Flow

```typescript
// Session Start
1. get_project_blueprint({ path: '.' })
   → Get instant context + check learning status

2. auto_learn_if_needed({ path: '.' })
   → Learn if needed (only runs if data is stale/missing)

// During Development
3. predict_coding_approach({ problemDescription: '...', includeFileRouting: true })
   → Get implementation approach + target files

4. get_pattern_recommendations({ problemDescription: '...', includeRelatedFiles: true })
   → Get patterns + similar files

5. search_codebase({ query: '...', type: 'semantic' })
   → Find relevant code

6. analyze_codebase({ path: './specific/file.ts' })
   → Understand specific files

// Session End (Optional)
7. contribute_insights({ type: '...', content: {...} })
   → Record learnings for future sessions
```

## 🎨 Best Practices

- **Always check learning status** before starting work
- **Use semantic search** for concept-based queries
- **Leverage feature maps** for instant navigation
- **Follow pattern recommendations** to maintain consistency
- **Contribute insights** when you discover architectural decisions
- **Use token-efficient responses** - tools automatically limit output for LLM efficiency

## 📚 Additional Resources

- Full API documentation: See tool schemas in `src/mcp-server/tools/`
- Implementation roadmap: `IMPLEMENTATION_ROADMAP.md`
- Architecture overview: `README.md`

---

**Remember**: In Memoria learns from the codebase and provides **intelligent, context-aware suggestions**. Trust the pattern recommendations and semantic insights - they reflect actual code in the project.