logly/mureo

v0.9.19 closes umbrella #161 — /learn knowledge consumption + external MCP federation. Because v0.9.18 was merged but never independently released, this release bundles both parts: the local /learn read-side gap closure (was 0.9.18) and the new external advisor MCP federation (0.9.19).

PyPI users upgrading from v0.9.17 will see one release on PyPI that delivers both new tools.

Added — mureo_consult_advisor MCP tool: retrieval-pattern federation with external advisor servers (0.9.19)

v0.9.18 closed the local /learn read-side gap. This release extends the read surface to external advisor MCP servers through a retrieval-pattern federation: mureo sends a query text to each configured server, the server performs vector search over its own corpus (embedder + vector store, no LLM), and returns the top-k matching fragments with similarity scores. The operator-side Claude reasons over the aggregated fragments. The earlier text-return federation proposal (#163) was abandoned because returning the full corpus per call leaked the advisor's know-how; this design only ever surfaces the relevant snippets.

A new MCP tool, mureo_consult_advisor, takes a question (required) and an optional campaign_id. mureo enriches the question with the local campaign's metrics, recent action-log entries, and STRATEGY.md excerpt via the new mureo.learning.context_builder so the advisor's vector search has rich context to match against — not just the raw question. The tool then fans out to every server declared in ~/.mureo/insight_sources.json, gathers the per-source fragments, and renders them as a single Markdown payload with per-advisor sections and similarity scores.

Config schema (~/.mureo/insight_sources.json):

{
  "sources": [
    {
      "name": "acme",
      "transport": "stdio",
      "command": "acme-advisor-mcp",
      "tool": "vector_search",
      "top_k": 5
    },
    {
      "name": "benchmarks",
      "transport": "http",
      "url": "https://benchmarks.example/mcp",
      "tool": "vector_search",
      "top_k": 3
    }
  ]
}

Three transports are supported: stdio (subprocess; mcp SDK's stdio_client), sse (sse_client), and http (streamablehttp_client). Per-source isolation rules: a single misbehaving source NEVER blocks the diagnostic flow. Per-source timeout (default 10s) caps each call via asyncio.wait_for; failures yield an empty tuple for that source and the others continue. Sources fan out via asyncio.gather so total wall-time is bounded by the slowest, not the sum. asyncio.CancelledError is re-raised so structured concurrency cleanup still works.

Untrusted-payload defence: 1 MiB raw-JSON cap per response, 50 fragments cap, 4 KiB per-fragment text truncation, top_k <= 50, timeout_sec <= 120s, boolean-as-similarity rejected, env / headers preserve the absent-vs-explicit-empty distinction ("env": {} seals the subprocess, NOT parent-env inheritance), fragment text whitespace-flattened and ## / --- defanged at render time.

Server authors only need to expose a single vector-search tool that takes {query, top_k} and returns a JSON array of {text, similarity, ...} fragments. The advisor side does NOT need an LLM — just an embedder (e.g. sentence-transformers) and a vector store (ChromaDB, pgvector, Pinecone, Vespa). docs/insight-federation.md and the Japanese mirror docs/insight-federation.ja.md ship a 30-line example plus a comprehensive server-side security and abuse-control spec for advisor authors (authentication, per-key rate limiting, per-key fragment quota, query logging / anomaly detection, response shaping, corpus partitioning).

The existing mureo_learning_insights_get tool from v0.9.18 is unchanged and continues to surface only the operator's local /learn history.

Closes #166 (part 2 of 2 of umbrella #161). Supersedes #163.

Added — mureo_learning_insights_get MCP tool closes the /learn read-side gap (0.9.18)

/learn (in v0.8.0) has been writing insights to ~/.claude/skills/_mureo-pro-diagnosis/SKILL.md via the FilesystemKnowledgeStore, but the diagnostic workflows that the docstring claimed would consume those insights (/daily-check, /rescue, /budget-rebalance, etc.) had no read path. The saved Markdown sat on disk, available to Claude Code's general skill discovery but never explicitly consulted by the workflows. This release closes that read-side gap.

A new MCP tool, mureo_learning_insights_get, returns the operator-tier knowledge base verbatim by calling KnowledgeStore.read_operator_knowledge(). The tool takes no arguments — its job is to surface every saved insight so the agent treats them as authoritative practitioner know-how. An empty knowledge base (no file, or only the YAML-frontmatter scaffold) returns a guidance string rather than a blank payload, so the agent neither quotes an empty section into its analysis nor mistakes the scaffold header for content.

Seven diagnostic skills (daily-check, rescue, budget-rebalance, creative-refresh, goal-review, competitive-scan, search-term-cleanup) gain a "Before you start" paragraph at the top of their Steps section instructing the agent to call mureo_learning_insights_get first and treat the returned Markdown as authoritative context.

The tool defers entirely to the runtime context's KnowledgeStore, so an alternate backend registered via the mureo.runtime_context_factory entry-point group works transparently. This is the foundation the v0.9.19 federation builds on.

Closes #162 (part 1 of 2 of umbrella #161).