LangChain Principles → Mia-Code Roadmap

Based on analysis of /references/langchain/ documentation and mia-code's stated goals.

Current State Analysis

Mia-code currently implements a Handoffs pattern:

User Prompt
  ↓
Primary Agent (Gemini/Claude) → tools, code, analysis
  ↓  [handoff]
Unifier (Claude) → interprets essence
  ↓
🧠 Mia + 🌸 Miette output

Handoffs strengths (from LangChain docs):

• ⭐⭐⭐⭐⭐ Multi-hop (sequential processing)
• ⭐⭐⭐⭐⭐ Direct user interaction
• Efficient for repeat requests (context persists)

Current limitation: Sequential only, no parallelization.

Future Goals → Recommended Patterns

1. MCP Tool Integration

Source: references/langchain/python/mcp.md

MCP (Model Context Protocol) provides standardized tool discovery and execution. For mia-code:

Action items:

• Add MCP client to primary agent for dynamic tool discovery
• Expose mia-code capabilities as MCP server for other agents
• Use @langchain/mcp-adapters (TypeScript) for integration

// Example: MCP tool loading
import { loadMCPTools } from "@langchain/mcp-adapters";
const tools = await loadMCPTools({ servers: ["filesystem", "github"] });

2. Multi-Agent Coordination (Claude Code, Copilot CLI)

Source: references/langchain/python/multi-agents/

Recommended: Hybrid Subagents + Handoffs pattern

User Prompt
  ↓
Router/Main Agent → decides which agent(s)
  ├── Gemini (current primary) ──┐
  ├── Claude Code ───────────────┼──→ [parallel execution possible]
  └── Copilot CLI ───────────────┘
          ↓
    Unifier (existing handoff)
          ↓
    🧠🌸 output

Why Subagents for external tools:

• ⭐⭐⭐⭐⭐ Distributed development (each tool maintained separately)
• ⭐⭐⭐⭐⭐ Parallelization (can query multiple agents simultaneously)
• Context isolation (each agent gets only relevant context)

Implementation approach:

// Wrap external CLIs as subagent tools
const claudeCodeTool = tool(
  async (input) => execClaudeCode(input),
  { name: "claude_code", description: "Complex refactoring tasks" }
);

const copilotTool = tool(
  async (input) => execCopilot(input),
  { name: "copilot", description: "Code completion and suggestions" }
);

3. Streaming Unifier Output

Source: references/langchain/python/agents.md (streaming section)

Current unifier is buffered. To stream:

// Use streaming callbacks
const stream = await agent.stream(
  { messages: [new HumanMessage(prompt)] },
  { streamMode: "messages" }
);

for await (const chunk of stream) {
  process.stdout.write(chunk.content);
}

4. Narrative Arc Tracking (Long-term Memory)

Source: references/langchain/python/long-term-memory.md

Store unifier outputs for pattern recognition across sessions.

Options:

1. InMemoryStore (simplest) - good for dev
2. SQLite/Postgres - for persistence
3. Vector store - for semantic retrieval of past narratives

import { InMemoryStore } from "@langchain/langgraph";

const memoryStore = new InMemoryStore();

// Store narrative arc
await memoryStore.put(
  ["narratives", sessionId],
  { mia: miaOutput, miette: mietteOutput, timestamp: Date.now() }
);

// Retrieve for context engineering
const pastNarratives = await memoryStore.search(["narratives"]);

Priority Order (Recommended)

1. MCP Tool Integration - Foundational, enables everything else
2. Multi-Agent Coordination - Subagents pattern for external CLI integration
3. Long-term Memory - Narrative arc tracking with persistent store
4. Streaming Unifier - UX improvement, can be done incrementally

Key LangChain Concepts to Leverage

References

• Multi-agent overview: references/langchain/python/multi-agents/overview.md
• MCP integration: references/langchain/python/mcp.md
• Long-term memory: references/langchain/python/long-term-memory.md
• Context engineering: references/langchain/python/context-engineering.md