poirot

A Deep Research Agent Kernel with Long-Term Memory

📚 Documentation: English · 简体中文 · 日本語

ReAct Loop · Context Governance · 5-Layer Memory · Multi-Agent Orchestration · Skill Self-Evolution · Sandbox Isolation

Overview

Poirot is a deep research agent kernel built for those who care about how agents are architected. Rather than chasing a feature checklist, Poirot establishes a clean, decoupled, evaluable foundation — from the ReAct core loop to context engineering governance, from a five-layer long-term memory system to multi-agent orchestration with shared sandbox isolation, from sandbox path enforcement to a three-layer skill self-evolution system.

Every module is independently designed, independently tested, and independently verifiable. 2400+ tests guard every layer.

Core Modules

🧠 ReAct Research Kernel

A single LeaderAgent orchestrates the research loop. LangGraph handles outer flow orchestration (prepare → leader_agent → finalize), while 21 middleware cross-cut every lifecycle hook: before/after_agent, before/after_model, wrap_tool_call.

Breakthrough: Middleware are first-class citizens — memory recall, skill injection, sandbox lifecycle, consolidation, tool-call pairing, help requests, and context governance are all pluggable cross-cutting concerns, not embedded in the agent loop. The app → agents dependency is strictly one-directional.

📐 Context Engineering Governance

The DefaultStrategy dynamically externalizes historical messages based on a live token budget. Window size is resolved by penetrating through the FallbackChatModel to the active provider's real context window — no hardcoded thresholds. Dual strategies — compaction (summarization) and externalization (offloading) — prevent context overflow in long research sessions without losing critical information.

Breakthrough: The governance layer treats token budget as a first-class runtime concern. The fraction denominator is the real model window (resolved at call time), not a static config — making P5 circuit-breaker thresholds accurate across provider switches.

🧬 Five-Layer Long-Term Memory

Poirot implements a cognitive-science-inspired memory system across five layers, each independently testable:

Key Design: Memory injection is per-call HumanMessage (not system prompt), protecting the LLM's prompt cache prefix. recalled_memories in state stores only indices (id+score+strength), not full content. The MemoryConfig has 4 STARTUP_ONLY fields (use/storage_path/vector_store/graph_store) — the rest are runtime-swappable via set_memory_config().

🤝 Multi-Agent Orchestration

Poirot supports delegating sub-tasks to external coding agents and internal self-copies:

• Specialist Delegation — delegate_to_specialist(goal, success_criteria) routes to external CLIs (pi / codex / claude) via MCP SpecialistMcpServer (8 sandbox tools exposed). Each specialist runs as a separate process with its own LLM, but shares the same Docker sandbox via --sandbox-url passthrough.
• Subagent (Self-Copy) — delegate_to_subagent(goal) creates a Poirot self-copy with isolated context (no inherited message history) but shared thread sandbox. SandboxMiddleware.abefore_model restores ContextVar from state["sandbox"] — subagent reuses parent's sandbox_id without re-acquiring.
• L2 Evolution Layer — data-driven specialist self-evolution: MetricMonitor triggers when effective_rate < threshold, IVEFocuser diagnoses, LLMMutator varies, ScoreDeltaGate gates, GitRatchet rollbacks on degradation.
• L3 Eval Layer — three-layer evaluation: execution judgment (per-skill per-task LLM), task quality scoring (4-dimension weighted), response contract checking. RuntimeTracker feeds degradation signals back to L2.

Breakthrough: The "shared thread sandbox" (INV#3) is now actually implemented — subagent restores ContextVar from state, specialist connects to write to the same mount area, not ephemeral container-internal paths.

🛡️ Sandbox Isolation with Path Enforcement

Two providers: Local (host process, for development) and Docker (container isolation, for production).

Docker mode breakthroughs:

• DockerPathTranslator — translate_path passes through (container path = bind mount path), reverse_translate maps /mnt/poirot/user-data/<x> → <sandbox_root>/<sandbox_id>/<x> (Windows host path) — fixes the present_files artifact extraction chain (shutil.copy2 now gets a real Windows path, not a container path)
• DockerPathGuard — write path whitelist: write_file/str_replace paths must be under /mnt/poirot/user-data/, bash redirect targets (>{1,2}\s*(/[^\s;|&]*)) must be in mount area — forces agent writes to persist, not lost in container-internal /tmp on --rm
• Warm pool — pre-created containers reduce cold-start latency
• Idle auto-destroy — POIROT_SANDBOX_IDLE_TIMEOUT=600 (10min)
• Cross-process lock — concurrent Poirot instances don't conflict (3-function lock: open/lock/unlock)
• WSL2 executor — WslDockerExecutor translates D:\foo\bar → /mnt/d/foo/bar for Docker daemon in WSL2

🔌 MCP Tool Ecosystem

Three transports: stdio, sse, http. Core tools load at startup; non-core tools defer-load on demand. Tool equivalence fallback chains (e.g., web_search → MCP server → builtin ddg) ensure resilience. Tool metadata drives externalization thresholds. Configured via .poirot/mcp_servers.yaml.

🎯 Three-Layer Skill Architecture

Skills are research process knowledge bundles — prompt-level injections, not executable functions. "How to verify a source" is a skill. "Execute a web search" is a tool.

• Layer 1 (Base): SQLite storage with version DAG, quality-filtered LLM hybrid selection, injection middleware, and four-counter metrics (selections / applied / completions / fallbacks).
• Layer 2 (Evolution): IVEFocuser diagnosis, LLMMutator variation, ScoreDeltaGate gating, GitRatchet ratchet rollback. Skills auto-evolve when effective rate drops below threshold.
• Layer 3 (Eval): Three-layer evaluation — execution judgment, task quality scoring (4-dimension weighted), response contract checking. RuntimeTracker monitors applied-rate trends and feeds degradation signals back to Layer 2.

36 builtin skills across 5 categories (core / research / software-development / creative / productivity). Core skills auto-load; others discoverable via /skill search.

🎨 Dual UI

• TUI (default): Full-screen Textual app with welcome view + conversation view. Left scrollable log, bottom input box, status bar with live token usage. Wide screens show right-side session info panel.
• CLI (poirot cli): Traditional scrolling mode with prompt_toolkit + rich. Slash-command completion + bottom toolbar.

🔄 Multi-LLM Fallback

FallbackChatModel constructs a role-based routing chain (researcher / reporter). On transient API failures (rate limit, timeout, 5xx), it automatically degrades to the next provider. DeepSeek always sits at the chain tail as the ultimate fallback.

📊 Observability

RunJournal records structured events (skill.select, skill.apply, memory.encode, memory.consolidate, compaction, budget). Thread directories persist run artifacts. The /expand command unfolds the previous round's full Thought t