@musashishao/agent-kit 1.8.1 → 1.9.0

package/.agent/skills/agent-memory-systems/SKILL.md

@@ -0,0 +1,426 @@
+---
+name: agent-memory-systems
+description: "Memory architectures for intelligent agents. Covers short-term (context window), long-term (vector stores), episodic, semantic, and procedural memory. Understanding that memory failures look like intelligence failures - the hard part isn't storing, it's retrieving the right memory at the right time."
+version: "1.0.0"
+source: "antigravity-awesome-skills (adapted)"
+---
+
+# 🧠 Agent Memory Systems
+
+> Memory is the cornerstone of intelligent agents. Without it, every interaction starts from zero.
+
+You are a cognitive architect who understands that memory makes agents intelligent. The hard part isn't storing - it's retrieving the right memory at the right time.
+
+**Core insight**: Memory failures look like intelligence failures. When an agent "forgets" or gives inconsistent answers, it's almost always a retrieval problem, not a storage problem.
+
+---
+
+## When to Use This Skill
+
+- Designing memory architecture for AI agents
+- Implementing long-term memory with vector stores
+- Building conversational agents that remember
+- Creating agents that learn from past interactions
+- Optimizing retrieval for context windows
+
+---
+
+## 1. Memory Type Architecture
+
+### Memory Types Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    AGENT MEMORY SYSTEM                       │
+│                                                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │   Working    │  │   Episodic   │  │   Semantic   │      │
+│  │   Memory     │  │   Memory     │  │   Memory     │      │
+│  │ (Context)    │  │ (Events)     │  │ (Facts)      │      │
+│  └──────────────┘  └──────────────┘  └──────────────┘      │
+│         │                 │                 │               │
+│         ▼                 ▼                 ▼               │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │              Retrieval & Synthesis                   │   │
+│  │         (What's relevant right now?)                 │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+| Memory Type | Description | Storage | Retrieval |
+|-------------|-------------|---------|-----------|
+| **Working** | Current context window | In-memory | Direct |
+| **Episodic** | Past conversations, events | Vector DB | Semantic search |
+| **Semantic** | Facts, knowledge | Vector DB + Graph | Query |
+| **Procedural** | How to do things | Code/Prompts | Pattern match |
+
+### Implementation
+
+```python
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import List, Optional
+
+@dataclass
+class Memory:
+    id: str
+    content: str
+    memory_type: str  # working, episodic, semantic, procedural
+    timestamp: datetime
+    metadata: dict
+    embedding: Optional[List[float]] = None
+    importance: float = 0.5
+    access_count: int = 0
+    last_accessed: Optional[datetime] = None
+
+class MemoryStore(ABC):
+    @abstractmethod
+    def store(self, memory: Memory) -> str:
+        """Store a memory, return ID"""
+        pass
+    
+    @abstractmethod
+    def retrieve(self, query: str, top_k: int = 5) -> List[Memory]:
+        """Retrieve relevant memories"""
+        pass
+    
+    @abstractmethod
+    def forget(self, memory_id: str) -> bool:
+        """Remove a memory"""
+        pass
+
+class AgentMemorySystem:
+    def __init__(self):
+        self.working_memory = WorkingMemory(max_tokens=8000)
+        self.episodic_memory = EpisodicMemory(vector_db=ChromaDB())
+        self.semantic_memory = SemanticMemory(vector_db=ChromaDB())
+        self.procedural_memory = ProceduralMemory()
+    
+    def remember(self, content: str, memory_type: str, metadata: dict = None):
+        """Store a new memory"""
+        memory = Memory(
+            id=generate_id(),
+            content=content,
+            memory_type=memory_type,
+            timestamp=datetime.now(),
+            metadata=metadata or {},
+            importance=self._assess_importance(content)
+        )
+        
+        if memory_type == "working":
+            self.working_memory.add(memory)
+        elif memory_type == "episodic":
+            self.episodic_memory.store(memory)
+        elif memory_type == "semantic":
+            self.semantic_memory.store(memory)
+    
+    def recall(self, query: str, memory_types: List[str] = None) -> List[Memory]:
+        """Retrieve relevant memories across types"""
+        results = []
+        
+        types = memory_types or ["working", "episodic", "semantic"]
+        
+        if "working" in types:
+            results.extend(self.working_memory.search(query))
+        if "episodic" in types:
+            results.extend(self.episodic_memory.retrieve(query))
+        if "semantic" in types:
+            results.extend(self.semantic_memory.retrieve(query))
+        
+        # Rank by relevance + recency + importance
+        return self._rank_memories(results, query)
+```
+
+---
+
+## 2. Working Memory (Context Window)
+
+```python
+class WorkingMemory:
+    """
+    Active context that fits in LLM context window.
+    Manages what the agent is "currently thinking about".
+    """
+    
+    def __init__(self, max_tokens: int = 8000):
+        self.max_tokens = max_tokens
+        self.memories: List[Memory] = []
+        self.priority_queue = []
+    
+    def add(self, memory: Memory):
+        """Add memory, evicting if necessary"""
+        tokens = count_tokens(memory.content)
+        
+        # Evict low-priority memories if needed
+        while self._current_tokens() + tokens > self.max_tokens:
+            self._evict_lowest_priority()
+        
+        self.memories.append(memory)
+    
+    def get_context(self) -> str:
+        """Get formatted context for LLM"""
+        return "\n---\n".join([m.content for m in self.memories])
+    
+    def _evict_lowest_priority(self):
+        """Remove least important memory"""
+        if not self.memories:
+            return
+        
+        # Score by importance * recency
+        scores = []
+        for m in self.memories:
+            age_hours = (datetime.now() - m.timestamp).total_seconds() / 3600
+            recency_score = 1 / (1 + age_hours)
+            score = m.importance * recency_score
+            scores.append((score, m))
+        
+        # Remove lowest scoring
+        scores.sort(key=lambda x: x[0])
+        self.memories.remove(scores[0][1])
+```
+
+---
+
+## 3. Episodic Memory (Conversations & Events)
+
+```python
+class EpisodicMemory:
+    """
+    Stores past conversations and events.
+    "What happened before?"
+    """
+    
+    def __init__(self, vector_db):
+        self.vector_db = vector_db
+        self.collection = vector_db.get_or_create_collection("episodic")
+    
+    def store(self, memory: Memory):
+        """Store an episode"""
+        # Generate embedding
+        embedding = embed(memory.content)
+        
+        # Store with metadata
+        self.collection.add(
+            ids=[memory.id],
+            embeddings=[embedding],
+            documents=[memory.content],
+            metadatas=[{
+                "timestamp": memory.timestamp.isoformat(),
+                "session_id": memory.metadata.get("session_id"),
+                "user_id": memory.metadata.get("user_id"),
+                "importance": memory.importance
+            }]
+        )
+    
+    def retrieve(self, query: str, top_k: int = 5, 
+                 time_range: tuple = None,
+                 session_id: str = None) -> List[Memory]:
+        """Retrieve relevant episodes"""
+        
+        # Build filter
+        where = {}
+        if session_id:
+            where["session_id"] = session_id
+        if time_range:
+            where["timestamp"] = {
+                "$gte": time_range[0].isoformat(),
+                "$lte": time_range[1].isoformat()
+            }
+        
+        results = self.collection.query(
+            query_texts=[query],
+            n_results=top_k,
+            where=where if where else None
+        )
+        
+        return self._results_to_memories(results)
+    
+    def summarize_session(self, session_id: str) -> str:
+        """Create summary of a session for compression"""
+        episodes = self.retrieve("", session_id=session_id, top_k=100)
+        
+        # Use LLM to summarize
+        summary = llm.summarize([e.content for e in episodes])
+        
+        # Store summary as new memory
+        self.store(Memory(
+            id=f"summary_{session_id}",
+            content=summary,
+            memory_type="episodic",
+            metadata={"is_summary": True, "session_id": session_id}
+        ))
+        
+        return summary
+```
+
+---
+
+## 4. Semantic Memory (Facts & Knowledge)
+
+```python
+class SemanticMemory:
+    """
+    Stores facts and knowledge.
+    "What do I know about X?"
+    """
+    
+    def __init__(self, vector_db):
+        self.vector_db = vector_db
+        self.collection = vector_db.get_or_create_collection("semantic")
+    
+    def store_fact(self, fact: str, source: str = None, 
+                   confidence: float = 1.0, category: str = None):
+        """Store a fact with metadata"""
+        memory = Memory(
+            id=generate_id(),
+            content=fact,
+            memory_type="semantic",
+            timestamp=datetime.now(),
+            metadata={
+                "source": source,
+                "confidence": confidence,
+                "category": category
+            },
+            importance=confidence
+        )
+        
+        # Check for conflicts
+        existing = self.retrieve(fact, top_k=3)
+        for e in existing:
+            if self._is_contradictory(fact, e.content):
+                # Store conflict for resolution
+                self._store_conflict(fact, e)
+        
+        self.store(memory)
+    
+    def retrieve(self, query: str, top_k: int = 5,
+                 category: str = None,
+                 min_confidence: float = 0.5) -> List[Memory]:
+        """Retrieve relevant facts"""
+        
+        where = {"confidence": {"$gte": min_confidence}}
+        if category:
+            where["category"] = category
+        
+        results = self.collection.query(
+            query_texts=[query],
+            n_results=top_k,
+            where=where
+        )
+        
+        return self._results_to_memories(results)
+```
+
+---
+
+## 5. Retrieval Strategies
+
+### 5.1 Hybrid Retrieval
+
+```python
+class HybridRetriever:
+    """Combine multiple retrieval strategies"""
+    
+    def retrieve(self, query: str, memory_system: AgentMemorySystem) -> List[Memory]:
+        # 1. Semantic search
+        semantic_results = memory_system.episodic_memory.retrieve(query, top_k=10)
+        
+        # 2. Keyword search (BM25)
+        keyword_results = self._bm25_search(query)
+        
+        # 3. Recency boost
+        recent_results = memory_system.episodic_memory.retrieve(
+            query, 
+            time_range=(datetime.now() - timedelta(hours=24), datetime.now())
+        )
+        
+        # 4. Combine with RRF
+        all_results = self._reciprocal_rank_fusion([
+            semantic_results,
+            keyword_results,
+            recent_results
+        ], weights=[0.5, 0.3, 0.2])
+        
+        return all_results[:5]
+```
+
+### 5.2 Temporal Scoring
+
+```python
+def temporal_score(memory: Memory, query_time: datetime) -> float:
+    """Score memory by time relevance"""
+    age = (query_time - memory.timestamp).total_seconds()
+    
+    # Exponential decay
+    half_life_hours = 24
+    decay = 0.5 ** (age / (half_life_hours * 3600))
+    
+    return memory.importance * decay
+```
+
+---
+
+## 6. Anti-Patterns
+
+### ❌ Store Everything Forever
+
+```python
+# WRONG: Never delete anything
+def store(self, memory):
+    self.db.insert(memory)  # Grows forever!
+
+# CORRECT: Implement decay and consolidation
+def store(self, memory):
+    self.db.insert(memory)
+    self._maybe_consolidate()  # Summarize old memories
+    self._maybe_forget()       # Remove low-value memories
+```
+
+### ❌ Chunk Without Testing Retrieval
+
+```python
+# WRONG: Chunk and hope for the best
+chunks = text.split("\n\n")
+
+# CORRECT: Test retrieval quality
+chunks = chunk_document(text)
+for test_query in test_queries:
+    results = retrieve(test_query)
+    assert any(expected_chunk in r for r in results)
+```
+
+### ❌ Single Memory Type for All Data
+
+```python
+# WRONG: Everything in one vector store
+self.memory.store(conversation)  # Episodic
+self.memory.store(user.name)     # Semantic
+self.memory.store(code_pattern)  # Procedural
+
+# CORRECT: Separate by type
+self.episodic.store(conversation)
+self.semantic.store(f"User name: {user.name}")
+self.procedural.store(code_pattern)
+```
+
+---
+
+## 7. Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Embedding drift over time | Critical | Track embedding model in metadata |
+| Context overflow | High | Budget tokens per memory type |
+| Stale information | High | Add temporal scoring |
+| Contradictory facts | Medium | Detect conflicts on storage |
+| Chunking breaks context | High | Use contextual chunking |
+| Retrieval misses | High | Test with diverse queries |
+
+---
+
+## Related Skills
+
+- `llm-app-patterns` - LLM architecture patterns
+- `rag-engineering` - Advanced RAG techniques
+- `langgraph` - Agent frameworks with memory
+- `autonomous-agent-patterns` - Agent design patterns

package/.agent/skills/agent-tool-builder/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: agent-tool-builder
+description: "Expertise in designing, building, and optimizing tools for AI agents. Covers MCP (Model Context Protocol), function calling schemas, tool security, and sandbox execution."
+version: "1.0.0"
+---
+
+# 🛠️ Agent Tool Builder
+
+You are an expert in building tools that AI agents use to interact with the world. You know how to design schemas that LLMs understand, handle errors gracefully, and ensure tools are secure and robust.
+
+---
+
+## When to Use This Skill
+
+- Building MCP servers
+- Designing function calling schemas (OpenAI/Anthropic)
+- Creating custom tools for LangChain/CrewAI/LangGraph
+- Implementing secure code execution sandboxes
+- Optimizing tool descriptions for LLM selection
+
+---
+
+## Capabilities
+
+- `mcp-server-development`
+- `function-calling-schemas`
+- `json-schema-design`
+- `tool-security-sandboxing`
+- `api-wrapper-tools`
+- `browser-use-tools`
+
+---
+
+## 1. Tool Schema Design (JSON Schema)
+
+The most important part of a tool is its description and schema. LLMs use these to decide when and how to call the tool.
+
+```typescript
+// Good tool definition
+export const searchDocsSchema = {
+  name: "search_documentation",
+  description: "Search the project documentation for specific topics. Use this when the user asks 'how to' or for technical details.",
+  parameters: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "The search query (e.g., 'auth setup', 'database schema')"
+      },
+      category: {
+        type: "string",
+        enum: ["api", "guides", "deployment", "troubleshooting"],
+        description: "Optional category to filter search results"
+      }
+    },
+    required: ["query"]
+  }
+};
+```
+
+---
+
+## 2. MCP Server (FastMCP Pattern)
+
+```typescript
+// server.ts
+import { FastMCP } from "fastmcp";
+
+const server = new FastMCP("System-Manager");
+
+// Define a tool
+server.addTool({
+  name: "get_system_stats",
+  description: "Get CPU and Memory usage of the host system",
+  parameters: {
+    type: "object",
+    properties: {
+      includeHistory: { type: "boolean" }
+    }
+  },
+  execute: async ({ includeHistory }) => {
+    const stats = await getStats();
+    return JSON.stringify(stats);
+  }
+});
+
+// Define a resource
+server.addResource({
+  uri: "system://logs",
+  name: "System Logs",
+  load: async () => {
+    const logs = await readLogs();
+    return logs;
+  }
+});
+
+server.start();
+```
+
+---
+
+## 3. Secure Execution (Sandboxing)
+
+```python
+import docker
+
+def execute_in_sandbox(code: str):
+    client = docker.from_env()
+    container = client.containers.run(
+        "python:3.11-slim",
+        command=f'python -c "{code}"',
+        network_disabled=True,
+        mem_limit="128m",
+        cpu_period=100000,
+        cpu_quota=50000,
+        remove=True,
+        detach=False
+    )
+    return container.decode("utf-8")
+```
+
+---
+
+## 4. Best Practices
+
+| Rule | Rationale |
+|------|-----------|
+| **Be Descriptive** | LLMs rely on the description to choose the tool. Avoid generic names like `run`. |
+| **Keep it Simple** | Too many parameters confuse the model. Split complex tools into smaller ones. |
+| **Handle Errors** | Always return a clear error message that the LLM can use to fix its call. |
+| **Idempotency** | Ensure side-effect tools can be safely called multiple times by the agent. |
+
+---
+
+## Related Skills
+
+- `autonomous-agent-patterns` - For the "Agent Loop"
+- `mcp-builder` - Deep dive into MCP
+- `api-patterns` - For tool backends

package/.agent/skills/ai-agents-architect/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: ai-agents-architect
+description: "Architecture and design of multi-agent systems. Covers agent communication, role delegation, task decomposition, and swarm intelligence."
+version: "1.0.0"
+---
+
+# 🤖 AI Agents Architect
+
+You are an architect specializing in Multi-Agent Systems (MAS). You know how to decompose complex tasks into sub-tasks and delegate them to specialized agents. You design robust communication protocols and handle agent orchestration at scale.
+
+---
+
+## When to Use This Skill
+
+- Designing multi-agent workflows (Manager-Worker, Swarm, Hierarchical)
+- Implementing agent communication protocols
+- Balancing agent autonomy vs. controlled orchestration
+- Solving tasks too complex for a single agent
+- Designing agentic feedback loops
+
+---
+
+## Capabilities
+
+- `agent-orchestration`
+- `task-decomposition`
+- `swarm-intelligence`
+- `agent-communication-protocols`
+- `dynamic-teaming`
+- `error-propagation-in-mas`
+
+---
+
+## 1. Orchestration Patterns
+
+### Hierarchical Orchestration (The Manager Pattern)
+
+```python
+class ManagerAgent:
+    def __init__(self):
+        self.specialists = {
+            "coder": CoderAgent(),
+            "reviewer": ReviewerAgent(),
+            "docs": DocumentationAgent()
+        }
+
+    async def run_task(self, request: str):
+        # 1. Plan
+        plan = await self.decompose(request)
+        
+        # 2. Delegate & Execute
+        code = await self.specialists["coder"].execute(plan["code_specs"])
+        review = await self.specialists["reviewer"].execute(code)
+        
+        # 3. Loop until quality met
+        while review.has_bugs:
+            code = await self.specialists["coder"].fix(review.bugs)
+            review = await self.specialists["reviewer"].execute(code)
+            
+        return code
+```
+
+---
+
+## 2. Communication Protocols
+
+Agents should communicate using structured data or standardized thought protocols.
+
+```json
+{
+  "from": "frontend_agent",
+  "to": "backend_agent",
+  "intent": "SCHEMA_REQUEST",
+  "content": {
+    "module": "Auth",
+    "format": "OpenAPI"
+  },
+  "priority": "HIGH"
+}
+```
+
+---
+
+## 3. Swarm Logic (Decentralized)
+
+```python
+class SwarmAgent:
+    async def process(self, context):
+        # Check if I can handle the task
+        if self.can_handle(context):
+            return await self.execute(context)
+        else:
+            # Pass to the most suitable neighbor
+            neighbor = self.find_best_neighbor(context)
+            return await neighbor.process(context)
+```
+
+---
+
+## 4. Design Matrix
+
+| Pattern | Best For | Trade-off |
+|---------|----------|-----------|
+| **Sequential** | Clear linear workflows | High latency, brittle |
+| **Hierarchical** | Quality-critical tasks | Manager overhead |
+| **Broadcast** | Open-ended brainstorming | High noise/token usage |
+| **Swarm** | Large-scale parallel tasks | Difficult to debug |
+
+---
+
+## Related Skills
+
+- `crewai` - For specific multi-agent frameworks
+- `langgraph` - For stateful agent graphs
+- `autonomous-agent-patterns` - Individual agent design