/by-knowledge

id: "skill_1074c69b6e034130bea9cd82aa22cfe2"
name: "by-knowledge"
display-name: "BY Knowledge Graph"
short-description: "Persistent structured memory across campaigns — record and recall targets, scaffolds, designs, screening results, and failure patterns. Use when starting a new campaign, recording outcomes after screening, diagnosing repeated failures, or recommending parameters based on prior art."
category: "persistence"
keywords: "knowledge graph, persistent memory, campaign history, scaffold rankings, failure patterns, cross-campaign learning, NDJSON, entity, relationship"
version: "1.0"
last-updated: "2026-05-20"
mcp_tools: ["mcp__by-knowledge__knowledge_store_campaign", "mcp__by-knowledge__knowledge_query_similar", "mcp__by-knowledge__knowledge_scaffold_rankings", "mcp__by-knowledge__knowledge_store_failure", "mcp__by-knowledge__knowledge_get_recommendations", "mcp__by-knowledge__knowledge_consolidate"]

BY Knowledge Graph

Persistent structured memory that turns isolated campaigns into a learning system. Each campaign writes outcomes, top designs, and failure modes into a JSON-backed graph so the next campaign benefits from prior art without re-running compute.

The store is intentionally minimal: append-only JSON files, no server process, no embeddings — keyword overlap is enough for the scale we operate at (hundreds to low thousands of campaigns). Six MCP tools wrap the storage layer so every agent in the BY suite reads and writes through the same contract.

---

When to Use This Skill

Use this skill when:

• ✅ Starting a new campaign — query prior campaigns and scaffold rankings before committing compute
• ✅ Finishing a campaign — record outcomes, top designs, and any failure patterns
• ✅ Diagnosing low pass rates — search for matching failure patterns from prior campaigns
• ✅ Pre-flight parameter selection — call `knowledge_get_recommendations` to seed defaults
• ✅ Periodic maintenance — run `knowledge_consolidate` after every 20-30 campaigns
• ✅ Cross-target analysis — compare hit rates of a scaffold across target classes

Don't use this skill for:

• ❌ Storing raw design files — those live in the campaign directory (FASTA, PDB, CIF)
• ❌ Storing every design from a campaign — record the top 10-20 only (selectivity matters)
• ❌ Replacing the research dossier — `by-research` writes `research/research.md`; this skill stores the summary
• ❌ Per-job telemetry or compute logs — use `by-campaign-manager` checkpoints instead
• ❌ Free-form notes that have no entity to attach to — write them to `.claude/memory/` directly

The graph is a long-lived asset. Be selective on writes; aggressive on queries.

---

Quick Start

# 1. Query prior art at campaign start
result = mcp__by_knowledge__knowledge_query_similar(
    target_description="TNF-alpha cytokine homotrimer autoimmune",
    modality="VHH",
    top_k=5,
)

# 2. Record outcomes at campaign end (top 10-20 designs, not all of them)
mcp__by_knowledge__knowledge_store_campaign(
    target="TNF-alpha",
    modality="VHH",
    parameters={"scaffold": "caplacizumab", "seeds": 4, "temperature": 0.7},
    outcomes={
        "hit_rate": 0.23,
        "best_ipsae": 0.78,
        "best_iptm": 0.85,
        "screening_pass_rate": 0.18,
    },
    notes="Iter-2 hotspot refinement converged on Y56/R113",
    designs=[
        {"design_id": "tnf_001", "scaffold": "caplacizumab", "ipsae": 0.78, "iptm": 0.85, "status": "PASS"},
        # ... up to ~20 top designs
    ],
)

Expected runtime: <100 ms per call (no network, no DB engine). Storage is local JSON; first call seeds `~/.by/knowledge/` if missing.

---

Installation

| Software | Version | License | Commercial Use | Installation | |----------|---------|---------|----------------|--------------| | Python | >= 3.11 | PSF | ✅ Permitted | Pre-installed in BY env | | `mcp` SDK | >= 1.0.0 | MIT | ✅ Permitted | `pip install mcp` | | `jsonschema` (optional, for migration) | >= 4.0 | MIT | ✅ Permitted | `pip install jsonschema` |

No database, no server process, no compute. The MCP server starts cold in under one second. License Compliance: All packages permit commercial use.

**Storage directory resolution** (priority order): 1. `KNOWLEDGE_DIR` environment variable (explicit override) 2. `$BY_PROJECT_ROOT/.by/knowledge/` (project-local) 3. `~/.by/knowledge/` (home directory fallback)

---

Inputs

**Required for `knowledge_store_campaign`:**

• `target` (str): Target name. Use lowercase-hyphenated form for stability (e.g. `"tnf-alpha"`, `"pd-l1"`).
• `modality` (str): One of `"antibody"`, `"nanobody"`, `"VHH"`, `"scFv"`, `"de_novo"`, `"binder"`.
• `parameters` (dict): Scaffold, seeds, temperature, MSA mode, etc.
• `outcomes` (dict): Must include `hit_rate`, `best_ipsae`, `best_iptm`, `screening_pass_rate` where available.

**Optional:**

• `notes` (str): Free-text, indexed for keyword search.
• `designs` (list[dict]): Top 10-20 designs with `design_id`, `scaffold`, `ipsae`, `iptm`, `status` (`PASS`/`FAIL`).

**Required for `knowledge_store_failure`:**

• `campaign_id` (str): Stable identifier (use the campaign directory name).
• `description` (str): What broke.
• `root_cause` (str): Underlying cause from post-mortem.
• `target` (str): Target the campaign was for.

See [references/graph-schema.md](references/graph-schema.md) for the full JSON Schema of every entity and relationship type.

---

Outputs

All write tools return a JSON envelope:

{
  "status": "stored",
  "id": "campaign_a1b2c3d4e5f6",
  "document": "Campaign targeting TNF-alpha using VHH modality. Scaffold: caplacizumab. Hit rate: 0.23. Best ipSAE: 0.78.",
  "metadata": { /* echoed back for confirmation */ }
}

All read tools return result lists with similarity scores:

{
  "results": [
    {
      "id": "campaign_a1b2c3d4e5f6",
      "similarity": 0.83,
      "document": "Campaign targeting TNF-alpha...",
      "metadata": { "target": "...", "outcomes": {...}, "parameters": {...} }