mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
refactor: PM Agent complete independence from external MCP servers (#439)
* refactor: PM Agent complete independence from external MCP servers ## Summary Implement graceful degradation to ensure PM Agent operates fully without any MCP server dependencies. MCP servers now serve as optional enhancements rather than required components. ## Changes ### Responsibility Separation (NEW) - **PM Agent**: Development workflow orchestration (PDCA cycle, task management) - **mindbase**: Memory management (long-term, freshness, error learning) - **Built-in memory**: Session-internal context (volatile) ### 3-Layer Memory Architecture with Fallbacks 1. **Built-in Memory** [OPTIONAL]: Session context via MCP memory server 2. **mindbase** [OPTIONAL]: Long-term semantic search via airis-mcp-gateway 3. **Local Files** [ALWAYS]: Core functionality in docs/memory/ ### Graceful Degradation Implementation - All MCP operations marked with [ALWAYS] or [OPTIONAL] - Explicit IF/ELSE fallback logic for every MCP call - Dual storage: Always write to local files + optionally to mindbase - Smart lookup: Semantic search (if available) → Text search (always works) ### Key Fallback Strategies **Session Start**: - mindbase available: search_conversations() for semantic context - mindbase unavailable: Grep docs/memory/*.jsonl for text-based lookup **Error Detection**: - mindbase available: Semantic search for similar past errors - mindbase unavailable: Grep docs/mistakes/ + solutions_learned.jsonl **Knowledge Capture**: - Always: echo >> docs/memory/patterns_learned.jsonl (persistent) - Optional: mindbase.store() for semantic search enhancement ## Benefits - ✅ Zero external dependencies (100% functionality without MCP) - ✅ Enhanced capabilities when MCPs available (semantic search, freshness) - ✅ No functionality loss, only reduced search intelligence - ✅ Transparent degradation (no error messages, automatic fallback) ## Related Research - Serena MCP investigation: Exposes tools (not resources), memory = markdown files - mindbase superiority: PostgreSQL + pgvector > Serena memory features - Best practices alignment: /Users/kazuki/github/airis-mcp-gateway/docs/mcp-best-practices.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: add PR template and pre-commit config - Add structured PR template with Git workflow checklist - Add pre-commit hooks for secret detection and Conventional Commits - Enforce code quality gates (YAML/JSON/Markdown lint, shellcheck) NOTE: Execute pre-commit inside Docker container to avoid host pollution: docker compose exec workspace uv tool install pre-commit docker compose exec workspace pre-commit run --all-files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: update PM Agent context with token efficiency architecture - Add Layer 0 Bootstrap (150 tokens, 95% reduction) - Document Intent Classification System (5 complexity levels) - Add Progressive Loading strategy (5-layer) - Document mindbase integration incentive (38% savings) - Update with 2025-10-17 redesign details * refactor: PM Agent command with progressive loading - Replace auto-loading with User Request First philosophy - Add 5-layer progressive context loading - Implement intent classification system - Add workflow metrics collection (.jsonl) - Document graceful degradation strategy * fix: installer improvements Update installer logic for better reliability * docs: add comprehensive development documentation - Add architecture overview - Add PM Agent improvements analysis - Add parallel execution architecture - Add CLI install improvements - Add code style guide - Add project overview - Add install process analysis * docs: add research documentation Add LLM agent token efficiency research and analysis * docs: add suggested commands reference * docs: add session logs and testing documentation - Add session analysis logs - Add testing documentation * feat: migrate CLI to typer + rich for modern UX ## What Changed ### New CLI Architecture (typer + rich) - Created `superclaude/cli/` module with modern typer-based CLI - Replaced custom UI utilities with rich native features - Added type-safe command structure with automatic validation ### Commands Implemented - **install**: Interactive installation with rich UI (progress, panels) - **doctor**: System diagnostics with rich table output - **config**: API key management with format validation ### Technical Improvements - Dependencies: Added typer>=0.9.0, rich>=13.0.0, click>=8.0.0 - Entry Point: Updated pyproject.toml to use `superclaude.cli.app:cli_main` - Tests: Added comprehensive smoke tests (11 passed) ### User Experience Enhancements - Rich formatted help messages with panels and tables - Automatic input validation with retry loops - Clear error messages with actionable suggestions - Non-interactive mode support for CI/CD ## Testing ```bash uv run superclaude --help # ✓ Works uv run superclaude doctor # ✓ Rich table output uv run superclaude config show # ✓ API key management pytest tests/test_cli_smoke.py # ✓ 11 passed, 1 skipped ``` ## Migration Path - ✅ P0: Foundation complete (typer + rich + smoke tests) - 🔜 P1: Pydantic validation models (next sprint) - 🔜 P2: Enhanced error messages (next sprint) - 🔜 P3: API key retry loops (next sprint) ## Performance Impact - **Code Reduction**: Prepared for -300 lines (custom UI → rich) - **Type Safety**: Automatic validation from type hints - **Maintainability**: Framework primitives vs custom code 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: consolidate documentation directories Merged claudedocs/ into docs/research/ for consistent documentation structure. Changes: - Moved all claudedocs/*.md files to docs/research/ - Updated all path references in documentation (EN/KR) - Updated RULES.md and research.md command templates - Removed claudedocs/ directory - Removed ClaudeDocs/ from .gitignore Benefits: - Single source of truth for all research reports - PEP8-compliant lowercase directory naming - Clearer documentation organization - Prevents future claudedocs/ directory creation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * perf: reduce /sc:pm command output from 1652 to 15 lines - Remove 1637 lines of documentation from command file - Keep only minimal bootstrap message - 99% token reduction on command execution - Detailed specs remain in superclaude/agents/pm-agent.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * perf: split PM Agent into execution workflows and guide - Reduce pm-agent.md from 735 to 429 lines (42% reduction) - Move philosophy/examples to docs/agents/pm-agent-guide.md - Execution workflows (PDCA, file ops) stay in pm-agent.md - Guide (examples, quality standards) read once when needed Token savings: - Agent loading: ~6K → ~3.5K tokens (42% reduction) - Total with pm.md: 71% overall reduction 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: consolidate PM Agent optimization and pending changes PM Agent optimization (already committed separately): - superclaude/commands/pm.md: 1652→14 lines - superclaude/agents/pm-agent.md: 735→429 lines - docs/agents/pm-agent-guide.md: new guide file Other pending changes: - setup: framework_docs, mcp, logger, remove ui.py - superclaude: __main__, cli/app, cli/commands/install - tests: test_ui updates - scripts: workflow metrics analysis tools - docs/memory: session state updates 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: simplify MCP installer to unified gateway with legacy mode ## Changes ### MCP Component (setup/components/mcp.py) - Simplified to single airis-mcp-gateway by default - Added legacy mode for individual official servers (sequential-thinking, context7, magic, playwright) - Dynamic prerequisites based on mode: - Default: uv + claude CLI only - Legacy: node (18+) + npm + claude CLI - Removed redundant server definitions ### CLI Integration - Added --legacy flag to setup/cli/commands/install.py - Added --legacy flag to superclaude/cli/commands/install.py - Config passes legacy_mode to component installer ## Benefits - ✅ Simpler: 1 gateway vs 9+ individual servers - ✅ Lighter: No Node.js/npm required (default mode) - ✅ Unified: All tools in one gateway (sequential-thinking, context7, magic, playwright, serena, morphllm, tavily, chrome-devtools, git, puppeteer) - ✅ Flexible: --legacy flag for official servers if needed ## Usage ```bash superclaude install # Default: airis-mcp-gateway (推奨) superclaude install --legacy # Legacy: individual official servers ``` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: rename CoreComponent to FrameworkDocsComponent and add PM token tracking ## Changes ### Component Renaming (setup/components/) - Renamed CoreComponent → FrameworkDocsComponent for clarity - Updated all imports in __init__.py, agents.py, commands.py, mcp_docs.py, modes.py - Better reflects the actual purpose (framework documentation files) ### PM Agent Enhancement (superclaude/commands/pm.md) - Added token usage tracking instructions - PM Agent now reports: 1. Current token usage from system warnings 2. Percentage used (e.g., "27% used" for 54K/200K) 3. Status zone: 🟢 <75% | 🟡 75-85% | 🔴 >85% - Helps prevent token exhaustion during long sessions ### UI Utilities (setup/utils/ui.py) - Added new UI utility module for installer - Provides consistent user interface components ## Benefits - ✅ Clearer component naming (FrameworkDocs vs Core) - ✅ PM Agent token awareness for efficiency - ✅ Better visual feedback with status zones 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor(pm-agent): minimize output verbosity (471→284 lines, 40% reduction) **Problem**: PM Agent generated excessive output with redundant explanations - "System Status Report" with decorative formatting - Repeated "Common Tasks" lists user already knows - Verbose session start/end protocols - Duplicate file operations documentation **Solution**: Compress without losing functionality - Session Start: Reduced to symbol-only status (🟢 branch | nM nD | token%) - Session End: Compressed to essential actions only - File Operations: Consolidated from 2 sections to 1 line reference - Self-Improvement: 5 phases → 1 unified workflow - Output Rules: Explicit constraints to prevent Claude over-explanation **Quality Preservation**: - ✅ All core functions retained (PDCA, memory, patterns, mistakes) - ✅ PARALLEL Read/Write preserved (performance critical) - ✅ Workflow unchanged (session lifecycle intact) - ✅ Added output constraints (prevents verbose generation) **Reduction Method**: - Deleted: Explanatory text, examples, redundant sections - Retained: Action definitions, file paths, core workflows - Added: Explicit output constraints to enforce minimalism **Token Impact**: 40% reduction in agent documentation size **Before**: Verbose multi-section report with task lists **After**: Single line status: 🟢 integration | 15M 17D | 36% 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: consolidate MCP integration to unified gateway **Changes**: - Remove individual MCP server docs (superclaude/mcp/*.md) - Remove MCP server configs (superclaude/mcp/configs/*.json) - Delete MCP docs component (setup/components/mcp_docs.py) - Simplify installer (setup/core/installer.py) - Update components for unified gateway approach **Rationale**: - Unified gateway (airis-mcp-gateway) provides all MCP servers - Individual docs/configs no longer needed (managed centrally) - Reduces maintenance burden and file count - Simplifies installation process **Files Removed**: 17 MCP files (docs + configs) **Installer Changes**: Removed legacy MCP installation logic 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: update version and component metadata - Bump version (pyproject.toml, setup/__init__.py) - Update CLAUDE.md import service references - Reflect component structure changes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: kazuki <kazuki@kazukinoMacBook-Air.local> Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
kazuki nakai
558
docs/research/research_repository_scoped_memory_2025-10-16.md
Normal file
558
docs/research/research_repository_scoped_memory_2025-10-16.md
Normal file
@@ -0,0 +1,558 @@
|
||||
# Repository-Scoped Memory Management for AI Coding Assistants
|
||||
**Research Report | 2025-10-16**
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This research investigates best practices for implementing repository-scoped memory management in AI coding assistants, with specific focus on SuperClaude PM Agent integration. Key findings indicate that **local file storage with git repository detection** is the industry standard for session isolation, offering optimal performance and developer experience.
|
||||
|
||||
### Key Recommendations for SuperClaude
|
||||
|
||||
1. **✅ Adopt Local File Storage**: Store memory in repository-specific directories (`.superclaude/memory/` or `docs/memory/`)
|
||||
2. **✅ Use Git Detection**: Implement `git rev-parse --git-dir` for repository boundary detection
|
||||
3. **✅ Prioritize Simplicity**: Start with file-based approach before considering databases
|
||||
4. **✅ Maintain Backward Compatibility**: Support future cross-repository intelligence as optional feature
|
||||
|
||||
---
|
||||
|
||||
## 1. Industry Best Practices
|
||||
|
||||
### 1.1 Cursor IDE Memory Architecture
|
||||
|
||||
**Implementation Pattern**:
|
||||
```
|
||||
project-root/
|
||||
├── .cursor/
|
||||
│ └── rules/ # Project-specific configuration
|
||||
├── .git/ # Repository boundary marker
|
||||
└── memory-bank/ # Session context storage
|
||||
├── project_context.md
|
||||
├── progress_history.md
|
||||
└── architectural_decisions.md
|
||||
```
|
||||
|
||||
**Key Insights**:
|
||||
- Repository-level isolation using `.cursor/rules` directory
|
||||
- Memory Bank pattern: structured knowledge repository for cross-session context
|
||||
- MCP integration (Graphiti) for sophisticated memory management across sessions
|
||||
- **Problem**: Users report context loss mid-task and excessive "start new chat" prompts
|
||||
|
||||
**Relevance to SuperClaude**: Validates local directory approach with repository-scoped configuration.
|
||||
|
||||
---
|
||||
|
||||
### 1.2 GitHub Copilot Workspace Context
|
||||
|
||||
**Implementation Pattern**:
|
||||
- Remote code search indexes for GitHub/Azure DevOps repositories
|
||||
- Local indexes for non-cloud repositories (limit: 2,500 files)
|
||||
- Respects `.gitignore` for index exclusion
|
||||
- Workspace-level context with repository-specific boundaries
|
||||
|
||||
**Key Insights**:
|
||||
- Automatic index building for GitHub-backed repos
|
||||
- `.gitignore` integration prevents sensitive data indexing
|
||||
- Repository authorization through GitHub App permissions
|
||||
- **Limitation**: Context scope is workspace-wide, not repository-specific by default
|
||||
|
||||
**Relevance to SuperClaude**: `.gitignore` integration is critical for security and performance.
|
||||
|
||||
---
|
||||
|
||||
### 1.3 Session Isolation Best Practices
|
||||
|
||||
**Git Worktrees for Parallel Sessions**:
|
||||
```bash
|
||||
# Enable multiple isolated Claude sessions
|
||||
git worktree add ../feature-branch feature-branch
|
||||
# Each worktree has independent working directory, shared git history
|
||||
```
|
||||
|
||||
**Context Window Management**:
|
||||
- Long sessions lead to context pollution → performance degradation
|
||||
- **Best Practice**: Use `/clear` command between tasks
|
||||
- Create session-end context files (`GEMINI.md`, `CONTEXT.md`) for handoff
|
||||
- Break tasks into smaller, isolated chunks
|
||||
|
||||
**Enterprise Security Architecture** (4-Layer Defense):
|
||||
1. **Prevention**: Rate-limit access, auto-strip credentials
|
||||
2. **Protection**: Encryption, project-level role-based access control
|
||||
3. **Detection**: SAST/DAST/SCA on pull requests
|
||||
4. **Response**: Detailed commit-prompt mapping
|
||||
|
||||
**Relevance to SuperClaude**: PM Agent should implement context reset between repository changes.
|
||||
|
||||
---
|
||||
|
||||
## 2. Git Repository Detection Patterns
|
||||
|
||||
### 2.1 Standard Detection Methods
|
||||
|
||||
**Recommended Approach**:
|
||||
```bash
|
||||
# Detect if current directory is in git repository
|
||||
git rev-parse --git-dir
|
||||
|
||||
# Check if inside working tree
|
||||
git rev-parse --is-inside-work-tree
|
||||
|
||||
# Get repository root
|
||||
git rev-parse --show-toplevel
|
||||
```
|
||||
|
||||
**Implementation Considerations**:
|
||||
- Git searches parent directories for `.git` folder automatically
|
||||
- `libgit2` library recommended for programmatic access
|
||||
- Avoid direct `.git` folder parsing (fragile to git internals changes)
|
||||
|
||||
### 2.2 Security Concerns
|
||||
|
||||
- **Issue**: Millions of `.git` folders exposed publicly by misconfiguration
|
||||
- **Mitigation**: Always respect `.gitignore` and add `.superclaude/` to ignore patterns
|
||||
- **Best Practice**: Store sensitive memory data in gitignored directories
|
||||
|
||||
---
|
||||
|
||||
## 3. Storage Architecture Comparison
|
||||
|
||||
### 3.1 Local File Storage
|
||||
|
||||
**Advantages**:
|
||||
- ✅ **Performance**: Faster than databases for sequential reads
|
||||
- ✅ **Simplicity**: No database setup or maintenance
|
||||
- ✅ **Portability**: Works offline, no network dependencies
|
||||
- ✅ **Developer-Friendly**: Files are readable/editable by humans
|
||||
- ✅ **Git Integration**: Can be versioned (if desired) or gitignored
|
||||
|
||||
**Disadvantages**:
|
||||
- ❌ No ACID transactions
|
||||
- ❌ Limited query capabilities
|
||||
- ❌ Manual concurrency handling
|
||||
|
||||
**Use Cases**:
|
||||
- **Perfect for**: Session context, architectural decisions, project documentation
|
||||
- **Not ideal for**: High-concurrency writes, complex queries
|
||||
|
||||
---
|
||||
|
||||
### 3.2 Database Storage
|
||||
|
||||
**Advantages**:
|
||||
- ✅ ACID transactions
|
||||
- ✅ Complex queries (SQL)
|
||||
- ✅ Concurrency management
|
||||
- ✅ Scalability for cross-repository intelligence (future)
|
||||
|
||||
**Disadvantages**:
|
||||
- ❌ **Performance**: Slower than local files for simple reads
|
||||
- ❌ **Complexity**: Database setup and maintenance overhead
|
||||
- ❌ **Network Bottlenecks**: If using remote database
|
||||
- ❌ **Developer UX**: Requires database tools to inspect
|
||||
|
||||
**Use Cases**:
|
||||
- **Future feature**: Cross-repository pattern mining
|
||||
- **Not needed for**: Basic repository-scoped memory
|
||||
|
||||
---
|
||||
|
||||
### 3.3 Vector Databases (Advanced)
|
||||
|
||||
**Recommendation**: **Not needed for v1**
|
||||
|
||||
**Future Consideration**:
|
||||
- Semantic search across project history
|
||||
- Pattern recognition across repositories
|
||||
- Requires significant infrastructure investment
|
||||
- **Wait until**: SuperClaude reaches "super-intelligence" level
|
||||
|
||||
---
|
||||
|
||||
## 4. SuperClaude PM Agent Recommendations
|
||||
|
||||
### 4.1 Immediate Implementation (v1)
|
||||
|
||||
**Architecture**:
|
||||
```
|
||||
project-root/
|
||||
├── .git/ # Repository boundary
|
||||
├── .gitignore
|
||||
│ └── .superclaude/ # Add to gitignore
|
||||
├── .superclaude/
|
||||
│ └── memory/
|
||||
│ ├── session_state.json # Current session context
|
||||
│ ├── pm_context.json # PM Agent PDCA state
|
||||
│ └── decisions/ # Architectural decision records
|
||||
│ ├── 2025-10-16_auth.md
|
||||
│ └── 2025-10-15_db.md
|
||||
└── docs/
|
||||
└── superclaude/ # Human-readable documentation
|
||||
├── patterns/ # Successful patterns
|
||||
└── mistakes/ # Error prevention
|
||||
|
||||
```
|
||||
|
||||
**Detection Logic**:
|
||||
```python
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
|
||||
def get_repository_root() -> Path | None:
|
||||
"""Detect git repository root using git rev-parse."""
|
||||
try:
|
||||
result = subprocess.run(
|
||||
["git", "rev-parse", "--show-toplevel"],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=5
|
||||
)
|
||||
if result.returncode == 0:
|
||||
return Path(result.stdout.strip())
|
||||
except (subprocess.TimeoutExpired, FileNotFoundError):
|
||||
pass
|
||||
return None
|
||||
|
||||
def get_memory_dir() -> Path:
|
||||
"""Get repository-scoped memory directory."""
|
||||
repo_root = get_repository_root()
|
||||
if repo_root:
|
||||
memory_dir = repo_root / ".superclaude" / "memory"
|
||||
memory_dir.mkdir(parents=True, exist_ok=True)
|
||||
return memory_dir
|
||||
else:
|
||||
# Fallback to global memory if not in git repo
|
||||
return Path.home() / ".superclaude" / "memory" / "global"
|
||||
```
|
||||
|
||||
**Session Lifecycle Integration**:
|
||||
```python
|
||||
# Session Start
|
||||
def restore_session_context():
|
||||
repo_root = get_repository_root()
|
||||
if not repo_root:
|
||||
return {} # No repository context
|
||||
|
||||
memory_file = repo_root / ".superclaude" / "memory" / "pm_context.json"
|
||||
if memory_file.exists():
|
||||
return json.loads(memory_file.read_text())
|
||||
return {}
|
||||
|
||||
# Session End
|
||||
def save_session_context(context: dict):
|
||||
repo_root = get_repository_root()
|
||||
if not repo_root:
|
||||
return # Don't save if not in repository
|
||||
|
||||
memory_file = repo_root / ".superclaude" / "memory" / "pm_context.json"
|
||||
memory_file.parent.mkdir(parents=True, exist_ok=True)
|
||||
memory_file.write_text(json.dumps(context, indent=2))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.2 PM Agent Memory Management
|
||||
|
||||
**PDCA Cycle Integration**:
|
||||
```python
|
||||
# Plan Phase
|
||||
write_memory(repo_root / ".superclaude/memory/plan.json", {
|
||||
"hypothesis": "...",
|
||||
"success_criteria": "...",
|
||||
"risks": [...]
|
||||
})
|
||||
|
||||
# Do Phase
|
||||
write_memory(repo_root / ".superclaude/memory/experiment.json", {
|
||||
"trials": [...],
|
||||
"errors": [...],
|
||||
"solutions": [...]
|
||||
})
|
||||
|
||||
# Check Phase
|
||||
write_memory(repo_root / ".superclaude/memory/evaluation.json", {
|
||||
"outcomes": {...},
|
||||
"adherence_check": "...",
|
||||
"completion_status": "..."
|
||||
})
|
||||
|
||||
# Act Phase
|
||||
if success:
|
||||
move_to_patterns(repo_root / "docs/superclaude/patterns/pattern-name.md")
|
||||
else:
|
||||
move_to_mistakes(repo_root / "docs/superclaude/mistakes/mistake-YYYY-MM-DD.md")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.3 Context Isolation Strategy
|
||||
|
||||
**Problem**: User switches from `SuperClaude_Framework` to `airis-mcp-gateway`
|
||||
**Current Behavior**: PM Agent retains SuperClaude context → Noise
|
||||
**Desired Behavior**: PM Agent detects repository change → Clears context → Loads airis-mcp-gateway context
|
||||
|
||||
**Implementation**:
|
||||
```python
|
||||
class RepositoryContextManager:
|
||||
def __init__(self):
|
||||
self.current_repo = None
|
||||
self.context = {}
|
||||
|
||||
def check_repository_change(self):
|
||||
"""Detect if repository changed since last invocation."""
|
||||
new_repo = get_repository_root()
|
||||
|
||||
if new_repo != self.current_repo:
|
||||
# Repository changed - clear context
|
||||
if self.current_repo:
|
||||
self.save_context(self.current_repo)
|
||||
|
||||
self.current_repo = new_repo
|
||||
self.context = self.load_context(new_repo) if new_repo else {}
|
||||
|
||||
return True # Context cleared
|
||||
return False # Same repository
|
||||
|
||||
def load_context(self, repo_root: Path) -> dict:
|
||||
"""Load repository-specific context."""
|
||||
memory_file = repo_root / ".superclaude" / "memory" / "pm_context.json"
|
||||
if memory_file.exists():
|
||||
return json.loads(memory_file.read_text())
|
||||
return {}
|
||||
|
||||
def save_context(self, repo_root: Path):
|
||||
"""Save current context to repository."""
|
||||
if not repo_root:
|
||||
return
|
||||
memory_file = repo_root / ".superclaude" / "memory" / "pm_context.json"
|
||||
memory_file.parent.mkdir(parents=True, exist_ok=True)
|
||||
memory_file.write_text(json.dumps(self.context, indent=2))
|
||||
```
|
||||
|
||||
**Usage in PM Agent**:
|
||||
```python
|
||||
# Session Start Protocol
|
||||
context_mgr = RepositoryContextManager()
|
||||
if context_mgr.check_repository_change():
|
||||
print(f"📍 Repository: {context_mgr.current_repo.name}")
|
||||
print(f"前回: {context_mgr.context.get('last_session', 'No previous session')}")
|
||||
print(f"進捗: {context_mgr.context.get('progress', 'Starting fresh')}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4.4 .gitignore Integration
|
||||
|
||||
**Add to .gitignore**:
|
||||
```gitignore
|
||||
# SuperClaude Memory (session-specific, not for version control)
|
||||
.superclaude/memory/
|
||||
|
||||
# Keep architectural decisions (optional - can be versioned)
|
||||
# !.superclaude/memory/decisions/
|
||||
```
|
||||
|
||||
**Rationale**:
|
||||
- Session state changes frequently → should not be committed
|
||||
- Architectural decisions MAY be versioned (team decision)
|
||||
- Prevents accidental secret exposure in memory files
|
||||
|
||||
---
|
||||
|
||||
## 5. Future Enhancements (v2+)
|
||||
|
||||
### 5.1 Cross-Repository Intelligence
|
||||
|
||||
**When to implement**: After PM Agent demonstrates reliable single-repository context
|
||||
|
||||
**Architecture**:
|
||||
```
|
||||
~/.superclaude/
|
||||
└── global_memory/
|
||||
├── patterns/ # Cross-repo patterns
|
||||
│ ├── authentication.json
|
||||
│ └── testing.json
|
||||
└── repo_index/ # Repository metadata
|
||||
├── SuperClaude_Framework.json
|
||||
└── airis-mcp-gateway.json
|
||||
```
|
||||
|
||||
**Smart Context Selection**:
|
||||
```python
|
||||
def get_relevant_context(current_repo: str) -> dict:
|
||||
"""Select context based on current repository."""
|
||||
# Local context (high priority)
|
||||
local = load_local_context(current_repo)
|
||||
|
||||
# Global patterns (low priority, filtered by relevance)
|
||||
global_patterns = load_global_patterns()
|
||||
relevant = filter_by_similarity(global_patterns, local.get('tech_stack'))
|
||||
|
||||
return merge_contexts(local, relevant, priority="local")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5.2 Vector Database Integration
|
||||
|
||||
**When to implement**: If SuperClaude requires semantic search across 100+ repositories
|
||||
|
||||
**Use Case**:
|
||||
- "Find all authentication implementations across my projects"
|
||||
- "What error handling patterns have I used successfully?"
|
||||
|
||||
**Technology**: pgvector, Qdrant, or Pinecone
|
||||
|
||||
**Cost-Benefit**: High complexity, only justified for "super-intelligence" tier features
|
||||
|
||||
---
|
||||
|
||||
## 6. Implementation Roadmap
|
||||
|
||||
### Phase 1: Repository-Scoped File Storage (Immediate)
|
||||
**Timeline**: 1-2 weeks
|
||||
**Effort**: Low
|
||||
|
||||
- [ ] Implement `get_repository_root()` detection
|
||||
- [ ] Create `.superclaude/memory/` directory structure
|
||||
- [ ] Integrate with PM Agent session lifecycle
|
||||
- [ ] Add `.superclaude/memory/` to `.gitignore`
|
||||
- [ ] Test repository change detection
|
||||
|
||||
**Success Criteria**:
|
||||
- ✅ PM Agent context isolated per repository
|
||||
- ✅ No noise from other projects
|
||||
- ✅ Session resumes correctly within same repository
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: PDCA Memory Integration (Short-term)
|
||||
**Timeline**: 2-3 weeks
|
||||
**Effort**: Medium
|
||||
|
||||
- [ ] Integrate Plan/Do/Check/Act with file storage
|
||||
- [ ] Implement `docs/superclaude/patterns/` and `docs/superclaude/mistakes/`
|
||||
- [ ] Create ADR (Architectural Decision Records) format
|
||||
- [ ] Add 7-day cleanup for `docs/temp/`
|
||||
|
||||
**Success Criteria**:
|
||||
- ✅ Successful patterns documented automatically
|
||||
- ✅ Mistakes recorded with prevention checklists
|
||||
- ✅ Knowledge accumulates within repository
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Cross-Repository Patterns (Future)
|
||||
**Timeline**: 3-6 months
|
||||
**Effort**: High
|
||||
|
||||
- [ ] Implement global pattern database
|
||||
- [ ] Smart context filtering by tech stack
|
||||
- [ ] Pattern similarity scoring
|
||||
- [ ] Opt-in cross-repo intelligence
|
||||
|
||||
**Success Criteria**:
|
||||
- ✅ PM Agent learns from past projects
|
||||
- ✅ Suggests relevant patterns from other repos
|
||||
- ✅ No performance degradation
|
||||
|
||||
---
|
||||
|
||||
## 7. Comparison Matrix
|
||||
|
||||
| Feature | Local Files | Database | Vector DB |
|
||||
|---------|-------------|----------|-----------|
|
||||
| **Performance** | ⭐⭐⭐⭐⭐ Fast | ⭐⭐⭐ Medium | ⭐⭐ Slow (network) |
|
||||
| **Simplicity** | ⭐⭐⭐⭐⭐ Simple | ⭐⭐ Complex | ⭐ Very Complex |
|
||||
| **Setup Time** | Minutes | Hours | Days |
|
||||
| **ACID Transactions** | ❌ No | ✅ Yes | ✅ Yes |
|
||||
| **Query Capabilities** | ⭐⭐ Basic | ⭐⭐⭐⭐⭐ SQL | ⭐⭐⭐⭐ Semantic |
|
||||
| **Offline Support** | ✅ Yes | ⚠️ Depends | ❌ No |
|
||||
| **Developer UX** | ⭐⭐⭐⭐⭐ Excellent | ⭐⭐⭐ Good | ⭐⭐ Fair |
|
||||
| **Maintenance** | ⭐⭐⭐⭐⭐ None | ⭐⭐⭐ Regular | ⭐⭐ Intensive |
|
||||
|
||||
**Recommendation for SuperClaude v1**: **Local Files** (clear winner for repository-scoped memory)
|
||||
|
||||
---
|
||||
|
||||
## 8. Security Considerations
|
||||
|
||||
### 8.1 Sensitive Data Handling
|
||||
|
||||
**Problem**: Memory files may contain secrets, API keys, internal URLs
|
||||
**Solution**: Automatic redaction + gitignore
|
||||
|
||||
```python
|
||||
import re
|
||||
|
||||
SENSITIVE_PATTERNS = [
|
||||
r'sk_live_[a-zA-Z0-9]{24,}', # Stripe keys
|
||||
r'eyJ[a-zA-Z0-9_-]*\.[a-zA-Z0-9_-]*', # JWT tokens
|
||||
r'ghp_[a-zA-Z0-9]{36}', # GitHub tokens
|
||||
]
|
||||
|
||||
def redact_sensitive_data(text: str) -> str:
|
||||
"""Remove sensitive data before storing in memory."""
|
||||
for pattern in SENSITIVE_PATTERNS:
|
||||
text = re.sub(pattern, '[REDACTED]', text)
|
||||
return text
|
||||
```
|
||||
|
||||
### 8.2 .gitignore Best Practices
|
||||
|
||||
**Always gitignore**:
|
||||
- `.superclaude/memory/` (session state)
|
||||
- `.superclaude/temp/` (temporary files)
|
||||
|
||||
**Optional versioning** (team decision):
|
||||
- `.superclaude/memory/decisions/` (ADRs)
|
||||
- `docs/superclaude/patterns/` (successful patterns)
|
||||
|
||||
---
|
||||
|
||||
## 9. Conclusion
|
||||
|
||||
### Key Takeaways
|
||||
|
||||
1. **✅ Local File Storage is Optimal**: Industry standard for repository-scoped context
|
||||
2. **✅ Git Detection is Standard**: Use `git rev-parse --show-toplevel`
|
||||
3. **✅ Start Simple, Evolve Later**: Files → Database (if needed) → Vector DB (far future)
|
||||
4. **✅ Repository Isolation is Critical**: Prevents context noise across projects
|
||||
|
||||
### Recommended Architecture for SuperClaude
|
||||
|
||||
```
|
||||
SuperClaude_Framework/
|
||||
├── .git/
|
||||
├── .gitignore (+.superclaude/memory/)
|
||||
├── .superclaude/
|
||||
│ └── memory/
|
||||
│ ├── pm_context.json # Current session state
|
||||
│ ├── plan.json # PDCA Plan phase
|
||||
│ ├── experiment.json # PDCA Do phase
|
||||
│ └── evaluation.json # PDCA Check phase
|
||||
└── docs/
|
||||
└── superclaude/
|
||||
├── patterns/ # Successful implementations
|
||||
│ └── authentication-jwt.md
|
||||
└── mistakes/ # Error prevention
|
||||
└── mistake-2025-10-16.md
|
||||
```
|
||||
|
||||
**Next Steps**:
|
||||
1. Implement `RepositoryContextManager` class
|
||||
2. Integrate with PM Agent session lifecycle
|
||||
3. Add `.superclaude/memory/` to `.gitignore`
|
||||
4. Test with repository switching scenarios
|
||||
5. Document for team adoption
|
||||
|
||||
---
|
||||
|
||||
**Research Confidence**: High (based on industry standards from Cursor, GitHub Copilot, and security best practices)
|
||||
|
||||
**Sources**:
|
||||
- Cursor IDE memory management architecture
|
||||
- GitHub Copilot workspace context documentation
|
||||
- Enterprise AI security frameworks
|
||||
- Git repository detection patterns
|
||||
- Storage performance benchmarks
|
||||
|
||||
**Last Updated**: 2025-10-16
|
||||
**Next Review**: After Phase 1 implementation (2-3 weeks)
|
||||
Reference in New Issue
Block a user