Skip to content
Back to search

poirot

Poirot is a deep research agent kernel built for those who care about how agents are architected.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hezaohezao--poirot/badge.svg)](/listings/hezaohezao--poirot)

HTML

<a href="/listings/hezaohezao--poirot"><img src="/api/listings/hezaohezao--poirot/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 1. Clone
git clone <repo-url> && cd Poirot

# 2. Create environment (Python 3.12+)
python -m venv .venv
.venv\Scripts\activate         # Windows
# source .venv/bin/activate    # Linux / macOS

# 3. Install
pip install -e ".[dev]"

# 4. Configure
cp .env.example .env
# Edit .env — fill in at least: DEEPSEEK_API_KEY=sk-xxx

# 5. Launch (TUI by default)
poirot

<sub>Type a question to start researching. Type `/` for command completion, `/help` for all commands.</sub>

Enable Advanced Features

# Long-term memory (L4 recall + L5 auto-consolidation)
POIROT_MEMORY_USE=default
POIROT_MEMORY_PHASE2_ENABLED=true
POIROT_MEMORY_PHASE2_TURNS=10

# Skill system (L1 base + L2 evolution + L3 eval)
POIROT_SKILL_ENABLED=true
POIROT_SKILL_EVOLVE_ENABLED=true
POIROT_SKILL_EVAL_ENABLED=true
POIROT_SKILL_MAX_INJECT=15

# Multi-Agent (specialist delegation + L2/L3)
POIROT_MULTIAGENT_ENABLED=true
POIROT_MULTIAGENT_L2_ENABLED=true
POIROT_MULTIAGENT_L3_ENABLED=true

# Docker sandbox (container isolation)
POIROT_SANDBOX_USE=poirot.backend.agents.sandbox.docker.docker_sandbox_provider:DockerSandboxProvider
POIROT_SANDBOX_EXECUTOR=wsl              # Windows + WSL2 Docker

# MCP tools
POIROT_MCP_ENABLED=true

> **👉 For full configuration, commands, and troubleshooting — see the [Usage Guide](USAGE.md).**

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 239 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img alt="Poirot README Hero" width="960" src="resource/assets/poirot-readme-hero.png">
  3. ### A Deep Research Agent Kernel with Long-Term Memory
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-7c6ff0?style=for-the-badge)](LICENSE)
  5. [![Python 3.12+](https://img.shields.io/badge/Python-3.12+-45c4b8?style=for-the-badge)](https://www.python.org/)
  6. [![LangGraph](https://img.shields.io/badge/LangGraph-1.x-5aa9f5?style=for-the-badge)](https://github.com/langchain-ai/langgraph)
  7. [![DeepSeek](https://img.shields.io/badge/LLM-DeepSeek-00BFFF?style=for-the-badge)](https://www.deepseek.com/)
  8. **📚 Documentation:** [English](USAGE.md) · [简体中文](resource/USAGE.zh-CN.md) · [日本語](resource/USAGE.ja.md)
  9. <sub>ReAct Loop · Context Governance · 5-Layer Memory · Multi-Agent Orchestration · Skill Self-Evolution · Sandbox Isolation</sub>
  10. </div>
  11. ---
  12. <picture>
  13. <source media="(prefers-color-scheme: dark)" srcset="resource/assets/poirot-logo.png">
  14. <img alt="Poirot" width="720" src="resource/assets/poirot-logo.png">
  15. </picture>
  16. ## Overview
  17. 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.
  18. Every module is independently designed, independently tested, and independently verifiable. **2400+ tests** guard every layer.
  19. ---
  20. ## Core Modules
  21. ### 🧠 ReAct Research Kernel
  22. 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`.
  23. **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.
  24. ### 📐 Context Engineering Governance
  25. 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.
  26. **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.
  27. ### 🧬 Five-Layer Long-Term Memory
  28. Poirot implements a cognitive-science-inspired memory system across five layers, each independently testable:
  29. | Layer | Role | Key Breakthrough |
  30. |-------|------|-----------------|
  31. | **L1** | Schema + Protocol | `MemoryTrace` frozen dataclass (15 fields) + `MemoryType` enum (episodic/semantic/procedural) + 5 atomic operations (Encode/Retrieve/Associate/Consolidate/Reconsolidate) — **tools have no LLM**, pure data operations |
  32. | **L2** | Default Strategies | Ebbinghaus decay formula (`strength = base×(1-decay)^hours + log(1+access)×0.1 + importance×0.05`) + composite forget (TTL + strength threshold) + 6 hard-wired decisions (A1-F2) — **lazy decay**, strength computed at retrieve time, no background tasks |
  33. | **L3** | Store + Retriever | `MarkdownFileStore` (single `traces.md` truth source + `<!-- trace: {id} -->` separators + YAML frontmatter) + `HybridRetriever` (pure BM25, no vector/graph dependency) — **retrieve reinforcement write-back** (1A:命中后 store.update 强化 strength) + **forgotten filtering** (3B: metadata.forgotten=True excluded) + **incremental index** (5B: store decorator triggers retriever.on_trace_*) |
  34. | **L4** | Middleware + Bootstrap | `MemoryMiddleware.abefore_model` — per-call `HumanMessage` injection (protects prompt caching, `hide_from_ui=True`) + `set_turn_id` ContextVar (traceability C: actor = turn:N) + bootstrap lifecycle (lazy-load double-check lock + `set_memory_config` global singleton sync) |
  35. | **L5** | Auto-Consolidation | `MemoryConsolidationMiddleware.aafter_model` — **non-blocking** submit every N turns + `MemoryWorker` (daemon thread + `threading.Queue` + LLM construction injection) — LLM extracts episodic memories → `manager.encode` → candidate ≥ N → LLM generates merged content → `manager.consolidate` (max=10, E1) — **errors: log + skip**, never blocks main loop |
  36. **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()`.
  37. ### 🤝 Multi-Agent Orchestration
  38. Poirot supports delegating sub-tasks to external coding agents and internal self-copies:
  39. - **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.
  40. - **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.
  41. - **L2 Evolution Layer** — data-driven specialist self-evolution: `MetricMonitor` triggers when `effective_rate < threshold`, `IVEFocuser` diagnoses, `LLMMutator` varies, `ScoreDeltaGate` gates, `GitRatchet` rollbacks on degradation.
  42. - **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.
  43. **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.
  44. ### 🛡️ Sandbox Isolation with Path Enforcement
  45. Two providers: **Local** (host process, for development) and **Docker** (container isolation, for production).
  46. **Docker mode breakthroughs:**
  47. - **`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)
  48. - **`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`
  49. - **Warm pool** — pre-created containers reduce cold-start latency
  50. - **Idle auto-destroy** — `POIROT_SANDBOX_IDLE_TIMEOUT=600` (10min)
  51. - **Cross-process lock** — concurrent Poirot instances don't conflict (3-function lock: open/lock/unlock)
  52. - **WSL2 executor** — `WslDockerExecutor` translates `D:\foo\bar` → `/mnt/d/foo/bar` for Docker daemon in WSL2
  53. ### 🔌 MCP Tool Ecosystem
  54. 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`.
  55. ### 🎯 Three-Layer Skill Architecture
  56. 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.
  57. - **Layer 1 (Base):** SQLite storage with version DAG, quality-filtered LLM hybrid selection, injection middleware, and four-counter metrics (selections / applied / completions / fallbacks).
  58. - **Layer 2 (Evolution):** `IVEFocuser` diagnosis, `LLMMutator` variation, `ScoreDeltaGate` gating, `GitRatchet` ratchet rollback. Skills auto-evolve when effective rate drops below threshold.
  59. - **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.
  60. 36 builtin skills across 5 categories (core / research / software-development / creative / productivity). Core skills auto-load; others discoverable via `/skill search`.
  61. ### 🎨 Dual UI
  62. - **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.
  63. - **CLI** (`poirot cli`): Traditional scrolling mode with `prompt_toolkit` + `rich`. Slash-command completion + bottom toolbar.
  64. ### 🔄 Multi-LLM Fallback
  65. `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.
  66. ### 📊 Observability
  67. `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 text and tool results.
  68. ---
  69. ## Architecture
  70. <div align="center">
  71. <img src="resource/assets/poirot-architecture-diagram.png" alt="Poirot Architecture" width="880">
  72. </div>
  73. <sub>Outer flow: `prepare → before_agent → LeaderAgent (ReAct loop) → after_agent → finalize`. 21 middleware cross-cut every hook. Memory recall (L4) happens in `before_model`, consolidation (L5) in `after_model`. Skill injection (L1+L2+L3) in `before_model`. Tool calls route through Sandbox / MCP / Builtin via `wrap_tool_call`. Multi-agent delegation via `delegate_to_specialist` / `delegate_to_subagent`.</sub>
  74. ---
  75. ## Quick Start
  76. ```bash
  77. # 1. Clone
  78. git clone <repo-url> && cd Poirot
  79. # 2. Create environment (Python 3.12+)
  80. python -m venv .venv
  81. .venv\Scripts\activate # Windows
  82. # source .venv/bin/activate # Linux / macOS
  83. # 3. Install
  84. pip install -e ".[dev]"
  85. # 4. Configure
  86. cp .env.example .env
  87. # Edit .env — fill in at least: DEEPSEEK_API_KEY=sk-xxx
  88. # 5. Launch (TUI by default)
  89. poirot
  90. ```
  91. <sub>Type a question to start researching. Type `/` for command completion, `/help` for all commands.</sub>
  92. ### Enable Advanced Features
  93. ```env
  94. # Long-term memory (L4 recall + L5 auto-consolidation)
  95. POIROT_MEMORY_USE=default
  96. POIROT_MEMORY_PHASE2_ENABLED=true
  97. POIROT_MEMORY_PHASE2_TURNS=10
  98. # Skill system (L1 base + L2 evolution + L3 eval)
  99. POIROT_SKILL_ENABLED=true
  100. POIROT_SKILL_EVOLVE_ENABLED=true
  101. POIROT_SKILL_EVAL_ENABLED=true
  102. POIROT_SKILL_MAX_INJECT=15
  103. # Multi-Agent (specialist delegation + L2/L3)
  104. POIROT_MULTIAGENT_ENABLED=true
  105. POIROT_MULTIAGENT_L2_ENABLED=true
  106. POIROT_MULTIAGENT_L3_ENABLED=true
  107. # Docker sandbox (container isolation)
  108. POIROT_SANDBOX_USE=poirot.backend.agents.sandbox.docker.docker_sandbox_provider:DockerSandboxProvider
  109. POIROT_SANDBOX_EXECUTOR=wsl # Windows + WSL2 Docker
  110. # MCP tools
  111. POIROT_MCP_ENABLED=true
  112. ```
  113. > **👉 For full configuration, commands, and troubleshooting — see the [Usage Guide](USAGE.md).**
  114. ---
  115. ## Screenshots
  116. <div align="center">
  117. <img src="resource/assets/screenshot-tui-conversation.png" alt="Poirot TUI Conversation" width="880">
  118. <sub>TUI Conversation View — dual-panel layout with live context governance, sandbox status, and memory recall</sub>
  119. </div>
  120. ---
  121. ## Tech Stack
  122. <div align="center">
  123. ![Python](https://img.shields.io/badge/Python-3776AB?style=flat-square&logo=python&logoColor=white)
  124. ![LangGraph](https://img.shields.io/badge/LangGraph-1.x-00BFFF?style=flat-square)
  125. ![LangChain](https://img.shields.io/badge/LangChain-1.x-1c3c3c?style=flat-square)
  126. ![Rich](https://img.shields.io/badge/Rich-13+-red?style=flat-square)
  127. ![Textual](https://img.shields.io/badge/Textual-0.40+-7c6ff0?style=flat-square)
  128. ![prompt_toolkit](https://img.shields.io/badge/prompt__toolkit-3+-45c4b8?style=flat-square)
  129. ![SQLite](https://img.shields.io/badge/SQLite-skill_store-003B57?style=flat-square&logo=sqlite&logoColor=white)
  130. ![Docker](https://img.shields.io/badge/Docker-Sandbox-2496ED?style=flat-square&logo=docker&logoColor=white)
  131. ![PyYAML](https://img.shields.io/badge/PyYAML-config-6c4097?style=flat-square)
  132. </div>
  133. ---
  134. ## Acknowledgments
  135. Poirot stands on the shoulders of giants. The architecture draws inspiration from several outstanding open-source projects and research frameworks:
  136. **Agent Architecture** — The middleware-first design and ReAct loop orchestration patterns are inspired by modern-based agent frameworks. The separation of concerns — where memory, skills, sandbox, and tool routing are pluggable cross-cutting middleware rather than embedded agent logic — builds upon ideas from conversational agent platforms that prioritize decoupled, testable architectures.
  137. **Memory System** — The five-layer memory architecture (schema → strategies → store → middleware → auto-consolidation) is informed by cognitive science models of episodic, semantic, and procedural memory. The Ebbinghaus decay formula, lazy strength computation, and Markdown-as-truth-source patterns draw from long-term memory research in AI agent design. The "tools have no LLM" principle — where atomic operations are pure data transformations and LLM orchestration lives in the middleware layer — is inspired by memory framework designs that separate engine from orchestration.
  138. **Multi-Agent Orchestration** — The specialist delegation model (where Poirot delegates coding tasks to external CLI agents via MCP) and the shared-thread-sandbox concept build upon multi-agent collaboration patterns from coding agent ecosystems. The idea that a lead agent can orchestrate specialized sub-agents — each with their own LLM and toolset — while sharing a unified sandbox for artifact continuity, is informed by production multi-agent system designs.
  139. **Sandbox Isolation** — The three-component sandbox model (Runtime + PathTranslator + SecurityGuard) and the warm-pool lifecycle management are inspired by sandbox isolation patterns from deep research agent platforms. The Docker path translation and mount-area enforcement address real-world challenges of cross-platform (Windows + WSL2 + Docker) file persistence.
  140. **Skill Self-Evolution** — The three-layer skill architecture (base storage → LLM-driven evolution → multi-dimensional evaluation) with ratchet rollback and quality gating builds upon self-improving agent research. The concept of skills as "process knowledge bundles" (prompt-level injections, not executable functions) draws from prompt engineering and skill management frameworks.
  141. We gratefully acknowledge the developers and researchers of these projects whose work — whether through direct code patterns, architectural ideas, or research papers — made Poirot possible.
  142. ---
  143. ## License
  144. [MIT](LICENSE) © Poirot Authors
  145. ---
  146. <div align="center">
  147. <sub>Built for those who care about how agents are built.</sub><br>
  148. <sub>If this project helps you, a ⭐ is appreciated.</sub>
  149. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.