agent-scaffold-cli 0.1.1__py3-none-any.whl

agent_scaffold/_bundled_deployments/docs/frameworks/crewai.md

@@ -0,0 +1,91 @@
+# Framework: CrewAI
+
+**Language:** Python
+**Install:** `uv add crewai`
+**Version pinned:** >=0.28.0
+
+## Core abstractions
+
+- **Agent:** An LLM-powered entity with a role, goal, backstory, and tools. Agents have a persona that shapes their behavior.
+- **Task:** A unit of work with a description, expected output, and optionally an assigned agent. Tasks can depend on other tasks.
+- **Crew:** A team of agents working together on tasks. The crew defines the process (sequential, parallel, or hierarchical).
+- **Process:** How agents execute tasks — `sequential` (one after another), `hierarchical` (manager delegates), or custom.
+- **Tool:** A function the agent can call. CrewAI tools are based on LangChain's tool interface.
+
+## Patterns it supports well
+
+- **Multi-Agent Flat** — The canonical use case. Define a crew with specialized agents, assign tasks, run. Built-in collaboration.
+- **Multi-Agent Hierarchical** — Set `process=Process.hierarchical` and designate a `manager_agent`. The manager delegates tasks to workers.
+- **Prompt Chaining** — Sequential task execution where each task's output feeds the next.
+- **ReAct** — Individual agents use a ReAct loop internally when they have tools.
+
+## Patterns where it's awkward
+
+- **Routing / Classification** — CrewAI is designed for collaboration, not intent routing. Use Pydantic AI instead.
+- **RAG** — Possible via tools but there's no built-in retrieval. Better handled by a dedicated RAG framework.
+- **Parallel fan-out on data** — CrewAI's parallelism is at the agent/task level, not data-level. For batch processing N items, use `asyncio.gather()` instead.
+- **Fine-grained state control** — No checkpointing or state graph. The crew runs to completion.
+
+## Idiomatic minimal example
+
+```python
+from crewai import Agent, Task, Crew, Process
+
+researcher = Agent(
+    role="Researcher",
+    goal="Find accurate information about the topic",
+    backstory="You are an expert researcher with attention to detail.",
+    tools=[search_tool],
+)
+
+writer = Agent(
+    role="Writer",
+    goal="Write clear, concise summaries",
+    backstory="You are a technical writer who excels at making complex topics accessible.",
+)
+
+research_task = Task(
+    description="Research {topic}",
+    expected_output="Detailed research notes with sources",
+    agent=researcher,
+)
+
+write_task = Task(
+    description="Write a summary based on the research",
+    expected_output="A clear, concise summary",
+    agent=writer,
+)
+
+crew = Crew(
+    agents=[researcher, writer],
+    tasks=[research_task, write_task],
+    process=Process.sequential,
+)
+
+result = crew.kickoff(inputs={"topic": "AI agents"})
+```
+
+## Strengths
+
+- **Multi-agent first** — The best framework for teams of agents working together. Crew/Agent/Task is a natural mental model.
+- **Role-based agents** — Backstory + role + goal gives agents strong personas without complex prompt engineering.
+- **Built-in delegation** — Hierarchical process with manager delegation works out of the box.
+- **Low code for simple cases** — A 2-agent crew with sequential tasks is ~20 lines.
+
+## Trade-offs
+
+- **Opinionated** — The Crew/Agent/Task model doesn't fit every pattern. Single-agent workflows feel over-engineered.
+- **Token-heavy** — Agent backstories, task descriptions, and inter-agent messages consume many tokens. Costs add up.
+- **Less control** — The internal ReAct loop and delegation logic are opaque. Hard to customize behavior mid-execution.
+- **LangChain dependency** — Tools and some internals depend on LangChain, adding to the dependency tree.
+- **Debugging** — Multi-agent interactions are hard to trace. Add verbose logging.
+
+## Used in this repo
+
+| Prototype | Role |
+|-----------|------|
+| `ops-crew` | Planned for flat multi-agent DevOps/Security/Database crew (skeleton) |
+
+## Reference implementations
+
+- [recipes/ops-crew.md](../recipes/ops-crew.md) — Multi-agent ops crew (skeleton)

agent_scaffold/_bundled_deployments/docs/frameworks/langgraph.md

@@ -0,0 +1,79 @@
+# Framework: LangGraph
+
+**Language:** Python
+**Install:** `uv add langgraph`
+**Version pinned:** 0.3.21
+
+## Core abstractions
+
+- **StateGraph:** A directed graph where nodes are functions and edges are transitions. State flows through the graph as a typed dict.
+- **State:** A TypedDict (or Pydantic model) that accumulates data as the graph executes. Each node receives the full state and returns updates.
+- **Nodes:** Python functions (sync or async) that take state, do work (call LLM, run tool, transform data), and return state updates.
+- **Edges:** Transitions between nodes. Can be unconditional (always go A -> B) or conditional (router function picks the next node based on state).
+- **Checkpointer:** Persists state between steps, enabling resume, replay, and human-in-the-loop. Postgres-backed in production.
+- **ToolNode:** Built-in node that executes tool calls from a preceding LLM node. Handles tool schemas, invocation, and result injection.
+
+## Patterns it supports well
+
+- **RAG** -- Retriever node -> generator node with state carrying retrieved chunks. Add conditional edges for multi-step retrieval.
+- **ReAct** -- `create_react_agent()` gives you a prebuilt reason-act-observe loop with tool execution. The canonical use case.
+- **Plan & Execute** -- Planner node produces a step list in state, executor node works through them, reflector node evaluates and optionally re-plans.
+- **Multi-Agent (hierarchical)** -- `langgraph-supervisor` package provides a supervisor node that delegates to sub-graphs. Each sub-agent is its own compiled graph.
+- **Memory** -- Checkpointer + state persistence means conversation history and memory are first-class.
+
+## Patterns where it's awkward
+
+- **Simple tool use / routing** -- If your agent is just "classify intent, call one tool," LangGraph's graph abstraction is overkill. Use Pydantic AI instead.
+- **Parallel fan-out** -- LangGraph supports map-reduce via `Send()`, but the ergonomics are heavier than raw `asyncio.gather()` with Pydantic AI.
+
+## Idiomatic minimal example
+
+```python
+from langgraph.graph import StateGraph, START, END
+from langgraph.prebuilt import create_react_agent
+from langchain_anthropic import ChatAnthropic
+from langchain_core.tools import tool
+
+@tool
+def search(query: str) -> str:
+    """Search the web."""
+    return f"Results for: {query}"
+
+llm = ChatAnthropic(model="claude-sonnet-4-6-20250514")
+agent = create_react_agent(llm, tools=[search])
+
+# Run
+result = agent.invoke({"messages": [("user", "What is MCP?")]})
+print(result["messages"][-1].content)
+```
+
+## Strengths
+
+- **State management** is the best in class. TypedDict state + checkpointing means you can pause, resume, replay, and branch agent execution.
+- **Observability** via LangSmith integration -- every node execution, LLM call, and tool invocation is traced automatically.
+- **Composition** -- sub-graphs can be compiled and used as nodes in parent graphs, enabling hierarchical agent architectures.
+- **Production-proven** -- widely deployed, well-documented, active maintenance.
+
+## Trade-offs
+
+- **Learning curve** -- the graph mental model takes time. Simple agents feel over-engineered.
+- **LangChain coupling** -- while LangGraph is technically separate, it works best with LangChain's model wrappers (`ChatAnthropic`, `ChatOpenAI`), tool decorators, and message types.
+- **Async complexity** -- async graph execution works but debugging is harder than sync Pydantic AI agents.
+- **Verbose for simple cases** -- a 3-node graph with conditional edges is more code than a Pydantic AI agent with a tool.
+
+## Used in this repo
+
+| Prototype | Role |
+|-----------|------|
+| `docs-rag-qa` | Listed as LangGraph in README, but implementation uses Pydantic AI for simplicity. LangGraph would be the choice for multi-step RAG with state. |
+| `research-assistant` | Listed for ReAct loop. The `create_react_agent` helper is the natural fit. |
+| `code-review-agent` | Plan & Execute pattern -- planner + executor + reflector as graph nodes. (Skeleton) |
+| `memory-assistant` | Checkpointer-backed memory with LangGraph + mem0. (Skeleton) |
+| `hierarchical-agent` | `langgraph-supervisor` for hierarchical multi-agent. (Skeleton) |
+
+## Reference implementations
+
+- [recipes/docs-rag-qa.md](../recipes/docs-rag-qa.md) -- RAG pipeline (design-level LangGraph, implemented with Pydantic AI)
+- [recipes/research-assistant.md](../recipes/research-assistant.md) -- ReAct agent
+- [recipes/code-review-agent.md](../recipes/code-review-agent.md) -- Plan & Execute (skeleton)
+- [recipes/hierarchical-agent.md](../recipes/hierarchical-agent.md) -- Hierarchical multi-agent (skeleton)

agent_scaffold/_bundled_deployments/docs/frameworks/mastra.md

@@ -0,0 +1,74 @@
+# Framework: Mastra
+
+**Language:** TypeScript
+**Install:** `npm install mastra @mastra/core`
+**Version pinned:** >=0.1.0
+
+## Core abstractions
+
+- **Agent:** An LLM-powered entity with a system prompt, model config, and tools. Similar to Pydantic AI's Agent but in TypeScript.
+- **Tool:** A typed function the agent can call. Defined with Zod schemas for input/output validation.
+- **Workflow:** A directed graph of steps (like LangGraph but TS-native). Supports branching, looping, and parallel execution.
+- **Memory:** Built-in memory primitives for conversation history and semantic memory. Integrates with vector stores.
+- **Integration:** Pre-built connectors for external services (APIs, databases, SaaS tools).
+
+## Patterns it supports well
+
+- **ReAct** — Agent with tools runs a built-in reason-act-observe loop. Similar ergonomics to Pydantic AI.
+- **Routing + Tool Use** — Agent with structured output for classification, separate agents per handler.
+- **Prompt Chaining** — Workflow steps execute sequentially, passing typed data between stages.
+- **Memory** — First-class memory support with built-in storage backends.
+- **Multi-Agent** — Agent handoffs via workflows. Agents can delegate to other agents.
+
+## Patterns where it's awkward
+
+- **Plan-and-Execute** — Possible via workflows but no dedicated planner/reflector abstractions.
+- **Complex state management** — Workflows handle state but lack LangGraph's checkpointing depth (no replay, no branching history).
+
+## Idiomatic minimal example
+
+```typescript
+import { Agent } from "@mastra/core";
+import { anthropic } from "@ai-sdk/anthropic";
+import { z } from "zod";
+
+const agent = new Agent({
+  name: "assistant",
+  model: anthropic("claude-sonnet-4-6-20250514"),
+  instructions: "You are a helpful assistant.",
+  tools: {
+    search: {
+      description: "Search for information",
+      parameters: z.object({ query: z.string() }),
+      execute: async ({ query }) => `Results for: ${query}`,
+    },
+  },
+});
+
+const result = await agent.generate("What is MCP?");
+console.log(result.text);
+```
+
+## Strengths
+
+- **TS-native** — Built for TypeScript from the ground up. Zod schemas, async/await, full type inference.
+- **Batteries included** — Memory, workflows, integrations, and tools in one framework.
+- **Workflow engine** — Directed graph workflows with branching and parallelism, similar to LangGraph but in TS.
+- **Growing ecosystem** — Active development, increasing community adoption.
+
+## Trade-offs
+
+- **Newer framework** — Smaller community, fewer production deployments compared to Vercel AI SDK or LangChain.
+- **Heavier than Vercel AI SDK** — More abstractions to learn. For simple agents, Vercel AI SDK is lighter.
+- **Integration lock-in** — Built-in integrations are convenient but may not match your exact needs.
+- **Documentation gaps** — As a newer project, some advanced use cases lack documentation.
+
+## Used in this repo
+
+| Prototype | Role |
+|-----------|------|
+| Not currently used | The TS track uses Vercel AI SDK. Mastra is documented as a TS framework option for teams that need workflow orchestration or built-in memory. |
+
+## Reference implementations
+
+- No direct recipes yet. See [frameworks/vercel-ai-sdk.md](vercel-ai-sdk.md) for the TS framework currently used in prototypes.

agent_scaffold/_bundled_deployments/docs/frameworks/pydantic-ai.md

@@ -0,0 +1,77 @@
+# Framework: Pydantic AI
+
+**Language:** Python
+**Install:** `uv add pydantic-ai[anthropic]`
+**Version pinned:** >=0.1.0
+
+## Core abstractions
+
+- **Agent:** The central class. Wraps a model, system prompt, tools, and result type. Calling `agent.run()` executes a full reason-act-observe loop until the agent produces a result.
+- **Tool:** A decorated Python function (`@agent.tool` or `@agent.tool_plain`) that the agent can call. Tools receive typed arguments and return typed results.
+- **Result type:** A Pydantic model that defines the structured output the agent must produce. The framework validates the LLM's output against this schema automatically.
+- **Dependencies:** Typed context injected into tools via `@agent.tool` (as opposed to `@agent.tool_plain`). Useful for passing DB connections, API clients, or user context.
+- **System prompt:** Static string or dynamic function that sets the agent's behavior. Dynamic prompts can use dependencies.
+
+## Patterns it supports well
+
+- **Routing + Tool Use** — Structured `result_type` makes intent classification natural. Separate agents per specialist with isolated tool sets. This is the pattern used in `customer-support-triage`.
+- **ReAct** — `agent.run()` is a built-in ReAct loop. The agent reasons, calls tools, observes results, and loops until it produces the result type. Used in `research-assistant`.
+- **RAG** — Retrieval as a tool, generation via the agent. Type-safe citation schemas via `result_type`. Used in `docs-rag-qa`.
+- **Prompt Chaining** — Sequential `agent.run()` calls with different `result_type` per stage. Type safety between stages.
+- **Parallel Calls** — `asyncio.gather()` with multiple `agent.run()` calls. Async-first design makes this natural.
+
+## Patterns where it's awkward
+
+- **Plan-and-Execute** — No built-in state management or checkpointing. You'd manage the plan/reflect state yourself.
+- **Multi-Agent (hierarchical)** — No supervisor abstraction. You'd orchestrate agent-calling-agent manually.
+- **Memory** — No built-in persistence. You'd integrate with an external memory store via tools.
+
+## Idiomatic minimal example
+
+```python
+from pydantic_ai import Agent
+
+agent = Agent(
+    "anthropic:claude-sonnet-4-6-20250514",
+    system_prompt="You are a helpful assistant.",
+)
+
+@agent.tool_plain
+async def search(query: str) -> str:
+    """Search for information."""
+    return f"Results for: {query}"
+
+result = await agent.run("What is MCP?")
+print(result.data)
+```
+
+## Strengths
+
+- **Type safety** — Pydantic models for inputs, outputs, and tool signatures. Validation is automatic.
+- **Minimal boilerplate** — An agent with tools is ~10 lines. No graph to define, no nodes to wire.
+- **Async-first** — Built on asyncio. Parallel tool calls and concurrent agents work naturally.
+- **Framework-agnostic models** — Supports Anthropic, OpenAI, Gemini, Ollama, and more via a clean provider interface.
+- **Testable** — `TestModel` and `FunctionModel` allow deterministic testing without hitting an LLM.
+
+## Trade-offs
+
+- **No state management** — Unlike LangGraph, there's no checkpointer or state graph. Complex multi-step workflows require manual state handling.
+- **No built-in multi-agent** — Each agent is independent. Orchestrating multiple agents is your responsibility.
+- **Simpler = less control** — The ReAct loop is opaque. You can't easily inject logic between reason and act steps (LangGraph lets you add nodes anywhere).
+- **Younger ecosystem** — Smaller community and fewer integrations compared to LangChain/LangGraph.
+
+## Used in this repo
+
+| Prototype | Role |
+|-----------|------|
+| `customer-support-triage` | Classifier agent with `result_type=ClassificationResult`, specialist agents per intent |
+| `docs-rag-qa` | RAG agent with Qdrant retrieval as a tool |
+| `research-assistant` | ReAct agent with web search tool |
+| `content-pipeline` | Planned for prompt chaining (skeleton) |
+| `parallel-enricher` | Planned for parallel `asyncio.gather()` pattern (skeleton) |
+
+## Reference implementations
+
+- [recipes/customer-support-triage.md](../recipes/customer-support-triage.md) — Routing + Tool Use
+- [recipes/docs-rag-qa.md](../recipes/docs-rag-qa.md) — Agentic RAG
+- [recipes/research-assistant.md](../recipes/research-assistant.md) — ReAct research agent

agent_scaffold/_bundled_deployments/docs/frameworks/vercel-ai-sdk.md

@@ -0,0 +1,83 @@
+# Framework: Vercel AI SDK
+
+**Language:** TypeScript
+**Install:** `npm install ai @ai-sdk/anthropic`
+**Version pinned:** ai ^4.0.0, @ai-sdk/anthropic ^1.0.0
+
+## Core abstractions
+
+- **`generateText()`:** Single LLM call that can use tools. The agent loops internally (up to `maxSteps`) calling tools until it produces a final text response.
+- **`generateObject()`:** LLM call that returns structured output validated against a Zod schema. Ideal for classification, extraction, and structured data.
+- **`streamText()` / `streamObject()`:** Streaming variants for real-time output.
+- **`tool()`:** Defines a tool with a Zod schema and an execute function. Tools are passed to `generateText()` as a record.
+- **Provider:** Model abstraction (`@ai-sdk/anthropic`, `@ai-sdk/openai`, etc.) that handles API communication.
+
+## Patterns it supports well
+
+- **ReAct** — `generateText()` with `tools` and `maxSteps` runs a built-in reason-act-observe loop. The simplest way to build an agent in TS.
+- **Routing + Tool Use** — `generateObject()` for classification (structured output), `generateText()` per specialist. Clean and lightweight.
+- **RAG** — Retrieval as a tool, generation via `generateText()`. Or inject retrieved context directly into the prompt.
+- **Prompt Chaining** — Sequential `generateObject()` / `generateText()` calls. Each stage is a function call.
+- **Parallel Calls** — `Promise.all()` with multiple `generateText()` calls. Standard TS async.
+
+## Patterns where it's awkward
+
+- **Plan-and-Execute** — No state management or checkpointing. You'd manage everything manually.
+- **Multi-Agent (hierarchical)** — No supervisor abstraction. You'd orchestrate agent-calling-agent yourself.
+- **Memory** — No built-in persistence. Conversation history must be managed externally.
+- **Complex workflows** — No graph or workflow engine. For complex flows, consider Mastra or a manual state machine.
+
+## Idiomatic minimal example
+
+```typescript
+import { generateText, tool } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { z } from "zod";
+
+const result = await generateText({
+  model: anthropic("claude-sonnet-4-6-20250514"),
+  system: "You are a helpful assistant.",
+  prompt: "What is MCP?",
+  tools: {
+    search: tool({
+      description: "Search for information",
+      parameters: z.object({ query: z.string() }),
+      execute: async ({ query }) => `Results for: ${query}`,
+    }),
+  },
+  maxSteps: 5,
+});
+
+console.log(result.text);
+```
+
+## Strengths
+
+- **Minimal API surface** — Three functions (`generateText`, `generateObject`, `streamText`) cover most use cases. Easy to learn.
+- **Type safety** — Zod schemas for tool inputs, structured outputs, and provider configs. Full TypeScript inference.
+- **Streaming-first** — Built for real-time UIs. `streamText()` and `streamObject()` integrate with React Server Components and Next.js.
+- **Provider-agnostic** — Swap models by changing the provider import. Same code works with Anthropic, OpenAI, Google, and more.
+- **Lightweight** — No framework overhead. Functions, not classes. Composes with any TS codebase.
+- **Production-proven** — Widely deployed via Vercel's ecosystem. Well-documented, actively maintained.
+
+## Trade-offs
+
+- **No orchestration** — No graph, no workflow, no state management. Complex multi-step agents require manual plumbing.
+- **No multi-agent** — Each `generateText()` call is independent. No built-in agent-to-agent communication.
+- **No memory** — Conversation history is your responsibility. Pass `messages` array manually.
+- **UI-focused origin** — Some features (streaming, React hooks) are optimized for web UIs, which may be unnecessary for backend agents.
+
+## Used in this repo
+
+| Prototype | Role |
+|-----------|------|
+| `customer-support-triage` (TS) | Classifier with `generateObject()`, specialist with `generateText()` + tools |
+| `docs-rag-qa` (TS) | RAG agent with retrieval tool |
+| `research-assistant` (TS) | ReAct agent with web search tool |
+| All TS prototypes | The standard TS framework for all prototypes in this repo |
+
+## Reference implementations
+
+- [recipes/customer-support-triage.md](../recipes/customer-support-triage.md) — Routing + Tool Use (TS track)
+- [recipes/docs-rag-qa.md](../recipes/docs-rag-qa.md) — Agentic RAG (TS track)
+- [recipes/research-assistant.md](../recipes/research-assistant.md) — ReAct agent (TS track)

agent_scaffold/_bundled_deployments/docs/patterns/README.md

@@ -0,0 +1,26 @@
+# Patterns
+
+Architecture patterns for AI agents. Each file answers: **"What shape does my agent take?"**
+
+| Pattern | One-liner | Best framework fit |
+|---------|-----------|-------------------|
+| [RAG](rag.md) | Ground answers in retrieved documents | LangGraph, Pydantic AI |
+| [ReAct](react.md) | Think → act → observe loop with tools | LangGraph, Pydantic AI |
+| [Routing + Tool Use](routing-tool-use.md) | Classify intent, route to specialist | Pydantic AI |
+| [Prompt Chaining](prompt-chaining.md) | Fixed sequence of LLM calls | Pydantic AI, Vercel AI SDK |
+| [Plan, Execute, Reflect](plan-execute-reflect.md) | Plan steps, execute, self-correct | LangGraph |
+| [Parallel Calls](parallel-calls.md) | Fan-out / fan-in concurrent execution | Pydantic AI, Vercel AI SDK |
+| [Memory](memory.md) | Persist context across conversations | LangGraph |
+| [Multi-Agent Flat](multi-agent-flat.md) | Peer agents collaborating | CrewAI |
+| [Multi-Agent Hierarchical](multi-agent-hierarchical.md) | Supervisor delegates to workers | LangGraph |
+
+## How to pick a pattern
+
+1. **Single task, no tools needed?** → Just prompt the model directly. No pattern needed.
+2. **Need external data but fixed flow?** → [RAG](rag.md) or [Prompt Chaining](prompt-chaining.md)
+3. **Need tools, unknown sequence?** → [ReAct](react.md)
+4. **Multiple request types?** → [Routing + Tool Use](routing-tool-use.md)
+5. **Complex task needing self-correction?** → [Plan, Execute, Reflect](plan-execute-reflect.md)
+6. **N independent sub-tasks?** → [Parallel Calls](parallel-calls.md)
+7. **Need cross-session context?** → [Memory](memory.md)
+8. **Multiple specialists needed?** → [Multi-Agent Flat](multi-agent-flat.md) or [Hierarchical](multi-agent-hierarchical.md)

agent_scaffold/_bundled_deployments/docs/patterns/memory.md

@@ -0,0 +1,82 @@
+# Pattern: Memory
+
+**One-liner:** Persist information across conversations so the agent can recall context, preferences, and facts from prior interactions.
+
+## When to use
+
+- The agent has repeat users who expect it to remember past interactions.
+- Context from previous conversations is needed to give good answers (e.g., user preferences, prior decisions).
+- You want the agent to learn and improve over time from interactions.
+- The agent manages ongoing relationships or projects that span multiple sessions.
+
+## When NOT to use
+
+- Every interaction is independent (stateless Q&A, one-shot tasks).
+- The conversation context window is large enough to hold all relevant history.
+- Privacy/compliance requirements prohibit storing user interaction data.
+
+## Core flow
+
+```
+User message
+    |
+    v
+  [Retrieve memories] ──> query memory store for relevant past context
+    |
+    v
+  [Augment prompt] ──> inject retrieved memories into system/user prompt
+    |
+    v
+  [LLM generates response] ──> answer informed by past context
+    |
+    v
+  [Extract & store memories] ──> save new facts/preferences from this interaction
+    |
+    v
+  Response
+```
+
+### Memory types
+
+- **Conversation history:** Raw message log from prior sessions. Simple but grows unbounded.
+- **Semantic memory:** Facts and knowledge extracted from conversations, stored as embeddings. Retrievable by similarity.
+- **Episodic memory:** Summaries of past interactions ("Last week, user asked about X and we resolved it by Y").
+- **User profile memory:** Structured preferences and attributes (name, role, preferred language, past decisions).
+- **Working memory:** Short-term context within a single session. Typically managed by the conversation itself.
+
+### Variants
+
+- **Explicit memory:** User says "remember that I prefer dark mode." Agent stores it as-is.
+- **Implicit memory:** Agent automatically extracts noteworthy facts from conversations.
+- **Hybrid:** Both explicit and implicit, with the agent deciding what's worth remembering.
+
+## Key components
+
+- **Memory store:** Where memories live. Options: vector DB (semantic search), relational DB (structured), or specialized services like Mem0.
+- **Memory retriever:** Queries the store for memories relevant to the current conversation. Typically vector similarity search.
+- **Memory extractor:** After each conversation, identifies new facts/preferences worth persisting.
+- **Memory manager:** Handles deduplication, updates, and expiration of memories. Prevents contradictions (old preference vs. new one).
+- **Injection layer:** Formats retrieved memories and adds them to the prompt context.
+
+## Common pitfalls
+
+- **Unbounded memory:** Storing everything makes retrieval noisy. Be selective about what gets stored.
+- **Stale memories:** User preferences change. Memories need timestamps and a mechanism to update or expire.
+- **Contradictions:** "User likes dark mode" and "User prefers light mode" both stored. Newer should overwrite older.
+- **Privacy leakage:** Memories from one user accessible to another. Always scope memories by user ID.
+- **Retrieval noise:** Irrelevant memories injected into the prompt confuse the model. Use relevance thresholds.
+- **Memory extraction hallucination:** The extractor "remembers" things the user didn't actually say. Validate extracted facts against the conversation.
+
+## Framework fit
+
+| Framework | Native support | Notes |
+|-----------|----------------|-------|
+| LangGraph | Checkpointer for conversation state, integrates with external memory stores | Best for stateful agents with complex memory needs |
+| Pydantic AI | Manual memory integration via tool calls or prompt augmentation | Flexible but you build the plumbing |
+| Mastra | Built-in memory primitives and storage integrations | TS-native memory support |
+| CrewAI | Agent memory via `memory=True` flag | Simple but limited customization |
+| Vercel AI SDK | Manual integration | No built-in memory |
+
+## Reference implementations
+
+- [recipes/memory-assistant.md](../recipes/memory-assistant.md) — Memory-enabled assistant with LangGraph + Mem0 (skeleton)

agent_scaffold/_bundled_deployments/docs/patterns/multi-agent-flat.md

@@ -0,0 +1,72 @@
+# Pattern: Multi-Agent Flat (Peer Collaboration)
+
+**One-liner:** Multiple specialized agents collaborate as peers, each handling part of a task, without a central supervisor.
+
+## When to use
+
+- The task naturally splits into independent specialist domains (e.g., DevOps + Security + Database).
+- Agents need to collaborate but no single agent should be "in charge."
+- You want modular agent design where adding a new specialist doesn't change the others.
+- Each agent has a distinct tool set and expertise.
+
+## When NOT to use
+
+- One agent can handle the task alone (simpler is better).
+- Agents need strict coordination or sequencing (use Hierarchical or Plan-and-Execute).
+- The number of agents is large (>5) — coordination overhead grows. Use hierarchical instead.
+
+## Core flow
+
+```
+User task
+    |
+    v
+  [Task distribution] ──> split across agents
+    |
+    ├──> [Agent A: DevOps] ──> findings
+    ├──> [Agent B: Security] ──> findings
+    └──> [Agent C: Database] ──> findings
+                                    |
+                                    v
+                              [Aggregation]
+                                    |
+                                    v
+                              Combined report
+```
+
+### Variants
+
+- **Independent execution:** Each agent works on its piece independently, results merged at the end. No inter-agent communication.
+- **Round-robin discussion:** Agents take turns adding to a shared context. Each sees what prior agents said.
+- **Debate/critique:** Agents review each other's outputs and provide feedback. Converges through iteration.
+- **Handoff:** Agents pass work to each other when they encounter something outside their expertise.
+
+## Key components
+
+- **Crew/Team:** The container that holds the set of agents and defines how they interact (parallel, sequential, round-robin).
+- **Agent:** An LLM with a specialized system prompt and tool set. Each agent has a distinct role.
+- **Task:** A unit of work assigned to one or more agents. Has a description, expected output, and optionally a designated agent.
+- **Communication protocol:** How agents share information — shared state, message passing, or output chaining.
+- **Aggregator:** Merges individual agent outputs into a cohesive result.
+
+## Common pitfalls
+
+- **Role overlap:** Two agents covering similar ground produces redundant or contradictory output. Define clear boundaries.
+- **No aggregation strategy:** Individual agent outputs dumped together aren't useful. Design the merge step.
+- **Excessive communication:** Agents chatting with each other burns tokens and adds latency. Minimize inter-agent messages.
+- **Lowest common denominator:** The final output quality is limited by the weakest agent. Each specialist needs to be good at its job.
+- **Coordination failure:** Without a supervisor, no one resolves disagreements between agents. Have a tie-breaking mechanism.
+
+## Framework fit
+
+| Framework | Native support | Notes |
+|-----------|----------------|-------|
+| CrewAI | Purpose-built — `Crew`, `Agent`, `Task` abstractions | Best fit for flat multi-agent |
+| LangGraph | Multiple sub-graphs composed in a parent graph | More manual but more control |
+| Mastra | Multi-agent workflows with agent handoffs | TS-native option |
+| Pydantic AI | Multiple agents orchestrated manually | Works but no built-in multi-agent |
+| Vercel AI SDK | Manual orchestration | No multi-agent primitives |
+
+## Reference implementations
+
+- [recipes/ops-crew.md](../recipes/ops-crew.md) — DevOps/Security/Database ops crew with CrewAI (skeleton)