Skip to main content
xkayo32

agent-memory-orchestrator

by xkayo32v0.1.0

Hybrid plugin providing long-term memory, intelligent task orchestration, and portable skills compatible with VS Code/GitHub Copilot

Installation guide →
7 skillsMIT GitHub

Keywords

memoryorchestrationtasksgitcontextagent-skills

Commands

memory

Manage long-term project memory - store, search, and retrieve project context

orchestrate

Orchestrate complex multi-step tasks with memory context and systematic execution

verify

Run 4-phase post-implementation verification cycle to ensure quality and completeness

Documentation

# Agent Memory & Task Orchestrator

<div align="center">

![Version](https://img.shields.io/badge/version-0.1.0-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
![Python](https://img.shields.io/badge/python-3.8+-blue.svg)
![Claude Code](https://img.shields.io/badge/Claude_Code-Compatible-purple.svg)
![Agent Skills](https://img.shields.io/badge/Agent_Skills-Standard-orange.svg)

**Hybrid Claude Code plugin providing long-term memory, intelligent task orchestration, and portable skills compatible with VS Code/GitHub Copilot.**

[Features](#-features) •
[Installation](#-installation) •
[Usage](#-usage) •
[Documentation](#-documentation) •
[Contributing](#-contributing)

</div>

---

## 🚀 Features

### 🧠 Long-Term Memory System
- **Persistent Storage**: SQLite + ChromaDB vector database for semantic search
- **Project Isolation**: Separate memory per project
- **Semantic Search**: Find relevant context using natural language queries
- **Git Integration**: Automatic commit indexing and change tracking
- **Team Sharing**: Shared memory via `.claude/agent-memory/` (git-versioned)

### 🎯 Intelligent Task Orchestration
- **Auto-Decomposition**: Complex tasks broken into manageable subtasks
- **Role-Based Execution**: Architect → Implementer → Tester → Reviewer workflow
- **Context-Aware Planning**: Leverages historical project knowledge
- **Progress Tracking**: Real-time subtask status and results
- **Memory Integration**: Decisions and learnings stored automatically

### ✅ 4-Phase Verification Cycle
1. **Intent Verification** - Implementation matches requirements?
2. **Documentation Check** - Dependencies current and secure?
3. **Test Execution** - All tests pass with good coverage?
4. **Environment Validation** - Application runs correctly?

### 🔄 Portable Skills (Agent Skills Standard)
7 specialized skills compatible with **multiple IDEs**:
- **Claude Code**: Full functionality (MCP + skills)
- **VS Code/GitHub Copilot**: Skills work instruction-only
- **Cursor/Other**: Compatible with Agent Skills standard

**Skills**: orchestrator, architect, implementer, tester, debugger, reviewer, documenter

### 🤖 Autonomous Agents
- **Quality Validator**: Proactive code quality checks before commits
- **Context Compactor**: Intelligent context management (prevents overflow)
- **Git Analyzer**: Repository insights and change pattern analysis

### 🔗 Event-Driven Hooks
- **SessionStart**: Auto-load project context
- **PostToolUse**: Detect git commits and sync
- **PreCompact**: Preserve critical info before compaction

---

## 📦 Installation

### Prerequisites

```bash
# Python 3.8-3.11 recommended (3.12+ has compatibility issues with ChromaDB)
python --version  # Should be 3.8-3.11 for full features

# Claude Code installed
claude --version
```

> **⚠️ Important**: If using Python 3.12+, vector search (semantic similarity) will be disabled. The plugin will still work with basic keyword search via SQLite.

### Option 1: From GitHub (Recommended)

```bash
# Clone the repository
git clone https://github.com/xkayo32/agent-memory-orchestrator.git
cd agent-memory-orchestrator

# Install base dependencies (always works)
pip install -r requirements.txt

# Optional: Install vector search support (Python 3.8-3.11 only)
# If this fails, the plugin still works without semantic search
pip install -r requirements-vector.txt  # Optional

# Test locally with --plugin-dir
cd ..
cc --plugin-dir ./agent-memory-orchestrator
```

### Option 2: Install to Project

```bash
# Copy plugin to project
cp -r agent-memory-orchestrator /path/to/your/project/.claude-plugin/

# Navigate and start
cd /path/to/your/project
cc
```

### Option 3: Global Installation

```bash
# Install globally (future)
claude plugin install github.com/xkayo32/agent-memory-orchestrator
```

### Verify Installation

```bash
# Check plugin is loaded
cc
# In Claude Code:
> /help
# Should see: /orchestrate, /memory, /verify

# Check MCP server
> /mcp
# Should see: agent-memory server with ~20 tools
```

---

## 💻 Usage

### Quick Start

```bash
# Initialize project memory
/memory init "my-project" "/path/to/project" "https://github.com/user/repo"

# Orchestrate a complex task
/orchestrate Add user authentication with JWT tokens

# Search memory
/memory search "authentication decisions"

# Store important decision
/memory store decision "JWT Architecture" "Chose httpOnly cookies with CSRF tokens because..."

# Verify implementation
/verify task-123 abc456
```

### Commands Reference

#### 🎯 `/orchestrate [task description]`

Decompose and execute complex multi-step tasks with automatic role assignment.

**Example:**
```
/orchestrate Implement RESTful API for user management
```

**What it does:**
1. Loads relevant project context from memory
2. Decomposes task into subtasks (design → code → test → review)
3. Assigns roles (architect, implementer, tester, etc.)
4. Executes sequentially with progress tracking
5. Stores decisions and learnings in memory
6. Runs 4-phase verification after implementation

**Use when:**
- Building new features (authentication, APIs, dashboards)
- Refactoring large modules
- Migrating to new technologies
- Complex debugging scenarios

---

#### 🧠 `/memory [operation] [parameters]`

Manage long-term project memory with semantic search.

**Operations:**

**Store information:**
```bash
/memory store decision "Architecture Choice" "Chose microservices over monolith because..."
/memory store bug_fix "Login Timeout" "Root cause: Redis connection pooling..."
/memory store implementation "Payment Gateway" "Integrated Stripe with webhooks..."
```

**Search by semantic similarity:**
```bash
/memory search "how did we handle authentication?"
/memory search "database schema changes" type=implementation
/memory search "test failures" limit=5
```

**Get context for task:**
```bash
/memory context "implementing user roles"
```

**Manage projects:**
```bash
/memory init "project-name" "/path" "git-url"
/memory projects
/memory switch "other-project"
```

**Context management:**
```bash
/memory check        # Check usage (should compact at 70%+)
/memory compact      # Intelligent compaction
/memory summary      # Recent activity overview
```

**Git integration:**
```bash
/memory git-sync                          # Sync recent commits
/memory git-changes "7 days ago"          # Get recent changes
/memory find-commits "authentication"     # Search commits
```

---

#### ✅ `/verify [task_id] [commit_hash]`

Execute systematic 4-phase verification cycle after implementation.

**Example:**
```bash
/verify task-auth-123 a1b2c3d
```

**Verification Phases:**

**Phase 1: Intent Verification**
- Implementation matches original request?
- All requirements satisfied?
- No unintended side effects?

**Phase 2: Documentation Check**
- Libraries/frameworks up to date?
- Breaking API changes?
- Security advisories?

**Phase 3: Test Execution**
- Unit tests passing?
- Integration tests passing?
- Coverage meets threshold (80%+)?

**Phase 4: Environment Validation**
- Application starts successfully?
- No errors in logs?
- Endpoints responding?
- Database connections working?

**Output:** Comprehensive report with pass/fail for each phase and actionable recommendations.

---

### Skills (Auto-Activated)

Skills automatically load when relevant context is detected:

| Skill | Triggers | Purpose |
|-------|----------|---------|
| **orchestrator** | Complex tasks, multi-step work | Task decomposition and coordination |
| **architect** | Design questions, "how should I...", technical decisions | Architecture design and pattern selection |
| **implementer** | "Write code", "implement", actual coding tasks | Production code implementation |
| **tester** | "Create tests", "verify", validation requests | Test creation and verification cycles |
| **debugger** | "Error", "bug", "not working", failing tests | Systematic debugging and root cause analysis |
| **reviewer** | "Review code", "check quality", pre-commit | Code quality assessment and standards validation |
| **documenter** | "Write docs", "document API", README creation | Technical documentation and explanation |

**Skills work in:**
- ✅ **Claude Code** - Full functionality
- ✅ **VS Code/GitHub Copilot** - Instruction-only (no MCP tools)
- ✅ **Cursor** - Instruction-only
- ✅ **Other IDEs** - Via Agent Skills standard

---

### Agents (Autonomous Triggering)

Agents proactively assist without explicit invocation:

#### 🔍 Quality Validator
**Triggers:** After significant Write/Edit operations, before git commits

**What it does:**
- Analyzes recent code changes
- Identifies security, performance, and quality issues
- Categorizes by severity (Critical/Major/Minor)
- Provides actionable recommendations

**Example:**
```
assistant: "I've completed the authentication module. Let me validate code quality."
[Uses quality-validator agent]

Report:
- Critical: SQL injection risk in auth.service.ts:42
- Major: Missing error handling (2 locations)
- Minor: Inconsistent naming (5 files)
```

#### 🗜️ Context Compactor
**Triggers:** When context usage exceeds 70%, before major tasks

**What it does:**
- Identifies critical information to preserve
- Summarizes less important content
- Executes intelligent compaction
- Verifies essential context retained

**Example:**
```
assistant: "Context usage at 75%. Let me compact before continuing."
[Uses context-compactor agent]

Preserved:
- Active task: task-auth-123 (in progress)
- Recent decisions: JWT architecture (5 min ago)
- Action items: Fix token refresh (pending)

Freed: 45% of context space
```

#### 📊 Git Analyzer
**Triggers:** When asking about changes, before refactoring, bug investigation

**What it does:**
- Analyzes commit history and patterns
- Groups related changes by topic
- Identifies frequently changed files (hotspots)
- Provides insights for decision-making

**Example:**
```
user: "What changed in the auth module recently?"
[Uses git-analyzer agent]

Analysis:
- 8 commits in last 7 days
- Hotspot: auth.service.ts (changed 5 times)
- Main authors: Alice (60%), Bob (40%)
- Theme: Security improvements + bug fixes
```

---

### Hooks (Event-Driven Automation)

Hooks execute automatically on specific events:

#### 📍 SessionStart Hook
**Event:** Claude Code session starts

**Action:**
- Checks if project initialized
- Loads recent context if active project
- Suggests initialization if no project

**Example output:**
```
Active project: web-app-xyz
Loaded context: Last 3 tasks, 5 recent decisions
Ready to continue work on: JWT authentication feature
```

#### 🔗 PostToolUse Hook (Git Detection)
**Event:** After Bash tool usage

**Action:**
- Detects git commit commands
- Extracts commit hash
- Calls git_sync() to index changes
- Suggests verification if task_id available

**Example output:**
```
Git commit detected: a1b2c3d "Add JWT authentication"
Repository index updated
Suggestion: Run /verify task-auth-123 a1b2c3d
```

#### 💾 PreCompact Hook
**Event:** Before context compaction

**Action:**
- Identifies critical information:
  - Active task IDs and status
  - Recent architectural decisions (last 10 min)
  - Pending action items
- Stores explicitly in memory with high-priority marker

**Example output:**
```
Preserving before compaction:
- Task: task-auth-123 (status: in_progress)
- Decision: JWT architecture (5 min ago)
- Action: Implement token refresh (pending)

All critical info stored in memory.
```

---

## 🏗️ Architecture

### Hybrid Plugin Design

```
agent-memory-orchestrator/
├── .claude-plugin/
│   └── plugin.json           # Plugin manifest
├── .mcp.json                 # MCP server config
├── commands/                 # Slash commands
│   ├── orchestrate.md        # /orchestrate
│   ├── memory.md             # /memory
│   └── verify.md             # /verify
├── agents/                   # Autonomous agents
│   ├── quality-validator.md
│   ├── context-compactor.md
│   └── git-analyzer.md
├── .github/skills/           # Portable skills (Agent Skills standard)
│   ├── orchestrator/
│   ├── architect/
│   ├── implementer/
│   ├── tester/
│   ├── debugger/
│   ├── reviewer/
│   └── documenter/
├── hooks/
│   └── hooks.json            # Event-driven hooks
├── src/                      # Python MCP server
│   ├── server.py             # MCP entry point
│   ├── memory/               # Memory store (SQLite + ChromaDB)
│   ├── tools/                # MCP tool implementations
│   ├── models/               # Data models
│   └── git/                  # Git integration
└── requirements.txt          # Python dependencies
```

### Technology Stack

- **Memory Storage**: SQLite (structured) + ChromaDB (vector embeddings)
- **Embeddings**: sentence-transformers/all-MiniLM-L6-v2
- **MCP Server**: Python 3.8+ with stdio transport
- **Skills Format**: Agent Skills standard (portable across IDEs)
- **Git Integration**: Native git commands + parsing

---

## 📚 Documentation

### Memory MCP Tools (~20 tools)

**Project Management:**
- `project_init(name, path, git_repo)` - Initialize project
- `project_list()` - List all projects
- `project_switch(project_id)` - Switch active project

**Memory Operations:**
- `memory_store(project_id, type, title, content, metadata)` - Store memory
- `memory_search(project_id, query, type?, limit?)` - Semantic search
- `memory_get_context(project_id, task_description)` - Get relevant context

**Task Orchestration:**
- `task_plan(project_id, description, use_context)` - Decompose task
- `task_execute(task_id, subtask_id)` - Get next subtask
- `task_complete(task_id, subtask_id, result)` - Mark complete
- `task_verify(task_id, commit_hash)` - Run verification

**Git Integration:**
- `git_sync(project_id)` - Sync repository index
- `git_get_changes(project_id, since?, limit?)` - Get recent changes
- `git_find_commits(project_id, query)` - Search commits

**Context Management:**
- `context_check()` - Check usage and compaction status
- `context_compact(project_id)` - Intelligent compaction
- `context_summary(project_id)` - Recent activity summary
- `verify_needs_docs(project_id, files_changed)` - Check if docs outdated

### Memory Storage Structure

```
.claude/agent-memory/
├── memory.db                 # SQLite database
│   ├── projects              # Project registry
│   ├── memories              # Stored information
│   ├── tasks                 # Task orchestration
│   ├── subtasks              # Subtask tracking
│   └── git_commits           # Commit index
└── chroma/                   # ChromaDB vector store
    ├── embeddings.parquet    # Vector embeddings
    └── index/                # HNSW index
```

**Memory is:**
- ✅ Git-versioned (team sharing enabled)
- ✅ Project-isolated (`.claude/agent-memory/` per project)
- ✅ Semantically searchable (vector embeddings)
- ✅ Persistent (survives sessions)

---

## 🧪 Testing

### Manual Testing

```bash
# 1. Test skills
"Help me architect a REST API"           # architect skill
"Implement the API endpoints"            # implementer skill
"Create tests for the API"               # tester skill

# 2. Test commands
/memory init "test-project" "." "https://github.com/test/repo"
/memory store decision "Test" "Testing memory storage"
/memory search "test"

# 3. Test orchestration
/orchestrate Add user authentication

# 4. Test agents (should trigger automatically)
[Make code changes]                      # quality-validator triggers
[Let context reach 70%]                  # context-compactor triggers
"Show recent changes"                    # git-analyzer triggers

# 5. Test hooks
cc                                       # SessionStart hook
git commit -m "test"                     # PostToolUse hook
[Trigger compaction]                     # PreCompact hook
```

### Automated Testing (Future)

```bash
# Unit tests
pytest tests/

# Integration tests
pytest tests/integration/

# E2E tests
pytest tests/e2e/
```

---

## 🔧 Troubleshooting

### Python 3.12+ Compatibility Issues

**Problem**: `ERROR: Cannot install chromadb` or `onnxruntime not available`

**Solution**:
```bash
# Option 1: Use Python 3.11 (Recommended)
# Download from https://www.python.org/downloads/
python3.11 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -r requirements-vector.txt

# Option 2: Use without vector search (works on any Python 3.8+)
pip install -r requirements.txt  # Only base dependencies
# Plugin works with keyword search only (no semantic similarity)
```

### ChromaDB Installation Fails

**Problem**: `Building wheel for chromadb failed`

**Solution**:
```bash
# Install build dependencies first
pip install --upgrade pip setuptools wheel

# On Windows, install Visual C++ Build Tools
# Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/

# Try installing ChromaDB separately
pip install chromadb==0.4.13

# If still fails, use without vector search
pip install -r requirements.txt  # Skip requirements-vector.txt
```

### Memory Tools Not Available

**Problem**: MCP server not starting or tools not showing

**Solution**:
```bash
# Check if server script is executable
python src/server.py  # Should not error

# Verify .mcp.json is correct
cat .mcp.json

# Test with debug mode
cc --plugin-dir . --debug
# Check logs for server connection errors
```

### Vector Search Not Working

**Problem**: Semantic search returns no results

**Cause**: ChromaDB not installed or failed to load

**Workaround**: Use keyword-based search (still works without ChromaDB)
```bash
# Instead of semantic search
/memory search "authentication"  # Works with SQLite LIKE queries

# Store with keywords
/memory store decision "JWT Auth" "keywords: jwt token authentication bearer"
```

---

## 🤝 Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.

### Development Setup

```bash
# Clone repository
git clone https://github.com/xkayo32/agent-memory-orchestrator.git
cd agent-memory-orchestrator

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install development dependencies
pip install -r requirements-dev.txt  # Future

# Test locally
cc --plugin-dir .
```

### Project Structure

- **Commands** (`commands/`): Slash command implementations (Markdown)
- **Agents** (`agents/`): Autonomous agent definitions (Markdown)
- **Skills** (`.github/skills/`): Portable skills (Agent Skills standard)
- **Hooks** (`hooks/`): Event-driven automation (JSON + scripts)
- **MCP Server** (`src/`): Python implementation of memory tools

### Creating Issues

Use GitHub Issues for:
- 🐛 Bug reports
- ✨ Feature requests
- 📚 Documentation improvements
- 💡 Ideas and suggestions

### Pull Request Process

1. Fork the repository
2. Create feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open Pull Request

---

## 🗺️ Roadmap

### v0.2.0 (Next Release)
- [ ] Complete MCP tool implementations (task, git, context)
- [ ] Add comprehensive unit tests
- [ ] Performance optimization (ChromaDB indexing)
- [ ] Enhanced git analysis (branch tracking, merge detection)
- [ ] VS Code extension bridge

### v0.3.0 (Future)
- [ ] Multi-user collaboration (shared memory with permissions)
- [ ] Cloud sync options (optional remote storage)
- [ ] Advanced analytics (task patterns, team velocity)
- [ ] Integration with CI/CD pipelines
- [ ] Custom skill creation wizard

### v1.0.0 (Stable Release)
- [ ] Production-ready stability
- [ ] Comprehensive documentation
- [ ] Video tutorials and guides
- [ ] Plugin marketplace submission
- [ ] Enterprise features

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- **Claude Code Team** - For the excellent plugin architecture
- **Agent Skills Community** - For the portable skills standard
- **Contributors** - For making this project better

---

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/xkayo32/agent-memory-orchestrator/issues)
- **Discussions**: [GitHub Discussions](https://github.com/xkayo32/agent-memory-orchestrator/discussions)
- **Email**: [email protected]
- **Documentation**: [GitHub Wiki](https://github.com/xkayo32/agent-memory-orchestrator/wiki)

---

## 🌟 Star History

If this plugin helps you, please consider starring the repository!

[![Star History Chart](https://api.star-history.com/svg?repos=xkayo32/agent-memory-orchestrator&type=Date)](https://star-history.com/#xkayo32/agent-memory-orchestrator&Date)

---

<div align="center">
Made with ❤️ by xkayo32
</div>