# Using Agents in Other Repositories This guide explains how to use the MCP Memory Service workflow automation agents in other repositories. The agents were designed for mcp-memory-service but are portable to Python, Node.js, Rust, Go, and other projects with appropriate configuration. **Quick Stats**: 95% portable (Amp CLI) | 60-80% portable (Release Manager, Quality Guard) | Language-specific adaptations required for PR automation --- ## Table of Contents 1. [Quick Start](#quick-start) - Get started in 5 minutes (Python projects) 2. [Portability Overview](#portability-overview) - What works as-is 3. [Language-Specific Guides](#language-specific-guides) - Python, Node.js, Rust, Go 4. [Configuration System](#configuration-system) - `.claude/project.json` template 5. [Agent Adaptation Guide](#agent-adaptation-guide) - Per-agent instructions 6. [Migration Checklists](#migration-checklists) - Step-by-step for each language 7. [Troubleshooting](#troubleshooting) - Common cross-repo issues --- ## Quick Start ### For Python Projects (Easiest - 30 minutes) The agents work best with Python projects since they were originally built for one. Here's the fastest path: ```bash # 1. Copy agent definitions cd your-python-project/ mkdir -p .claude/agents curl -o .claude/agents/github-release-manager.md \ https://raw.githubusercontent.com/doobidoo/mcp-memory-service/main/.claude/agents/github-release-manager.md curl -o .claude/agents/code-quality-guard.md \ https://raw.githubusercontent.com/doobidoo/mcp-memory-service/main/.claude/agents/code-quality-guard.md curl -o .claude/agents/gemini-pr-automator.md \ https://raw.githubusercontent.com/doobidoo/mcp-memory-service/main/.claude/agents/gemini-pr-automator.md curl -o .claude/agents/amp-automation.md \ https://raw.githubusercontent.com/doobidoo/mcp-memory-service/main/.claude/agents/amp-automation.md # 2. Copy portable scripts (work with any language) mkdir -p scripts/pr/lib curl -o scripts/pr/watch_reviews.sh \ https://raw.githubusercontent.com/doobidoo/mcp-memory-service/main/scripts/pr/watch_reviews.sh curl -o scripts/pr/resolve_threads.sh \ https://raw.githubusercontent.com/doobidoo/mcp-memory-service/main/scripts/pr/resolve_threads.sh curl -o scripts/pr/thread_status.sh \ https://raw.githubusercontent.com/doobidoo/mcp-memory-service/main/scripts/pr/thread_status.sh curl -o scripts/pr/lib/graphql_helpers.sh \ https://raw.githubusercontent.com/doobidoo/mcp-memory-service/main/scripts/pr/lib/graphql_helpers.sh chmod +x scripts/pr/*.sh # 3. Copy Groq bridge (for fast LLM calls) mkdir -p scripts/utils curl -o scripts/utils/groq \ https://raw.githubusercontent.com/doobidoo/mcp-memory-service/main/scripts/utils/groq chmod +x scripts/utils/groq # 4. Update hardcoded references # Edit .claude/agents/github-release-manager.md # Replace version file paths with your project's version files # Example: src/mcp_memory_service/__init__.py → src/your_package/__init__.py # 5. Configure environment export GROQ_API_KEY="your-groq-api-key" # Get from https://console.groq.com/keys # 6. Test with Claude Code # Open your project in Claude Code, mention an agent: # "Use the github-release-manager agent to check if we need a release" ``` **Result**: You now have working agents for release management, code quality, and PR automation! --- ## Portability Overview ### Highly Portable Components (95-100%) These work across **all languages** with zero or minimal changes: | Component | Portability | Works With | Changes Needed | |-----------|-------------|------------|----------------| | **Amp CLI Bridge** | 95% | Any language | Update project name only | | **GraphQL Helpers** | 100% | Any language | None | | **Watch Reviews** | 100% | Any language | None | | **Resolve Threads** | 100% | Any language | None | | **Thread Status** | 100% | Any language | None | | **Groq Bridge** | 100% | Any language | None | **Why They're Portable**: - Pure GitHub API interactions (language-agnostic) - No assumptions about file types or project structure - Work via GitHub CLI and HTTP APIs --- ### Moderately Portable Components (60-80%) These need **configuration** but core logic works across languages: | Component | Portability | Configuration Needed | Complexity | |-----------|-------------|---------------------|------------| | **GitHub Release Manager** | 70% | Version file paths, lock file command | Medium | | **Code Quality Guard** | 60% | File extensions, complexity targets | Medium | | **CHANGELOG Format** | 100% | None (uses standard format) | None | **What Needs Configuration**: - Version file locations (different per language) - Lock file update commands (`uv lock` vs `npm install` vs `cargo update`) - File extensions for quality checks (`.py` vs `.js` vs `.rs`) --- ### Language-Specific Components (40-60%) These require **script rewrites** for each language: | Component | Portability | Rewrite Needed | Effort | |-----------|-------------|----------------|--------| | **Quality Gate Scripts** | 40% | File filters, test commands | 2-3 hours | | **Test Generation** | 30% | Test framework patterns | 4-6 hours | | **Breaking Change Detection** | 50% | API pattern matching | 3-4 hours | | **Pre-commit Hooks** | 40% | File filters, linters | 1-2 hours | **Why They Need Rewrites**: - Test frameworks differ (pytest vs Jest vs cargo test) - API patterns differ (Python decorators vs Rust traits vs Go interfaces) - Breaking changes detected differently per language --- ## Language-Specific Guides ### Python Projects (Current Implementation) **Works Out-of-the-Box**: ✅ All agents and scripts **Version Files**: ```python # src/your_package/__init__.py __version__ = "1.2.3" # pyproject.toml [project] version = "1.2.3" ``` **Lock File Update**: ```bash uv lock # or: pip-compile, poetry lock, pdm lock ``` **Test Command**: ```bash pytest tests/ # or: python -m pytest ``` **File Extensions**: `.py` **Configuration** (`.claude/project.json`): ```json { "projectType": "python", "versionFiles": [ "src/your_package/__init__.py", "pyproject.toml" ], "lockFile": "uv.lock", "lockCommand": "uv lock", "testCommand": "pytest tests/", "fileExtensions": [".py"], "apiPaths": ["src/your_package/api/"] } ``` --- ### Node.js / TypeScript Projects **Requires Adaptation**: Script rewrites, version file mapping **Version Files**: ```json // package.json { "version": "1.2.3" } ``` **Lock File Update**: ```bash npm install # Updates package-lock.json # or: yarn install # Updates yarn.lock # or: pnpm install # Updates pnpm-lock.yaml ``` **Test Command**: ```bash npm test # Usually jest or mocha # or: yarn test # or: pnpm test ``` **File Extensions**: `.js`, `.ts`, `.jsx`, `.tsx` **Configuration** (`.claude/project.json`): ```json { "projectType": "nodejs", "versionFiles": ["package.json"], "lockFile": "package-lock.json", "lockCommand": "npm install", "testCommand": "npm test", "fileExtensions": [".js", ".ts", ".jsx", ".tsx"], "apiPaths": ["src/api/", "src/routes/"] } ``` **Required Script Adaptations**: **1. Quality Gate** (`scripts/pr/quality_gate.sh`): ```bash # Change from: changed_files=$(gh pr diff $PR_NUMBER --name-only | grep '\.py$') pytest tests/ # To: changed_files=$(gh pr diff $PR_NUMBER --name-only | grep '\\.\\(js\\|ts\\)$') npm test ``` **2. Test Generation** (`scripts/pr/generate_tests.sh`): ```bash # Change from pytest patterns: describe('functionName', () => { it('should handle valid input', () => { expect(functionName('valid')).toBe(expected); }); it('should throw on invalid input', () => { expect(() => functionName('invalid')).toThrow(); }); }); ``` **3. Pre-commit Hook** (`scripts/hooks/pre-commit`): ```bash # Change from: CHANGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.py$') # To: CHANGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.\(js\|ts\)$') eslint $CHANGED_FILES ``` --- ### Rust Projects **Requires Adaptation**: Script rewrites, version file mapping, cargo-specific commands **Version Files**: ```toml # Cargo.toml [package] version = "1.2.3" ``` **Lock File Update**: ```bash cargo update # Updates Cargo.lock ``` **Test Command**: ```bash cargo test ``` **File Extensions**: `.rs` **Configuration** (`.claude/project.json`): ```json { "projectType": "rust", "versionFiles": ["Cargo.toml"], "lockFile": "Cargo.lock", "lockCommand": "cargo update", "testCommand": "cargo test", "fileExtensions": [".rs"], "apiPaths": ["src/lib.rs", "src/api/"] } ``` **Required Script Adaptations**: **1. Quality Gate**: ```bash # Change to: changed_files=$(gh pr diff $PR_NUMBER --name-only | grep '\\.rs$') cargo test cargo clippy -- -D warnings ``` **2. Test Generation**: ```rust #[cfg(test)] mod tests { use super::*; #[test] fn test_function_valid_input() { let result = function_name("valid"); assert_eq!(result, expected); } #[test] #[should_panic] fn test_function_invalid_input() { function_name("invalid"); } } ``` **3. Breaking Change Detection**: ```bash # Detect public API changes git diff $BASE_BRANCH...$HEAD_BRANCH -- src/lib.rs | grep "^-pub " # Check for removed traits, structs, enums git diff $BASE_BRANCH...$HEAD_BRANCH -- src/ | grep "^-pub \\(trait\\|struct\\|enum\\)" ``` --- ### Go Projects **Requires Major Adaptation**: No version file, tag-based versioning, different test patterns **Version Files**: ⚠️ **None** - Go uses git tags only **Lock File Update**: ```bash go mod tidy # Updates go.sum ``` **Test Command**: ```bash go test ./... ``` **File Extensions**: `.go` **Configuration** (`.claude/project.json`): ```json { "projectType": "go", "versionFiles": [], "versioningStrategy": "git-tags", "lockFile": "go.sum", "lockCommand": "go mod tidy", "testCommand": "go test ./...", "fileExtensions": [".go"], "apiPaths": ["pkg/api/", "internal/"] } ``` **Major Changes Required**: **1. Version Management**: ```bash # GitHub Release Manager needs complete rewrite # Instead of updating version files: # 1. Create git tag: git tag -a v1.2.3 -m "Release 1.2.3" # 2. Push tag: git push origin v1.2.3 # 3. GitHub release references tag ``` **2. Quality Gate**: ```bash changed_files=$(gh pr diff $PR_NUMBER --name-only | grep '\\.go$') go test ./... go vet ./... golint ./... ``` **3. Test Generation**: ```go func TestFunctionName(t *testing.T) { tests := []struct { name string input string want string wantErr bool }{ {"valid input", "valid", "expected", false}, {"invalid input", "invalid", "", true}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { got, err := FunctionName(tt.input) if (err != nil) != tt.wantErr { t.Errorf("got error = %v, wantErr %v", err, tt.wantErr) } if got != tt.want { t.Errorf("got %v, want %v", got, tt.want) } }) } } ``` --- ## Configuration System ### Create `.claude/project.json` Place this file in your repository root to configure agent behavior: **Full Schema**: ```json { "$schema": "https://github.com/doobidoo/mcp-memory-service/wiki/schemas/project.json", "projectType": "python|nodejs|rust|go|java", "projectName": "your-project-name", "versionFiles": [ "path/to/version/file.py", "pyproject.toml" ], "versioningStrategy": "file-based|git-tags", "lockFile": "uv.lock", "lockCommand": "uv lock", "testCommand": "pytest tests/", "fileExtensions": [".py"], "apiPaths": [ "src/your_package/api/", "src/your_package/handlers/" ], "complexityTargets": { "api_handlers": 5, "business_logic": 6, "utilities": 3, "maximum": 8 }, "customScripts": { "qualityGate": "scripts/pr/quality_gate.sh", "generateTests": "scripts/pr/generate_tests.sh", "detectBreaking": "scripts/pr/detect_breaking_changes.sh" }, "changelogFormat": "keep-a-changelog", "changelogPath": "CHANGELOG.md" } ``` **Minimal Configuration** (agents will use defaults): ```json { "projectType": "python", "versionFiles": ["src/mypackage/__init__.py", "pyproject.toml"], "testCommand": "pytest tests/" } ``` --- ## Agent Adaptation Guide ### GitHub Release Manager **Portability**: 70% (version file paths need configuration) **What's Portable**: - ✅ CHANGELOG format (Keep a Changelog standard) - ✅ GitHub release creation - ✅ Issue tracking and closure - ✅ Workflow verification - ✅ Git operations (tag, push) **What Needs Configuration**: - ❌ Version file paths (different per language) - ❌ Lock file update command - ❌ Project-specific context references **Adaptation Steps**: 1. **Update version file references**: ```markdown # In .claude/agents/github-release-manager.md # Find lines mentioning: src/mcp_memory_service/__init__.py # Replace with your project's version file: src/your_package/__init__.py # or package.json (Node.js) # or Cargo.toml (Rust) ``` 2. **Update lock file command**: ```markdown # Find: uv lock # Replace with: npm install # Node.js cargo update # Rust go mod tidy # Go ``` 3. **Remove project-specific context** (optional): ```markdown # Find references to: - Storage backend - MCP protocol - Cloudflare # Either remove or replace with your project's domain concepts ``` **Go Projects Special Case**: - Completely rewrite version bump procedure - Use git tag workflow instead of file updates - Skip steps that update version files --- ### Code Quality Guard **Portability**: 60% (file extensions and complexity targets need configuration) **What's Portable**: - ✅ Groq/Gemini integration - ✅ Complexity scoring concept (1-10 scale) - ✅ TODO prioritization - ✅ Pre-commit hook architecture **What Needs Configuration**: - ❌ File extensions (`.py` → `.js`, `.rs`, `.go`) - ❌ Complexity targets (project-specific standards) - ❌ Security patterns (language-specific) **Adaptation Steps**: 1. **Update file extensions**: ```markdown # In .claude/agents/code-quality-guard.md # Find: \.py$ # Replace with: \\.\\(js\\|ts\\)$ # Node.js \\.rs$ # Rust \\.go$ # Go ``` 2. **Adjust complexity targets**: ```markdown # Find existing targets: - Storage backend methods: ≤6 - MCP tool handlers: ≤5 # Replace with your project's standards: - API endpoints: ≤5 - Business logic: ≤7 - Utilities: ≤3 - Maximum: 8 (blocks commit) ``` 3. **Update security patterns**: ```markdown # Python: SQL injection, XSS, subprocess # Node.js: eval(), prototype pollution, SQL injection # Rust: unsafe blocks, unchecked indexing # Go: SQL injection, goroutine leaks, race conditions ``` --- ### Gemini PR Automator **Portability**: 50% (supporting scripts need language-specific rewrites) **What's Portable**: - ✅ Watch reviews script (100%) - ✅ Resolve threads script (100%) - ✅ GraphQL helpers (100%) - ✅ PR monitoring workflow **What Needs Rewrites**: - ❌ `quality_gate.sh` - File filters, test commands - ❌ `generate_tests.sh` - Test framework patterns - ❌ `detect_breaking_changes.sh` - API change detection **Adaptation Steps**: 1. **Copy portable scripts** (no changes): ```bash scripts/pr/watch_reviews.sh scripts/pr/resolve_threads.sh scripts/pr/thread_status.sh scripts/pr/lib/graphql_helpers.sh ``` 2. **Rewrite language-specific scripts**: - See [Language-Specific Guides](#language-specific-guides) above - Follow patterns for your language - Test thoroughly before relying on automation 3. **Update agent references**: ```markdown # In .claude/agents/gemini-pr-automator.md # Update script paths if you renamed them: bash scripts/pr/quality_gate_nodejs.sh bash scripts/pr/generate_tests_nodejs.sh ``` --- ### Amp CLI Bridge **Portability**: 95% (almost perfect) **What's Portable**: - ✅ Everything! This agent is already language-agnostic **What Needs Configuration**: - Project name only (cosmetic) **Adaptation Steps**: 1. **Update project name** (optional): ```markdown # In .claude/agents/amp-automation.md # Find: "project": "mcp-memory-service" # Replace with: "project": "your-project-name" ``` 2. **Copy agent definition**: ```bash cp mcp-memory-service/.claude/agents/amp-automation.md \ your-project/.claude/agents/amp-automation.md ``` **That's it!** This agent works across all languages. --- ## Migration Checklists ### Python Project (30 minutes) - [ ] Copy `.claude/agents/` directory - [ ] Copy portable scripts (`watch_reviews.sh`, `resolve_threads.sh`, etc.) - [ ] Copy Groq bridge: `scripts/utils/groq` - [ ] Update version file paths in `github-release-manager.md` - [ ] Update `uv lock` command if using different package manager - [ ] Configure `GROQ_API_KEY` environment variable - [ ] Create `.claude/project.json` (optional) - [ ] Test with sample PR or release --- ### Node.js / TypeScript Project (2-3 hours) - [ ] Copy `.claude/agents/` directory - [ ] Copy portable scripts - [ ] Copy Groq bridge - [ ] Update `github-release-manager.md`: - [ ] Replace `pyproject.toml` → `package.json` - [ ] Replace `uv lock` → `npm install` - [ ] Update `code-quality-guard.md`: - [ ] Change file extensions `.py` → `.js`, `.ts` - [ ] Update complexity targets for JavaScript/TypeScript - [ ] Rewrite `scripts/pr/quality_gate.sh`: - [ ] File filter: `grep '\\.\\(js\\|ts\\)$'` - [ ] Test command: `npm test` - [ ] Add ESLint: `eslint $CHANGED_FILES` - [ ] Rewrite `scripts/pr/generate_tests.sh`: - [ ] Use Jest/Mocha patterns instead of pytest - [ ] Rewrite `scripts/pr/detect_breaking_changes.sh`: - [ ] Detect removed exports, changed function signatures - [ ] Update `scripts/hooks/pre-commit`: - [ ] Change file filter to `.js`/`.ts` - [ ] Run ESLint, Prettier - [ ] Create `.claude/project.json` - [ ] Configure `GROQ_API_KEY` - [ ] Test thoroughly with real PR --- ### Rust Project (4-6 hours) - [ ] Copy `.claude/agents/` directory - [ ] Copy portable scripts - [ ] Copy Groq bridge - [ ] Update `github-release-manager.md`: - [ ] Replace `pyproject.toml` → `Cargo.toml` - [ ] Replace `uv lock` → `cargo update` - [ ] Update `code-quality-guard.md`: - [ ] Change file extensions `.py` → `.rs` - [ ] Add `unsafe {}` block detection - [ ] Update complexity targets for Rust patterns - [ ] Rewrite `scripts/pr/quality_gate.sh`: - [ ] File filter: `grep '\\.rs$'` - [ ] Test command: `cargo test` - [ ] Add Clippy: `cargo clippy -- -D warnings` - [ ] Rewrite `scripts/pr/generate_tests.sh`: - [ ] Use Rust `#[test]` patterns - [ ] Rewrite `scripts/pr/detect_breaking_changes.sh`: - [ ] Detect removed `pub` items, changed trait definitions - [ ] Update `scripts/hooks/pre-commit`: - [ ] Change file filter to `.rs` - [ ] Run `cargo fmt --check`, `cargo clippy` - [ ] Create `.claude/project.json` - [ ] Configure `GROQ_API_KEY` - [ ] Test with Rust project --- ### Go Project (6-8 hours) - [ ] Copy `.claude/agents/` directory - [ ] Copy portable scripts - [ ] Copy Groq bridge - [ ] **Major rewrite: `github-release-manager.md`**: - [ ] Remove version file updates (Go uses tags only) - [ ] Implement git tag workflow - [ ] Update README manually or via script - [ ] Replace `uv lock` → `go mod tidy` - [ ] Update `code-quality-guard.md`: - [ ] Change file extensions `.py` → `.go` - [ ] Update complexity targets for Go patterns - [ ] Add goroutine leak detection - [ ] Rewrite `scripts/pr/quality_gate.sh`: - [ ] File filter: `grep '\\.go$'` - [ ] Test command: `go test ./...` - [ ] Add `go vet ./...`, `golint ./...` - [ ] Rewrite `scripts/pr/generate_tests.sh`: - [ ] Use Go table-driven test patterns - [ ] Rewrite `scripts/pr/detect_breaking_changes.sh`: - [ ] Detect removed exported functions/types - [ ] Check for changed function signatures - [ ] Update `scripts/hooks/pre-commit`: - [ ] Change file filter to `.go` - [ ] Run `go fmt`, `go vet` - [ ] Create `.claude/project.json` (with `versioningStrategy: "git-tags"`) - [ ] Configure `GROQ_API_KEY` - [ ] Extensive testing required --- ## Troubleshooting ### Common Issues **Issue: "Agent can't find version file"** ```bash # Solution: Check .claude/project.json or agent definition # Ensure version file path is correct for your project # Python: src/package/__init__.py # Node.js: package.json # Rust: Cargo.toml # Go: N/A (use git tags) ``` **Issue: "Lock file update fails"** ```bash # Solution: Update lockCommand in .claude/project.json # Python: uv lock, pip-compile, poetry lock # Node.js: npm install, yarn install, pnpm install # Rust: cargo update # Go: go mod tidy ``` **Issue: "Quality gate always fails"** ```bash # Solution: Check file extension filters # Ensure your project's file extensions are included # Python: .py # Node.js: .js, .ts, .jsx, .tsx # Rust: .rs # Go: .go ``` **Issue: "Test generation creates wrong syntax"** ```bash # Solution: Rewrite generate_tests.sh for your language # Each test framework has different patterns # Python: pytest # Node.js: Jest/Mocha # Rust: #[test] # Go: func TestXxx(t *testing.T) ``` **Issue: "Breaking change detection misses changes"** ```bash # Solution: Update detect_breaking_changes.sh patterns # Different languages have different API patterns # Python: def in public modules # Node.js: exports in package.json "exports" field # Rust: pub items in lib.rs # Go: exported (capitalized) functions/types ``` **Issue: "Groq API calls fail"** ```bash # Solution: Check GROQ_API_KEY environment variable echo $GROQ_API_KEY # If empty, set it: export GROQ_API_KEY="your-key-from-console.groq.com" # Add to .env for persistence: echo 'GROQ_API_KEY="your-key"' >> .env ``` **Issue: "Gemini CLI requires OAuth during commit"** ```bash # Solution: Use Groq as primary LLM (avoids OAuth) # Pre-commit hooks now use Groq first, Gemini fallback # Ensure GROQ_API_KEY is set to avoid interruptions ``` --- ## Related Resources - [Agent Integrations Guide](11-Agent-Integrations-Guide.md) - Detailed agent usage and workflows - [Complete Feature List](10-Complete-Feature-List.md) - All 33 MCP Memory Service features - [mcp-memory-service Repository](https://github.com/doobidoo/mcp-memory-service) - Original agent implementation - [Groq Console](https://console.groq.com/keys) - Get API key for fast LLM inference - [GitHub CLI Documentation](https://cli.github.com/manual/) - GitHub CLI setup and usage --- ## Feedback & Contributions These agents are actively maintained in the [mcp-memory-service repository](https://github.com/doobidoo/mcp-memory-service). If you: - ✅ Successfully adapted agents to a new language → Share your scripts! - ❌ Encountered issues → Open an issue with details - 💡 Have improvement suggestions → Start a discussion - 🔧 Created language-specific versions → Submit a PR **Community Contributions Welcome**: Help us make these agents work better across all languages and project types! --- ## 📚 Documentation | 🚀 Features | 🤖 Automation | 🌟 Community **Documentation**: [Home](./Home) • [Installation](./01-Installation-Guide) • [Integration](./03-Integration-Guide) • [Troubleshooting](./07-TROUBLESHOOTING) **Features**: [All 33 Features](./10-Complete-Feature-List) • [Memory Hooks](./Memory-Hooks-Complete-Guide) • [Web Dashboard](./Web-Dashboard-Guide) • [OAuth 2.1](./OAuth-2.1-Setup-Guide) **Automation**: [Agent Guide](./11-Agent-Integrations-Guide) • [Cross-Repo Setup](./12-Using-Agents-in-Other-Repositories) • [Context Provider](./Context-Provider-Workflow-Automation) **Community**: [GitHub](https://github.com/doobidoo/mcp-memory-service) • [Discussions](https://github.com/doobidoo/mcp-memory-service/discussions) • [Issues](https://github.com/doobidoo/mcp-memory-service/issues) • [Contribute](https://github.com/doobidoo/mcp-memory-service/blob/main/CONTRIBUTING.md) --- **MCP Memory Service** • Zero database locks • 5ms reads • 85% accurate memory triggers • [MIT License](https://github.com/doobidoo/mcp-memory-service/blob/main/LICENSE)