Fix COQ skill branch

MemMachine · Tianyang-Zhang · Mar 3, 2026 · Mar 6, 2026 · Mar 8, 2026 · Mar 8, 2026
commit b9af61a812252cfc6ad91001c27616a798fe9cb7
diff --git a/packages/server/server_tests/memmachine_server/retrieval_agent/test_agent_markdown_specs.py b/packages/server/server_tests/memmachine_server/retrieval_agent/test_agent_markdown_specs.py
@@ -35,11 +35,22 @@ def test_load_markdown_top_level_spec_file() -> None:
     assert "spawn_sub_agent" not in spec.policy_markdown
     assert "return_final" not in spec.policy_markdown
     assert "answer directly in plain text" in spec.policy_markdown
-    assert "Mandatory COQ procedure for dependency chains" in spec.policy_markdown
+    assert "Enter the attached COQ branch only for multi-hop questions" in (
+        spec.policy_markdown
+    )
+    assert "prefer the attached `coq.md` branch for multi-hop questions" in (
+        spec.policy_markdown
+    )
+    assert "do not enter the COQ branch for single-hop" in spec.policy_markdown
+    assert "let `coq.md` determine the next hop" in spec.policy_markdown
     assert "[person] spouse died when" in spec.policy_markdown
     assert "[person] born where" in spec.policy_markdown
-    assert "generic templates, not memorized benchmark examples" in spec.policy_markdown
-    assert "maternal grandfather" in spec.policy_markdown
+    assert "The attached `coq.md` branch is available" in spec.policy_markdown
+    assert "Mandatory COQ procedure for dependency chains" not in spec.policy_markdown
+    assert "generic templates, not memorized benchmark examples" not in (
+        spec.policy_markdown
+    )
+    assert "maternal grandfather" not in spec.policy_markdown
     assert "disambiguating context" in spec.policy_markdown
 
 
@@ -54,6 +65,8 @@ def test_load_markdown_coq_sub_agent_spec_file() -> None:
     assert "## Examples" in spec.policy_markdown
     assert "## Failure Modes" in spec.policy_markdown
     assert "plain text" in spec.policy_markdown
+    assert "classified the question as" in spec.policy_markdown
+    assert "not for single-hop direct lookups" in spec.policy_markdown
     assert "return_sub_agent_result" not in spec.policy_markdown
 
 

diff --git a/...ges/server/src/memmachine_server/retrieval_agent/agents/specs/sub_agents/coq.md b/...ges/server/src/memmachine_server/retrieval_agent/agents/specs/sub_agents/coq.md
@@ -2,7 +2,7 @@
 name: coq
 version: v1
 kind: sub-agent
-description: "Sequential chain-of-query guidance for single-session retrieval."
+description: "Sequential chain-of-query branch guidance for multi-hop retrieval."
 route_name: coq
 timeout_seconds: 120
 max_return_len: 10000
@@ -23,22 +23,28 @@ required_sections:
 
 ## Intent
 
-Use sequential chain-of-query reasoning inside the current LLM session.
+Use sequential chain-of-query reasoning inside the current LLM session, but
+only after the top-level retrieve-agent has classified the question as
+multi-hop.
 
 Your job:
 - break a multi-hop question into dependency-ordered searches,
 - resolve the earliest blocking fact first,
 - keep searching with `memmachine_search`,
 - answer directly in plain text once the chain is complete.
 
-This file is guidance for the same session. It is not a callable sub-session.
+This file is guidance for the same session. It is not a callable sub-session,
+and it is not for single-hop direct lookups.
 
 ## Rules
 
 Follow this step-by-step procedure exactly.
 
 ### Step 0: Establish internal state
 
+Enter this branch only when at least one intermediate hop still needs to be
+resolved before the final asked attribute can be answered.
+
 Maintain:
 - `original_query`,
 - `used_queries`,
@@ -55,6 +61,9 @@ For the current state, identify:
 
 Always prioritize the earliest blocking hop.
 
+If the question no longer has a blocking intermediate hop, leave this branch
+and let the top-level direct-lookup flow finish the answer.
+
 ### Step 2: Generate exactly one next search query
 
 Produce one concrete follow-up query for the earliest missing fact.

diff --git a/.../src/memmachine_server/retrieval_agent/agents/specs/top_level/retrieve_agent.md b/.../src/memmachine_server/retrieval_agent/agents/specs/top_level/retrieve_agent.md
@@ -33,6 +33,7 @@ Working assumptions:
 - Treat MemMachine only as a searchable memory store.
 - `memmachine_search` is the only external tool.
 - Any decomposition or hop-by-hop reasoning happens inside this same session.
+- The attached `coq.md` branch is available, but only for multi-hop questions.
 
 ## Rules
 
@@ -53,43 +54,29 @@ Do not reset state between searches.
 
 Before the first search:
 - prefer direct lookup for single-subject questions,
-- prefer the COQ dependency-chain procedure below for multi-hop questions,
+- prefer the attached `coq.md` branch for multi-hop questions,
 - preserve entities, time windows, and location constraints exactly.
 
 This routing decision stays internal. Do not call a routing tool.
 
-### Step 1A: Mandatory COQ procedure for dependency chains
-
-For any relation chain or dependency chain, execute this exact internal loop:
-1. identify the final asked attribute,
-2. list the dependency hops needed to reach it,
-3. resolve the earliest missing hop first,
-4. only ask for the terminal attribute after the intermediate entity is known.
-
-Mandatory chain rules:
-- resolve entity-valued relations before terminal attributes:
-  - good: `[person] husband`
-  - then: `When did [husband name] die?`
-- resolve parent identities before parent attributes:
-  - good: `[person] father`
-  - then: `When did [father name] die?`
-- resolve spouse identity before spouse attributes:
-  - good: `[person] wife`
-  - then: `What was the cause of death of [wife name]?`
-- resolve composite kinship relations step-by-step instead of querying them whole:
-  - maternal grandfather: `[person] mother` then `[mother name] father`
-  - paternal grandmother: `[person] father` then `[father name] mother`
-  - father-in-law: `[person] spouse` then `[spouse name] father`
-- resolve creator or performer identities before biographical attributes:
-  - `director of [film]` then `Where was [director name] born?`
-  - `performer of [song]` then `Where was [performer name] born?`
-- for comparisons, resolve both branches separately before deciding:
-  - `director of [film A]` + `director of [film B]`
-  - then compare the requested dates/places/release years only after both sides are identified
-- treat these as generic templates, not memorized benchmark examples.
-
-This COQ procedure is duplicated here intentionally so it still applies even if
-an auxiliary `coq.md` attachment is ignored or weakly attended.
+### Step 1A: Enter the attached COQ branch only for multi-hop questions
+
+If the query is multi-hop:
+1. switch to the attached `coq.md` branch guidance,
+2. follow that dependency-ordered procedure exactly,
+3. keep all searches in this same session using only `memmachine_search`,
+4. stay in that branch until the final asked attribute is supported or the
+   remaining gap is still unsupported after reasonable targeted search.
+
+COQ branch rules:
+- invoke the branch only when the answer depends on unresolved intermediate
+  hops, a comparison that requires resolving both sides, or a compositional
+  relation,
+- do not enter the COQ branch for single-hop, single-subject, or direct
+  attribute lookup questions,
+- once inside the COQ branch, let `coq.md` determine the next hop instead of
+  improvising a speculative terminal query,
+- keep the routing decision internal. Do not mention `coq.md` to the user.
 
 ### Step 2: Search iteratively with `memmachine_search`
 
@@ -127,8 +114,8 @@ After each search:
 2. reassess whether the final asked attribute is now supported,
 3. continue searching only if a concrete missing link remains.
 
-If the query is multi-hop, keep following the Step 1A COQ procedure to choose
-the next hop, but keep using only `memmachine_search`.
+If the query is multi-hop, keep following the attached `coq.md` branch from
+Step 1A to choose the next hop, but keep using only `memmachine_search`.
 
 ### Step 4: Finalize with direct assistant text